建立 XML 單向橋接器

更新日期: 2015年8月

本節列出在 BizTalk 服務專案 中建立 XML 單向橋接器 的步驟。XML 橋接器 有不同的階段。本主題內容:

  1. 將橋接器新增至 BizTalk 服務專案

  2. 為 XML 橋接器 所處理之 XML 訊息輸入要求結構描述

  3. 設定解碼階段

  4. 設定驗證階段

  5. 設定擴充階段及其屬性

  6. 設定轉換階段

  7. 設定擴充階段 (轉換後)

  8. 設定編碼階段

  1. 建立BizTalk 服務專案。<開始使用 Visual Studio 專案>列出步驟。

  2. 以滑鼠右鍵按一下 BizTalk 服務專案 設計區域的任何位置,然後選取 [屬性]。在 [BizTalk 服務 URL] 中,輸入您的 BizTalk 服務 URL。

  3. XML 單向橋接器 從 [工具箱] 拖放到 BizTalk 服務專案 設計區域。會將 .BridgeConfig 檔案加入至解決方案。

  4. 以滑鼠右鍵按一下 橋接器,選取 [屬性],然後輸入下列屬性:

     

    屬性名稱 描述

    相關專案項目

    唯讀:相關 .BridgeConfig 檔的名稱。若要變更檔案名稱,請變更 [實體名稱] 屬性。

    實體名稱

    BizTalk 服務專案 設計區域上的 XML 橋接器 的名稱。此名稱必須對 BizTalk 服務專案 而言是唯一的。.BridgeConfig 檔的名稱與您在此處輸入的值相同。

    相對位址

    在 Microsoft Azure 上主控 XML 橋接器 處的相對位址。合併此位址和您在步驟 2 輸入的 BizTalk 服務 URL,可建立 橋接器 的完整 URL。

    例如,如果 BizTalk 服務 URL 是 MyBizTalkService,而 橋接器 的相對位址是 UpdateCustomers,則 服務匯流排 上的端點 URL 將是 https://MyBizTalkService.biztalk.windows.net/default/UpdateCustomers

    路由順序表

    輸入訊息從 橋接器 到其他訊息流程元件的路由順序。請參閱The Routing Order

    執行階段位址

    部署橋接器的公用執行階段端點 URL。

    追蹤屬性

    設定此屬性來定義 橋接器 可追蹤哪些訊息屬性。請參閱追蹤橋接器處理的訊息

  5. 按一下 [儲存]

單一 BizTalk 服務專案可以有多個橋接器和多個結構描述。為了輕鬆使用和節省處理時間,您可以將結構描述和橋接器產生關聯。換句話說,您可以要求特定橋接器只能處理符合特定結構描述或一組結構描述的訊息。本節列出建立此關聯的步驟。

  1. 將結構描述加入至 BizTalk 服務專案。<開始使用 Visual Studio 專案>列出步驟。重複此步驟來加入 BizTalk 服務專案所需的任何數量的結構描述。

  2. 按兩下 XML 單向橋接器 開啟路線設計工具。

    note附註
    路線設計工具是唯讀區域。您無法在路線設計工具中新增或移除階段或活動。

  3. 在 橋接器 設計區域上的 [訊息類型] 方塊中,選取新增圖示 [ 新增圖示 ] 開啟 [訊息類型選擇器]。在 [訊息類型選擇器] 中:

    1. 從 [可用的訊息類型] 方塊中,選取要求訊息的結構描述。

    2. 選取向右箭號圖示 [ 箭號圖示 ],將要求結構描述與橋接器建立關聯。

    3. 選取 [確定]。您選取的結構描述現在列在 [訊息類型] 方塊下方。

      其他

      • 您無法一次新增多個結構描述。若要將多個結構描述與橋接器產生關聯,請重複此步驟。

      • 若要移除與橋接器的結構描述關聯,請從 [訊息類型] 方塊中選取結構描述,然後按刪除圖示 [ 刪除圖示 ]。

      • 若要將一個結構描述關聯取代為另一個,請按一下編輯按鈕 [ 編輯圖示 ],重新開啟 [訊息類型選擇器]。

  4. 按一下 [儲存]

