Show Menu
TEMAS×

API orientadas a datos

Las API orientadas a datos le permiten abordar todo el modelo de datos.

Descripción general del modelo de datos

Adobe Campaign no oferta una API de lectura dedicada por entidad (sin la función getRecipient o getDelivery, etc.). Utilice los métodos de lectura y modificación de datos CONSULTA y WRITER para acceder a los datos del modelo.
Adobe Campaign permite administrar colecciones: Las consultas permiten recuperar un conjunto de información recopilada en toda la base. A diferencia del acceso en modo SQL, las API de Adobe Campaign devuelven un árbol XML en lugar de columnas de datos. De este modo, Adobe Campaign crea documentos compuestos con todos los datos recopilados.
Este modo operativo no oferta la asignación uno a uno entre los atributos y elementos de los documentos XML y las columnas de las tablas de la base de datos.
Los documentos XML se almacenan en campos de tipo MEMO de la base de datos.

Descripción del modelo

Debe estar familiarizado con el modelo de datos de Adobe Campaign para poder abordar los campos de la base de datos en las secuencias de comandos.
Para ver una presentación del modelo de datos, consulte la descripción del modelo de datos de Adobe Campaign.
Para generar su estructura, consulte este artículo: Cómo generar un modelo de datos o un diccionario de datos.

Consulta y escritor

El siguiente esquema de introducción detalla los intercambios de bajo nivel para lectura (ExecuteQuery) y escritura (Writer) entre la base de datos y el cliente (páginas web o consola cliente de Adobe Campaign).

ExecuteQuery

For columns and conditions, you can use Queries.
This lets you isolate the underlying SQL. The query language does not depend on the underlying engine: some functions will be re-mapped, which may generate several SELECT SQL orders.
The ExecuteQuery method is presented in ExecuteQuery (xtk:queryDef) .

Write

Los comandos de escritura permiten escribir documentos simples o complejos, con entradas en una o varias tablas de la base.
Transactional APIs let you manage reconciliations via the updateOrInsert command: one command lets you create or update data. También puede configurar la combinación de modificaciones ( combinar ): este modo operativo permite autorizar actualizaciones parciales.
The XML structure offers a logical view of the data and lets you sidestep the physical structure of the SQL table.
The Write method is presented in Write / WriteCollection (xtk:session) .

ExecuteQuery (xtk:queryDef)

This method lets you perform queries from data associated with a schema. It takes an authentication string (must be logged in) and an XML document describing the query to be submitted as parameters. The return parameter is an XML document containing the result of the query in the format of the schema to which the query refers.
Definición del método "ExecuteQuery" en el esquema "xtk:queryDef":
<method name="ExecuteQuery" const="true">
  <parameters>
    <param desc="Output XML document" name="output" type="DOMDocument" inout="out"/>
  </parameters>
</method>

Es un método "const". Los parámetros de entrada se incluyen en un documento XML con el formato del esquema "xtk:queryDef".

Formato del documento XML de la consulta de entrada

La estructura del documento XML de la consulta se describe en el esquema "xtk:queryDef". Este documento describe las cláusulas de una consulta SQL: "select", "where", "order by", "group by", "have".
<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>

Se puede definir una subconsulta ( <subquery> ) en un <condition> elemento. La sintaxis de un <subquery> elemento se basa en la sintaxis de un <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>  
  

Una consulta debe hacer referencia a un esquema de inicio desde el atributo esquema .
El tipo de operación deseada se introduce en el atributo de operación y contiene uno de los siguientes valores:
  • get : recupera un registro de la tabla y devuelve un error si los datos no existen,
  • getIfExists : recupera un registro de la tabla y devuelve un documento vacío si los datos no existen,
  • seleccionar : crea un cursor para devolver varios registros y devuelve un documento vacío si no hay datos,
  • count : devuelve un recuento de datos.
La sintaxis de XPath se utiliza para localizar datos basados en el esquema de entrada. Para obtener más información sobre XPath, consulte esquemas de datos .

Ejemplo con la operación 'get'

Recupera los apellidos y el nombre de un destinatario ("esquema nms:destinatario") con un filtro en el correo electrónico.
<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>

Ejemplo con la operación 'select'

Devuelve la lista de destinatarios filtrados en una carpeta y el dominio de correo electrónico con un orden descendente en la fecha de nacimiento.
<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>

Las expresiones pueden ser campos simples o expresiones complejas, como operaciones aritméticas o la concatenación de cadenas.
Para limitar el número de registros que se van a devolver, agregue el atributo lineCount al <querydef> elemento .
Para limitar el número de registros devueltos por la consulta a 100:
<queryDef schema="nms:recipient" operation="select" lineCount="100">
...

Para recuperar los 100 registros siguientes, vuelva a ejecutar la misma consulta y agregue el atributo startLine .
<queryDef schema="nms:recipient" operation="select" lineCount="100" startLine="100">
...

Ejemplo con la operación 'count'

Para contar el número de registros de una 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>

Nuevamente, usamos la condición del ejemplo anterior. No se utilizan las cláusulas <select> y. </select>

Data grouping

Para recuperar las direcciones de correo electrónico a las que se hace referencia más de una 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>

La consulta se puede simplificar agregando el atributo groupBy directamente al campo que se va a agrupar:
<select>
  <node expr="@email" groupBy="true"/>
</select>

Ya no es necesario rellenar el <groupby> elemento.

Bracketing in conditions

