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

API 读取示例

离开

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

本指南介绍了如何从 Nest 设备和结构中读取数据。如需了解如何进行写入调用,请参阅 API 写入示例

前提条件

在进行 API 调用之前,请先获取访问令牌(如使用 OAuth 2.0 进行身份验证中所述)。

REST 读取调用简介

对于 REST 调用,请使用 GET 读取数据。

REST 读取调用非常有用,例如以下用例:

  • 临时一次性呼叫
  • 概念验证实验
  • 问题排查
  • 大约每分钟轮询一次的应用
  • “刷新”按钮实现

REST 读取调用对于持续的实时或流式场景没有用处。

不记名身份验证

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

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

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

示例

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

读取结构和设备

要读取所有结构和设备数据(基础级别),请使用根级网址。 对于更为细化的响应,请根据需要修改此网址。

卷发
curl -v --location-trusted \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -X GET "https://developer-api.nest.com/"
Curl 多路复用
curl -v --location-trusted \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer LIST_OF_ACCESS_TOKENS" \
  -X GET "https://developer-api.nest.com/multiplex"
Go
package main

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

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

func main() {
    url := "https://developer-api.nest.com/"
    req, _ := http.NewRequest(http.MethodGet, url, nil)

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

    customClient := http.Client {
        CheckRedirect: func(redirRequest *http.Request, via []*http.Request) error {
            // Go's http.DefaultClient does not forward headers when a redirect 3xx
            // response is received. Thus, the header (which in this case contains the
            // Authorization token) needs to be passed forward to the redirect
            // destinations.
            redirRequest.Header = req.Header

            // Go's http.DefaultClient allows 10 redirects before returning an
            // an error. We have mimicked this default behavior.
            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(string(body))

}
Node.js
"use strict"

var request = require('request');

var token = "YOUR_TOKEN_HERE"; // Update with your token

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

var options = {
    "method": "GET",
    "path": "/",
    "headers": {
       "Authorization": "Bearer " + token
    },
    "followRedirect": true
};

var req = request(url, options, function(err, resp, data) {
    console.log('response code: ' + resp.statusCode);
    if (err) {
        console.log('Error: ' + err.message);
    }
    console.log("data: " + data);
});

req.end();

如需使用 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/"

token = "YOUR_TOKEN_HERE" # Update with your token

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

response = requests.get(url, headers=headers, allow_redirects=False)
if response.status_code == 307:
    response = requests.get(response.headers['Location'], headers=headers, allow_redirects=False)

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

token = "YOUR_TOKEN_HERE" # Update with your token

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

if response.status == 307:
    redirectLocation = urlparse(response.getheader("location"))
    conn = http.client.HTTPSConnection(redirectLocation.netloc)
    conn.request("GET", "/", headers=headers)
    response = conn.getresponse()
    if response.status != 200:
        raise Exception("Redirect with non 200 response")

data = response.read()
print(data.decode("utf-8"))
Java
import java.io.IOException;
import okhttp3.Headers;
import okhttp3.OkHttpClient;
import okhttp3.OkHttpClient.Builder;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.Authenticator;
import okhttp3.Route;

public class ReadNest {

    public static void main(String[] args) throws IOException {
        String auth = "Bearer YOUR_TOKEN_HERE"; // Update with your token

        OkHttpClient client = new OkHttpClient.Builder()
        .authenticator(new Authenticator() {
          @Override public Request authenticate(Route route, Response response) throws IOException {
            return response.request().newBuilder()
                .header("Authorization", auth)
                .build();
          }
        })
        .followRedirects(true)
        .followSslRedirects(true)
        .build();

        Request request = new Request.Builder()
        .url("https://developer-api.nest.com")
        .get()
        .addHeader("content-type", "application/json; charset=UTF-8")
        .addHeader("authorization", auth)
        .build();

        try {
            System.out.println("Begin request:  ");
            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
            System.out.println("End request");
            System.out.println();
            Thread.sleep(2 * 1000);
        } catch (InterruptedException e) {
                e.printStackTrace();
        }
   }
}

如需使用 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 ReadNest.java
java -cp .:okhttp-<ver>.jar:okio-<ver>.jar:kotlin-stdlib-<ver>.jar ReadNest

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

使用 Postman 测试 API

上述 Curl 调用可以在 Postman 中轻松复制。

要写入的 PUT 标头

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