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

搜尋

此段落內的文章

BarTender REST API 概述

Samantha Petro

BarTender Content Team

  • 更新於

概述

BarTender 2022 引入了一個 RESTful API，讓您可以透過 REST 呼叫自動化列印工作。REST API 是現代應用程式和系統透過網路或網際網路彼此交換資料的方式。請求會執行伺服器端資源的功能，這些功能可以改變其狀態、形式或狀態，同時也能執行相關的伺服器端操作。如果您曾經使用過 Print Portal REST API 或其他 REST API，這種 API 呼叫方式應該會讓您感到很熟悉。不過，與前述 API 不同，這些 API 呼叫的運作方式更接近於 Integration 或 Process Builder 的動作。

BTRESTAPI.png

適用對象

BarTender 2022 及以後版本

Automation 版本或更高版本

資訊

REST API 需求

  • 版本：BarTender 2022 R1 及以後版本
  • 版本：Automation 或 Enterprise 版本
  • 發送應用程式：自訂、Swagger、Insomnia、Postman
    • 支援 IWA、NTLM 和基本驗證
    • 支援 CORS
    • 自訂應用程式支援 Curl、C# 和 .NET 語言
  • 需安裝 BarTender 以接收指令

API 使用 5159 埠運作，因此必須開啟此埠，API 才能接收 REST 指令。

安全性

REST API 支援多種驗證方式

  • 基本驗證（Basic Authentication）
  • 整合式 Windows 驗證（IWA）
  • Windows 挑戰/回應（NTLM）

預設情況下，基本驗證是關閉的。

使用 Insomnia 或 Postman 發送請求時，請將驗證方式設為 NTLM。

使用 IWA 時，發送 REST 請求的帳戶需要具備以下條件：

  • 發送請求的使用者必須有權登入伺服器
  • 使用者必須擁有在管理主控台中設定的整合管理權限

啟用基本驗證

基本驗證預設為關閉。若要啟用，請依照下列步驟操作：

  1. 前往 C:\Program Files\Seagull\BarTender 2022\net5.0（若使用最新版本則為 \net6.0）。
  2. 找到 appsettings.json。
  3. 往下捲動至接近底部的 AuthenticationSchemes，將 Basic 的值從 false 改為 true（必須全部小寫）。
  4. 儲存檔案。
  5. 開啟 管理主控台。
  6. 在左側選單中點選 Windows 服務，然後重新啟動 BarTender Integration Service。

在您的客戶端應用程式中設定基本驗證時，您需要提供 Windows 帳號密碼才能存取 BarTender REST API。

透過 HTTPS 傳送

REST API 建立於 Windows 的 HTTP 伺服器（Http.sys）之上。不過，您也可以將 REST API 設定為使用 HTTPS，以確保連線安全。

設定 HTTPS 的方式與整合設定 HTTPS 類似，您需要透過 Print Portal 轉送 REST 請求。這個過程需要一張 SSL 憑證，可以是憑證授權單位簽發的，也可以是自簽憑證。

  1. 首先，請使用您的 SSL 憑證將 Print Portal 設定為 HTTPS。
  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。這個 ID 只會在腳本於 API 伺服器上處於活動狀態時有效。預設為 60 分鐘，但可以在 POST 訊息中更改。

您可以透過 GET 取得的變數，就像整合中的變數一樣。您可以取得整合變數、全域變數，以及透過 POST 動作建立的任何本地變數。取得的值會與您提交的腳本 ID 相關。

POST 腳本

使用 POST 指令時，您可以指示 BarTender 執行各種動作，並在提交後讓這些動作持續執行。預設情況下，一個動作會持續 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 套件安裝的說明文件中有 YAML 的相關說明。

提交 POST 後，API 會回傳一個回應。這個回應會包含狀態碼，告訴您腳本是否被接受。您要找的是 201 這個狀態碼，代表腳本已被接受並排程執行。如果收到成功回應，回應中也會包含腳本的 ID。

如果收到其他回應，說明文件中有完整的回應碼清單，方便您排查問題。說明文件的位置請參考下方 API 參考章節。

資料庫動作

使用資料庫動作時，您需要指定資料庫連線。與整合不同，這裡無法透過動作對話框指定，而是要在動作的屬性中設定。

要設定連線，您需要一個連線檔案，告訴 API 您要連線的內容。這個連線檔案會定義資料庫連線，以及您指定的設定，例如自訂 SQL 或別名。

建立資料庫連線檔案時，請先在 BarTender 設計師中設定好資料庫連線。連線完成後，如果資料庫對話框未開啟，請到 檔案 > 資料庫連線設定 開啟。對話框底部點選 匯出 按鈕。

2022_export_db.png

這樣會將連線資訊以 XML 格式儲存。您的使用者名稱、密碼及其他識別資訊都會經過遮蔽，不會以明文儲存。

取得檔案後，您可以在任何需要資料庫連線的動作的 ConnectionSetup 屬性中使用。每個動作都需要各自的連線設定，請為每個動作分別設定。

API 參考

說明文件中有多個地方可以協助您快速上手。說明文件可在 BarTender 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 的電腦名稱。用瀏覽器前往這個網址，就能看到 API 介面。

所有 API 指令都可以在頁面中往下捲動找到，或用左側選單快速跳到想查的指令。進入每個指令後，右側欄位會隨著您捲動，並有互動區塊可查看 API 呼叫與回應範例。

對於 POST，會顯示 BTXML 範例。您可以切換內容類型，選擇 BTXML、YAML 或 JSON 格式。有些範例還有下拉選單可切換更多範例。以下是選擇 JSON 範例時的 POST 指令截圖：

rest_api_redoc2.png

在範例和範例運作說明的下方，會列出 API 可能回傳的各種回應。API 採用常見的 HTTP 回應碼，但每個回應碼在這裡都有特定的意義，例如腳本格式錯誤或用戶未經驗證等。

每種指令類型都有不同的回應碼，並以顏色區分指令是否執行成功。綠色的回應碼可以展開，查看成功回應的內容。以下是 POST 指令的回應範例：

rest_api_redoc3.png

Swagger

Swagger 是一個 API 參考工具，隨 BarTender 套件安裝包一起提供。它包含完整的腳本和 REST 指令參考，還能用來測試腳本，非常方便。

Swagger 是一個強大的工具，但它無法涵蓋 Insomnia 或 Postman 的所有功能。它主要適合用來嘗試和學習 API 的操作。

你可以在 hostname:5159/swagger 找到 Swagger，其中 hostname 是安裝 BarTender 的電腦名稱。只要在瀏覽器輸入這個網址，就會看到文件首頁。

rest_api_swagger.png

每個指令都可以點擊展開，會顯示簡短說明和測試工具。點選右側的 Try it Out 按鈕後，你可以編輯想要傳送到伺服器的值。對於 Swagger，你可以使用包含自訂腳本的文字檔，或直接在下方的請求內容範例中修改。

rest_api_swagger2b.png

編輯好內容並確認無誤後，往下捲動並點擊大大的藍色 Execute 按鈕。這樣就會將腳本送到伺服器，伺服器會回傳結果。

例如，這是一個 POST 指令成功回應的範例：

rest_api_swagger3.png

和 ReDoc 一樣，在 REST 工具下方也有一份回應列表，列出所有可能的回應碼及簡要說明。成功的回應碼還會附上可能回傳的範例內容。

你可以利用 Swagger 來測試腳本，確保它們能正確運作再投入正式環境。這是個很好的工具，可以用來即時排解問題，並透過視覺化方式檢查系統的回應模式。

相關文章