跳到主内容
Deutsch English (United States) Español Français 日本語 繁體中文

搜索

此组别内的文章

查看更多

创建安全的 Web 服务集成

Samantha Petro

BarTender Content Team

  • 更新
随着 BarTender 2022 R5 的发布，BarTender 原生支持了 HTTPS。关于如何在 Integration Builder 中启用 HTTPS，请参阅本指南。

概述

Web 服务集成是一种通过 Web 请求自动化打印的好方法。这些请求通常通过 HTTP 进行，但 HTTP 并不安全。那么，是否可以通过 HTTPS 发送这些请求，从而保护 Web 请求中的数据呢？

答案是可以的，不过不能直接通过 Integration Builder 或管理控制台实现。你需要将 Web 请求发送到 BarTender 的 Web 应用程序——BarTender Print Portal。BarTender Print Portal 提供了安全的 Integration Passthrough 功能，可以将 Web 服务请求转发到同一系统上监听的集成服务。

注意：这种方法与之前的版本略有不同，如果你是从 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
  • 一个用于发送 Web 请求的应用程序。本教程以 Postman 和 Insomnia 为例，你也可以选择其他工具。

此外，以下是本示例用到的示例文件：

启用 HTTPS

为了让 Integration Passthrough 的连接更加安全，你必须在 BarTender Print Portal 上绑定 HTTPS。这需要在 IIS 管理器中完成。

微软有一份详细的如何为网站配置 HTTPS的操作指南。默认情况下，BarTender Print Portal 在 IIS 管理器的站点列表中显示为 BarTender。该指南介绍了如何创建和使用自签名证书。如果你有来自证书颁发机构的证书，也可以按照相同步骤（跳过自签名证书部分）来使用你的证书。

绑定完成后，你会在站点绑定列表中看到 HTTP 和 HTTPS 都已列出，如下图所示：

integration_passthrough_bindings.png

无需重启站点或系统。绑定设置后会立即生效。

开启 Integration Passthrough

Integration Passthrough 是 BarTender Print Portal 配置文件中的一个设置。默认情况下，该设置是关闭的，所以如果你现在尝试发送 Web 请求，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. 在右侧操作列表中点击停止，稍等片刻后再点击启动。

配置集成

集成本身的设置与其他 Web 服务集成类似。以下是每种 Web 服务请求类型的简要设置说明：

GET

  • 标签文件必须使用命名数据源。
  • 集成必须在“打印文档”操作中覆盖命名数据源。
  • 单条记录作为请求 URL 的一部分发送。

POST

POST 请求有两种不同的设置方式，取决于你发送多少条记录。

如果只发送一条记录，可以像 GET 请求一样设置集成和标签文件。数据会放在请求体中，而不是 URL。

如果要发送多条记录，设置如下：

  • 标签文件连接到文本数据库，如 JSON 或 CSV。
  • 集成在“打印文档”操作中覆盖数据库，使用 %EventData%。
  • 一条或多条记录以与标签连接的文本数据库相同的格式作为请求体发送。

在本示例中，示例文件是一条记录，可以通过 GET 或 POST 请求发送。这是比较常见且最简单的设置方式。

如需了解更多信息和排查方法，可以参考以下文章：

解压示例文件

请按照以下步骤解压并设置示例文件：

  1. 下载示例包：TempIntegration.zip 
  2. 将集成和标签文件解压到 C:\TempIntegration\ 
  3. 打开集成文件
  4. 点击 打印文档 操作，然后切换到 打印选项 标签页。
  5. 将打印机更改为你系统上的某台打印机。

配置请求

本节需要使用 Insomnia、Postman 或类似应用来发送 Web 请求。无论是 POST 还是 GET，请求的 URL 都需要集成的 URL。你可以在 Integration Builder 的服务部分找到该 URL。下图为示例集成文件的截图，黄色高亮部分即为集成 URL：

integration_passthrough_url.png

如果你之前用过 Web 服务集成，这个 URL 应该很熟悉。通常情况下，发送 Web 服务请求时，你会将请求发送到这个完整的 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 发送 Web 服务集成请求的基础 URL 如下。此前无需额外参数指定集成 URL。 
http://localhost/BarTender/API/Integration/WebServiceIntegration/Execute

创建 GET 请求

GET 请求会将所有信息放在 URL 中。通常是通过填写 Header 信息实现。但由于 Integration Passthrough 需要 targetURL 参数，标签数据需要放在其他位置。

在 Insomnia（如下图所示）中，正确的位置是 Query。在 Postman 中，则是 Params。

integration_passthrough_get.png

如果你自己构建 URL，可以将每个参数作为键值对添加到 URL 中，用 & 分隔，如上图中的 URL 预览所示。

本示例用到的数据如下：

创建 POST 请求

POST 请求会将数据放在请求体中，而不是 URL。与 GET 请求类似，POST 请求也有 targetURL 参数，用于告知 Integration Passthrough 要将信息发送到哪里。

integration_passthrough_post.png

如果你查看了集成文件中的所有设置，可能会注意到输入数据设置为 JSON。集成可以自动解析 JSON 键值对为可用变量，无需你额外操作或添加动作。如果你只打算发送一条记录，这种方式很适合你。

本示例用到的数据如下：

  • 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 部分了解如何设置。

数据以 %变量名% 形式打印，而不是实际值

在你的标签上，可能会看到带有 % 的值，而不是实际信息。% 符号表示集成中的变量。当集成没有可用值填充这些变量时，就会直接打印变量名。

出现这种情况时，说明你在 Web 请求应用中输入的值（左侧）拼写不正确或缺失。值必须与集成中列出的变量名一致。这些变量可以在“打印文档”操作的“命名数据源”标签页中找到。如下图所示，Insomnia 中的值（黑色）与集成中的变量名（白色）一致：

integration_passthrough_values_match.png

POST 示例中的 JSON 数据也是同样的道理。

仅针对 GET 请求，如果你发现命名数据源设置正确且与发送的数据匹配，但仍然只显示变量名，请检查你放置数据的位置。如果你把数据放在 Header 部分（无论是 Insomnia 还是 Postman），这些数据不会通过 Integration Passthrough 服务传递。请返回配置请求部分，确保你把数据放在正确的位置。

集成错误

遇到集成错误？请查看这份详细指南：故障排查指南：集成问题

相关文章