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 Element <methods> verfügbar.

<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 finden Sie ein Beispiel für die Definition der Methode GenerateForm.

Die Beschreibung des Dienstes beginnt mit dem Element <method> . Die Liste der Parameter der Methode wird aus dem Element <parameters> ausgefüllt. 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 des Elements <method> eines Adobe Campaign-Schemas finden Sie im Kapitel "Schema references"unter Method

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 an. 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

<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

Der <porttype> verknüpft die Nachrichten mit dem Vorgang "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

Der Teil <binding> gibt das SOAP-Kommunikationsprotokoll ( <soap:binding> ), den Datentransport über HTTP (Wert des Attributs "transport") und das Datenformat für den Vorgang "ExecuteQuery" an. 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

Der Teil <service> 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 Sicherheit für Authentifizierungsmechanismen erhöht, indem Sicherheitszonen und Sitzungsverwaltungseinstellungen eingeführt wurden.

Es stehen zwei Authentifizierungsmodi zur Verfügung:

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

oder

  • über das Adobe Campaign-Login + Kennwort, mit dem ein Sitzungstoken erstellt wird. 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 von 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 von HttpServletRequest:
HINWEIS

Die URLs, die in den folgenden HttpServletRequest -Aufrufen verwendet werden, müssen im Abschnitt "URL-Berechtigungen"der Datei serverConf.xml auf Zulassungsliste sein. 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