[解碼] 階段會將內送的文字訊息解碼為 XML 訊息,並將它傳遞到XML 單向橋接器橋接器的 [驗證] 階段上。不同於橋接器的其他階段,[解碼] 階段沒有 IsEnabled 屬性。階段的 IsEnabled 屬性可定義階段是否會處理通過橋接器的訊息。因為訊息解碼與否會視傳入訊息的內容類型而定,[解碼] 階段不包含此屬性。 If a bridge receives a message of ‘text/plain’ content type, the decode stage decodes the message and converts it to an XML message.橋接器中每個階段的 Rest 處理皆會在 XML 訊息上發生,而不是在一般檔案訊息上發生。不過,如果橋接器收到任何其他內容類型的訊息時,解碼階段未啟動,則訊息便會傳遞至下一個階段。

[解碼] 階段提供兩個屬性:[On Enter Inspector] 和 [On Exit Inspector]。這些屬性可用來將自訂程式碼納入橋接器處理中。請參閱如何將自訂程式碼加入橋接器中

在 [驗證] 階段中,您可以輸入此階段是否對傳入的要求訊息進行任何結構描述驗證,以及是否將驗證警告傳回給用戶端當做例外狀況。

  1. 按兩下 橋接器 以開啟 橋接器組態 設計區域。

  2. 選取 [驗證] 階段。在 [屬性] 中,將 [IsEnabled] 設為 [True] 或 [False]。設為 [True] 時,階段會根據您先前新增的結構描述來驗證傳入的要求訊息。若為 [False],則不會進行結構描述驗證,訊息會直接傳到下一個階段。

    其他

  3. 選取 [Xml 驗證] 活動。在 [屬性] 中,將 [將警告報告為錯誤] 屬性設定為 [True] 或 [False]。設為 [True] 時,在根據結構描述來驗證 XML 期間,橋接器會將任何發生的警告報告為錯誤,並傳回給原本傳送要求訊息的用戶端。驗證警告會當做例外狀況擲回,然後驗證會失敗。如需了解 XML 結構描述驗證的警告和錯誤,請參閱<驗證和結構描述物件模型>。

  4. 按一下 [儲存]

[擴充] 階段會實現訊息擴充,方法為定義屬性,其值可透過 BizTalk 服務 所提升的預設屬性衍生自訊息標頭 (標準或自��)、衍生自外部資料來源 (僅支援 Microsoft Azure SQL Database 資料表),或衍生自訊息主體內的元素。這些屬性便可以用來將訊息路由傳送到目的地端點,或由訊息接收實體進行更進一步的處理。本節列出執行下列每個動作的步驟:

  • 將訊息標頭值指派給屬性。

  • 使用 BizTalk 服務 所提升的預設屬性或系統屬性。

  • 查閱外部資料來源

  • 使用 Xpath 從訊息主體元素擷取值

重要事項

您可以藉由開啟或關閉擴充階段,選擇是否要執行其中任何動作。

