向助手添加扩展
构建定制扩展后,必须将其添加到助手,然后才能通过操作对其进行访问。
将该扩展添加到助手会配置该扩展以在特定环境中使用,并使该扩展可用,以便可以从操作中调用该扩展。
您可以对每个环境使用不同的配置详细信息。 例如,您可能希望将 URL 用于草稿环境中的测试服务器,但用于实时环境中的生产服务器。
有关如何创建定制扩展的信息,请参阅 构建定制扩展。
将扩展添加到草稿环境
要向助手添加定制扩展,请执行以下步骤:
-
在
集成 页面上,滚动到 扩展 部分,并查找要添加的定制扩展的磁贴。
-
单击添加。 查看扩展的概述,然后单击 确认 以针对助手进行配置。
首次向助手添加扩展时,您提供的配置设置仅应用于草稿环境。 必须先完成草稿环境的配置,然后才能在实时环境中添加扩展。
-
阅读 入门 步骤中的信息,然后单击 下一步。
-
在 认证 步骤中,指定您希望助手在调用服务时使用的认证和服务器信息。
-
在 认证类型 字段中,选择要使用的认证类型 (如果未认证 API,请选择 无认证 )。 可用认证类型由 OpenAPI 文档中定义的安全方案确定。
-
指定所选认证类型所需的其他信息 (例如用户名和密码,API 密钥,不记名令牌或 OAuth 2.0 详细信息)。
有关配置 OAuth 2.0 认证的更多信息,请参阅 OAuth 2.0 认证。
-
在 服务器 字段中,选择要使用的服务器 URL。
如果所选 URL 包含任何变量,请同时指定要使用的值。 根据在 OpenAPI 文档中定义每个变量的方式,您可以从有效值列表中进行选择,也可以输入要在字段中使用的值。
生成的 URL 消息显示助手使用的完整 URL,包括变量值。
单击下一步。
-
-
在 管理扩展 步骤中,您可以查看并替换导入的 OpenAPI 文档 (如果需要)。 有关替换 OpenAPI 文档的更多信息,请参阅 替换 OpenAPI 文档。
-
在 认证 选项卡中,您将看到有关 OpenAPI 文档中定义的认证方法的信息。 表。 “认证”选项卡 中的字段提供有关“认证”选项卡中的字段的详细信息:
字段名称 描述 值 认证类型 在 OpenAPI 脚本中设置的认证类型。 - OAuth 2.0
-Basic Auth
-API key auth
-Bearer auth
用户名 OpenAPI 脚本中的用户名凭证。 例如, user
密码 在 OpenAPI 脚本中设置的密码凭证。 例如, Password@123
服务器 指向要连接的开放式 API 文档中定义的服务器的链接。到 API 扩展。 例如, https://custom-extension-server.xyz
-
复审操作 表显示助手能够从操作步骤调用的操作。 操作 是在特定资源上使用特定 HTTP 方法 (例如
GET
或POST
) 的请求。复审操作表 对于每个操作,表中的一行显示以下信息:
- 操作: 操作的描述,派生自 OpenAPI 文件中的
summary
(如果存在) 或description
。 - 方法: 用于发送操作的 API 请求的 HTTP 方法。
- 资源: 操作对其执行操作的资源的路径。
要查看有关操作的更多信息,请单击表中其行旁边的
图标。 详情如下:
- 请求参数: 为操作定义的输入参数的列表,以及每个参数的类型以及参数是必需参数还是可选参数。
- 响应属性: 映射到助手可访问的变量的响应主体的属性。
- 操作: 操作的描述,派生自 OpenAPI 文件中的
-
单击完成。
-
单击 关闭 以返回到“集成”页面。
该扩展现在已连接到助手,可供草稿环境中的操作使用。
OAuth 2.0 认证
如果要配置 OAuth 2.0 认证,那么必须提供的信息取决于授权类型。
有关 OAuth 2.0的更多信息,请参阅 OAuth 2.0。
要完成 OAuth 认证设置,请执行以下步骤:
-
如果尚未注册,请向要访问的外部 API 注册应用程序。 复制外部 API 提供的客户机标识和客户机密钥。
-
在 授权类型 字段中,选择要使用的授权类型。 可用授权类型由 OpenAPI 文档中的
securitySchemes
对象中定义的流确定。 支持以x-
开头的授权代码,客户机凭证,密码和定制授权类型。OAuth2 定制授权类型
x-<any custom name>
由 IBM IAM 认证机制 和 watsonx 使用。 -
指定外部 API 在注册应用程序时提供的必需值。 必需值取决于授权类型:
授权类型 授予类型 必需值 授权代码 - 客户 ID
- 客户秘密
客户机凭证 - 客户 ID
- 客户秘密
密码 - 客户机标识
- 客户机密钥
- 用户名
- 密码
x-<any custom name>
- openAPI 规范文件中提到的私钥字段列表
-
如果您正在使用“授权代码”授权类型,请执行以下步骤:
-
从 watsonx Assistant 扩展设置页面复制重定向 URL,并将其粘贴到外部 API 的应用程序注册页面上的相应字段中。 (重定向 URL 有时称为 回调 URL。)
-
单击“授予访问权限”。 您将重定向到外部服务的 Web 站点上的授权页面。 验证是否授予了正确的访问权,然后单击以核准。 然后,使用重定向 URL将您重定向回扩展设置页面。
-
-
在 客户机认证 字段中,指定是在 HTTP 头中发送认证凭证,还是作为请求主体的一部分发送认证凭证。 (在请求主体中发送的凭证使用
x-www-form-urlencoded
内容类型。) 选择外部服务期望的选项。 -
在 头前缀 字段中,指定
Authorization
头中访问令牌之前的前缀。 (缺省前缀为Bearer
,这是大多数应用程序的典型前缀。) -
如果您正在使用定制授权类型
x-<any custom name>
(例如,x-apikey),请执行以下步骤:- 添加与私钥字段关联的私钥值。
- 添加可选参数值 (如果有)。
如果外部服务支持“刷新令牌”授权类型,那么 watsonx Assistant 将在旧令牌到期时自动获取新的访问令牌。 如果 OpenAPI 文档定义了 refreshUrl
属性,那么将使用指定的 URL ; 否则,将使用 tokenUrl
URL。
为实时环境配置扩展
要配置实时环境的扩展,请执行以下步骤:
-
在
集成 页面上,滚动到 扩展 部分,并查找要添加的定制扩展的磁贴。
-
单击打开。 此时将打开“打开定制扩展”窗口。
-
在 环境 字段中,选择 实时。 请单击确认。
-
重复配置过程,指定要用于实时环境的值。
如果您正在使用多个环境,请执行相同的步骤为每个环境配置扩展。 有关更多信息,请参阅 添加和使用多个环境。
现在,该扩展在您配置的环境中可用,并且可以从助手调用该扩展。 有关如何从操作调用扩展的更多信息,请参阅 调用定制扩展。
套餐限制
可以添加到助手的定制扩展数取决于您的套餐。 如果已向助手添加了最大数目的扩展,那么必须先除去扩展,然后才能添加新扩展。
套餐 | 每个助手的扩展 |
---|---|
企业 | 100 |
高级 (旧版) | 100 |
Plus | 10 |
试用 | 5 |
Lite | 3 |
标准(旧版) | 0 |