密级	公开
版本	10D.2

AICP 统一资源管理 HTTP开发手册

note

AICP-10 D.1 之前的版本中，提供了单独的 ASR 热词和敏感词的管理接口，这些接口在 10D.1 之后已废弃。

1. 概述#

AICP 10 统一资源管理服务（aicp_ros）为各能力提供动态资源的管理接口，通过HTTP接口实现对资源的增删改查操作。

2. 动态资源#

动态资源指可以动态维护和配置，来优化 AI 能力的轻量级资源，例如 ASR 能力的热词。

2.1 资源分类#

动态资源又分为用户资源与系统资源：

用户资源：客户端通过网关访问此接口创建资源并获得资源 ID，然后在调用能力接口时指定资源 ID。
- 用户共享资源：创建时不需要指定用户标识（userId），创建后同一开发者下的任何应用中都可以使用
- 用户独享资源：创建时需要指定 userId，创建后同一开发者下的任何应用中都可以使用，但使用时也需要指定同一个 userId
系统资源：管理后台或者内部的资源维护工具访问此接口创建资源。一般在创建后需要配置到请求配置集中，在使用时作为默认的资源。在有些能力中需要在调用接口中指定。

举例：

“用户独享资源” 是和某个特定用户相关的，例如将当前用户的手机通讯录作为 ASR 的 “热词”。
“用户共享资源” 则是外部第三方应用创建的，供此应用使用，但和某个特定用户无关。例如会议系统设置 ASR 的 “敏感词”，或者质检分析系统设置 NLP 的 “质检规则”。
“系统资源” 则是由 AICP 提供的管理后台或者资源维护工具（例如 OCR 模板编辑器）进行创建的，此类资源可以在管理后台进行查看或维护（即使有专门的资源维护工具，在管理后台也能查看）。例如可以在管理后台维护 ASR 的“敏感词”，或者 OCR 模板编辑器维护 OCR 的“自定义模板”。

2.2 支持的资源类型#

当前支持的资源类型如下：

cu	type	说明	系统资源	用户共享资源	用户独享资源
asr	userword	热词	✓	✓	✓
	sensword	敏感词	✓	✓
	olm	小语料优化模型	✓	✓
ocr	template	OCR 自定义模板	✓
nlp	qarule	质检规则	✓	✓
nlp	talktrick	话术	✓	✓

ASR的资源格式请参见 ASR 优化指南；NLP的资源格式请参见 NLP 资源指南。

OCR 自定义模板一般由 OCR 模板编辑器 进行维护，无需用户手动制作，也不支持用户资源类型，因此没有对应的格式描述。

3. 接口概览#

统一资源资源服务支持如下接口：

创建资源
POST http://ip:port/v10/resource/{category}/{cu}/{type}?appkey={appkey}&userId={userId}
修改资源
PUT http://ip:port/v10/resource/{category}/{cu}/{type}/{resId}?appkey={appkey}&userId={userId}
查找资源
GET http://ip:port/v10/resource/{category}/{cu}/{type}?appkey={appkey}&userId={userId}&offset={offset}&limit={limit}
下载资源
GET http://ip:port/v10/resource/{category}/{cu}/{type}/{resId}?appkey={appkey}&userId={userId}
删除资源
DELETE http://ip:port/v10/resource/{category}/{cu}/{type}/{resId}?appkey={appkey}&userId={userId}

上述接口均支持https形式。

3.1 URL 参数#

URL中的通用参数如下：

参数	类型	必选	缺省	说明
category	String	是		资源类别。可以取如下值： `user`: 用户资源 `sys`: 系统资源


cu	String	是		AI能力。参见支持的资源类型。
type	String	是		资源类型。参见支持的资源类型。
resId	String	否		资源ID。为“创建资源”接口返回的Id。
appkey	String	是		分配给开发者的 `appkey`
userId	String	否	*	用户ID。无此参数或者为 `*`/`空串` 时表示创建用户共享资源，否则表示创建用户独享资源仅在 `category` 为 `user` 时且支持用户独享资源时有效

note

category为sys的系统资源相关的接口，是AICP 平台内部使用的，外部应用无法访问。

3.2 HTTP 头域参数#

“创建资源”和“修改资源”接口都使用JSON串作为包体，因此在HTTP Header中需要如下参数：

参数	类型	必选	说明
Content-Type	String	是	application/json

上述接口暂时不需要先通过 get-access-token 接口获取 token，再将 token 放在 X-Hci-Access-Token 头中加以访问。

3.3 包体参数#

如果有请求消息，都会放在请求正文的包体中，并以JSON格式编码。

3.4 响应格式#

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

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

3.4.1 正常响应#

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

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

