Show Menu
TÓPICOS×

APIs orientadas a dados

As APIs orientadas por dados permitem que você solucione todo o modelo de dados.

Visão geral do modelo de dados

O Adobe Campaign não oferece uma API de leitura dedicada por entidade (sem função getRecipient ou getDelivery etc.). Use os métodos de leitura e modificação de dados de CONSULTA e GRAVADOR para acessar os dados do modelo.
O Adobe Campaign permite gerenciar coleções: as consultas permitem recuperar um conjunto de informações coletadas em toda a base. Diferentemente do acesso no modo SQL, as APIs do Adobe Campaign retornam uma árvore XML em vez de colunas de dados. Assim, o Adobe Campaign cria documentos compostos com todos os dados coletados.
Esse modo operacional não oferece mapeamento de um para um entre os atributos e elementos dos documentos XML e as colunas das tabelas no banco de dados.
Os documentos XML são armazenados nos campos do tipo MEMO do banco de dados.

Descrição do modelo

Você deve estar familiarizado com o modelo de dados do Adobe Campaign para poder endereçar os campos do banco de dados em seus scripts.
Para obter uma apresentação do modelo de dados, consulte a descrição do modelo Dados do Adobe Campaign.
Para gerar sua estrutura, consulte este artigo: Como gerar um Modelo de dados ou um Dicionário de dados.

Consulta e gravador

O esquema de introdução a seguir detalha as trocas de baixo nível para leitura (ExecuteQuery) e gravação (Writer) entre o banco de dados e o cliente (páginas da Web ou console do cliente Adobe Campaign).

ExecuteQuery

Para colunas e condições, você pode usar Consultas.
Isso permite isolar o SQL subjacente. A linguagem de consulta não depende do mecanismo subjacente: algumas funções serão mapeadas novamente, o que pode gerar várias ordens SELECT SQL.
Para obter mais informações, consulte Exemplo no método 'ExecuteQuery' do esquema 'xtk:queryDef' .
O método ExecuteQuery é apresentado em ExecuteQuery (xtk:queryDef) .

Gravar

Os comandos Gravar permitem que você escreva documentos simples ou complexos, com entradas em uma ou mais tabelas da base.
As APIs transacionais permitem gerenciar reconciliações por meio do comando updateOrInsert : um comando permite criar ou atualizar dados. Você também pode configurar a união de modificação ( mesclagem ): esse modo operacional permite autorizar atualizações parciais.
A estrutura XML oferece uma exibição lógica dos dados e permite que você ignore a estrutura física da tabela SQL.
O método Write é apresentado em Write / WriteCollection (xtk:session) .

ExecuteQuery (xtk:queryDef)

Esse método permite que você execute consultas a partir de dados associados a um esquema. É necessária uma string de autenticação (deve estar conectado) e um documento XML que descreve a consulta a ser enviada como parâmetros. O parâmetro return é um documento XML que contém o resultado da consulta no formato do esquema ao qual a consulta se refere.
Definição do método "ExecuteQuery" no esquema "xtk:queryDef":
<method name="ExecuteQuery" const="true">
  <parameters>
    <param desc="Output XML document" name="output" type="DOMDocument" inout="out"/>
  </parameters>
</method>

Este é um método "const". Os parâmetros de entrada são incluídos em um documento XML no formato do esquema "xtk:queryDef".

Formato do documento XML da consulta de entrada

A estrutura do documento XML da consulta é descrita no esquema "xtk:queryDef ". Este documento descreve as cláusulas de uma consulta SQL: "select", "where", "order by", "group by", "tendo".
<queryDef schema="schema_key" operation="operation_type">
  <select>
    <node expr="expression1">
    <node expr="expression2">
    ...
  </select>
  <where> 
    <condition expr="expression1"/> 
    <condition expr="expression2"/>
    ... 
  </where>
  <orderBy>
    <node expr="expression1">
    <node expr="expression2">
    ...
  </orderBy>
  <groupBy>
    <node expr="expression1">
    <node expr="expression2">
    ...
  </groupBy>
  <having>
    <condition expr="expression1"/> 
    <condition expr="expression2"/>
    ...
  </having>
</queryDef>

