APIs orientadas por dados data-oriented-apis

As APIs orientadas por dados permitem abordar todo o modelo de dados.

Visão geral do modelo de dados overview-of-the-datamodel

A Adobe Campaign não oferece uma API de leitura dedicada por entidade (nenhuma função getRecipient ou getDelivery, etc.). Use os métodos de leitura e modificação de dados QUERY & WRITER para acessar os dados do modelo.

O Adobe Campaign permite gerenciar coleções: consultas permitem recuperar um conjunto de informações coletadas em toda a base. Ao contrário do acesso no modo SQL, as APIs do Adobe Campaign retornam uma árvore XML em vez de colunas de dados. O Adobe Campaign cria documentos compostos com todos os dados coletados.

Esse modo operacional não oferece mapeamento 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 em campos do tipo MEMO do banco de dados.

Descrição do modelo description-of-the-model

Você deve estar familiarizado com o modelo de dados do Adobe Campaign para poder abordar os campos do banco de dados nos scripts.

Para ver uma apresentação do modelo de dados, consulte a descrição do modelo de dados do Adobe Campaign.

Query e Writer query-and-writer

A introdução a seguir detalha intercâmbios 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 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 remapeadas, o que pode gerar várias ordens SQL SELECT.

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 write

Os comandos Gravar permitem escrever 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. Também é possível configurar a mesclagem de modificações (mesclar): esse modo operacional permite autorizar atualizações parciais.

A estrutura XML oferece uma visualização lógica dos dados e permite contornar a estrutura física da tabela SQL.

O método Write é apresentado em Write / WriteCollection (xtk:session).

ExecuteQuery (xtk:queryDef) executequery--xtk-querydef-

Esse método permite executar queries de dados associados a um schema. É necessária uma cadeia de caracteres 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 schema 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>

Formato do documento XML da consulta de entrada format-of-the-xml-document-of-the-input-query

A estrutura do documento XML da consulta é descrita no schema "xtk:queryDef ". Este documento descreve as cláusulas de uma consulta SQL: "select", "where", "order by", "group by", "having".

<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 elemento <condition> . A sintaxe de um <subquery> o elemento é baseado na sintaxe de um <querydef>.

Exemplo de um <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 do atributo schema.

O tipo de operação desejado é inserido no atributo operation e contém um dos seguintes valores:

A sintaxe XPath é usada para localizar dados com base no esquema de entrada. Para obter mais informações sobre XPaths, consulte Esquemas de dados.

Exemplo com a operação 'get' example-with-the--get--operation

Recupera o sobrenome e o nome de um recipient (schema "nms:recipient") 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' example-with-the--select--operation

Retorna a lista de recipients 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 elemento <querydef>.

Para limitar para 100 o número de registros retornados pela consulta:

<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" example-with-the--count--operation

Para contar o número de registros em uma consulta:

<queryDef schema="nms:recipient" operation="count"">
  <!-- condition on the folder and domain of the email -->
  <where>
    <condition expr="[@folder-id] = 1234" and @domain like 'Adobe%'"/>
  </where>
</queryDef>

Agrupamento de dados data-grouping

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>

  <!-- email 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>

Interrupção em condições bracketing-in-conditions

Aqui estão dois exemplos de suporte na mesma condição.

É 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 query quando mais de dois dados são usados na condição.

Exemplos em links examples-on-links

Associação dos parâmetros da cláusula 'where' e 'select' binding-the-parameters-of-the--where--and--select--clause

O vínculo de parâmetros permite que o mecanismo defina os valores dos parâmetros usados na consulta. Isso é muito útil, pois o mecanismo é responsável pelo escape de valores e há o benefício adicional de um cache para os parâmetros a serem recuperados.

Quando um query é construído, os valores "vinculados" são substituídos por um caractere (? no ODBC, #[index]# em postgres…) 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 a associação de um parâmetro, o atributo "noSqlBind" deve ser preenchido com o valor 'true'.

Formato do documento de saída output-document-format

O parâmetro return é um documento XML no formato do schema associado à consulta.

Exemplo de retorno do schema "nms:recipient" 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 operação do tipo "count":

<recipient count="3"/>

Alias alias

Um alias permite modificar o local 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>

Devoluções:

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

Em vez de:

<recipient firstName="John" lastName="Doe">
  <folder label="Recipients"/>
</recipient>

Exemplo de mensagens de SOAP example-of-soap-messages

Write / WriteCollection (xtk:session) 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 schema de dados. Os parâmetros de entrada são uma string de autenticação (deve estar conectada) 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 schema "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>

Visão geral overview

A reconciliação de dados opera com base na definição das chaves inseridas no schema associado. O procedimento de gravação procura a primeira chave qualificada com base nos dados inseridos no documento de entrada. A entidade é inserida ou atualizada com base em sua existência no banco de dados.

A chave do esquema da entidade a ser atualizada foi concluída com base no atributo xtkschema.

Portanto, a chave de reconciliação pode ser forçada com o atributo _key contendo a lista de XPaths 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:

Exemplo com o método 'Write' example-with-the--write--method

Atualizar ou inserir um recipient (operação "insertOrUpdate" implícita) 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 recipient:

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

Exemplo com o método 'WriteCollection' example-with-the--writecollection--method

Atualização ou inserção 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>

Exemplo em links example-on-links

Exemplo 1 example-1

Associar a pasta a um recipient com base em seu nome interno (@name).

<recipient _key="[folder/@name], @email" email="john.doe@adobe.net" lastName="Doe" firstName="John" xtkschema="nms:recipient">
  <folder name="Folder2" _operation="none"/>
</recipient>

Os atributos "_key" e "_operation" podem ser inseridos em um elemento vinculado. O comportamento nesse elemento é o mesmo do elemento principal do schema de entrada.

A definição da chave da entidade principal ("nms:recipient") consiste em um campo de uma tabela vinculada (esquema do elemento <folder> "xtk:folder") e do email.

Exemplo 2 example-2

Atualização da empresa (tabela vinculada no schema "cus:company") de um recipient:

<recipient _key="[folder/@name], @email" email="john.doe@adobe.net" lastName="Doe" firstName="John" xtkschema="nms:recipient">
  <company name="adobe" code="ERT12T" _key="@name" _operation="update"/>
</recipient>

Exemplo 3 example-3

Adicionar um recipient a um grupo com a tabela de relação de grupo ("nms:rcpGrpRel"):

<recipient _key="@email" email="martin.ledger@adobe.net" xtkschema="nms:recipient">
  <rcpGrpRel _key="[rcpGroup/@name]">
    <rcpGroup name="GRP1"/>
  </rcpGrpRel>
</recipient>

Elementos da coleção XML xml-collection-elements

Por padrão, todos os elementos de coleção devem ser preenchidos para atualizar os elementos de coleção XML. Os dados do banco de dados serão substituídos por 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 coleção a serem atualizados para forçar uma mesclagem com os dados XML do banco de dados.

Exemplo de mensagens de SOAP example-of-soap-messages-1