貝殼物聯公開用戶接口
一、概述
二、添加第三方應用
三、獲取授權碼
四、開放資源
1、用戶信息 2、設備信息 3、數據接口 4、接口歷史數據 5、定時器
五、發送實時消息
六、測試設置參考
為了方便用戶自行開發APP或網站對接貝殼物聯平臺,特開放部分用戶權限,包括設備、數據接口、報警、實時通訊等接口。
貝殼物聯平臺 充分信任 各位開發者的基礎上授權采用OAuth2.0的User Credentials授權模式,即用戶使用ID和密碼直接登錄第三方應用,無需顯式授權認證,這樣降低了開發流程上的難道。但為了 充分保護 用戶安全,此處密碼非用戶登錄貝殼物聯的密碼,是用戶在后臺獲取的用戶APIKEY。
在貝殼物聯用戶中心→個人信息→開發者出點擊成為開發者,填寫應用信息保存即可獲取第三方應用ID(client_id)和密碼(client_secret),此信息在獲取授權時需用到。
地址:http://www.smgyp.com/oauth/token
請求方式:POST(application/x-www-form-urlencoded)
參數:
{ client_id:"應用ID", client_secret:"應用密碼", username:"用戶ID", password:"用戶apikey", grant_type:"password" }
示例:
$ curl "http://www.smgyp.com/oauth/token" -d "grant_type=password&client_id=xxxx&client_secret=xxxx&username=x&passwor=xxxx"
請求信息正確返回值:
{"access_token":"219e53e4fea824e7cc86","expires_in":172800,"token_type":"Bearer","scope":null,"refresh_token":"8107bce9803527c448"}
access_token——獲取網站資源憑證
expires_in——憑證有效時間,單位秒
token_type——憑證類型
scope——備用字段
fresh_token——刷新當前token憑證,可用于延期當前憑證(暫不可用)
請求信息錯誤返回值:
{"error":"invalid_grant","error_description":"Invalid username and password combination"}
不同錯誤描述部分有所不同。
注意:token有效期為2天,請在本地妥善儲存使用,在到期或即將到期時再次獲取。不可每次調用接口時就獲取一次,或者頻繁定期獲取。定期獲取可以一天一次。同一用戶同一應用獲取token頻率長期超過12小時/次的,將會被停用。
每次請求開放資源時,都需攜帶在有效期內的access_token。
地址:http://www.smgyp.com/oauth/userinfo
請求方式:GET
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息" }
示例:
$ curl http://www.smgyp.com/oauth/userinfo?access_token=xxxxxxxxxxxxx
請求信息正確返回值:
{"uid":"2","nickname":"xxxx","level":"8","score":"534","online":0,"image":"57de7787e3de9_769"}
uid——用戶ID
nickname——用戶名
level——用戶等級
score——用戶積分
online——在線狀態,0:不在線,1:在線
image——頭像代碼,可用于獲取頭像
請求信息錯誤返回值:
{"error":"invalid_grant","error_description":"xxxxxxxxxxxxxx xxxxxxx"}
不同錯誤描述部分有所不同。
頭像獲取地址:http://www.smgyp.com/userimg/bigiot_xxxx_big.jpg
xxxx替換為image字段的值,bigiot_xxxx_big中的big也可以替換為centre、small,代表圖片的三種不同尺寸。
地址:http://www.smgyp.com/oauth/dev
請求方式:GET
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息", id:要查詢信息的設備ID,為0時獲取用戶名下所有設備信息 }
示例:
$ curl http://www.smgyp.com/oauth/dev?access_token=xxxxxxxxxxxxx&id=0
請求所有設備信息正確返回值:
[{"id":"2","title":"first dev","description":"my first dev","open":"1","open_listen":"1","online":"0","encrypt":"0","image":"57dcec62826c1_890","lat":"0.0000000","lng":"0.0002000","online_time":"189573"},...]
請求單個設備信息正確返回值:
{"id":"2","title":"first dev","description":"my first dev","open":"1","open_listen":"1","online":"0","encrypt":"0","image":"57dcec62826c1_890","lat":"0.0000000","lng":"0.0002000","online_time":"189573"}
id——設備ID
title——設備名稱
description——設備簡介
open——是否公開,0:否,1:是
open_listen——是否公開監聽,0:否,1:是
online——是否在線,0:否,1:是
encrypt——是否開啟加密登錄,0:否,1:是
image——頭像代碼,可用于獲取頭像
lat——設備所在經度
lng——設備所在維度
onlinetime——在線時長,單位:秒
請求信息錯誤返回值:
{"error":"invalid_grant","error_description":"xxxxxxxxxxxxxx xxxxxxx"}
不同錯誤描述部分有所不同。
頭像獲取地址:http://www.smgyp.com/devimg/bigiot_xxxx_big.jpg
xxxx替換為image字段的值,bigiot_xxxx_big中的big也可以替換為centre、small,代表圖片的三種不同尺寸。
地址:http://www.smgyp.com/oauth/myinputs
請求方式:GET
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息" }
示例:
$ curl http://www.smgyp.com/oauth/myinputs?access_token=xxxxxxxxxxxxx
請求信息正確返回值:
[{"id":"1","did":"1","title":"\u5f00\u5173","type":"0","unit":"Lux","description":"\u7535\u706f\u5f00\u5173\u72b6\u6001","save":"1","save_interval":"10"},...]
id——數據接口ID
did——所屬設備ID
title——接口名稱
type——接口類型,0:數字量,1:模擬量,2,定位接口,3:圖片接口
unit——接口數據單位
description——設備簡介
save——是否保存歷史數據,0:否,1:是
save_interval——保存歷史數據間隔,單位:分鐘
請求信息錯誤返回值:
{"error":"invalid_grant","error_description":"xxxxxxxxxxxxxx xxxxxxx"}
不同錯誤描述部分有所不同。
①獲取接口歷史數據
地址:http://www.smgyp.com/oauth/historydata
請求方式:GET
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息", id:"要查詢的數據接口ID" }
示例:
$ curl http://www.smgyp.com/oauth/historydata?access_token=xxxxxxxxxxxxx&id=xx
請求信息正確返回值:(接口類型不同返回數據有所不同)
[{"value":"1","time":"1"},...]
value——數值
time——數據上傳時間
請求信息錯誤返回值:
{"error":"invalid_grant","error_description":"xxxxxxxxxxxxxx xxxxxxx"}
不同錯誤描述部分有所不同。
②清空接口歷史數據
地址:http://www.smgyp.com/oauth/delete_history_data
請求方式:POST
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息", id:"要清空數據的接口ID" }
示例:
$ curl "http://www.smgyp.com/oauth/delete_history_data" -d "access_token=xxxxxxxxxxxxx&id=xx"
請求信息正確返回值:
{"status":1}
請求信息錯誤返回值:
{"status":0,"error":"刪除失敗"}
不同錯誤描述部分有所不同。
地址:http://www.smgyp.com/oauth/timer
①獲取定時器信息
請求方式:GET
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息", id:"要查詢的定時器ID,取值為0時,獲取名下所有定時器信息" }
示例:
$ curl http://www.smgyp.com/oauth/timer?access_token=xxxxxxxxxxxxx&id=xx
②修改定時器
請求方式:POST(application/x-www-form-urlencoded)
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息", id:"要修改的定時器ID", title:"定時器名稱", enable:0/1, //0關閉,1開啟 repeats:0/1,//0不重復提醒,1重復提醒 content:"命令內容", toid:"命令發送目標,形如:D12", week:"星期設置,形如:0,1,2,3,4,5,6", hour:"小時設置,形如:0,1,2,...,21,22,23", min:"分鐘設置,形如:0,5,10,15,...,45,50,55" }
說明:access_token、id字段必填,其他字段根據修改需要填寫。
示例:
$ curl "http://www.smgyp.com/oauth/timer" -d "access_token=xxxxxxxxxxxxx&id=xx&enable=0"
地址:http://www.smgyp.com/oauth/say
請求方式:POST(application/x-www-form-urlencoded)
參數:
{ access_token:"授權憑證,憑證內部已包含用戶ID信息", id:"發送目標通訊ID,可為設備或用戶,形如:U2、D12,設備ID前加D,用戶ID前加U", c:"消息內容,如:play", sign:"可選,用于信息標識" }
示例:
$ curl "http://www.smgyp.com/oauth/say" -d "access_token=xxxxxxxxxxxxx&id=D10&c=play&sign=room"
以Postman獲取access_token設置為例,設置如下。
1、在Headers里設置Content-Type為application/x-www-form-urlencoded
2、在Body內設置請求參數,其中password保存原樣,其他四個參數根據自己實際情況修改。設置完成點擊send,返回結果如圖中所示。