AICP 系统配置接口开发手册

1. 概述

系统配置接口由 aicp_sysconf 服务提供，支持一些系统配置的维护，包括：

• 应用
• 配置集
• 租户
• 分区

2. 接口定义

2.1 应用

以下描述中，URI 前面都省略了 /v10/sysconf/。

接口说明	接口	备注
创建应用	POST /apps	返回 appkey
查看应用	GET /apps/<appkey>
查询应用	GET /apps
修改应用	PATCH /apps/<appkey>
重置秘钥	PATCH /apps/<appkey>/secret
删除应用	DELETE /apps/<appkey>

2.1.1 创建应用

POST /apps

创建一个新的应用。

新建应用时，会在 Consul 中新建 /app/{appkey} KV 值，以便其它系统监听并接受到此信息。其值为：

{

"name": "应用A",

"description": "应用描述",

"secret": "asIds1x18"

}

• 请求消息

参数	类型	必选	说明
name	String	是	应用名称，不能重复，中英文、数字、-、_
description	String	否	应用描述

{

"name": "应用A",

"description": "应用描述"

}

• 响应消息

{

"created": {

"appkey": "12345678", // appkey, 8位字符串

"secret": "asIds1x1" // 自动生成的secret，8位字符串

}

}

2.1.2 查看应用

GET /apps/<appkey>

• 请求消息

无

• 响应消息

{

"appkey": "12345678",

"name": "应用A",

"description": "应用描述",

"secret": "asIds1x1"

}

2.1.3 查询应用

• 请求参数

参数	类型	必选	说明
offset	Integer	否	当前查询返回列表的起始偏移，缺省为0
limit	Integer	否	当前查询返回列表数量，缺省为50，范围为 [10-1000]
name	String	否	查找名称为此值的应用

例如：

GET /v10/sysconf/apps?offset=10&limit=20

GET /v10/sysconf/apps?name=应用A

• 请求消息

无

• 响应消息

{

"total": 123, // 总的数量

"offset": 10, // 和前端指定一致

"limit": 20, // 和前端指定一致

"apps": [ // 实际数量由此数组大小决定

{

"appkey": "12345678",

"name": "应用A",

"description": "应用描述",

"secret": "asIds1x1"

},

...

]

}

2.1.4 修改应用

PATCH /apps/<appkey>

修改应用信息时，会在 Consul 修改对应的 KV 值。

• 请求消息

可修改字段：name, description。

各字段都是可选的，具体请查看“创建应用”。

• 响应消息

{

"updated": {

"appkey": "12345678"

}

}

2.1.5 重置秘钥

PATCH /apps/<appkey>/secret

重置 secret，会在 Consul 修改对应的 KV 值。

• 请求消息

无

• 响应消息

{

"updated": {

"appkey": "12345678",

"secret": "1w03xs94" // 新秘钥

}

}

2.1.6 删除应用

DELETE /apps/<appkey>

删除应用时，会在 Consul 中删除对应的 KV 值，以便其它系统监听并接受到此信息，同时会删除此应用下的所有配置集 (profile)。

• 请求消息

无

• 响应消息

{

"deleted": {

"appkey": "12345678"

}

}

2.2 配置集

以下描述中，URI 前面都省略了 /v10/sysconf/。

接口说明	接口	备注
创建配置集	POST /profiles	返回 profileId
查看配置集	GET /profiles/<profileId>
查询配置集	GET /profiles
修改配置集	PATCH /profiles/<profileId>
删除配置集	DELETE /profiles/<profileId>

2.2.1 创建配置集

POST /profiles

创建一个新的配置集。

