# 文件上传
物联网平台支持设备通过MQTT协议方式，将文件上传至用户自己的OSS空间进行储存。本文介绍设备上传文件流程相关的Topic和数据格式，包括设备请求上传文件、设备上传文件分片和设备取消上传文件。
# 背景信息
- 择将文件上传至您自己的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": "tagValue1",
"tagKey2": "tagValue2"
}
}
}
}
请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息 ID 号。String 类型的数字，取值范围 0~4294967295，且每个消息 ID 在当前设备中具有唯一性。 |
| params | Object | 请求业务参数。 |
| fileName | String | 设备上传文件的名称。限制如下： - 支持数字、英文字母、下划线（_）和英文句点（.）。 - 首字符仅支持数字和英文字母。 - 长度不超过 100 字节。 |
| fileSize | Long | 上传文件大小，单位字节。单个文件大小不超过 16 MB。 取值为 -1 时，表示文件大小未知。文件上传完成时，需在上传文件分片的消息中，指定参数 isComplete，具体说明，请参见设备上传文件分片。 |
| conflictStrategy | String | 物联网平台对设备上传同名文件的处理策略。非必填参数，默认为 overwrite。使用说明： - 若物联网平台不存在同名文件，直接创建文件的上传任务。 - 若物联网平台已存在同名文件，则按照设置的策略，进行如下处理： - overwrite：覆盖模式。先删除同名文件，再创建文件的上传任务。从创建文件上传任务成功开始计时，如果 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 所有者类型。可取值： - 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
}
}
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息 ID 号。String 类型的数字，取值范围 0~4294967295，且每个消息 ID 在当前设备中具有唯一性。 |
| code | Integer | 结果码。返回 200 表示成功，返回其他状态码，表示失败，具体请参见设备端接收的错误码。 |
| message | String | 请求失败时，返回的错误信息。 |
| data | Object | 返回设备端的数据。 |
| fileName | String | 设备上传文件的名称。 |
| uploadId | String | 本次上传文件任务的标识 ID。后续上传文件分片时，需要传递该文件标识 ID。 |
| offset | Long | 返回的已上传文件的大小，单位为字节。 |
# 设备上传文件分片
- 请求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
}
}
请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| 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***"
}
}
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| 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***"
}
}
请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| 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***"
}
}
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息 ID 号。String 类型的数字，取值范围 0~4294967295，且每个消息 ID 在当前设备中具有唯一性。 |
| code | Integer | 结果码。返回 200 表示成功，返回其他状态码，表示失败，具体请参见设备端接收的错误码。 |
| message | String | 请求失败时，返回的错误信息。 |
| data | Object | 返回设备端的数据。 |
| uploadId | String | 取消的文件上传任务标识 ID。 |