第 9 章 自定义 Fuse Online

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

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

使用 OAuth 的 REST API 必须具有授权 URL，该 URL 使用客户端回调 URL 作为输入。在 Fuse Online 创建连接器后，在您使用连接器来创建连接前，您必须访问该 URL 将 Fuse 在线环境注册为 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'

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 文档中的每个资源操作映射到连接操作。action 名称和操作描述来自 OpenAPI 文档中的文档。

OpenAPI 文档提供的更多详细信息，在连接到 API 时可以提供更多支持 Fuse Online。例如，不需要 API 定义来为请求和响应声明数据类型。在没有类型声明的情况下，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 基本身份验证。这会影响使用 tokenUrl 端点来获取 OAuth 访问令牌。

要指定 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

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 vendor extension 的设置是 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

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