创建自定义连接器
本页介绍了如何创建自定义连接器。如需了解什么是自定义连接器，请参阅自定义连接器。
如需使用自定义连接器与后端建立连接，您需要执行以下任务：
- 创建自定义连接器 - 在此任务中，您将提供端点的 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 规范不支持多部分媒体类型。
- 您无法修改自定义连接器的版本详细信息。