WooCommerce 進階設定 - 知行之桥文档

XML 模型

WooCommerce 端口將知行之橋中的 WooCommerce 表建模為 XML。建模遵循以下結構：

父元素標識要插入的表。
每個子元素對應目標表中的一列。

這在 XML 元素和 WooCommerce 值之間建立了連線，這允許端口從傳入的 XML 文件中讀取值並在 INSERT 或 UPDATE 查詢中使用它們。單擊配置面板上方的 </> 程式碼 可以檢視表的 XML 模型。以下 XML 是名為 Account 的表的簡化範例模型，它被建模為 XML 元素 <Account>：

<Items>
    <Account action="upsert">
        <Id key="true" />
        <account_c />
        <AccountNumber />
        <AccountSource />
    </Account>
</Items>

在上面的例子中，Id、account_c、AccountNumber 和 AccountSource 是 Account 表中的列。當端口處理與此結構匹配的 XML 檔案時，它會自動將來自該 XML 的值插入到 Account 表中。當端口查詢 Account 表時，它會輸出與此結構匹配的 XML。

批次處理輸入

批次處理輸出

查詢輸出時，可以配置端口以支援將記錄批次處理到單個文件中。Max Records 設定控制單個訊息中應包含多少條記錄，Batch Size 設定指示單個批次處理組中應包含多少條批次處理訊息。

子表

子表 XML

插入父表和子表時，輸入對映 XML 結構將是多層的。以下 XML 是透過外部索引鍵關聯的兩個表的範例輸入對映：

<Account action="upsert">
    <Id key="true" />
    <account_c />
    <AccountNumber />
    <AccountSource />
    <AccountPartner>
        <Id key="true" />
        <AccountFromId ref="@Id" />
        <IsPrimary />
        <OpportunityId />
        <Role />
    </AccountPartner>
</Account>

在上面的例子中，Account 是父表，AccountPartner 是子表。當 WooCommerce 端口處理匹配此結構的輸入 XML 檔案時，它會更新這兩個表並確保連結兩條記錄的鍵相同。

使用 ref 屬性

子表中的某些列標有 ref 標記。此標記表示這些列對應於父表中的主索引鍵。在對父表進行插入之後，在對子表進行插入之前，端口會在父表中查詢它剛剛插入的記錄的主索引鍵。然後，端口在插入子表時使用此值。當父表的主索引鍵由 WooCommerce 生成時，這很有用。在這種情況下，此列不會作為輸入 XML 傳入，因此端口在將記錄插入到父表中之前不知道該列的值。在 XML 模型中，ref 屬性表示可以稍後引用列，或者應該從對映中的另一列讀取列的值。為了引用由 WooCommerce 生成的列的值，列元素應包含一個設定為保留值 LAST_INSERT_ID 的 ref 屬性：

<Item action="upsert">
    <Id key="true" upsert="id" ref="@@LAST_INSERT_ID" />

這表明 id 值將在插入後檢索，並且可以在以後引用（通常在子表中）。要稍後引用此值，請將 ref 元素設定為相關列的名稱：

<id key="true" ref="@id" />

在上面的例子中，id 是父表中主索引鍵的名稱，也是子表中某列的名稱。ref 語法指示端口在插入後從父表中檢索 id，然後將檢索到的值用作子表中的 id 列。

從子表中選擇

通常，當從父表和子表中選擇時，如果外部索引鍵與父表中的主索引鍵匹配，則應僅從子表中提取記錄。

例如，假設一個 Select 從父表 PurchaseOrders 和子表 PurchaseOrderLineItems 中提取採購訂單資料。從 PurchaseOrders 拉取的每條記錄（訂單）還應拉取與該訂單關聯的行專案。這兩個表透過共享的 PONumber 列關聯，該列是 PurchaseOrders 表的主索引鍵和 PurchaseOrdersLineItems 表中的外部索引鍵。如果訂單項的 PONumber 與從父表中提取的訂單的 PONumber 匹配，則應僅從子表中提取訂單項記錄。

要在知行之橋中建立這種關係，請向 Select 新增一個新過濾器並按如下方式配置它：

