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

搜尋

此段落內的文章

BarTender REST API 概觀

Samantha Petro

BarTender Content Team

  • 更新於

概觀

BarTender 2022 引進了 RESTful API，讓您可以使用 REST 呼叫自動執行列印工作。REST API 是應用程式和系統透過網路或網際網路相互交換資料的最新方法。REST API 要求會執行伺服器型資源的功能以變更資源的狀況/形式/狀態，也會執行相關的伺服器端動作。如果您使用過 Print Portal REST API 或任何其他 REST API，您可能會發現這種 API 呼叫風格非常熟悉。 與前述 API 不同的是，這種 API 呼叫的功能更類似於 Integration Builder 或 Process Builder 動作。

BTRESTAPI.png

適用於

BarTender 2022 及更新版本

自動化版或更高版本

資訊

REST API 需求

  • 版本編號：BarTender 2022 R1 及更新版本
  • 版本名稱：自動化版或企業版
  • 傳送應用程式：自訂、Swagger、Insomnia、Postman
    • 支援 IWA、NTLM 和基本驗證
    • 支援 CORS
    • 自訂應用程式支援 Curl、C# 和 .NET 語言
  • 安裝 BarTender 以接收指令

API 作業使用連接埠 5159，因此需要開啟此連接埠，以便 API 可以接收 REST 指令。

安全性

REST API 支援多種類型的驗證

  • 基本驗證
  • 整合式 Windows 驗證 (IWA)
  • Windows 挑戰/回應 (NTLM)

依預設，基本驗證為停用狀態。

使用 Insomnia 或 Postman 傳送要求時，請將驗證設定為 NLTM。

使用 IWA 時，傳送 REST 要求的帳戶需要具有下列屬性：

  • 傳送要求的使用者必須具有登入伺服器的權限
  • 使用者必須具有 Administration Console 中設定的管理整合權限

使用基本驗證

依預設，基本驗證為停用狀態。若要啟用，請執行下列步驟：

  1. 瀏覽至 C:\Program Files\Seagull\BarTender 2022\net5.0。
  2. 找到 appsettings.json。
  3. 向下捲動至底端附近的 AuthenticationSchemes，並將 Basic 從 False 變更為 True。
  4. 儲存檔案。
  5. 開啟 Administration Console。
  6. 瀏覽至左側功能表上的「Windows 服務」，然後重新啟動 BarTender Integration Service。

透過 HTTPS 傳送

REST API 建置在 Windows 的 HTTP 伺服器 (Http.sys) 上。但是，您可以將 REST API 設定為使用 HTTPS 來保護您的連線安全。這僅適用於內部 RESTful 要求，目前不適用於外部要求。

就像針對整合設定 HTTPS 一樣，會從 Print Portal 退回 REST 要求。在此程序中，您需要來自憑證授權單位的 SSL 憑證或自我簽署 SSL 憑證。

  1. 首先，使用 SSL 憑證透過 HTTPS 保護 Print Portal 安全。
  2. 將所有 RESTful 呼叫導向至 https://localhost/Bartender/api/actions。視需要將 localhost 取代為伺服器名稱或 IP。

REST API 指令

BarTender REST API 僅使用三個 REST 指令：POST、GET 和 PATCH。從下表可以大致了解每個指令如何與 API 互動。

HTTP

URL 路徑

  

POST

/api/actions

提交指令碼以在伺服器中執行

GET

/api/actions/{id}

取得執行中指令碼的狀態和訊息

PATCH

/api/actions/{Id}

取消或變更指令碼的屬性

GET

/api/actions

取得提交給伺服器的指令碼清單

GET

/api/actions/{Id}/variables

擷取與指令碼關聯的變數

GET

/api/actions/{Id}/variables/{VariableName}

擷取與指令碼關聯的特定變數的值

ID 用於與目前部署的任何動作搭配使用。當您 POST 指令碼時，如果 API 接受了該指令碼，則會將 ID 包含在回應中。 如果指令碼在 API 伺服器上一直處於作用中狀態，ID 會持續存在。依預設，該持續時間為 60 分鐘，但您可以在 POST 訊息中變更此設定。

