ALTER SERVICE-Anweisung [SOAP-Webdienst]

ALTER SERVICE service-name
[ TYPE 'SOAP' ]
[ DATATYPE { ON | OFF | IN | OUT } ]
[ FORMAT { 'DNET' | 'CONCRETE' [ EXPLICIT { ON | OFF } ] | 'XML' | NULL } ]
[ common-attributes ]
[ AS statement ]

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

method :
DEFAULT
| POST
| HEAD
| NONE

ALTER SERVICE service-name
[ TYPE 'DISH' ]
[ GROUP { group-name | NULL } ]
[ FORMAT { 'DNET' | 'CONCRETE' [ EXPLICIT { ON | OFF } ]| 'XML' | NULL } ]
[ common-attributes ]

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

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

Die Beschreibung der Klauseln für die ALTER SERVICE-Anweisung ist mit der Beschreibung der Klauseln für die CREATE SERVICE-Anweisung identisch.

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.
Im Gegensatz zu anderen Diensten dürfen Sie in einem DISH-Dienstnamen keinen Schrägstrich (/) verwenden.

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.
- 'SOAP' Die Ergebnismenge wird im XML-Format zurückgegeben, das als SOAP-Envelope bezeichnet wird. Das Format der Daten wird durch die FORMAT-Klausel bestimmt. Eine Anforderung an einen SOAP-Dienst muss eine gültige SOAP-Anforderung und nicht nur eine einfache HTTP-Anforderung sein. Weitere Hinweise zu den SOAP-Standards finden Sie unter http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
- 'DISH' Ein DISH-Dienst (Determine SOAP Handler) ist ein SOAP-Endpunkt, der alle SOAP-Dienste in seinem GROUP-Kontext referenziert. Außerdem exponiert er die Schnittstellen zu seinen SOAP-Diensten durch die Erstellung eines WSDL-Objekts (Web Services Description Language), das von SOAP-Client-Toolkits verwendet werden kann.
GROUP-Klausel Ein DISH Dienst ohne GROUP-Klausel exponiert alle in der Datenbank definierten SOAP-Dienste. Laut Konvention kann der SOAP-Dienstname aus einem GROUP- und einem NAME-Element bestehen. Der Name wird durch den letzten Schrägstrich von der Gruppe getrennt. Beispiel: Der Name eines als 'aaa/bbb/ccc' definierten SOAP-Dienstes ist 'ccc', und die Gruppe 'aaa/bbb'. Die Angabe eines DISH-Dienstes unter Verwendung dieser Konvention ist ungültig. Stattdessen wird eine GROUP-Klausel angewendet, um die Gruppe von SOAP-Diensten anzugeben, für die er als SOAP-Endpunkt fungieren soll.

Hinweis

Schrägstriche werden in WSDL in Unterstriche konvertiert, um gültigen XML-Code zu erzeugen. Lassen Sie bei der Verwendung von einem DISH-Dienst Vorsicht walten, dessen GROUP-Klausel nicht so angegeben ist, dass alle SOAP-Dienste exponiert werden, die möglicherweise Schrägstriche enthalten. Lassen Sie Vorsicht walten, wenn Sie Gruppen in Verbindung mit SOAP-Dienstnamen verwenden, die Unterstriche enthalten, um Mehrdeutigkeiten zu vermeiden.
DATATYPE-Klausel Gilt nur für SOAP-Dienste. Wenn DATATYPE OFF angegeben ist, werden SOAP-Eingabeparameter und -Antwortdaten als XMLSchema-Zeichenfolgetypen definiert. In den meisten Fällen werden die tatsächlichen Datentypen bevorzugt, weil durch sie die Notwendigkeit entfällt, dass der SOAP-Client die Daten vor der Berechnung festlegt. Parameterdatentypen werden im Schema-Abschnitt der WDSL angezeigt, der vom DISH-Dienst erstellt wird. Ausgabedatentypen werden als XML-Schematypattribute für die jeweilige Datenspalte dargestellt.
Die folgenden Werte sind bei der DATATYPE-Klausel zulässig:
- ON Generiert die Datentypisierung für Eingabeparameter und zurückgegebene Ergebnismengen
- OFF Alle Eingabeparameter und Antwortdaten haben den Datentyp XMLSchema-Zeichenfolge (Standardwert).
- IN Generiert die tatsächlichen Datentypen nur für Eingabeparameter. Antwortdatentypen sind XMLSchema-Zeichenfolgen.
- OUT Generiert die tatsächlichen Datentypen nur für Antworten. Eingabeparameter werden als XMLSchema-Zeichenfolge eingegeben.
Weitere Hinweise zu SOAP-Diensten finden Sie unter Praktische Einführung: Verwenden von SQL Anywhere für den Zugriff auf einen SOAP/DISH-Dienst.

