创建自定义连接器

本页介绍了如何创建自定义连接器。如需了解什么是自定义连接器,请参阅自定义连接器

如需使用自定义连接器与后端建立连接,您需要执行以下任务:

  1. 创建自定义连接器 - 在此任务中,您将提供端点的 OpenAPI 规范,以定义集成连接器与端点(后端)之间的协定。目前,仅支持 OpenAPI 版本 3.0 及其所有次要版本。指定规范是一项一次性活动。
  2. 创建自定义连接器连接 - 在此任务中,您将配置后端的连接详细信息,例如主机名和身份验证。对于特定的自定义连接器,您可以根据需要创建任意数量的连接。

如需了解连接器与连接之间的区别,请参阅连接器与连接

准备工作

创建自定义连接器

后端连接场景中所述,自定义连接器可以采用以下任一连接模式:

  • 直接连接到后端的公共端点。
  • 通过中间公共端点间接连接到后端。

这两种模式的自定义连接器创建步骤略有不同。

通过直接连接创建

如需创建可直接连接到后端端点的自定义连接器,请按以下步骤操作:

控制台

  1. Console 中,依次前往 Integration Connectors > Custom connectors 页面,然后选择或创建一个 Google Cloud 项目。

    前往“自定义连接器”页面

  2. 点击新建,打开创建自定义连接器页面。
  3. 连接器详情部分中,设置以下字段:
    1. 连接器名称:输入连接器的名称。
    2. 显示名称:输入连接器的显示名称。
    3. 说明:输入说明。
    4. 服务账号:选择具有所需角色的服务账号。
    5. 徽标:将图片上传到 Cloud Storage 存储分区,以用作连接器徽标。
  4. 点击下一步
  5. 连接器规范部分中,设置以下字段:
    1. 自定义连接器类型:选择自定义连接器类型。
    2. 连接器规范:输入 Open API 规范的公开网址,或将规范文件上传到 Cloud Storage 存储分区。
  6. 查看连接器配置详情,然后点击创建

如果连接器创建成功,新创建的连接器将显示在 前往“自定义连接器”页面中,如果是新连接器,系统还会创建该连接器的第一个版本。您可以在自定义连接器详情页面的版本标签页中查看版本详情。如需了解详情,请参阅

不过,请注意,若要连接到后端,您必须为新创建的连接器创建连接。如需了解详情,请参阅创建自定义连接器连接

API

以下示例命令展示了如何使用集成连接器 API 创建自定义连接器:

  1. 创建连接器。
    curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"
    -d '{"customConnectorType":"OPEN_API", \
    "displayName":"CUSTOM_CONNECTOR_NAME", \
    "description": "an open api based custom connector for hrms"}' \
    "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
    

    请替换以下内容:

    • CUSTOM_CONNECTOR_NAME:自定义连接器的名称。
    • PROJECT_ID: Google Cloud 项目的 ID。
    • UNIQUE_IDENTIFIER:连接器的唯一标识符。例如 custom-connector-1
  2. 配置自定义连接器版本。
    curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"spec_location": "SPECIFICATION_URL",}' \
    "https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"
    
  3. 请替换以下内容:

    • SPECIFICATION_URL:Open API 规范网址。例如 https://petstore3.swagger.io/api/v3/openapi.json
    • PROJECT_ID: Google Cloud 项目的 ID。
    • VERSION_NUMBER:连接器的版本号。例如 2

使用间接连接创建

如需创建通过中间端点连接到后端的自定义连接器,请按以下步骤操作:

