本文档列举了物联网络管理平台 API 的公共请求参数和公共返回参数。

公共请求参数是调用每个 API 时都需要使用的请求参数。

名称 类型 是否必需 描述
Format String 返回值的类型,支持 JSON 和 XML 类型。
Version String API版本号,为日期形式:YYYY-MM-DD,最新版本为2019-03-01。每个接口可以存在多个版本。
AccessKeyId String 阿里云颁发给用户的访问服务所用的密钥 Id。
Signature String 签名结果串。
SignatureMethod String 签名方式,目前支持 HMAC-SHA1。
Timestamp String 请求的时间戳。日期格式按照 ISO8601 标准表示,并需要使用 UTC 时间。格式为YYYY-MM-DDThh:mm:ssZ。例如:2019-01-20T12:00:00Z(为北京时间2019年01月20日20点0分0秒)。
SignatureVersion String 签名算法版本。目前版本是1.0。
SignatureNonce String 唯一随机数。用于防止网络重放攻击。用户在不同请求中要使用不同的随机数值。
RegionId String 服务所在地域(与控制台上的Region对应),目前仅支持 cn-shanghai。
Action String API 方法名,用来指定所请求的操作。

示例

https://linkwan.cn-shanghai.aliyuncs.com/
?Format=JSON
&Version=2019-01-20
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&AccessKeyId=...
&Timestamp=2019-01-20T12:00:00Z
&RegionId=cn-shanghai
&Action=GetGateway
&GwEui=0000000000000000
			

公共返回参数

API 返回结果采用统一格式。返回 4xx 或 5xx HTTP 状态码代表未能成功调用到物联网络管理平台的服务(例如签名错误等情况)。返回 2xx HTTP 状态码代表成功调用到物联网络管理平台的服务,但 API 请求的成功与否取决于具体的返回内容。返回的数据格式有 JSON 和 XML 两种,可以在发送请求时指定返回的数据格式。

每次请求接口,无论成功与否,系统都会返回本次请求的唯一标识 RequestId。

API 调用返回 2xx HTTP 状态码的情况下,存在请求成功、请求失败两类情况。下文例举这两类情况的返回内容。

请求成功示例

  • JSON 格式
{
    "RequestId": "89EF6CAA-958F-F32C-BE45-FE003C6DE097",
    "Success": true,
    "Data": "返回的业务数据,Data 字段可能是列表、字典或简单类型。此外,并非所有 API 方法的返回参数中都包含 Data 字段。"
}
			
  • XML 格式
<?xml version="1.0" encoding="utf-8"?>
<API 方法名 + Response>
    <RequestId>89EF6CAA-958F-F32C-BE45-FE003C6DE097</RequestId>
    <Success>true</Success>
    <Data>返回的业务数据,Data 字段可能是列表、字典或简单类型。此外,并非所有 API 方法的返回参数中都包含 Data 字段。</Data>
</API 方法名 + Response>
			

请求失败示例

  • JSON 格式
{
    "RequestId": "89EF6CAA-958F-F32C-BE45-FE003C6DE097",
    "Code": "InternalError",
    "Message": "The request processing has failed due to some unknown error, exception or failure."
}
			
  • XML 格式
<?xml version="1.0" encoding="utf-8"?>
<API 方法名 + Response>
    <RequestId>89EF6CAA-958F-F32C-BE45-FE003C6DE097</RequestId>
    <Code>InternalError</Code>
    <Message>The request processing has failed due to some unknown error, exception or failure.</Message>
</API 方法名 + Response>