From bdb46b9836c1893c07e84d1453652eaf9ab2a196 Mon Sep 17 00:00:00 2001 From: Xiahai Date: Tue, 23 Jan 2024 16:14:58 +0800 Subject: [PATCH] =?UTF-8?q?fix:=201.=E4=BF=AE=E6=94=B9=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E7=89=A9=E6=A8=A1=E5=9E=8B=E9=A1=B5=E6=9C=AC=E5=9C=B0=E5=88=B7?= =?UTF-8?q?=E6=96=B0=E7=A9=BA=E7=99=BD=E9=97=AE=E9=A2=98=202.=E5=8E=BB?= =?UTF-8?q?=E6=8E=89OTA=E9=83=A8=E5=88=86MQTT=E4=BF=A1=E6=81=AF=203.?= =?UTF-8?q?=E4=BF=AE=E6=94=B9OTA=EF=BC=88Openapi=EF=BC=89=E5=9C=B0?= =?UTF-8?q?=E5=9D=80=E5=A2=9E=E5=8A=A0nginx=E5=89=8D=E7=BC=80base-api=204.?= =?UTF-8?q?=E4=BF=AE=E6=94=B9=E5=8C=97=E5=90=91=E6=8E=A5=E5=8F=A3=E9=83=A8?= =?UTF-8?q?=E5=88=86=E5=8F=82=E6=95=B0=E3=80=81=E5=9C=B0=E5=9D=80=E9=94=99?= =?UTF-8?q?=E8=AF=AF=E4=BB=A5=E5=8F=8A=E9=87=8D=E5=86=99=E4=BC=A0=E5=85=A5?= =?UTF-8?q?=E5=8F=82=E6=95=B0=E7=BB=9F=E4=B8=80=E4=BD=BF=E7=94=A8Key?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- develop/northbound/http.md | 91 ++++++++++++++++++++------------ develop/protocol/http.md | 27 +++++----- develop/protocol/mqtt.md | 6 +-- guide/device_access/setup_tsl.md | 22 ++++---- 4 files changed, 84 insertions(+), 62 deletions(-) diff --git a/develop/northbound/http.md b/develop/northbound/http.md index ce17075..3c9ebf8 100644 --- a/develop/northbound/http.md +++ b/develop/northbound/http.md @@ -7,7 +7,7 @@ 1. 登录`sagoo` 系统，进入`系统配置`-> `基础配置` 查找下面两个的值，分别对应`SK`和`AK` - `开放接口AK`: `Ak` - `开放接口SK`: `SK` -2. 参照[AK/SK认证过程](https://iotdoc.sagoo.cn/develop/base-api/openapi/start.html) 针对请求进行鉴权 +2. 参照[AK/SK认证过程](https://iotdoc.sagoo.cn/develop/openapi/start.html) 针对请求进行鉴权 ## api接口列表 @@ -17,15 +17,16 @@ 2. productId: 产品id 3. deviceId: 设备id -| api名称 | url | method| api描述 | -|--------|--------------------------------------------------------------|--------------|----------| -| 获取产品详情 | https://{domain}/base-api/openapi/v1/north/product/detail?id={productId} | GET| 获取产品详情 | -| 获取设备详情 | https://{domain}/base-api/openapi/v1/north/device/detail?id={deviceId} | GET| 获取设备详情 | -| 获取设备列表 | https://{domain}/base-api/openapi/v1/north/device/list?id={productId} | GET| 获取设备列表 | -| 获取设备属性 | https://{domain}/base-api/openapi/v1/north/device/property/list | GET| 获取设备属性 | -| 设置设备属性 | https://{domain}/base-api/openapi/v1/north/property/set | POST| 设置设备属性 | -| 获取事件列表 | https://{domain}/base-api/openapi/v1/north/tsl/event/all?key={keyword} | GET| 获取产品事件列表 | -| 调用设备服务 | https://{domain}/base-api/openapi/v1/north/function/do | POST| 调用设备服务 | +| api名称 | url | method | api描述 | +|--------|--------------------------------------------------------------------------------|--------|----------| +| 获取产品详情 | https://{domain}/base-api/openapi/v1/north/product/detail?id={productId} | GET | 获取产品详情 | +| 获取设备详情 | https://{domain}/base-api/openapi/v1/north/device/detail?deviceKey={deviceKey} | GET | 获取设备详情 | +| 获取设备列表 | https://{domain}/base-api/openapi/v1/north/device/list?id={productId} | GET | 获取设备列表 | +| 获取设备属性 | https://{domain}/base-api/openapi/v1/north/device/property/list | GET | 获取设备属性 | +| 设置设备属性 | https://{domain}/base-api/openapi/v1/north/property/set | POST | 设置设备属性 | +| 获取事件列表 | https://{domain}/base-api/openapi/v1/north/tsl/event/all?productKey={productKey} | GET | 获取产品事件列表 | +| 调用设备服务 | https://{domain}/base-api/openapi/v1/north/function/do | POST | 调用设备服务 | +| 设备获取升级包信息 | https://{domain}/base-api/openapi/v1/north/get_ota_info | GET | 设备获取升级包信息 | ## 接口定义 @@ -299,12 +300,12 @@ ### 获取设备详情 1. 请求方式：`GET` -2. 请求url：`https://{domain}/base-api/openapi/v1/north/device/detail?id={deviceId}` +2. 请求url：`https://{domain}/base-api/openapi/v1/north/device/detail?deviceKey={deviceKey}` 3. 请求参数： - | 参数名称 | 是否必传 | 类型 | 描述 | - | :--- | :--- | :--- |:-----| - | id| 是 | int | 设备id | + | 参数名称 | 是否必传 | 类型 | 描述 | + | :--- | :--- |:-------|:------| + | deviceKey| 是 | string | 设备key | 4. 返回参数： 详细参数定义参见 [DeviceOutput](https://github.com/sagoo-cloud/sagooiot/blob/main/internal/model/dev_device.go) @@ -785,18 +786,17 @@ 2. 请求url：`https://{domain}/base-api/openapi/v1/device/property/list` 3. 请求参数： - | 参数名称 | 是否必传 | 类型 | 描述 | - | :--- | :--- | :--- | :--- | - | id| 是 | int | 设备id | - |propertyKey| 否 | string | 属性key | - |keyWord| 否 | string | 模糊搜索关键字 | - |DateRange| 否 | []string | 时间范围 | - |OrderBy| 否 | string | 排序字段 | - |pageNum| 否 | int | 分页号码，默认1 | - |PageSize| 否 | int | 分页大小，默认10,分页数量，最大50 | + | 参数名称 | 是否必传 | 类型 | 描述 | + |:------------|:-----|:---------|:--------------------| + | deviceKey | 是 | string | 设备标识key | + | propertyKey | 是 | string | 属性key | + | keyWord | 否 | string | 模糊搜索关键字 | + | DateRange | 否 | []string | 时间范围 | + | OrderBy | 否 | string | 排序字段 | + | pageNum | 否 | int | 分页号码，默认1 | + | PageSize | 否 | int | 分页大小，默认10,分页数量，最大50 | 4. 返回参数： -详细参数定义参见 [DeviceGetPropertyListOutput](https://github.com/sagoo-cloud/sagooiot/blob/main/internal/model/dev_device.go) ```json { "code": 0, @@ -818,7 +818,6 @@ 1. 请求方式：`POST` 2. 请求url：`https://{domain}/base-api/openapi/v1/north/product/property/set ` 3. 请求参数： -详细参数定义参见[DevicePropertyInput](https://github.com/sagoo-cloud/sagooiot/blob/main/internal/model/dev_device_property.go) ```json { "deviceKey": "string", @@ -829,7 +828,6 @@ } ``` 4. 返回参数： -详细参数定义参见[DevicePropertyOutput](https://github.com/sagoo-cloud/sagooiot/blob/main/internal/model/dev_device_property.go) ```json { "code": 0, @@ -845,15 +843,14 @@ ### 获取设备事件列表 1. 请求方式：`GET` -2. 请求url：`https://{domain}/base-api/openapi/v1/north/tsl/event/all?key={keyword}` +2. 请求url：`https://{domain}/base-api/openapi/v1/north/tsl/event/all?productKey={productKey}` 3. 请求参数： 4. - | 参数名称 | 是否必传 | 类型 | 描述 | - | :--- | :--- |:---------|:--------------------| - | key| 是 | string | 事件关键字 | + | 参数名称 | 是否必传 | 类型 | 描述 | + |:-----------| :--- |:---------|:-----| + | productKey | 是 | string | 产品标识 | 5. 返回参数： -详细参数定义参见 [AllTSLPropertyRes](https://github.com/sagoo-cloud/sagooiot/blob/main/api/v1/north/product/tsl.go) ```json { "code": 0, @@ -927,7 +924,6 @@ 1. 请求方式：`POST` 2. 请求url：`https://{domain}/base-api/openapi/v1/north/function/do` 3. 请求参数： -详细参数定义参见[DeviceFunctionReq](https://github.com/sagoo-cloud/sagooiot/tree/main/api/v1/north/product/device_function.go) ```json { "deviceKey": "string", @@ -939,7 +935,6 @@ } ``` 4. 返回参数： - 详细参数定义参见[DeviceFunctionRes](https://github.com/sagoo-cloud/sagooiot/tree/main/api/v1/north/product/device_function.go) ```json { "code": 0, @@ -952,3 +947,33 @@ } } ``` + +### 设备获取升级包信息 +1. 请求方式：`GET` +2. 请求url：`https://{domain}/base-api/openapi/v1/north/get_ota_info` +3. 请求参数： +```json +{ + "deviceKey": "string" +} +``` +4. 返回参数： +```json +{ + "code": 0, + "message": "", + "data": [ + { + "url": "https://{domain}/base-api/upload_file/2024-01-20/cyjlvk9eusn4p7invt.png", + "version": "1.0.1", + "module": "20", + "sign": "", + "signMethod": "MD5", + "size": 0, + "extData": { + "strategy": 28 + } + } + ] +} +``` \ No newline at end of file diff --git a/develop/protocol/http.md b/develop/protocol/http.md index a914d5b..bf97770 100644 --- a/develop/protocol/http.md +++ b/develop/protocol/http.md @@ -7,15 +7,15 @@ 1. 登录`sagoo` 系统，进入`系统配置`-> `基础配置` 查找下面两个的值，分别对应`SK`和`AK` - `开放接口AK`: `Ak` - `开放接口SK`: `SK` -2. 参照[AK/SK认证过程](https://iotdoc.sagoo.cn/develop/openapi/start.html#ak-sk%E8%AE%A4%E8%AF%81%E8%BF%87%E7%A8%8B) 针对请求进行鉴权 +2. 参照[AK/SK认证过程](https://iotdoc.sagoo.cn/develop/openapi/start.html) 针对请求进行鉴权 ## 协议接口列表 1. OTA相关 1. 设备获取升级包信息(设备端发起) - 1. 请求url:`https://{domain}/openapi/v1/ota/get_ota_info` + 1. 请求url:`https://{domain}/base-api/openapi/v1/ota/get_ota_info` 2. 上报升级进度信息(设备端发起) - 1. 请求url:`https://{domain}/openapi/v1/ota/write_ota_info` + 1. 请求url:`https://{domain}/base-api/openapi/v1/ota/write_ota_info` ## OTA相关 @@ -23,7 +23,7 @@ #### 请求 -1. 请求url: `https://{domain}/openapi/v1/ota/get_ota_info` +1. 请求url: `https://{domain}/base-api/openapi/v1/ota/get_ota_info` 2. 请求method: GET 3. application_type: application/json 4. 请求参数 @@ -69,18 +69,18 @@ #### 请求 -1. 请求Topic: `https://{domain}/openapi/v1/ota/write_ota_info` +1. 请求Topic: `https://{domain}/base-api/openapi/v1/ota/write_ota_info` 2. 请求method: POST 3. application_type: application/json 4. 请求参数 ```json - { - "deviceKey": "deviceKey", - "step": "-1", - "desc": "OTA升级失败，请求不到升级包信息。", - "module": "MCU", - "strategy": "1" - } + { + "params": { + "deviceKey": "deviceKey", + "step": "-1", + "strategy": "1" + } + } ``` 字段说明 1. deviceKey: 设备key，设备唯一标识 @@ -90,7 +90,6 @@ 3. -2：下载失败。 4. -3：校验失败。 5. -4：烧写失败。 - 3. module: OTA模块名称，类型为字符串 4. strategy: OTA批次ID 5. 响应 ```json @@ -99,9 +98,7 @@ "message": "" } ``` - 字段说明 - 1. code: 应答码，200表示成功，其他表示失败。 2. message: 结果信息 diff --git a/develop/protocol/mqtt.md b/develop/protocol/mqtt.md index 00997b1..ef6ec8a 100644 --- a/develop/protocol/mqtt.md +++ b/develop/protocol/mqtt.md @@ -37,12 +37,12 @@ 1. 请求:`/ota/device/upgrade/${productKey}/${deviceKey}` 3. 上报升级进度信息(设备端发起) 1. 请求:`/ota/device/progress/${productKey}/${deviceKey}` - 4. 设备请求OTA升级包信息(设备端发起) + ## 物物模型相关 ### 设备上报属性 @@ -400,7 +400,7 @@ 1. 请求Topic: `/ota/device/progress/${productKey}/${deviceKey}` 2. 请求数据格式: -``` +```json { "id": "123", "params": { diff --git a/guide/device_access/setup_tsl.md b/guide/device_access/setup_tsl.md index 79e5182..1dc7341 100644 --- a/guide/device_access/setup_tsl.md +++ b/guide/device_access/setup_tsl.md @@ -18,14 +18,14 @@ ## 支持的数据类型 -| 参数 | 说明 | 示例 | -|---------| ------------------------------------------------------------ |-------------------------| -| int | 32位整形 | 100 | -| float | 单精度浮点型 | 10.4 | -| double | 双精度浮点型 | 10.45 | -| text | 字符串，对应的数据长度不能超过10240字节。 | 你好，SagooIOT | -| date | 时间戳。默认格式为String类型的UTC时间戳，单位：毫秒。 | 1626738482010 | -| boolean | 布尔型。采用0（false）或1（true）来定义布尔值 | 1表示是、0表示否 | -| enum | 枚举型。定义枚举项的参数值和参数描述。 | [{key:1,value:1}] | -| array | 数组。需声明数组内的元素类型、数组元素个数。需确保同一个数组元素类型相同。元素个数限制为1~512个。 | [1, 2, 3, 4, 5, 6] | -| Object | 结构体数据，支持树形结构化数据。树形数据格式为JSON。 | {"name":"开关","value":1} | +| 参数 | 说明 | 示例 | +|---------| ------------------------------------------------------------ |---------------------------| +| int | 32位整形 | 100 | +| float | 单精度浮点型 | 10.4 | +| double | 双精度浮点型 | 10.45 | +| text | 字符串，对应的数据长度不能超过10240字节。 | 你好，SagooIOT | +| date | 时间戳。默认格式为String类型的UTC时间戳，单位：毫秒。 | 1626738482010 | +| boolean | 布尔型。采用0（false）或1（true）来定义布尔值 | 1表示是、0表示否 | +| enum | 枚举型。定义枚举项的参数值和参数描述。 | [{key:1,value:1}] | +| array | 数组。需声明数组内的元素类型、数组元素个数。需确保同一个数组元素类型相同。元素个数限制为1~512个。 | [1, 2, 3, 4, 5, 6] | +| Object | 结构体数据，支持树形结构化数据。树形数据格式为JSON。 | [{"name":"开关","value":1}] | -- Gitee