在第一個（左側）下拉式清單中，選擇作為父表外部索引鍵的子表列。在上面的範例中，這將是 PurchaseOrderLineItems 表的 PONumber 列。
在中間（運算子）下拉式清單中，選擇 equal。
在最後一個（右側）輸入框中，首先使用右側的下拉箭頭選擇 REF。之後，輸入框應該有 $ 字首，表示正在引用父表。
使用最後一個（右側）下拉式清單選擇應與子表的外部索引鍵匹配的父表列。在上面的範例中，這將是 PurchaseOrders 表的 PONumber 列。

只處理新的或更改的記錄

可以將選擇操作配置為僅檢索最近更新或新增的記錄。端口可以使用兩種方法來檢測哪些記錄是新的或被修改的。

第一種方法需要一個 DateTime 列來表示記錄的最後修改時間。
第二種方法需要一個列來顯式儲存一個值，該值表示是否應該處理記錄。

這兩個選項均在配置面板底部的進階設定中的設定索引標籤上設定。要進一步細化您的要求，請參閱進階索引標籤的進階設定部分中的三個附加 流程更改... 設定。

使用最後修改的列

在配置面板底部找到 進階設定 設定。如果檢測到 DateTime 列，則選項顯示為 使用列處理新的記錄或已更改的記錄。將此設定為表示記錄的上次修改時間的相應 DateTime 列。

使用自定義列

預處理和後處理查詢

在 Upsert 對映中

在 UPSERT 對映中，可以發出在所有記錄被 UPSERT 到表中之前或之後自動執行的查詢。要配置此功能，首先單擊 Upsert 配置 窗格中的 </> 程式碼。

開啟的文字編輯器允許編輯資料表對映的進階功能。文字可能如下所示：

<Items>
    <Names table="`dbo`.`Names`" action="upsert">
        <ID key="true" />
        <Name />
        …
    </Names>
</Items>

如要在任何列被新增到表之前或之後觸發請求，定義一個具有以下屬性的節點：

requireInput：設定為 false。此屬性值指示端口即使輸入檔案中沒有任何匹配的輸入元素也發出查詢。
insertQuery：包含要在 UPSERT 查詢之前或之後執行的語句。
table（可選）：設定為要使用額外查詢定位的表的名稱。（在下面的範例中，表名稱是 updateTable。）如果在對映的根級別發出查詢（即，作為 <Items> 元素的子元素），此屬性不是必需的。如果將查詢作為另一個表的子項發出，設定 table 屬性可確保查詢與該表的列區分開來。

根據你希望它執行的時間，將新定義的元素放在 UPSERT 查詢之前或之後。在下面的例子中，<runFirst> 會在任何 UPSERT 請求之前對錶執行 EXEC [dbo.FlushTemp]：

<Items>
    <runFirst table="updateTable" insertQuery="EXEC [dbo].[FlushTemp]" requireInput="false" />
    <Names table="`dbo`.`Names`" action="upsert">
        <ID key="true" />
        <Name />
        …
    </Names>
</Items>

在下面的例子中，<runLast> 會在所有 UPSERT 請求完成後對錶執行 EXEC [dbo].[CommitTemp]。

<Items>
    <Names table="`dbo`.`Names`" action="upsert">
        <ID key="true" />
        <Name />
        …
    </Names>
    <runLast table="updateTable" insertQuery="EXEC [dbo].[CommitTemp]" requireInput="false" />
</Items>

例子中的元素名稱（runFirst 和 runLast）都是佔位符，你可以隨意自選。

UPSERT 對映中的預處理和後處理查詢不接受查詢中未硬編碼的輸入元素，並且它們也不會生成輸出資料。

在 Select 對映中

在 Select 對映中，可以發出在對目標表發出查詢之前或之後自動執行的查詢。要配置此功能，首先單擊 Select 配置 窗格中的 </> 程式碼。

開啟的文字編輯器允許編輯資料表對映的進階功能。如要在任何列被新增到表之前或之後觸發請求，定義一個具有以下屬性的節點：

outputResult：設定為 false。此屬性值指示端口不將查詢的任何資料作為結果傳回到輸出檔案中。
selectQuery：包含要在 SELECT 查詢之前或之後執行的語句。
table（可選）：設定為要使用額外查詢定位的表的名稱。（在下面的範例中，表名稱是 selectTable。）如果在對映的根級別發出查詢（即，作為 <Items> 元素的子元素），此屬性不是必需的。如果將查詢作為另一個表的子項發出，設定 table 屬性可確保查詢與該表的列區分開來。

