Ejemplos de escritura de API

Termostato

Usa la API de Nest para detectar cambios en estructuras y dispositivos, de modo que puedas tomar medidas para conservar energía cuando los propietarios no estén, notificarles que algo no funciona (por ejemplo, si la puerta de la cochera está abierta) o activar funciones a fin de hacer que la casa sea más cómoda y acogedora.

En esta guía, aprenderás a usar el comando PUT para escribir datos en estructuras y dispositivos Nest. Para obtener información sobre cómo realizar llamadas de lectura, consulta Ejemplos de lectura de API.

Consulta estas muestras de código y aprende a escribir datos en el Nest Learning Thermostat y la Nest Cam.

Requisitos previos

Antes de realizar llamadas a la API, obtén un token de acceso, como se describe en Autentica con OAuth 2.0 y el Código de muestra para autorización.

Acerca de las llamadas de escritura en REST

Para las llamadas de REST, usa PUT o PATCH para escribir datos.

Autenticación del portador

Recomendamos el cumplimiento del estándar OAuth, que ofrece mayor seguridad mediante la autenticación "Bearer" para transmitir el token de acceso. No se recomienda realizar llamadas con credenciales de cliente en la URL.

El encabezado "Content-Type" indica al servidor que use JSON.

El encabezado "Authorization" proporciona acceso a la API.

Examples

En los siguientes ejemplos, reemplaza YOUR_TOKEN_HERE por tu token de acceso específico, como "c.twC2q..."

Cómo establecer el estado "Ausente" en una estructura

Para cambiar el estado ausente de una estructura a "home", escribe el campo away con este formato: "{"away": "home"}", donde "Ausente" es el nombre del campo y "home" es el estado nuevo.

Para escribir en una estructura, agregaremos el objeto /structures y structure_id a la ruta raíz de la URL. Ten en cuenta que las strings tienen el formato de comillas "

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"

Cambiar la escala de temperatura (C/F) de un termostato

En este ejemplo, forzaremos la escala de temperatura a mostrar grados Fahrenheit. Cuando compilas tu producto, primero debes leer la escala de temperatura y, luego, decidir si deseas cambiarlo con una llamada de escritura.

Para hacer la llamada, especifica el campo y el valor que deseas actualizar: "{"temperature_scale": "F"}", y cambia la ruta raíz para incluir /devices/thermostats y el termostato device_id.

Curl
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"
Ir
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);
        });
    }
});

Para usar el ejemplo de código de Node.js, instala el módulo de solicitud (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());
    }
}

Para usar el ejemplo de código Java, haz lo siguiente:

1. Descarga los archivos okhttp y okio Jar más recientes en http://square.github.io/okhttp/. Además, descarga el archivo stdlib de Kotlin en https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-stdlib si tu versión de okhttp depende de él.

2. Construye tu código.

3. Compila y ejecuta el programa con la siguiente configuración de ruta de clase.

Sustituye los números de versión de tu biblioteca en los comandos javac y java que se indican a continuación:
javac -cp .:okhttp-<ver>.jar:okio-<ver>.jar NestWrite.java
java -cp .:okhttp-<ver>.jar:okio-<ver>.jar:kotlin-stdlib-<ver>.jar NestWrite

Por ejemplo, si tienes las siguientes versiones 3.11.0, 2.1.0 y 1.3.0, tus comandos se verán de la siguiente manera:
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

Cómo cambiar la temperatura final de un termostato

Después de cambiar la escala de temperatura a grados Fahrenheit, puedes establecer la temperatura objetivo. Usa el mismo proceso que en los ejemplos anteriores, especifica el campo o valor que quieres actualizar y cambia la ruta raíz. Ten en cuenta que "strings" y numbers tienen un formato 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"

Configura una etiqueta personalizada en un termostato

También puedes cambiar la etiqueta de termostato para asignarle un sobrenombre personalizado. Para incluir una comilla simple en el nombre, puedes usar el carácter 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"

Configura el estado de transmisión en una cámara

En este ejemplo, cambiamos la ruta de acceso raíz para reflejar el dispositivo que deseas modificar, /devices/cameras/device_id, y configuramos el estado de transmisión de la cámara en 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"

Cómo usar Postman para probar la API

Las llamadas a Curl anteriores se pueden replicar fácilmente en Postman. En los siguientes pasos, se cambia la temperatura final en un termostato, como en el ejemplo de Curl anterior.

Encabezado PUT para escribir
Cuerpo PUT para escribir

Usa el vínculo Code en Postman para traducir una llamada a diferentes idiomas como punto de partida a fin de continuar con el desarrollo.