IBM Cloud Docs
向助手添加扩展

向助手添加扩展

构建定制扩展后,必须将其添加到助手,然后才能通过操作对其进行访问。

将该扩展添加到助手会配置该扩展以在特定环境中使用,并使该扩展可用,以便可以从操作中调用该扩展。

您可以对每个环境使用不同的配置详细信息。 例如,您可能希望将 URL 用于草稿环境中的测试服务器,但用于实时环境中的生产服务器。

有关如何创建定制扩展的信息,请参阅 构建定制扩展

将扩展添加到草稿环境

要向助手添加定制扩展,请执行以下步骤:

  1. "集成" 图标 集成 页面上,滚动到 扩展 部分,并查找要添加的定制扩展的磁贴。

  2. 单击添加。 查看扩展的概述,然后单击 确认 以针对助手进行配置。

    首次向助手添加扩展时,您提供的配置设置仅应用于草稿环境。 必须先完成草稿环境的配置,然后才能在实时环境中添加扩展。

  3. 阅读 入门 步骤中的信息,然后单击 下一步

  4. 认证 步骤中,指定您希望助手在调用服务时使用的认证和服务器信息。

    • 认证类型 字段中,选择要使用的认证类型 (如果未认证 API,请选择 无认证 )。 可用认证类型由 OpenAPI 文档中定义的安全方案确定。

    • 指定所选认证类型所需的其他信息 (例如用户名和密码,API 密钥,不记名令牌或 OAuth 2.0 详细信息)。

      有关配置 OAuth 2.0 认证的更多信息,请参阅 OAuth 2.0 认证

    • 服务器 字段中,选择要使用的服务器 URL。

      如果所选 URL 包含任何变量,请同时指定要使用的值。 根据在 OpenAPI 文档中定义每个变量的方式,您可以从有效值列表中进行选择,也可以输入要在字段中使用的值。

      生成的 URL 消息显示助手使用的完整 URL,包括变量值。

    单击下一步

  5. 管理扩展 步骤中,您可以查看并替换导入的 OpenAPI 文档 (如果需要)。 有关替换 OpenAPI 文档的更多信息,请参阅 替换 OpenAPI 文档

  6. 认证 选项卡中,您将看到有关 OpenAPI 文档中定义的认证方法的信息。 表。 “认证”选项卡 中的字段提供有关“认证”选项卡中的字段的详细信息:

    字段名称 描述
    认证类型 在 OpenAPI 脚本中设置的认证类型。 - OAuth 2.0
    - Basic Auth
    - API key auth
    - Bearer auth
    用户名 OpenAPI 脚本中的用户名凭证。 例如, user
    密码 在 OpenAPI 脚本中设置的密码凭证。 例如, Password@123
    服务器 指向要连接的开放式 API 文档中定义的服务器的链接。到 API 扩展。 例如, https://custom-extension-server.xyz
  7. 复审操作 表显示助手能够从操作步骤调用的操作。 操作 是在特定资源上使用特定 HTTP 方法 (例如 GETPOST) 的请求。

    复审操作表
    复审操作表

    对于每个操作,表中的一行显示以下信息:

    • 操作: 操作的描述,派生自 OpenAPI 文件中的 summary (如果存在) 或 description
    • 方法: 用于发送操作的 API 请求的 HTTP 方法。
    • 资源: 操作对其执行操作的资源的路径。

    要查看有关操作的更多信息,请单击表中其行旁边的 标签 图标。 详情如下:

    • 请求参数: 为操作定义的输入参数的列表,以及每个参数的类型以及参数是必需参数还是可选参数。
    • 响应属性: 映射到助手可访问的变量的响应主体的属性。
  8. 单击完成

  9. 单击 关闭 以返回到“集成”页面。

该扩展现在已连接到助手,可供草稿环境中的操作使用。

OAuth 2.0 认证

如果要配置 OAuth 2.0 认证,那么必须提供的信息取决于授权类型。

有关 OAuth 2.0的更多信息,请参阅 OAuth 2.0

要完成 OAuth 认证设置,请执行以下步骤:

  1. 如果尚未注册,请向要访问的外部 API 注册应用程序。 复制外部 API 提供的客户机标识和客户机密钥。

  2. 授权类型 字段中,选择要使用的授权类型。 可用授权类型由 OpenAPI 文档中的 securitySchemes 对象中定义的流确定。 支持以 x- 开头的授权代码,客户机凭证,密码和定制授权类型。

    OAuth2 定制授权类型 x-<any custom name>IBM IAM 认证机制watsonx 使用。

  3. 指定外部 API 在注册应用程序时提供的必需值。 必需值取决于授权类型:

    授权类型
    授予类型 必需值
    授权代码
    • 客户 ID
    • 客户秘密
    客户机凭证
    • 客户 ID
    • 客户秘密
    密码
    • 客户机标识
    • 客户机密钥
    • 用户名
    • 密码
    x-<any custom name>
    • openAPI 规范文件中提到的私钥字段列表
  4. 如果您正在使用“授权代码”授权类型,请执行以下步骤:

    1. 从 watsonx Assistant 扩展设置页面复制重定向 URL,并将其粘贴到外部 API 的应用程序注册页面上的相应字段中。 (重定向 URL 有时称为 回调 URL。)

    2. 单击“授予访问权限”。 您将重定向到外部服务的 Web 站点上的授权页面。 验证是否授予了正确的访问权,然后单击以核准。 然后,使用重定向 URL将您重定向回扩展设置页面。

  5. 客户机认证 字段中,指定是在 HTTP 头中发送认证凭证,还是作为请求主体的一部分发送认证凭证。 (在请求主体中发送的凭证使用 x-www-form-urlencoded 内容类型。) 选择外部服务期望的选项。

  6. 头前缀 字段中,指定 Authorization 头中访问令牌之前的前缀。 (缺省前缀为 Bearer,这是大多数应用程序的典型前缀。)

  7. 如果您正在使用定制授权类型 x-<any custom name> (例如,x-apikey),请执行以下步骤:

    1. 添加与私钥字段关联的私钥值。
    2. 添加可选参数值 (如果有)。

如果外部服务支持“刷新令牌”授权类型,那么 watsonx Assistant 将在旧令牌到期时自动获取新的访问令牌。 如果 OpenAPI 文档定义了 refreshUrl 属性,那么将使用指定的 URL ; 否则,将使用 tokenUrl URL。

为实时环境配置扩展

要配置实时环境的扩展,请执行以下步骤:

  1. "集成" 图标 集成 页面上,滚动到 扩展 部分,并查找要添加的定制扩展的磁贴。

  2. 单击打开。 此时将打开“打开定制扩展”窗口。

  3. 环境 字段中,选择 实时。 请单击确认

  4. 重复配置过程,指定要用于实时环境的值。

    如果您正在使用多个环境,请执行相同的步骤为每个环境配置扩展。 有关更多信息,请参阅 添加和使用多个环境

现在,该扩展在您配置的环境中可用,并且可以从助手调用该扩展。 有关如何从操作调用扩展的更多信息,请参阅 调用定制扩展

套餐限制

可以添加到助手的定制扩展数取决于您的套餐。 如果已向助手添加了最大数目的扩展,那么必须先除去扩展,然后才能添加新扩展。

按套餐划分的扩展限制
套餐 每个助手的扩展
企业 100
高级 (旧版) 100
Plus 10
试用 5
Lite 3
标准(旧版) 0