跳至主內容
Deutsch English (United States) Español Français 日本語 简体中文

搜尋

此段落內的文章

檢視更多

建立安全的網路服務整合

Samantha Petro

BarTender Content Team

  • 更新於
隨著 BarTender 2022 R5 的發佈，BarTender 現已原生支援 HTTPS。若需在 Integration Builder 中啟用 HTTPS 的說明，請參閱本指南。

概述

網路服務整合是一種很棒的方式，可以透過網路請求自動化列印。這些請求是透過 HTTP 傳送的，但 HTTP 並不安全。那麼，有沒有辦法改用 HTTPS 傳送，讓網路請求中的資料更安全呢？

這是可行的，但不是直接透過 Integration Builder 或管理主控台來實現。你可以將網路請求發送到 BarTender Print Portal，也就是 BarTender 的網頁應用程式。BarTender Print Portal 具備安全的 Integration Passthrough 功能，能將網路服務請求轉發到同一系統上正在監聽的整合。

注意：這個方法與舊版本略有不同，如果你是從 BarTender 2019 升級，請確保 URL 和標頭資訊符合新的格式。

本範例將帶你一步步完成如何保護 BarTender Print Portal 底下運作的 Internet Information Services (IIS)、你的整合，以及標籤檔案。

適用範圍

BarTender 2021 至 BarTender 2022 R4

Print Portal

先決條件

若要使用 BarTender Print Portal 的 Integration Passthrough 功能，你需要準備以下項目：

  • Internet Information Services (IIS) 管理員。這是 Windows 的一項功能，可以透過 開啟或關閉 Windows 功能 應用程式安裝。
  • BarTender Print Portal
  • 一個可以發送網路請求的應用程式。本教學以 Postman 和 Insomnia 為例，但你也可以選擇其他工具。

此外，這裡有本範例會用到的範例文件：

啟用 HTTPS

為了讓 Integration Passthrough 的連線更安全，你必須將 HTTPS 綁定到 BarTender Print Portal。這個步驟需要在 IIS 管理員中進行。

Microsoft 有一份詳細的說明，教你如何為網站設定 HTTPS。預設情況下，BarTender Print Portal 在 IIS 管理員的網站清單中會顯示為 BarTender。這份說明會教你如何建立並使用自簽名憑證。不過，如果你有從憑證授權單位取得的憑證，也可以依照相同步驟（略過自簽名憑證的部分）來使用你的憑證。

完成綁定後，你會在網站綁定區看到 HTTP 和 HTTPS 都已列出，如下圖所示：

integration_passthrough_bindings.png

不需要重新啟動網站或系統。綁定設定會立即生效。

啟用 Integration Passthrough

Integration Passthrough 是 BarTender Print Portal 設定檔中的一個設定。預設情況下這個設定是關閉的，所以如果你現在就發送網路請求，BarTender Print Portal 會忽略它。

要更改這個設定，你需要用系統管理員權限或能自動提權的文字編輯器開啟設定檔。Windows 不允許一般使用者儲存這個檔案。請依照以下步驟操作：

  1. 如果你使用 記事本：
    1. 在 開始選單 找到 記事本。
    2. 右鍵點擊並選擇 以系統管理員身分執行。
  2. 前往 C:\inetpub\wwwroot\BarTender\ 並開啟 settings.xml
  3. 往下捲動到接近底部，找到 IntegrationPassthrough 參數
  4. 將 Enabled 改為 "true"

integration_passthrough_config.png

儲存檔案後，你需要重新啟動幾個元件，讓所有與 Passthrough 有關的部分都知道這個功能已經啟用。

重新啟動服務

  1. 從開始選單或控制台開啟 服務 管理工具。
  2. 右鍵點擊 BarTender System Service，選擇 重新啟動。
  3. 系統會通知你相關相依服務也會一併重啟。點選 確定。
  4. 當所有對話框都關閉後，所有 BarTender 服務旁邊應該都會顯示「正在執行」

重新啟動 IIS 應用程式集區

  1. 開啟 IIS 管理員
  2. 點選應用程式集區
  3. 點選 BPP_AppPool
  4. 在右側動作清單中點選停止，稍等片刻後再點選啟動。

設定整合

整合本身的設定方式與其他網路服務整合大致相同。以下簡單說明各種網路服務請求的設定方式：

GET

  • 標籤必須使用命名資料來源。
  • 整合必須在「列印文件」動作中覆寫命名資料來源。
  • 單一紀錄會作為請求 URL 的一部分傳送。

POST

POST 請求的設定方式有兩種，取決於你要傳送多少筆紀錄。

如果你只想傳送一筆紀錄，可以像 GET 請求一樣設定整合和標籤檔案。資料會放在請求的主體中，而不是 URL。

如果你想傳送多筆紀錄，設定方式如下：

  • 標籤連接到像 JSON 或 CSV 這類文字資料庫。
  • 整合在「列印文件」動作中覆寫資料庫，改用 %EventData%。
  • 一筆或多筆紀錄會以與標籤連接的文字資料庫相同的格式，作為請求主體傳送。

在本範例中，範例檔案是一筆紀錄，可以用 GET 或 POST 請求傳送。這是很常見且最簡單的設定方式。

如需更多資訊與疑難排解，請參考以下文章：

解壓縮範例檔案

請依照以下步驟解壓縮並設定範例：

  1. 下載範例包：TempIntegration.zip 
  2. 將整合和標籤檔案解壓縮到 C:\TempIntegration\ 
  3. 開啟整合檔案
  4. 點選 列印文件 動作，然後切換到 列印選項 分頁。
  5. 將印表機更改為你系統上有的印表機。

