规则字典API
调用方式
概述
规则字典API的设计采用了Restful风格,每个API功能(也可以称之为资源)都使用URI(Universal Resource Identifier)来唯一确定。对资源的请求方式是通过向资源对应的URI发送标准的 HTTP 请求,比如 GET、PUT、POST等,同时,请求需要遵守签名算法,并包含约定的请求参数。
通用约定
- 所有编码都采用UTF-8
- 日期格式采用yyyy-MM-dd方式,如2015-08-10
- 时间格式采用UTC格式:yyyy-MM-ddTHH:mm:ssZ, 如2015-08-20T01:24:32Z
-
Content-type为application/json; charset=UTF-8
- object类型的key必须使用双引号(")括起来
- object类型的key必须使用lowerCamelCase表示
公共请求头
头域(Header) | 是否必须 | 说明 |
---|---|---|
Authorization | 必须 | 包含Access Key与请求签名 |
Host | 必须 | 包含API的域名 |
x-bce-date | 必须 | 表示时间的字符串,符合时间格式要求 |
Content-Type | 可选 | application/json; charset=utf-8 |
公共响应头
头域(Header) | 说明 |
---|---|
Content-Type | 只支持JSON格式,application/json; charset=utf-8 |
x-bce-request-id | 规则字典后端生成,并自动设置到响应头域中 |
响应状态码
返回的响应状态码遵循RFC 2616 section 6.1.1
- 1xx: Informational - Request received, continuing process.
- 2xx: Success - The action was successfully received, understood, and accepted.
- 3xx: Redirection - Further action must be taken in order to complete the request.
- 4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
- 5xx: Server Error - The server failed to fulfill an apparently valid request.
请求消息体格式(HTTP Request Body)
规则字典服务要求使用JSON格式的结构体来描述一个请求的具体内容。
示例
以下是一个标准的创建字典时的请求消息体格式:
{
"name": "name",
"description": "description"
}
请求返回格式(HTTP Response)
规则字典服务均采用JSON格式的消息体作为响应返回的格式。
示例
以下是一个标准的获取字典列表的请求返回:
{
"result":[
{
"name":"name",
"description":"description",
"uuid":"0fef631b-cd2d-4d64-9351-c9dec9b8d298",
"keyCount":0,
"createTime":1551778483000,
"updateTime":1551778483000
}
],
"totalCount":1,
"pageNo":1,
"pageSize":10
}
通用错误返回格式
当调用接口出错时,将返回通用的错误格式。Http的返回状态码为4xx或5xx,返回的消息体将包括全局唯一的请求、错误代码以及错误信息。调用方可根据错误码以及错误信息定位问题,当无法定位到错误原因时,可以发工单联系百度技术人员,并提供requestid以便于快速地帮助您解决问题。
消息体定义
参数名 | 类型 | 说明 |
---|---|---|
requestId | String | 请求的唯一标识 |
code | String | 错误类型代码 |
message | String | 错误的信息说明 |
错误返回示例
{
"requestId": "47e0ef1a-9bf2-11e1-9279-0100e8cf109a",
"code":"NoSuchKey",
"message":"The resource you requested does not exist"
}
签名认证
规则字典 API会对每个访问的请求进行身份认证,以保障用户的安全。安全认证采用Access Key与请求签名机制。Access Key由Access Key ID和Secret Access Key组成,均为字符串,由百度智能云官方颁发给用户。其中Access Key ID用于标识用户身份,Access Key Secret 是用于加密签名字符串和服务器端验证签名字符串的密钥,必须严格保密。
对于每个HTTP请求,用户需要使用下文所描述的方式生成一个签名字符串,并将认证字符串放在HTTP请求的Authorization头域里。
签名字符串格式
bce-auth-v{version}/{accessKeyId}/{timestamp}/{expireTime}/{signedHeaders}/{signature}
其中:
- version是正整数,目前取值为1。
- timestamp是生成签名时的时间。时间格式符合通用约定。
- expireTime表示签名有效期限,单位为秒,从timestamp所指定的时间开始计算。
- signedHeaders是签名算法中涉及到的头域列表。头域名字之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。当signedHeaders为空时表示取默认值。
- signature是256位签名的十六进制表示,由64个小写字母组成,生成方式由如下签名生成算法给出。
签名生成算法
有关签名生成算法的具体介绍,请参看鉴权认证机制。
多区域选择
Region代表着一个独立的地域,是百度智能云中的重要概念,请参考区域选择说明。百度智能云中的服务除了极少数如账号服务全局有效之外,绝大部分服务都是区域间隔离的。每个区域的服务独立部署互不影响。服务间共享数据需要通过显式拷贝完成。在API中引用区域必须使用其ID。目前规则字典服务的区域是“华南-广州”、“华北-北京”,目前支持http和https调用。
接口域名
区域 | ID | 域名 | 协议 |
---|---|---|---|
华南-广州 | gz | iotredata.gz.baidubce.com | http和https |
华北-北京 | bj | iotredata.bj.baidubce.com | http和https |
管理接口
创建字典
方法 | API | 说明 |
---|---|---|
POST | /v1/dict | 创建字典 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
name | String | 是 | 字典名称 |
description | String | 否 | 字典描述 |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
uuid | String | 字典uuid |
请求示例
{
"name":"name",
"description":"description"
}
返回示例
{
"uuid":"0fef631b-cd2d-4d64-9351-c9dec9b8d298"
}
修改字典
方法 | API | 说明 |
---|---|---|
PUT | /v1/dict/{uuid} | 修改字典 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
description | String | 否 | 只支持修改description字段 |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
result | String | 修改结果 |
请求示例
{
"description":"description"
}
返回示例
{
"result":"OK"
}
获取字典列表
方法 | API | 说明 |
---|---|---|
GET | /v1/dict?pageNo={pageNo}&pageSize={pageSize}&q={q} | 获取字典列表 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
pageNo | Int | 否 | 分页的页数,默认为1 |
pageSize | Int | 否 | 分页的大小,默认为10 |
q | String | 否 | 根据名称进行模糊匹配,默认值为"" |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
result | List | 字典列表 |
totalCount | Int | 字典总数 |
pageNo | Int | 当前分页的页数 |
pageSize | Int | 分页的大小 |
其中result中每个元素拥有6个属性
参数名字 | 参数类型 | 说明 |
---|---|---|
name | String | 字典名字 |
description | String | 字典描述 |
uuid | String | 字典uuid |
keyCount | Int | 字典包含的key的总数 |
createTime | Long | 字典创建时间 |
updateTime | Long | 字典更新时间 |
请求示例
GET /v1/dict?pageNo=1&pageSize=10&q=name
返回示例
{
"result":[
{
"name":"name",
"description":"description",
"uuid":"0fef631b-cd2d-4d64-9351-c9dec9b8d298",
"keyCount":0,
"createTime":1551778483000,
"updateTime":1551778483000
}
],
"totalCount":1,
"pageNo":1,
"pageSize":10
}
获取字典详情
方法 | API | 说明 |
---|---|---|
GET | /v1/dict/{uuid} | 获取字典详情 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
uuid | String | 是 | 字典uuid |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
name | String | 字典名字 |
description | String | 字典描述 |
uuid | String | 字典uuid |
keyCount | Int | 字典包含的key的总数 |
createTime | Long | 字典创建时间 |
updateTime | Long | 字典更新时间 |
请求示例
GET /v1/dict/0fef631b-cd2d-4d64-9351-c9dec9b8d298
返回示例
{
"name":"name",
"description":"description",
"uuid":"0fef631b-cd2d-4d64-9351-c9dec9b8d298",
"keyCount":0,
"createTime":1551778483000,
"updateTime":1551778483000
}
删除字典
方法 | API | 说明 |
---|---|---|
DELETE | /v1/dict/{uuid} | 删除字典 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
uuid | String | 是 | 字典uuid |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
result | String | 删除结果 |
请求示例
DELETE /v1/dict/0fef631b-cd2d-4d64-9351-c9dec9b8d298
返回示例
{
"result":"OK"
}
数据接口
写入数据
方法 | API | 说明 |
---|---|---|
PUT | /v1/dict/data/{uuid} | 写入数据 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
Map | 是 | 待写入数据,一组kv对 |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
result | String | 默认为OK,全部写入失败为ERROR |
success | Int | 成功写入的kv对数量 |
errKey | List | 因key值不符合规范而写入失败的kv对的key列表 |
errValue | List | 因value值不符合规范而写入失败的kv对的key列表 |
请求示例
{
"key01":"value01",
"key02":"value02",
"key03":"{\"alarmCnt\": 23,\"info\": {\"imei\": \"imei2019001\", \"customer\": \"customer001\",\"sn\": \"2019003\" },\"subTopics\":[\"topic1\", \"topic2\"]}"
}
返回示例
{
"result":"OK",
"success":3,
"errKey":[],
"errValue":[]
}
删除数据
方法 | API | 说明 |
---|---|---|
DELETE | /v1/dict/data/{uuid}?key={key} | 删除数据 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
uuid | String | 是 | 字典uuid |
key | String | 是 | 待删除的key值 |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
result | String | 删除结果 |
请求示例
DELETE /v1/dict/data/0fef631b-cd2d-4d64-9351-c9dec9b8d298?key=key01
返回示例
{
"result":"OK"
}
获取数据
方法 | API | 说明 |
---|---|---|
GET | /v1/dict/data/{uuid}?key={key} | 获取数据 |
请求参数
参数名字 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
uuid | String | 是 | 字典uuid |
key | String | 是 | 需要获取的key值 |
返回参数
参数名字 | 参数类型 | 说明 |
---|---|---|
result | String | key对应的value |
请求示例
GET /v1/dict/data/0fef631b-cd2d-4d64-9351-c9dec9b8d298?key=key01
返回示例
{
"result": "value01"
}