实体 API (Thing)

实体 API 使用以下四个入口：

• POST /thing/create
• POST /thing/update
• POST /thing/archive
• POST /thing/delete

契约说明

• 请求体必须是 JSON。
• 请求模型为严格解析，未声明字段会直接报错（400）。
• Authorization: Bearer <token> 仅在网关开启鉴权时必填。

通用字段

字段	类型	必填	说明
channel_id	string	是	目标频道 ID。
password	string	是	频道密码，长度 8-128。
op_id	string	否	幂等键；不传则网关自动生成并在响应回传。

路由级必填矩阵

路由	业务硬必填字段
/thing/create	observed_at
/thing/update	thing_id、observed_at
/thing/archive	thing_id、observed_at
/thing/delete	thing_id、observed_at

字段规则

字段	类型	必填	规则
thing_id	string	更新/归档/删除必填	创建时不能传；由网关生成。
title	string	否（创建建议传）	产品语义上建议 create 传入主标题；当前网关不会因缺失 title 拒绝创建。
description	string	否	空字符串会按缺省处理。
tags	string[]	否	最多 32 项，每项最多 64 字符，trim 后去重。
primary_image	string	否	可选 URL，最大 2048 字符。
images	string[]	否	最多 32 项，每项最多 2048 字符，trim 后去重。
created_at	number	否	仅 create 允许；不传时回退为 observed_at。
deleted_at	number	否	仅 delete 允许；不传时回退为 observed_at。
external_ids	object	否	key 仅允许 [A-Za-z0-9_:.\-]，且 key <= 64；value 仅 string 或 null（null 表示删键）。
location_type + location_value	string + string	成对	必须同时出现。location_type 仅允许 physical/geo/cloud/datacenter/logical。
observed_at	number	是	Unix 秒时间戳，作为本次对象分发的发生时间。
attrs	object	否	对象补丁；value 为 null 表示删键；不允许数组；对象嵌套仅支持一层。
metadata	object	否	仅支持标量值（string/number/bool），key <= 64，value <= 512。

创建示例

curl -X POST https://gateway.pushgo.cn/thing/create \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "06J0FZG1Y8XGG14VTQ4Y3G10MR",
    "password": "pass-1234",
    "title": "客厅温度计",
    "observed_at": 1713750000,
    "tags": ["sensor", "temperature"],
    "attrs": { "temperature": 22.5 }
  }'

响应示例

{
  "success": true,
  "data": {
    "channel_id": "06J0FZG1Y8XGG14VTQ4Y3G10MR",
    "op_id": "op-20260422-001",
    "thing_id": "8a1fc4b3d9f04fd2857f92f66f7cc5d1",
    "accepted": true
  },
  "error": null,
  "error_code": null
}