Erstellt eine Webclient-Funktion, die eine HTTP- oder SOAP-über-HTTP-Anforderung durchführt. Hinweise zum Erstellen einer benutzerdefinierten SQL-Funktion finden Sie unter CREATE FUNCTION-Anweisung.
SyntaxCREATE [ OR REPLACE ] FUNCTION [ Eigentümer.]Funktionsname ( [ Parameter, ... ] ) RETURNS Datentyp URL URL-Zeichenfolge [ HEADER Header-Zeichenfolge ] [ SOAPHEADER SOAP-Header-Zeichenfolge ] [ TYPE { 'HTTP[ :{ GET | POST[:MIME-Typ ] | PUT[:MIME-Typ ] | DELETE | HEAD } ]' | 'SOAP[:{ RPC | DOC } ]' } ] [ NAMESPACE Namespace-Zeichenfolge ] [ CERTIFICATE Zertifikat-Zeichenfolge ] [ CLIENTPORT Clientport-Zeichenfolge ] [ PROXY Proxy-Zeichenfolge ] [ SET Protokolloption-Zeichenfolge ]
URL-Zeichenfolge : '{ HTTP | HTTPS | HTTPS_FIPS }://[Benutzer:Kennwort@]Hostname[:Port][/Pfad]'
Parameter : [ IN ] Parametername Datentyp [ DEFAULT Ausdruck ]
ParameterCREATE FUNCTION Parameternamen müssen den Regeln für Datenbankbezeichner folgen. Sie müssen einen gültigen SQL-Datentyp umfassen und das Schlüsselwort IN kann vorangestellt werden. Dieses Präfix weist darauf hin, dass das Argument ein Ausdruck ist, welcher der Funktion einen Wert zur Verfügung stellt.
Wenn Funktionen ausgeführt werden, müssen nicht alle Parameter angegeben werden. Wenn in der CREATE FUNCTION-Anweisung ein Standardwert bereitgestellt wird, werden den fehlenden Parametern die Standardwerte zugeordnet. Falls kein Argument vom Aufrufer angegeben wurde und kein Standardwert gesetzt ist, wird ein Fehler ausgegeben.
Wenn Sie OR REPLACE (CREATE OR REPLACE FUNCTION) angeben, wird eine neue Funktion erstellt oder eine bestehende Funktion mit demselben Namen ersetzt. Diese Klausel ändert die Definition der Funktion, lässt aber bestehende Berechtigungen unberührt. Sie können die OR REPLACE-Klausel nicht mit temporären Funktionen verwenden.
RETURNS-Klausel Geben Sie einen der folgenden Werte an, um den Rückgabetyp für die SOAP- oder HTTP-Funktion zu definieren:
Der zurückgegebene Wert ist der Hauptteil der HTTP-Antwort. Es werden keine HTTP-Headerinformationen aufgenommen. Wenn weitere Informationen wie z.B. Statusinformationen benötigt werden, verwenden Sie eine Prozedur statt einer Funktion.
Der Datentyp hat keinen Einfluss auf die Verarbeitung der HTTP-Antwort.
URL-Klausel Wird nur verwendet, wenn Sie eine Clientfunktion für HTTP- oder SOAP-Webdienste festlegen. Gibt die URL 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.
Die Angabe von HTTPS_FIPS zwingt das System, die FIPS-Bibliotheken zu verwenden. Wenn HTTPS_FIPS angegeben wird, aber keine FIPS-Bibliotheken vorhanden sind, werden stattdessen Nicht-FIPS-Bibliotheken verwendet.
HEADER-Klausel Wenn Sie HTTP-Webdienst-Clientfunktionen erstellen, verwenden Sie diese Klausel, um Headereinträge der HTTP-Anforderung hinzuzufügen oder zu ändern. Für HTTP-Header können nur druckbare ASCII-Zeichen angegeben werden, deren Groß- und Kleinschreibung nicht berücksichtigt wird. Weitere Hinweise zur Verwendung dieser Klausel finden Sie unter der HEADER-Klausel der CREATE PROCEDURE-Anweisung (Webclients).
Weitere Hinweise zur Verwendung von HTTP-Headern finden Sie unter HTTP-Anforderungsheader verwalten.
SOAPHEADER-Klausel Wenn Sie einen SOAP-Webdienst als Funktion 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 Webdienstfunktion kann einen oder mehrere IN-Modus-Ersetzungsparameter definieren, aber keinen INOUT- oder OUT-Ersetzungsparameter. Weitere Hinweise zur Verwendung dieser Klausel finden Sie unter der SOAPHEADER-Klausel der CREATE PROCEDURE-Anweisung (Webclients).
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.
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 Funktion erfolgt, nachdem Parameterersetzungen verarbeitet wurden, darf kein oder nur ein einziger Parameter verbleiben. Der Aufruf einer Webdienstfunktion 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:
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 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 konfigurieren, der das Beispiel put_data.sql ausführt:
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 konfigurieren, der das Beispiel put_data.sql ausführt:
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.
NAMESPACE-Klausel Gilt nur für SOAP-Clientfunktionen. 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 Funktion bis zur optionalen Pfadkomponente (die aber nicht eingeschlossen ist).
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-Clientfunktion mithilfe von TCP/IP kommuniziert. Sie steht für Verbindungen zur Verfügung, die durch ein Firewall-Schutzsystem geleitet werden, da Firewalls entsprechend dem TCP/UDP-Port Filter anwenden. Die Klausel ist nur in diesem Fall empfehlenswert. 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. Diese Klausel zeigt an, dass die Funktion 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 FUNCTION 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 FUNCTION accounts_login(
name LONG VARCHAR,
pwd LONG VARCHAR )
SET 'HTTP ( CHUNK=ON; VERSION=1.1 ), SOAP( OPERATION=login )'
... |
BemerkungenDie CREATE FUNCTION-Anweisung erstellt eine Webdienstfunktion in der Datenbank. Eine Funktion kann für einen anderen Benutzer erstellt werden, indem der Name eines Eigentümers angegeben wird.
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.
BerechtigungenRESOURCE-Berechtigung.
DBA-Berechtigung für externe Funktionen, einschließlich Java-Funktionen.
NebenwirkungenAutomatisches Festschreiben (Autocommit).
Siehe auch Standards und KompatibilitätSQL/2008 Erweiterung des Herstellers.
Transact-SQL Wird von Adaptive Server Enterprise nicht unterstützt.
BeispieleDie folgende Anweisung erstellt eine Funktion namens cli_test1, die Bilder aus dem auf localhost ausgeführten get_picture-Dienst zurückgibt:
CREATE FUNCTION cli_test1( image LONG VARCHAR ) RETURNS LONG BINARY URL 'http://localhost/get_picture' TYPE 'HTTP:GET'; |
Die folgende Anweisung gibt eine HTTP-Anforderung aus mit der URL http://localhost/get_picture?image=widget:
SELECT cli_test1( 'widget' ); |
Die folgende Anweisung verwendet einen Ersetzungsparameter, damit die Anforderungs-URL als Eingabeparameter übergeben werden kann. Die SET-Klausel wird verwendet, um den CHUNK-Modus für die Übertragungskodierung zu deaktivieren.
CREATE FUNCTION cli_test2( image LONG VARCHAR, myurl LONG VARCHAR ) RETURNS LONG BINARY URL '!myurl' TYPE 'HTTP:GET' SET 'HTTP(CH=OFF)' HEADER 'ASA-ID'; |
Die folgende Anweisung gibt eine HTTP-Anforderung aus mit der URL http://localhost/get_picture?image=widget:
CREATE VARIABLE a_binary LONG BINARY
a_binary = cli_test2('widget', 'http://localhost/get_picture');
SELECT a_binary; |
 |
Kommentieren Sie diese Seite in DocCommentXchange.
|
Copyright © 2010, iAnywhere Solutions, Inc. - SQL Anywhere 12.0.0 |