Weitere Hinweise zur Zuordnung von XML-Schematypen zu SQL-Datentypen finden Sie unter SOAP-Datentypen.
FORMAT-Klausel Diese Klausel gibt das Ausgabeformat an, das beim Senden von Antworten an SOAP-Clientanwendungen verwendet wird.
Das SOAP-Dienstformat wird durch die dazugehörige DISH-Dienstformatspezifikation bestimmt, wenn es nicht vom SOAP-Dienst angegeben wird. Das Standardformat ist DNET.

SOAP-Anforderungen sollten an den DISH-Dienst (den SQL Anywhere-SOAP-Endpunkt) gerichtet werden, um gemeinsame Formatierungsregeln für eine Gruppe von SOAP-Diensten (SOAP-Vorgängen) zu nutzen. Eine FORMAT-Spezifikation für einen SOAP-Dienst überschreibt diejenige eines DISH-Dienstes. Die Formatspezifikation des DISH-Dienstes wird verwendet, wenn für den SOAP-Dienst keine FORMAT-Klausel definiert ist. Wenn für keinen der beiden Dienste ein FORMAT-Objekt zur Verfügung gestellt wird, ist der Standardwert 'DNET'.

Folgende Formate werden unterstützt:
- 'DNET' Die Ausgabe erfolgt in einem System.Data.DataSet-kompatiblen Format zur Verwendung durch .NET-Clientanwendungen (Standardwert).
- 'CONCRETE' Dieses Ausgabeformat wird zur Unterstützung von Client-SOAP-Toolkits verwendet, die in der Lage sind, Schnittstellen zu generieren, die Arrays von Zeilen- und Spaltenobjekten darstellen, aber nicht in der Lage sind, das DNET-Format zu bearbeiten. Java -und .NET-Clients können dieses Ausgabeformat einfach bearbeiten.
  Das spezifische Ausgabeformat wird im WSDL-Objekt eines DISH-Dienstes exponiert. Bei CONCRETE OFF oder, als letzter Möglichkeit, einem CONCRETE-Format wird es für einen oder mehrere SOAP-Dienste als SimpleDataset dargestellt. Das WSDL-Objekt zeigt, dass SimpleDataset aus einem Array von Zeilen besteht, das wiederum aus einem Array mit einer beliebigen Anzahl von Spalten besteht. Dies ist keine ideale Darstellung, weil die jeweiligen Spaltennamen und Datentypen nicht angegeben werden. Es wird empfohlen, dass SOAP-Dienste einen Aufruf einer gespeicherten Prozedur definieren, die wiederum eine RESULT-Klausel definiert. Ein DISH-Dienst, der SOAP-Dienste mit einer derartigen Definition exponiert, kann die Ergebnismenge vollständig beschreiben, wenn das WSDL-Objekt generiert wird.
  
  Standardmäßig wird EXPLICIT ON vorausgesetzt und das WSDL-Objekt enthält einen bestimmten Dataset-Eintrag für jeden SOAP-Dienst, wenn die Ergebnismenge für einen SOAP-Dienst beschrieben werden kann. Jedem Eintragsnamen werden der SOAP-Dienstname und ein Unterstrich vorangestellt. Beispiel: Ein SOAP-Dienst mit dem Namen test erzeugt eine test_Dataset-Objektspezifikation mit den XMLSchema-Definitionen für jedes seiner Spaltenelemente.
  
  Wenn EXPLICIT ON angegeben ist (Standard), beschreibt das WSDL-Objekt ein explizites DataSet-Element, sofern folgende Kriterien erfüllt sind:
  - Die CREATE SERVICE-Anweisung ruft eine gespeicherte Prozedur auf.
  - Eine RESULT-Klausel mit der Beschreibung der Spalten und Datentypen ist in der gespeicherten Prozedur angegeben.
  Wenn EXPLICIT OFF angegeben ist, beschreibt as WSDL-Objekt das SimpleDataset-Element. Diese Beschreibung stellt nicht die Anzahl der Spalten, Spaltennamen oder Datentypen bereit.
