概述

BarTender 2022 引入了 RESTful API，允许您通过 REST 调用自动化打印任务。REST API 是现代应用程序和系统通过网络或互联网相互交换数据的主流方式。请求会执行基于服务器资源的功能，可以改变其状态/形式/状态，同时也能执行相关的服务器端操作。如果您用过 Print Portal REST API 或其他 REST API，您会发现这种 API 调用方式非常熟悉。不过，与前述 API 不同，这些 API 调用的运行方式更类似于集成或流程构建器中的操作。

适用范围

BarTender 2022 及更高版本

自动化版或更高级别

信息

REST API 要求

• 版本：BarTender 2022 R1 及更高版本
• 版本：自动化版或企业版
• 发送应用程序：自定义、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 服务。

通过 HTTPS 发送

REST API 基于 Windows 的 HTTP 服务器（Http.sys）构建。不过，您可以将 REST API 配置为使用 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 交互的方式概览。

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 脚本示例：

如果您之前用过 REST API，正在创建新的 API 接口，或者更熟悉 JSON 或 YAML，API 也支持这些格式的调用。它们比 BTXML 更简洁、易读。以下是两种格式的示例：

提交 POST 后，API 会返回响应。响应中包含状态码，指示脚本是否被接受。请关注代码 201，表示脚本已被接受并计划运行。如果响应成功，脚本的 ID 也会包含在响应中。

如果收到其他响应，帮助文档中有完整的响应代码列表，方便您排查问题。文档位置见下方 API 参考部分。

数据库操作

进行数据库操作时，您需要指定数据库连接。与集成不同，不能通过操作对话框指定，而是在操作属性中设置。

要配置连接，您需要一个连接文件，告诉 API 您的需求。该连接文件定义了数据库连接及您指定的设置，如自定义 SQL 或别名。

要创建数据库连接文件，先在 BarTender 设计器中连接数据库。连接后，如果数据库对话框未打开，请进入 文件 > 数据库连接设置 打开。在对话框底部，点击 导出 按钮。

这会将连接信息以 XML 格式保存。您的用户名、密码及其他身份信息会被加密，不会以明文保存。

有了该文件后，您可以在任何使用数据库连接的操作的 ConnectionSetup 属性中使用。连接仅对该操作有效，因此每个操作都需单独设置。

API 参考

帮助文档中有多个地方可以帮助您快速上手。帮助文档可在 BarTender Designer 内找到，也可在线访问。打开设计器后，关闭弹窗，进入 帮助 > BarTender 帮助。以下是查找 REST API 文档的关键位置：

BTXML 参考

如果您使用 BTXML 提交脚本，可在 BarTender 帮助文件中找到完整的 BTXML 脚本参考：

这里有 BTXML 的介绍和完整标签列表。

YAML 和 JSON 参考

YAML 和 JSON 使用相同类型的变量和设置，格式略有不同。BarTender 的 YAML 参考在帮助文件中详细列出了所有变量、脚本和可用调用。您可以在这里找到。

打开 YAML 参考后，您会看到 API 内所有可用操作的列表，按操作类型分组，并有简要说明。点击操作可进入页面，查看该操作的所有可用属性及实际示例。

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 命令截图：

在示例和示例工作原理说明的下方，会列出 API 可能返回的响应列表。API 使用常见的 HTTP 响应码，但每个响应码在 API 中都有特定的含义，比如脚本格式错误或客户端用户未通过身份验证。

每种命令类型都有不同的响应码集合，并通过颜色区分命令是否成功。绿色的响应码可以展开，查看成功响应的具体内容。以下是 POST 命令返回的响应示例：

Swagger

Swagger 是一个 API 参考工具，随 BarTender 套件一起安装。它包含完整的脚本和 REST 命令参考，还可以用来测试脚本。

你可以在 hostname:5159/swagger 找到 swagger，其中 hostname 是托管 BarTender 的计算机名称。在浏览器中输入这个地址后，会打开文档的首页。

每个命令都可以点击展开，显示简要说明和测试工具。点击右侧的 Try it Out 按钮后，你可以编辑要发送到服务器的参数值。对于 Swagger，你可以使用包含自定义脚本的文本文件，或者直接在底部的请求体示例基础上修改。

编辑好参数并确认无误后，向下滚动，点击蓝色的 Execute 按钮。这样脚本就会被发送到服务器，服务器会返回响应。

例如，下面是 POST 命令成功返回的响应：

和 ReDoc 类似，在 REST 工具下方也有一个响应列表，列出了所有可能的响应码及简要说明。成功的响应码还会有返回内容的示例。

你可以用 Swagger 来测试脚本，确保它们在正式使用前能正常运行。它是一个很好的排查工具，可以通过可视化界面实时查看系统的响应模式。