電信物聯(lián)網(wǎng)開放平臺北向api java sdk說明

SDK使用介 SDK的使 accessToken與appId的概 14 應(yīng)用訂閱 更 SDK的其他說 SDK依賴的開源組 DeviceInfo類說 DeviceService類說 Pagination類說 mandDTO類說 SDK中類方法的說 類方 info類方 NorthApiException類方 SSLConfig NB-IoT方案集成簡 softradio簡 本文描述了針電信物聯(lián)網(wǎng)開放平臺（下文簡稱平臺）北向接口的KitSDKSDKSDKJavaSDKSDK包的本文檔電信物聯(lián)網(wǎng)開放平臺（后文以平臺或IoT平臺指代中國電信物聯(lián)網(wǎng)開放平臺）JavaSDK的說明文檔。SDKSDK接口，可以實現(xiàn)平臺服務(wù)SDKrestfulAPI封裝起來，因此在調(diào)用平臺服務(wù)時，需要通過SSL的雙向認證。集成開發(fā)者通過全景圖了解到：SDK提供了哪些功能？每個功能包含哪些接口？接口注銷V4更SDKSDKSDKAPI為伙伴提供應(yīng)用安全接入、設(shè)備管理、、信令傳送、設(shè)備服務(wù)調(diào)用、批量處理、規(guī)則等業(yè)務(wù)功能。功能的實現(xiàn)依賴于SDK中NorthApi //1新建對象//2初始化

=newNorthApi Info=new StringappId="ax2M****X Stringsecret= Authenticationauth=new //5SDKAuthOutDTOauthOutDTO=accessTokenappIdappIdsecret調(diào)用鑒權(quán)接口，獲取鑒權(quán)accessTokenaccessToken，平臺對accessTokentokenSDKAPI接口都需要重新輸入appId是應(yīng)用的唯一標(biāo)志，應(yīng)用與應(yīng)用之間可以存在與被關(guān)系，如若應(yīng)用A被應(yīng)用B，應(yīng)用A就可以通過在入?yún)⒅袛y帶應(yīng)用B的appId，對應(yīng)用B下的設(shè)備進不是所有接口都在入?yún)⒅袛y帶有appId，只有攜帶有appId的接口才可以進行的調(diào)appId。pdcid,StringappId,StringaccessToken)throws如果不存在應(yīng)用關(guān)系，入?yún)⒅械腶ppId可以不賦值或賦值為自身的appIdSDKAPI為伙伴提供應(yīng)用安全接入、設(shè)備管理、、信令傳送、設(shè)備服務(wù)調(diào)appIdsecrettokenpublicAuthOutDTOgetAuthToken()throws

