物联网平台支持设备通过MQTT协议方式,将文件上传至用户自己的OSS空间或阿里云物联网平台空间进行储存。本文介绍设备上传文件流程相关的Topic和数据格式,包括设备请求上传文件、设备上传文件分片和设备取消上传文件。

背景信息

设备端完成文件上传能力开发的具体操作,请参见文件上传(MQTT)

若选择将文件上传至您自己的OSS空间,设备上传文件后,您可以在OSS中访问文件。

注意 OSS Bucket必须为设备所属用户所有,Bucket地域必须与设备所属地域相同。

若将文件上传至阿里云物联网平台空间,设备上传文件后,您可以在物联网平台控制台查看、下载、删除文件。具体操作,请参见文件管理

设备请求上传文件

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/init
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/init_reply

请求数据格式:

{
    "id":"123456",
    "params":{
        "fileName":"abc.bin",
        "fileSize":123455,
        "conflictStrategy":"overwrite",
        "ficMode":"crc64",
        "ficValue":"0205d7***",
        "initUid":"ab1***34",
        "extraParams":{
            "ossOwnerType":"device-user",
            "serviceId":"device1.bucket",
            "fileTag":{
                "tagKey1":"tagValu1",
                "tagKey2":"tagValue2"
            }
        }
    }
}
表 1. 请求参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
params Object 请求业务参数。
fileName String 设备上传文件的名称。限制如下:
  • 支持数字、英文字母、下划线(_)和英文句点(.)。
  • 首字符仅支持数字和英文字母。
  • 长度不超过100字节。
fileSize Long 上传文件大小,单位字节。单个文件大小不超过16 MB。

取值为-1时,表示文件大小未知。文件上传完成时,需在上传文件分片的消息中,指定参数isComplete,具体说明,请参见设备上传文件分片

conflictStrategy String 物联网平台对设备上传同名文件的处理策略。非必填参数,默认为overwrite

使用说明:

  • 若物联网平台不存在同名文件,直接创建文件的上传任务。
  • 若物联网平台已存在同名文件,则按照设置的策略,进行如下处理:
    • overwrite:覆盖模式。

      先删除同名文件,再创建文件的上传任务。

    • append:文件追加模式。
      • 若同名文件上传未完成,设备端可根据物联网平台返回的文件信息,继续上传文件。
      • 若同名文件上传已完成,创建文件上传任务会失败。设备端可修改文件名称或通过覆盖模式(overwrite)重新请求上传文件。
    • reject:拒绝模式。

      物联网平台拒绝同名文件上传的请求,并返回文件已存在的错误码。

    注意 从创建文件上传任务成功开始计时,如果24小时内设备端未完成上传,物联网平台云端会自动删除该文件上传任务。
ficMode String 文件的完整性校验模式,目前可取值crc64。非必传参数。
  • 若不传入,在文件上传完成后不校验文件完整性。
  • 若传入,与ficValue同时传入,根据校验模式和校验值校验文件完整性。
注意fileSize值为-1,不支持设置ficModeficValue
ficValue String 文件的完整性校验值,是16位的Hex格式编码的字符串。

非必传参数。若传入,与ficMode同时传入。

initUid String 自定义的设备请求上传文件的任务唯一ID,同一上传任务请求必须对应相同的唯一ID。限制如下:
  • 支持数字、英文字母、短划线(-)、下划线(_)和英文句点(.)。
  • 首字符仅支持数字和英文字母。
  • 长度不超过16个字符。

该参数可选:

  • 传入:用于设备请求上传文件的消息,在重发场景下的幂等性处理。您需确保同一上传文件任务的重试消息使用相同的initUid

    在同一设备下,该参数相同的两个上传请求消息,会被物联网平台云端识别为消息重试,返回相同的文件请求上传的响应消息。

    在同一设备下,若重试的时间间隔超过24小时,则重试的请求会识别为新的文件上传任务请求。此时若请求上传文件成功,则返回新的uploadId

  • 不传入:物联网平台的云端识别当前请求为新的文件上传请求。
extraParams Object 设备上传文件至OSS存储空间的配置参数。非必须参数。

若未指定该参数,表示设备将文件上传至物联网平台的存储空间中。

ossOwnerType String 设备上传文件的目标OSS所有者类型。可取值:
  • iot-platform:表示上传到阿里云物联网平台的OSS存储空间中。

    上传的文件会在物联网平台控制台的设备文件列表中展示,且可以通过相关的云端API管理。详细内容,请参见文件管理

  • device-user:表示上传到设备所属用户自己的OSS存储空间中。

    上传的文件不会在物联网平台控制台的设备文件列表中展示,也不能通过相关的云端API管理。

    文件上传位置为:{ossbucket}/aliyun-iot-device-file/${instanceId}/${productKey}/${serviceId}/${deviceName}/${fileName}

    • {ossbucket}:在物联网平台控制台已配置的目标Bucket。
    • {instanceId}:设备所属实例的ID。
    • {productKey}:设备所属产品的ProductKey。
    • {serviceId}:在物联网平台控制台已配置的业务ID。
    • {deviceName}:设备名称。
    • {fileName}:设备文件名称。
serviceId String 文件上传相关的业务ID。该ID需要在物联网平台控制台预先定义。具体操作,请参见配置设备文件上传至Bucket

ossOwnerTypedevice-user时,serviceId有效。

fileTag Object 文件保存到OSS存储空间携带的标签,最多包含5个。标签定义规则,请参见对象标签

标签Key不能以2个下划线(_)开头。

ossOwnerTypedevice-user时,fileTag有效。

响应数据格式:

