Gegevensgerichte API’s data-oriented-apis

Met gegevensgeoriënteerde API's kunt u het volledige datamodel beheren.

Overzicht van het datamodel overview-of-the-datamodel

Adobe Campaign biedt geen specifieke lees-API per entiteit (geen functie getRecipient of getDelivery, enz.). Met de methoden QUERY & WRITER-gegevens lezen en wijzigen hebt u toegang tot de gegevens van het model.

Met Adobe Campaign kunt u verzamelingen beheren: met query's kunt u een set gegevens herstellen die in de gehele basis zijn verzameld. In tegenstelling tot toegang in SQL-modus, retourneren Adobe Campaign API's een XML-structuur in plaats van gegevenskolommen. Adobe Campaign maakt dus samengestelde documenten met alle verzamelde gegevens.

Deze werkende wijze biedt geen één-op-één afbeelding tussen de attributen en de elementen van de documenten van XML en de kolommen van de lijsten in het gegevensbestand aan.

XML-documenten worden opgeslagen in MEMO-tekstvelden van de database.

Beschrijving van het model description-of-the-model

U moet bekend zijn met het Adobe Campaign-gegevensmodel om de velden van de database in uw scripts te kunnen verwerken.

Voor een presentatie van het gegevensmodel raadpleegt u de Beschrijving gegevensmodel Adobe Campaign.

Query en schrijver query-and-writer