根據你希望它執行的時間，將新定義的元素放在 SELECT 查詢之前或之後。在下面的例子中，<runFirst> 會在對錶發出 SELECT 查詢之前執行 EXEC [dbo].[prepTable]：

<Items>
    <runFirst table="selectTable" selectQuery="EXEC [dbo].[prepTable]" outputResult="false" />
    <Names table="`dbo`.`Names`" action="select">
        <ID key="true" />
        <Name />
        …
    </Names>
</Items>

在下面的例子中，<runLast> 會在對錶發出 SELECT 查詢及任何子查詢之後執行 EXEC [dbo].[cleanTable]：

<Items>
    <Names table="`dbo`.`Names`" action="select">
        <ID key="true" />
        <Name />
        …
    </Names>
    <runLast table="selectTable" selectQuery="EXEC [dbo].[cleanTable]" outputResult="false" />
</Items>

例子中的元素名稱（runFirst 和 runLast）都是佔位符，你可以隨意自選。

SELECT 對映中的預處理和後處理查詢不接受查詢中未硬編碼的輸入元素。

XML 屬性

表屬性

allColumns

在選擇（Select）對映中，使用此屬性指定輸出 XML 應包含查詢結果中傳回的所有列。這允許定義輸出對映，而無需在輸出對映中顯式定義所有列的名稱。如果不使用此屬性，輸出對映中存在的列將用於按照程式碼檢視中指定的順序對查詢傳回的元素進行定位，查詢中傳回但輸出對映中沒有匹配列的元素將不會傳回到輸出 XML 中。

<MyTable allcolumns="true" selectQuery="SELECT * FROM [MyTable]" />

insertQuery

在更新/插入（Upsert）對映中，當插入記錄時，可以使用此查詢覆蓋端口建立的預設查詢。它可以用於釋出超出與輸入檔案關聯的普通插入操作之外的查詢。

<runFirst insertQuery="TRUNCATE TABLE [dbo].[Records]" requireInput="false" />

outputResult

在選擇（Select）對映中，如果設定此屬性，則會發出匹配 Select 查詢的查詢，但不會生成要在輸出 XML 中傳回的內容。這允許執行作為交易一部分的其他查詢，而這些查詢不會反映在端口的輸出中。

<runFirst table="selectTable" selectQuery="EXEC [dbo].[prepTable]" outputResult="false" />

processChangesOnly

在選擇（Select）對映中，如果將 processChangesOnly 屬性應用於表，並結合將 timeCheck 屬性應用於日期時間列，則選擇對映會在查詢中動態生成的 WHERE 子句中使用此列，以確保僅檢索新記錄。這對應於設計器中 使用列 columnname 處理新記錄或更改記錄 選項中所選的列。有關更多資訊，請參閱僅處理新記錄或更改記錄。

此屬性僅適用於選擇對映中的根表。

<Orders processChangesOnly="true">

requireInput

在更新/插入（Upsert）對映中，如果設定此屬性，則無論輸入 XML 是否包含匹配元素，都會執行與 inputQuery 匹配的查詢。當預處理或後處理查詢作為存在一個或多個輸入元素的同一交易的一部分發布時（例如，在輸入新批次之前截斷表，或在批次完成後執行預存程序），將使用此屬性。

<runFirst insertQuery="TRUNCATE TABLE [dbo].[Records]" requireInput="false" />

selectQuery

在選擇（Select）對映中，此屬性用於在 XML 中定義查詢及其參數。如果未提供 selectQuery，則會發出簡單的 SELECT *。可以將 selectQuery 用於自定義查詢，例如使用 JOIN 或其他 SQL 關鍵字的查詢。

<Orders selectQuery="SELECT ID, OrderNo, OrderDate FROM Orders">

table

用於指定作為對映查詢目標的表，特別是當表名與對映到它的有效 XML 元素名稱不同時。

如果在 selectQuery、upsertQuery 或 insertQuery 中編寫了顯式查詢，則此屬性將被忽略。

<Purchase_Orders table="Purchase Orders">

upsertQuery

在更新/插入（Upsert）對映中，使用此查詢來確定正在處理的記錄是新記錄（INSERT）還是正在更新的現有記錄（UPDATE）。操作將根據是否找到此查詢的匹配結果來確定。

<Records action="upsert" upsertQuery="SELECT ID FROM Records WHERE Key1 = @Key1 and Key2 = @Key2">

列屬性

aggregate

