Todos os métodos de API são apresentados na forma de serviços da Web. Isso permite gerenciar todas as funções do Adobe Campaign por meio de chamadas SOAP, que são o ponto de entrada nativo do servidor de aplicativos Adobe Campaign. O próprio console do Adobe Campaign usa somente chamadas SOAP.
Os serviços da Web permitem que você crie vários aplicativos a partir de um sistema de terceiros:
A definição dos serviços Web implementados no servidor de aplicativos Adobe Campaign está disponível nos schemas de dados.
Um serviço da Web está descrito na gramática dos schemas de dados e está disponível no elemento <methods>
.
<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>
Aqui temos um exemplo da definição do método chamado GenerateForm.
A descrição dos start de serviço com o elemento <method>
. A lista dos parâmetros do método é concluída a partir do elemento <parameters>
. Cada parâmetro é especificado por um nome, um tipo (Booliano, string, DOMElement etc.) e uma descrição. O atributo "inout" com o valor "out" permite especificar que o parâmetro "resultado" está na saída da chamada SOAP.
A presença do atributo "static" (com o valor "true") descreve esse método como static, o que significa que todos os parâmetros do método devem ser declarados.
Um método "const" tem implicitamente um documento XML no formato de seu schema associado como entrada.
Uma descrição completa do elemento <method>
de um schema Adobe Campaign está disponível no capítulo "Referências do Schema" em Método
Exemplo do método "const"-type "ExecuteQuery" do 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>
O parâmetro de entrada desse método é um documento XML no formato do schema "xtk:queryDef".
Um arquivo WSDL (Web Service Description Library) está disponível para cada serviço. Esse arquivo XML usa um idioma de metalagem para descrever o serviço e especificar os métodos, parâmetros e o servidor disponíveis para entrar em contato para executar o serviço.
Para gerar um arquivo WSDL, insira o seguinte URL de um navegador da Web:
https://<server>
/nl/jsp/schemawsdl.jsp?schema=<schema>
Com:
<server>
: o servidor de aplicativos Adobe Campaign (nlserver web)<schema>
: Chave de identificação do schema (namespace:schema_name)O arquivo WSDL é gerado do URL:
https://localhost/nl/jsp/schemawsdl.jsp?schema=xtk:queryDef
Um start de descrição WSDL definindo os tipos usados para formar mensagens, associadas em "portas", conectadas a um protocolo por "vínculos" formando serviços da Web.
As definições de tipo são baseadas em schemas XML. Em nosso exemplo, o método "ExecuteQuery" utiliza uma string "s:string" e um documento XML (<s:complextype>
) como parâmetros. O valor de retorno do método ("ExecuteQueryResponse") é um 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>
O <message>
descreve os nomes e os tipos de um conjunto de campos a serem enviados. O método usa duas mensagens para passar como parâmetro ("ExecuteQueryIn") e o valor de retorno ("ExecuteQueryOut").
<message name="ExecuteQueryIn">
<part element="tns:ExecuteQuery" name="parameters"/>
</message>
<message name="ExecuteQueryOut">
<part element="tns:ExecuteQueryResponse" name="parameters"/>
</message>
O <porttype>
associa as mensagens na operação "ExecuteQuery" acionada pelo query ("input") que gera uma resposta ("output").
<portType name="queryDefMethodsSoap">
<operation name="ExecuteQuery">
<input message="tns:ExecuteQueryIn"/>
<output message="tns:ExecuteQueryOut"/>
</operation>
</portType>
A parte <binding>
especifica o protocolo de comunicação SOAP ( <soap:binding>
), o transporte de dados em HTTP (valor do atributo "transport") e o formato de dados para a operação "ExecuteQuery". O corpo do envelope SOAP contém os segmentos de mensagem diretamente sem transformação.
<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>
A parte <service>
descreve o serviço "XtkQueryDef" com seu URI no URL do servidor de aplicativos Adobe Campaign.
<service name="XtkQueryDef">
<port binding="tns:queryDefMethodsSoap" name="queryDefMethodsSoap">
<soap:address location="https://localhost/nl/jsp/soaprouter.jsp"/>
</port>
</service>
A Adobe Campaign aumentou a segurança dos mecanismos de autenticação ao introduzir zonas de segurança (consulte o capítulo Definição de zonas de segurança em esta seção), bem como as definições de gestão de sessões.
Há dois modos de autenticação disponíveis:
ou
O token de sessão tem as seguintes características:
um ciclo de vida de X hora (o ciclo de vida é configurável no arquivo 'serverConf.xml', o período padrão é de 24 horas)
uma construção aleatória (ela não contém mais o logon do usuário e a senha)
quando acessado pela Web:
O token de segurança tem as seguintes características:
é gerado do token de sessão
tem um ciclo de vida de 24 horas (configurável no arquivo 'serverConf.xml', o período padrão é de 24 horas)
ele é armazenado no console do Adobe Campaign
quando acessado pela Web:
Quando acessado pelo console, é:
De um POST e HTTP GET:
De uma chamada SOAP:
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())
Os URLs usados nas seguintes chamadas HttpServletRequest precisam estar na lista de permissões na seção de permissões de url do arquivo serverConf.xml. Isso também é válido para o URL do próprio servidor.
Execução de logon():
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);
Execução do 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)