介绍

简介

物解析是在云端为用户提供工业协议解析服务(比如Modbus和OPC UA)服务。当云端收到网关返回的原始数据后,结合用户提供的设备通讯地址表,“物解析”将数据解析成直接可用于存储和分析的数据。

物解析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的域名
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的返回状态码为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"   
}

公共错误码

Code Message HTTP Status Code 说明
BceValidationException [param]:[param]=[Validation criteria] 400 无效的[param]参数
MoneyNotEnough Money not enough to complete the current request 400 余额不足以完成当前的请求操作
SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details 400 Authorization头域中附带的签名和服务端验证不一致
InvalidAccessKeyId The Access Key ID you provided does not exist in our records 403 Access Key ID不存在
ServiceInternalError Service internal error occurred 500 内部服务发生错误

签名认证

物解析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个小写字母组成,生成方式由如下签名生成算法给出。

签名生成算法

有关签名生成算法的具体介绍,请参看鉴权认证机制

多区域选择

物解析目前仅支持“华南-广州”区域,区域的API地址为:parser.iot.gz.baidubce.com