Bulk-Write CSV Data

使用单个 HTTP POST 以 CSV 格式将多个条目写入通道

描述

为了节省设备电量或组通道更新，您可以使用批量更新 API。使用批量更新 API 时，您会随着时间的推移收集数据，然后将数据上传到 ThingSpeak™。要以 JSON 格式写入数据，请参阅 Bulk-Write JSON Data。要写入单个条目，请参阅 Write Data。

注意

如果您将 React App 中的 Test Frequency 设置为 On Data Insertion，则当 Condition Type 与 Condition 匹配时，即使 Condition 匹配多次，您的 React 也只会在每次批量写入请求中触发一次。

请求

HTTP 方法

POST

URL

https://api.thingspeak.com/channels/<channel_id>/bulk_update.csv

URL 参数

名称	描述
`<channel_id>`	（必填）感兴趣通道的通道 ID。

URL 示例：https://api.thingspeak.com/channels/999990/bulk_update.csv

Content-Type

application/x-www-form-urlencoded

主体参数

名称	描述	值类型
`write_api_key`	（必填）为该特定通道指定写入 API 密钥。写入 API 密钥位于通道视图的 API Keys 选项卡上。	字符串
`time_format`	（必需）用 `time_format=absolute` 指定事件的绝对时间或用 `time_format=relative` 指定测量之间的时间。	字符串 `absolute` 或 `relative`
`updates`	批量数据发布到通道。使用管道字符 (`\|`) 分隔连续的条目。每次更新都以绝对日期时间或秒数开始。用逗号分隔连续的字段	请参阅更新参数。

更新参数

更新包含要发布到您的通道的数据。这些参数按照表中显示的顺序在每次更新中依次出现。每次更新仅会出现一个时间规范。

名称	描述	值类型
timestamp	（必需）如果是 `time_format=absolute`，请指定 ISO 8601、EPOCH 或 MYSQL 格式的日期时间。如果是 `time_format=relative`，则指定自上次输入以来经过的秒数。时间戳在通道内必须是唯一的。	日期时间或整数
字段 `<X>` 数据	（必填）字段 X 数据，其中 X 是字段 ID	任何值
纬度	（必需）纬度（以度为单位），指定为 `-90` 和 `90` 之间的值。	小数
经度	（必需）经度（以度为单位），指定为 `-180` 和 `180` 之间的值。	小数
海拔	（必填）海拔（以米为单位）	整数
状态	（必填）状态字段输入的消息	字符串

主体格式

每个 CSV 批量写入都包含一个写入 API 密钥和一个时间格式规范。每次批量写入可以包含多个更新。使用管道字符 (|) 分隔连续的条目。为每个连续参数提供数据或空白条目，直到最后一个具有有效数据的参数。

write_api_key=WRITE_API_KEY&time_format=TIME_FORMAT&updates=TIMESTAMP,FIELD1_VALUE,FIELD2_VALUE,FIELD3_VALUE,FIELD4_VALUE,FIELD5_VALUE,FIELD6_VALUE,FIELD7_VALUE,FIELD8_VALUE,LATITUDE,LONGITUDE,ELEVATION,STATUS | DATETIME_STAMP_OR_SECONDS_FROM_LAST_ENTRY,FIELD1_VALUE,FIELD2_VALUE,FIELD3_VALUE,FIELD4_VALUE,FIELD5_VALUE,FIELD6_VALUE,FIELD7_VALUE,FIELD8_VALUE,LATITUDE,LONGITUDE,ELEVATION,STATUS

指定绝对时间格式

write_api_key=XXXXXXXXXXXXXXXX&time_format=absolute&updates=2018-06-14T12:12:22-0500,1,,3,0.4,1.5,1.6,,1.8,40.0,5.4,0,wet|2018-01-30T10:26:23-0500,1.2,2.3,3,4,5,6,7,8,42.0,0.5,50,falling

指定相对时间格式

write_api_key=XXXXXXXXXXXXXXXX&time_format=relative&updates=4,1.1,2,0.3,,,6,7.7,0.8,41.2,19.5,100,ok|3,1,2,3,4,5,6,7,8,41.2,25.1,110,rising

响应

成功

HTTP 状态代码

200 OK

主体

响应是一个表示成功的 JSON 对象：

{
    "success": true
}

错误

完整列表请参阅错误代码。

限制

单次批量更新的消息数量限制为：免费帐户用户为 960 条消息，付费帐户用户为 14,400 条消息。连续批量更新调用之间的时间间隔必须为 15 秒或更长。
MQTT 订阅不会将批量写入操作的更新报告给通道。
所有更新必须使用相同的时间格式。
所有时间戳必须是唯一的。如果您提交重复的时间戳，您的所有更新都会被拒绝，否则只有通道中已有时间戳的更新才会被拒绝。

示例

全部展开

使用相对时间戳创建 POSTMAN 请求

您可以配置 POSTMAN 来尝试 RESTful API 调用。要发送 HTTP POST 请求以使用 CSV 格式的数据批量更新通道源，请配置 POSTMAN。

从 HTTP 动词下拉列表中选择 POST。
输入 URL，将 <channel_id> 更改为您的通道 ID。
https://api.thingspeak.com/channels/<channel_id>/bulk_update.csv
选择 x-www-form-urlencoded。
在 Key 部分输入 write_api_key，并在 value 部分输入您通道的写入 API 密钥。
在 Key 部分输入 time_format，在 value 部分输入 relative。
在 Key 部分输入 updates，然后输入 0,2,,,,,,,,,,,|2,2,,,,,,,,,,,|1,16,,,,,,,,,,,|2,2,,,,,,,,,,,|5,164,,,,,,,,,,,|1,22,,,,,,,,,,,|3,116,,,,,,,,,,,|
在 value 部分。每个空白条目使用逗号。
发送请求。

对请求的响应是一个表示成功的 JSON 对象。

{
    "success": true
}

图中显示了在 19:07:20 时对该通道的一次调用中发布的六个值。最后一条条目包含提交请求时的时间戳。请求中带有相对时间戳的每个更新都会从最后一个条目开始按时间向后递减。

批量写入带绝对时间戳的 CSV 值

对于具有内置实时时钟的设备，您可以为每个条目提供相对时间戳。指定 time_format=relative。每个条目以距上次测量的时间（以秒为单位）开始。

POST /channels/266256/bulk_update.csv HTTP/1.1
Host: api.thingspeak.com
Content-Type: application/x-www-form-urlencoded
time_format: relative


write_api_key=JNWIVP3CD54ZGI9X&time_format=absolute&updates=2018-01-30T10%3A26%3A2-0500%2C2%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-30+10%3A26%3A23-0500%2C2%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-31+10%3A27%3A2-0500%2C16%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-31+11%3A26%3A32-0500%2C2%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-31+11%3A27%3A22-0500%2C164%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C

该消息必须经过 URL 编码。%2C 和 %7C 分别代表“，”和“|”的 URL 编码字符。

对请求的响应是一个表示成功的 JSON 对象。