Show Menu
ARGOMENTI×

Informazioni sui servizi Web

Definizione delle API di Adobe Campaign

Il server delle applicazioni Adobe Campaign è stato progettato per consentire un'integrazione semplice e aperta con sistemi informativi aziendali sempre più diversificati e complessi.
Le API di Adobe Campaign sono 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, vedere Implementazione dei metodi SOAP.
Il numero di chiamate al motore autorizzate al giorno varia in base al contratto di licenza. For more on this, refer to this page . In questa documentazione dedicata è disponibile un elenco di tutte le API, inclusa la descrizione completa.

Prerequisiti

Prima di utilizzare le API di Adobe Campaign, devi avere familiarità con i seguenti argomenti:
  • Javascript
  • Protocollo SOAP
  • Modello dati di Adobe Campaign

Utilizzo delle API di 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 alle API orientate ai dati .
  • API specifiche per le aziende che consentono di agire su ciascun oggetto: consegne, flussi di lavoro, iscrizioni ecc. Fate riferimento a API orientate al business .
Per sviluppare le API e interagire con Adobe Campaign, devi 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 di 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, vedere ExecuteQuery (xtk:queryDef) .
La descrizione WSDL di questo servizio è completata nell'esempio seguente: Descrizione del servizio Web: WSDL .

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' <soap-env:envelope> elemento è il primo elemento del messaggio che rappresenta l'inviluppo SOAP.
L’ <soap-env:body> elemento è il primo elemento secondario dell’inviluppo. Contiene la descrizione del messaggio, ovvero il contenuto della query o la risposta.
Il metodo da invocare viene immesso nell' <executequery> elemento 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' <querydef> elemento.

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' <pdomoutput> elemento .

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' <soap-env:fault> elemento 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' <faultcode> elemento viene verificato.
Tutti i servizi Web di Adobe Campaign gestiscono gli errori. È quindi vivamente consigliato testare ogni chiamata per gestire gli errori restituiti.
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 ( Web del server).