CREATE PROCEDURE-Anweisung (Webclients)

CREATE [ OR REPLACE ] PROCEDURE [ Eigentümer.]Prozedurname ( [ Parameter, ... ] )
URL URL-Zeichenfolge
[ TYPE { HTTP-Typ-Zeichenfolge | SOAP-Typ-Zeichenfolge } ]
[ HEADER Header-Zeichenfolge ]
[ CERTIFICATE Zertifikat-Zeichenfolge ]
[ CLIENTPORT Clientport-Zeichenfolge ]
[ PROXY Proxy-Zeichenfolge ]
[ SET Protokolloption-Zeichenfolge ]
[ SOAPHEADER SOAP-Header-Zeichenfolge ]
[ NAMESPACE Namespace-Zeichenfolge ]

HTTP-Typ-Zeichenfolge :
HTTP[: { GET 
  | POST[:MIME-Typ ] 
  | PUT[:MIME-Typ ] 
  | DELETE 
  | HEAD } ]

SOAP-Typ-Zeichenfolge :
SOAP[:{ RPC | DOC }

Parameter :
  Parametermodus Parametername Datentyp [ DEFAULT Ausdruck ]

Parametermodus : 
IN 
| OUT 
| INOUT

URL-Zeichenfolge :
{ HTTP | HTTPS | HTTPS_FIPS }://[Benutzer:Kennwort@]Hostname[:Port][/Pfad]

Protokolloption-Zeichenfolge
[ HTTP-Optionsliste]
[, SOAP-Optionsliste ]

HTTP-Optionsliste : 
HTTP(
[ CH[UNK]={ ON | OFF | AUTO } ]
[; VER[SION]={ 1.0 | 1.1 } ]
)

 SOAP-Optionsliste: 
SOAP(OP[ERATION]=SOAP-Vorgangsname)

CREATE PROCEDURE Sie können eine Webdienst-Clientprozedur erstellen oder ersetzen. PROC kann als Synonym für PROCEDURE verwendet werden.
Für SOAP-Anforderungen wird der Prozedurname standardmäßig als SOAP-Vorgangsname verwendet. Siehe SET-Klausel.

Parameternamen müssen den Regeln für andere Datenbankbezeichner, wie z.B. Spaltennamen, entsprechen. Es muss sich dabei um einen gültigen SQL-Datentyp handeln. Eine Liste der gültigen Datentypen finden Sie unter SQL-Datentypen.

Nur SOAP-Anforderungen unterstützen die Übertragung von eingetippten Daten des Typs FLOAT, INT etc. HTTP-Anforderungen unterstützen nur die Übertragung von Zeichenfolge, daher sind sie hier auf CHAR-Datentypen beschränkt. Weitere Hinweise zu unterstützten SOAP-Datentypen finden Sie unter Mit Datentypen arbeiten (nur SOAP) und Mit strukturierten Datentypen arbeiten (nur SOAP).

Parameter können eines der Schlüsselwörter IN, OUT oder INOUT vorangestellt haben. Wenn Sie keinen dieser Werte angeben, sind die Parameter standardmäßig INOUT. Die Schlüsselwörter haben die folgenden Bedeutungen:
- IN Dieser Parameter ist ein Ausdruck, der der Prozedur einen Wert zur Verfügung stellt.
- OUT Dieser Parameter ist eine Variable, die von der Prozedur einen Wert erhalten kann.
- INOUT Dieser Parameter ist eine Variable, die einen Wert für die Prozedur bereitstellt und von der Prozedur einen neuen Wert erhalten kann.
Wenn Prozeduren mit der CALL-Anweisung ausgeführt werden, müssen nicht alle Parameter angegeben werden. Wenn in der CREATE PROCEDURE-Anweisung ein Standardwert bereitgestellt wird, werden fehlenden Parametern die Standardwerte zugeordnet. Falls kein Argument in der CALL-Anweisung angegeben wurde und kein Standardwert gesetzt ist, wird ein Fehler ausgegeben.

Wenn Sie OR REPLACE (CREATE OR REPLACE PROCEDURE) angeben, wird eine neue Prozedur erstellt oder eine bestehende Prozedur mit demselben Namen ersetzt. Diese Klausel ändert die Definition der Prozedur, lässt aber bestehende Berechtigungen unberührt. Ein Fehler wird zurückgegeben, wenn Sie eine Prozedur ersetzen, die gerade verwendet wird.

Sie können keine TEMPORARY-Webdienst-Prozeduren erstellen.
URL-Klausel Gibt den URI des Webdiensts an. Die optionalen Benutzernamen- und Kennwortparameter bieten eine Möglichkeit, die für die HTTP Basic Authentication erforderlichen Berechtigungsnachweise zu liefern. Die HTTP Basic Authentication Base-64 verschlüsselt die Benutzer- und Kennwortinformationen und übergibt sie an den Header "Authentication" der HTTP-Anforderung. Bei dieser Art der Angabe werden Benutzername und Kennwort unverschlüsselt, als Teil der URL, übergeben.

TYPE-Klausel Gibt das für die Webdienstanforderung verwendete Format an. SOAP:RPC wird verwendet, wenn SOAP angegeben oder keine TYPE-Klausel enthalten ist. HTTP:POST wird verwendet, wenn HTTP angegeben ist. Siehe Webclientanwendungen entwickeln.

Die TYPE-Klausel ermöglicht die Angabe eines MIME-Typs für HTTP:GET-, HTTP:POST- und HTTP:PUT-Typen. Mithilfe des Werts für den MIME-Typ wird der Anforderungs-Header "Content-Type" eingerichtet und der Betriebsmodus so eingestellt, dass nur ein einzelner Aufrufparameter den Hauptteil der Anforderung auffüllen kann. Wenn ein Webdienstaufruf einer gespeicherten Prozedur erfolgt, nachdem Parameterersetzungen verarbeitet wurden, darf kein oder nur ein einziger Parameter verbleiben. Der Aufruf einer Webdienstprozedur mit NULL oder keinem Parameter (nach Ersetzungen) ergibt eine Anfrage ohne Hauptteil und mit einer Inhaltslänge von Null. Wenn kein MIME-Typ angegeben wird, ist das Verhalten unverändert. Parameternamen und -werte (Mehrfachparameter sind erlaubt) werden innerhalb des Hauptteils der HTTP-Anforderungen URL-kodiert.

Zu den typischen MIME-Typen gehören folgende:

text/plain
text/html
text/xml

Die Schlüsselwörter für die TYPE-Klausel haben die folgende Bedeutung:

'HTTP:GET' Standardmäßig verwendet dieser Typ den MIME-Typ application/x-www-form-urlencoded zum Kodieren von in der URL angegebenen Parametern.

Die folgende Anforderung wird beispielsweise erzeugt, wenn ein Client eine Anforderung aus der URL http://localhost/WebServiceName?arg1=param1&arg2=param2 sendet:

GET /WebServiceName?arg1=param1&arg2=param2 HTTP/1.1
// <End of Request - NO BODY>

'HTTP:POST' Standardmäßig verwendet dieser Typ den MIME-Typ application/x-www-form-urlencoded zum Kodieren von im Hauptteil einer POST-Anforderung angegebenen Parametern. URL-Parameter werden im Hauptteil der Anforderung gespeichert.

Die folgende Anforderung wird beispielsweise erzeugt, wenn ein Client eine Anforderung aus der URL http://localhost/WebServiceName?arg1=param1&arg2=param2 sendet:

POST /WebServiceName HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 19
arg1=param1&arg2=param2
// <End of Request>

HTTP:PUT HTTP:PUT ist ähnlich wie HTTP:POST, aber die HTTP-Anforderungsmethode wird gesendet. Ein HTTP:PUT-Typ verfügt nicht über einen Standardmedientyp.

Das folgende Beispiel zeigt, wie Sie eine allgemeine Clientprozedur für den Upload von Daten in einen SQL Anywhere-Server, der das Beispiel Beispielverzeichnis\SQLAnywhere\HTTP\put_data.sql ausführt, konfigurieren:

ALTER PROCEDURE CPUT("data" LONG VARCHAR, resnm LONG VARCHAR, mediatype LONG VARCHAR)
    URL 'http://localhost/resource/!resnm'
    TYPE 'HTTP:PUT:!mediatype';

CALL CPUT('hello world', 'hello', 'text/plain' );

HTTP:DELETE Eine Webdienst-Clientprozedur kann so konfiguriert werden, dass eine auf einem Server befindliche Ressource gelöscht wird. Das Angeben des Medientyps ist optional.

Das folgende Beispiel zeigt, wie Sie eine allgemeine Clientprozedur für das Löschen von Daten aus einem SQL Anywhere-Server, der das Beispiel put_data.sql ausführt, konfigurieren:

ALTER PROCEDURE CDEL(resnm LONG VARCHAR, mediatype LONG VARCHAR)
    URL 'http://localhost/resource/!resnm'
    TYPE 'HTTP:DELETE:!mediatype';

CALL CDEL('hello', 'text/plain' );

HTTP:HEAD Die head-Methode ist identisch mit einer GET-Methode, aber der Server gibt keinen Hauptteil zurück. Ein Medientyp kann angegeben werden.

ALTER PROCEDURE CHEAD(resnm LONG VARCHAR) URL 'http://localhost/resource/!resnm' TYPE 'HTTP:HEAD'; CALL CHEAD( 'hello' );

'SOAP:RPC' Dieser Typ setzt den Content-Type-Header auf 'text/xml'. SOAP-Vorgänge und-Parameter werden in SOAP Envelope-XML-Dokumenten gekapselt.
'SOAP:DOC' Dieser Typ setzt den Content-Type-Header auf 'text/xml'. Er ähnelt dem SOAP:RPC-Typ, ermöglicht jedoch das Senden umfangreicherer Datentypen. SOAP-Vorgänge und-Parameter werden in SOAP Envelope-XML-Dokumenten gekapselt.

Das Angeben eines MIME-Typs für die TYPE-Klausel setzt automatisch den Content-Type-Header auf diesen MIME-Typ. Beispiele für die Verwendung des MIME-Typs finden Sie unter Variablen an einen Webdienst übergeben und Praktische Einführung: Verwenden von MIME-Typen in einem RAW-Dienst.

HEADER-Klausel Wenn Sie HTTP-Webdienst-Clientprozeduren erstellen, verwenden Sie diese Klausel, um Headereinträge der HTTP-Anforderung hinzuzufügen, sie zu ändern oder zu löschen. Die Angabe von Headern ist dem Format sehr ähnlich, das im RFC2616 Hypertext Transfer Protocol - HTTP/1.1 und im RFC822-Standard für ARPA Internet-Textnachrichten verwendet wird, einschließlich der Tatsache, dass nur druckbare ASCII-Zeichen für HTTP-Header angegeben werden können, deren Groß- und Kleinschreibung nicht berücksichtigt wird.
Header können definiert werden als Headername:Wertname-Paare. Jeder Header wird mit einem Doppelpunkt ( : ) von seinem Wert getrennt und darf daher keinen Doppelpunkt enthalten. Sie können mehrere Header definieren, indem Sie die Paare mit \n, \x0d\n, <LF> (Zeilenvorschub), oder <CR><LF> voneinander trennen. (Wagenrücklauf gefolgt von einem Zeilenvorschub)

Mehrere aufeinanderfolgende Leerzeichen innerhalb des Headers werden in ein einziges Leerzeichen konvertiert.

Weitere Hinweise zur Verwendung von HTTP-Headern finden Sie unter HTTP-Anforderungsheader verwalten.

CERTIFICATE-Klausel Um eine sichere (HTTPS-)Anforderung durchführen zu können, muss der Client Zugriff auf das vom HTTPS-Server verwendete Zertifikat haben. Die benötigten Informationen werden in einer Zeichenfolge von durch Semikola getrennten Schlüssel/Werte-Paaren angegeben. Sie können mithilfe des Dateischlüssels den Dateinamen für das Zertifikat angeben oder mithilfe des Zertifikatschlüssels das Serverzertifikat in einer Zeichenfolge angeben. Sie können nicht sowohl einen Dateischlüssel als auch einen Zertifikatschlüssel angeben. Folgende Schlüssel sind verfügbar:

Schlüssel	Abkürzung	Beschreibung
file		Der Dateiname des Zertifikats
certificate	cert	Das Zertifikat selbst
company	co	Die im Zertifikat angegebene Organisation
unit		Die im Zertifikat angegebene Organisationseinheit
name		Der im Zertifikat angegebene allgemeine Name

Zertifikate sind nur bei Anforderungen erforderlich, die entweder an den HTTPS-Server gerichtet sind oder von einem nicht-sicheren zu einem sicheren Server umgeleitet werden können. Nur PEM-formatierte Zertifikate werden unterstützt.

CLIENTPORT-Klausel Kennzeichnet die Portnummer, auf der die HTTP-Clientprozedur mithilfe von TCP/IP kommuniziert. Sie wird nur für Verbindungen über Firewalls bereitgestellt und empfohlen, die "ausgehende" TCP/IP-Verbindungen filtern. Sie können eine einzelne Portnummer, Bereiche von Portnummern oder eine Kombination von beiden angeben, z.B. CLIENTPORT "85,90-97". Siehe ClientPort-Protokolloption (CPORT).
PROXY-Klausel Gibt den URI eines Proxyservers an. Wird verwendet, wenn der Client über einen Proxyserver auf das Netzwerk zugreifen muss. Zeigt an, dass die Prozedur eine Verbindung zum Proxyserver herstellen soll, um die Anforderung durch ihn zum Webdienst zu senden.

SET-Klausel Gibt Optionen für protokollspezifisches Verhalten für HTTP und SOAP an. Die folgende Liste beschreibt die unterstützten SET-Optionen. CHUNK und VERSION gelten für das HTTP-Protokoll und OPERATION gilt für das SOAP-Protokoll. Die Ersetzung von Parametern wird bei dieser Klausel unterstützt.

'HTTP(CH[UNK]=option)' (HTTP oder SOAP) Mit dieser Option können Sie angeben, ob das Aufteilen in Abschnitte verwendet werden soll. Dies ermöglicht es, HTTP-Nachrichten in mehrere Abschnitte aufzuteilen. Mögliche Werte sind: ON (immer Abschnitte verwenden), OFF (keine Abschnitte) und AUTO (Abschnitte nur verwenden, wenn der Inhalt, ausgenommen automatisch generiertes Markup, 8196 Byte überschreitet). Die folgende SET-Klausel aktiviert z.B. das Aufteilen in Abschnitte:

SET 'HTTP(CHUNK=ON)'

Wenn die CHUNK-Option nicht angegeben ist, ist das Standardverhalten AUTO. Wenn eine in Abschnitte aufgeteilte Anforderung im AUTO-Modus mit dem Status 505 (HTTP Version Not Supported - HTTP-Version nicht unterstützt) , mit 501 (Not Implemented - Nicht implementiert) oder mit 411 (Length Required - Länge erforderlich) fehlschlägt, wiederholt der Client die Anforderung ohne eine in Abschnitte aufgeteilte Übertragungskodierung.

Definieren Sie die CHUNK-Option mit OFF (keine Aufteilung), wenn der HTTP-Server in Abschnitte aufgeteilte übertragungskodierte Anforderungen nicht unterstützt.

Da der CHUNK-Modus die Übertragungskodierung ab HTTP-Version 1.1 unterstützt, erfordert die Definition von CHUNK mit ON, dass die Version (VER) auf 1.1 oder gar nicht gesetzt wird. Im letzten Fall wird 1.1 als die Standardversion verwendet.

' HTTP(VER[SION]=ver)' (HTTP oder SOAP) Mit dieser Option können Sie die Version des HTTP-Protokolls angeben, das für das Format der HTTP-Nachricht verwendet wird. Beispiel: Die folgende SET-Klausel setzt die HTTP-Version auf 1.1:

SET 'HTTP(VERSION=1.1)'

Mögliche Werte sind 1.0 und 1.1. Wenn VERSION nicht angegeben ist:

Wenn CHUNK auf ON gesetzt ist, wird die HTTP-Version 1.1 verwendet.
Wenn CHUNK auf OFF gesetzt ist, wird die HTTP-Version 1.0 verwendet.
Wenn CHUNK auf AUTO gesetzt ist, wird entweder 1.0 oder 1.1 verwendet, abhängig davon, ob der Client im CHUNK-Modus sendet.

' SOAP(OP[ERATION]=soap_Vorgangsname) (Nur SOAP) Mit dieser Option können Sie den Namen des SOAP-Vorgangs angeben, falls er sich vom Namen der von Ihnen erstellten Prozedur unterscheidet. Der Wert für OPERATION ist mit dem Namen eines entfernten Prozeduraufrufs vergleichbar. Beispiel: Wenn Sie eine Prozedur mit dem Namen accounts_login erstellen wollen, die einen SOAP-Vorgang mit dem Namen login aufruft, geben Sie in etwa Folgendes ein:

CREATE PROCEDURE accounts_login( name LONG VARCHAR, pwd LONG VARCHAR ) SET 'SOAP(OPERATION=login)'

Wenn die OPERATION-Option nicht angegeben ist, muss der Name des SOAP-Vorgangs mit dem Namen der Prozedur übereinstimmen, die Sie erstellen.

Die folgende Anweisung zeigt, wie mehrere Protokolloption-Einstellungen in derselben SET-Klausel kombiniert werden:

CREATE PROCEDURE accounts_login( 
      name LONG VARCHAR, 
      pwd LONG VARCHAR )
   SET 'HTTP ( CHUNK=ON; VERSION=1.1 ), SOAP( OPERATION=login )' 
   ...

SOAPHEADER-Klausel (Nur SOAP-Format) Wenn Sie einen SOAP-Webdienst als Prozedur deklarieren, verwenden Sie diese Klausel, um einen oder mehrere Headereinträge der SOAP-Anforderung anzugeben. Ein SOAP-Header kann als statische Konstante deklariert oder dynamisch mithilfe des Parameterersetzungsmechanismus (IN-, OUT- oder INOUT-Parameter für hd1, hd2 etc. deklarieren) gesetzt werden. Eine Webdienstprozedur kann einen oder mehrere IN-Modus-Ersetzungsparameter und einen einzigen INOUT- oder OUT-Ersetzungsparameter definieren.

Das folgende Beispiel zeigt, wie ein Client das Senden von mehreren Headereinträgen mit Parametern und das Empfangen der Antwort-SOAP-Header-Daten angeben kann:

CREATE PROCEDURE soap_client
  (INOUT hd1 LONG VARCHAR, IN hd2 LONG VARCHAR, IN hd3 LONG VARCHAR) 
  URL 'localhost/some_endpoint' 
  SOAPHEADER '!hd1!hd2!hd3';

Weitere Hinweise zur Verwendung von SOAP-Headern finden Sie unter Praktische Einführung: Verwenden von SQL Anywhere für den Zugriff auf einen SOAP/DISH-Dienst.

Weitere Hinweise zu Ersetzungsparametern finden Sie unter HTTP- und SOAP-Anforderungsstrukturen.

NAMESPACE-Klausel (Nur SOAP-Format) Diese Klausel kennzeichnet den Methoden-Namespace, der üblicherweise sowohl bei SOAP:RPC- als auch bei SOAP:DOC-Anforderungen erforderlich ist. Der die Anforderung verarbeitende SOAP-Server verwendet diesen Namespace, um die Namen von Entitäten im Hauptteil der SOAP-Anforderung zu interpretieren. Der Namespace kann anhand der WSDL-Beschreibung (WSDL = Web Services Description Language) des SOAP-Diensts ermittelt werden, die der Webdienstserver zur Verfügung stellt. Der Standardwert ist die URL der Prozedur bis zur optionalen Pfadkomponente (die aber nicht eingeschlossen ist). Weitere Hinweise zur Verwendung von SOAP-Namespaces finden Sie unter Mit strukturierten Datentypen arbeiten (nur SOAP).

Weitere Hinweise zum Erstellen von Webdiensten sowie Beispiele finden Sie unter SQL Anywhere als HTTP-Webserver verwenden.

Parameterwerte werden als Teil der Anforderung weitergegeben. Die verwendete Syntax hängt vom Typ der Anforderung ab. Bei HTTP:GET werden die Parameter als Teil der URL weitergegeben. Bei HTTP:POST-Anforderungen werden die Werte in den Hauptteil der Anforderung platziert. Parameter von SOAP-Anforderungen werden immer im Anforderungshauptteil gebündelt.

RESOURCE-Datenbankberechtigung ist erforderlich.

Sie müssen über DBA-Berechtigungen verfügen, um eine Prozedur für einen anderen Benutzer erstellen zu können.

Automatisches Festschreiben (Autocommit).

SQL/2008 Erweiterung des Herstellers.
Transact-SQL Wird von Adaptive Server Enterprise nicht unterstützt.

Mit dem folgenden Beispiel wird eine Webdienst-Clientprozedur namens FtoC erstellt.

CREATE PROCEDURE FtoC( IN temperature FLOAT,
    INOUT inoutheader LONG VARCHAR,
    IN inheader LONG VARCHAR )
  URL 'http://localhost:8082/FtoCService'
  TYPE 'SOAP:DOC'
  SOAPHEADER '!inoutheader!inheader';

CREATE PROCEDURE-Anweisung (Webclients)

Syntax

Parameter

Bemerkungen

Berechtigungen

Nebenwirkungen

Siehe auch

Standards und Kompatibilität

Beispiel