{"id":27861009,"url":"https://github.com/iot-thingscloud/thingscloud-api-python-tools","last_synced_at":"2026-03-11T04:31:22.785Z","repository":{"id":266192662,"uuid":"894817318","full_name":"IoT-ThingsCloud/thingscloud-api-python-tools","owner":"IoT-ThingsCloud","description":"ThingsCloud API 工具集，基于平台的开放 API 体系，实现了多种扩展工具，可用于数据导入导出、自动化、数据处理、数据分析等。","archived":false,"fork":false,"pushed_at":"2025-09-10T04:02:13.000Z","size":51,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-10T08:07:43.773Z","etag":null,"topics":["api","iot","iot-application","iot-platform","python","thingscloud"],"latest_commit_sha":null,"homepage":"https://www.thingscloud.xyz/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IoT-ThingsCloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-27T03:36:23.000Z","updated_at":"2025-09-10T04:02:16.000Z","dependencies_parsed_at":"2025-03-25T02:33:01.372Z","dependency_job_id":"1fc3dc17-c76e-4b4d-98af-3387706f124e","html_url":"https://github.com/IoT-ThingsCloud/thingscloud-api-python-tools","commit_stats":null,"previous_names":["iot-thingscloud/thingscloud-api-python-tools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/IoT-ThingsCloud/thingscloud-api-python-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IoT-ThingsCloud%2Fthingscloud-api-python-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IoT-ThingsCloud%2Fthingscloud-api-python-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IoT-ThingsCloud%2Fthingscloud-api-python-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IoT-ThingsCloud%2Fthingscloud-api-python-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IoT-ThingsCloud","download_url":"https://codeload.github.com/IoT-ThingsCloud/thingscloud-api-python-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IoT-ThingsCloud%2Fthingscloud-api-python-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30370797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","iot","iot-application","iot-platform","python","thingscloud"],"created_at":"2025-05-04T18:26:19.551Z","updated_at":"2026-03-11T04:31:22.755Z","avatar_url":"https://github.com/IoT-ThingsCloud.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# thingscloud-api-python-tools\n\n[ThingsCloud API](https://www.thingscloud.xyz/docs/guide/api/project-api.html) 工具集，基于平台的开放 API 体系，实现了多种扩展工具，可用于数据导入导出、自动化、数据处理、数据分析等。\n\n👋🏻 已实现的工具包括：\n\n- ✨ 批量创建设备\n- ✨ 批量导出设备信息，以及生成设备二维码\n- ✨ 批量导出设备属性历史数据\n- ✨ 批量导出设备证书\n\n🔨 计划实现的工具包括：\n\n- ✨ 批量创建用户\n- ✨ 实时接收设备最新数据\n- ✨ 实时接收设备在线状态变化\n- ✨ 实时接收设备告警消息\n- ✨ 批量移除设备\n- ✨ 批量导出设备属性聚合统计数据\n\n工具集持续更新中，欢迎使用，欢迎贡献代码。\n\n同时，该工具集也提供了快速开发的框架，您可以自行扩展和定制开发需要的功能。\n\n## 环境准备\n\n该工具集使用 Python 语言编写，运行在您的电脑上，需要安装 Python 3.8 或以上版本。\n\nPython 环境安装方法，网上教程非常丰富，请自行学习。\n\n\n## 下载工具代码库\n\n### 推荐方法\n\n点击以下链接，下载代码压缩包，解压缩。\n\n[https://github.com/IoT-ThingsCloud/thingscloud-api-python-tools/archive/refs/heads/main.zip](https://github.com/IoT-ThingsCloud/thingscloud-api-python-tools/archive/refs/heads/main.zip)\n\n### 高级方法\n\n或使用 `git` 命令下载代码库。\n\n```bash\ngit clone https://github.com/IoT-ThingsCloud/thingscloud-api-python-tools.git\n```\n\n## 安装依赖库\n\n下载代码库后，进入 `thingscloud-api-python-tools` 代码目录的根目录，执行以下命令，安装依赖库：\n\n```bash\npip install -r requirements.txt\n```\n\n## 修改配置\n\n进入 config 目录，将 `project_api.template.ini` 复制到 `project_api.ini`，填写 API 参数，如下：\n\n```ini\n[API]\nbase_url=\napp_id=\naccess_key=\nsecret_key=\n```\n\n以上信息可以在 ThingsCloud 平台控制台中获取，方法如下：\n\n| 参数名 | 获取方法 |\n| --- | --- |\n| base_url | 进入项目 \u003e 连接信息，查看 应用端 API 接入点。 |\n| app_id | 创建项目应用 \u003e API，查看应用 AppID。 |\n| access_key | 创建项目应用 \u003e API，查看应用 AccessKey。 |\n| secret_key | 创建项目应用 \u003e API，查看应用 SecretKey。 |\n\n## 运行工具\n\n进入代码的根目录，执行以下命令。\n\n### 查看帮助\n\n```bash\npython main.py --help\n```\n\n获得使用帮助信息如下：\n\n```bash\nUsage: main.py [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --log   开启日志\n  --help  Show this message and exit.\n\nCommands:\n  create_devices\n  export_devices\n  export_devices_attributes_history\n  ...\n```\n\n以上列出的每个命令（Command），对应一个工具名称，可以查询工具的帮助信息，例如：\n\n```bash\npython main.py create_devices --help\n```\n\n获得帮助信息如下：\n\n```bash\nUsage: main.py create_devices [OPTIONS]\n\nOptions:\n  --path TEXT     指定导入的 CSV 文件路径  [default:\n                  import/create_devices_template.csv]\n  --type_id TEXT  为创建的设备指定设备类型 ID  [required]\n  --help          Show this message and exit.\n```\n\n### 批量创建设备\n\n该工具使用 CSV 文件中的设备信息，批量创建设备。\n\n#### 示例 1\n\n默认导入 `import/create_devices_template.csv` 文件中的设备信息，执行命名：\n\n```bash\npython main.py create_devices --type_id=\u003ctype_id\u003e\n```\n\n请将 `\u003ctype_id\u003e` 替换为创建设备所关联的设备类型 ID。批量创建设备必须指定所属设备类型。\n\n您可以修改该文件内容，格式如下：\n\n```\nname,device_key\n设备名称1,100001\n设备名称2,100002\n设备名称3,100003\n```\n\n如果不需要为设备指定唯一标识（DeviceKey）, 可以将 `device_key` 列留空，例如：\n\n```\nname,device_key\n设备名称1,\n设备名称2,\n设备名称3,\n```\n\n请注意，csv 文件务必使用 UTF-8 编码格式，否则设备名称包含中文会导致程序运行报错。\n\n工具运行后，会显示导入进度，如下图：\n\n![](https://img-1300291923.cos.ap-beijing.myqcloud.com/articles/2023/20241204095121_f90a1f93075f3da225d300abf9a90317.png)\n\n\n#### 示例 2\n\n自定义导入 CSV 文件的路径，执行命名：\n\n```bash\npython main.py create_devices --type_id=\u003ctype_id\u003e --file_path=\u003cfile_path\u003e\n```\n\n将 `\u003cfile_path\u003e` 替换为您电脑上的 CSV 文件路径，例如 `C:\\Users\\Join\\Desktop\\devices.csv`。\n\n### 批量导出设备信息\n\n该工具用于批量导出设备信息到本地 CSV 文件，也同时批量生成设备二维码。\n\n#### 示例 1\n\n导出项目中的所有设备，执行命令：\n\n```bash\npython main.py export_devices\n```\n\n导出的 CSV 文件将保存在 `export` 目录下，以当前时间命令，例如： `export/2024-10-01-10-08-31.csv`。\n\n#### 示例 2\n\n导出项目中的所有设备，同时生成设备二维码，执行命令：\n\n```bash\npython main.py export_devices --qrcode\n```\n\n工具运行时显示导出进度，如下：\n\n![](https://img-1300291923.cos.ap-beijing.myqcloud.com/articles/2023/20241204100627_fabb8461b7eabca93b2f9c1a6eac080d.png)\n\n生成二维码图片文件，如下：\n\n![](https://img-1300291923.cos.ap-beijing.myqcloud.com/articles/2023/20241204100908_be9a6a4aebacfc31befe8632169ffbc2.png)\n\n\n#### 示例 3\n\n导出项目中指定设备类型下的所有设备，执行命令：\n\n```bash\npython main.py export_devices --type_id=\u003ctype_id\u003e\n```\n\n将 `\u003ctype_id\u003e` 替换为您要导出的设备类型 ID。\n\n#### 示例 4\n\n导出项目中指定设备组下的所有设备，执行命令：\n\n```bash\npython main.py export_devices --group_id=\u003cgroup_id\u003e\n```\n\n将 `\u003cgroup_id\u003e` 替换为您要导出的设备组 ID。支持多个组，以逗号分隔。例如：`--group_id=\u003cgroup_id1\u003e,\u003cgroup_id2\u003e,\u003cgroup_id3\u003e`。\n\n#### 示例 5\n\n导出项目中指定设备组下的所有设备，并包含子组下的所有设备，执行命令：\n\n```bash\npython main.py export_devices --group_id=\u003cgroup_id\u003e --include_sub_groups\n```\n\n\n### 批量导出设备属性历史数据\n\n该工具用于批量导出多个设备的属性历史数据到一个 CSV 文件，生成规范结构化数据（也称为 Tidy Data）。\n\n#### 示例 1\n\n导出项目中所有设备的属性历史数据，执行命令：\n\n```bash\npython main.py export_devices_attributes_history\n```\n\n该命令默认导出最近 30 天的属性历史数据。\n\n工具运行时显示导出进度，如下：\n\n![](https://img-1300291923.cos.ap-beijing.myqcloud.com/articles/2023/20241204101018_bfe957ef52043afbdb0ca46fecbe2ddb.png)\n\n导出的 CSV 文件在 Excel 中打开如下：\n\n![](https://img-1300291923.cos.ap-beijing.myqcloud.com/articles/2023/20241204101208_7669bd9e1d52857c9ede33d89391a856.png)\n\n#### 示例 2\n\n指定导出时间范围，执行命令：\n\n```bash\npython main.py export_devices_attributes_history  --start_time=\u003c开始时间\u003e --end_time=\u003c结束时间\u003e\n```\n\n将 `\u003c开始时间\u003e` 和 `\u003c结束时间\u003e` 替换为实际时间，时间格式为：`YYYYMMDDHHmmss`。\n\n例如，导出 2024 年 12 月 1 日 00:00:00 到 12 月 2 日 20:00:00 的属性历史数据：\n\n```bash\npython main.py export_devices_attributes_history  --start_time=20241201000000 --end_time=20241202200000\n```\n\n#### 示例 3\n\n指定导出的设备，执行命令：\n\n```bash\npython main.py export_devices_attributes_history --device_id=\u003cdevice_id\u003e\n```\n\n将 `\u003cdevice_id\u003e` 替换为您要导出的设备 ID。\n\n\n#### 示例 4\n\n指定设备类型下的所有设备，执行命令：\n\n```bash\npython main.py export_devices_attributes_history --type_id=\u003ctype_id\u003e\n```\n\n将 `\u003ctype_id\u003e` 替换为您要导出的设备类型 ID。\n\n#### 示例 5\n\n指定设备组下的所有设备，执行命令：\n\n```bash\npython main.py export_devices_attributes_history --group_id=\u003cgroup_id\u003e\n```\n\n将 `\u003cgroup_id\u003e` 替换为您要导出的设备组 ID。支持多个组，以逗号分隔。例如：`--group_id=\u003cgroup_id1\u003e,\u003cgroup_id2\u003e,\u003cgroup_id3\u003e`。\n\n#### 示例 6\n\n指定设备组下的所有设备，并包含子组下的所有设备，执行命令：\n\n```bash\npython main.py export_devices_attributes_history --group_id=\u003cgroup_id\u003e --include_sub_groups\n```\n\n\n\n### 批量导出设备证书\n\n该工具用于批量导出设备证书到本地 CSV 文件。\n\n出于安全考虑，导出的证书信息中仅包含每台设备的 AccessToken，其它信息可以在 ThingsCloud 控制台中查看。\n\n设备证书用于硬件设备接入 ThingsCloud 平台时进行身份认证，关于设备证书的使用方法，请浏览 [ThingsCloud 文档 - 设备证书](https://www.thingscloud.xyz/docs/guide/connect-device/device-certificate.html)。\n\n\n#### 示例 1\n\n导出项目中所有设备的证书，执行命令：\n\n```bash\npython main.py export_devices_certificates\n```\n\n\n#### 示例 2\n\n指定设备类型下的所有设备证书，执行命令：\n\n```bash\npython main.py export_devices_certificates --type_id=\u003ctype_id\u003e\n```\n\n将 `\u003ctype_id\u003e` 替换为您要导出的设备类型 ID。\n\n#### 示例 3\n\n指定设备组下的所有设备证书，执行命令：\n\n```bash\npython main.py export_devices_certificates --group_id=\u003cgroup_id\u003e\n```\n\n将 `\u003cgroup_id\u003e` 替换为您要导出的设备组 ID。支持多个组，以逗号分隔。例如：`--group_id=\u003cgroup_id1\u003e,\u003cgroup_id2\u003e,\u003cgroup_id3\u003e`。\n\n#### 示例 4\n\n指定设备组下的所有设备证书，并包含子组下的所有设备，执行命令：\n\n```bash\npython main.py export_devices_certificates --group_id=\u003cgroup_id\u003e --include_sub_groups\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiot-thingscloud%2Fthingscloud-api-python-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiot-thingscloud%2Fthingscloud-api-python-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiot-thingscloud%2Fthingscloud-api-python-tools/lists"}