設定請求

本節需要使用 Insomnia、Postman 或類似的應用程式來發送網路請求。無論是 POST 還是 GET，請求的 URL 都需要整合的 URL。你可以在 Integration Builder 的服務區段找到這個 URL。下圖是範例整合檔案的截圖，黃色標示的部分就是整合 URL：

integration_passthrough_url.png

如果你之前用過網路服務整合，這個 URL 應該很熟悉。一般來說，發送網路服務請求時，你會將請求送到這個完整的 URL 路徑，觸發整合列印。不過在使用 Passthrough 時，我們是將請求送到 BarTender Print Portal，但它需要知道要轉發到哪個整合。我們就是透過提供整合 URL 來告訴它。

無論是 GET 還是 POST，網路請求的 URL 格式如下：

https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=[IntegrationURL]

請注意，這個 URL 和整合檔案中列出的不同。它是透過 Integration Passthrough 轉送請求，再傳給 targetURL。

以本範例檔案來說，填入整合 URL 後，完整的請求 URL 會是：

https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute

以下範例都會用上面的 URL。如果你用的是自己的檔案，請將範例的整合 URL 換成你自己整合中找到的 URL。

在 BarTender 2019 之前的版本，透過 Print Portal Integration Passthrough 發送網路服務整合請求的基礎 URL 如下。當時不需要額外參數來指定整合 URL。 
http://localhost/BarTender/API/Integration/WebServiceIntegration/Execute

建立 GET 請求

GET 請求會將所有資訊放在 URL 中。這通常是透過填寫標頭資訊來完成。不過，由於 Integration Passthrough 需要 targetURL 參數，標籤資料需要放在不同的位置。

在 Insomnia（如下圖）中，正確的位置是 Query。在 Postman 中則是 Params。

integration_passthrough_get.png

如果你自己組合 URL，請將每個參數以 key-value 形式加到 URL 上，每組之間用 & 分隔，如上圖的 URL 預覽所示。

本範例使用的資料如下：

建立 POST 請求

POST 請求會將資料放在請求主體中，而不是 URL。和 GET 請求一樣，POST 請求也有 targetURL 參數，告訴 Integration Passthrough 要將資訊送到哪裡。

integration_passthrough_post.png

如果你有查看整合檔案的所有設定，可能會注意到 Input Data 設為 JSON。整合可以自動解析 JSON 的 key-value 配對，轉成可用的變數，不需要你額外處理或新增動作。如果你只打算傳送一筆紀錄，這會是個不錯的選擇。

本範例使用的資料如下：

  • URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
  • 主體資料: {"Company": "The Company", "IDNumber": "3"}

發送請求

一切設定好之後，你就可以發送請求了。

  1. 啟動整合。點選 測試 分頁，然後點擊大大的綠色 啟動 按鈕
  2. 在 Insomnia 或 Postman 應用程式中，點選 發送 按鈕。如果你用的是自訂應用程式，請照平常方式發送請求。
  3. 回到整合畫面。你應該會在訊息區看到訊息開始出現。
  4. 當你看到訊息顯示工作已送到列印佇列時，恭喜你！你已經成功透過 Integration Passthrough 系統發送請求並列印標籤。

疑難排解

結果和你預期的不一樣嗎？以下是你可能會遇到的一些常見問題。

SSL 對等憑證或 SSH 遠端金鑰不正確

第一次發送請求時，會出現這個錯誤（下圖來自 Insomnia）：

integration_passthrough_SSL_validation.png

這個錯誤通常是因為你使用了自簽名憑證。只要關閉 SSL 驗證，然後重新發送請求即可。

404 Not Found

發送請求時，你會在 Integration Passthrough 服務的回應中看到以下錯誤訊息（下圖來自 Insomnia）：

integration_passthrough_404_response.png

這個錯誤常見的原因如下：

這個錯誤可能表示整合本身沒有啟動。當 Passthrough 嘗試轉發資訊時，沒有整合來接收它。Passthrough 服務會認為 URL 不正確，並回覆 404 Not Found。請確保你先啟動整合，再傳送資料給它。

這個錯誤也可能表示 targetURL 參數遺漏或不正確。請參考設定請求區段，確認你的 URL 是否正確，以及如何找到整合 URL。

此外，這個錯誤也可能表示 Integration Passthrough 沒有啟用。請參考Integration Passthrough 區段，了解如何設定。

資料以 %變數名稱% 顯示，而不是實際值

在你的標籤上，可能會看到帶有 % 的值，而不是實際的資訊。% 符號代表整合中的變數。如果整合沒有對應的值可以填入這些變數，就會直接印出變數名稱。

發生這種情況時，通常是你在網路請求應用程式中輸入的值（左側）拼寫錯誤或遺漏。這些值必須和整合中列出的變數名稱一致。這些變數可以在「列印文件」動作的「命名資料來源」分頁中找到。如下圖所示，Insomnia（黑色）中的值和整合（白色）中的變數名稱一致：

integration_passthrough_values_match.png

POST 範例中的 JSON 資料也是一樣的道理。

僅限 GET 請求，如果你發現命名資料來源已正確設定且與你傳送的資料相符，但仍然只看到變數名稱，請檢查你放資料的位置。如果你把資料放在 Header 區段（無論是 Insomnia 還是 Postman），這些資料不會經過 Integration Passthrough 服務。請回到設定請求區段，確認你把資料放在正確的位置。

整合錯誤

遇到整合錯誤嗎？請參考這份詳細指南：疑難排解指南：整合問題

相關文章