
از Nest API برای گوش دادن به تغییرات در ساختارها و دستگاهها استفاده کنید، بنابراین میتوانید برای صرفهجویی در مصرف انرژی در زمانی که مالکان خانه نیستند، به آنها اطلاع دهید که مشکلی وجود ندارد (مثلاً درب گاراژ باز است) یا ویژگیهایی را فعال کنید تا خانه راحت تر و دلپذیرتر
در این راهنما، نحوه استفاده از دستور PUT را برای نوشتن داده در دستگاهها و ساختارهای Nest خواهید آموخت. برای یادگیری نحوه برقراری تماسهای خواندنی، به نمونههای خواندن API مراجعه کنید.
این نمونههای کد را بررسی کنید و یاد بگیرید که دادهها را در ترموستات یادگیری Nest و Nest Cam بنویسید.
پیش نیازها
قبل از برقراری تماسهای API، یک نشانه دسترسی، همانطور که در احراز هویت با OAuth 2.0 و کد نمونه برای مجوز شرح داده شده است، دریافت کنید.
درباره REST تماسها را بنویسید
برای تماس های REST، از PUT یا PATCH برای نوشتن داده استفاده کنید.
احراز هویت حامل
ما رعایت استاندارد OAuth را توصیه می کنیم که با استفاده از احراز هویت "Bearer"
برای انتقال رمز دسترسی، امنیت بیشتری را ارائه می دهد. تماس با اعتبار مشتری در URL توصیه نمی شود.
هدر "Content-Type"
سرور را به استفاده از JSON هدایت می کند.
هدر "Authorization"
دسترسی API را فراهم می کند.
مثال ها
در مثالهای زیر، YOUR_TOKEN_HERE
را با نشانه دسترسی خاص خود، مانند "c.twC2q..." جایگزین کنید.
حالت دور را برای یک ساختار تنظیم کنید
برای تغییر حالت دور یک ساختار به "home"، فیلد away
را با استفاده از این قالب بنویسید: "{"away": "home"}"
، جایی که "away" نام فیلد است و "home" دولت جدید
برای نوشتن در یک ساختار، شی /structures
و structure_id
را به مسیر ریشه URL اضافه می کنیم. توجه داشته باشید که رشته ها با "علامت نقل قول" قالب بندی شده اند.
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
و thermostat 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); }); } });
برای استفاده از مثال کد Node.js، ماژول درخواست ( 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()); } }
برای استفاده از کد جاوا به عنوان مثال:
1. آخرین فایل های okhttp و okio Jar را در http://square.github.io/okhttp/ دانلود کنید. علاوه بر این، اگر نسخه 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"
یک برچسب سفارشی روی ترموستات تنظیم کنید
همچنین می توانید برچسب ترموستات را تغییر دهید تا یک نام مستعار سفارشی به آن بدهید. برای درج یک نقل قول در نام، می توانید از کاراکتر یونیکد استفاده کنید.
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 بالا تغییر می دهد.


از پیوند Code در Postman برای ترجمه تماس به زبان های مختلف به عنوان نقطه شروع برای توسعه بیشتر استفاده کنید.