密级公开
版本10D.2

AICP NLU 资源管理 开发手册

2. 接口概览#

NLU 资源管理服务提供的接口均为 HTTP 形式，遵循 Restful 的风格，规范如下：

  • 所有集合型的资源名称使用复数，但如果是一个父资源下面独立的子资源使用单数
  • 一对多的资源，如果子资源类型只是在父资源下使用才有意义，那么子资源需要使用 nest 的方式来访问，同时也都需要父级资源的ID：
    • POST /tickets/12/messages，而非 POST /messages?ticket_id=12
    • GET /tickets/12/messages/5，而非 GET /tickets/messages/5
  • PUT 表示资源的整体更新， PATCH 表示资源的局部更新。为了简单和统一起见，我们都只提供 PATCH 方法。
  • 父资源的 PATCH 方法只支持自身属性的修改，不支持子资源的修改；所有子资源的增删改，都是通过子资源的URL来进行。
  • 由于有的HTTP客户端可能不支持 PATCH / PUT 等方法，或者有的防火墙只允许通过GET / POST，此时可以都使用POST，但头信息里包含 X-HTTP-Method-Override字 段，它的值是实际需要的方法。(优先级低，可不支持)

2.1 资源URI#

资源的URI均为如下格式： /v10/nlu/resource/{property}/xxxxxxxx?appkey={appkey}

xxxxxxxx 部分根据维护的资源不同而变化，会在下面具体描述。

2.2 URL 参数#

URL 中携带的参数如下：

参数类型必选说明
propertyString是模型特征串，服务器端利用此值来调用不同的模型
appkeyString是分配给开发者的 appkey

2.3 HTTP 头域参数#

请求的 HTTP Header 参数如下：

参数类型必选说明
Content-TypeString是application/json
X-Hci-Access-TokenString是从 get-access-token 接口获取的令牌
X-Tenant-IdString否租户ID

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口 get-access-token 获取到的令牌，详细见《系统服务 HTTP 开发手册》。

X-Tenant-Id 是租户ID，通过“系统配置服务接口”中的“创建租户”接口获取，或从管理后台中获取。

在不启用多租户的系统或者单机版中，可以没有 X-Tenant-Id 头，或者将租户 ID 设为空串。

注意

如果租户不存在、访问资源不存在、或者访问的资源存在但不属于当前租户，均会返回 404 Not Found

2.4 包体参数#

待处理的文本连同其它参数必须放在请求正文中，并以JSON格式编码。

2.5 响应格式#

在响应消息中，HTTP 状态码表示请求的总体执行情况，正文包含一个以JSON格式编码的字符串，用于携带进一步的信息。

  • 正常响应：HTTP 状态码为 200，响应包体中不包含“error”字段，但携带正常的结果数据。
  • 失败响应：HTTP 状态码为 200 之外的值，响应包体中包含“error”字段，包含详细错误码和错误信息。

2.5.1 正常响应#

正常响应的响应消息结构，针对不同调用接口是不一样的，会在后面的每个接口描述中详细说明。

以下是一个正常响应的示例：

{
"created" : {
"id": 1939
}
}

2.5.2 失败响应#

失败响应的响应消息结构为：

参数类型说明
errorObject发生错误时可用，如果请求成功将没有此字段

error 的结构如下：

参数类型说明
codeInteger错误代码，请参见 《AICP 10 开发通用规范》
messageString详细的错误信息

以下是一个失败响应的示例：

{
"error": {
"code": 29,
"message": "robotId is not found"
}
}