Web-Dienstaufrufe

Allgemeine Informationen

Alle API-Methoden werden in Form von Webdiensten dargestellt. Dadurch können Sie alle Adobe Campaign-Funktionen über SOAP-Aufrufe verwalten, die den nativen Einstiegspunkt des Adobe Campaign-Anwendungsservers bilden. Die Adobe Campaign-Konsole selbst verwendet nur SOAP-Aufrufe.

Mit Webdiensten können Sie viele Anwendungen aus einem Drittanbietersystem erstellen:

  • synchrone Warnhinweise, Benachrichtigungen und Ausführung von Versandvorlagen in Echtzeit von einem Back-Office- oder Transaktionssystem aus;
  • Entwicklung spezieller Schnittstellen mit vereinfachter Funktionalität (Webschnittstellen usw.),
  • Fütterung und Suche von Daten in der Datenbank unter Beachtung von Handelsregeln und isoliert von dem zugrunde liegenden physischen Modell.

Definition von Webdiensten

Die Definition der auf dem Adobe Campaign-Anwendungsserver implementierten Webdienste ist in den Datenschemata verfügbar.

Ein Webdienst wird in der Grammatik der Datenschemata beschrieben und ist im Abschnitt <methods> -Element.

<methods>
  <method name="GenerateForm" static="true">
    <help>Generates the form in Mail or Web mode</help>
    <parameters>
      <param name="formName" type="string" desc="Name of form"/>
      <param name="mailMode" type="boolean" desc="Generate a form of type Mail"/>
      <param name="result" type="string" inout="out" desc="Result "/>
    </parameters>
  </method>
</methods>

Hier haben wir ein Beispiel für die Definition der Methode namens GenerateForm.

Die Beschreibung des Dienstes beginnt mit der <method> -Element. Die Liste der Parameter der Methode wird aus dem <parameters> -Element. Jeder Parameter wird durch einen Namen, einen Typ (Boolesch, Zeichenfolge, DOMElement usw.) und eine Beschreibung. Mit dem Attribut "inout"mit dem Wert "out"können Sie angeben, dass sich der Parameter "result"in der SOAP-Aufrufausgabe befindet.

Das Attribut "static"(mit dem Wert "true") beschreibt diese Methode als statisch, d. h., alle Parameter der Methode müssen deklariert werden.

Eine "const"-Methode hat implizit ein XML-Dokument im Format seines zugehörigen Schemas als Eingabe.

Eine vollständige Beschreibung der <method> -Element eines Adobe Campaign-Schemas ist im Kapitel "Schemaverweise"unter Methode

Beispiel der Methode "const"-type "ExecuteQuery" aus dem Schema "xtk:queryDef":

<method name="ExecuteQuery" const="true">
  <help>Retrieve data from a query</help>
  <parameters>
    <param desc="Output xml document" name="output" type="DOMDocument" inout="out"/>
  </parameters>
</method>

Der Eingabeparameter dieser Methode ist ein XML-Dokument im Format des Schemas "xtk:queryDef".

Webdienstbeschreibung: WSDL

Für jeden Dienst ist eine WSDL-Datei (Web Service Description Library) verfügbar. Diese XML-Datei verwendet eine Metalsprache, um den Dienst zu beschreiben und die verfügbaren Methoden, Parameter und den Server anzugeben, die für die Ausführung des Dienstes kontaktiert werden sollen.

WSDL-Dateigenerierung

Um eine WSDL-Datei zu generieren, müssen Sie die folgende URL in einem Webbrowser eingeben:

https://<server>/nl/jsp/schemawsdl.jsp?schema=<schema>

Mit:

  • <server>: der Adobe Campaign-Anwendungsserver (nlserver web)
  • <schema>: Schemaidentifizierungsschlüssel (namespace:schema_name)

Beispiel für die Methode 'ExecuteQuery' des Schemas 'xtk:queryDef'

Die WSDL-Datei wird über die URL generiert:

https://localhost/nl/jsp/schemawsdl.jsp?schema=xtk:queryDef

Eine WSDL-Beschreibung beginnt mit der Definition der Typen, die zum Erstellen von Nachrichten verwendet werden, die mit "Ports"verknüpft sind, die mit einem Protokoll verbunden sind, indem "Bindungen"Webdienste bilden.

Typen

Typdefinitionen basieren auf XML-Schemata. In unserem Beispiel nimmt die Methode "ExecuteQuery"eine Zeichenfolge "s:string"und ein XML-Dokument (<s:complextype>) als Parameter. Der Rückgabewert der Methode ("ExecuteQueryResponse") ist ein XML-Dokument ( <s:complextype>).

