Search

工作流 API

Version 24.3.9111

工作流 API

知行之桥工作流 API 使你能够创建模块化的单路径工作流，并将它们公开为可以查询的接口。知行之桥处理你传递给工作流 API 接口的数据，并将结果返回给你的查询服务。

你可以使用工作流 API 从外部应用程序和服务运行知行之桥工作流。这种灵活性使你能够使用自己选择的工具来管理工作流和自动化。

视频资源

观看此短视频，了解如何设置和使用 Flow API。

创建工作流 API

通过以下步骤创建工作流 API：

  1. 在知行之桥的“工作区”页面中，在端口上单击右键并选择 创建工作流 API。

    注意： 工作流 API 目前不支持某些端口。当你尝试将不支持的端口添加到流API时，知行之桥会显示一条错误消息。

  2. 出现 创建工作流 API 设置 模态框。在 方法 字段的下栏菜单中选择你希望工作流 API 接受请求的 HTTP 方法。选项有 GET、POST、PUT、PATCH、和 DELETE。在创建工作流 API 之后，你可以根据需要对此进行更改。

  3. 在 路径 列输入工作流 API 的名称。这个名称将被用于 API 查询。

    注意： 只有当工作流 API 执行不同的功能时，才可以使用重名。例如，你可以有一个名为 API_X12 的执行 POST 功能的工作流 API 和一个名为 API_X12 的执行 PATCH 功能的工作流 API，但是你不能有两个名为 API_x12 且都执行 POST 功能的工作流 API。

  4. 点击 创建工作流API。你的工作流 API 将会出现在工作区。

  5. 将附加端口拖到工作流 API 框中，并将它们连接在一起。还可以向工作流 API 框添加注解。

注意：工作流 API 中的第一个端口从发出查询的实体接收输入数据，最后一个端口将输出数据发送回发出查询的实体。

当你完成添加和链接端口时，你可以配置和测试你的工作流API。

不支持的端口

工作流 API 中的端口必须以一种方式连接，从而为每个输入消息产生一个输出消息。不支持基于计划或外部进程处理文件的端口。因此，在工作流 API 中不允许使用以下端口:

工作流 API 示例

以下示例显示了一个配置后的工作流 API 的真实用例：

此工作流 API 运行以下工作流：

  1. 数据在开始节点以加密的 X12 文件的形式接收。

  2. OpenPGP_Decrypt 端口解密 X12 文件，并将其传递给 X12 端口。

  3. X12 端口将 X12 文件转换为 XML，并将转换后的 XML 文件传递给 JSON 端口。

  4. JSON 端口将 XML 文件转换为 JSON 格式，并将转换后的文件传递给 OpenPGP_Encrypt 端口，后者对 JSON 文件进行加密。

  5. 加密的 JSON 文件通过结束节点返回。

在本例中，每个端口都链接到另外两个端口，一个在前面，一个在后面。开始和结束节点会自动添加到流的接口。

配置和测试工作流API

创建工作流 API 后，你可以配置其设置并运行示例请求来测试你的配置。

配置

单击工作流 API 标题中的齿轮状图标，以打开设置面板。

在此面板中，你可以配置你的工作流 API 的行为。

这些设置在下面的章节中概述。

请求

在 路径 字段中，你可以选择工作流API的请求类型。如果更改请求类型，请确保端口的结构和配置对于新的请求类型是正确的。

在 说明 字段中输入关于工作流API的可选描述。当你有多个工作流API并且想要跟踪每个流API的用途时，这可能会很有用。

请求参数

此部分使你能够为工作流指定查询字符串参数。如果你在此处添加参数，当消息沿工作流向下传递时，它们将作为元数据头保留下来。这些头使用前缀 API-QueryParameter-，因此 test 的查询字符串将使用 API-QueryParameter-test。当你在端口的输入或输出选项卡上选择消息时，可以在 消息内容 模态框上看到此标题。

如果你希望将信息作为请求的一部分传递，但该信息不是请求体的一部分，那么这个特性会很有用。例如，如果你想要查询数据库中特定公司的最近销售订单的ID，你可以将 CompanyName 查询参数添加到你的 API 中，并使用 API-QueryParameter-CompanyName 头在流中引用它。

主体和响应

在主体部分中，将类型字段设置为与你期望的数据类型:

  • None—请求中没有预期的主体
  • Raw—任意格式的自由格式数据
  • Form data—表单数据-名称-值对
  • x-www-form-urlencoded

