文档首页/ 云搜索服务 CSS_企业搜索服务 KooSearch/ 用户指南/ 通过API使用KooSearch实现搜索问答
更新时间：2025-08-21 GMT+08:00
查看PDF
分享

通过API使用KooSearch实现搜索问答

KooSearch服务提供的API支持发布到不同的环境，发布成功后支持被调用。

场景描述

KooSearch服务开通成功后，会自动创建KooSearch API。在KooSearch服务详情页的API管理页签，可以看到知识管理和文档解析两类API。

  • 知识管理：该类API主要用于知识库管理，例如上传文件、查询文件等。
  • 文档解析：该类API主要用于对文档数据进行处理，例如解析文档内容。

将KooSearch API发布到不同环境后，支持在环境中调用API使用KooSearch服务。操作流程如下：

  1. 在APIG服务配置API网关：配置API网关。
  2. 在CSS服务发布KooSearch API：发布KooSearch API。
  3. 在业务环境中调用已发布的KooSearch API：调用已发布的KooSearch API。

当已发布的KooSearch API需要修改安全认证方式时，可以编辑API。

当已发布的KooSearch API不希望被调用时，可以下线API。

配置API网关

  1. 创建实例：使用API网关，需要先购买实例。

    实例需要跟KooSearch服务在同一个VPC和子网。

  2. 创建API分组：API分组相当于API的集合，您在创建API前，需要先创建API分组。
  3. 创建环境：API可以同时提供给不同的场景调用，如生产环境（RELEASE）及其他自定义环境。RELEASE是默认存在的环境，无需创建。

发布KooSearch API

将KooSearch API发布到环境。

  1. 进入KooSearch服务详情页面。
    1. 登录云搜索服务管理控制台。
    2. 在左侧导航栏选择“KooSearch>KooSearch文档问答”，进入KooSearch服务列表。
    3. 选择目标服务，单击服务名称，进入服务详情页。
  2. 单击“API管理”，进入API管理页签。
  3. 选择待发布的API，单击操作列的“发布”。
  4. 在“发布”页面配置API网关信息。
    表1 发布服务

    参数

    说明

    实例

    使用API网关，需要先购买实例。可以单击右边的“实例管理”去创建实例。具体创建步骤请看创建实例。

    说明：

    实例需要跟KooSearch服务在同一个VPC和子网。

    发布环境

    API可以同时提供给不同的场景调用，如生产环境（RELEASE）及其他自定义环境。

    建议选择默认存在的环境“RELEASE”，RELEASE是默认的线上环境，是正式发布API的环境，只有发布在RELEASE上的API，才能上架售卖。

    如果您需要创建自定义环境，具体创建步骤请看创建环境。

    分组

    API分组相当于API的集合，API提供者以API分组为单位，管理分组内的所有API。

    建议选择默认分组“DEFAULT”，该分组为系统自动生成，组内所有API均支持通过弹性公网IP（EIP）或私有IP地址两种方式访问。

    如果您需要创建自定义分组，具体创建步骤请看创建API分组。

    配置委托
    选择IAM委托，授权当前账号访问和使用APIG的权限。
    • 当首次配置委托时，可以单击“自动创建委托”新建委托“css_apig_agency”直接使用。
    • 当已有自动创建的委托时，可以单击“委托一键授权”，自动删除委托中APIG Administrator系统角色或APIG FullAccess系统策略的权限，并自动新增如下自定义策略授权委托到最小化权限。 
      "apig:vpcChannels:*",
"apig:apis:*",
"apig:instances:*",
"apig:envs:*",
"apig:groups:*",
"apig:apps:*"
    • 执行“自动创建委托”和“委托一键授权”的用户需要如下最小权限。 
      "iam:agencies:listAgencies",
"iam:roles:listRoles",
"iam:agencies:getAgency",
"iam:agencies:createAgency",
"iam:permissions:listRolesForAgency",
"iam:permissions:grantRoleToAgency",
"iam:permissions:listRolesForAgencyOnProject",
"iam:permissions:revokeRoleFromAgency",
"iam:roles:createRole"
    • 使用委托的用户需要如下最小权限。 
      "iam:agencies:listAgencies",
