Informazioni sui servizi web

Definizione di API Adobe Campaign

Il server delle applicazioni Adobe Campaign è stato progettato per garantire l'apertura e la facilità di integrazione con sistemi informativi aziendali sempre più diversificati e complessi.

le API Adobe Campaign vengono utilizzate in JavaScript all'interno dell'applicazione e in SOAP all'esterno. Costituiscono una libreria di funzioni generiche che possono essere arricchite. Per ulteriori informazioni, fare riferimento a Implementazione di metodi SOAP.

Prerequisiti

Prima di utilizzare le API Adobe Campaign , è necessario avere familiarità con i seguenti argomenti:

• Javascript
• Protocollo SOAP
• modello dati Adobe Campaign

Utilizzo API Adobe Campaign

Adobe Campaign utilizza due tipi di API:

• API di accesso ai dati generici per la query dei dati del modello dati. Fare riferimento a API orientate ai dati.
• API specifiche per le aziende che consentono di agire su ciascun oggetto: consegne, flussi di lavoro, iscrizioni ecc. Fare riferimento a API orientate agli affari.

Per sviluppare le API e interagire con Adobe Campaign, è necessario avere familiarità con il modello dati. Adobe Campaign consente di generare una descrizione completa della base. Fare riferimento a Descrizione del modello.

Chiamate SOAP

Il protocollo SOAP consente di invocare metodi API tramite il client avanzato, applicazioni di terze parti che utilizzano servizi Web o JSP utilizzando questi metodi in modo nativo.

La struttura di un messaggio SOAP è la seguente:

• un involucro che definisce la struttura del messaggio,
• un'intestazione opzionale,
• un organismo contenente le informazioni sulla chiamata e la risposta,
• gestione degli errori che definisce la condizione di errore.

Risorse e scambi

Lo schema seguente mostra le varie risorse coinvolte nell'utilizzo delle API Adobe Campaign:

Esempio di messaggio SOAP sul metodo 'ExecuteQuery'

In questo esempio, una query SOAP richiama il metodo "ExecuteQuery", che considera una stringa di caratteri come parametro per l'autenticazione (token sessione) e un contenuto XML per la descrizione della query da eseguire.

Per ulteriori informazioni, fare riferimento a ExecuteQuery (xtk:queryDef).

Query SOAP

<?xml version='1.0' encoding='ISO-8859-1'?>
  <SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
    <SOAP-ENV:Body>
      <ExecuteQuery xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
        <__sessiontoken xsi:type='xsd:string'/>
        <entity xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>
          <queryDef firstRows="true" lineCount="200" operation="select" schema="nms:rcpGrpRel" startLine="0" startPath="/" xtkschema="xtk:queryDef">
          ...
          </queryDef>
        </entity>
      </ExecuteQuery>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

L'elemento <soap-env:envelope> è il primo elemento del messaggio che rappresenta la busta SOAP.

L'elemento <soap-env:body> è il primo elemento secondario dell'involucro. Contiene la descrizione del messaggio, ovvero il contenuto della query o la risposta.

Il metodo da invocare viene immesso nell'elemento <executequery> dal corpo del messaggio SOAP.

In SOAP, i parametri sono riconosciuti dall'ordine di aspetto. Il primo parametro, <__sessiontoken>, prende la catena di autenticazione, il secondo parametro è la descrizione XML della query dall'elemento <querydef>.

Risposta SOAP

<?xml version='1.0' encoding='ISO-8859-1'?>
  <SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
    <SOAP-ENV:Body>
      <ExecuteQueryResponse xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
        <pdomOutput xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>
          <rcpGrpRel-collection><rcpGrpRel group-id="1872" recipient-id="1362"></rcpGrpRel></rcpGrpRel-collection>
        </pdomOutput>
      </ExecuteQueryResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Il risultato della query viene immesso dall'elemento <pdomoutput>.

Gestione errori

Esempio di risposta di errore SOAP:

<?xml version='1.0' encoding='ISO-8859-1'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Server</faultcode>
      <faultstring>Error while executing 'Write' of the 'xtk:persist'.</faultstring> service
      <detail>ODBC error: [Microsoft][ODBC SQL Server Driver][SQL Server]Cannot insert duplicate key row in object 'XtkOption' with unique index 'XtkOption_name'. SQLSTate: 23000
ODBC error: [Microsoft][ODBC SQL Server Driver][SQL Server]The statement has been terminated. SQLSTate: 01000 Cannot save the 'Options (xtk:option)' document </detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

L'elemento <soap-env:fault> nel corpo del messaggio SOAP viene utilizzato per trasmettere i segnali di errore generati durante l'elaborazione del servizio Web. È composta dai seguenti sottoelementi:

• <faultcode> : indica il tipo di errore. I tipi di errore sono:

  • "VersionMismatch" in caso di incompatibilità con la versione SOAP utilizzata,
  • "mustUnderstand" in caso di problemi nell'intestazione del messaggio,
  • "Client" nel caso in cui al client manchino alcune informazioni,
  • "Server" nel caso in cui il server abbia un problema durante l'esecuzione dell'elaborazione.

• <faultstring> : messaggio che descrive l'errore

• <detail> : long error message

Il successo o il fallimento della chiamata del servizio viene identificato quando l'elemento <faultcode> viene verificato.

Esempio di gestione degli errori in C#:

try 
{
  // Invocation of method
  ...
}
catch (SoapException e)
{
  System.Console.WriteLine("Soap exception: " + e.Message);        
  if (e.Detail != null)
    System.Console.WriteLine(e.Detail.InnerText);
}

URL del server del servizio Web (o di EndPoint)

Per inviare il servizio Web, è necessario contattare il server Adobe Campaign che implementa il metodo di servizio corrispondente.

L'URL del server è il seguente:

https://serverName/nl/jsp/soaprouter.jsp

Con <server> il server applicazione Adobe Campaign (nlserver web).