调用 REST 服务

在线编辑
从 OpenAPI 规范（以前称为“Swagger”）中发现 REST 服务，并根据所发现的 REST 服务来生成外部服务。 然后，可在服务流中使用外部服务来调用 REST 服务。 有关可以集成的外部服务的示例，请参阅 概述: 集成外部服务。

关于本任务

您必须具有有效且完整的 OpenAPI 2.0（或 3.0）规范，其中包含必需的安全性定义。 OpenAPI 格式可以为 JSON 或 YAML。 要验证您的 OpenAPI 规范是否有效，请在 OpenAPI 编辑器或 Swagger 编辑器中打开该文件。

要在设计器中使用 REST 服务，请发现该服务并选择要使用的操作。 然后，设置包含调用服务所需的配置属性的服务器。 将会生成外部服务，该服务包含您在发现的服务中选择的操作以及对所选服务器的引用。 同时还会根据 OpenAPI 规范生成业务对象。

服务提供者会定期更新其服务，您可能需要重新发现已更新的服务才能使用此服务。 发现服务时，如果从同一文件中发现的外部服务已存在于设计器中，那么可以覆盖现有服务或创建新的服务。 要获取 REST 服务的更新版本，请替换外部服务。 如果外部服务包含一个服务任务，那么会保留其操作和数据映射，除非新版本中不包含操作或数据。 如果服务器连接信息保持不变，那么可保留对服务器信息的引用。

如果以下任何情况适用，那么必须调用服务，如 使用 JavaScript调用 REST 服务中所述。
  • 要使用 REST 服务，且 OpenAPI 文件（以前称为 Swagger）为其指定基本认证或 API 密钥认证以外的认证类型（作为头或查询字符串参数）。
  • 要调用 REST 服务，其中 OpenAPI 规范针对此服务包含无属性的对象。
  • 要调用指定文件或字符串/二进制类型的 REST 服务。
  • 要使用 application/json 以外的 MIME 类型、具有原语值的 application/x-www-form-urlencoded、具有原语值的数组或具有模式类型字符串的 text/plain。 请注意，不支持将类型为字符串且格式为二进制的参数与除 application/json 以外的 MIME 类型结合使用。 在运行时，将拒绝调用并显示一个异常。
  • 将属性 enum 用于数据类型 boolean、decimal、integer、string + format=date 和 string + format=date-time。
  • 使用参数类型 formData。
  • 要使用类型为 object 的数据类型，其中并非所有属性名称都是有效的 JavaScript 标识。 如果名称以字母、下划线 (_) 或美元符号 ($) 开头，并且仅包含字母、数字、下划线或美元符号，那么该名称就是有效的 JavaScript 标识。

过程

要使用 OpenAPI 规范来发现现有 REST 服务并生成可在服务流中使用的外部服务，请完成以下步骤。

  1. 通过以下方法之一创建外部服务：
    • 在库导航中的服务旁边，单击加号 (+)。选择外部服务。 在“新建外部服务”页面中，选择 Java、REST 或 Web Service。
    • 在 " 服务流 " 编辑器中，选择 服务 任务。 在服务的 实施 选项卡中，单击 新建。
  2. 选择以下某项：
    来自 URL 的 REST 服务
    输入 OpenAPI (Swagger) 文件的 URL。 例如，https://hostname:port/rest-api.json。 其中， hostname 是主机名， port 是端口号。
    来自本地文件的 REST 服务
    选择本地文件系统上的 OpenAPI (Swagger) 文件。
    提示: 您可以发现在其 OpenAPI 文件中具有 API 密钥安全性定义的 REST 服务。
    注: OpenAPI 2.0 规范允许您将头描述为 REST API 的参数。 对于某些头，OpenAPI 2.0 规范具有应使用的特殊构造，而不是将这些头描述为参数，因为 OpenAPI 3.0 将忽略这些参数：
    Content-Type
    对于请求内容类型，使用 consumes。

    对于响应内容类型，使用 produces。

    Accept
    使用 produces。
    授权
    使用 securityDefinitions或 security。
  3. 您可能会看到以下一项或两项：
    • 只可以使用脚本任务调用的操作列表。 这些操作不会包含在生成的外部服务中，因此在工具中不可供服务任务调用。 要查看原因，请单击查看解释。

      要调用这些操作，必须使用 JavaScript API。 要使这些操作可通过 JavaScript 进行调用，必须通过完成服务发现来生成外部服务。 有关更多信息，请参阅 使用 JavaScript调用 REST 服务。

      提示: 您可以在 "外部服务" 编辑器的源视图中查看操作。
    • 在 OpenAPI 规范中具有警告的操作列表。 您可以查看每个操作的警告。 如果决定运行此类操作，可能会得到意想不到的结果；无论您是通过服务任务还是脚本任务进行调用。 有关更多信息，请参阅 OpenAPI 支持调用 REST 服务
  4. 单击下一步。
  5. 将列出发现的操作。 选择要包含在外部服务中的操作，并单击下一步。
  6. 如果已发现 OpenAPI 规范，那么可创建新服务或替换现有服务。 单击下一步。
  7. 设置包含用于调用 REST 服务的属性的服务器。 选择现有服务器，或者基于 OpenAPI 规范中的信息创建新服务器。 单击完成。