控制台

  1. Console 中,依次前往 Integration Connectors > Custom connectors 页面,然后选择或创建一个 Google Cloud 项目。

    前往“自定义连接器”页面

  2. 点击新建,打开创建自定义连接器页面。
  3. 连接器详情部分中,设置以下字段:
    1. 连接器名称:输入连接器的名称。
    2. 显示名称:输入连接器的显示名称。
    3. 说明:输入说明。
    4. 为后端访问配置连接器目标位置:启用此选项。这会在页面中显示其他配置部分。
    5. 服务账号:选择具有所需角色的服务账号。
    6. 徽标:将图片上传到 Cloud Storage 存储分区,以用作连接器徽标。
  4. 点击下一步
  5. 连接器规范部分中,设置以下字段:
    1. 自定义连接器类型:选择自定义连接器类型。
    2. 连接器规范:输入 Open API 规范的公开网址,或将规范文件上传到 Cloud Storage 存储分区。
  6. 点击下一步
  7. 连接器目标位置部分中,设置以下字段:
    1. 目标类型:选择主机地址
    2. 主机:输入中介服务正在运行的主机名。
    3. 端口:输入中介服务的端口号。
  8. 点击下一步
  9. 连接器身份验证部分中,选择中介服务的身份验证类型,然后根据提示输入相应详细信息。此步骤用于配置从集成连接器到中介服务的身份验证。

    您无法在集成连接器中配置从中介服务到后端的身份验证配置;中介服务如何与后端进行身份验证取决于中介服务本身。

    您可以使用以下身份验证类型对中介服务进行身份验证:

    • 服务账号身份验证
    • API 密钥身份验证
    • OAuth 2.0 - 客户端凭据身份验证
    • 基本身份验证
    • 摘要身份验证
    • 如需了解如何配置这些身份验证类型,请参阅配置身份验证

    如果对 API 资源的访问不受限制且不需要任何身份验证,请选择无身份验证

  10. 点击下一步
  11. 后端变量部分,输入您希望通过中介服务发送到后端的值。您必须将值配置为键值对。如需输入键值对,请点击添加变量,然后设置以下字段:
    • 密钥:输入密钥名称。
    • 值类型:选择变量的数据类型。
    • 显示名称:输入显示名称。
    • Location:指定您希望连接器如何将变量发送到中介服务。可用选项包括 HeaderRequest payloadQuery parameter
    • (可选)选择 Required 以指定该变量为必需变量。
  12. 点击下一步
  13. 查看连接器配置详情,然后点击创建

如果连接器创建成功,新创建的连接器将显示在“自定义连接器”页面中,如果是新连接器,系统还会创建该连接器的第一个版本。您可以在自定义连接器详情页面的版本标签页中查看版本详情。如需了解如何创建和修改自定义连接器版本,请参阅管理自定义连接器版本

不过,请注意,若要连接到后端,您必须为新创建的连接器创建连接。如需了解详情,请参阅创建自定义连接器连接

配置身份验证

根据您要使用的身份验证输入详细信息。

  • 服务账号身份验证

    选择此选项可使用 Google Cloud 服务账号进行身份验证。确保您已向服务账号提供进行身份验证所需的相关 IAM 角色和权限。

    • 范围:从下拉菜单中选择所需的 OAuth 2.0 范围。如需了解详情,请参阅访问权限范围
  • API 密钥身份验证

    选择此选项可使用 API 密钥进行身份验证。

    • API 密钥:选择 API 密钥的 Secret Manager Secret。
    • Secret 版本:选择 Secret 版本。
    • API 密钥参数名称:输入 API 密钥的参数名称。API 密钥会作为键值对发送到您的后端服务器。您在此处输入的值将用作您之前选择的 API 密钥的密钥名称。
    • API 密钥位置:选择要在请求中添加 API 密钥的位置。
  • OAuth 2.0 - 客户端凭据授予
    • 客户端 ID:用于向中介服务进行身份验证的客户端 ID。
    • 客户端密钥:包含用于对中介服务进行身份验证的客户端密钥的 Secret Manager Secret。
    • 访问令牌的请求格式:在从身份验证服务器提取访问令牌的请求中使用的请求格式。 选择 body 以将客户端 ID 和 Secret 作为请求正文传递,或选择 header 以将其作为编码标头传递。
    • 令牌请求路径:要附加到身份验证服务器网址以提取访问令牌网址的请求路径。
  • 基本身份验证
    • 用户名:用于向中介服务进行身份验证的用户名。
    • 密码:包含与提供的用户名关联的密码的 Secret Manager Secret。
  • 摘要身份验证
    • 用户名:用于向中介服务进行身份验证的用户名。
    • 密码:包含与提供的用户名关联的密码的 Secret Manager Secret。

API

