
Use a API Nest para detectar mudanças em estruturas e dispositivos e tomar medidas para economizar energia quando os proprietários estiverem ausentes. Além disso, use a API para avisar que algo está errado (por exemplo, a porta da garagem está aberta) ou ative recursos para tornar a casa mais confortável e acolhedora.
Neste guia, você aprenderá a usar o comando PUT para gravar dados em dispositivos e estruturas Nest. Para saber como fazer chamadas de leitura, consulte Exemplos de leitura de API.
Confira estes exemplos de código e saiba como gravar dados no Nest Learning Thermostat e na Nest Cam.
Prerequisites
Antes de fazer chamadas de API, receba um token de acesso conforme descrito em Como autenticar com o OAuth 2.0 e em Exemplo de código para autorização.
Sobre as chamadas de gravação REST
Para chamadas REST, use PUT ou PATCH para gravar dados.
Autenticação do portador
Recomendamos o cumprimento do padrão OAuth, que oferece maior segurança usando a autenticação "Bearer"
para transmitir o token de acesso. As chamadas com credenciais de cliente no URL não são recomendadas.
O cabeçalho "Content-Type"
direciona o servidor para usar JSON.
O cabeçalho "Authorization"
fornece acesso à API.
Examples
Nos exemplos a seguir, substitua YOUR_TOKEN_HERE
pelo token de acesso específico, como "c.twC2q...".
Definir o estado ausente de uma estrutura
Para mudar o estado ausente de uma estrutura para
"quot;home"", escreva o campo away
usando este formato: "{"away": "home"}"
, em que
"quot;away" é o nome do campo e "quot;home"quot; é o novo estado.
Para gravar em uma estrutura, adicionaremos o objeto /structures
e
structure_id
ao caminho raiz do URL. As strings são formatadas com "aspas".
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"
Mudar a escala de temperatura (C/F) de um termostato
Neste exemplo, forçaremos a escala de temperatura para exibir graus Fahrenheit. Quando estiver criando seu produto, primeiro leia a escala de temperatura e, depois, decida se você quer alterá-lo com uma chamada de gravação.
Para fazer a chamada, especifique o campo e o valor que você quer atualizar:
"{"temperature_scale": "F"}"
e mude o caminho raiz para incluir
/devices/thermostats
e o termostato 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)) }
"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); }); } });
Para usar o exemplo de código do Node.js, instale o módulo de solicitação (https://www.npmjs.com/package/request).
npm install request
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)
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"))
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()); } }
Para usar o exemplo de código Java:
1. Faça o download dos arquivos okhttp e okio Jar mais recentes em http://square.github.io/okhttp/. Além disso, faça o download do arquivo stdlib do Kotlin em https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-stdlib (link em inglês), se a versão do okhttp depender dele.
2. Compile seu código.
3. Compile e execute o programa com as configurações de caminho de classe a seguir.
Substitua os números da versão da sua biblioteca nos comandos javac e java abaixo:
javac -cp .:okhttp-<ver>.jar:okio-<ver>.jar NestWrite.java
java -cp .:okhttp-<ver>.jar:okio-<ver>.jar:kotlin-stdlib-<ver>.jar NestWrite
Por exemplo, se você tiver as versões 3.11.0, 2.1.0 e 1.3.0, seus comandos ficariam assim:
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
Mudar a temperatura-alvo de um termostato
Depois de mudar a escala de temperatura para graus Fahrenheit, defina a temperatura desejada.
Use o mesmo processo dos exemplos anteriores, especifique o campo/valor a ser atualizado e altere o caminho raiz. Observe que "strings"
e numbers
são
formatados de forma diferente.
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"
Definir um rótulo personalizado em um termostato
Também é possível alterar o rótulo de termostato para dar a ele um apelido personalizado. Para incluir aspas simples no nome, use o caractere 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"
Definir o status de streaming em uma câmera
Neste exemplo, mudamos o caminho raiz para refletir o dispositivo que você quer
modificar, /devices/cameras/device_id
, e definimos o
estado de streaming da câmera como 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"
Como usar o Postman para testar a API
As chamadas Curl acima podem ser facilmente replicadas no Postman. As etapas abaixo alteram a temperatura-alvo em um termostato, como no exemplo do Curl acima.


Use o link Código no Postman para traduzir uma chamada para diferentes idiomas como ponto de partida.