创建自定义连接器
本页介绍了如何创建自定义连接器。如需了解什么是自定义连接器,请参阅自定义连接器。
如需使用自定义连接器与后端建立连接,您需要执行以下任务:
- 创建自定义连接器 - 在此任务中,您将提供端点的 OpenAPI 规范,以定义集成连接器与端点(后端)之间的协定。目前,仅支持 OpenAPI 版本 3.0 及其所有次要版本。指定规范是一项一次性活动。
- 创建自定义连接器连接 - 在此任务中,您将配置后端的连接详细信息,例如主机名和身份验证。对于特定的自定义连接器,您可以根据需要创建任意数量的连接。
如需了解连接器与连接之间的区别,请参阅连接器与连接。
准备工作
-
如需获得创建自定义连接器所需的权限,请让您的管理员向您授予项目的 Custom Connectors Admin (
roles/connectors.customConnectorAdmin
) IAM 角色。 如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。 - 启用 Connector API:
启用 Connector API
创建自定义连接器
如后端连接场景中所述,自定义连接器可以采用以下任一连接模式:
- 直接连接到后端的公共端点。
- 通过中间公共端点间接连接到后端。
这两种模式的自定义连接器创建步骤略有不同。
通过直接连接创建
如需创建可直接连接到后端端点的自定义连接器,请按以下步骤操作:
控制台
- 在 Console 中,依次前往 Integration Connectors > Custom connectors 页面,然后选择或创建一个 Google Cloud 项目。
- 点击新建,打开创建自定义连接器页面。
- 在连接器详情部分中,设置以下字段:
- 连接器名称:输入连接器的名称。
- 显示名称:输入连接器的显示名称。
- 说明:输入说明。
- 服务账号:选择具有所需角色的服务账号。
- 徽标:将图片上传到 Cloud Storage 存储分区,以用作连接器徽标。
- 点击下一步。
- 在连接器规范部分中,设置以下字段:
- 自定义连接器类型:选择自定义连接器类型。
- 连接器规范:输入 Open API 规范的公开网址,或将规范文件上传到 Cloud Storage 存储分区。
- 查看连接器配置详情,然后点击创建。
如果连接器创建成功,新创建的连接器将显示在 前往“自定义连接器”页面中,如果是新连接器,系统还会创建该连接器的第一个版本。您可以在自定义连接器详情页面的版本标签页中查看版本详情。如需了解详情,请参阅 。
不过,请注意,若要连接到后端,您必须为新创建的连接器创建连接。如需了解详情,请参阅创建自定义连接器连接。
API
以下示例命令展示了如何使用集成连接器 API 创建自定义连接器:
- 创建连接器。
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
。
- 配置自定义连接器版本。
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"
SPECIFICATION_URL
:Open API 规范网址。例如https://petstore3.swagger.io/api/v3/openapi.json
。PROJECT_ID
: Google Cloud 项目的 ID。VERSION_NUMBER
:连接器的版本号。例如2
。
请替换以下内容:
使用间接连接创建
如需创建通过中间端点连接到后端的自定义连接器,请按以下步骤操作:
控制台
- 在 Console 中,依次前往 Integration Connectors > Custom connectors 页面,然后选择或创建一个 Google Cloud 项目。
- 点击新建,打开创建自定义连接器页面。
- 在连接器详情部分中,设置以下字段:
- 连接器名称:输入连接器的名称。
- 显示名称:输入连接器的显示名称。
- 说明:输入说明。
- 为后端访问配置连接器目标位置:启用此选项。这会在页面中显示其他配置部分。
- 服务账号:选择具有所需角色的服务账号。
- 徽标:将图片上传到 Cloud Storage 存储分区,以用作连接器徽标。
- 点击下一步。
- 在连接器规范部分中,设置以下字段:
- 自定义连接器类型:选择自定义连接器类型。
- 连接器规范:输入 Open API 规范的公开网址,或将规范文件上传到 Cloud Storage 存储分区。
- 点击下一步。
- 在连接器目标位置部分中,设置以下字段:
- 目标类型:选择主机地址。
- 主机:输入中介服务正在运行的主机名。
- 端口:输入中介服务的端口号。
- 点击下一步。
- 在连接器身份验证部分中,选择中介服务的身份验证类型,然后根据提示输入相应详细信息。此步骤用于配置从集成连接器到中介服务的身份验证。
您无法在集成连接器中配置从中介服务到后端的身份验证配置;中介服务如何与后端进行身份验证取决于中介服务本身。
您可以使用以下身份验证类型对中介服务进行身份验证:
- 服务账号身份验证
- API 密钥身份验证
- OAuth 2.0 - 客户端凭据身份验证
- 基本身份验证
- 摘要身份验证
如需了解如何配置这些身份验证类型,请参阅配置身份验证。
如果对 API 资源的访问不受限制且不需要任何身份验证,请选择无身份验证。
- 点击下一步。
- 在后端变量部分,输入您希望通过中介服务发送到后端的值。您必须将值配置为键值对。如需输入键值对,请点击添加变量,然后设置以下字段:
- 密钥:输入密钥名称。
- 值类型:选择变量的数据类型。
- 显示名称:输入显示名称。
- Location:指定您希望连接器如何将变量发送到中介服务。可用选项包括
Header
、Request payload
和Query parameter
。 - (可选)选择
Required
以指定该变量为必需变量。
- 点击下一步。
- 查看连接器配置详情,然后点击创建。
如果连接器创建成功,新创建的连接器将显示在“自定义连接器”页面中,如果是新连接器,系统还会创建该连接器的第一个版本。您可以在自定义连接器详情页面的版本标签页中查看版本详情。如需了解如何创建和修改自定义连接器版本,请参阅管理自定义连接器版本。
不过,请注意,若要连接到后端,您必须为新创建的连接器创建连接。如需了解详情,请参阅创建自定义连接器连接。
配置身份验证
根据您要使用的身份验证输入详细信息。
- 服务账号身份验证
选择此选项可使用 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 创建自定义连接器:
- 创建连接器。
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
。
- 配置自定义连接器版本和身份验证。
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"
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
。
请替换以下内容:
创建自定义连接器连接
创建自定义连接器后,若要连接到后端,您必须创建自定义连接器类型的连接。创建新连接的简要步骤如下:
- 在 Cloud 控制台 中,进入 Integration Connectors > 连接页面,然后选择或创建一个 Google Cloud 项目。
- 点击新建以打开创建连接页面。
- 在位置部分中,从区域字段中选择连接的位置。
如需查看所有受支持区域的列表,请参阅位置。
- 点击下一步。
- 在连接详情部分中,设置以下字段:
- 连接器:从可用连接器的下拉列表中选择您的自定义连接器。
- 连接器版本:从可用版本的下拉列表中选择一个连接器版本。
- 在连接名称字段中,输入连接的名称。
连接名称必须符合以下条件:
- 连接名称可以使用字母、数字或连字符。
- 字母必须小写。
- 连接名称必须以字母开头,以字母或数字结尾。
- 连接名称不能超过 63 个字符。
- (可选)输入连接的说明。
- 您可以选择启用 Cloud Logging 以启用 Cloud Logging。
- 服务账号:选择具有所需角色的服务账号。
- (可选)配置连接节点设置:
- 节点数下限:输入连接节点数下限。
- 节点数上限:输入连接节点数上限。
节点是处理事务的连接单元(或副本)。 连接处理越多事务就需要越多节点,相反,处理越少事务需要越少节点。 如需了解节点如何影响连接器价格,请参阅连接节点的价格。如果未输入任何值,则默认情况下,节点数下限设置为 2(以便提高可用性),节点数上限设置为 50。
- (可选)点击添加标签,以键值对的形式为连接添加标签。
- 点击下一步。
- 在身份验证部分中,输入后端的身份验证详细信息。
- 如果您直接连接到后端,集成连接器会提示您为后端配置身份验证。
- 如果您通过中介服务间接连接到后端,集成连接器不会提示您配置身份验证详细信息。创建连接器时,您应该已在集成连接器和中介服务之间配置了身份验证。集成连接器不需要您配置中介服务与后端之间的身份验证;中介服务如何与后端进行身份验证取决于中介服务本身。
- 点击下一步。
- 查看连接配置详情,然后点击创建。
如果连接创建成功,该连接会显示在“所有连接”页面中,并且该连接将在应用集成中可用。您可以通过连接器任务在集成中使用该连接。
注意事项
创建自定义连接器时,请考虑以下几点:
- 集成连接器仅支持 OpenAPI 3.0 版及其所有子版本。
- 在创建自定义连接器期间,系统不会验证 Open API 规范。为自定义连接器创建连接时,集成连接器会验证规范,如果存在错误,连接将处于
Error
状态。 - 集成连接器不会区分实体和操作。因此,自定义连接器中会将后端的实体和操作都列为
Actions
。 - Google Cloud 启用了 VPC Service Controls 的项目不支持自定义连接器。
- Open API 规范端点和后端端点都应可公开访问。这意味着您无法与后端建立专用连接。
- Open API 规范不支持多部分媒体类型。
- 您无法修改自定义连接器的版本详细信息。