以下示例命令展示了如何使用集成连接器 API 创建自定义连接器:

  1. 创建连接器。
    curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"
    -d '{"customConnectorType":"OPEN_API", \
    "displayName":"CUSTOM_CONNECTOR_NAME", \
    "description": "an open api based custom connector for hrms"}' \
    "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
    

    请替换以下内容:

    • CUSTOM_CONNECTOR_NAME:自定义连接器的名称。
    • PROJECT_ID: Google Cloud 项目的 ID。
    • UNIQUE_IDENTIFIER:连接器的唯一标识符。例如 custom-connector-1
  2. 配置自定义连接器版本和身份验证。
    curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"spec_location": "SPECIFICATION_URL", \
    "service_account":"test-sa", \
    "enable_backend_destination_config": true, \
    "auth_config": { \
    "auth_type":"USER_PASSWORD", \
    "auth_key": "basic", \
    "user_password": { \
    "username":"USERNAME", \
    "password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
    }}, \
    "backend_variable_templates": [{ \
    "key":"authkey", \
    "value_type":"SECRET", \
    "display_name":"Authorization Key", \
    "required":true, \
    "location_type": "HEADER" \
    }], \
    "destination_configs":[{ \
    "key":"base_url", \
    "destinations": [{ \
    "host":"DESTINATION_HOST_ADDRESS" \
    }]} \
    ]}' \
    "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"
    
  3. 请替换以下内容:

    • SPECIFICATION_URL:Open API 规范网址。例如 https://petstore3.swagger.io/api/v3/openapi.json
    • PROJECT_ID: Google Cloud 项目的 ID。
    • USERNAME:用于与中介服务进行身份验证的用户名。
    • SECRET_VERSION_NUMBER:Secret Manager Secret 的版本号。例如 2
    • DESTINATION_HOST_ADDRESS:中介服务的主机地址。例如 http://www.test.com:80
    • CONNECTOR_VERSION_NUMBER:自定义连接器的版本号。例如 1

创建自定义连接器连接

创建自定义连接器后,若要连接到后端,您必须创建自定义连接器类型的连接。创建新连接的简要步骤如下:

  1. Cloud 控制台 中,进入 Integration Connectors > 连接页面,然后选择或创建一个 Google Cloud 项目。

    转到“连接”页面

  2. 点击新建以打开创建连接页面。
  3. 位置部分中,从区域字段中选择连接的位置。

    如需查看所有受支持区域的列表,请参阅位置

  4. 点击下一步
  5. 连接详情部分中,设置以下字段:
    1. 连接器:从可用连接器的下拉列表中选择您的自定义连接器。
    2. 连接器版本:从可用版本的下拉列表中选择一个连接器版本。
    3. 连接名称字段中,输入连接的名称。

      连接名称必须符合以下条件:

      • 连接名称可以使用字母、数字或连字符。
      • 字母必须小写。
      • 连接名称必须以字母开头,以字母或数字结尾。
      • 连接名称不能超过 63 个字符。
    4. (可选)输入连接的说明
    5. 您可以选择启用 Cloud Logging 以启用 Cloud Logging。
    6. 服务账号:选择具有所需角色的服务账号。
    7. (可选)配置连接节点设置

      • 节点数下限:输入连接节点数下限。
      • 节点数上限:输入连接节点数上限。

      节点是处理事务的连接单元(或副本)。 连接处理越多事务就需要越多节点,相反,处理越少事务需要越少节点。 如需了解节点如何影响连接器价格,请参阅连接节点的价格。如果未输入任何值,则默认情况下,节点数下限设置为 2(以便提高可用性),节点数上限设置为 50。

    8. (可选)点击添加标签,以键值对的形式为连接添加标签。
  6. 点击下一步
  7. 身份验证部分中,输入后端的身份验证详细信息。
    • 如果您直接连接到后端,集成连接器会提示您为后端配置身份验证。
    • 如果您通过中介服务间接连接到后端,集成连接器不会提示您配置身份验证详细信息。创建连接器时,您应该已在集成连接器和中介服务之间配置了身份验证。集成连接器不需要您配置中介服务与后端之间的身份验证;中介服务如何与后端进行身份验证取决于中介服务本身。
  8. 点击下一步
  9. 查看连接配置详情,然后点击创建

如果连接创建成功,该连接会显示在“所有连接”页面中,并且该连接将在应用集成中可用。您可以通过连接器任务在集成中使用该连接。

注意事项

创建自定义连接器时,请考虑以下几点:

  • 集成连接器仅支持 OpenAPI 3.0 版及其所有子版本。
  • 在创建自定义连接器期间,系统不会验证 Open API 规范。为自定义连接器创建连接时,集成连接器会验证规范,如果存在错误,连接将处于 Error 状态。
  • 集成连接器不会区分实体和操作。因此,自定义连接器中会将后端的实体和操作都列为 Actions
  • Google Cloud 启用了 VPC Service Controls 的项目不支持自定义连接器。
  • Open API 规范端点和后端端点都应可公开访问。这意味着您无法与后端建立专用连接。
  • Open API 规范不支持多部分媒体类型。
  • 您无法修改自定义连接器的版本详细信息。