在 主体 和 响应 的文本字段中，可以使用下拉菜单选择正文和响应的预期数据格式(XML、JSON或Custom)。

测试工作流API

要打开工作流 API 的测试模态框，请单击工作流 API 标题中的三角形图标。

在测试模态框中，左边的框充当请求，右边的框显示响应。每个框以设置面板中选择的数据格式显示数据。

要测试你的工作流 API，请在左侧的框中输入一个测试查询，然后单击 运行 按钮。如果响应与预期的结果匹配，那么你的工作流 API 就可以使用了。如果响应不正确，请检查你的工作流 API 的配置以及工作流 API 中每个端口的配置。

将 Flow API 与外部应用程序一起使用

以下步骤说明了如何从外部客户端调用 Flow API。 此示例展示了如何从 Postman 执行 Flow API，但你也可以使用任何可以发送 REST 请求的客户端。

  1. 通过使用工作流设计器右下角的 选择多个端口 选项，选择你想要公开为 API 的工作流。 然后，单击 创建 API 设置。 此操作会打开 创建 API 设置 对话框。

  2. 选择一个方法（例如，POST），如下所示，并为你的 API 起一个有意义的名称。

    Select a method

  3. 点击 创建 API 创建一个工作流 API。

  4. 在 设置 窗口中，配置工作流 API 以在 Body 部分和 Content-Type 中定义预期的希望在 Response 部分中响应的 Content-Type 值。 作为一种选择，可以为请求和响应提供示例数据。

  5. 复制出现在 请求 窗口中的路径，如下所示。

    The path in the Request pane

  6. 打开 Postman 应用程序，确保相同的内容类型（在本例中为 POST）出现在 Content-Type 下拉列表中。 然后，将在知行之桥（第 5 步）中复制的路径粘贴到请求 URL 字段中。 将请求的正文指定为应该启动流程的内容。

    Copy and past the Content-Type path

  7. 工作流 API 身份验证。 工作流 API 使用与 Admin API 相同的身份验证规则。 此示例使用身份验证令牌消息头 (x-cdata-authtoken) 作为身份验证方法。

    要使用该方法：

    1. 点击导航栏上的系统设置齿轮图标。然后点击添加以打开添加用户对话框或编辑现有用户。

    2. 在出现的对话框中，选中复选框 API Access 以显示身份验证令牌。 （将此令牌复制到安全的地方，因为该对话框将不会再次显示。如果丢失或删除了你的身份验证令牌，则必须创建一个新令牌。）然后，单击 保存更改。

    3. 返回 Postman 应用程序并添加工作流 API 的身份验证凭据，如下所示：

      1. 点击Headers标签。

      2. 把x-cdata-authtoken粘贴到Key字段中。

      3. 将在 中复制的身份验证令牌粘贴到 Value 字段中。

  8. 一旦你的请求准备就绪，请点击发送按钮。 然后，应该会看到对发送的请求的响应，如下例所示：

    Response to the request

跨源资源共享（CORS）

可以导航到设置页面的系统 API 选项卡，为 Flow API 配置跨域资源共享 (CORS)。。 CORS 允许基于浏览器的客户端连接到知行之桥。 如果没有 CORS，基于浏览器的脚本将无法连接到知行之桥，因为浏览器强制执行同源策略。 此策略限制客户端脚本和文档加载其来源之外的资源。 脚本的来源由协议、主机和端口组成。

  • 启用跨源资源共享 (CORS) 是否启用 CORS。 仅当选中此框时，其余选项才可用。
  • 允许所有不带 ‘*’ 的域 如果启用，域来源不限于特定列表。
  • Access-Control-Allow-Origin 要允许的以逗号分隔的域来源列表。 作为 HTTP 响应消息头包含在内。
  • Access-Control-Allow-Credentials 跨域请求中是否允许用户凭据（例如 cookie）。 作为 HTTP 响应消息头包含在内。
  • Access-Control-Allow-Methods 允许的以逗号分隔的方法列表。 作为 HTTP 响应消息头包含在内。
  • Access-Control-Allow-Headers 允许的消息头的逗号分隔列表。 作为 HTTP 响应消息头包含在内。
  • Access-Control-Max-Age 可以缓存 Access-Control 响应消息头值的最大持续时间（以秒为单位）。