概述

BarTender 2022 中引入了 RESTful API，允许您使用 REST 调用来自动执行打印作业。REST API 是一种现代方法，应用程序和系统使用该方法通过网络或 Internet 相互交换数据。REST API 请求会执行基于服务器的资源的功能，从而更改资源的状态/形式/状况，也会执行相关的服务器端操作。如果您使用过 Print Portal REST API 或任何其他 REST API，那么可能会对这种风格的 API 调用感到非常熟悉。 但是，这种 API 调用的功能与前述 API 不同，更类似于 Integration Builder 操作或 Process Builder 操作。

适用范围

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 来保护集成非常相似，REST 请求会从 Print Portal 退回。此过程需要来自证书颁发机构的 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 交互的概述。

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

如果您以前使用过 REST API，如果您正在创建一个新的 API 接口，或者如果您只是对 JSON 或 YAML 更熟悉，那么该 API 也可以接受这些调用。 它们比 BTXML 更简单、更易于阅读。下面是这两种格式的一些示例：

提交 POST 后，API 会发回响应。此响应将包含一个状态代码，用于指示脚本是否被接受。您需要找到代码 201，它表示脚本已被接受并计划运行。如果您收到成功响应，响应中还将包含脚本的 ID。

但是，如果您收到其他响应，可以参考帮助文档中的完整响应代码列表来诊断问题。有关该帮助文档的位置，请参阅下面的“API 参考”部分。

数据库操作

使用数据库操作时，需要指定数据库连接。 与集成不同，无法通过操作的对话框来指定此连接。 只能在操作的某个属性中指定。

要配置连接，需要有一个连接文件来告诉 API 您的需求。此连接文件会定义数据库连接以及您指定的任何设置（如自定义 SQL 或别名）。 

要创建数据库连接文件，首先在 BarTender Designer 中通过连接到数据库来设置连接。建立连接后，如果数据库对话框未打开，请转至“文件”>“数据库连接设置”将其打开。在对话框底部，单击“导出”按钮。

这将以 XML 格式保存连接信息。您的用户名、密码和其他身份识别信息会被模糊化，并且不会以纯文本形式保存。

获得该文件后，您可以在使用数据库连接的任何操作的 ConnectionSetup 属性中使用该文件。连接是操作特定的，因此请为您使用的每个操作设置一个连接。

API 参考

有关如何开始使用 API 的信息，请参阅帮助文档中的相应部分。您可以在 BarTender Designer 中或在线找到帮助文档。 要查看帮助文档，请在打开 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 之间交换格式。一些示例有第二个下拉菜单，其中包含其他示例。下面是 POST 命令的屏幕截图，其中显示的是 JSON 示例。

在示例和示例工作原理的描述下方是从 API 发回的可能响应的列表。API 使用常见的 HTTP 响应代码，但每个响应代码都已经过定制以表示特定于 API 的某种情况，例如脚本格式错误或客户端不是经过身份验证的用户。

每种类型的命令都有一组不同的响应代码，它们被编码为不同的颜色来指示命令是否成功。将绿色的代码条目展开后，可以看到成功响应代码中的内容。下面是 POST 的响应示例：

Swagger

Swagger 是随 BarTender Suite 安装一起提供的 API 参考和工具。它包含完整的脚本和 REST 命令参考，还可用于测试脚本。

您可以在 hostname:5159/swagger 中找到 Swagger，其中 hostname 是托管 BarTender 的计算机的名称。在 Web 浏览器中输入此地址后，您会看到说明文档的首页。

您可以单击每个命令将其展开，以显示简短描述和测试工具。单击右侧的“试试看”按钮时，可以编辑要发送到服务器的值。对于 Swagger，您可以使用包含自定义脚本的文本文件，也可以基于底部请求正文中的示例进行构建。

编辑完这些值并感到满意后，向下滚动并单击较大的蓝色“执行”按钮。这会将脚本发送到服务器，然后服务器会发回响应。例如，下面是从 POST 命令返回的成功响应：

与 ReDoc 非常相似，REST 工具下方也有一个响应列表。该列表会列出所有可能的响应代码和简要描述。成功的响应代码还将包含有关可能返回哪些内容的示例。

您可以使用 Swagger 作为测试脚本的工具，以确保脚本在进入生产环境之前能够正常工作。Swagger 是使用系统的可视化表示形式实时排除故障和检查响应模式的好工具。