{
  "deleted" : {
    "id": 1939
  }
}

3.4.2 失败响应#

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

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

error 的结构如下：

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

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

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

后续只描述正常响应的消息结构。

4. 接口描述#

4.1 创建资源#

POST /v10/resource/{category}/{cu}/{type}?appkey={appkey}&userId={userId}

创建资源时，针对不同类型的资源，有一定的约束，例如允许创建的数目等。具体请参见各类资源的资源指南。

4.1.1 请求消息#

参数	类型	必选	说明
resource	Object	是	资源信息

resource的结构如下：

参数	类型	必选	缺省	说明
name	String	是		资源命名
lang	String	是		资源对应语种(参考`property`的第一部分)
desc	String	否	空串	资源描述
content	String	是		经过BASE64编码后的资源内容

如果不是共享的用户资源，则每个用户下资源的名称必须不一样。如果是共享的用户资源，则其下资源的名称必须不一样。

目前 lang 仅起记录作用，在识别时不会判断资源的此属性是否和当前模型一致，但未来版本可能会加入判断。

各种不同类型资源的具体资源内容格式，请参见各能力优化手册的“资源格式”一章。

4.1.2 响应消息#

参数	类型	说明
created	Object	调用成功标志创建的资源信息，调用失败时将没有此字段

created 的结构如下：

参数	类型	说明
id	String	资源ID
crc64	String	资源内容的校验信息
ver	String	当前版本信息

4.1.3 示例#

请求示例

{
  "resource":
  {
    "name": "telepower",
    "lang": "cn",
    "content": "5Zub5bedIFtzaTQgY2h1YW4xXQ=="
  }
}

上述content内容是"四川 [si4 chuan1]" 经过BASE64编码之后的串。

成功响应示例

{
  "created":
  {
    "id": "CFD08A32-6176-4ad7-92F9-11ED015C8109",
    "crc64": "E74B6FF9EBF138BE",
    "ver": "1"
  }
}

4.2 修改资源#

PUT /v10/resource/{category}/{cu}/{type}/{resId}?appkey={appkey}&userId={userId}

4.2.1 请求消息#

参数	类型	必选	说明
resource	Object	是	资源信息

resource 的结构和 “创建资源接口” 的输入参数一致。

4.2.2 响应消息#

参数	类型	说明
updated	Object	调用成功标识修改后的资源信息，调用失败时将没有此字段

updated 的结构如下：

参数	类型	说明
id	String	资源ID
crc64	String	资源内容的校验信息
ver	String	当前版本信息

其中 id 肯定和 URL 中的 resId 一致， ver 为修改后的最新版本号。

注意：目前版本只能更新 resource 中的 content，也即资源内容本身，无法更新 name, lang, desc 等元信息。

4.2.3 示例#

请求示例

{
  "resource":
  {
    "name": "telepower",
    "lang": "cn",
    "content": "5Zub5bedIFtzaTQgY2h1YW4xXQ=="
  }
}

成功响应示例

{
  "updated":
  {
    "id": "CFD08A32-6176-4ad7-92F9-11ED015C8109",
    "crc64": "E74B6FF9EBF138BE",
    "ver": "1"
  }
}

4.3 查找资源#

GET /v10/resource/{category}/{cu}/{type}?appkey={appkey}&userId={userId}&offset={offset}&limit={limit}

该接口支持查找一种类型下所有的资源。对于每个资源，都会返回其最新的版本。

4.3.1 URL 参数#

此接口包括额外的 URL 参数：

参数	类型	必选	缺省	说明
offset	number	否	0	查询时的起始位置
limit	number	否	100	每次查询返回的最大数量，范围[1-10000]

4.3.2 请求消息#

无

4.3.3 响应消息#

参数	类型	说明
totalCount	number	用户名下的此类资源总数，调用失败时将没有此字段
resourceList	array	用户名下的指定指定分页中的资源信息，调用失败时将没有此字段

resourceList 中的每一项结构如下：

参数	类型	说明
id	String	资源id
ver	String	资源的最新版本号
name	String	资源的名字
lang	String	资源的语种信息
desc	String	资源描述，如果为空，可能没有

注意：

此接口只返回资源的ID和元信息，不返回资源的具体内容。要查看资源的具体内容，请使用“查看资源”接口通过每个资源ID进行查看
找不到资源时返回错误，如果是offset大于总的数目了，则正常返回总数和空数组（[]）

4.3.4 示例#

请求示例
GET /v10/resource/user/asr/userword?appkey=appkey&userId=user
请求示例，带页码信息
GET /v10/resource/user/asr/userword?appkey=appkey&userId=user&offset=10&limit=10
成功响应示例

