Erstellt einen neuen Webdienst.
Syntax 1: Allgemeine HTTP-Webdienste Syntax 2: SOAP über HTTP Syntax 3: DISH-Dienste ParameterDienstname 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. Weitere Hinweise finden Sie unter root-Webdienst erstellen und anpassen.
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 als SOAP-Antwort zurückgegeben. 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 ![[external link]](gif/external.gif)
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.
'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. Siehe Webdienstanwendungen auf einem HTTP-Webserver entwickeln und sa_set_http_header-Systemprozedur.
'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. 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. Siehe sa_set_http_header-Systemprozedur.
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 das letzte Schrägstrich-Zeichen von der Gruppe getrennt. Beispiel: Der Name eines als 'aaa/bbb/ccc' definierten SOAP-Dienstes ist 'ccc', und die Gruppe 'aaa/bbb'. Das Abtrennen 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.
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 werden als XMLSchema-Zeichenfolge eingegeben. (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 XMLSchema-Typen zu SQL-Datentypen finden Sie unter Mit Datentypen arbeiten (nur SOAP).
URL-Klausel Bestimmt, ob URL-Pfade akzeptiert werden und, falls ja, wie sie verarbeitet werden sollen. Gilt für XML-, HTML-, JSON- und RAW-Diensttypen. PATH ist in der Syntax optional und wird ignoriert.
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.
FORMAT-Klausel Gilt nur für DISH- und SOAP-Dienste. 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. Das 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 für DISH- und SOAP-Dienste 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 letzte Möglichkeit wird ein CONCRETE-Format 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 alle Dienste mit Ausnahme von DISH 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. 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:
| Anforderungstyp | Gilt für Dienst | Beschreibung |
|---|---|---|
| DEFAULT | Alle | Verwenden Sie DEFAULT, um die Gruppe von Anforderungstypen auf die Standardwertgruppe für einen bestimmten Diensttyp zurückzusetzen. Kann nicht in eine Liste mit anderen Anforderungstypen aufgenommen werden. |
| POST | SOAP, DISH, RAW, HTML, XML | Standardmäßig aktiviert für SOAP, RAW, HTML und XML. |
| GET | DISH, RAW, HTML, XML | Standardmäßig aktiviert für DISH, RAW, HTML und XML. |
| HEAD | SOAP, DISH, RAW, HTML, XML | Standardmäßig aktiviert für SOAP, DISH, RAW, HTML und XML. |
| PUT | RAW, HTML, XML | Standardmäßig nicht aktiviert. |
| DELETE | RAW, HTML, XML | Standardmäßig nicht aktiviert. |
| NONE | Alle |
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. |
| * | DISH, RAW, HTML, 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.
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.
Anweisung 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 Anweisung 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 Anweisung 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 Anweisung 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.
Bemerkungen Berechtigungen Nebenwirkungen Siehe auch Standards und Kompatibilität Beispiele |
Kommentieren Sie diese Seite in DocCommentXchange.
|
Copyright © 2010, iAnywhere Solutions, Inc. - SQL Anywhere 12.0.0 |