API orientate ai dati data-oriented-apis

Le API orientate ai dati consentono di gestire l’intero modello dati.

Panoramica del modello dati overview-of-the-datamodel

Adobe Campaign non offre un’API di lettura dedicata per entità (nessuna funzione getRecipient o getDelivery, ecc.). Utilizzare i metodi di lettura e modifica dei dati QUERY & WRITER per accedere ai dati del modello.

Adobe Campaign consente di gestire le raccolte: le query consentono di recuperare un set di informazioni raccolte in tutta la base. A differenza dell’accesso in modalità SQL, le API di Adobe Campaign restituiscono una struttura XML anziché colonne di dati. Adobe Campaign crea quindi documenti compositi con tutti i dati raccolti.

Questa modalità operativa non offre il mapping uno-a-uno tra gli attributi e gli elementi dei documenti XML e le colonne delle tabelle nel database.

I documenti XML vengono memorizzati nei campi di tipo MEMO del database.

Descrizione del modello description-of-the-model

Per poter gestire i campi del database negli script, è necessario avere familiarità con il modello dati di Adobe Campaign.

Per una presentazione del modello dati, fare riferimento alla descrizione del modello dati Adobe Campaign.

Query e writer query-and-writer

Il seguente schema introduttivo descrive gli scambi di basso livello per la lettura (ExecuteQuery) e la scrittura (Writer) tra database e cliente (pagine web o console client di Adobe Campaign).

ExecuteQuery executequery

Per le colonne e le condizioni, è possibile utilizzare le query.

In questo modo è possibile isolare l'istruzione SQL sottostante. Il linguaggio di query non dipende dal motore sottostante: alcune funzioni verranno nuovamente mappate, il che potrebbe generare diversi ordini SELECT SQL.

Per ulteriori informazioni, consultare Esempio sul metodo 'ExecuteQuery' dello schema 'xtk:queryDef'.

Il metodo ExecuteQuery è presentato in ExecuteQuery (xtk:queryDef).

Scrittura write

I comandi di scrittura consentono di scrivere documenti semplici o complessi, con voci in una o più tabelle della base.

Le API transazionali consentono di gestire le riconciliazioni tramite il comando updateOrInsert: un comando consente di creare o aggiornare dati. È inoltre possibile configurare l'unione modifiche (merge): questa modalità operativa consente di autorizzare aggiornamenti parziali.

La struttura XML offre una vista logica dei dati e consente di ignorare la struttura fisica della tabella SQL.

Il metodo Write è presentato in Write / WriteCollection (xtk:session).

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

Questo metodo consente di eseguire query dai dati associati a uno schema. Richiede una stringa di autenticazione (deve aver effettuato l’accesso) e un documento XML che descriva la query da inviare come parametri. Il parametro restituito è un documento XML contenente il risultato della query nel formato dello schema a cui la query fa riferimento.

Definizione del metodo "ExecuteQuery" nello schema "xtk:queryDef":

<method name="ExecuteQuery" const="true">
  <parameters>
    <param desc="Output XML document" name="output" type="DOMDocument" inout="out"/>
  </parameters>
</method>

Formato del documento XML della query di input format-of-the-xml-document-of-the-input-query

La struttura del documento XML della query è descritta nello schema "xtk:queryDef". Questo documento descrive le clausole di una query 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>

È possibile definire una sottoquery ( <subquery> ) in un elemento <condition> . La sintassi per un <subquery> è basato sulla sintassi di un elemento <querydef>.

Esempio di <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 query deve fare riferimento a uno schema iniziale dall'attributo schema.

Il tipo di operazione desiderato viene immesso nell'attributo operation e contiene uno dei valori seguenti:

La sintassi XPath viene utilizzata per individuare i dati in base allo schema di input. Per ulteriori informazioni su XPaths, fare riferimento a Schemi di dati.

Esempio con l’operazione "get" example-with-the--get--operation

Recupera il cognome e il nome di un destinatario (schema "nms:recipient") con un filtro nell’e-mail.

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

Esempio con l’operazione "select" example-with-the--select--operation

Restituisce l’elenco dei destinatari filtrati su una cartella e il dominio e-mail con un ordinamento decrescente alla data di nascita.

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

Le espressioni possono essere campi semplici o espressioni complesse, ad esempio operazioni aritmetiche o concatenazione di stringhe.

Per limitare il numero di record da restituire, aggiungere l'attributo lineCount all'elemento <querydef>.

Per limitare a 100 il numero di record restituiti dalla query:

<queryDef schema="nms:recipient" operation="select" lineCount="100">
...

Per recuperare i 100 record successivi, eseguire nuovamente la stessa query, aggiungendo l'attributo startLine.

<queryDef schema="nms:recipient" operation="select" lineCount="100" startLine="100">
...

Esempio con l’operazione "count" example-with-the--count--operation

Per contare il numero di record in una query:

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

Raggruppamento di dati data-grouping

Per recuperare gli indirizzi e-mail a cui si fa riferimento più di una volta:

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

La query può essere semplificata aggiungendo l'attributo groupBy direttamente al campo da raggruppare:

<select>
  <node expr="@email" groupBy="true"/>
</select>

