设备图片上传

在一些物联网应用场景中，设备需要向云平台上报图片，实现可视化的远程监测和告警。ThingsCloud 为设备提供了专用的图片上传服务，设备通过简单的 HTTP 请求即可将图片上传到平台，并自动关联到设备属性中。

以下是一些典型的应用场景：

• 农业虫情监测：虫情测报灯自动诱捕害虫并拍照，设备将照片上传至云平台，结合 AI 识别实现虫害统计和预警。
• 安防预警：门磁传感器、红外人体感应器触发报警后，联动摄像头抓拍现场照片并上传，便于远程确认警情。
• 红外火警相机：热成像相机检测到温度异常或明火时，自动拍摄可见光照片上传，辅助消防预警和溯源。
• 工业质检异常：产线视觉检测设备发现产品缺陷时，将异常品照片上传，供质量管理人员远程复核和追溯。
• 设备运行状态截图：带有屏幕的工控设备或仪表，定期截屏上传，方便运维人员远程查看现场界面。
• AI 识别结果：边缘计算设备完成图像识别后，将标记了识别结果的照片上传，用于留档或人工二次确认。

以上场景中，设备只需要将图片以原始二进制形式通过 HTTP POST 发送到图片上传服务，平台会自动将图片存储到项目集成的 OSS 对象存储中，并将图片 URL 更新到相关设备属性中，方便在控制台、可视化看板以及用户应用中直接查看图片。

准备工作

进入控制台的 项目设置 > 第三方集成，完成阿里云对象存储的集成配置，具体步骤请参阅 阿里云 OSS 对象存储集成指南。

图片上传接入点

接入点格式如下：

如需获得设备图片上传接入点 <endpoint>，请联系技术支持。

图片上传 API

设备向云平台上报图片时，调用如下 API：

POST https://<endpoint>/device/v1/<AccessToken>/<identifier>/image

HTTP 请求头

调用图片上传 API 时，需要在 HTTP 请求头中加入以下字段：

请求头示例如下：

Content-Type: application/octet-stream
Region: <Region>
Project-Key: <ProjectKey>

URL 路径参数

请求正文

HTTP 请求的正文部分为原始图片二进制数据，不支持 multipart/form-data 或其它格式。

支持的图片格式

设备上传的图片必须满足以下格式要求：

图片大小限制

单张图片大小不得超过 500 KB。

请求频率限制

为了防止滥用，图片上传服务对请求频率进行了限制：

调用成功响应

图片上传成功且完成属性上报后，HTTP 响应正文如下：

{
  "result": 1,
  "image_url": "https://..."
}

错误响应

当请求参数不正确或处理失败时，接口会返回相应的错误信息：

{
  "result": 0,
  "errcode": 4001,
  "message": "Missing Region header"
}

错误码一览

完整请求示例

以下是一个使用 curl 命令上传图片的完整示例：

curl -X POST https://<endpoint>/device/v1/<AccessToken>/<identifier>/image \
  -H "Content-Type: application/octet-stream" \
  -H "Region: <region>" \
  -H "Project-Key: <ProjectKey>" \
  --data-binary "@/path/to/image.jpg"

示例代码

Node.js

以下示例使用 axios 发送图片二进制数据：

const fs = require('fs');
const axios = require('axios');

async function uploadImage(imagePath) {
  const endpoint = '<endpoint>';               // 图片上传接入点
  const accessToken = '<AccessToken>';         // 设备访问令牌
  const identifier = '<identifier>';           // 图片类型属性标识符
  const projectKey = '<ProjectKey>';           // 项目密钥
  const region = '<region>';                   // 设备所属区域

  const imageBuffer = fs.readFileSync(imagePath);

  try {
    const response = await axios.post(
      `https://${endpoint}/device/v1/${accessToken}/${identifier}/image`,
      imageBuffer,
      {
        headers: {
          'Content-Type': 'application/octet-stream',
          'Region': region,
          'Project-Key': projectKey,
        },
        maxBodyLength: 512 * 1024,  // 500 KB 限制
      }
    );

    console.log('上传成功:', response.data);
    // { result: 1, image_url: 'https://...' }
  } catch (error) {
    if (error.response) {
      console.error('上传失败:', error.response.status, error.response.data);
    } else {
      console.error('请求异常:', error.message);
    }
  }
}

// 调用示例
uploadImage('./image.jpg');

运行步骤：

1. 确保已安装 Node.js 运行环境。
2. 安装 axios 依赖：

   npm install axios
   
3. 将以上代码保存为 upload.js，修改其中的 <endpoint>、<AccessToken>、<identifier>、<ProjectKey>、<region> 为实际值。
4. 执行程序：

   node upload.js
   

Python

以下示例使用 requests 发送图片二进制数据：

import requests

def upload_image(image_path):
    endpoint = '<endpoint>'               # 图片上传接入点
    access_token = '<AccessToken>'        # 设备访问令牌
    identifier = '<identifier>'           # 图片类型属性标识符
    project_key = '<ProjectKey>'          # 项目密钥
    region = '<region>'                   # 设备所属区域

    url = f"https://{endpoint}/device/v1/{access_token}/{identifier}/image"

    headers = {
        'Content-Type': 'application/octet-stream',
        'Region': region,
        'Project-Key': project_key,
    }

    with open(image_path, 'rb') as f:
        image_data = f.read()

    try:
        response = requests.post(url, data=image_data, headers=headers)
        result = response.json()

        if result.get('result') == 1:
            print('上传成功:', result['image_url'])
        else:
            print('上传失败:', result)
    except requests.exceptions.RequestException as e:
        print('请求异常:', e)

# 调用示例
upload_image('./image.jpg')

运行步骤：

1. 确保已安装 Python 3 运行环境。
2. 安装 requests 依赖：

   pip install requests
   
3. 将以上代码保存为 upload.py，修改其中的 <endpoint>、<AccessToken>、<identifier>、<ProjectKey>、<region> 为实际值。
4. 执行程序：

   python upload.py