Bulk-Write JSON Data

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

描述

为了节省设备电量或组通道更新，您可以使用批量更新 API。使用批量更新 API 时，您会随着时间的推移收集数据，然后将数据上传到 ThingSpeak™。要以 CSV 格式写入数据，请参阅 Bulk-Write CSV 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.json

URL 参数

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

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

正文参数和对象成员

批量 JSON 写入操作的正文是一个 JSON 对象，其成员和数组列在这些表中。

名称	描述	值类型
`write_api_key`	（私有通道必需）指定此特定通道的写入 API 密钥。您可以在通道视图的 API Keys 选项卡上找到写入 API 密钥。	字符串
`updates`	（必需）指定您的通道的更新数组。	JSON 对象数组，其成员如更新所示

更新

更新是 JSON 对象的 JSON 数组，每个对象均具有以下键值对。

名称	描述	值类型
`created_at`	（除非包含 `delta_t`，否则必填）事件的绝对时间，采用 ISO 8601、EPOCH 或 MYSQL 格式。时间戳在通道内必须是唯一的。	字符串
`delta_t`	（除非包含 `created_at`，否则必填）使用 `delta_t` 指定自上次输入以来经过的秒数。除了数组中的第一个值之外，`delta_t` 的值不能为零。	字符串
`field<X>`	（可选）字段 X 数据，其中 X 是字段 ID	任何值
`latitude`	（可选）纬度（以度为单位），指定为 `-90` 和 `90` 之间的值。	数值
`longitude`	（可选）经度（以度为单位），指定为 `-180` 和 `180` 之间的值。	数值
`elevation`	（可选）海拔（以米为单位）	字符串
`status`	（可选）状态字段输入的消息	字符串

Content-Type

application/json

主体格式

{
	"write_api_key": "WRITE_API_KEY",
	"updates": [{
			"created_at": "DATETIME_STAMP",
			"field1": FIELD1_VALUE,
			"field2": FIELD2_VALUE,
			"field3": FIELD3_VALUE,
			"field4": FIELD4_VALUE,
			"field5": FIELD5_VALUE,
			"field6": FIELD6_VALUE,
			"field7": FIELD7_VALUE,
			"field8": FIELD8_VALUE,
			"Latitude": LATITUDE_VALUE,
			"Longitude": LONGITUDE_VALUE,
			"Elevation": ELEVATION_VALUE,
			"Status": "STATUS_STRING"
		},
		{
			"created_at": "DATETIME_STAMP",
			"field1": "FIELD1_VALUE",
			Etc...
		}
	]
}

指定时间格式 created_at

{
	"write_api_key": "WRITE_API_KEY",
	"updates": [{
			"created_at": "2018-01-30 10:26:2 -0500",
			"field1": "1.0",
			"field2": "2.0"
		},
		{
			"created_at": "2018-02-02 11:27:27 -0500",
			"field1": "1.1",
			"field2": "2.2",
			"status": "well done"
		}
	]
}

指定时间格式 delta_t

{
	"write_api_key": "WRITE_API_KEY",
	"updates": [{
			"delta_t": 4,
			"field1": 1.0,
			"field2": "2.0"
		},
		{
			"delta_t": 2,
			"field1": 1.1,
			"field2": 2.2,
			"elevation": 6,
			"status": "Good"
		}
	]
}

响应

成功

HTTP 状态代码

200 OK

主体

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

{
    "success": true
}

错误

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

限制

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

示例

全部展开

使用绝对时间戳创建批量写入 POSTMAN 请求

您可以配置 POSTMAN 来尝试 RESTful API 调用。要使用 JSON 对象发送 HTTP POST 请求以批量更新通道源，请按如下所示配置 POSTMAN：

在 Headers 选项卡中，将 Content-Type 设置为 application/json。

将请求的 Body 设置为 rawJSON 对象，并在 POSTMAN 中输入该 JSON 对象。

完整 POST 的格式如下所示。

POST /channels/999900/bulk_update.json HTTP/1.1
Host: api.thingspeak.com
Content-Type: application/json
{
	"write_api_key": "JNWIVP3CD54ZGI9X",
	"updates": [{
			"created_at": "2018-01-30 10:26:2 -0500",
			"field1": 100
		},
		{
			"created_at": "2017-01-30 10:26:23 -0500",
			"field1": "red",
			"field2": "blue",
			"field3": "green",
			"field4": "fish",
			"field5": "alimony",
			"field6": 100,
			"field7": 100,
			"field8": 100,
			"status": "good"
		},
		{
			"created_at": "2018-01-30 10:26:26 -0500",
			"field1": 1500,
			"field2": 150,
			"field3": 100,
			"field4": 100,
			"field5": 100,
			"field6": 100,
			"field7": 100,
			"field8": 100,
			"latitude": 123,
			"longitude": 23,
			"elevation": 34
		}
	]
}

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

使用相对时间戳进行批量写入

对于没有内置实时时钟的设备，您可以为每个条目提供相对时间戳。每个条目以 delta_t 开头，并列出距离上次测量的时间（以秒为单位）。

输入 POST 代码。具体流程和格式取决于您的客户。

POST /channels/999900/bulk_update.json HTTP/1.1
Host: api.thingspeak.com
Content-Type: application/json
{
	"write_api_key": "XXXXXXXXXXXXXXXX",
	"updates": [{
			"delta_t": "0",
			"field1": 100
		},
		{
			"delta_t": "2",
			"field1": "200"
		},
		{
			"delta_t": "1",
			"field1": 103
		},
		{
			"delta_t": "2",
			"field1": "23"
		},
		{
			"delta_t": "1",
			"field1": 86
		},
		{
			"delta_t": "5",
			"field1": "201"
		}
	]
}

最后一条条目包含提交请求时的时间戳。请求中带有相对时间戳的每个更新都会从最后一个条目开始按时间向后递减。对请求的响应是一个表示成功的 JSON 对象。