Parentesi quadra in condizioni bracketing-in-conditions

Di seguito sono riportati due esempi di parentesi quadre nella stessa condizione.

È possibile sostituire l’operatore "OR" con l’operazione "IN" quando più condizioni si applicano allo stesso campo:

<where>
  <condition>
    <condition expr="@age IN (15, 45)"/>
    <condition expr="@city IN ('Newton', 'Culver City')"/>
  </condition>
</where>

Questa sintassi semplifica la query quando nella condizione vengono utilizzati più di due dati.

Esempi sui collegamenti examples-on-links

Associazione dei parametri delle clausole 'where' e 'select' binding-the-parameters-of-the--where--and--select--clause

L’associazione dei parametri consente al motore di impostare i valori dei parametri utilizzati nella query. Questo è molto utile, poiché il motore è responsabile dell’escape dei valori e c’è il vantaggio aggiuntivo di una cache per i parametri da recuperare.

Quando viene creata una query, i valori "associati" vengono sostituiti da un carattere (? in ODBC, #[index]# in postgres…) nel corpo della query 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>

Per evitare di associare un parametro, l'attributo "noSqlBind" deve essere compilato con il valore "true".

Formato documento di output output-document-format

Il parametro restituito è un documento XML nel formato dello schema associato alla query.

Esempio di ritorno dallo schema "nms:recipient" su un’operazione "get":

<recipient email="john.doe@adobe.com" lastName"Doe" firstName="John"/>

In un’operazione di "selezione", il documento restituito è un’enumerazione di elementi:

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

Esempio di documento restituito per l'operazione di tipo "conteggio":

<recipient count="3"/>

Alias alias

Un alias consente di modificare la posizione dei dati nel documento di output. L'attributo alias deve specificare un XPath nel campo corrispondente.

<queryDef schema="nms:recipient" operation="get">
  <select>
    <node expr="@firstName" alias="@firstName"/>
    <node expr="@lastName"/>
    <node expr="[folder/@label]" alias="@My_folder"/>
  </select>
</queryDef>

Restituisce:

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

Invece di:

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

Esempio di messaggi SOAP example-of-soap-messages

Write/WriteCollection (xtk:session) write---writecollection--xtk-session-

Questi servizi vengono utilizzati per inserire, aggiornare o eliminare un'entità (metodo "Write") o un insieme di entità (metodo "WriteCollection").

Le entità da aggiornare sono associate a uno schema di dati. I parametri di input sono una stringa di autenticazione (deve essere effettuato l'accesso) e un documento XML contenente i dati da aggiornare.

Questo documento è completato da istruzioni per la configurazione delle procedure di scrittura.

La chiamata non restituisce alcun dato, ad eccezione degli errori.

Definizione dei metodi "Write" e "WriteCollection" nello 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>

Panoramica overview

La riconciliazione dei dati funziona in base alla definizione delle chiavi immesse nello schema associato. La procedura di scrittura cerca la prima chiave idonea in base ai dati immessi nel documento di input. L’entità viene inserita o aggiornata in base alla sua esistenza nel database.

La chiave dello schema dell'entità da aggiornare è completata in base all'attributo xtkschema.

È quindi possibile forzare la chiave di riconciliazione con l'attributo _key contenente l'elenco di XPaths che compongono la chiave (separati da virgole).

È possibile forzare il tipo di operazione compilando l'attributo _operation con i valori seguenti:

Esempio con il metodo 'Write' example-with-the--write--method

Aggiornamento o inserimento di un destinatario (operazione implicita "insertOrUpdate") con indirizzo e-mail, data di nascita e città:

<recipient xtkschema="nms:recipient" email="john.doe@adobe.com" birthDate="1956/05/04" folder-id=1203 _key="@email, [@folder-id]">
  <location city="Newton"/>
</recipient>

Eliminazione di un destinatario:

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

Esempio con il metodo 'WriteCollection' example-with-the--writecollection--method

Aggiornamento o inserimento per più destinatari:

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

Esempio di collegamenti example-on-links

Esempio 1 example-1

Associazione della cartella a un destinatario in base al suo 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>

Gli attributi "_key" e "_operation" possono essere immessi in un elemento collegato. Il comportamento di questo elemento è lo stesso dell’elemento principale dello schema di input.

La definizione della chiave dell'entità principale ("nms:recipient") è costituita da un campo di una tabella collegata (elemento <folder> schema "xtk:folder") e dall'e-mail.

Esempio 2 example-2

Aggiornamento della società (tabella collegata nello schema "cus:company") da un destinatario:

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

Esempio 3 example-3

Aggiunta di un destinatario a un gruppo con la tabella delle relazioni di gruppo ("nms:rcpGrpRel"):

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

Elementi della raccolta XML xml-collection-elements

Per impostazione predefinita, per aggiornare gli elementi di raccolta XML è necessario compilare tutti gli elementi di raccolta. I dati del database verranno sostituiti con i dati del documento di input. Se il documento contiene solo gli elementi da aggiornare, è necessario compilare l'attributo "_operation" su tutti gli elementi di raccolta da aggiornare per forzare un'unione con i dati XML del database.

Esempio di messaggi SOAP example-of-soap-messages-1