Uma subconsulta ( <subquery> ) pode ser definida em um <condition> elemento. A sintaxe de um <subquery> elemento se baseia na sintaxe de um <querydef> .
Example of a <subquery> : </subquery>
<condition setOperator="NOT IN" expr="@id" enabledIf="$(/ignored/@ownerType)=1">
  <subQuery schema="xtk:operatorGroup">
     <select>
       <node expr="[@operator-id]" />
     </select>
     <where>
       <condition expr="[@group-id]=$long(../@owner-id)"/>
     </where>
   </subQuery>
</condition>  
  

Uma consulta deve fazer referência a um esquema inicial a partir do atributo schema .
O tipo de operação desejado é inserido no atributo operation e contém um dos seguintes valores:
  • get : recupera um registro da tabela e retorna um erro se os dados não existirem,
  • getIfExists : recupera um registro da tabela e retorna um documento vazio se os dados não existirem,
  • selecione : cria um cursor para retornar vários registros e retorna um documento vazio se não houver dados,
  • contagem : retorna uma contagem de dados.
A sintaxe XPath é usada para localizar dados com base no esquema de entrada. Para obter mais informações sobre XPouts, consulte Esquemas de dados .

Exemplo com a operação 'get'

Recupera o sobrenome e o nome de um destinatário (esquema "nms:receipt") com um filtro no email.
<queryDef schema="nms:recipient" operation="get">
  <!-- fields to retrieve -->
  <select>
    <node expr="@firstName"/>
    <node expr="@lastName"/>
  </select> 

  <!-- condition on email -->
  <where>  
    <condition expr="@email= 'john.doe@aol.com'"/>
  </where>
</queryDef>

Exemplo com a operação 'select'

Retorna a lista de destinatários filtrados em uma pasta e o domínio de email com uma classificação em ordem decrescente na data de nascimento.
<queryDef schema="nms:recipient" operation="select">
  <select>
    <node expr="@email"/>
    <!-- builds a string with the concatenation of the last name and first name separated by a dash -->      
    <node expr="@lastName+'-'+@firstName"/>
    <!-- get year of birth date -->
    <node expr="Year(@birthDate)"/>
  </select> 

  <where>  
     <condition expr="[@folder-id] = 1234 and @domain like 'Adobe%'"/>
  </where>

  <!-- order by birth date -->
  <orderBy>
    <node expr="@birthDate" sortDesc="true"/> <!-- by default sortDesc="false" -->
  </orderBy>
</queryDef>

As expressões podem ser campos simples ou expressões complexas, como operações aritméticas ou a concatenação de strings.
Para limitar o número de registros a serem retornados, adicione o atributo lineCount ao <querydef> elemento.
Para limitar o número de registros retornados pela consulta para 100:
<queryDef schema="nms:recipient" operation="select" lineCount="100">
...

Para recuperar os próximos 100 registros, execute a mesma consulta novamente, adicionando o atributo startLine .
<queryDef schema="nms:recipient" operation="select" lineCount="100" startLine="100">
...

Exemplo com a operação 'count'

Para contar o número de registros em uma consulta:
<queryDef schema="nms:recipient" operation="count"">
  <!-- condition on the folder and domain of the e-mail -->
  <where>  
    <condition expr="[@folder-id] = 1234" and @domain like 'Adobe%'"/>
  </where>
</queryDef>