新建应用时，会在 Consul 中新建 /{capkey}/profile/app/{appkey}/{profileName} KV 值， (共享配置集 {appkey} 取 shared），以便其它系统监听并接受到此信息。其值为：

{

"id": 1001,

"description": "配置集描述",

"config": {

// 和capkey有关, 以 asr.cloud.freetalk 为例, 目前只考虑动态优化资源

"userword" : { // 可以没有，表示没有配置热词

"id": "xxxxxx",

"type": "REPLACE",

},

"sensword": {

"id": "xxxx",

"type": "REPLACE",

},

"olm" : {

"id": "xxxxx" // olm 时没有 type 项

}

}

}

• 请求消息

参数	类型	必选	说明
name	String	是	配置集名称，一个AI能力下不能重复，中英文、数字、-、_
description	String	否	配置集描述
capkey	String	是	AI能力标识
appkey	String	否	应用标识，从“创建应用”接口获取 缺省为 "*"，表示共享的配置集
config	Object	是	具体的配置，JSON对象，和 capkey 相关。

在能力调用时，在接口参数中会使用配置集的 name，因此同样的 appkey 下，name 不能重复。共享的配置集下，name 也不能重复。

{

"name": "profile_A",

"description": "配置集描述",

"capkey": "asr.cloud.freetalk",

"appkey": "12345678",

"config": {

// 和capkey有关, 以 asr.cloud.freetalk 为例, 目前只考虑动态优化资源

"userword" : { // 可以没有，表示没有配置热词

"id": "xxxxxx",

"type": "REPLACE",

},

"sensword": {

"id": "xxxx",

"type": "REPLACE",

},

"olm" : {

"id": "xxxxx" // olm 时没有 type 项

}

}

}

• 响应消息

{

"created": {

"profileId": 1001,

}

}

2.2.2 查看配置集

GET /profiles/<profileId>

• 请求消息

无

• 响应消息

{

"id": 1001,

"name": "profile_A",

"description": "配置集描述",

"capkey": "asr.cloud.freetalk",

"appkey": "12345678",

"config": {

// 和capkey有关, 以 asr.cloud.freetalk 为例, 目前只考虑动态优化资源

"userword" : { // 可以没有，表示没有配置热词

"id": "xxxxxx",

"type": "REPLACE",

},

"sensword": {

"id": "xxxx",

"type": "REPLACE",

},

"olm" : {

"id": "xxxxx" // olm 时没有 type 项

}

}

}

2.2.3 查询配置集

• 请求参数

参数	类型	必选	说明
offset	Integer	否	当前查询返回列表的起始偏移，缺省为0
limit	Integer	否	当前查询返回列表数量，缺省为50，范围为 [10-1000]
capkey	String	否	查询AI能力标识为 capkey 的配置集
appkey	String	否	查询应用标识为 appkey 的配置集 为 "*"，表示查询共享的配置集

capkey 和 appkey 条件同时存在时，两个条件是“与”的关系。

例如：

GET /v10/sysconf/profiles?offset=10&limit=20

GET /v10/sysconf/profiles?offset=10&limit=20&capkey=asr.cloud.freetalk&appkey=12345678

• 请求消息

无

• 响应消息

{

"total": 123, // 总的数量

"offset": 10, // 和前端指定一致

"limit": 20, // 和前端指定一致

"apps": [ // 实际数量由此数组大小决定

{

"id": 1001,

"name": "profile_A",

"description": "配置集描述",

"capkey": "asr.cloud.freetalk",

"appkey": "12345678",

"config": {

// 和capkey有关, 以 asr.cloud.freetalk 为例, 目前只考虑动态优化资源

"userword" : { // 可以没有，表示没有配置热词

"id": "xxxxxx",

"type": "REPLACE",

},

"sensword": {

"id": "xxxx",

"type": "REPLACE",

},

"olm" : {

"id": "xxxxx" // olm 时没有 type 项

}

}

}

...

]

}

2.2.4 修改配置集

PATCH /profiles/<profileId>

修改配置集信息时，会在 Consul 修改对应的 KV 值。修改 name 时，会删除原来的 KV，创建新的 KV。

• 请求消息

可修改字段：name, description, config。

各字段都是可选的，具体请查看“创建配置集”。

• 响应消息

{

"updated": {

"id": 1001

}

}

2.2.5 删除配置集

DELETE /profile/<profileId>

删除应用时，会在 Consul 中删除对应的 KV 值，以便其它系统监听并接受到此信息。

• 请求消息

无

• 响应消息

{

"deleted": {

"id": 1001

}

}

2.3 租户

以下描述中，URI 前面都省略了 /v10/sysconf/。

接口说明	接口	备注
创建租户	POST /tenants	返回 tenantId
查看租户	GET /tenants/<tenantId>
查询租户	GET /tenants
修改租户	PATCH /tenants/<tenantId>
删除租户	DELETE /tenants/<tenantId>

2.3.1 创建租户

POST /tenants

创建一个新的租户。一个平台下的租户都是统一管理的，所有的租户名称都不能够重复。

新建租户信息时，会在 Consul 中新建 /tenant/{tenantId} KV 值，以便其它系统监听并接受到此信息。其值为：

{

"name": "租户A",

"description": "长城电子公司",

"zoneId": 0

}

• 请求消息

参数	类型	必选	说明
name	String	是	租户名称，所有租户名称不能重复，中英文、数字、-、_
description	String	否	租户描述
zoneId	Integer	否	分区Id，缺省为0

zoneId 为一个从“创建分区”获得的分区Id，也可以为0，表示缺省分区。

{

"name": "租户A",

"description": "长城电子公司",

"zoneId": 0

}

• 响应消息

{

"created": {

"id": "12345678", // tenantId, 8位字符串

}

}

2.3.2 查看租户

GET /tenants/<tenantId>

• 请求消息

无

• 响应消息

{

"id": "12345678",

"name": "租户A",

"description": "长城电子公司",

"zoneId": 0

}

2.3.3 查询租户

• 请求参数

参数	类型	必选	说明
offset	Integer	否	当前查询返回列表的起始偏移，缺省为0
limit	Integer	否	当前查询返回列表数量，缺省为50，范围为 [10-1000]
name	String	否	查找名称为此值的租户
zoneId	Integer	否	查找绑定此分区的租户

name 和 zoneId 条件同时存在时，两个条件是“与”的关系。

例如：

GET /v10/sysconf/tenants?offset=10&limit=20

GET /v10/sysconf/tenants?name=TenantA

• 请求消息

无

• 响应消息

{

"total": 123, // 总的数量

"offset": 10, // 和前端指定一致

"limit": 20, // 和前端指定一致

"tenants": [ // 实际数量由此数组大小决定

{

"id": "12345678",

"name": "租户A",

"description": "长城电子公司",

"zoneId": 0

},

...

]

}

2.3.4 修改租户

PATCH /tenants/<tenantId>

• 请求消息

可修改字段：name, description, zoneId。

各字段都是可选的，具体请查看“创建租户”。

修改租户信息时，会在 Consul 修改对应的 KV 值。

• 响应消息

{

"updated": {

"id": "12345678"

}

}

2.3.5 删除租户

DELETE /tenants/<tenantId>

删除租户信息时，会在 Consul 中删除对应的 KV 值，以便其它系统监听并接受到此信息，进行此租户与本系统相关资源的清理。

• 请求消息

无

• 响应消息

{

"deleted": {

"id": "12345678"

}

}

2.4 分区

以下描述中，URI 前面都省略了 /v10/sysconf/。

接口说明	接口	备注
创建分区	POST /zones	返回 zoneId
查看分区	GET /zones/<zoneId>
查询分区	GET /zones
修改分区	PATCH /zones/<zoneId>
删除分区	DELETE /zones/<zoneId>

2.4.1 创建分区

POST /zones

创建一个新的分区。

• 请求消息

参数	类型	必选	说明
name	String	是	分区名称，所有分区名称不能重复，中英文、数字、-、_
description	String	否	分区描述

{

"name": "分区A",

"description": "分区描述",

}

• 响应消息

{

"created": {

"id": 12

}

}

2.4.2 查看分区

GET /zones/<zoneId>

zoneId 是从“创建分区”接口获得的，也可以为 0，表示 “缺省分区”。

• 请求消息

无

• 响应消息

{

"id": 1223,

"name": "分区A",

"description": "分区描述",

}

2.4.3 查询分区

• 请求参数

参数	类型	必选	说明
offset	Integer	否	当前查询返回列表的起始偏移，缺省为0
limit	Integer	否	当前查询返回列表数量，缺省为50，范围为 [10-1000]
name	String	否	查找名称为此值的分区

例如：

GET /v10/sysconf/zones?offset=10&limit=20

GET /v10/sysconf/zones?name=Zone1

• 请求消息

无

• 响应消息

{

"total": 123, // 总的数量

"offset": 10, // 和前端指定一致

"limit": 20, // 和前端指定一致

"zones": [ // 实际数量由此数组大小决定

{

"id": 1223,

"name": "分区A",

"description": "分区描述",

},

...

]

}

2.4.4 修改分区

PATCH /zones/<zoneId>

修改一个分区的信息。zoneId 是从“创建分区”接口获得的，也可以为 0，表示 “缺省分区”。

• 请求消息

可修改字段：name, description。

各字段都是可选的，具体请查看“创建分区”。

• 响应消息

{

"updated": {

"id": 12

}

}

2.4.5 删除分区

DELETE /zones/<zoneId>

删除分区。不能删除有租户绑定的分区，也不能删除缺省分区，如果删除，返回 409 Conflict。

• 请求消息

无

• 响应消息

{

"deleted": {

"id": 12

}

}

3. 版本记录

接口版本	平台支持版本	组件及支持版本	修改内容
10.1.0	10D.1	aicp_sysconf 10.1.0	增加应用和配置集的管理接口
10.0.0	10D.0	aicp_sysconf 10.0.0	初始版本