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 匹配，即使 Condition 匹配多次。

请求

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

内容类型

application/x-www-form-urlencoded

主体参数

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

更新参数

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

名称	描述	值类型
时间戳	（必需）如果 `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 调用。要使用 CSV 格式的数据发送 HTTP POST请求以批量更新通道源，请配置 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 对象，表示成功。