Informazioni sui servizi web about-web-services
Definizione delle API di Adobe Campaign definition-of-adobe-campaign-apis
Il server applicazioni Adobe Campaign è stato progettato per offrire apertura e facilità di integrazione con sistemi informativi aziendali sempre più complessi e diversificati.
Le API di Adobe Campaign vengono utilizzate in JavaScript all’interno dell’applicazione e in SOAP al di fuori di essa. Costituiscono una libreria di funzioni generiche che possono essere arricchite. Per ulteriori informazioni, fare riferimento a Implementazione dei metodi SOAP.
Un elenco di tutte le API, inclusa la loro descrizione completa, è disponibile in [questa documentazione dedicata] (https://experienceleague.adobe.com/developer/campaign-api/api/index.html?lang=it.
Prerequisiti prerequisites
Prima di utilizzare le API di Adobe Campaign, è necessario avere familiarità con i seguenti argomenti:
- JavaScript
- Protocollo SOAP
- Modello dati di Adobe Campaign
Utilizzo delle API di Adobe Campaign using-adobe-campaign-apis
Adobe Campaign utilizza due tipi di API:
- API di accesso ai dati generiche per l’esecuzione di query sui dati del modello dati. Fai riferimento a API orientate ai dati.
- API specifiche per l’azienda che consentono di agire su ciascun oggetto: consegne, flussi di lavoro, abbonamenti, ecc. Fai riferimento a API orientate alle aziende.
Per sviluppare API e interagire con Adobe Campaign, è necessario avere familiarità con il modello dati. Adobe Campaign consente di generare una descrizione completa della base. Fai riferimento a Descrizione del modello.
Chiamate SOAP soap-calls
Il protocollo SOAP consente di richiamare i metodi API tramite il rich client, le applicazioni di terze parti tramite i servizi web o JSP utilizzando tali metodi in modo nativo.
La struttura di un messaggio SOAP è la seguente:
- una busta che definisce la struttura del messaggio,
- un’intestazione facoltativa,
- un corpo contenente le informazioni sulla chiamata e la risposta,
- gestione degli errori che definisce la condizione di errore.
Risorse e scambi resources-and-exchanges
Lo schema seguente mostra le varie risorse coinvolte nell’utilizzo delle API di Adobe Campaign:
Esempio di messaggio SOAP sul metodo 'ExecuteQuery' example-of-a-soap-message-on-the--executequery--method--
In questo esempio, una query SOAP richiama il metodo "ExecuteQuery", che accetta una stringa di caratteri come parametro per l'autenticazione (token di sessione) e un contenuto XML per la descrizione della query da eseguire.
Per ulteriori informazioni, fare riferimento a ExecuteQuery (xtk:queryDef).
Query SOAP soap-query
<?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>
Il <soap-env:envelope>
è il primo elemento del messaggio che rappresenta la busta SOAP.
Il <soap-env:body>
è il primo elemento figlio della busta. Contiene la descrizione del messaggio, ovvero il contenuto della query o della risposta.
Il metodo da richiamare viene immesso nel <executequery>
dal corpo del messaggio SOAP.
In SOAP, i parametri vengono riconosciuti in base all'ordine di visualizzazione. Il primo parametro, <__sessiontoken>
, prende la catena di autenticazione, il secondo parametro è la descrizione XML della query dal <querydef>
elemento.
Risposta SOAP soap-response
<?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 dal <pdomoutput>
elemento.
Gestione degli errori error-management
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>
Il <soap-env:fault>
nel corpo del messaggio SOAP viene utilizzato per trasmettere i segnali di errore generati durante l'elaborazione del servizio web. È composto 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 problema 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>
: messaggio di errore lungo
L'esito positivo o negativo della chiamata del servizio viene identificato quando <faultcode>
è 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 EndPoint) url-of-web-service-server--or-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 applicazioni Adobe Campaign (nlserver web).