跳到主要内容
版本:1.4.0

服务账号

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

服务账号与开放平台

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

开放平台 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对应鉴权值需要替换为真实有效值。