步驟

  1. 按兩下 XML 單向橋接器 開啟路線設計工具。

  2. 選取 [擴充] 階段。在 [屬性] 中,將 [IsEnabled] 屬性設定為 [True] 或 [False]。

    note附註
    若為 True 且未定義任何屬性時,則在設定 橋接器 (設計階段) 且未處理訊息 (執行階段) 時,橋接器 不會擲回錯誤。

    其他

  3. 在 [擴充] 階段內選取 [擴充] 活動。在 [屬性] 中,選取 [屬性定義] 屬性的省略符號按鈕 (…),開啟 [屬性定義]。

  4. 在 [屬性定義] 中選取 [新增]。在 [加入屬性] 中,您可以使用各種來源中的值,並將它們納入到訊息中作為屬性。這些屬性和其值此後就能用於其他處理工作,例如根據屬性值將訊息路由遞送至不同目的地 (請參閱The Routing Action。下表列出不同來源,以及加入屬性至訊息的方法:

     

    來源 作法

    將訊息標頭值指派給屬性

     

    使用系統提升的屬性

     

    查閱外部資料來源

    To lookup an external data source

    使用 XPath 從訊息內擷取值

    To extract values from a message body using xpath

  1. 在 [加入屬性] 中,執行下列動作:

    note附註
    本表僅列出將標頭指派給屬性這項作業所需的欄位,而這項作業僅適用於使用訊息傳輸通訊協定 (例如 SOAP、HTTP、FTP 和 SFTP) 所傳輸的訊息。因此,僅在您從 [類型] 下拉式清單中選取 [HTTP]、[SOAP]、[FTP] 或 [SFTP] 時,下列步驟才適用。另外,根據您在 [類型] 下拉式清單選取的項目,必要欄位將加上紅框,而其餘欄位將呈現灰色。

     

    章節 欄位名稱 描述

    來源 (讀取來源)

    類型

    指定從該處擷取標頭值的訊息類型。若要將標頭值指派給屬性,可能值為 [SOAP]、[HTTP]、[FTP]、[SFTP] 和 [代理]。

    SOAP 標頭命名空間 (僅在 [類型] 設為 [SOAP] 時)

    指定自訂 SOAP 標頭的命名空間。例如,在下列摘錄中,所強調顯示的是 MessageType 自訂標頭的命名空間:

    <s:Header>
       ...
      <MessageType xmlns="http://schemas.microsoft.com/integration/2011/system-properties">http://POAttr.org#PurchaseOrderAttr</MessageType> 
       ...
    </s:Header>
    
    Important重要事項
    如果您從 [識別碼] 下拉式清單中選取標準標頭,則這個欄位會顯示為灰色。您只須針對自訂 SOAP 標頭輸入命名空間;然而,這並不是必要屬性。

    如果類型設為 [HTTP]、[FTP]、[SFTP] 或 [代理],則這個欄位也會呈現灰色。

    識別碼

    指定訊息標頭屬性的名稱,而您想要擷取該屬性的值,並將此值指派給您在這個對話方塊中定義的屬性。如果我們以上面同一個摘錄為例,則識別碼將為 MessageType

    您也可以在此處指定自訂標頭。若為 FTP 和 SFTP,下拉式清單會列出標準識別碼。若為 HTTP 訊息類型,因為標準標頭清單會很龐大,所以下拉式清單不會列出任何標頭;在這樣的情況下,您可以輸入標頭的名稱。另外,若為 SOAP、HTTP 和代理訊息類型,您也可以列出要將其值指派給另一個屬性的自訂標頭。

    若要深入了解,請看看這個範例。讓我們假設 SOAP 訊息標頭看起來像下面這樣:

    <s:Header>
      ...  
      <PONumber xmlns="http://schemas.microsoft.com/integration/promotedpropertiesinfo">PO1234</PONumber> 
      ...  
    </s:Header>
    

    在這個摘錄中,PONumber 為自訂 SOAP 標頭,其值為 PO1234。因此,如果您將識別碼設為 PONumber,則值 PO1234 將指派給您在這裡定義的屬性。

    屬性 (寫入)

    屬性名稱

    指定正在定義之屬性的名稱。這個屬性的值將設為從您稍早指定的訊息標頭屬性中擷取的值。

    若要繼續使用上面的同一個範例,而您將屬性名稱設為 P1,並將 [識別碼] 設為 PONumber,則 P1 的值將設為 PO1234

    資料類型

    指定屬性的資料類型。您可以從下拉式清單中選取一值。

  2. 按一下 [加入屬性] 對話方塊中的 [確定]。對話方塊現在應該如下所示:

    屬性定義

    所以,這個螢幕擷取畫面到底在說明什麼?其表示,如果傳入訊息為 SOAP 訊息,其 SOAP 標頭名稱為 PONumber,而標頭命名空間為 http://schemas.microsoft.com/integration/promotedpropertiesinfo,即會建立資料類型為 stringP1,而且標頭的值會指派給這個屬性。

  3. 若要更新或移除屬性定義,您可以在對話方塊中選取屬性定義,然後按一下 [編輯] 或 [移除]。按一下 [屬性定義] 對話方塊中的 [確定],然後按一下 [儲存],以將變更儲存至 橋接器組態。

  1. 在 [加入屬性] 中,執行下列動作:

    note附註
    本表僅列出將系統提升的屬性指派給訊息所需的欄位。另外,根據您在 [類型] 下拉式清單選取的項目,必要欄位將加上紅框,而其餘欄位將呈現灰色。

     

    章節 欄位名稱 描述

    來源 (讀取來源)

    類型

    若要使用系統提升的屬性,請從下拉式清單中選取 [系統]。

    識別碼

    指定系統提升之屬性的名稱,而您想要擷取該屬性的值,並將此值指派給您在這個對話方塊中定義的屬性。

    屬性 (寫入)

    屬性名稱

    指定正在定義之屬性的名稱。這個屬性的值將設為從您稍早指定的系統提升之屬性中擷取的值。

    資料類型

    指定屬性的資料類型。您可以從下拉式清單中選取一值。

  1. 在 [加入屬性] 中,執行下列動作:

    note附註
    本表僅列出查閱作業所需的欄位。因此,僅在您從 [類型] 下拉式清單中選取 [查閱] 時,下列步驟才適用。另外,根據您在 [類型] 下拉式清單選取的項目,必要欄位將加上紅框,而其餘欄位將呈現灰色。

    Important重要事項
    就此版本而言,您只能從 Microsoft Azure SQL Database 資料表中查閱。

     

    章節 欄位名稱 描述

    來源 (讀取來源)

    類型

    針對搜尋作業,從下拉式清單選取 [查閱]。

    識別碼

    從下拉式清單中,選取已設定的提供者

    如果您尚未設定提供者,請設定一個:

    1. 在 [識別碼] 下拉式清單中選取 [設定新的]。

    2. 在 [提供者組態] 對話方塊中,指定下列值:

       

      欄位名稱 描述

      提供者名稱

      指定提供者的名稱

      連接字串

      指定有效的連接字串以連接到 Microsoft Azure SQL Database 資料表

      資料表名稱

      指定要從中執行資料查閱的來源 Microsoft Azure SQL Database 資料表名稱

      在資料行中查詢

      指定 Microsoft Azure SQL Database 資料表中的資料行名稱,將它的值當做執行資料查閱的輸入查詢

      查詢輸出資料行

      指定 Microsoft Azure SQL Database 資料表中的資料行名稱,它的值就是最後會指派給查閱屬性的輸出值。

    3. 按一下 [確定] 加入提供者組態。

    查閱屬性

    在下拉式清單中選取您已經定義的屬性。這個屬性的值會傳遞給上述的提供者組態中指定的 [在資料行中查詢]。

    屬性 (寫入)

    屬性名稱

    指定內含查閱值的屬性名稱。這個屬性的值衍生自上述的提供者組態中 [在資料行中查詢] 的值。

    資料類型

    指定屬性的資料類型。您可以從下拉式清單中選取一值。

  2. 按一下 [加入屬性] 對話方塊中的 [確定]。對話方塊應該如下所示:

    查閱定義

    所以,這些對話方塊到底在說明什麼?這是邏輯流動的方式 (將以上述的同一個採購單範例說明):

    • 橋接器 會在資料表 (TempTable) (定義於 MyProvider 提供者組態中) 的輸入查詢資料行 (P_Order) 中查詢 P1 (PO1234) 的值。

    • 然後,橋接器 會從 TempTable 中的輸出查詢資料行 (Cust_Name) 挑選對應於 PO1234 的值。

    • 從輸出查詢資料行取得的值會指派給屬性 P2。例如,如果對應於採購單 PO1234 的客戶名稱是 John,P2 的值便設為 John。

    • 屬於 P2 的資料類型會設為 string

  3. 若要更新或移除屬性定義,您可以在對話方塊中選取屬性定義,然後按一下 [編輯] 或 [移除]。按一下 [屬性定義] 對話方塊中的 [確定],然後按一下 [儲存],以將變更儲存至 橋接器組態。

  1. 在 [加入屬性] 中,執行下列動作:

    note附註
    本表僅列出擷取 (xpath) 作業所需的欄位。另外,根據您在 [類型] 下拉式清單選取的項目,必要欄位將加上紅框,而其餘欄位將呈現灰色。

     

    章節 欄位名稱 描述

    來源 (讀取來源)

    類型

    在下拉式清單中選取 Xpath

    識別碼

    指定要從訊息中擷取元素或屬性的 xpath 查詢。一般的 xpath 查詢如下所示:

    /*[local-name()='<root_node>' and namespace-uri()='<namespace>']/*[local-name()='<node_name>' and namespace-uri()=<namespace>']/*@[local-name()='<attribute_name>' and namespace-uri()='<namespace>']
    

    訊息類型

    指定訊息的訊息類型,而您必須使用 xpath 查詢從這個訊息中擷取元素或屬性值。

    下拉式清單顯示所有您已加入至 BizTalk 服務專案 的結構描述。選取具有您要擷取之元素的結構描述。

    屬性 (寫入)

    屬性名稱

    指定正在定義之屬性的名稱。此屬性的值將設為使用 xpath 查詢從訊息本文擷取的值。

    資料類型

    指定屬性的資料類型。您可以從下拉式清單中選取一值。

  2. 按一下 [加入屬性] 對話方塊中的 [確定]。對話方塊應該如下所示:

    使用 Xpath 擷取

    所以,這個對話方塊到底在說明什麼?其表示,從訊息類型 (在這個範例中是 PurchaseOrder) 中,橋接器 會根據指定的 xpath 查詢從元素中擷取值、將該值指派給屬性 P3,然後將屬性 P3 的資料類型設為 double

  3. 若要更新或移除屬性定義,您可以在對話方塊中選取屬性定義,然後按一下 [編輯] 或 [移除]。按一下 [屬性定義] 對話方塊中的 [確定],然後按一下 [儲存],以將變更儲存至 橋接器組態。

在設計階段您可以使用 橋接器組態 設計介面,定義要提升的屬性,以及要指派給這些屬性的值。但是在執行階段,屬性提升及值指派實際上是發生訊息流程通過 服務匯流排 上部署的 橋接器 時。然而在執行階段,屬性提升有時候會由於各種原因而失敗。使用下表以瞭解如何及何時可能發生:

 

若是發生這種情況 什麼會獲得提升

您在設計階段指定的 SOAP 或 HTTP 標頭不存在於執行階段實際傳送至 橋接器 的訊息。

您在設計階段定義的屬性未在執行階段獲得提升;不會擲回任何例外狀況。

您在設計階段指定的 XPATH 查詢未對應於執行階段傳送至 橋接器 的訊息中的元素。

您在設計階段定義的屬性未在執行階段獲得提升;不會擲回任何例外狀況。

就查閱而言,如果您在設計階段指定的查閱屬性在執行階段不存在 (因為它從未獲得提升)

由於查閱而被指派一值的屬性並未獲得提升;不會擲回任何例外狀況。

就查閱而言,如果您在設計階段指定的提供者組態 (其中包括連接字串、資料表名稱等等) 不正確

在執行階段會擲回例外狀況;不會提升任何屬性。在設計階段不會擲回任何例外狀況的原因是 橋接器組態 設計介面並不會驗證提供者組態。

Important重要事項
在設計階段只會驗證使用者認證,而且如果驗證不成功,部署就會失敗。

就查閱而言,如果您在設計階段指定的查閱屬性值,在執行階段的提供者資料來源中 (在這個情況中是 Microsoft Azure SQL Database 資料表) 沒有相符項目

擲回例外狀況;不會提升任何值

就查閱而言,如果您在設計階段指定的查閱屬性值,在執行階段的提供者資料來源中 (在這個情況中是 Microsoft Azure SQL Database 資料表) 有多個相符項目

屬性獲得提升,而且來自資料來源的相符值當中只有一個相符值會被指派給提升的屬性作為值。

就 SOAP、HTTP、XPATH 和查閱而言,如果在設計階段針對屬性指定的資料類型不同於屬性將在執行階段具有之值的資料類型

每當類型轉換可行時,即會轉換類型並提升屬性。例如,您在設計階段將屬性定義為字串,但在執行階段指派給該屬性的值為 30,則該屬性的值將為 "30" (作為字串)。

當類型轉換不可行時,即會擲回例外狀況,而且不會提升屬性。例如,您在設計階段將屬性定義為 "double",但在執行階段指派給該屬性的值為 "John"。因為 "John" 無法當作 "double" 儲存在屬性中,所以會擲回例外狀況,而且不會提升屬性。

在這個階段,您可以輸入橋接器所使用的轉換。您也可以啟用或停用此階段。

  1. 將轉換加入至 BizTalk 服務專案。<開始使用 Visual Studio 專案>列出步驟。重複此步驟來加入專案所需的任何數量的轉換。

  2. 按兩下 XML 單向橋接器 開啟路線設計工具。

  3. 選取 [轉換] 階段。在 [屬性] 中,將 [IsEnabled] 設為 [True] 或 [False]。若為 True,階段會使用您輸入的轉換來轉換傳入的要求訊息。若為 False,則不會轉換訊息,訊息會直接傳到下一個階段。

    其他

  4. 轉換階段內,選取 [Xml 轉換] 活動。在 [屬性] 中,選取 [Map] 屬性的省略符號按鈕 (…),開啟 [選取對應範圍]。

  5. 從顯示的對應清單中,選取要與轉換階段產生關聯的對應,然後選取 [確定]。您新增的對應現在列在路線設計工具的 [選取的對應] 下方。

    Important重要事項
    對話方塊所顯示的對應,只限於其來源結構描述符合您在輸入要求結構描述中輸入的要求訊息結構描述 (在此主題中)。

    note附註
    如果 [IsEnabled] 屬性在 [轉換] 階段設定為 True,而您沒有在 Xml 轉換活動中指定對應,則橋接器無論在設定橋接器時 (設計階段) 或處理訊息時 (執行階段),皆不會擲回錯誤。

    您可以按一下 [Map] 屬性的省略符號按鈕 (…),以新增或移除對應。

  6. 按一下 [儲存]

設定轉換階段之後的 [擴充] 階段,與設定轉換階段之前的擴充階段相類似。請參閱本主題中的設定擴充階段及其屬性。在設定轉換後擴充階段時唯一需要考量的是,您在轉換前擴充階段中定義的屬性也將可在轉換後擴充階段中使用。因此,如果您想要保留這些屬性,請勿建立具有相同名稱的屬性。如果您這樣做,新的屬性定義會覆寫舊的屬性定義。

轉換後擴充階段也提供兩個屬性:On Enter InspectorOn Exit Inspector。這些屬性可用來將自訂程式碼納入橋接器處理中。請參閱如何將自訂程式碼加入橋接器中

在這個階段,您可以輸入用來將 XML 訊息轉換成一般檔案訊息的一般檔案結構描述。訊息進入編碼階段時已是 XML 格式。視編碼階段的設定方式而定,訊息可以編碼為一般檔案格式,或是以 XML 訊息的形式傳送出去。

  1. 按兩下 XML 單向橋接器 開啟路線設計工具。

  2. 選取 [編碼] 階段。在 [屬性] 中,將 [IsEnabled] 屬性設定為 [True] 或 [False]。如果設定為 [True],此階段會使用輸入的一般檔案結構描述來編碼 XML 訊息,使其成為一般檔案訊息。如果設定為 [False],則不會有編碼動作,XML 訊息會從橋接器傳送出去。

    其他

  3. 在 [編碼] 階段,選取 [一般檔案編碼] 活動。在 [屬性] 中,按一下 [一般檔案結構描述] 屬性對應的省略符號按鈕 (…),以開啟 [一般檔案結構描述選項] 對話方塊。

  4. 從對話方塊內的一般檔案結構描述清單中,選取您要用來編碼 XML 訊息並使其轉換成一般檔案訊息的結構描述,然後按一下 [確定]。在 XML 訊息到達一般檔案編碼活動的執行階段中,訊息類型 (Namespace#Root) 會對應到在活動設定過程中提供的一般檔案結構描述。如果有相符的對應,該結構描述就會用來將 XML 訊息轉換為一般檔案訊息。已轉換之訊息的 HTTP 標頭會設定為 “text/plain”。如果沒有相符的對應,所處理的 XML 會維持原狀在編碼階段傳送出去。

    note附註
    如果 [IsEnabled] 屬性在 [編碼] 階段設定為 [True],而您沒有在一般檔案編碼活動過程中指定一般檔案結構描述,則 橋接器 無論在設定橋接器時 (設計階段) 或處理訊息時 (執行階段) 皆不會擲回錯誤。

    您可以按一下 [一般檔案結構描述] 屬性對應的省略符號按鈕 (…) 來新增或移除結構描述。

  5. 按一下 [儲存]

XML 單向橋接器 便設定完成。您現在可以將 橋接器 連接到企業營運系統、路由傳送訊息,以及/或部署 橋接器:

從 BizTalk 服務專案連線至 LOB 系統

在 BizTalk 服務專案中將訊息從橋接器路由至目的地

部署和重新整理 BizTalk 服務專案

另請參閱

顯示: