Header der SOAP-Anforderung verwalten

Bei dem Header einer SOAP-Anforderung handelt es sich um ein XML-Fragment innerhalb des SOAP-Envelope. Während der SOAP-Vorgang und seine Parametern auch als RPC (Remote Procedure Call) betrachtet werden können, kann der Header einer SOAP-Anforderung verwendet werden, um Metadaten in einer spezifischen Anforderung oder Antwort zu übertragen. Die Header einer SOAP-Anforderung übertragen Metadaten wie etwa Autorisierungs- oder Sitzungskriterien.

Der Wert einer SOAPHEADER-Klausel muss ein gültiges XML-Fragment sein, das einem Headereintrag der SOAP-Anforderung entspricht. Es können mehrere Headereinträge für eine SOAP-Anforderung angegeben werden. Die gespeicherte Prozedur oder Funktion injiziert automatisch die Headereinträge der SOAP-Anforderung innerhalb eines SOAP-Headerelements (SOAP-ENV:Header). SOAPHEADER-Werte geben SOAP-Header an, die als statische Konstante deklariert oder dynamisch mithilfe des Parameterersetzungsmechanismus festgelegt werden können. Nachstehend wird ein Fragment aus einer SOAP-Anforderung gezeigt. Es enthält zwei XML-Header namens Authentication und Session.

<?xml version="1.0"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:m="HTTP://localhost:8082">
  <SOAP-ENV:Header>
    <Authentication xmlns="CustomerOrderURN">
      <userName pwd="none" mustUnderstand="1">
        <first>John</first>
        <last>Smith</last>
      </userName>
    </Authentication>
    <Session xmlns="SomeSession">123456789</Session>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <m:SoapOperation>
      <m:intVariable>123</m:intVariable>
      <m:charVariable>data</m:charVariable>
    </m:SoapOperation>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP-Antwort-Header (zurückgegeben vom SOAP-Aufruf) werden für Prozeduren und Funktionen unterschiedlich verarbeitet. Bei Verwendung einer Funktion, was die flexibelste und empfohlene Methode darstellt, wird der gesamte SOAP-Antwortrahmen empfangen. Der Antwort-Envelope kann dann mit dem OPENXML-Operator verarbeitet werden, um SOAP-Header und SOAP-Hauptteildaten zu extrahieren. Bei Verwendung einer Prozedur können SOAP-Antwort-Header nur durch einen Ersetzungsparameter extrahiert werden, der einer IN- oder INOUT-Variable zugeordnet ist. In einer SOAP-Prozedur sind maximal ein IN- oder INOUT-Parameter zulässig.

Eine Webdienstfunktion muss den SOAP-Antwortrahmen syntaktisch analysieren, um die Header-Einträge zu erhalten.

Beispiele

Die folgenden Beispiele veranschaulichen das Erstellen von SOAP-Prozeduren und -Funktionen, die Parameter und SOAP-Header senden. Wrapper-Prozeduren werden verwendet, um die Aufrufe für Webdienstprozeduren zu füllen und die Antworten zu verarbeiten. Die soapAddItemProc-Prozedur veranschaulicht die Verwendung einer SOAP-Webdienstprozedur, die soapAddItemFunc-Funktion veranschaulicht die Verwendung einer SOAP-Webdienstfunktion und die httpAddItemFunc-Funktion zeigt, wie die SOAP-Daten an eine HTTP-Webdienstprozedur übergeben werden können.

Das folgende Beispiel zeigt eine SOAP-Clientprozedur, die Substitutionsparameter verwendet, um SOAP-Header zu senden. Ein einzelner INOUT-Parameter wird verwendet, um SOAP-Header zu empfangen. Eine als Wrapper fungierende gespeicherte Prozedur addItemProcWrapper, die soapAddItemProc aufruft, zeigt, wie SOAP-Header einschließlich Parametern gesendet und empfangen werden.

CREATE PROCEDURE soapAddItemProc(amount INT, item LONG VARCHAR, 
        INOUT inoutheader LONG VARCHAR, IN inheader LONG VARCHAR)
    URL 'http://localhost:8082/itemStore'
    SET 'SOAP( OP=addItems )'
    TYPE 'SOAP:DOC'
    SOAPHEADER '!inoutheader!inheader';

CREATE PROCEDURE addItemProcWrapper(amount INT, item LONG VARCHAR, 
        first_name LONG VARCHAR, last_name LONG VARCHAR)
BEGIN
    DECLARE io_header LONG VARCHAR;     // inout (write/read) soap header
    DECLARE resxml LONG VARCHAR;
    DECLARE soap_header_sent LONG VARCHAR;
    DECLARE i_header LONG VARCHAR;      // in (write) only soap header
    DECLARE err int;
    DECLARE crsr CURSOR FOR 
        CALL soapAddItemProc( amount, item, io_header, i_header );

    SET io_header = XMLELEMENT( 'Authentication',
                        XMLATTRIBUTES('CustomerOrderURN' as xmlns),
                        XMLELEMENT('userName', XMLATTRIBUTES(
                                        'none' as pwd,
                                        '1' as mustUnderstand ),
                            XMLELEMENT( 'first', first_name ),
                            XMLELEMENT( 'last', last_name ) ) );
    SET i_header = '<Session xmlns="SomeSession">123456789</Session>';
    SET soap_header_sent = io_header || i_header;
    OPEN crsr;
    FETCH crsr INTO resxml, err;
    CLOSE crsr;

    SELECT resxml, err, soap_header_sent, io_header AS soap_header_received;
END;

/* example call to addItemProcWrapper */
CALL addItemProcWrapper( 5, 'shirt', 'John', 'Smith' );

Das folgende Beispiel zeigt eine SOAP-Clientfunktion, die Substitutionsparameter verwendet, um SOAP-Header zu senden. Ein kompletter SOAP-Antwortrahmen wird zurückgegeben. SOAP-Header können mit dem OPENXML-Operator syntaktisch analysiert werden. Eine als Wrapper fungierende Funktion addItemFuncWrapper, die soapAddItemFunc aufruft, zeigt, wie SOAP-Header einschließlich Parametern gesendet und empfangen werden. Außerdem zeigt sie, wie die Antwort mit dem OPENXML-Operator verarbeitet wird.

CREATE FUNCTION soapAddItemFunc(amount INT, item LONG VARCHAR, 
        IN inheader1 LONG VARCHAR, IN inheader2 LONG VARCHAR )
    RETURNS XML
    URL 'http://localhost:8082/itemStore'
    SET 'SOAP(OP=addItems)'
    TYPE 'SOAP:DOC'
    SOAPHEADER '!inheader1!inheader2';

CREATE PROCEDURE addItemFuncWrapper(amount INT, item LONG VARCHAR, 
        first_name LONG VARCHAR, last_name LONG VARCHAR )
