diff --git a/HTTP_API_README.md b/HTTP_API_README.md new file mode 100644 index 0000000..c6c7cd8 --- /dev/null +++ b/HTTP_API_README.md @@ -0,0 +1,878 @@ +# 🧩 IoT 容器管理接口文档 + +**模块**:`container_handler` +**作者**:licheng5 +**创建时间**:2020-04-26 +**说明**:提供容器的部署、配置、启动、停止、查询等管理 API 接口。 + +--- + +## 📦 模块结构 + +| 模块 | 说明 | +|------|------| +| `container_handler` | 提供容器管理的 HTTP 接口处理 | +| `iot_util` | 工具模块,用于生成标准化 JSON 响应 | + +--- + +## ⚙️ `iot_util` 模块函数声明 + +```erlang +%%-------------------------------------------------------------------- +%% @doc +%% 将数据封装为标准 JSON 响应: +%% {"result": Data} +%%-------------------------------------------------------------------- +json_data(Data) -> + jiffy:encode(#{ + <<"result">> => Data + }, [force_utf8]). + +%%-------------------------------------------------------------------- +%% @doc +%% 生成错误响应 JSON: +%% { +%% "error": { +%% "code": ErrCode, +%% "message": ErrMessage +%% } +%% } +%%-------------------------------------------------------------------- +json_error(ErrCode, ErrMessage) when is_integer(ErrCode), is_binary(ErrMessage) -> + jiffy:encode(#{ + <<"error">> => #{ + <<"code">> => ErrCode, + <<"message">> => ErrMessage + } + }, [force_utf8]). +``` + +### 📘 返回格式说明 + +| 字段 | 说明 | +|------|------| +| `result` | 正常返回数据 | +| `error.code` | 错误代码 | +| `error.message` | 错误信息 | + +--- + +## 🌐 HTTP API 接口列表 + +以下为 `container_handler` 模块导出的全部 HTTP 接口。 + +--- + +### 1️⃣ 获取容器列表 + +**URL**:`/container/get_all` +**Method**:`GET` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | list | 容器信息列表 | + +#### 示例响应 +```json +{ + "result": [ + {"name": "container_1", "status": "running"}, + {"name": "container_2", "status": "stopped"} + ] +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": -1, + "message": "host not found" + } +} +``` + +--- + +### 2️⃣ 下发配置文件 + +**URL**:`/container/push_config` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | +| container_name | binary (string) | ✅ | 容器名称 | +| config | binary (string, JSON) | ✅ | 容器配置内容(JSON 字符串) | +| timeout | integer | ✅ | 超时时间(秒) | + +### 请求示例 +```json +{"uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm", "container_name": "my_nginx_new", "config": "{\"application\":{\"namexyz\":\"RandomConfigApp\",\"version\":\"1.2.7\",\"environment\":{\"debug_mode\":true,\"log_level\":\"info\",\"max_log_files\":10}},\"server\":{\"host\":\"127.0.0.1\",\"port\":8080,\"ssl_enabled\":false,\"allowed_origins\":[\"https:\\/\\/example.com\",\"http:\\/\\/localhost:3000\"]},\"database\":{\"type\":\"postgresql\",\"host\":\"db.example.com\",\"port\":5432,\"username\":\"admin_7xq9f\",\"password\":\"p@ssw0rd!r4nd\",\"connection_pool\":15,\"timeout_seconds\":30},\"features\":{\"enable_analytics\":true,\"enable_cache\":false,\"experimental_features\":[\"ai_enhancement\",\"realtime_sync\"]},\"third_party\":{\"api_key\":\"a3b8c2d4e5f6g7h8i9j0k1l2m3n4o5p\",\"weather_service_url\":\"https:\\/\\/api.weather.example\\/v3\",\"payment_gateway\":{\"endpoint\":\"https:\\/\\/pay.example.com\",\"merchant_id\":\"M123456789\"}},\"scheduled_tasks\":[{\"name\":\"nightly_backup\",\"cron\":\"0 3 * * *\",\"enabled\":true},{\"name\":\"log_cleanup\",\"interval_minutes\":1440,\"retention_days\":7}],\"admins\":[{\"username\":\"alice_dev\",\"email\":\"alice@example.com\",\"permissions\":[\"read\",\"write\",\"admin\"]},{\"username\":\"bob_ops\",\"email\":\"bob@example.org\",\"permissions\":[\"read\",\"audit\"]}]}", "timeout": 10} +``` + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | map | 配置结果 | + +#### 示例响应 +```json +{ + "result": { + "container_name": "sensor_service", + "status": "config pushed" + } +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": -1, + "message": "host not found" + } +} +``` + +--- + +### 3️⃣ 部署容器服务 + +**URL**:`/container/deploy` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | +| task_id | integer | ✅ | 任务 ID | +| config | map | ✅ | 部署配置内容 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | map | 部署结果 | + +### 请求示例 +```json +{ + "uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm", + "task_id": 1, + "timeout": 10, + "config": { + "image": "docker.1ms.run/library/nginx:latest", + "container_name": "my_nginx_new", + "command": [ + "nginx", + "-g", + "daemon off;" + ], + "entrypoint": [ + "/docker-entrypoint.sh" + ], + "envs": [ + "ENV1=val1", + "ENV2=val2" + ], + "env_file": [ + "./env.list" + ], + "ports": [ + "8080:80", + "443:443" + ], + "expose": [ + "80", + "443" + ], + "volumes": [ + "/host/data:/data", + "/host/log:/var/log" + ], + "networks": [ + "mynet" + ], + "labels": { + "role": "web", + "env": "prod" + }, + "restart": "always", + "user": "www-data", + "working_dir": "/app", + "hostname": "myhost", + "privileged": true, + "cap_add": [ + "NET_ADMIN" + ], + "cap_drop": [ + "MKNOD" + ], + "devices": [ + "/dev/snd:/dev/snd" + ], + "mem_limit": "512m", + "mem_reservation": "256m", + "cpu_shares": 512, + "cpus": 1.5, + "ulimits": { + "nofile": "1024:2048" + }, + "sysctls": { + "net.ipv4.ip_forward": "1" + }, + "tmpfs": [ + "/tmp" + ], + "extra_hosts": [ + "host1:192.168.0.1" + ], + "healthcheck": { + "test": [ + "CMD-SHELL", + "curl -f http://localhost || exit 1" + ], + "interval": "30s", + "timeout": "10s", + "retries": 3 + } + } +} + +``` + +#### 示例响应 +```json +{ + "result": { + "task_id": 1001, + "status": "deployed" + } +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "host not found" + } +} +``` + +--- + +### 4️⃣ 启动容器服务 + +**URL**:`/container/start` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | +| container_name | binary (string) | ✅ | 容器名称 | + +### 请求示例 +```json +{"uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm", "container_name": "my_nginx_new"} +``` + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | map | 启动结果 | + +#### 示例响应 +```json +{ + "result": { + "container_name": "sensor_service", + "status": "started" + } +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "host not found" + } +} +``` + +--- + +### 5️⃣ 停止容器服务 + +**URL**:`/container/stop` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | +| container_name | binary (string) | ✅ | 容器名称 | + +### 请求示例 +```json +{"uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm", "container_name": "my_nginx_new"} +``` + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | map | 停止结果 | + +#### 示例响应 +```json +{ + "result": { + "container_name": "sensor_service", + "status": "stopped" + } +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "host not found" + } +} +``` + +--- + +### 6️⃣ 未知路径处理 + +**说明**:如果请求路径未匹配任何定义接口,将返回错误信息。 + +#### 示例响应 +```json +{ + "error": { + "code": -1, + "message": "url: /unknown/path not found" + } +} +``` + +--- + +## 🧾 返回约定总结 + +| 类型 | 说明 | +|------|------| +| `{"result": Data}` | 表示请求成功 | +| `{"error": {"code": N, "message": Text}}` | 表示请求失败 | + + + +# 🧩 IoT Endpoint 管理接口文档 + +**模块**:`endpoint_handler` +**作者**:licheng5 +**创建时间**:2020-04-26 +**说明**:用于管理 IoT Endpoint 的运行状态,包括启动、停止、重启、状态查询等。 + +--- + +## 📦 模块结构 + +| 模块 | 说明 | +|------|------| +| `endpoint_handler` | 提供 Endpoint 管理的 HTTP 接口处理 | +| `iot_util` | 工具模块,用于生成标准化 JSON 响应 | + +--- + +## ⚙️ `iot_util` 模块函数声明 + +```erlang +%%-------------------------------------------------------------------- +%% @doc +%% 将数据封装为标准 JSON 响应: +%% {"result": Data} +%%-------------------------------------------------------------------- +json_data(Data) -> + jiffy:encode(#{ + <<"result">> => Data + }, [force_utf8]). + +%%-------------------------------------------------------------------- +%% @doc +%% 生成错误响应 JSON: +%% { +%% "error": { +%% "code": ErrCode, +%% "message": ErrMessage +%% } +%% } +%%-------------------------------------------------------------------- +json_error(ErrCode, ErrMessage) when is_integer(ErrCode), is_binary(ErrMessage) -> + jiffy:encode(#{ + <<"error">> => #{ + <<"code">> => ErrCode, + <<"message">> => ErrMessage + } + }, [force_utf8]). +``` + +### 📘 返回格式说明 + +| 字段 | 说明 | +|------|------| +| `result` | 正常返回数据 | +| `error.code` | 错误代码 | +| `error.message` | 错误信息 | + +--- + +## 🌐 HTTP API 接口列表 + +以下为 `endpoint_handler` 模块导出的全部 HTTP 接口。 + +--- + +### 1️⃣ 获取 Endpoint 运行状态 + +**URL**:`/endpoint/run_statuses` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| Ids | list | ✅ | Endpoint ID 列表 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | list | 每个 ID 对应状态:`0` 未运行,`1` 运行中 | + +#### 示例请求 +```json +[1, 2, 3] +``` + +#### 示例响应 +```json +{ + "result": [1, 0, 1] +} +``` + +--- + +### 2️⃣ 启动 Endpoint + +**URL**:`/endpoint/start` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| id | integer | ✅ | Endpoint 唯一 ID | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | string | 启动结果,如 `"success"` | + +#### 示例响应 +```json +{ + "result": "success" +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "endpoint not found" + } +} +``` + +--- + +### 3️⃣ 停止 Endpoint + +**URL**:`/endpoint/stop` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| id | integer | ✅ | Endpoint 唯一 ID | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | string | 停止结果,如 `"success"` | + +#### 示例响应 +```json +{ + "result": "success" +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "stop endpoint error" + } +} +``` + +--- + +### 4️⃣ 重启 Endpoint + +**URL**:`/endpoint/restart` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| id | integer | ✅ | Endpoint 唯一 ID | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | string | 重启结果,如 `"success"` | + +#### 示例响应 +```json +{ + "result": "success" +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "restart endpoint error" + } +} +``` + +--- + +### 5️⃣ 未知路径处理 + +**说明**:如果请求路径未匹配任何定义接口,将返回错误信息。 + +#### 示例响应 +```json +{ + "error": { + "code": -1, + "message": "url: /unknown/path not found" + } +} +``` + +--- + +## 🧾 返回约定总结 + +| 类型 | 说明 | +|------|------| +| `{"result": Data}` | 表示请求成功 | +| `{"error": {"code": N, "message": Text}}` | 表示请求失败 | + + +# 🧩 IoT Host 管理接口文档 + +**模块**:`host_handler` +**作者**:licheng5 +**创建时间**:2020-04-26 +**说明**:用于管理 IoT 主机,包括主机指标、状态查询、激活、删除、发布事件等接口。 + +--- + +## 📦 模块结构 + +| 模块 | 说明 | +|------|------| +| `host_handler` | 提供 Host 管理的 HTTP 接口处理 | +| `iot_util` | 工具模块,用于生成标准化 JSON 响应 | + +--- + +## ⚙️ `iot_util` 模块函数声明 + +```erlang +%%-------------------------------------------------------------------- +%% @doc +%% 将数据封装为标准 JSON 响应: +%% {"result": Data} +%%-------------------------------------------------------------------- +json_data(Data) -> + jiffy:encode(#{ + <<"result">> => Data + }, [force_utf8]). + +%%-------------------------------------------------------------------- +%% @doc +%% 生成错误响应 JSON: +%% { +%% "error": { +%% "code": ErrCode, +%% "message": ErrMessage +%% } +%% } +%%-------------------------------------------------------------------- +json_error(ErrCode, ErrMessage) when is_integer(ErrCode), is_binary(ErrMessage) -> + jiffy:encode(#{ + <<"error">> => #{ + <<"code">> => ErrCode, + <<"message">> => ErrMessage + } + }, [force_utf8]). +``` + +### 📘 返回格式说明 + +| 字段 | 说明 | +|------|------| +| `result` | 正常返回数据 | +| `error.code` | 错误代码 | +| `error.message` | 错误信息 | + +--- + +## 🌐 HTTP API 接口列表 + +以下为 `host_handler` 模块导出的全部 HTTP 接口。 + +--- + +### 1️⃣ 获取主机指标 + +**URL**:`/host/metric` +**Method**:`GET` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | map | 主机指标信息 | + +#### 示例响应 +```json +{ + "result": {"cpu": 20, "memory": 1024, "disk": 51200} +} +``` + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "host not found" + } +} +``` + +#### 无指标信息响应 +```json +{ + "error": { + "code": 404, + "message": "no metric info" + } +} +``` + +--- + +### 2️⃣ 查询主机状态 + +**URL**:`/host/status` +**Method**:`GET` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | map | 主机状态信息 | + +#### 示例响应 +```json +{ + "result": {"authorize_status": 1, "active": true} +} +``` + +--- + +### 3️⃣ 重新加载主机信息 + +**URL**:`/host/reload` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | string | 重新加载结果,如 `"success"` | + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "reload error" + } +} +``` + +--- + +### 4️⃣ 删除主机 + +**URL**:`/host/delete` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | string | 删除结果,如 `"success"` | + +#### 错误响应 +```json +{ + "error": { + "code": 404, + "message": "error" + } +} +``` + +--- + +### 5️⃣ 激活主机 + +**URL**:`/host/activate` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | +| auth | boolean | ✅ | `true` 激活, `false` 取消激活 | + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | string | 激活结果,如 `"success"` | + +#### 错误响应 +```json +{ + "error": { + "code": 400, + "message": "host not found" + } +} +``` + +--- + +### 6️⃣ 发布主机事件 + +**URL**:`/host/pub` +**Method**:`POST` + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| uuid | binary (string) | ✅ | 主机唯一标识符 | +| topic | binary (string) | ✅ | 事件主题 | +| content | binary (string) | ✅ | 发布内容 | + +### 请求示例 +```json +{"uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm", "topic": "/device/1234/all", "content": "this is a topic payload", "timeout": 10} +``` + +#### 响应参数 +| 字段 | 类型 | 说明 | +|------|------|------| +| result | string | 发布结果,如 `"success"` | + +#### 错误响应 +```json +{ + "error": { + "code": 400, + "message": "host not found" + } +} +``` + +--- + +### 7️⃣ 未知路径处理 + +**说明**:如果请求路径未匹配任何定义接口,将返回错误信息。 + +#### 示例响应 +```json +{ + "error": { + "code": -1, + "message": "url: /unknown/path not found" + } +} +``` + +--- + +## 🧾 返回约定总结 + +| 类型 | 说明 | +|------|------| +| `{"result": Data}` | 表示请求成功 | +| `{"error": {"code": N, "message": Text}}` | 表示请求失败 | diff --git a/README.md b/README.md deleted file mode 100644 index 22ca0a3..0000000 --- a/README.md +++ /dev/null @@ -1,12 +0,0 @@ -iot -===== - -An OTP application - -## erlang client sdk - https://github.com/emqx/emqtt - -Build ------ - - $ rebar3 compile