In het volgende introductieschema worden uitwisselingen op laag niveau beschreven voor lezen (ExecuteQuery) en schrijven (Writer) tussen database en klant (webpagina's of Adobe Campaign-clientconsole).

ExecuteQuery executequery

Voor kolommen en voorwaarden kunt u Query's gebruiken.

Hierdoor kunt u de onderliggende SQL isoleren. De querytaal is niet afhankelijk van de onderliggende engine: sommige functies worden opnieuw toegewezen, waardoor meerdere SELECT SQL-orders kunnen worden gegenereerd.

Raadpleeg voor meer informatie hierover Voorbeeld van de methode 'ExecuteQuery' van schema 'xtk:queryDef'.

De ExecuteQuery methode wordt weergegeven in ExecuteQuery (xtk:queryDef).

Schrijven write

Met schrijfopdrachten kunt u eenvoudige of complexe documenten schrijven met items in een of meer tabellen van de basis.

Met de Transactionele API's kunt u aansluitingen beheren via de updateOrInsert opdracht: met één opdracht kunt u gegevens maken of bijwerken. U kunt ook samenvoeging van wijzigingen configureren (samenvoegen): in deze modus kunt u gedeeltelijke updates toestaan.

De structuur van XML biedt een logische mening van de gegevens aan en laat u de fysieke structuur van de SQL lijst negeren.

De methode Write wordt voorgesteld in Write/WriteCollection (xtk:session).

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

Deze methode laat u vragen van gegevens uitvoeren verbonden aan een schema. Het neemt een authentificatietekenreeks (moet worden het programma geopend) en een document van XML beschrijvend de vraag die als parameters moet worden voorgelegd. De retourparameter is een XML-document dat het resultaat bevat van de query in de indeling van het schema waarnaar de query verwijst.

Definitie van de methode "ExecuteQuery" in het schema "xtk:queryDef":

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

Indeling van het XML-document van de invoerquery format-of-the-xml-document-of-the-input-query

De structuur van het XML-document van de query wordt beschreven in het schema "xtk:queryDef". In dit document worden de clausules van een SQL-query beschreven: "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>

Een subquery ( <subquery> ) kan worden gedefinieerd in een <condition> element. De syntaxis voor een <subquery> element is gebaseerd op de syntaxis van een <querydef>.

Voorbeeld van een <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>

Een query moet verwijzen naar een beginschema in het menu schema kenmerk.

Het gewenste type bewerking wordt ingevoerd in het dialoogvenster bewerking en bevat een van de volgende waarden:

De XPath wordt syntaxis gebruikt om gegevens te vinden die op het inputschema worden gebaseerd. Raadpleeg voor meer informatie over XPails Gegevensschema's.

Voorbeeld met de bewerking get example-with-the--get--operation

Haalt de achternaam en voornaam van een ontvanger ("nms:ontvanger"-schema) op met een filter in de 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>

Voorbeeld met de bewerking 'select' example-with-the--select--operation

Retourneert de lijst met ontvangers die zijn gefilterd op een map en het e-maildomein met een sortering in aflopende volgorde op de geboortedatum.

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

Expressies kunnen eenvoudige velden of complexe expressies zijn, zoals rekenkundige bewerkingen of het samenvoegen van tekenreeksen.

Als u het aantal records dat moet worden geretourneerd wilt beperken, voegt u de opdracht lineCount aan de <querydef> element.

Om het aantal verslagen te beperken die door de vraag aan 100 zijn teruggekeerd:

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

Om de volgende 100 verslagen terug te winnen, stel de zelfde vraag opnieuw in werking, toevoegend startLine kenmerk.

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

Voorbeeld met de bewerking 'count' example-with-the--count--operation

Om het aantal verslagen op een vraag te tellen:

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

Gegevensgroepering data-grouping

U kunt als volgt e-mailadressen ophalen waarnaar meerdere keren wordt verwezen:

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

De query kan worden vereenvoudigd door de groupBy rechtstreeks kenmerk aan het veld dat moet worden gegroepeerd:

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

Bracketing in omstandigheden bracketing-in-conditions

Hier volgen twee voorbeelden van haakjes op dezelfde voorwaarde.

Het is mogelijk de operator 'OR' te vervangen door de operator 'IN' wanneer er verschillende voorwaarden gelden voor hetzelfde veld:

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

Deze syntaxis vereenvoudigt de query wanneer meer dan twee gegevens in de voorwaarde worden gebruikt.

Voorbeelden van koppelingen examples-on-links

De parameters van de component 'where' en 'select' binden binding-the-parameters-of-the--where--and--select--clause

Door de binding van parameters kan de engine de waarden instellen van de parameters die in de query worden gebruikt. Dit is zeer nuttig, aangezien de motor voor het ontsnappen van waarden verantwoordelijk is, en er het extra voordeel van een geheime voorgeheugen voor de parameters is die moeten worden teruggewonnen.

Wanneer een vraag wordt geconstrueerd, worden de "gebonden"waarden vervangen door een karakter (? in ODBC, #[index]# in postgres…) in de tekst van de SQL-query.

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

Als u wilt voorkomen dat een parameter wordt gebonden, moet het kenmerk "noSqlBind" worden gevuld met de waarde "true".

Tip voor het samenstellen van query's: query-building-tip-

Om met de syntaxis van een vraag te helpen, kunt u de vraag schrijven gebruikend de generische vraagredacteur in de de cliëntconsole van Adobe Campaign ( Tools/ Generic query editor… ). Dit doet u als volgt:

Documentindeling uitvoeren output-document-format

De retourparameter is een XML-document in de indeling van het schema dat aan de query is gekoppeld.

Voorbeeld van een terugkeer van het "nms:ontvanger"schema op "krijgt"verrichting:

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

Bij een "select"-bewerking is het geretourneerde document een opsomming van elementen:

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

Voorbeeld van een document dat wordt geretourneerd voor bewerking van het type "count":

<recipient count="3"/>

Alias alias

Met een alias kunt u de locatie van gegevens in het uitvoerdocument wijzigen. De alias moet een XPath op het overeenkomstige gebied specificeren.

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

Retourneert:

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

In plaats van:

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

Voorbeeld van SOAP-berichten example-of-soap-messages

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

Deze services worden gebruikt om een entiteit ("Write"-methode) of een verzameling entiteiten ("WriteCollection"-methode) in te voegen, bij te werken of te verwijderen.

De bij te werken entiteiten zijn gekoppeld aan een gegevensschema. De invoerparameters zijn een verificatietekenreeks (moet worden aangemeld) en een XML-document met de gegevens die moeten worden bijgewerkt.

Dit document wordt aangevuld met instructies voor het configureren van de schrijfprocedures.

De aanroep retourneert geen gegevens, behalve fouten.

Definitie van de methoden "Write" en "WriteCollection" in het 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>

Overzicht overview

De afstemming van gegevens werkt op basis van de definitie van de sleutels die zijn ingevoerd in het bijbehorende schema. De schrijfprocedure zoekt naar de eerste in aanmerking komende sleutel op basis van de gegevens die in het invoerdocument zijn ingevoerd. De entiteit wordt ingevoegd of bijgewerkt op basis van haar bestaan in de database.

De sleutel van het schema van de te bijwerken entiteit wordt voltooid op basis van het xtkschema kenmerk.

De verzoeningssleutel kan dus worden afgedwongen met de _key kenmerk met de lijst met XPails die de sleutel vormen (gescheiden door komma's).

Het is mogelijk het type activiteit af te dwingen door de _operation kenmerk met de volgende waarden:

Voorbeeld met de methode 'Write' example-with-the--write--method

Een ontvanger bijwerken of invoegen (impliciete bewerking "insertOrUpdate") met e-mailadres, geboortedatum en plaats:

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

Een ontvanger verwijderen:

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

Voorbeeld met de methode WriteCollection example-with-the--writecollection--method

Bijwerken of invoegen voor verschillende ontvangers:

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

Voorbeeld van koppelingen example-on-links

Voorbeeld 1 example-1

De map koppelen aan een ontvanger op basis van de interne naam (@name).

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

De kenmerken "_key" en "_operation" kunnen worden ingevoerd op een gekoppeld element. Het gedrag op dit element is hetzelfde als op het hoofdelement van het invoerschema.

De definitie van de sleutel van de hoofdentiteit ("nms:ontvanger") bestaat uit een veld van een gekoppelde tabel (element <folder> schema "xtk:folder") en e-mail.

Voorbeeld 2 example-2

Het bijwerken van het bedrijf (verbonden lijst in "cus:bedrijf"schema) van een ontvanger:

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

Voorbeeld 3 example-3

Een ontvanger aan een groep toevoegen met de groeprelatietabel ("nms:rcpGrpRel"):

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

XML-verzamelingselementen xml-collection-elements

Door gebrek, moeten alle inzamelingselementen worden bevolkt om de de inzamelingselementen van XML bij te werken. Gegevens uit de database worden vervangen door gegevens uit het invoerdocument. Als het document alleen de elementen bevat die moeten worden bijgewerkt, moet u het kenmerk "_operation" invullen voor alle verzamelingselementen die moeten worden bijgewerkt om een samenvoeging met de XML-gegevens van de database te forceren.

Voorbeeld van SOAP-berichten example-of-soap-messages-1