資料導向 API

資料導向API可讓您處理整個資料模型。

資料模型概述

Adobe Campaign並未針對每個實體提供專用的讀取API（沒有getRecipient或getDelivery函式等）。 使用QUERY & WRITER資料讀取和修改方法訪問模型資料。

Adobe Campaign可讓您管理系列：查詢使您能夠恢復整個資料庫中收集的一組資訊。 與在SQL模式中存取不同，Adobe Campaign API會傳回XML樹狀結構，而非資料欄。 因此，Adobe Campaign會建立包含所有收集資料的複合檔案。

此操作模式不提供XML文檔的屬性和元素以及資料庫中表的列之間的一對一映射。

XML文檔儲存在資料庫的MEMO類型欄位中。

型號的說明

您必須熟悉Adobe Campaign資料模型，才能處理指令碼中資料庫的欄位。

如需資料模型的簡報，請參閱Adobe Campaign資料模型說明。

為了生成其結構，請參閱本文：如何產生資料模型或資料字典。

查詢和寫入器

以下簡介架構詳細說明資料庫與客戶（網頁或Adobe Campaign用戶端主控台）之間的低階讀取(ExecuteQuery)和寫入(Writer)交換。

ExecuteQuery

對於列和條件，可以使用查詢。

這可讓您隔離基礎SQL。 查詢語言不依賴於基礎引擎：某些函式將重新映射，這可能會生成多個SELECT SQL命令。

有關詳細資訊，請參閱Example on the 'xtk:queryDef' schema的'ExecuteQuery'方法。

ExecuteQuery​方法顯示在ExecuteQuery(xtk:queryDef)中。

寫

Write命令可讓您編寫簡單或複雜的文檔，並在一個或多個基本表中輸入條目。

交易API可讓您透過​updateOrInsert​命令管理調節：一個命令可讓您建立或更新資料。 您也可以設定修改合併(merge):此作業模式可讓您授權部分更新。

XML結構提供了資料的邏輯視圖，並使您能夠避開SQL表的物理結構。

Write方法顯示在Write / WriteCollection(xtk:session)中。

ExecuteQuery(xtk:queryDef)

此方法可讓您從與結構關聯的資料執行查詢。 它會使用驗證字串（必須登入）和XML檔案，將查詢描述為參數。 return參數是XML文檔，包含查詢結果的格式為查詢引用的模式。

"xtk:queryDef"架構中"ExecuteQuery"方法的定義：

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

這是一種"const"方法。 輸入參數以"xtk:queryDef"模式的格式包含在XML文檔中。

輸入查詢的XML文檔格式

查詢的XML文檔結構在"xtk:queryDef "模式中描述。 本文檔描述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>

可在<condition> 元素中定義子查詢(<subquery>)。 a的語法 <subquery> 元素是以 <querydef>。

<subquery> : </subquery>範例

<condition setOperator="NOT IN" expr="@id" enabledIf="$(/ignored/@ownerType?lang=zh-Hant)=1">
  <subQuery schema="xtk:operatorGroup">
     <select>
       <node expr="[@operator-id]" />
     </select>
     <where>
       <condition expr="[@group-id]=$long(../@owner-id)"/>
     </where>
   </subQuery>
</condition>

查詢必須從​schema​屬性中引用啟動模式。

所需的操作類型在​operation​屬性中輸入，並包含以下值之一：

  • get:從表中檢索記錄並返回錯誤（如果資料不存在）,
  • getIfExists:從表中檢索記錄並返回空文檔（如果資料不存在）,
  • 選擇:建立游標以返回多個記錄，如果沒有資料，則返回空文檔，
  • 計數:傳回資料計數。

XPath​語法用於根據輸入模式查找資料。 有關XPaths的詳細資訊，請參閱資料架構。

運算'get'的範例

在電子郵件上檢索具有過濾器的收件者（「nms:recipient」架構）的姓氏和名字。

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

操作<select'的示例

傳回在資料夾和電子郵件網域上篩選的收件者清單，並在出生日期以遞減順序排序。

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

運算式可以是簡單欄位或複雜的運算式，例如算術運算或串連。

要限制要返回的記錄數，請將​lineCount​屬性添加到<querydef>元素中。

要將查詢返回的記錄數限制為100，請執行以下操作：

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

要檢索下一個100條記錄，請再次運行相同的查詢，添加​startLine​屬性。

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

的'count'操作示例

要計算查詢上的記錄數，請執行以下操作：

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

我們再次使用上例中的條件。 <select>和子句不被使用。</select>

資料分組

要檢索引用多次的電子郵件地址，請執行以下操作：

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

通過將​groupBy​屬性直接添加到要分組的欄位中，可以簡化查詢：

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

不再需要填入<groupby>元素。

條件中的括弧

以下是兩個在相同條件下加括弧的例子。

  • 單一運算式中的簡單版本：

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

  • 包含<condition>元素的結構化版本：

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

當數個條件套用至相同欄位時，可將「OR」運算子取代為「IN」運算：

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

此語法可簡化條件中使用超過兩個資料時的查詢。

  • 連結1-1或N1:當表具有外鍵（連結從表開始）時，可以直接過濾或檢索連結表的欄位。

    資料夾標籤上的篩選範例：

    <where>
  <condition expr="[folder/@label] like 'Segment%'"/>
</where>

    要從「nms:recipient」架構中檢索資料夾的欄位，請執行以下操作：

    <select>
  <!-- label of recipient folder -->
  <node expr="[folder/@label]"/>
  <!-- displays the string count of the folder -->
  <node expr="partition"/>