{
    "id": "123456",
    "code": 200,
    "message": "this is error msg when code is not 200",
    "data":{
        "fileName": "abc.bin",
        "uploadId": "03d9151e-6***",
        "offset": 123123
    }
}
表 2. 响应参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code Integer 结果码。返回200表示成功,返回其他状态码,表示失败,具体请参见设备端接收的错误码
message String 请求失败时,返回的错误信息。
data Object 返回设备端的数据。
fileName String 设备上传文件的名称。
uploadId String 本次上传文件任务的标识ID。后续上传文件分片时,需要传递该文件标识ID。
offset Long 仅当请求参数conflictStrategyappend,且物联网平台云端存在未完成上传的文件时,返回的已上传文件的大小,单位为字节。

设备上传文件分片

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/send
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/send_reply

请求数据格式:

  • 结构如下图:结构
    结构项 说明
    Header Length 表示请求Header中JSON字符串对应的字节数组长度,必须占位2个字节,高位字节在前,低位字节在后。

    例如,Header的JSON字符串使用UTF-8编码转码成字节数组的长度为十进制的87,对应十六进制57,则高位字节为0x00,低位字节为0x57。

    Header String Bytes 表示请求Header中JSON字符串对应的字节数组,编码格式为UTF-8。具体内容,请参见下文的“Header的JSON数据格式”。
    File Block Bytes 表示当前文件分片的字节数组,字节顺序按照相对于文件头的偏移量从小至大排列。
    CRC16/IBM 表示文件分片的校验值,仅支持CRC16/IBM,占位2个字节,低位字节在前,高位字节在后。

    例如,文件分片的校验值为0x0809,则低位字节为0x09,高位字节为0x08。

  • Header的JSON数据格式:
    {
        "id":"123456",
        "params":{
            "uploadId":"03d9151e-6***",
            "offset":34344,
            "bSize":123455,
            "isComplete":true
        }
    }
表 3. 请求参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
params Object 请求业务参数。
uploadId String 设备请求上传文件时返回的文件上传任务标识ID。
offset Long 已上传文件分片的总大小,单位为字节。
bSize Long 当前上传文件分片的大小,单位为字节。
  • 非最后一个分片时,分片大小范围为256 B~131072 B。
  • 最后一个文件分片时,若上传的文件大小已知,则分片大小范围为1 B~131072 B;若上传的文件大小未知,则分片大小范围为0 B~131072 B。
isComplete Boolean 仅当设备请求上传文件中fileSize为-1,即文件大小未知时,该参数有效,表示当前分片是否是文件的最后一个分片。
  • true:是。此时,物联网平台的云端会校验已上传文件大小是否超过16 MB:
    • 未超过:若文件大小大于0,则文件上传成功。若文件大小为0,则返回文件不能为空的错误信息且删除文件上传任务。
    • 超过:返回文件大小超过16 MB的错误码,并删除已上传的文件。详细说明,请参见设备上传文件相关错误码
  • false:否。表示不是最后一个文件分片,需继续上传文件。

响应数据格式:

说明 未知大小的文件上传过程中,上传文件大小若超过16 MB,则返回文件大小超过16 MB的错误码78117,且物联网平台云端会自动取消文件上传任务,并删除已上传的文件。
{
    "id":"123456",
    "code":200,
    "message":"this is error msg when code is not 200",
    "data":{
        "uploadId":"03d9151e-6***",
        "offset":34344,
        "bSize":123455,
        "complete":true,
        "ficMode":"crc64",
        "ficValueClient":"0205d7***",
        "ficValueServer":"0205d7***"
    }
}
表 4. 响应参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code Integer 结果码。返回200表示成功,返回其他状态码,表示失败,具体请参见设备端接收的错误码
message String 上传失败时,返回的错误信息。
data Object 返回设备端的数据。
uploadId String 本次上传文件任务的标识ID。后续上传文件分片时,需要传递该文件标识ID。
offset Long 已上传文件分片的总大小,单位为字节。
bSize Long 当前上传文件分片的大小,单位为字节。
  • 非最后一个分片时,分片大小范围为256 B~131072 B。
  • 最后一个文件分片时,若上传的文件大小已知,则分片大小范围为1 B~131072 B;若上传的文件大小未知,则分片大小范围为0 B~131072 B。
complete Boolean 当上传了最后一个分片数据后,文件上传完成,返回该参数,值为true
  • 若设备请求上传文件的请求消息中fileSize值大于0,即文件大小已知时,若已上传的文件大小与设备请求上传文件时的文件大小相同,文件被识别为上传完成。
  • 若设备请求上传的请求消息中fileSize值为-1,即文件大小未知时,若文件分片上传请求中isComplete存在且值为true,文件被识别为上传完成。
ficMode String 文件的完整性校验模式。若请求上传文件时传入了该参数,对应的值仅支持为crc64
ficValueClient String 文件上传完成,返回设备请求上传文件时的ficValue值。
ficValueServer String 文件上传完成,返回物联网平台云端计算的文件完整性校验值。该值与ficValueClient值相同,表示文件上传完整。

设备取消上传文件

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/cancel
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/cancel_reply

请求数据格式:

{
    "id":"123456",
    "params":{
        "uploadId":"03d9151e-6***"
    }
}
表 5. 请求参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
params Object 请求业务参数。
uploadId String 设备请求上传文件时返回的文件上传任务标识ID。

响应数据格式:

{
    "id":"123456",
    "code":200,
    "message":"uploading task for upload-id xxxx does not exist.",
    "data":{
        "uploadId":"03d9151e-6***"
    }
}
表 6. 响应参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code Integer 结果码。返回200表示成功,返回其他状态码,表示失败,具体请参见设备端接收的错误码
message String 请求失败时,返回的错误信息。
data Object 返回设备端的数据。
uploadId String 取消的文件上传任务标识ID。

相关文档

设备端接收的错误码信息,请参见设备上传文件相关错误码