Write Data and Execute TalkBack Command

使用 HTTP GET 或 POST 更新通道数据并执行 TalkBack 命令

请求

HTTP 方法

POST 或 GET

URL

https://api.thingspeak.com/update.<format>

URL 参数

名称	描述
`<format>`	HTTP 响应的格式，指定为 `json` 或 `xml`。

示例： https://api.thingspeak.com/update.json?api_key=XXXXXXXXXXXXXXXXtalkback_key=YYYYYYYYYYYYYYYY

主体

名称	描述	值类型
`api_key`	（必填）为该特定通道指定写入 API 密钥。您还可以使用 THINGSPEAKAPIKEY HTTP 头文件发送写入 API 密钥。写入 API 密钥位于通道视图的 API Keys 选项卡上。	字符串
`talkback_key`	（必需）TalkBack 特定实例的 API 密钥。包含 TalkBack API 密钥会导致队列中的下一个命令被删除并在响应中返回该命令。	字符串
`field<X>`	（可选）字段 X 数据，其中 X 是字段 ID	任何值
`lat`	（可选）纬度（度）	小数
`long`	（可选）经度（度）	小数
`elevation`	（可选）海拔（以米为单位）	整数
`status`	（可选）状态更新消息	字符串
`created_at`	（可选）创建源条目的日期，采用 ISO 8601 格式，例如 `2014-12-31 23:59:59`。在通道内必须是唯一的。可以使用 timezone 参数指定时区。	日期时间

Content-Type

Content-Type 仅对于 POST 方法来说是必需的，对于 GET 方法来说则不需要。

使用 application/json 进行 JSON 格式的更新。

使用 application/x-www-form-urlencoded 进行所有其他更新。

响应

成功

HTTP 状态代码

200 OK

正文

文本示例

POST https://api.thingspeak.com/update
     api_key=XXXXXXXXXXXXXXXX
     field1=73
     talkback_key=YYYYYYYYYYYYYYYY

响应

响应是具有指定 TalkBack API 密钥的 TalkBack 队列中的下一个 TalkBack 命令的命令字符串。

如果更新失败，响应为 0。

JSON 示例

POST https://api.thingspeak.com/update.json
     api_key=XXXXXXXXXXXXXXXX
     field1=73
     talkback_key=YYYYYYYYYYYYYYYY

响应是具有指定 TalkBack API 密钥的 TalkBack 队列中的下一个命令的 JSON 对象，例如：

{
"id": 15254213,
"command_string": "OPENDOOR",
"position": null,
"executed_at": "2019-03-05T15:48:29Z",
"created_at": "2019-02-26T13:45:09Z"
}

XML 示例

POST https://api.thingspeak.com/update.xml
     api_key=XXXXXXXXXXXXXXXX
     field1=73
     talkback_key=YYYYYYYYYYYYYYYY

响应是具有指定 TalkBack API 密钥的 TalkBack 队列中的下一个命令的 XML 对象，例如：

<command>
<id type="integer">15338752</id>
<command-string>OPENDOOR</command-string>
<position type="integer" nil="true"/>
<executed-at type="dateTime">2019-03-05T15:52:08Z</executed-at>
<created-at type="dateTime">2019-03-05T15:51:54Z</created-at>
</command>

错误

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

示例

全部展开

使用 POSTMAN 添加 TalkBack 命令

您可以使用 POSTMAN 尝试使用 ThingSpeak 的 RESTful API 发出 HTTP 请求。此示例显示如何使用 POSTMAN 同时更新通道并从现有队列执行 TalkBack 命令。

将 123 写入通道的字段 1，并返回现有 TalkBack 队列中的下一个 TalkBack 命令。

POST https://api.thingspeak.com/update
     api_key=XXXXXXXXXXXXXXXX
     talkback_key=YYYYYYYYYYYYYYYYY

在 POSTMAN 中，从 HTTP 动词下拉列表中选择 POST，然后在地址栏中输入 https://api.thingspeak.com/update。
输入附加参数和值：
- Key: api_key，Value: XXXXXXXXXXXXXXXX
- Key: talkback_key，Value: YYYYYYYYYYYYYYYY

响应为文本格式。注意服务器响应值为 200 OK，这表示通道更新和 TalkBack 命令执行成功。

执行的命令显示在响应中。

限制

所有时间戳必须是唯一的。您不能使用与通道中现有数据匹配的时间戳写入新数据。

另请参阅