您可以使用 GET 擷取的變數類似於整合中的變數。 您可以擷取整合變數和全域變數以及透過 POST 動作建立的任何區域變數。您擷取的值將與您提交的指令碼 ID 相關。

POST 指令碼

您可以使用 POST 指令讓 BarTender 執行各種動作，並在提交 POST 後讓這些動作保持執行狀態。依預設，動作會持續執行 60 分鐘，但您可以變更該時間。

您可以透過 POST 讓 BarTender 執行各種所需動作。如果您使用過 Integration Builder 或 Process Builder，下列動作類別應該看起來相對熟悉，因為它們與這兩個應用程式使用的指令類型相同。下面是類別清單：

  • 列印動作 - 列印文件、命令指令碼、BTXML 指令碼
  • 輸入動作 - 讀取檔案、接聽序列埠等
  • 輸出動作 - 將訊息寫入日誌、傳送 Web 服務要求等
  • 執行動作 - 設定變數、執行 Shell 指令等
  • 檔案動作 - 建立資料夾、複製檔案、刪除檔案等
  • 轉換動作 - 搜尋和取代動作、搜尋和刪除等
  • 資料庫動作 - 執行 SQL、將文字轉換為記錄集、針對每一筆資料庫記錄等 (請參閱下面的「資料庫動作」一節)

傳送 POST 時，這些動作可以用 BTXML 指令碼、YAML 或 JSON 編寫。 如果您具有有效的 BTXML 整合，則使用 BTXML 可能是您最快的轉換方式。下面是列印 BTXML 指令碼的範例：

Printer_Tag.png

如果您以前使用過 REST API、正在建立新的 API 介面，或者只是更熟悉 JSON 或 YAML，則該 API 也可以接受這些呼叫。 它們比 BTXML 更簡單、更容易閱讀。下面是這兩種格式的一些範例：

REST_yaml_json.png

如果您不熟悉 YAML，隨 BarTender Suite 安裝的說明文件有 YAML 說明文件。

提交 POST 後，API 會傳回回應。此回應會包含一個狀態碼，告訴您是否已接受指令碼。您需要尋找代碼 201，它表示已接受指令碼並排定執行。如果您收到成功回應，指令碼的 ID 也會包含在回應中。

但是，如果您收到其他回應，則需要診斷問題，相關資訊請參閱說明文件中列出每個回應碼的完整清單。下面的「API 參照」一節列出了說明文件的位置。

資料庫動作

使用資料庫動作時，您必須指定資料庫連線。 與整合不同，您無法透過動作上的對話方塊來指定此連線。 您需要透過動作的其中一個屬性來指定。

若要設定連線，您需要一個連線檔案來告訴 API 您的需求。此連線檔案會定義資料庫連線以及您指定的任何設定 (例如，自訂 SQL 或別名)。 

若要建立資料庫連線檔案，請先透過連線到資料庫，在 BarTender Designer 中設定連線。建立連線後，如果資料庫對話方塊未開啟，請前往「檔案」>「資料庫連線設定」將其開啟。按一下對話方塊底端的「匯出」按鈕。

2022_export_db.png

這會以 XML 格式儲存連線資訊。您的使用者名稱、密碼和其他身分識別資訊會被模糊化，並且不會以純文字形式儲存。

取得該檔案後，您可以在任何使用資料庫連線的動作的 ConnectionSetup 屬性中使用該檔案。該連線僅適用於該特定動作，因此請為您使用的每個動作設定一個連線。

API 參照

說明文件中有幾個地方可以協助您輕鬆入門。說明文件位於 BarTender Designer 中或線上。 開啟 Designer 後，可以關閉快顯視窗並前往「說明」>「BarTender 說明」。下面是尋找 REST API 說明文件的關鍵位置：

BTXML 參照