- 'XML' Die Ausgabe wird in einem XMLSchema-Zeichenfolgenformat generiert. Die Antwort ist ein XML-Dokument, das zum Extrahieren der Spaltendaten eine weitere Verarbeitung durch den SOAP-Client erfordert. Dieses Format ist für SOAP-Clients geeignet, die keine Zwischen-Schnittstellenobjekte generieren, welche Arrays von Zeilen und Spalten darstellen.
- NULL Im Falle eines NULL-Typs verwendet der SOAP- oder DISH-Dienst das Standardverhalten. Der Formattyp eines bestehenden Diensts wird überschrieben, wenn der NULL-Typ in einer ALTER SERVICE-Anweisung verwendet wird.
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 SOAP-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, und NONE. Ein Sternchen (*) kann als Kurzform für die Darstellung der POST-, GET- und HEAD-Methoden verwendet werden. Die Standard-Methodentypen für SOAP-Dienste sind POST und HEAD. Die Standard-Methodentypen für DISH-Dienste sind GET, POST und HEAD. 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	Beide	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	Beide	Standardmäßig aktiviert für SOAP.
GET	Nur DISH	Standardmäßig aktiviert für DISH.
HEAD	Beide	Standardmäßig aktiviert für SOAP und DISH.
NONE	Beide	Verwenden Sie NONE, um den Zugriff auf einen Dienst zu deaktivieren. Bei der Anwendung auf einen SOAP-Dienst kann auf den Dienst nicht direkt über eine SOAP-Anforderung zugegriffen werden. Dies erzwingt exklusiven Zugriff auf einen SOAP-Vorgang über einen als SOAP-Endpunkt fungierenden DISH-Dienst. Es wird empfohlen, für die einzelnen SOAP-Dienste METHOD NONE anzugeben.
*	Nur DISH	Wie 'POST,GET,HEAD'.

Zum Beispiel können Sie die folgende Klausel verwenden, um festzulegen, dass ein Dienst alle SOAP über HTTP-Methodentypen unterstützt:

METHODS 'POST,HEAD'

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 Webdienstanforderung 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.

Ein DISH-Dienst ist der einzige Dienst, der entweder eine Null-Anweisung definieren oder keine Anweisung definieren muss. Ein SOAP-Dienst muss eine Anweisung definieren. Jeder andere SERVICE-Wert kann eine NULL-Anweisung definieren, jedoch nur, wenn er mit AUTHORIZATION ON konfiguriert ist.

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 'SOAP'
   AUTHORIZATION OFF
   USER DBA
   AS SELECT *
      FROM SYS.SYSTAB;

ALTER SERVICE WebServiceTable DISABLE;

ALTER SERVICE-Anweisung [SOAP-Webdienst]

Syntax 1 - SOAP über HTTP-Dienste

Syntax 2 - DISH-Dienste

Parameter

Parameter

Hinweis

Achtung

Bemerkungen

Berechtigungen

Nebenwirkungen

Siehe auch

Standards und Kompatibilität

Beispiel