结果

这样会创建外部服务。 操作及其输入和输出均取决于您在发现的 REST 服务中选择的操作。
  • 操作的输入与 OpenAPI 文件中所列的操作参数对应。 此外，对于具有 requestBody 的 OpenAPI v3 操作，将列示对应于 requestBody 的 content 的输入。 如果为此操作定义了 x-codegen-request-body-name 字段，那么其值将成为输入的名称。 否则，其名称为 body；或者，如果已存在名为 body 的参数，那么其名称为 body_n，其中 n 是正整数。
    注: x-codegen-request-body-name 是供应商扩展，由某些工具用于控制在 OpenAPI v3情况下如何命名请求主体参数。 如果 OpenAPI 定义未使用此扩展，但您想要控制输入的名称，请将供应商扩展 x-codegen-request-body-name 添加到相应操作，如以下片段所示：
    paths:
  /translateText:
    post:
      operationId: translateText
      x-codegen-request-body-name: input_parameter_name_for_body
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/translateTextInput'
        required: true
      responses:
        ...
    提示: 当您使用 JavaScript调用此操作时， x-codegen-request-body-name 字段没有相关性。

    如果 REST 服务是自动化服务，那么在其类型为复杂类型时，不会显示对应于 requestBody 的参数；而是会列出其组成部分。

  • 操作的输出与响应的对应：OpenAPI 文件中列出的每个响应代码对应一个输出。 如果 REST 服务是自动化服务，那么如果这些输出是复杂类型，就不会显示这些输出；而是会列出其组成部分。
  • 在详细信息部分中，将显示服务名称及其文档。
  • 选择绑定将显示绑定类型 REST、服务器和（可选）认证信息。 如果服务器绑定属性发生更改，那么可选择其他服务器。
    在此面板中，您可以为 OpenAPI 规范中定义的所有安全性定义输入用于调用服务的认证信息。
    重要信息: 对于类型为 basic 的安全性定义 (基本认证) ，您在此处指定的认证信息将覆盖为服务器提供的信息。 对于 apiKey 类型的安全性定义，可以在此处指定认证信息，但不能在服务器中指定。
  • 选择源将以只读方式显示 OpenAPI 规范源。 查看要通过 JavaScript API 进行调用的操作时，这很有用。
  • 在数据库部分中，您可能会看到因生成 REST 服务而产生的业务对象。 这些业务对象仅用于外部服务，并且是只读的。 删除外部服务也将删除这些业务对象。

创建外部服务后，可以将其选择为服务流中服务任务的实现。 从“操作”列表中选择要使用的操作，并在数据映射选项卡中映射输入和输出。 如果要使用 JavaScript 来调用操作，请在服务流的脚本任务中输入 JavaScript。 请参阅 创建服务流 和 使用 JavaScript调用 REST 服务。

如果 OpenAPI 规范包含类型为 apiKey 的安全性定义，那么所选操作使用的 API 密钥将出现在数据映射选项卡上。 在数据映射选项卡上，您可以在将 API 密钥用于服务流之前检索这些密钥，将其存储在专用瞬态变量中并进行映射。 通过将 API 密钥存储在瞬态变量中 (如 在服务流中使用瞬态变量中所述) ，它不会作为执行上下文的一部分持久存储在数据库中。

此处指定的 API 密钥的优先级高于在绑定选项卡上指定的任何 API 密钥。

要捕获服务中可能发生的任何错误，请将捕获所有边界错误事件附加到该服务，如使用错误边界事件捕获错误中所述。