نمونه های نوشتن API

ترموستات

از 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))

}
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
پایتون 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)
پایتون 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"))
جاوا
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 برای ترجمه تماس به زبان های مختلف به عنوان نقطه شروع برای توسعه بیشتر استفاده کنید.