在某些情況下，對映中列的值本身可能是一個 XML 聚合。預設行為是將該列視為字串，並使用 XML 編碼對列中聚合的值進行編碼。但是，當列上存在 aggregate 屬性時，對映到該表的 XML 檔案會將任何聚合列的值作為原始 XML，而不是編碼為單個元素。

<LineItems aggregate="true" />

column

對映中列上的 column 屬性提供了所引用表中的列名。這可以實現以下幾點：

對映到非有效 XML 元素的列
為資料庫中的列建立別名，以將其與其他表中名稱相似的列區分開來
在 XML 模型中使用更易讀的元素

<New_data column="New Data" />

id

在選擇（Select）對映中，此屬性使用 Id 標記對列值進行標記，隨後可以在子查詢中使用語法 ${#ID} 引用該標記。當子查詢中需要列值，且多個表中的匹配列名可能導致選擇歧義時，這非常有用。

    <Shipments table="`Shipments`" selectQuery="SELECT * FROM `Shipments`">
        <ID type="integer" key="true" id="ShipID"/>
        ...
        <ShipmentOrders table="`ShipmentOrders`" selectQuery="SELECT * FROM `ShipmentOrders` WHERE `ShipmentID` = ${ID}">
            <ID type="integer" key="true" id="ShipOrderID"/>
            ...
            <ShipmentOrderItems table="`ShipmentOrderItems`" selectQuery="SELECT * FROM `ShipmentOrderItems` WHERE `ShipmentOrderID` = ${ID}">
                <ID type="integer" key="true" id="ShipOrderItemID"/>
                ...

key

將該列標識為表的主索引鍵。當此屬性出現在更新/插入（Upsert）查詢中時，端口會在更新記錄前檢查該記錄是否存在。如果表中沒有主索引鍵屬性，則僅允許對錶進行插入（Insert）操作，且在選擇記錄後無法更新列值，因為無法標識唯一記錄。（如果確定某列可以像主索引鍵列一樣使用，則可以覆蓋現有列作為主索引鍵。）

<ID key="true" type="integer"/>

ref

在更新/插入（Upsert）對映中，此屬性用於向資料庫提供無法僅從輸入 XML 中確定的更新/插入值。這最常用於父子關係中以確定資料庫生成的主索引鍵，或者用於一個表引用子表上的外部索引鍵。有關更多資訊，請參閱使用 ref 屬性。

   <Orders table="`Orders`" action="upsert">
        <ID type="integer" key="true" ref="@@LAST_INSERT_ID" />
        ...
        <OrderLines table="`OrderLines`" action="upsert">
            <ID type="integer" key="true" />
            ...
            <OrderID type="integer" ref="@ID" />
        </OrderLines>
    </Orders>

timeCheck

此屬性僅適用於選擇對映中的根表。

<LastModified timeCheck="true" />

type

用於標識表中列的資料型別。對於更新/插入（Upsert）查詢，在執行查詢之前，系統會根據該型別對列中的值進行驗證。

<ID key="true" type="integer"/>

updateValue

在選擇（Select）對映中，從資料庫中選擇的任何記錄在檢索後，都會使用此列中的新值進行更新。這對應於設計器中的當行處理成功時，使用值 value 更新列 columnname 選項。

此屬性僅適用於查詢中的根表。

<Exported updateValue="true" />

​XML 模型

​批次處理輸入

​批次處理輸出

​子表

​子表 XML

​使用 ref 屬性

​從子表中選擇

​只處理新的或更改的記錄

​使用最後修改的列

​使用自定義列

​預處理和後處理查詢

​在 Upsert 對映中

​在 Select 對映中

​XML 屬性

​表屬性

​allColumns

​insertQuery

​outputResult

​processChangesOnly

​requireInput

​selectQuery

​table

​upsertQuery

​列屬性

​aggregate

​column

​id

​key

​ref

​timeCheck

​type

​updateValue

XML 模型

批次處理輸入

批次處理輸出

子表

子表 XML

使用 ref 屬性

從子表中選擇

只處理新的或更改的記錄

使用最後修改的列

使用自定義列

預處理和後處理查詢

在 Upsert 對映中

在 Select 對映中

XML 屬性

表屬性

allColumns

insertQuery

outputResult

processChangesOnly

requireInput

selectQuery

table

upsertQuery

列屬性

aggregate

column

id

key

ref

timeCheck

type

updateValue