跳到主要内容
版本：1.11.1

服务账号

本章节将讲解：什么是服务账号，以及如何通过服务账号管理和使用平台及机器人服务

服务账号与开放平台​

服务账号 是用于调用平台搭建和对话能力接口的的虚拟账号。通过服务账号完成鉴权认证后，开发者可以使用开放平台能力，而无需再依赖网页端应用。

开放平台 API 可以让你用任何支持发送 HTTP 请求的设备来与 Laiye 对话机器人平台进行交互。

你可以使用 API 做很多事情，比如：

  • 与即时通讯系统集成，获得机器人回复。
  • 配置机器人的平台数据。
  • 获取机器人的会话分析数据。
  • 获得部分 NLU 结果。

创建与调用​

为保证开放平台接口的安全性，在每次调用接口时，需要在请求的 Headers 对象中（Request Headers）附加服务账号ID和密钥用于鉴权认证。

创建服务账号​

  1. 在服务账号页面，点击“新建服务账号”按钮，即可创建一个新的服务账号，获得账号的 ID 和密钥。 create-zh-v1.3

  2. 如果需要更换账号密钥，点击对应账号行后面的“重置密钥”即可。注意更换密钥后，之前使用该账号密钥的接口均需更新为重置后的最新密钥。

开放平台调用方式​

开放平台接口调用是指向对话机器人平台服务端地址发送 HTTP/HTTPS 请求，并按照接口说明在请求中加入相应请求参数，调用后系统会返回处理结果。

请求开放平台接口时，需要使用 HTTP/HTTPS 协议、JSON 数据格式、UTF-8 编码。

POST 请求需要在 HTTP/HTTPS Headers 中设置Content-Type : application/json。

API 基础结构如下:

https://{Endpoint}/chatbot/{version}/agents/{agentId}/{type}/{action}

参数替换说明如下：

- Endpoint: 私有部署对应服务器开放的接入地址。
- version: 目前接口版本。
- agentId: 针对指定机器人，机器人id可在机器人设置中查看。
- type: 调用的api类型，比如user是用户类。
- action: 要执行的具体操作名称

详细各个接口的调用结构可以查看接口文档。

通过服务账号鉴权​

为了保证开放平台接口调用的安全性，需要通过服务账号进行鉴权认证。步骤如下:

  1. 从服务账号页面获取一组账号 ID 和 Secret： create-zh-v1.3

  2. 请求的鉴权是通过 HTTP Request Headers 里面包含的 4 个Api-Auth-xxx键值对来进行的，每次调用接口时需要在请求的 Headers 对象中（Request Headers）附加以下校验参数：

参数描述
Api-Auth-pubkey服务账号的账号 ID。
Api-Auth-nonce由调用方生成的随机数。位数不限，在一分钟之内每次请求中的随机数不可重复。
Api-Auth-sign由密钥、随机数 Api-Auth-nonce 生成。生成方法示例请见demo。
Api-Auth-timestamp秒级别时间戳，服务器生成随机数的时间点。

curl 命令示例：

curl -X POST https://{Endpoint}/chatbot/v1alpha1/agents/{agentId}/channels/{channelId}/users/mutate \
-H 'Api-Auth-pubkey: {{鉴权值}}' \
-H 'Api-Auth-nonce: {{鉴权值}}' \
-H 'Api-Auth-sign: {{鉴权值}}' \
-H 'Api-Auth-timestamp: {{鉴权值}}' \
-H 'Content-Type:application/json'
-d '{ \
   "operations": [
      {
         "create": {
         "username": "curl_username",
         "nickename": "curl_nickname",
         "avatarUrl": ""
         },
      }
   ]    
}'
caution

示例中请求路径中的{Endpoint}、{agentId}和{channelId}以及4个Api-Auth-xxx对应鉴权值需要替换为真实有效值。