<types>
<s:schema elementFormDefault="qualified" targetNamespace="urn:xtk:queryDef">
  <s:element name="ExecuteQuery">
    <s:complexType>
      <s:sequence>
        <s:element maxOccurs="1" minOccurs="1" name="sessiontoken" type="s:string"/>
        <s:element maxOccurs="1" minOccurs="1" name="entity">
          <s:complexType>
            <s:sequence>
              <s:any/>
            </s:sequence>
          </s:complexType>
        </s:element>
      </s:sequence>
    </s:complexType>
  </s:element>
  <s:element name="ExecuteQueryResponse">
    <s:complexType>
      <s:sequence>
        <s:element maxOccurs="1" minOccurs="1" name="pdomOutput">
          <s:complexType mixed="true">
            <s:sequence>
              <s:any/>
            </s:sequence>
          </s:complexType>
        </s:element>
      </s:sequence>
    </s:complexType>
  </s:element>

Nachrichten

Die <message> beschreibt die Namen und Typen eines Satzes von zu sendenden Feldern. Die Methode verwendet zwei Nachrichten, die als Parameter ("ExecuteQueryIn") und als Rückgabewert ("ExecuteQueryOut") übergeben werden.

<message name="ExecuteQueryIn">
  <part element="tns:ExecuteQuery" name="parameters"/>
</message>

<message name="ExecuteQueryOut">
  <part element="tns:ExecuteQueryResponse" name="parameters"/>
</message> 

PortType

Die <porttype> verknüpft die Nachrichten des Vorgangs "ExecuteQuery", der durch die Abfrage ("input") ausgelöst wird, die eine Antwort ("output") generiert.

<portType name="queryDefMethodsSoap">
  <operation name="ExecuteQuery">
    <input message="tns:ExecuteQueryIn"/>
    <output message="tns:ExecuteQueryOut"/>
  </operation>
</portType>

Bindung

Die <binding> Teil gibt das SOAP-Kommunikationsprotokoll ( <soap:binding> ), Datenübertragung über HTTP (Wert des Attributs "transport") und Datenformat für den Vorgang "ExecuteQuery". Der Textkörper des SOAP-Umschlags enthält die Nachrichtensegmente direkt ohne Umwandlung.

<binding name="queryDefMethodsSoap" type="tns:queryDefMethodsSoap">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
  <operation name="ExecuteQuery">
    <soap:operation soapAction="xtk:queryDef#ExecuteQuery" style="document"/>
    <input>
      <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:xtk:queryDef" use="literal"/>
    </input>
    <output>
      <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:xtk:queryDef" use="literal"/>
    </output>
  </operation>
</binding>

Service

Die <service> -Teil beschreibt den Dienst "XtkQueryDef"mit seinem URI auf der URL des Adobe Campaign-Anwendungsservers.

<service name="XtkQueryDef">
  <port binding="tns:queryDefMethodsSoap" name="queryDefMethodsSoap">
    <soap:address location="https://localhost/nl/jsp/soaprouter.jsp"/>
  </port>
</service>

Konnektivität

Adobe Campaign hat die Authentifizierungsmechanismen durch Einführung von Sicherheitszonen und Sitzungsverwaltungseinstellungen.

Es stehen zwei Authentifizierungsmodi zur Verfügung:

  • über einen Aufruf der Anmeldemethode(). Dieser Modus generiert ein Sitzungstoken und ein Sicherheits-Token. Dies ist der sicherste Modus und daher der am besten empfohlene.

oder

  • über Adobe Campaign Login + Passwort , das ein Sitzungstoken erstellt. Das Sitzungstoken läuft nach einem festgelegten Zeitraum automatisch ab. Dieser Modus wird nicht empfohlen und erfordert eine Reduzierung der Sicherheitseinstellungen der Anwendung für einige Zoneneinstellungen (allowUserPassword="true" und sessionTokenOnly="true").

Eigenschaften des Sitzungstokens

Das Sitzungstoken weist die folgenden Merkmale auf:

  • X-Stunden-Lebenszyklus (der Lebenszyklus ist in der Datei "serverConf.xml"konfigurierbar, der Standardzeitraum beträgt 24 Stunden)

  • eine zufällige Konstruktion (sie enthält nicht mehr die Benutzeranmeldung und das Kennwort)

  • beim Zugriff über das Internet:

    • wird das Sitzungs-Token zu einem permanenten Token, es wird nicht mehr zerstört, sobald der Browser geschlossen wird.
    • es wird in einem HTTP-NUR-Cookie platziert (Cookies müssen für Benutzer aktiviert werden)

Eigenschaften des Sicherheits-Tokens