Novamente usamos a condição do exemplo anterior. As cláusulas <select> e não são usadas. `

Agrupamento de dados

Para recuperar endereços de email referenciados mais de uma vez:
<queryDef schema="nms:recipient" operation="select">
  <select>
    <node expr="@email"/>
    <node expr="count(@email)"/>
  </select>

  <!-- e-mail grouping clause -->
  <groupby>
    <node expr="@email"/>
  </groupby>

  <!-- grouping condition -->
  <having>
    <condition expr="count(@email) > 1"/>
  </having>

</queryDef>

A consulta pode ser simplificada adicionando o atributo groupBy diretamente ao campo a ser agrupado:
<select>
  <node expr="@email" groupBy="true"/>
</select>

Não é mais necessário preencher o <groupby> elemento.

Supressão em condições

Estes são dois exemplos de colchetes na mesma condição.
  • A versão simples em uma única expressão:
    <where>
      <condition expr="(@age > 15 or @age <= 45) and  (@city = 'Newton' or @city = 'Culver City') "/>
    </where>
    
    
  • A versão estruturada com <condition> elementos:
    <where>
      <condition bool-operator="AND">
        <condition expr="@age > 15" bool-operator="OR"/>
        <condition expr="@age <= 45"/>
      </condition>
      <condition>
        <condition expr="@city = 'Newton'" bool-operator="OR"/>
        <condition expr="@city = 'Culver City'"/>
      </condition>
    </where>
    
    
É possível substituir o operador 'OR' pela operação 'IN' quando várias condições se aplicam ao mesmo campo:
<where>
  <condition>
    <condition expr="@age IN (15, 45)"/>
    <condition expr="@city IN ('Newton', 'Culver City')"/>
  </condition>
</where>

Essa sintaxe simplifica a consulta quando mais de dois dados são usados na condição.

Vínculo dos parâmetros das cláusulas 'where' e 'select'

O vínculo de parâmetros permite que o mecanismo defina os valores dos parâmetros usados na consulta. Isso é muito útil, já que o mecanismo é responsável pela fuga de valores e há o benefício adicional de um cache para os parâmetros serem recuperados.
Quando uma consulta é construída, os valores "vinculados" são substituídos por um caractere (? no ODBC, #[index]# em postagens...) no corpo da consulta SQL.
<select>
  <!--the value will be bound by the engine -->
  <node expr="@startDate = #2002/02/01#"/>                   
  <!-- the value will not be bound by the engine but visible directly in the query -->
  <node expr="@startDate = #2002/02/01#" noSqlBind="true"/> 
</select>

Para evitar vincular um parâmetro, o atributo "noSqlBind" deve ser preenchido com o valor "true".
Se a consulta incluir instruções "pedido por" ou "grupo por", os mecanismos do banco de dados não poderão "vincular" valores. Você deve colocar o atributo @noSqlBind="true" nas instruções "select" e/ou "where" da consulta.

Dica de criação de consulta:

Para ajudar com a sintaxe de uma consulta, você pode gravar a consulta usando o editor de consulta genérico no console do cliente Adobe Campaign ( Tools/ Generic query editor... menu). Para fazer isso:
  1. Selecione os dados a serem recuperados:
  2. Defina a condição do filtro:
  3. Execute a consulta e pressione CTRL+F4 para exibir o código da fonte de consulta.

Formato do documento de saída

O parâmetro return é um documento XML no formato do esquema associado à consulta.
Exemplo de um retorno do esquema "nms:receipt" em uma operação "get":
<recipient email="john.doe@adobe.com" lastName"Doe" firstName="John"/>

Em uma operação "select", o documento retornado é uma enumeração de elementos:
<!-- the name of the first element does not matter -->
<recipient-collection>   
  <recipient email="john.doe@adobe.com" lastName"Doe" firstName="John"/>
  <recipient email="peter.martinez@adobe.com" lastName"Martinez" firstName="Peter"/>
  <recipient...
</recipient-collection>  

Exemplo de um documento retornado para a operação do tipo "count":
<recipient count="3"/>

Alias

Um alias permite modificar a localização dos dados no documento de saída. O atributo alias deve especificar um XPath no campo correspondente.
<queryDef schema="nms:recipient" operation="get">
  <select>
    <node expr="@firstName" alias="@firstName"/>
    <node expr="@lastName"/>
    <node expr="[folder/@label]" alias="@My_folder"/>
  </select> 
</queryDef>

Retorna:
<recipient My_folder="Recipients" First name ="John" lastName="Doe"/>

Em vez de:
<recipient firstName="John" lastName="Doe">
  <folder label="Recipients"/>
</recipient>

Exemplo de mensagens SOAP

  • Consulta:
    <?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 operation="get" schema="nms:recipient" xtkschema="xtk:queryDef">
              <select>
                <node expr="@email"/>
                <node expr="@lastName"/>
                <node expr="@firstName"/>
              </select>
              <where>
                <condition expr="@id = 3599"/>
              </where>
            </queryDef>
          </entity>
        </ExecuteQuery>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
    
    
  • Resposta:
    <?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'>
            <recipient email="john.doe@adobe.com" lastName"Doe" firstName="John"/>
          </pdomOutput>
        </ExecuteQueryResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
    
    

Write / WriteCollection (xtk:session)

Esses serviços são usados para inserir, atualizar ou excluir uma entidade (método "Write") ou uma coleção de entidades (método "WriteCollection").
As entidades a serem atualizadas estão associadas a um esquema de dados. Os parâmetros de entrada são uma string de autenticação (deve estar conectado) e um documento XML contendo os dados a serem atualizados.
Este documento é complementado por instruções para configurar os procedimentos de gravação.
A chamada não retorna nenhum dado, exceto erros.
Definição dos métodos "Write" e "WriteCollection" no esquema "xtk:session":
<method name="Write" static="true">
  <parameters>
    <param name="doc" type="DOMDocument" desc="Difference document"/>
  </parameters>
</method>
<method name="WriteCollection" static="true">
  <parameters>
    <param name="doc" type="DOMDocument" desc="Difference collection document"/>
  </parameters>
</method>

Este é um método "estático". Os parâmetros de entrada são incluídos em um documento XML no formato do esquema a ser atualizado.

Visão geral

A reconciliação de dados opera com base na definição das chaves inseridas no esquema associado. O procedimento de gravação procura a primeira chave elegível com base nos dados inseridos no documento de entrada. A entidade é inserida ou atualizada com base na sua existência no banco de dados.
A chave do esquema da entidade a ser atualizada é concluída com base no atributo xtkschema .
A chave de reconciliação pode, portanto, ser forçada com o atributo _key contendo a lista de XPouts que compõem a chave (separados por vírgulas).
É possível forçar o tipo de operação preenchendo o atributo _operation com os seguintes valores:
  • inserir : força a inserção do registro (a chave de reconciliação não é utilizada),
  • insertOrUpdate : atualiza ou insere o registro, dependendo da chave de reconciliação (modo padrão),
  • atualização : atualiza o registro; não faz nada se os dados não existirem,
  • excluir : apaga os registros,
  • none : usado apenas para reconciliação de link, sem atualização ou inserção.

Exemplo com o método 'Write'

Atualizar ou inserir um destinatário (operação implícita "insertOrUpdate") com endereço de email, data de nascimento e cidade:
<recipient xtkschema="nms:recipient" email="john.doe@adobe.com" birthDate="1956/05/04" folder-id=1203 _key="@email, [@folder-id]">
  <location city="Newton"/>
</recipient>

Excluindo um destinatário:
<recipient xtkschema="nms:recipient" _operation="delete" email="rene.dupont@adobe.com" folder-id=1203 _key="@email, [@folder-id]"/>

Para uma operação de exclusão, o documento de entrada deve conter apenas os campos que compõem a chave de reconciliação.

Exemplo com o método 'WriteCollection'

Atualizar ou inserir para vários destinatários:
<recipient-collection xtkschema="nms:recipient">    
  <recipient email="john.doe@adobe.com" firstName="John" lastName="Doe" _key="@email"/>
  <recipient email="peter.martinez@adobe.com" firstName="Peter" lastName="Martinez" _key="@email"/>
  <recipient ...
</recipient-collection>

Elementos de coleção XML

Por padrão, todos os elementos da coleção devem ser preenchidos para atualizar os elementos da coleção XML. Os dados do banco de dados serão substituídos pelos dados do documento de entrada. Se o documento contiver apenas os elementos a serem atualizados, você deverá preencher o atributo "_operation" em todos os elementos de coleta a serem atualizados para forçar uma mesclagem com os dados XML do banco de dados.

Exemplo de mensagens SOAP

  • Consulta:
    <?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>
        <Write xmlns='urn:xtk:persist' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
          <__sessiontoken xsi:type='xsd:string'/>
          <domDoc xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>
            <recipient xtkschema="nms:recipient" email="rene.dupont@adobe.com" firstName="René" lastName="Dupont" _key="@email">
          </domDoc>
        </Write>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
    
    
  • Resposta:
    <?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>
        <WriteResponse xmlns='urn:' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
        </WriteResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
    
    
    Retornar com erro:
    <?xml version='1.0'?>
    <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
      <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
          <faultcode>SOAP-ENV:Server</faultcode>
          <faultstring xsi:type="xsd:string">Error while executing the method 'Write' of service 'xtk:persist'.</faultstring>
          <detail xsi:type="xsd:string">PostgreSQL error: ERROR:  duplicate key violates unique constraint &quot;nmsrecipient_id&quot;Impossible to save document of type 'Recipients (nms:recipient)'</detail>
        </SOAP-ENV:Fault>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>