Google 致力于为黑人社区推动种族平等。查看具体举措

API 编写示例

恒温器

使用 Nest API 监听结构和设备的变化,以便在住宅不在时,采取措施节省能源,并通知他们疏漏(例如车库门是开着的):或启用其他功能,让居室更加舒适温馨。

在本指南中,您将了解如何使用 PUT 命令将数据写入 Nest 设备和结构。如需了解如何进行读取调用,请参阅 API 读取示例

查看这些代码示例,并学习如何将数据写入 Nest Learning Thermostat 和 Nest Cam。

前提条件

在进行 API 调用之前,请先获取访问令牌(请参阅使用 OAuth 2.0 进行身份验证授权代码示例)。

REST 写入调用简介

对于 REST 调用,请使用 PUT 或 PATCH 写入数据。

不记名身份验证

我们建议您遵守 OAuth 标准,该标准使用 "Bearer" 身份验证来传输访问令牌,从而提高安全性。建议不要在网址中使用客户端凭据进行调用。

"Content-Type" 标头会指示服务器使用 JSON。

"Authorization" 标头提供 API 访问权限。

示例

在以下示例中,将 YOUR_TOKEN_HERE 替换为您的特定访问令牌,例如“c.twC2q...”。

设置结构的离开状态

如需将结构体的离开状态更改为“home”,请使用以下格式写入 away 字段:"{"away": "home"}",其中“away”是字段,而“home”是新状态。

为了向结构写入数据,我们将向网址根路径添加 /structures 对象和 structure_id。请注意,字符串的格式为“引号”。

curl --location-trusted -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"away": "home"}' \
  "https://developer-api.nest.com/structures/structure_id"

更改恒温器的温度计 (C/F)

在此示例中,我们将强制温度刻度显示华氏度。在构建产品时,首先读取温度范围,然后决定是否要使用写入调用对其进行更改。

如需发出该调用,请指定您要更新的字段和值:"{"temperature_scale": "F"}",并将根路径更改为包含 /devices/thermostats 和恒温器 device_id

卷发
curl --location-trusted -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"temperature_scale": "F"}' \
  "https://developer-api.nest.com/devices/thermostats/device_id"
前往
package main

