Bulk-Write JSON Data

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

描述

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

注意

请求您将 React app 设置为 Test Frequency，则将 On Data Insertion 设置为 On Data Insertion，当与 Condition 匹配，即使 Condition 匹配多次。

请求

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`	（可选）状态字段输入消息	<细绳>

内容类型

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设置为raw JSON对象，并在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 /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 对象，表示成功。