</select>

  • 系列連結(1N):必須通過​EXISTS​或​NOT EXISTS​運算子對收集表的欄位執行篩選。

    要篩選已訂閱「電子報」資訊服務的收件者，請執行以下操作：

    <where>
  <condition expr="subscription" setOperator="EXISTS">
    <condition expr="@name = 'Newsletter'"/>
  </condition>
</where>

    不建議從<select>子句直接檢索系列連結的欄位，因為查詢返回主產品。 僅當連結的表只包含一條記錄（例如<node expr="">）時才使用。

    「訂閱」系列連結的範例：

    <select>
  <node expr="subscription/@label"/>
</select>

    可以檢索<select>子句中包含收集連結元素的子清單。 參考欄位的XPaths是來自系列元素的內容相關式。

    篩選(<orderby>)和限制(<where>)元素可以添加到收集元素中。

    在此示例中，對於每個收件人，查詢將返回收件人所訂閱的電子郵件和資訊服務清單：

    <queryDef schema="nms:recipient" operation="select">
  <select>
    <node expr="@email"/>

    <!-- collection table (unbound type) -->
    <node expr="subscription">  
      <node expr="[service/@label]"/>    
      <!-- sub-condition on the collection table -->
      <where>  
        <condition expr="@expirationDate >= GetDate()"/>
      </where>
      <orderBy>
        <node expr="@expirationDate"/> 
      </orderBy>
    </node>
  </select> 
</queryDef>

綁定'where'和'select'子句的參數

參數的綁定可讓引擎設定查詢中使用的參數的值。 這非常有用，因為引擎負責值的逸出，而且快取對於要擷取的參數還有額外的好處。

當建立查詢時，「系結」值會由字元(?)取代 在ODBC中，#[index]#在SQL查詢主體的postgres…中。

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

要避免綁定參數，必須用值'true'填充"noSqlBind"屬性。

重要

如果查詢包含"order-by"或"group-by"指示，資料庫引擎將無法"bind"值。 您必須將@noSqlBind="true"屬性放置在查詢的"select"和／或"where"說明上。

查詢建立提示：

若要協助處理查詢的語法，您可以使用Adobe Campaign用戶端主控台（Tools/ Generic query editor…​功能表）中的一般查詢編輯器來編寫查詢。 操作步驟：

  1. 選擇要檢索的資料：

  2. 定義篩選條件：

  3. 執行查詢並按CTRL+F4以查看查詢原始碼。

輸出文檔格式

返回參數是與查詢相關聯的模式格式的XML文檔。

從"get"操作的"nms:recipient"模式返回的示例：

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

在「選擇」操作中，返回的文檔是元素的列舉：

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

為「計數」類型操作返回的文檔示例：

<recipient count="3"/>

別名

別名可讓您修改輸出檔案中資料的位置。 alias​屬性必須在對應欄位上指定XPath。

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

退貨：

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

而不是：

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

SOAP消息示例

  • 查詢:

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

  • 回應：

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

這些服務用於插入、更新或刪除實體（「寫入」方法）或實體集合（「寫入收集」方法）。

要更新的實體與資料模式相關聯。 輸入參數是驗證字串（必須登入）和包含要更新資料的XML檔案。

本檔案還附有設定寫入程式的指示。

呼叫不會傳回任何資料，但錯誤除外。

"xtk:session"架構中"Write"和"WriteCollection"方法的定義：

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

這是「靜態」方法。 輸入參數以要更新的模式格式包括在XML文檔中。

概觀

資料協調基於在關聯方案中輸入的密鑰的定義而運行。 寫入過程根據在輸入文檔中輸入的資料查找第一個合格密鑰。 根據實體在資料庫中的存在，插入或更新實體。

要更新的實體的模式的鍵基於​xtkschema​屬性完成。

因此，可以使用​_key​屬性強制協調密鑰，該屬性包含構成密鑰的XPaths清單（以逗號分隔）。

通過用以下值填充​_operation​屬性，可以強制執行操作類型：

  • 插入:強制插入記錄（不使用協調密鑰）,
  • insertOrUpdate:根據協調鍵（預設模式）更新或插入記錄，
  • 更新:更新記錄；如果資料不存在，則不執行任何操作，
  • 刪除:刪除記錄，
  • 無:僅用於連結協調，不需要更新或插入。

使用'Write'方法的示例

使用電子郵件地址、出生日期和城鎮更新或插入收件人（隱含的「insertOrUpdate」操作）:

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

刪除收件者：

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

對於刪除操作，輸入文檔只能包含構成協調鍵的欄位。

使用'WriteCollection'方法的範例

更新或插入數個收件者：

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

範例1

根據資料夾的內部名稱(@name)，將資料夾與收件者建立關聯。

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

可在連結的元素上輸入"_key"和"_operation"屬性。 此元素上的行為與輸入架構的主要元素上的行為相同。

主實體("nms:recipient")的鍵的定義由連結表（元素<folder>架構"xtk:folder"）和電子郵件中的欄位組成。

注意

在資料夾元素上輸入的操作「無」定義了不更新或插入的資料夾的協調。

範例2

從收件者更新公司（「cus:company」架構中的連結表格）:

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

範例3

將收件者添加到具有組關係表(「nms:rcpGrpRel」)的組：

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

在<rcpgroup>元素中不輸入鍵的定義，因為基於組名的隱式鍵在「nms:group」模式中定義。

XML收集元素

依預設，必須填入所有系列元素，才能更新XML系列元素。 來自資料庫的資料將替換為來自輸入文檔的資料。 如果文檔只包含要更新的元素，則必須在要更新的所有收集元素上填充「_operation」屬性，以強制與資料庫的XML資料合併。

SOAP消息示例

  • 查詢:

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

  • 回應：

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

    返回時出現錯誤：

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

本頁內容

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now