"iam:agencies:getAgency",
"iam:permissions:listRolesForAgencyOnProject",
"iam:permissions:listRolesForAgency"

    安全认证

    有APP认证和IAM认证两种方式，推荐使用APP认证方式。

    • “APP认证”：表示由API网关服务负责接口请求的安全认证。APP认证方式具体有多种认证路径。推荐使用AppCode简易认证。
      • 使用AppCode简易认证（推荐）：简易认证指在调用API时，HTTP请求头部消息增加一个参数X-Apig-AppCode（参数值填凭据详情中“AppCode”的值），而不需要对请求内容签名，API网关也仅校验AppCode，不校验请求签名，从而实现快速响应。以下为操作步骤：
        1. 单击“凭据管理”，进入凭据管理页面。
          图1 凭据管理
        2. 在“凭据管理”页面，单击“创建凭据”按钮，进入“创建凭据页面”，根据下面参数说明，填写凭据信息。

          凭据名称：凭据的名称。支持英文、中文、数字、下划线，且只能以英文或中文开头，长度为3~64个字符。

          描述：对凭据的介绍。长度为1~255个字符。

        3. 单击“确定”，创建凭据。
        4. 创建完成后单击创建好的凭据名称进入凭据详情页面。
        5. 单击“添加AppCode”按钮。

        6. 生成方式选择“自动生成”，单击“确定”。

        7. 生成好的AppCode出现在列表中。

          AppCode添加完成后，您可以使用AppCode进行API请求的简易认证。

          发送请求时，增加请求头部参数“X-Apig-AppCode”，省略请求签名相关信息。

          以Curl方式为例，增加头部参数名称：X-Apig-AppCode，参数值填已生成的AppCode。

          curl -X GET "https://api.exampledemo.com/testapi" -H "content-type: application/json"  -H "host: api.exampledemo.com" -H "X-Apig-AppCode: xhrJVJKABSOxc7d***********FZL4gSHEXkCMQC"
        8. 创建好凭据后，返回到发布页面，选择创建好的凭据，进行下一步操作。
      • 使用密钥对（Key、Secret）认证。需要在API网关中创建一个凭据，以生成凭据ID和密钥对，将创建的凭据绑定API后，才可以使用APP认证调用API。客户端（API调用者）在调用API过程中，把密钥对替换SDK中的密钥对，API网关服务根据密钥对进行身份核对，完成鉴权。具体创建凭据的步骤，请参考配置APIG的API认证凭据。
    • “华为IAM认证”：表示借助IAM服务进行安全认证。
      说明：

      选择“华为IAM认证”时，任何API网关租户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。
  5. 单击“确定”。

    当API的“状态”变成“已发布”时，表示该API已发布到环境，支持被调用。

调用已发布的KooSearch API

在业务环境中调用已发布的KooSearch API。

具体操作请参见。

编辑API

已发布的API，支持修改安全认证方式。

  1. 进入KooSearch服务详情页面。
    1. 登录云搜索服务管理控制台。
    2. 在左侧导航栏选择“KooSearch>KooSearch文档问答”，进入KooSearch服务列表。
    3. 选择目标服务，单击服务名称，进入服务详情页。
  2. 单击“API管理”，进入API管理页签。
  3. 选择已发布的API，单击操作列的“编辑”。
  4. 在“编辑”页面修改API的安全认证方式。
    • “华为IAM认证”：表示借助IAM服务进行安全认证。

      选择“华为IAM认证”时，任何API网关租户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。

  5. 单击“确定”完成修改。

下线API

已发布的API因为其他原因需要暂停对外提供服务，可以暂时将API从相关环境中下线。

该操作将导致此API在指定的环境无法被访问，请确保已经告知使用此API的用户。

  1. 进入KooSearch服务详情页面。
    1. 登录云搜索服务管理控制台。
    2. 在左侧导航栏选择“KooSearch>KooSearch文档问答”，进入KooSearch服务列表。
    3. 选择目标服务，单击服务名称，进入服务详情页。
  2. 单击“API管理”，进入API管理页签。
  3. 选择待下线的API，单击操作列的“下线”。
  4. 在滑出的页面中选择下线API的“实例”、“下线环境”、“配置委托”后单击“确定”。
  5. 待API的状态变为“未发布”，下线成功。