v7

Chiamate per servizi web

Informazioni generali

Tutti i metodi API sono presentati sotto forma di servizi web. Questo consente di gestire tutte le funzioni di Adobe Campaign tramite chiamate SOAP, che rappresentano il punto di ingresso nativo del server applicazioni Adobe Campaign. La console Adobe Campaign utilizza solo chiamate SOAP.

I servizi Web consentono di creare molte applicazioni da un sistema di terze parti:

• Avvisi sincroni, notifiche ed esecuzione di modelli di consegna in tempo reale da un back office o da un sistema di transazioni.
• sviluppo di interfacce speciali con funzionalità semplificate (interfacce web, ecc.),
• Invio e ricerca di dati nel database, nel rispetto delle regole commerciali, e isolamento dal modello fisico sottostante.

Definizione di servizi web

La definizione dei servizi Web implementati nel server applicazioni Adobe Campaign è disponibile negli schemi di dati.

Un servizio Web è descritto nella grammatica degli schemi di dati ed è disponibile nella <methods> elemento.

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

Ecco un esempio della definizione del metodo chiamato GenerateForm.

La descrizione del servizio inizia con <method> elemento. L’elenco dei parametri del metodo è completato da <parameters> elemento. Ogni parametro è specificato da un nome, un tipo (booleano, stringa, DOMElement, ecc.) e una descrizione. L’attributo "inout" con il valore "out" consente di specificare che il parametro "result" si trova nell’output della chiamata SOAP.

La presenza dell’attributo "static" (con il valore "true") descrive questo metodo come static, il che significa che tutti i parametri del metodo devono essere dichiarati.

Un metodo "const" ha implicitamente un documento XML nel formato dello schema associato come input.

Una descrizione completa del <method> di uno schema Adobe Campaign è disponibile nel capitolo "Riferimenti schema" in Metodo

Esempio del metodo "ExecuteQuery" di tipo "const" dallo 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>

Il parametro di input di questo metodo è un documento XML in formato "xtk:queryDef".

Descrizione servizio Web: WSDL

Per ogni servizio è disponibile un file WSDL (Web Service Description Library). Questo file XML utilizza un metalinguaggio per descrivere il servizio e specificare i metodi, i parametri e il server disponibili da contattare per l'esecuzione del servizio.

Generazione di file WSDL

Per generare un file WSDL, è necessario immettere l'URL seguente da un browser Web:

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

Con:

• <server>: server applicazioni Adobe Campaign (nlserver web)
• <schema>: chiave di identificazione dello schema (namespace:nome_schema)

Esempio sul metodo 'ExecuteQuery' dello schema 'xtk:queryDef'

Il file WSDL viene generato dall'URL:

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

Una descrizione WSDL inizia definendo i tipi utilizzati per la creazione dei messaggi, associati in "porte", connessi a un protocollo mediante "binding" che formano i servizi Web.

Tipi

Le definizioni dei tipi si basano su schemi XML. Nel nostro esempio, il metodo "ExecuteQuery" accetta una stringa "s:string" e un documento XML (<s:complextype>) come parametri. Il valore restituito dal metodo ("ExecuteQueryResponse") è un documento XML ( <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>

Messaggi

Il <message> descrive i nomi e i tipi di un set di campi da inviare. Il metodo utilizza due messaggi da passare come parametro ("ExecuteQueryIn") e il valore restituito ("ExecuteQueryOut").

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

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

PortType

Il <porttype> associa i messaggi sull'operazione "ExecuteQuery" attivata dalla query ("input") che genera una risposta ("output").

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

Binding

Il <binding> specifica il protocollo di comunicazione SOAP ( <soap:binding> ), il trasporto dei dati in HTTP (valore dell’attributo "transport") e il formato dei dati per l’operazione "ExecuteQuery". Il corpo dell'inviluppo SOAP contiene i segmenti del messaggio direttamente senza trasformazione.

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

Servizio

Il <service> La parte descrive il servizio "XtkQueryDef" con il relativo URI nell'URL del server applicazioni Adobe Campaign.

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

Connettività

Adobe Campaign ha aumentato la sicurezza dei meccanismi di autenticazione introducendo aree di protezione e le impostazioni di gestione delle sessioni.

Sono disponibili due modalità di autenticazione:

• tramite una chiamata a metodi di accesso(). Questa modalità genera un token di sessione e un token di sicurezza. È la modalità più sicura e quindi la più consigliata.

o

• tramite il login e la password di Adobe Campaign che crea un token di sessione. Il token di sessione scade automaticamente dopo un periodo impostato. Questa modalità non è consigliata e richiede la riduzione delle impostazioni di protezione dell'applicazione per alcune impostazioni di zona (allowUserPassword="true" e sessionTokenOnly="true").

Caratteristiche del token di sessione

Il token di sessione presenta le seguenti caratteristiche:

• un ciclo di vita di X ore (il ciclo di vita è configurabile nel file "serverConf.xml"; il periodo predefinito è di 24 ore)

• una costruzione casuale (non contiene più il login utente e la password)

• quando si accede tramite il Web:

  • il token di sessione diventa un token permanente e non viene eliminato una volta chiuso il browser
  • viene inserito in un cookie solo HTTP (i cookie devono essere attivati per gli operatori)

Caratteristiche del token di sicurezza

Il token di sicurezza presenta le seguenti caratteristiche:

• viene generato dal token di sessione

• ha un ciclo di vita di 24 ore (configurabile nel file "serverConf.xml", il periodo predefinito è di 24 ore)

• viene memorizzato nella console Adobe Campaign

• quando si accede tramite il Web:

  • viene memorizzato in un documento.__securityToken, proprietà
  • gli URL della pagina vengono aggiornati per aggiornare il token di sicurezza
  • i moduli vengono aggiornati anche tramite un campo nascosto contenente il token

Spostamento dei token di sicurezza

Se vi si accede tramite la console, si ottiene:

• trasmesse nella risposta di accesso (nell’intestazione HTTP)
• utilizzato in ogni query (nell’intestazione HTTP)

Da un POST e GET HTTP:

• il server completa i collegamenti con il token
• il server aggiunge un campo nascosto ai moduli

Da una chiamata SOAP:

• viene aggiunto alle intestazioni di chiamata

Esempi di chiamata

• Utilizzo di 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())

• Utilizzo di HttpServletRequest:

Esecuzione accesso:

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);

Esecuzione query:

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)

Risorse Business.Adobe.com

Analytics Integration Offer Management Cross Channel Marketing Campaign Management Dynamic Content Email Marketing