{
  "totalCount": 13,
  "resourceList": [
    {
      "id": "5F85A74C-BED9-4a15-B66E-039251D877D6",
      "ver": "1",
      "lang": "cn",
      "name": "weather",
    },
    {
      "id": "692602B7-3C4C-486a-954E-3256A0B9CE55",
      "ver": "2",
      "lang": "cn",
      "name": "arm",
    },
    {
      "id": "50875954-7328-42ab-B236-B3EC6E22207A",
      "ver": "1",
      "lang": "en",
      "name": "war",
      "desc": "some description"
    }
  ]
}

4.4 下载资源#

GET /v10/resource/{category}/{cu}/{type}/{resId}?appkey={appkey}&userId={userId}

4.4.1 请求消息#

无

4.4.2 响应信息#

参数	类型	说明
resource	Object	调用成功时表示资源内容，调用失败时将没有此项

resource 的结构如下：

参数	类型	说明
id	String	资源id
crc64	String	资源内容校验信息
path	String	资源存储路径
ver	String	资源的最新版本号
name	String	资源的名字
lang	String	资源的语种信息
desc	String	资源描述，如果为空，可能没有
content	String	BASE64编码后的资源内容

4.4.3 示例#

成功响应示例

{
  "resource":
  {
    "id": "CFD08A32-6176-4ad7-92F9-11ED015C8109",
    "crc64": "E74B6FF9EBF138BE",
    "ver": "3",
    "name": "telepower",
    "lang": "cn",
    "desc": "no desc",
    "content": "W+aIkOmDvSBjaGVuZzFkdTFdIg=="
  }
}

4.4.4 ETag 机制#

下载资源接口支持“ETag”机制，以避免重复下载相同的文件内容，具体流程如下：

客户端第一次发起 GET 请求一个文件
服务器处理请求，返回文件内容和 “ETag” 头，值为此文件的标识信息
当客户端再次发起 GET 请求，请求此文件时，可以带上 “If-None-Match” 头，值为第一次请求时服务器返回的 “ETag” 值
服务器检查当前的文件版本内容是否和此 “ETag” 值一致，如果一致，直接返回 304: Not Modified，无需返回文件内容；否则正常返回 200 OK 、新的文件内容和新的 “ETag” 头

示例：

第一次请求

GET /v10/resource/user/asr/userword/CFD08A32-6176-4ad7-92F9?appkey=xxxx&userId=xxxx

HTTP/1.1 200 OK
ETag: "3-E74B6FF9EBF138BE"

{
  "resource":
  {
    "id": "CFD08A32-6176-4ad7-92F9",
    "crc64": "E74B6FF9EBF138BE",
    "ver": "3",
    "name": "telepower",
    "lang": "cn",
    "desc": "no desc",
    "content": "W+aIkOmDvSBjaGVuZzFkdTFdIg=="
  }
}

第二次请求

GET /v10/resource/user/asr/userword/CFD08A32-6176-4ad7-92F9?appkey=xxxx&userId=xxxx
If-None-Match: "3-E74B6FF9EBF138BE"

如果服务器资源未改变，返回：

HTTP/1.1 304 Not Modified

如果服务器资源已改变，返回：

HTTP/1.1 200 OK
ETag: "4-6FF9E8A32BF138BE"

{
  "resource":
  {
    "id": "CFD08A32-6176-4ad7-92F9",
    "crc64": "6FF9E8A32BF138BE",
    "ver": "4",
    "name": "telepower",
    "lang": "cn",
    "desc": "no desc",
    "content": "6YeN5bqGIFtjaG9uZzIgcWluZzRdCiA="
  }
}

4.5 删除资源#

DELETE /v10/resource/{category}/{cu}/{type}/{resId}?appkey={appkey}&userId={userId}

如果要删除的 resId 属于某个用户，但提供的 userId 不匹配，会返回错误 404 Not Found。

4.5.1 请求消息#

无

4.5.2 响应消息#

参数	类型	说明
deleted	Object	调用成功时表示删除的资源内容，调用失败时将没有此项

deleted 的结构如下：

参数	类型	说明
id	String	被删除的资源id

4.5.3 示例#

成功响应示例

{
  "deleted":
  {
    "id": "6A522D0A-AAD6-428b-AAB8-E225EABEBC94",
  }
}

5. 版本记录#

接口版本	平台支持版本	组件及支持版本	修改内容
10.1.0	10E.0	aicp_ros 10.2.0	1. 新增 OCR/NLP 资源类型 2. 下载资源支持 ETag 机制
10.1.0	10E.0	aicp_ros 10.2.0	1. 新增 OCR/NLP 资源类型 2. 下载资源支持 ETag 机制
10.0.0	10D.1	aicp_ros 10.1.0	初始版本