规则引擎Rule Engine

    规则字典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"
    }
    上一篇
    数据接口
    下一篇
    Java-SDK