ALTER SERVICE-Anweisung [HTTP-Webdienst]

ALTER SERVICE service-name
[ TYPE { 'RAW' | 'HTML' | 'JSON' | 'XML' } ]
[ URL [ PATH ] { ON | OFF | ELEMENTS } ]
[ common-attributes ]
[ AS { statement | NULL } ]

common-attributes :
[ AUTHORIZATION { ON | OFF } ]
[ ENABLE | DISABLE ]
[ METHODS 'method,...' ]
[ SECURE { ON | OFF } ]
[ USER { user-name | NULL } ]

method :
DEFAULT
| POST
| GET
| HEAD
| PUT
| DELETE
| NONE
| *

service-name Webdienstnamen können aus einer beliebigen Sequenz von alphanumerischen Zeichen bestehen sowie die Zeichen Schrägstrich (/), Bindestrich (-), Unterstrich (_), Punkt (.), Ausrufezeichen (!), Tilde (~), Sternchen (*), Apostroph ('), öffnende Klammer (() oder schließende Klammer ()) enthalten. Allerdings darf der Dienstname nicht mit einem Schrägstrich (/) beginnen oder enden oder zwei oder mehr aufeinander folgende Schrägstriche (z.B. //) enthalten.
Sie können Ihren Dienst root nennen, aber dieser Name hat eine spezielle Funktion.
TYPE-Klausel Gibt den Typ des Dienstes an, wobei für jeden Dienst ein bestimmtes Antwortformat definiert wird. Der Typ muss einer der aufgelisteten Typen sein. Es gibt keine Standardeinstellung.
- 'RAW' Die Ergebnismenge wird ohne weitere Formatierung an den Client gesendet. Die Nutzung dieses Dienstes erfordert, dass alle Inhalts-Markups explizit zur Verfügung gestellt werden. Komplexe dynamische Inhalte, die aktuellen Inhalt mit Markup, JavaScript und Grafiken enthalten, können bei Bedarf generiert werden. Der Medientyp kann durch Einstellen des Antwort-Headers "Content-Type" unter Verwendung der Prozedur sa_set_http_header angegeben werden. Die Einstellung 'text/html' für den Content-Type-Header wird empfohlen, wenn Sie HTML-Markup generieren, damit alle Browser die Markup als HTML und nicht "text/plain" anzeigen.
- 'HTML' Die Ergebnismenge wird als HTML-Darstellung einer Tabelle oder einer Ansicht zurückgegeben.
- 'JSON' Die Ergebnismenge wird in JavaScript Object Notation (JSON) zurückgegeben. Ein JSON-Dienst verarbeitet nicht automatisch eine JSON-Eingabe. Er stellt lediglich Daten (in der Antwort) im JSON-Format bereit. JSON akzeptiert POST/PUT-Methoden, wobei application/x-www-form-urlencoded unterstützt wird. Wenn für eine POST/PUT METHODE Content-Type: application/json angegeben ist, kann die Anwendung http_variable('body') zum Abrufen des JSON-(Anforderung)-Inhalts verwenden. SQL Anywhere führt nicht automatisch eine syntaktische Analyse der JSON-Eingabe durch. Die Anwendung muss sie syntaktisch analysieren. Weitere Hinweise zu JSON finden Sie unter http://www.json.org
- 'XML' Die Ergebnismenge wird als XML zurückgegeben. Wenn die Ergebnismenge bereits XML ist, wird keine weitere Formatierung angewendet. Andernfalls wird sie automatisch als XML formatiert. Als alternativer Ansatz könnte ein RAW-Dienst unter Verwendung der FOR XML RAW-Klausel eine Auswahl zurückgeben, nachdem Sie mit der Prozedur sa_set_http_header einen gültigen Content-Type wie zum Beispiel 'text/xml' festgelegt haben.

URL-Klausel Bestimmt, ob URL-Pfade akzeptiert werden und, falls ja, wie sie verarbeitet werden sollen. Wenn Sie URL PATH angeben, hat dies dieselbe Wirkung wie URL.

OFF Gibt an, dass auf den Dienstnamen in einer URL-Anforderung kein Pfad folgen darf. OFF ist die Standardeinstellung. Zum Beispiel ist das folgende Format aufgrund der Pfadelemente /aaa/bbb/ccc nicht zulässig.

http://host-name/service-name/aaa/bbb/ccc

Nehmen wir an, bei der Erstellung des Webdiensts wurde CREATE SERVICE echo URL PATH OFF angegeben. Eine URL ähnlich wie http://localhost/echo?id=1 erzeugt die folgenden Werte:

HTTP_VARIABLE('id') == 1,
HTTP_HEADER('@HTTPQUERYSTRING') == id=1

ON Gibt an, dass auf den Dienstnamen in einer URL-Anforderung ein Pfad folgen darf. Der Pfadwert wird zurückgegeben durch Abfragen einer ausschließlich für ihn vorgesehenen HTTP-Variable mit dem Namen URL. Ein Dienst kann so definiert werden, dass er explizit den URL-Parameter bereitstellt, oder er kann mit der Funktion HTTP_VARIABLE abgerufen werden. Die folgende Form ist beispielsweise zulässig:

http://host-name/service-name/aaa/bbb/ccc

Nehmen wir an, bei der Erstellung des Webdiensts wurde CREATE SERVICE echo URL PATH ON angegeben. Eine URL ähnlich wie http://localhost/echo/one/two?id=1 erzeugt die folgenden Werte:

HTTP_VARIABLE('id') == 1,
HTTP_VARIABLE('URL') == one/two,
HTTP_HEADER('@HTTPQUERYSTRING') == id=1

ELEMENTS Gibt an, dass auf den Dienstnamen in einer URL-Anforderung ein Pfad folgen darf. Der Pfad wird in Segmenten abgerufen durch die Angabe des einzelnen Parameter-Schlüsselworts URL1, URL2 usw. Jeder Parameter kann mit der Funktion HTTP_VARIABLE oder NEXT_HTTP_VARIABLE abgerufen werden. Diese Wiederholfunktionen können in Anwendungen verwendet werden, in denen eine variable Anzahl von Pfadelementen bereitgestellt werden kann. Die folgende Form ist beispielsweise zulässig:

http://host-name/service-name/aaa/bbb/ccc

Nehmen wir an, bei der Erstellung des Webdiensts wurde CREATE SERVICE echo URL PATH ELEMENTS angegeben. Eine URL ähnlich wie http://localhost/echo/one/two?id=1 erzeugt die folgenden Werte:

HTTP_VARIABLE('id') == 1,
HTTP_VARIABLE('URL1') == one,
HTTP_VARIABLE('URL2') == two,
HTTP_HEADER('@HTTPQUERYSTRING') == id=1

Bis zu 10 Elemente können abgerufen werden. NULL wird zurückgegeben, wenn das entsprechende Element nicht angegeben wurde. In diesem Beispiel gibt HTTP_VARIABLE('URL3') NULL zurück, weil kein entsprechendes Element angegeben wurde.

Weitere Hinweise zu URLs finden Sie unter HTTP-Webserver durchsuchen und Auf vom Client bereitgestellte HTTP-Variablen und -Header zugreifen.

AUTHORIZATION-Klausel Bestimmt, ob die Benutzer einen Benutzernamen und ein Kennwort über die HTTP-Grundautorisierung angeben müssen, wenn sie eine Verbindung mit dem Dienst herstellen. Der Standardwert ist ON. Wenn AUTHORIZATION auf OFF gesetzt ist, muss die AS-Klausel für alle Dienste verwendet werden und ein Benutzer muss mit der USER-Klausel angegeben werden. Alle Anforderungen werden mit dem Konto und den Berechtigungen des betreffenden Benutzers ausgeführt. Wenn AUTHORIZATION auf ON gesetzt ist, müssen alle Benutzer einen Benutzernamen und ein Kennwort angeben. Der Zugriff auf diesen Dienst kann durch Angabe eines Benutzer- oder Gruppennamens mithilfe der USER-Klausel eingeschränkt werden. Wenn der Benutzername NULL ist, haben alle bekannten Benutzer Zugriff auf den Dienst. Die AUTHORIZATION-Klausel ermöglicht es den Webdiensten, mithilfe der Berechtigungen den Zugriff auf die Daten in Ihrer Datenbank zu steuern.
Wenn der Autorisierungswert ON ist, benutzt ein HTTP-Client, der sich mit einem Webdienst verbindet, die Basisauthentifizierung (RFC 2617), die die Benutzer- und Kennwortdaten mit base-64-Kodierung verschleiert. Es wird empfohlen, für erweiterte Sicherheit das HTTPS-Protokoll zu verwenden.
ENABLE- und DISABLE-Klausel Legt fest, ob der Dienst verfügbar ist. Standardmäßig ist ein Dienst aktiviert, wenn er erstellt wird. Beim Erstellen oder Ändern eines Diensts können Sie eine ENABLE- oder DISABLE-Klausel einbauen. Durch das Deaktivieren eines Diensts wird dieser offline gesetzt. Später kann er mit ALTER SERVICE und einer ENABLE-Klausel aktiviert werden. Eine HTTP-Anforderung an einen deaktivierten Dienst gibt in der Regel den HTTP-Status 404 Not Found zurück.

METHODS-Klausel Gibt die HTTP-Methoden an, die vom Dienst unterstützt werden. Gültige Werte sind DEFAULT, POST, GET, HEAD, PUT, DELETE und NONE. Ein Sternchen (*) kann als Platzhalter für die Methoden POST, GET und HEAD verwendet werden, welche die Standard-Anforderungstypen für die Diensttypen RAW, HTML und XML sind. Nicht alle HTTP-Methoden sind für alle Diensttypen gültig. Die folgende Tabelle enthält eine Übersicht über die gültigen HTTP-Methoden, die auf die einzelnen Diensttypen angewendet werden können:

Methodenwert	Gilt für Dienst	Beschreibung
DEFAULT	alle	Verwenden Sie DEFAULT, um die Gruppe der standardmäßigen HTTP-Methoden für den angegebenen Diensttyp zurückzusetzen. Kann nicht in eine Liste mit anderen Methodenwerten aufgenommen werden.
POST	RAW, HTML, JSON, XML	Standardmäßig aktiviert.
GET	RAW, HTML, JSON, XML	Standardmäßig aktiviert.
HEAD	RAW, HTML, JSON, XML	Standardmäßig aktiviert.
PUT	RAW, HTML, JSON, XML	Standardmäßig nicht aktiviert.
DELETE	RAW, HTML, JSON, XML	Standardmäßig nicht aktiviert.
NONE	alle	Verwenden Sie NONE, um den Zugriff auf einen Dienst zu deaktivieren.
*	RAW, HTML, JSON, XML	Wie 'POST,GET,HEAD'.

Zum Beispiel können Sie eine der folgenden Klauseln verwenden, um festzulegen, dass ein Dienst alle HTTP-Methodentypen unterstützt:

METHODS '*,PUT,DELETE'
METHODS 'POST,GET,HEAD,PUT,DELETE'

Um die Liste der Anforderungstypen für einen beliebigen Diensttyp auf den Standardwert zu setzen, können Sie die folgende Klausel verwenden:

METHODS 'DEFAULT'

SECURE-Klausel Gibt an, ob der Dienst auf einem sicheren oder nicht sicheren Listener zugänglich sein soll. ON bedeutet, dass nur HTTPS-Verbindungen akzeptiert werden und dass über den HTTP-Port empfangene Verbindungen automatisch zum HTTPS-Port umgeleitet werden. OFF bedeutet, dass sowohl HTTP- als auch HTTPS-Verbindungen akzeptiert werden, vorausgesetzt, die erforderlichen Ports werden beim Starten des Webservers angegeben. Der Standardwert ist OFF.
USER-Klausel Gibt einen Datenbankbenutzer oder eine Gruppe von Benutzern mit der Berechtigung an, die Webdienstanfordertung auszuführen. Eine USER-Klausel muss angegeben werden, wenn der Dienst mit AUTHORIZATION OFF konfiguriert wird, und sollte angegeben werden, wenn AUTHORIZATION ON (Standardwert) verwendet wird. Eine HTTP-Anforderung an einen Dienst, der Autorisierung erfordert, liefert den HTTP-Antwortstatus "401 Authorization Required". Basierend auf dieser Antwort fordert der Webbrowser den Benutzer auf, eine Benutzer-ID und ein Kennwort einzugeben.

Achtung

Es wird dringend empfohlen, dass Sie eine USER-Klausel angeben, wenn die Autorisierung aktiviert ist (Standardwert). Andernfalls wird die Berechtigung für alle Benutzer erteilt.

Die USER-Klausel steuert, welche Datenbank-Benutzerkonten verwendet werden können, um Dienstanforderungen zu verarbeiten. Datenbankzugriffsberechtigungen werden auf die dem Benutzer des Dienstes zugewiesenen Berechtigungen beschränkt.

statement Gibt einen Befehl an, zum Beispiel einen Aufruf einer gespeicherten Prozedur, der beim Zugreifen auf den Dienst aufgerufen werden soll.

Eine HTTP-Anforderung an einen Nicht-DISH-Dienst ohne statement gibt den SQL-Ausdruck zurück, der innerhalb seiner URL ausgeführt werden soll. Obwohl eine Autorisierung erforderlich ist, darf diese Fähigkeit nicht in Produktionssystemen benutzt werden, weil dies den Server für SQL-Injektionen anfällig macht. Wenn eine Anweisung in dem Dienst definiert ist, kann die angegebene SQL-Anweisung als einzige Anweisung über den Dienst ausgeführt werden.

In einer typischen Webdienstanwendung verwenden Sie statement zum Aufrufen einer Funktion oder Prozedur. Sie können Hostvariablen als Parameter für den Zugriff auf vom Client gelieferte HTTP-Variablen übergeben.

Die folgende statement zeigt einen Prozeduraufruf, der zwei Hostvariablem an eine Prozedur mit dem Namen AuthenticateUser übergibt. Dieser Aufruf setzt voraus, dass ein Webclient die Variablen user_name und user_password liefert:

CALL AuthenticateUser ( :user_name, :user_password );

Weitere Hinweise zum Übergeben von Hostvariablen an eine Funktion oder Prozedur finden Sie unter Auf vom Client bereitgestellte HTTP-Variablen und -Header zugreifen.

Die ALTER SERVICE-Anweisung ändert die Attribute eines Webdiensts.

DBA-Berechtigung

Keine.

SQL/2008 Erweiterung des Herstellers.

Das folgende Beispiel zeigt, wie Sie einem vorhandenen Webdienst mit der ALTER SERVICE-Anweisung deaktivieren:

CREATE SERVICE WebServiceTable
   TYPE 'RAW'
   AUTHORIZATION OFF
   USER DBA
   AS SELECT *
      FROM SYS.SYSTAB;

ALTER SERVICE WebServiceTable DISABLE;

ALTER SERVICE-Anweisung [HTTP-Webdienst]

Syntax

Parameter

Achtung

Bemerkungen

Berechtigungen

Nebenwirkungen

Siehe auch

Standards und Kompatibilität

Beispiel