通过MQTT协议将文件上传至物联网平台进行储存_物联网平台(IoT)-阿里云帮助中心

物联网平台支持设备通过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，不支持设置ficMode和ficValue。
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。仅ossOwnerType为`device-user`时，serviceId有效。
fileTag	Object	文件保存到OSS存储空间携带的标签，最多包含5个。标签定义规则，请参见对象标签。标签Key不能以2个下划线（_）开头。仅ossOwnerType为`device-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	仅当请求参数conflictStrategy为append，且物联网平台云端存在未完成上传的文件时，返回的已上传文件的大小，单位为字节。

设备上传文件分片

请求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。

背景信息

设备请求上传文件

设备上传文件分片

设备取消上传文件

相关文档