如果您使用 BTXML 提交指令碼，則可以在 BarTender 的說明檔案中找到完整的 BTXML 指令碼參照：

rest_api_btxml.png

您可以在這裡找到 BTXML 的介紹，以及含有完整標記清單的完整參照。

YAML 和 JSON 參照

雖然 YAML 和 JSON 之間的格式可能略有不同，但它們都使用相同類型的變數和設定。說明檔案中 BarTender 的 YAML 參照包含您可以使用的所有變數、指令碼和呼叫的詳細清單。您可以在這裡找到這些內容。

當您開啟 YAML 參照時，您可以找到 API 中所有可用動作的清單 (依動作類型分組)，以及每個動作的簡短說明。 按一下動作會將您帶到一個頁面，其中列出了每個動作的所有可用屬性和實務範例。

rest_api_yaml2.png

YAML 參照的首頁還列出了如何將動作組合成群組，以及如何建立要當作單一指令碼傳送至 API 的動作陣列。

ReDoc

ReDoc 是可以與 API 搭配使用的兩個工具之一。它包含範例、關於每種指令類型的簡要資訊，以及您可能收到的回應模式清單和每種模式的含義。

您可以在 hostname:5159/api/actions/reference/index.html 中找到 ReDoc，其中 hostname 是主控 BarTender 的電腦的名稱。當您在瀏覽器中輸入此 URL 時，您會看到 API。

對於每個 API 指令，您可以透過向下捲動頁面，或使用左側功能表找到所選指令。當您瀏覽至某個指令時，右側列會隨著捲動，並具有可用於查看範例 API 呼叫和回應的互動式區段。

對於 POST，您會看到範例 BTXML。您可以變更內容類型以在 BTXML、YAML 和 JSON 之間交換格式。一些範例有第二個下拉式功能表，其中包含其他範例。下面是選取了 JSON 範例的 POST 指令的螢幕擷取畫面。

rest_api_redoc2.png

在範例和範例工作方式的說明下方是從 API 傳回的可能回應的清單。API 使用常見的 HTTP 回應碼，雖然每個回應碼都已經過自訂以表示 API 的特定含義，例如指令碼格式錯誤或用戶端不是經過驗證的使用者。

每種類型的指令都有一組不同的回應碼，它們採用顏色編碼來指示指令是否成功。您可以展開綠色部分來查看成功回應碼中的內容。下面是 POST 的回應範例：

rest_api_redoc3.png

Swagger

Swagger 是隨 BarTender Suite 安裝一起提供的 API 參照和工具。它包含完整的指令碼和 REST 指令參照，並具有能夠測試指令碼的額外好處。

注意：Swagger 是一個強大的工具，但它並沒有涵蓋 Insomnia 或 Postman 所具有的所有功能。其使用案例僅限於實驗和學習 API。

您可以在 hostname:5159/swagger 中找到 Swagger，其中 hostname 是主控 BarTender 的電腦的名稱。當您在 Web 瀏覽器中輸入此網址時，它會顯示說明文件的首頁。

rest_api_swagger.png

對於每個指令，您可以按一下將其展開，以顯示簡短說明和測試工具。按一下右側的「試試看」按鈕時，可以編輯要傳送至伺服器的值。對於 Swagger，您可以使用含有自訂指令碼的文字檔案，也可以依據底端要求內文中的範例進行建置。

rest_api_swagger2b.png

編輯完這些值並感到滿意後，向下捲動並按一下較大的藍色「執行」按鈕。這會將指令碼傳送至伺服器，而伺服器會傳回回應。例如，下面是從 POST 指令傳回的成功回應：

rest_api_swagger3.png

與 ReDoc 非常相似，REST 工具下方也有一個回應清單。該清單列出了所有可能的回應碼和簡要說明。成功的回應碼還會含有可能傳回的內容的範例。

您可以將 Swagger 當作測試指令碼的工具使用，確保指令碼在用於生產環境前能夠正常運作。Swagger 是使用系統的視覺化呈現形式即時疑難排解和檢查回應模式的好工具。

相關文章