BEGIN
    DECLARE i_header1 LONG VARCHAR;
    DECLARE i_header2 LONG VARCHAR;
    DECLARE res LONG VARCHAR;
    DECLARE ns LONG VARCHAR;
    DECLARE xpath LONG VARCHAR;
    DECLARE header_entry LONG VARCHAR;
    DECLARE localname LONG VARCHAR;
    DECLARE namespaceuri LONG VARCHAR;
    DECLARE r_quantity int;
    DECLARE r_item LONG VARCHAR;
    DECLARE r_status LONG VARCHAR;

    SET i_header1 = XMLELEMENT( 'Authentication',
                        XMLATTRIBUTES('CustomerOrderURN' as xmlns),
                        XMLELEMENT('userName', XMLATTRIBUTES(
                                        'none' as pwd,
                                        '1' as mustUnderstand ),
                            XMLELEMENT( 'first', first_name ),
                            XMLELEMENT( 'last',  last_name ) ) );
    SET i_header2 = '<Session xmlns="SessionURN">123456789</Session>';

    SET res = soapAddItemFunc( amount, item, i_header1, i_header2 );

    SET ns = '<ns xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"'
            || ' xmlns:mp="urn:ianywhere-com:sa-xpath-metaprop"'
            || ' xmlns:customer="CustomerOrderURN"'
            || ' xmlns:session="SessionURN"'
            || ' xmlns:tns="http://localhost:8082"></ns>';

    // Process headers...            
    SET xpath = '//SOAP-ENV:Header/*';
    BEGIN
         DECLARE crsr CURSOR FOR SELECT * FROM
                 OPENXML( res, xpath, 1, ns )
                      WITH (  "header_entry" LONG VARCHAR '@mp:xmltext',
                              "localname"    LONG VARCHAR '@mp:localname',
                              "namespaceuri" LONG VARCHAR '@mp:namespaceuri' );
        OPEN crsr;
        FETCH crsr INTO "header_entry", "localname", "namespaceuri";
        CLOSE crsr;
    END;

    // Process body...
    SET xpath = '//tns:row';
    BEGIN
         DECLARE crsr1 CURSOR FOR SELECT * FROM
                 OPENXML( res, xpath, 1, ns )
                      WITH (  "r_quantity" INT 'tns:quantity/text()',
                              "r_item"     LONG VARCHAR 'tns:item/text()',
                              "r_status"   LONG VARCHAR 'tns:status/text()' );
        OPEN crsr1;
        FETCH crsr1 INTO "r_quantity", "r_item", "r_status";
        CLOSE crsr1;
    END;

    SELECT r_item, r_quantity, r_status, header_entry, localname, namespaceuri;
END;

/* example call to addItemFuncWrapper */
CALL addItemFuncWrapper( 6, 'shorts', 'Jack', 'Smith' );

Das folgende Beispiel zeigt, wie ein HTTP:POST als Transport für eine ganze SOAP-Datenladung verwendet werden kann. Anstatt eine Webdienst-Client-SOAP-Prozedur zu erstellen, erzeugt diese Methode eine Webdienst-HTTP-Prozedur, die die SOAP-Daten transportiert. Eine Wrapper-Prozedur addItemHttpWrapper ruft httpAddItemFunc auf, um die Verwendung der POST-Funktion zu zeigen. Damit wird gezeigt, wie SOAP-Header einschließlich Parametern gesendet und empfangen werden und wie die Antwort akzeptiert wird.

CREATE FUNCTION httpAddItemFunc(soapPayload XML)
    RETURNS XML
    URL 'http://localhost:8082/itemStore'
    TYPE 'HTTP:POST:text/xml'
    HEADER 'SOAPAction: "http://localhost:8082/addItems"';

CREATE PROCEDURE addItemHttpWrapper(amount INT, item LONG VARCHAR)
RESULT(response XML)
BEGIN
    DECLARE payload XML;
    DECLARE response XML;

    SET payload =
'<?xml version="1.0"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:m="http://localhost:8082">
  <SOAP-ENV:Body>
    <m:addItems>
      <m:amount>' || amount || '</m:amount>
      <m:item>' || item || '</m:item>
    </m:addItems>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>';

    SET response = httpAddItemFunc( payload );
    /* process response as demonstrated in addItemFuncWrapper */
    SELECT response;
END;

/* example call to addItemHttpWrapper */
CALL addItemHttpWrapper( 7, 'socks' );

Weitere Hinweise zur serverseitigen Implementierung dieses Beispiels finden Sie unter Zugriff auf vom Client bereitgestellte SOAP-Anforderungsheader.

Einschränkungen

Serverseitige SOAP-Dienste können aktuell keine SOAP-Header-Anforderungen für die Ein- und Ausgabe definieren. Aus diesem Grund sind keine SOAP-Header-Metadaten in der WSDL-Ausgabe eines DISH-Dienstes verfügbar. SOAP-Client-Toolkits können nicht automatisch SOAP-Header-Schnittstellen für einen SQL Anywhere SOAP-Dienstendpunkt generieren.
SOAP-Header-Fehler werden nicht unterstützt.

Kommentieren Sie diese Seite in DocCommentXchange.