# 通过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. [创建实例](https://support.huaweicloud.com/usermanual-apig/apig_03_0037.html)：使用API网关，需要先购买实例。 ![](https://support.huaweicloud.com/usermanual-koosearch/public_sys-resources/note_3.0-zh-cn.png) 实例需要跟KooSearch服务在同一个VPC和子网。 2. [创建API分组](https://support.huaweicloud.com/usermanual-apig/apig_03_0005.html)：API分组相当于API的集合，您在创建API前，需要先创建API分组。 3. [创建环境](https://support.huaweicloud.com/usermanual-apig/apig_03_0007.html)：API可以同时提供给不同的场景调用，如生产环境（RELEASE）及其他自定义环境。RELEASE是默认存在的环境，无需创建。 #### 发布KooSearch API 将KooSearch API发布到环境。 1. 进入KooSearch服务详情页面。 1. 登录[云搜索服务管理控制台](https://console.huaweicloud.com/elasticsearch/)。 2. 在左侧导航栏选择"KooSearch\>KooSearch文档问答"，进入KooSearch服务列表。 3. 选择目标服务，单击服务名称，进入服务详情页。 2. 单击"API管理"，进入API管理页签。 3. 选择待发布的API，单击操作列的"发布"。 4. 在"发布"页面配置API网关信息。 表1发布服务 | 参数 | 说明 | |:---|:---| | 实例 | 使用API网关，需要先购买实例。可以单击右边的"实例管理"去创建实例。具体创建步骤请看[创建实例](https://support.huaweicloud.com/usermanual-apig/apig_03_0037.html)。 说明： 实例需要跟KooSearch服务在同一个VPC和子网。 | | 发布环境 | API可以同时提供给不同的场景调用，如生产环境（RELEASE）及其他自定义环境。 建议选择默认存在的环境"RELEASE"，RELEASE是默认的线上环境，是正式发布API的环境，只有发布在RELEASE上的API，才能上架售卖。 如果您需要创建自定义环境，具体创建步骤请看[创建环境](https://support.huaweicloud.com/usermanual-apig/apig_03_0007.html)。 | | 分组 | API分组相当于API的集合，API提供者以API分组为单位，管理分组内的所有API。 建议选择默认分组"DEFAULT"，该分组为系统自动生成，组内所有API均支持通过弹性公网IP（EIP）或私有IP地址两种方式访问。 如果您需要创建自定义分组，具体创建步骤请看[创建API分组](https://support.huaweicloud.com/usermanual-apig/apig_03_0005.html)。 | | 配置委托 | 选择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，不校验请求签名，从而实现快速响应。具体操作步骤，请参考[AppCode简易认证]。 - 使用密钥对（Key、Secret）认证。需要在API网关中创建一个凭据，以生成凭据ID和密钥对，将创建的凭据绑定API后，才可以使用APP认证调用API。客户端（API调用者）在调用API过程中，把密钥对替换SDK中的密钥对，API网关服务根据密钥对进行身份核对，完成鉴权。具体创建凭据的步骤，请参考[配置APIG的API认证凭据](https://support.huaweicloud.com/usermanual-apig/apig_03_0056.html)。 - "华为IAM认证"：表示借助IAM服务进行安全认证。 说明： 选择"华为IAM认证"时，任何API网关租户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。 | 5. 单击"确定"。 当API的"状态"变成"已发布"时，表示该API已发布到环境，支持被调用。 #### AppCode简易认证 以下为操作步骤： 1. 单击"凭据管理"，进入凭据管理页面。 图1凭据管理 ![](https://support.huaweicloud.com/usermanual-koosearch/figure/zh-cn_image_0000002558883909.png) 2. 单击"创建凭据"按钮，进入"创建凭据页面"，根据下面参数说明，填写凭据信息。 - 凭据名称：凭据的名称。支持英文、中文、数字、下划线，且只能以英文或中文开头，长度为3\~64个字符。 - 描述：对凭据的介绍。长度为1\~255个字符。 ![](https://support.huaweicloud.com/usermanual-koosearch/figure/zh-cn_image_0000002558764001.png) 3. 单击"确定"，创建凭据。 4. 创建完成后单击创建好的凭据名称进入凭据详情页面。 5. 单击"添加AppCode"按钮。 ![](https://support.huaweicloud.com/usermanual-koosearch/figure/zh-cn_image_0000002527604184.png) 6. 生成方式选择"自动生成"，单击"确定"。 ![](https://support.huaweicloud.com/usermanual-koosearch/figure/zh-cn_image_0000002527764132.png) 7. 生成好的AppCode出现在列表中。 ![](https://support.huaweicloud.com/usermanual-koosearch/figure/zh-cn_image_0000002558883911.png) ![](https://support.huaweicloud.com/usermanual-koosearch/public_sys-resources/note_3.0-zh-cn.png) AppCode添加完成后，您可以使用AppCode进行API请求的简易认证。 使用postman发送请求时，增加请求头部参数"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. 创建好凭据后，返回到发布页面，选择创建好的凭据，进行下一步操作。 #### 调用已发布的KooSearch API 在业务环境中调用已发布的KooSearch API。 具体操作请参见[API参考](https://support.huaweicloud.com/api-koosearch/koosearch_06_0008.html)。 #### 编辑API 已发布的API，支持修改安全认证方式。 1. 进入KooSearch服务详情页面。 1. 登录[云搜索服务管理控制台](https://console.huaweicloud.com/elasticsearch/)。 2. 在左侧导航栏选择"KooSearch\>KooSearch文档问答"，进入KooSearch服务列表。 3. 选择目标服务，单击服务名称，进入服务详情页。 2. 单击"API管理"，进入API管理页签。 3. 选择已发布的API，单击操作列的"编辑"。 4. 在"编辑"页面修改API的安全认证方式。 - "华为IAM认证"：表示借助IAM服务进行安全认证。 ![](https://support.huaweicloud.com/usermanual-koosearch/public_sys-resources/note_3.0-zh-cn.png) 选择"华为IAM认证"时，任何API网关租户均可以访问此API，可能存在恶意刷流量，导致过量计费的风险。 5. 单击"确定"完成修改。 #### 下线API 已发布的API因为其他原因需要暂停对外提供服务，可以暂时将API从相关环境中下线。 ![](https://support.huaweicloud.com/usermanual-koosearch/public_sys-resources/note_3.0-zh-cn.png) 该操作将导致此API在指定的环境无法被访问，请确保已经告知使用此API的用户。 1. 进入KooSearch服务详情页面。 1. 登录[云搜索服务管理控制台](https://console.huaweicloud.com/elasticsearch/)。 2. 在左侧导航栏选择"KooSearch\>KooSearch文档问答"，进入KooSearch服务列表。 3. 选择目标服务，单击服务名称，进入服务详情页。 2. 单击"API管理"，进入API管理页签。 3. 选择待下线的API，单击操作列的"下线"。 4. 在滑出的页面中选择下线API的"实例"、"下线环境"、"配置委托"后单击"确定"。 5. 待API的状态变为"未发布"，下线成功。