第 9 章 自定义 Fuse 在线

将 OpenAPI 模式上传到 Fuse Online 后，到 REST API 的连接器将变为可用。您可以选择连接器来创建 REST API 客户端连接。然后，您可以创建新集成并添加 REST API 客户端连接，也可以编辑现有的集成以添加 REST API 客户端连接。

Fuse Online 连接器支持 OAuth 2.0、HTTP 基本授权和 API 密钥。如果访问 REST API 需要传输层安全(TLS)，API 需要使用可识别的证书颁发机构(CA)发布的有效证书。

使用 OAuth 的 REST API 必须有一个授权 URL，它将客户端回调 URL 作为输入。在 Fuse Online 创建连接器后，在使用连接器来创建连接前，您必须访问该 URL 将 Fuse Online 环境注册为 REST API 的客户端。这授权 Fuse Online 环境访问 REST API。作为注册的一部分，您可以提供 Fuse 在线回调 URL。有关执行此操作的详情，请参考 将 Fuse Online 连接到应用程序和服务，将 Fuse Online 注册为 REST API 客户端。

对于使用 OAuth 的 REST API，Fuse Online 仅支持 授权代码 授权流。在您上传以创建连接器的 OpenAPI 文档中，在 OAuth securityDefinitions 对象中，您必须将 flow 属性设置为 accessCode，例如：

securityDefinitions:
  OauthSecurity:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'

您不能将 流 设置为 隐式、密码 或 应用程序。

REST API 客户端连接器的 OpenAPI 模式无法具有 cyclic 模式引用。例如，指定请求或响应正文的 JSON 模式无法作为整体引用，也无法通过任意数量的中间模式引用其自身的任何部分。

Fuse Online 无法为支持 HTTP 2.0 协议的 REST API 创建连接器。

当 Fuse Online 创建 REST API 客户端连接器时，它会将 OpenAPI 文档中的每个资源操作映射到连接操作。操作名称和描述来自 OpenAPI 文档中的文档。

OpenAPI 文档提供的更多详细信息，在连接到 API 时，Fuse Online 提供了更多支持。例如，不需要为请求和响应声明数据类型。如果没有类型声明，Fuse Online 会将对应的连接操作定义为无类型。但是，在集成中，您无法在执行无类型操作的 API 连接前或立即添加数据映射步骤。

一个补救措施是向 OpenAPI 文档添加更多信息。识别将映射到您希望 API 连接执行的操作的 OpenAPI 资源操作。在 OpenAPI 文档中，确保有一个 YAML 或 JSON 模式，用于指定每个操作的请求和响应类型。

上传架构后，Fuse Online 为您提供了在 API Designer 中查看和编辑它的机会，这是基于 OpenAPI 文档设计 API 的可视化编辑器。您可以添加更多详情、保存更新，Fuse Online 创建一个包含更新的 API 客户端连接器。在 Fuse Online 创建客户端连接器后，您无法再编辑 OpenAPI 文档。要实现更改，必须创建新的客户端连接器。

如果 API 的 OpenAPI 文档声明了对 application/json 内容类型以及 application/xml 内容类型的支持，则连接器将使用 JSON 格式。如果 OpenAPI 文档指定 消耗 或生成 定义 application/json 和 application/xml 的参数，则连接器使用 JSON 格式。

当 Fuse Online 尝试获取访问 OAuth2 应用程序的授权时，它会使用 HTTP 基本身份验证来提供客户端凭据。如果需要，您可以更改此默认行为，以便 Fuse Online 将客户端凭证作为参数传递给提供程序，而不使用 HTTP 基本身份验证。这会影响用于获取 OAuth 访问令牌的 tokenUrl 端点。

要指定 Fuse Online 应将客户端凭证作为参数传递，请在 OpenAPI 文档的 securityDefinitions 部分中，添加 x-authorize-using-parameters 厂商扩展，并设置 true。在以下示例中，最后一行指定 x-authorize-using-parameters ：

securityDefinitions:
  concur_oauth2:
    type: 'oauth2'
    flow: 'accessCode'
    authorizationUrl: 'https://example.com/oauth/authorize'
    tokenUrl: 'https://example.com/oauth/token'
    scopes:
      LIST: Access List API
    x-authorize-using-parameters: true

x-authorize-using-parameters 厂商扩展的设置是 true 或 false ：

如果访问令牌具有过期日期，则 Fuse Online 集成时使用该令牌连接到应用程序，在令牌过期时停止运行。要获取新的访问令牌，您必须重新连接到应用程序，或使用应用程序重新注册。

如果需要，您可以更改此默认行为，以便 Fuse Online 在以下情况下自动请求新的访问令牌：

要指定 Fuse Online 应自动尝试在 OpenAPI 文档的 securityDefinitions 部分中获取新的访问令牌，请添加 x-refresh-token-retry-statuses 厂商扩展。此扩展的设置是一个以逗号分隔的列表，用于指定 HTTP 响应状态代码。当访问令牌的过期日期达到或 Fuse Online 收到来自 OAuth2 供应商的消息时，并且消息具有这些响应状态代码之一时，Fuse Online 会自动尝试获取新的访问令牌。在以下示例中，最后一行指定 x-refresh-token-retry-statuses ：

securityDefinitions:
  concur_oauth2:
    type: 'oauth2'
    flow: 'accessCode'
    authorizationUrl: 'https://example.com/oauth/authorize'
    tokenUrl: 'https://example.com/oauth/token'
    scopes:
      LIST: Access List API
    x-refresh-token-retry-statuses: 401,402,403