Das Security-Token weist die folgenden Merkmale auf:

  • wird aus dem Sitzungstoken generiert

  • Er verfügt über einen Lebenszyklus von 24 Stunden (konfigurierbar in der Datei "serverConf.xml", der Standardzeitraum beträgt 24 Stunden).

  • wird in der Adobe Campaign-Konsole gespeichert

  • beim Zugriff über das Internet:

    • in einem Dokument gespeichert.__securityToken-Eigenschaft
    • die Seiten-URLs aktualisiert werden, um das Sicherheits-Token zu aktualisieren
    • die Formulare auch über ein ausgeblendetes Feld mit dem Token aktualisiert werden

Bewegung des Sicherheits-Tokens

Der Zugriff über die Konsole erfolgt wie folgt:

  • wird in der Anmeldeantwort übertragen (im HTTP-Header)
  • wird in jeder Abfrage verwendet (im HTTP-Header)

Von einer POST und GET HTTP:

  • der Server schließt die Links mit dem Token ab
  • Der Server fügt ein ausgeblendetes Feld zu Formularen hinzu

Aus einem SOAP-Aufruf:

  • wird hinzugefügt, um Kopfzeilen aufzurufen

Aufrufbeispiele

  • Verwenden HttpSoapConnection/SoapService:
  
    var cnx = new HttpSoapConnection("https://serverURL/nl/jsp/soaprouter.jsp");
  var session = new SoapService(cnx, 'urn:xtk:session');
  session.addMethod("Logon", "xtk:session#Logon",
                      ["sessiontoken", "string", "Login", "string", "Password", "string", "Parameters", "NLElement"],
                      ["sessionToken", "string", "sessionInfo", "NLElement", "securityToken", "string"]);
  
  var res = session.Logon("", "admin", "pwd", <param/>);
  var sessionToken = res[0];
  var securityToken = res[2];
  
  cnx.addTokens(sessionToken, securityToken);
  var query = new SoapService(cnx, 'urn:xtk:queryDef');
  query.addMethod("ExecuteQuery", "xtk:queryDef#ExecuteQuery",
                      ["sessiontoken", "string", "entity", "NLElement"],
                      ["res", "NLElement"]);
  
  var queryRes = query.ExecuteQuery("", <queryDef operation="select" schema="nms:recipient">
            <select>
              <node expr="@email"/>
              <node expr="@lastName"/>
              <node expr="@firstName"/>
            </select>
            <where>
              <condition expr="@email = 'joe.doe@aol.com'"/>
            </where>
          </queryDef>);
  logInfo(queryRes[0].toXMLString())
  • Verwenden HttpServletRequest:
HINWEIS

Die in den folgenden URLs verwendeten URLs HttpServletRequest -Aufrufe müssen im Abschnitt "URL-Berechtigungen"der serverConf.xml -Datei. Dies gilt auch für die URL des Servers selbst.

Logon execution():

var req = new HttpClientRequest("https://serverURL/nl/jsp/soaprouter.jsp");
req.header["Content-Type"] = "text/xml; charset=utf-8";
req.header["SOAPAction"] =   "xtk:session#Logon";
req.method = "POST";
req.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:session">' +
    '<soapenv:Header/>' +
    '<soapenv:Body>' +
        '<urn:Logon>' +
            '<urn:sessiontoken></urn:sessiontoken>' +
            '<urn:strLogin>LOGIN_HERE</urn:strLogin>' +
            '<urn:strPassword>PASSWORD_HERE</urn:strPassword>' +
            '<urn:elemParameters></urn:elemParameters>' +
        '</urn:Logon>' +
    '</soapenv:Body>' +
'</soapenv:Envelope>';
req.execute();
           
var resp = req.response;
var xmlRes = new XML(String(resp.body).replace("<?xml version='1.0'?>",""));
var sessionToken = String(xmlRes..*::pstrSessionToken);;
var securityToken = String(xmlRes..*::pstrSecurityToken);

Ausführung der Abfrage:

var req2 = new HttpClientRequest("https://serverURL/nl/jsp/soaprouter.jsp");
req2.header["Content-Type"] = "text/xml; charset=utf-8";
req2.header["SOAPAction"] =   "xtk:queryDef#ExecuteQuery";req2.header["X-Security-Token"] = securityToken;
req2.header["cookie"]           = "__sessiontoken="+sessionToken;
req2.method = "POST";
req2.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:queryDef">' +
             '<soapenv:Header/><soapenv:Body><urn:ExecuteQuery><urn:sessiontoken/><urn:entity>' +
                '<queryDef operation="select" schema="nms:recipient">' +
                  '<select><node expr="@email"/><node expr="@lastName"/><node expr="@firstName"/></select>' +
                  '<where><condition expr="@email = \'john.doe@aol.com\'"/></where>' +
                '</queryDef>' +
           '</urn:entity></urn:ExecuteQuery></soapenv:Body></soapenv:Envelope>';
req2.execute();
var resp2 = req2.response;
logInfo(resp2.body)

Auf dieser Seite