请求数据

请求协议

请求的协议建议为https，如果使用http，服务器端会返回301引导客户端进行重定向，而某些开发语言的解析框架无法自动转向，还需要编码。所以建议第三方直接使用https协议。

请求头

1.请求的header中请不要随意增加不在报文范例中的键值对，否则服务器端可能由于无法理解请求中包含的header，而返回400 Bad Request错误。

2.所有接口请求头部都需要放入Authorization属性，值为token_type(默认为bearer) + access_token，获取token的接口除外

3.部分接口请求头部需要指定contentType，具体参考接口的请求报文示例

请求数据

1.接口根据设计的不同，请求数据的传参方式也不同，例如查询参数、路径参数、application/x-www-form-urlencoded、application/json等，具体需要参考接口的请求报文示例

2.接口中的字段长度均表示最大长度，给第三方设计数据库字段长度做参考

3.必传参数没有传、传参方式不对、参数格式不对等情况下接口会返回参数错误，请对照接口文档进行修改

请求示例

         POST  /xxx/xxxx  HTTP/1.1
         Host:api2.hik-cloud.com
         Content-Type:application/x-www-form-urlencoded; charset=utf-8
         Authorization:bearer  62c54b72-c85f-4a4e-8fd0-6941744d0af7

例如上述请求报文示例，说明了接口请求方式为POST，接口路径为xxx/xxx，协议为HTTP/1.1，请求主机地址为api2.hik-cloud.com，contentType指定了传参方式为application/x-www-form-urlencoded，编码方式为utf-8，Authorization指定了认证信息。

请求返回

1.请求返回的HTTP状态码为200表示请求成功，非200的错误码则为请求错误，例如401为认证失败，需要重新获取token，429为接口请求频率超过限制，500为服务端错误

2.请求返回数据中的code为200时表示请求成功，返回非200的code则需要对照错误码表进行判断，一般返回的message中已有错误信息的说明

认证管理

云眸平台所有REST API的调用都需要身份认证，采用Client Credentials授权方式，即采用client_id、client_secret获取accessToken。获取认证信息方式如下：

接口地址：https://api2.hik-cloud.com/oauth/token

请求方式：POST

请求参数：

属性名称	属性描述	类型	是否必填	备注
client_id	客户端ID	String	是	使用云眸账号登录开放平台门户网站open2.hik-cloud.com，进入开发者服务查看获取
client_secret	访问密钥	String	是	使用云眸账号登录开放平台门户网站open2.hik-cloud.com，进入开发者服务查看获取
grant_type	认证模式	String	是	只支持传入”client_credentials”
scope	权限范围	String	否	可选填”app”

返回数据

属性名称	属性描述	类型	是否必填
access_token	访问令牌	String	是
token_type	令牌类型	String	是
expires_in	过期时间(秒)	Long	是
scope	权限范围	String	是

请求报文示例：

         POST  /oauth/token  HTTP/1.1
         Host:api2.hik-cloud.com
         Content-Type:application/x-www-form-urlencoded
         
         client_id=a4f********b324&client_secret=0b********df59e68&grant_type=client_credentials&scope=app

响应数据包如下所示，其中 “access_token” 字段即为请求 REST API 所需的令牌, 默认情况下，Access Token 有效期为7天，开发者需要对 Access Token的有效性进行判断，若调用API时返回Http状态码为401，则说明Access Token已失效，重新获取即可。

注：请勿频繁调用获取token接口，频繁调用会刷新当前token，导致token提前失效

         {
             "access_token": "62c54b72-c85f-4a4e-8fd0-6941744d0af7",
             "token_type":"bearer",
             "expires_in": 43199,
             "scope":"app"
         }

Postman调用示例：

注：在使用postman调试时，注意尽量不要使用浏览器插件版本的postman，使用客户端版本的。因为插件版本的默认会使用浏览器中的cookie和缓存，可能在调用时会出现问题而难以排查。

接口说明

请求数据#

请求协议#

请求头#

请求数据#

请求示例#

请求返回#

认证管理#

请求数据

请求协议

请求头

请求数据

请求示例

请求返回

认证管理