import (
    "errors"
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

const token = "YOUR_TOKEN_HERE" // Update with your token

func main() {

    url := "https://developer-api.nest.com/devices/thermostats/device_id"

    payload := strings.NewReader("{\"temperature_scale\": \"F\"}")

    req, _ := http.NewRequest("PUT", url, payload)

    req.Header.Add(
        "Authorization",
        fmt.Sprintf("Bearer %s", token),
    )

    customClient := http.Client{
        CheckRedirect: func(redirRequest *http.Request, via []*http.Request) error {
            redirRequest.Header = req.Header
            if len(via) >= 10 {
                return errors.New("stopped after 10 redirects")
            }
            return nil
        },
    }


    response, _ := customClient.Do(req)

    if response.StatusCode != 200 {
        panic(fmt.Sprintf(
            "Expected a 200 status code; got a %d",
            response.StatusCode,
        ))
    }

    defer response.Body.Close()
    body, _ := ioutil.ReadAll(response.Body)
    fmt.Println(response)
    fmt.Println(string(body))

}
Node.js
"use strict"

const request = require('request');

const url = "https://developer-api.nest.com";

/* Update with your token and thermostat device ID below */
var path = "/devices/thermostats/device_id";
var token = "YOUR_TOKEN_HERE";

var options = {
    "method": "PUT",
    "url": url + path,
    "body": JSON.stringify({"temperature_scale": "F"}),
    "headers": {
        "Authorization": "Bearer " + token,
        "Content-Type": "application/json"
    },
    "followRedirect": true,
    "removeRefererHeader": false
};

request(options, function(err, resp, data) {
    if (resp.statusCode == 307) { // indicates a redirect is needed
        options.url = resp.headers.location;
        request(options, function(err, resp, data) {
            console.log('response code: ' + resp.statusCode);
            if (err) console.log('Error: ' + err.message);
            console.log("data: " + data);
        });
    }
});

如需使用 Node.js 代码示例,请安装请求模块 (https://www.npmjs.com/package/request)。

npm install request
Python 2
import hashlib
import json
import os
import requests

url = "https://developer-api.nest.com/devices/thermostats/device_id"

token = "YOUR_TOKEN_HERE" # Update with your token

payload = "{\"temperature_scale\": \"F\"}"

headers = {'Authorization': 'Bearer {0}'.format(token), 'Content-Type': 'application/json'}

response = requests.put(url, headers=headers, data=payload, allow_redirects=False)
if response.status_code == 307: # indicates a redirect is needed
    response = requests.put(response.headers['Location'], headers=headers, data=payload, allow_redirects=False)

print(response.text)
Python 3
import http.client
from urllib.parse import urlparse

token = "YOUR_TOKEN_HERE" # Update with your token

payload = "{\"temperature_scale\": \"F\"}"

url = "/devices/thermostats/device_id"

conn = http.client.HTTPSConnection("developer-api.nest.com")
headers = {'authorization': "Bearer {0}".format(token)}
conn.request("PUT", url, payload, headers)
response = conn.getresponse()

if response.status == 307: # indicates a redirect is needed
    redirectLocation = urlparse(response.getheader("location"))
    conn = http.client.HTTPSConnection(redirectLocation.netloc)
    conn.request("PUT", url, payload, headers)
    response = conn.getresponse()
    if response.status != 200:
        raise Exception("Response failed: ", response.reason)

data = response.read()
print(data.decode("utf-8"))
Java
import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.MediaType;
import okhttp3.RequestBody;

public class NestWrite {

    public Request makeRequest(String url, String value) {
        MediaType mediaType = MediaType.parse("application/octet-stream");
        RequestBody body = RequestBody.create(mediaType, "{\"temperature_scale\": \"F\"}\"");
        String auth = "Bearer YOUR_TOKEN_HERE"; // Update with your token
        Request request = new Request.Builder()
        .url(url)
        .put(body)
        .addHeader("authorization", auth)
        .build();
        return request;
    }

    public static void main(String[] args) throws IOException
    {
        OkHttpClient client = new OkHttpClient();
        NestWrite postman = new NestWrite();

        String url = "https://developer-api.nest.com/devices/thermostats/device_id";
        String value = "{\"away\": \"home\"}";
        Request request = postman.makeRequest(url, value);
        Response response = client.newCall(request).execute();
        //System.out.println(response.toString());

        // Use the new URL in case of temporary redirect
        if(response.isRedirect()){
            String newUrl = response.header("Location");
            request = postman.makeRequest(newUrl, value);
            response = client.newCall(request).execute();
        }
        System.out.println(response.body().string());
    }
}

如需使用 Java 代码示例,请执行以下操作:

1. 访问 http://square.github.io/okhttp/,下载最新的 okhttp 和 okio Jar 文件。此外,如果您的 okhttp 版本依赖于 Kotlin stdlib 文件,请访问 https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-stdlib

2. 构建代码。

3. 使用以下类路径设置编译并运行程序。

javac 和 java 命令中的库版本号替换为:
javac -cp .:okhttp-<ver>.jar:okio-<ver>.jar NestWrite.java
java -cp .:okhttp-<ver>.jar:okio-<ver>.jar:kotlin-stdlib-<ver>.jar NestWrite

例如,如果您具有以下版本 3.11: .0、2.1.0 和 1.3.0,您的命令将如下所示:
javac -cp .:okhttp-3.11.0.jar:okio-2.1.0.jar NestWrite.java
java -cp .:okhttp-3.11.0.jar:okio-2.1.0.jar:kotlin-stdlib-1.3.0.jar NestWrite

调节温控器的目标温度

将温度尺度更改为华氏度,可以设置目标温度。使用与上述示例相同的过程,指定要更新的字段/值,以及更改根路径。请注意,"strings"numbers 的格式有所不同。

curl --location-trusted -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"target_temperature_f": 70}' \
  "https://developer-api.nest.com/devices/thermostats/device_id"

在恒温器上设置自定义标签

您还可以更改 thermostat 标签,为其指定一个自定义的昵称。要在名称中包含单引号,可以使用 Unicode 字符 \u0027。

curl --location-trusted -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"label": "Kate\u0027s Room"}' \
  "https://developer-api.nest.com/devices/thermostats/device_id"

在摄像头上设置流式传输状态

在此示例中,我们更改根路径以反映您要修改的设备 /devices/cameras/device_id,并将相机流式传输状态设置为 ON

curl --location-trusted -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"is_streaming": true}' \
  "https://developer-api.nest.com/devices/cameras/device_id"

使用 Postman 测试 API

上述 Curl 调用可以在 Postman 中轻松复制。 以下步骤会更改恒温器上的目标温度,如上面的 Curl 示例

要写入的 PUT 标头
PUT 正文写入

在后续开发工作中,您可以使用 Postman 中的 Code 链接将调用翻译为不同的语言。