本文档介绍菜鸟IoT平台云端API的公共请求参数和公共返回参数。

公共请求参数

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

对于每一次HTTP或者HTTPS协议请求，菜鸟IoT平台会验证访问请求者的身份。身份验证包括三种方式：

  • AK/SK
  • Token
  • Cookie

    1. AK/SK方式：

    | 传参方式 | 名称 | 类型 | 是否必需 | 描述 | 格式及示例 | | —- | —- | —- | —- | —- | —- | | Headers | Authorization | String | 是 | 用于通过AK/SK方式访问菜鸟IoT服务时的数据校验和身份认证。 | 格式：
    algorithm Access=Access key, SignedHeaders=SignedHeaders, Signature=signature
    例如，
    CWS-HMAC-SHA256 Access=ClMDjAbYD9AjXI3tCF4sKJIc, SignedHeaders=content-type;host;x-cws-date, Signature=2fb0609f2469f5bd8108c06c38439d71acd1ffdd5ac1400bb1ef26d2445a1d72
    示例代码参见。 | | | X-Cws-Date | String | 是 | 用于校验通过AK/SK方式请求时的签名时间。 | 日期格式按照ISO8601标准表示，使用UTC时间，格式为：yyyyMMdd’T’HHmmss’Z’。
    例如，20211220T012159Z代表北京时间2021年12月20日9点21分59秒。
    示例代码参见。 |

AK/SK方式请求示例：

  1. curl --location --request GET 'https://service.example.com/group/INNTER_TEST_PRE/LEMO/devices/meta?search=&pageNo=1&pageSize=10'
  2. --header 'X-Cws-Date: 20211219T180338Z'
  3. --header 'Content-Type: application/json'
  4. --header 'Host: service.example.com'
  5. --header 'Authorization: CWS-HMAC-SHA256 Access=KlHDjAhYJ8AjXI3tBE4sIJIc, SignedHeaders=content-type;host;x-cws-date, Signature=ee42b63b800523df6e486193e7bc9fdadae4595e00957c6d6b581ef2bcfba5a0'

2. Token方式请求：

传参方式 名称 类型 是否必需 描述 格式及示例
Headers Token String 是 对于外部服务频繁调用菜鸟IoT平台受保护API的场景，Token可作为请求发起方的身份凭证。Token申请、Token刷新。 Token格式为格式为32位UUID：
002689b8-a50a-4f49-8c32-a463d6175446

Token方式请求示例：

curl --request GET 'https://service.example.com/products/shared' 
--header 'Token: 002689b8-a50a-4f49-8c32-a463d6175446'

3. Cookie方式请求：

传参方式 名称 类型 是否必需 描述 格式及示例
Headers Cookie String 否 保存用户登录状态的载体，由服务端下发并一般存储于浏览器中。服务端可通过Cookie识别用户身份及其有效性。
Cookie申请方式：帐密方式登录菜鸟IoT平台成功后，服务端会通过Set-Cookie头部将Cookie下发给客户端。
国内菜鸟IoT平台的Cookie作用域为.cainiao.com。		 Cookie格式为1个及以上的形如“key=value”的键值对集合，键值对间以冒号分隔：```json

SL34syaT=8C5D983BCBE6B9EFC7610EFF8ADB68A1; TwAhx8HL=C6BCB215B673113B88DEFEF22D0D5CD441D3D197ABA710AE36592A8446521ABFFD450F1DEF72F959E109045A4AF3574FD9E82E5E40A2D92EE258CB9BF0D4CEB185A22E147C92914724A36A2B2658281C9604F99845F0E6DD13A1B3A72635475D9122E2DA879F45B91FC6C25BC693817443261226126D9ADBFE753BFA707448C7E2EF05DA3123F2D9D17C0275BA0C0EF2ABE354FAEDC92A94435DFDB06FF1C5B4D3964330E9C44DB2B51837C5A6B9D9AC; account=MTU5Mjc1MzAyNzI=; accountId=NDA1ODg3ODIzNQ==; cncc=0a993cbc6ee971565e8eee4ef2a5fda4; cpcode=null; isLogin=true; lvt=1632721629831

 |

Cookie方式请求示例：
```java
curl --request GET 'https://service.example.com/businesses'
--header 'cookie: Hm_lvt_e70cb2c2a0f1de9b26160797400a5834=1638432969,1638860118; Hm_lvt_cf0b60286fae81792a6d6aefcfcfa4e1=1638432969,1638860118; cn_account_lang=zh; cna=BFKGGd5OOEACAYzNHAZim+h/; _hvn_login=21; SL34syaT=8C5D983BCBE6B9EFC7610EFF8ADB68A1; cpcode=cainiao; SSO_EMPID_HASH_V2=7103e9ab3e12e0037c3a28a58fdcdab4; SSO_BU_HASH_V2=4c988a8f25f822c7b8c069698622f053; tenantKey=0dc2223848734fd8; businessId=IOT_INNTER_TEST; TwAhx8HL=C6BCB215B673113B88DEFEF22D0D5CD441D3D197ABA710AE36592A8446521ABFDB183C82A28632B5F93401F00864AE1FCF3656D03379EDA4D389196F04F5F020D33FCD53C0381C326E8B83729CB867875EE5CCF157C98E91D22A7AF4D58700A3C715Ng==; isLogin=true; account=MTU5Mjc1MzAyNzI=; Hm_lpvt_e70cb2c2a0f1de9b26160797400a5834=1639970767; Hm_lpvt_cf0b60286fae81792a6d6aefcfcfa4e1=1639970767; tfstk=cNtGBij--6NSQtQHPcs6pzcSpQldZl3NZn-pY3rU4dmDeLxFiWUUzEkjK1RMDr1..; l=eBxEU0hrg2UbLri8XOfwourza77OSIRAguPzaNbMiOCPOSCp5JdRW6Q36S89C3GVh6rJR38X6jQgBeYBcIYU-S-RoyVga7kmn; isg=BDU14wc4uEvU2dzpjaiSMjNVRLfvsunEP18igLda8az7jlWAfwL5lEMI2FK4zgF8'

公共返回参数

API返回结果采用统一格式，返回2xx HTTP状态码代表调用成功；返回4xx或5xx HTTP状态码代表调用失败。调用成功返回的数据格式有String文本和JSON两种。

  • 调用成功的返回示例。

    • String文本格式

      200 OK
https://pre-zb-devops.iot.cainiao.com/p/1jux34?expire=1634049029788

    • JSON格式

      200 OK
[
{
   "groupId": "IOT_INNTER_TEST_PRE",
   "groupName": "IoT内部测试_预发",
   "env": "pre"
},
{
   "groupId": "IOT_INNTER_TEST_PROD",
   "groupName": "IoT内部测试_生产",
   "env": "prod"
}
]

  • 失败调用的返回示例。

    调用接口出错后，将不会返回结果数据。可根据错误码来定位错误原因。

当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。4xx状态码表示用户输入参数有误，5xx状态码表示服务端内部错误。返回文本中是具体的错误代码及错误信息。在您不能确认错误的情况下，可以联系菜鸟小二，并提供请求路径及参数，以便工作人员尽快帮您解决问题。

失败调用时常见的状态码及response示例：

400 Bad Request
business id can't be empty

401 Unauthorized
AkSk validation failed.

404 Not Found
Business not exists: IOT_INNTER_TEST

500 Internal Server Error
Update install policy rule failed