appId和secret使用 Info中的值tokenaccessToken的Oauth2.0Oauth2.0鑒權(quán)參數(shù)，用來刷新accessToken。（1個月的有效登錄用戶口令，填寫應(yīng)用程序tokenaccessToken的有效。 verifyCode，。appId,StringaccessToken)throwsverifyCode。如果不指定，系統(tǒng)verifyCode一般需要指定，如智慧家庭解IMEI。設(shè)備唯一標(biāo)識,如：MAC或SIM或設(shè)esn號等。與設(shè)備對接時，必須與設(shè)備nodeId一致。備注：nodeId和verifyCode需要填寫為設(shè)urn:imei:xxxx，xxxxIMEI號；海思芯IMEI號，其他種類終端用戶Id，如號碼，地psk碼，用于生成設(shè)備鑒權(quán)參數(shù)；如不傳單位秒，不填使用默認值(180s),0則0表示在指定時間內(nèi)設(shè)備進設(shè)備唯一標(biāo)識，1-64申請的臨時，設(shè)備可以通過獲取idpskdeviceIdStringaccessToken)throws設(shè)備唯一標(biāo)識，1-64是否通過獲取的狀態(tài)標(biāo)publicpublicvoiddeleteDirectDevice(StringdeviceId,StringappId,StringthrowsNB-IoTProfile文件關(guān)聯(lián)。詳見附錄NB-IoT方案集成簡介。publicpublicvoidmodifyDeviceInfo(ModifyDeviceInfoInDTOmdiid,StringappId,應(yīng)用唯一標(biāo)志。供被的應(yīng)用使用endUser可endUsernull。設(shè)備類型:z-wave:ProductType+16XXXX-XXXX0對齊設(shè)備配置信息，自定義結(jié)構(gòu)體（見下表d數(shù)據(jù)配置信息，自定義結(jié)構(gòu)體（見下表]支持刷新到本應(yīng)用的設(shè)備和授予權(quán)限（詳見章節(jié)接口入?yún)⒅械腶ppId）的其它應(yīng)用密鑰刷新后，deviceId不變，nodeIdStringappId,StringaccessToken)throwsverifyCodeNB場景下，verifyCodenodeId保設(shè)備唯一標(biāo)識,如：MAC或SIM或設(shè)esn號等。與設(shè)備對接時，必須與設(shè)備nodeId一致。備注：nodeId和verifyCode需要填寫相同的值。高通設(shè)備的唯一標(biāo)識為urn:imei:xxxx，xxxxIMEI號；海思芯IMEI號，其他種類單位秒，不填使用默認值(180s),0則0表示在指定時間內(nèi)設(shè)備進申請的臨時，設(shè)備可以通過獲取id4.3平臺支持對設(shè)備的訂閱，同時還支持查看設(shè)備上報的歷史數(shù)據(jù)，能按時、天、月等維度查看傳感器上報的歷史數(shù)據(jù)。實現(xiàn)了對設(shè)備數(shù)據(jù)收集直連設(shè)備publicpublicQueryDevicesOutDTOqueryDevices(QueryDevicesInDTOqdid,StringappId,accessToken)throws設(shè)備唯一標(biāo)識（識）。當(dāng)設(shè)備是直連設(shè)備時，gatewayId為deviceId。當(dāng)設(shè)備是非直連設(shè)備時，gatewayId為設(shè)備所關(guān)聯(lián)的直連設(shè)備（即網(wǎng)關(guān)）的deviceIdgatewayId和pageNonull，二指定節(jié)點的類：ENDPOINT:傳感器.GATEWAY:網(wǎng)關(guān).協(xié)議類型（v1.3.0url攜帶pageNo=null時查詢內(nèi)容0詢,0gatewayId和pageNonull，二設(shè)備唯一標(biāo)識（識）。當(dāng)設(shè)備是直連設(shè)備時，gatewayId為deviceId。當(dāng)設(shè)備是非直連設(shè)備時，gatewayId為設(shè)備所關(guān)聯(lián)的直連設(shè)備（即網(wǎng)關(guān)）的deviceIdgatewayId和pageNonull，二1的整數(shù)，設(shè)備狀態(tài),取值:ONLINE;OFFLINE;ABNORMAL查詢設(shè)備信息時間在startTime之后的HHmmss’Z’如： 查詢設(shè)備信息時間在endTime之前的HHmmss’Z’如： 設(shè)備的時間升序排列；DESC按設(shè)備注：gatewayIdpageNo返回的頁碼序號(0的整數(shù),0頁碼大小,當(dāng)不分頁查詢時,設(shè)備唯一標(biāo)識，1-64設(shè)備唯一標(biāo)識。當(dāng)設(shè)備是直連設(shè)備時，gatewayId為deviceId。當(dāng)設(shè)備是非直連設(shè)備時，gatewayId為設(shè)備所關(guān)聯(lián)的直連設(shè)備（即網(wǎng)關(guān)）的ENDPOINT:傳感器.GATEWAY:網(wǎng)關(guān).設(shè)備時間；時間格式HHmmss’Z’如 HHmmss’Z’如 publicpublicQueryDeviceDataOutDTOqueryDeviceData(StringdeviceId,StringappId,accessToken)throws 設(shè)備唯一標(biāo)識，1-64設(shè)備唯一標(biāo)識。當(dāng)設(shè)備是直連設(shè)備時，gatewayId為deviceId。當(dāng)設(shè)備是非直連設(shè)備時，gatewayId為設(shè)備所關(guān)聯(lián)的直連設(shè)備（即網(wǎng)關(guān)）的ENDPOINT:傳感器GATEWAY:網(wǎng)關(guān)設(shè)備時間；時間格式HHmmss’Z’如 HHmmss’Z’如 appId,StringaccessToken)throwsD是直連設(shè)備時，gatewayId為設(shè)備本身的gatewayId為設(shè)備所關(guān)聯(lián)的直連設(shè)備（即網(wǎng)關(guān)）deviceId。pageNo=null時查詢內(nèi)容00110萬條，這個數(shù)值Z’如 90天，這個數(shù)值有Z’如：T121212Z返回的頁碼序號(0的整數(shù),0頁碼大小,當(dāng)不分頁查詢時,O>設(shè)備唯一標(biāo)識，1-64網(wǎng)關(guān)的設(shè)備唯一標(biāo)識，1-64個字節(jié)。當(dāng)設(shè)備是直連設(shè)備時，gatewayIddeviceId。當(dāng)設(shè)備是非直連設(shè)備時，gatewayId為設(shè)備所關(guān)聯(lián)的直連設(shè)備（即網(wǎng)關(guān)）的Profile文propertyties。時間格式：yyyyMMdd’T’HHmmss’ZProfilepublicQueryDeviceCapabilitiesOutDTOqueryDeviceCapabilities(QueryDeviceCapabilitiesInDTOpublicQueryDeviceCapabilitiesOutDTOqueryDeviceCapabilities(QueryDeviceCapabilitiesInDTOqdcid,StringappId,StringaccessToken)throwsD設(shè)備唯一標(biāo)識，1-64id。當(dāng)設(shè)備是直連設(shè)備時，gatewayIddeviceId保持一致。當(dāng)設(shè)備是非直連設(shè)備時，gatewayId為設(shè)備所關(guān)聯(lián)的直連設(shè)備（即網(wǎng)關(guān)）deviceId。設(shè)備唯一標(biāo)識，1-64DTO>> mand結(jié)構(gòu)體，見下ServiceProperty單位（符號>響方法：RWERW單位（符號>publicpublicvoidsubscribeNotify(SubscribeInDTOsid,String 5、deviceEvent（設(shè)備9、ruleEvent（規(guī)則）址的端口。(說明：HTTP信道只可用于調(diào)NB-IoT創(chuàng)建設(shè)備命令pdcid,StringappId,StringaccessToken)throwsm)(說明：HTTP于調(diào)測，不可用于環(huán)境POSTHTTPBodyjson)48小時

HTTPS(說明：HTTP信道只可用于調(diào)測，不能用于環(huán)境當(dāng)命令狀態(tài)變化時(已送達)NAPOSTHTTPBodyjson48小時設(shè)備命令的狀態(tài)，DEFAULT表示未下發(fā)，EXPIRED表示命令已經(jīng)過期，SUCCESSFUL表示命令已經(jīng)成功執(zhí)行，F(xiàn)AILED表示命令執(zhí)行失敗，TIMEOUT表示命令下發(fā)執(zhí)行超時，CANCELED表示命令已經(jīng)被撤銷執(zhí)行設(shè)備命令執(zhí)行的詳細結(jié)果，格式為json查詢設(shè)備命令mandInDTOStringappId,StringaccessToken)throwsstartTime之后的記錄。時間格式：yyyyMMdd'T'HHmmss'Z'如：endTime之前的記錄。時間格式：yyyyMMdd'T'HHmmss'Z'如：

Pagination>O下發(fā)命令的信息， mandDTO類說(說明：HTTP信道只可用于調(diào)測，不能用于環(huán)境)；HTTPBodyjson48小時設(shè)備命令的狀態(tài)，DEFAULT表示未下發(fā)，EXPIRED表示命令已經(jīng)過期，SUCCESSFUL表示命令已經(jīng)成功執(zhí)行，F(xiàn)AILED表示命令執(zhí)行失敗，TIMEOUT表示命令下發(fā)執(zhí)行超時，CANCELED表示命令已經(jīng)被撤銷執(zhí)行設(shè)備命令執(zhí)行的詳細結(jié)果，格式為jsone修改設(shè)備命令publicpublicappId,StringaccessToken)throwsO下發(fā)命令的信息， mandDTO類說(說明：HTTP信道只可用于調(diào)測，不能用于環(huán)境)；HTTPBodyjson48小時設(shè)備命令的狀態(tài)，DEFAULT表示未下發(fā)，EXPIRED表示命令已經(jīng)過期，SUCCESSFUL表示命令已經(jīng)成功執(zhí)行，F(xiàn)AILED表示命令執(zhí)行失敗，TIMEOUT表示命令下發(fā)執(zhí)行超時，CANCELED表示命令已經(jīng)被撤銷執(zhí)行設(shè)備命令執(zhí)行的詳細結(jié)果，格式為jsonIDpublicDeviceCmdCancelTaskOutDTOcreateDeviceCmdCancelTaskV4(DeviceCmdCancelTaskInDTOpublicDeviceCmdCancelTaskOutDTOcreateDeviceCmdCancelTaskV4(DeviceCmdCancelTaskInDTOdcctod,StringappId,String撤銷任務(wù)的任務(wù)狀態(tài)，WAITTING表示等待執(zhí)行中，RUNNING表示撤銷任務(wù)正在執(zhí)行，SUCCESS表示撤銷任務(wù)執(zhí)行成功，F(xiàn)AILED表示撤銷任務(wù)執(zhí)行失敗，PART_SUCCESS表示推銷任務(wù)部分執(zhí)行成功。命令列表，UpdateDeviceCmdOutDTO詳見“修改設(shè)備publicQueryDeviceCmdCancelTaskOutDTOpublicQueryDeviceCmdCancelTaskOutDTOStringaccessToken)throws10001000IDIDstartTime之后的記錄。時間格式：yyyyMMdd'T'HHmmss'Z'如：格式：yyyyMMdd'T'HHmmss'Z'如：Pagination取消任務(wù)列表，DeviceCmdCancelTaskOutDTO請詳見V4章節(jié)”用來向設(shè)備下發(fā)消息（命令MQTT在附錄中有調(diào)用本接口進行非直連設(shè)備的添加publicpublicinvocateDeviceService(DeviceServiceInvocationInDTOdsiid,StringappId,StringaccessToken)throwsNorthApiException{}CommandNA2CloudHeader字段說requestId，就是用填寫的requestIdrequestIdAPP按照下面的規(guī)則保證其唯一性：GenerateseqNum：APP生seqNumPOSTBODYUUID_XXXX，UUIDJAVA自帶APP啟動后生成一個新的APP重新UUID值，XXXX的取值范圍重新0001NOACK，需要確認消息：ACKApp發(fā)起的請求：/users/{userId}NA)址的端口。(說明：HTTP信道只可用于調(diào)

命令狀態(tài)：sent已發(fā)送deliveriedtoType為CLOUDfailedtoTypeCLOUDHHmmss’Z’如 toTypeGATEWAYrequestId則同請求的requestIdrequestId則平臺分配一個序列號toTypeCLOUDnull;param參數(shù)結(jié)構(gòu)說，paramDeviceListDeviceTypeDeviceArea/GroupList/Broadcast>deviceIdDeviceType時需IDDeviceType時可DeviceType時可DeviceArea時，>GroupList時m下發(fā)命令的信息， publicpublicQueryOneTaskOutDTOqueryOneTask(Stringtasked,StringappId,accessToken)throws任務(wù)類型任務(wù)狀態(tài) tttttt，param批量命令類型：DeviceList/DeviceTypeDeviceAreaGroupList/appId,StringaccessToken)throws分頁查詢參數(shù)，pageNo=null時查詢內(nèi)容不0的整數(shù)時分頁查詢01的整數(shù),缺文件里第幾行,查詢批量設(shè)備使設(shè)備詳情信息列表批量設(shè)備或批量下發(fā)命令的輸出{"error_code"error_desc":規(guī)則的條件后，執(zhí)行相應(yīng)的動作，如以郵件或者的方式對用戶進行實時提醒。publicpublicRuleCreateOrUpdateOutDTOcreateRule(RuleDTOrcid,StringaccessToken)idykey值(1-規(guī)則名（1~128個字符List<Json條件列表，自定義結(jié)構(gòu)體（見下表）,andor，默認and條件場景的時間段。TimeRange為自定義結(jié)構(gòu)體（Condition-CycleTimer）List<Json規(guī)則的動作。Action為自定義結(jié)構(gòu)體。（見下-ListTriggerSource，只DEVICETIMER類型設(shè)備觸發(fā)源類型設(shè)備觸發(fā)源類型GroupExpressGroupElement內(nèi)層表達式運算的元素,element表示condition,conditionsCondition-DeviceDataconditioncondition的編號，在一條規(guī)則范圍內(nèi)唯一，比較表達式的右值(between操作符聯(lián)用時，“20,302030，應(yīng)用場景:2030之間觸發(fā)規(guī)則)0不Strategyreverse：上一次數(shù)據(jù)不滿Integer(>=-s，表示收到的傳感器數(shù)據(jù)多久有效，（eventTimeDeviceInfoServiceId/DataProperty，例如Condition-DeviceGroupDataconditioncondition的編號，在一條規(guī)則范圍內(nèi)唯一，比較表達式的右值(between操作符聯(lián)用時，“20,302030，應(yīng)用場景:2030之間觸發(fā)規(guī)則)0不DeviceGroupInfoServiceId/DataProperty，例如多個,OBD需要兩個屬性,經(jīng)度和緯度”,多個屬性中間以逗號分隔conditioncondition的編號，在一條規(guī)則范圍內(nèi)唯一，比較表達式的右值(between“20,302030，應(yīng)用場景:2030之間觸發(fā)規(guī)則0不ServiceId/DataProperty，例如多個,OBD需要兩個屬性,經(jīng)度和緯度”,多個屬性中間以逗號分隔conditioncondition的編號，在一條規(guī)則范圍內(nèi)唯一，指定執(zhí)行時間點，格式為Condition-CycleTimerconditioncondition的編號，在一條規(guī)則范圍內(nèi)唯一，Action-DeviceCMDaction的編號，在一條規(guī)則范圍內(nèi)唯keyCMD當(dāng))Action-SMSaction類型，取值為“SMS”action的編號，在一條規(guī)則范圍內(nèi)唯一，不通知內(nèi)容通知內(nèi)容（content為空時，Action-結(jié)構(gòu)說發(fā)送郵件action類型，取值為“action的編號，在一條規(guī)則范圍內(nèi)唯一，不通知內(nèi)容通知內(nèi)容（content為空時，郵件由北向應(yīng)用發(fā)送Action-DeviceAlarmaction類型，取值為action的編號，在一條規(guī)則范圍內(nèi)唯一，不告警狀態(tài)告警級別更publicpublicRuleCreateOrUpdateOutDTOupdateRule(RuleDTOrd,StringaccessToken)ruleIdpublicpublicvoidchangeRuleStatus(RuleStatusChangeInDTOrscid,StringPublicvoiddeleteRule(StringruleId,StringaccessToken)throwsPublicPublicList<RuleDTO>queryRules(QueryRulesInDTOqrid,StringaccessToken)RuleDTOrsbcid,StringaccessToken)throwseIndTO>RulestatusChangeIndTO為自定義結(jié)構(gòu)體“PartialOK”successful.”，否則為“Operationpartialok.”4.8認SDKrestfulAPI封裝起來，因此在調(diào)用平臺服務(wù)時，需要通過SSL的雙向認證。NorthApi提供了兩個重載方法，分別是測試雙向認證在SDK的jar中打包了調(diào)測使用ca.jks和outgoing.CertwithKey.pkcs12兩個。僅限在調(diào)測業(yè)務(wù)功能時使用，正式用途或商業(yè)用途需要申請正式。PublicvoidinitSSLConfig()throws 無無如果已經(jīng)有調(diào)用API相應(yīng)的 ，可以通過本接口將導(dǎo)入NorthApi。CA證書必須是jks格式，客戶端 必須是pkcs12格式。PublicvoidinitSSLConfig(SSLConfigsslc)throws 客戶端路CA路CA無SDKSDKSDKSDKSDKNorthApiExceptionpublicpublicclassNorthApiExceptionextendsExceptionprivateStringerror_code=null;privateStringerror_desc=privateinthttpStatusCode=-1;privateStringhttpReasonPhase="";privateStringhttpMessage="";｝error_code與error_descAPIerror_codeerror_code6位，SDK自身4位。SDK自身的異常列表如下：internalThehttpmethodisProcessdataerrorbeforeinvokePrecessdataerrorafterinvokeInvokeAPIerrorbutnoerror_codeanderror_desc,pleaserefertoSslconfigerror,pleasechecktheTheinputparameterofthemethodisErrorinInfo,PleasecheckwhetherInfoisconfiguredon.TheinputaccessTokenofthemethodcannotbenullorAppIdorsecretincludesomespaces.pleaseremoveAPI1、圖中省略了、網(wǎng)等節(jié)點/21是指網(wǎng)關(guān)（敏捷物聯(lián)網(wǎng)關(guān)、智慧家庭網(wǎng)關(guān)等，大部分集成了/除、服務(wù)能力上報、服務(wù)數(shù)據(jù)上報、服務(wù)命令分發(fā)2包含通過

3IoT平臺的設(shè)備。比如，一個家庭中包含門磁、溫度傳感器、頭等傳感器，它們通過統(tǒng)一的網(wǎng)關(guān)接入IoT平臺。DeviceInfo設(shè)備型號.Z-Wave協(xié)議，型號就ProductTypeProductId（用零填充，如果需要）格式的十六進制數(shù),例如Z-Wave格式是majorversionnumber.minorversionnumber,例如,1.1.(Z-TRUETRUE的TRUEONLINE:OFFLINE:INBOX:停用TRUE:被.FALSE:沒被.DeviceServiceID指定一個屬性值對yyyymmddThhmissZ,例如,PaginationmandDTOSDKNorthApi類方類用于創(chuàng)建實例，實現(xiàn)平臺restfulAPI的調(diào)用。主要方法如下publicvoidsetInfo(Info初始化NorthApi中的參數(shù)，Info中的publicvoidpublicvoid本方法用于導(dǎo)入，可以用于與正式使info用于初始化NorthApi中的基本信息。主要方法（省略get方法）如下publicvoidpublicvoidpublicvoidsetAppId(StringappIdappIdIDpublicvoidsetSecret(Stringsecret是與平臺appId配套的NorthApiExceptionSDKNorthApiException（set方法）publicString獲取異常的錯誤碼，SDK自身處理異常會拋出四error_code。publicStringpublicStringhttp狀態(tài)碼(StatusCode)SDKhttprestfulAPISDK在調(diào)restfulAPIhttp狀態(tài)404、200publicStringStatusCode400時，ReasonPhrase為“NotFound”；StatusCode200時，ReasonPhrase為publicStringSSLConfigSDKNorthApiException（get方法）publicString設(shè)置客戶端的位置的絕對路publicString設(shè)置客戶端