Here are two examples of bracketing on the same condition.
  • The simple version in a single expression:
    <where>
      <condition expr="(@age > 15 or @age <= 45) and  (@city = 'Newton' or @city = 'Culver City') "/>
    </where>
    
    
  • The structured version with <condition> elements:
    <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>
    
    
Es posible reemplazar el operador 'O' por la operación 'IN' cuando se apliquen varias condiciones al mismo campo:
<where>
  <condition>
    <condition expr="@age IN (15, 45)"/>
    <condition expr="@city IN ('Newton', 'Culver City')"/>
  </condition>
</where>

Esta sintaxis simplifica la consulta cuando se utilizan más de dos datos en la condición.

Enlace de los parámetros de las cláusulas 'where' y 'select'

El enlace de parámetros permite al motor establecer los valores de los parámetros utilizados en la consulta. Esto es muy útil, ya que el motor está a cargo del escape de los valores, y existe la ventaja adicional de una caché para los parámetros que se van a recuperar.
Cuando se construye una consulta, los valores "enlazados" se reemplazan por un carácter (?? en ODBC, #[index]# en pósters...) en el cuerpo de la 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 enlazar un parámetro, el atributo "noSqlBind" debe rellenarse con el valor 'true'.
Si la consulta incluye instrucciones "pedido por" o "grupo por", los motores de base de datos no podrán "enlazar" valores. Debe colocar el atributo @noSqlBind="true" en las instrucciones "select" y/o "where" de la consulta.

Sugerencia de creación de consultas:

Para ayudarle con la sintaxis de una consulta, puede escribir la consulta mediante el editor de consultas genérico en la consola cliente de Adobe Campaign ( Tools/ Generic query editor... menú). Para ello:
  1. Seleccione los datos que desea recuperar:
  2. Defina la condición del filtro:
  3. Ejecute la consulta y presione CTRL+F4 para vista del código fuente de la consulta.

Formato de documento de salida

El parámetro return es un documento XML con el formato del esquema asociado a la consulta.
Ejemplo de un retorno desde el esquema "nms:destinatario" en una operación "get":
<recipient email="john.doe@adobe.com" lastName"Doe" firstName="John"/>

En una operación de "selección", el documento devuelto es una lista desglosada 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>  

Ejemplo de un documento devuelto para la operación de tipo "count":
<recipient count="3"/>

Alias

Un alias permite modificar la ubicación de los datos en el documento de salida. El atributo alias debe especificar una XPath en el campo correspondiente.
<queryDef schema="nms:recipient" operation="get">
  <select>
    <node expr="@firstName" alias="@firstName"/>
    <node expr="@lastName"/>
    <node expr="[folder/@label]" alias="@My_folder"/>
  </select> 
</queryDef>

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

En lugar de:
<recipient firstName="John" lastName="Doe">
  <folder label="Recipients"/>
</recipient>

Ejemplo de mensajes 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>
    
    
  • Respuesta:
    <?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)

Estos servicios se utilizan para insertar, actualizar o eliminar una entidad (método "Write") o una colección de entidades (método "WriteCollection").
Las entidades que se van a actualizar están asociadas con un esquema de datos. Los parámetros de entrada son una cadena de autenticación (debe haber iniciado sesión) y un documento XML que contiene los datos que se van a actualizar.
Este documento se complementa con instrucciones para configurar los procedimientos de escritura.
La llamada no devuelve datos, excepto errores.
Definición de los métodos "Write" y "WriteCollection" en el 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>

Es un método "estático". Los parámetros de entrada se incluyen en un documento XML en el formato del esquema que se va a actualizar.

Información general

La reconciliación de datos funciona según la definición de las claves ingresadas en el esquema asociado. El procedimiento de escritura busca la primera clave elegible en función de los datos introducidos en el documento de entrada. La entidad se inserta o actualiza en función de su existencia en la base de datos.
La clave del esquema de la entidad que se va a actualizar se completa en función del atributo xtkschema .
Por lo tanto, la clave de reconciliación se puede forzar con el atributo _key que contiene la lista de XPath que conforma la clave (separada por comas).
Es posible forzar el tipo de operación rellenando el atributo _operation con los siguientes valores:
  • insertar : fuerza la inserción del registro (no se utiliza la clave de reconciliación),
  • insertOrUpdate : actualiza o inserta el registro en función de la clave de reconciliación (modo predeterminado),
  • update : actualiza el registro; no hace nada si los datos no existen,
  • delete : elimina los registros,
  • ninguno : solo se utiliza para la reconciliación de vínculos, sin actualización ni inserción.

Ejemplo con el método 'Write'

Actualización o inserción de un destinatario (operación implícita "insertOrUpdate") con dirección de correo electrónico, fecha de nacimiento y localidad:
<recipient xtkschema="nms:recipient" email="john.doe@adobe.com" birthDate="1956/05/04" folder-id=1203 _key="@email, [@folder-id]">
  <location city="Newton"/>
</recipient>

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

Para una operación de eliminación, el documento de entrada debe contener solo los campos que conforman la clave de reconciliación.

Ejemplo con el método 'WriteCollection'

Actualizar o insertar para varios destinatarios:
<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 la colección XML

De forma predeterminada, todos los elementos de la colección deben rellenarse para actualizar los elementos de la colección XML. Los datos de la base de datos se reemplazarán con los datos del documento de entrada. Si el documento contiene sólo los elementos que se van a actualizar, debe rellenar el atributo "_operation" en todos los elementos de recopilación que se van a actualizar para forzar una combinación con los datos XML de la base de datos.

Ejemplo de mensajes 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>
    
    
  • Respuesta:
    <?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>
    
    
    Regresar con error:
    <?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>