
در Nest API، مفهوم «خانه» یا «دور» تأثیر قدرتمندی بر رفتارهای صرفهجویی در انرژی و ویژگیهای راحتی Nest دارد.
خانه و دور چگونه کار می کند
Nest از سیگنالهای مختلفی برای تشخیص حضور انسان در خانه استفاده میکند. اگر Nest برای مدت طولانی عدم حضور را تشخیص دهد، خانه را بهطور خودکار روی «خارج» تنظیم میکند. وقتی حضور انسان را تشخیص داد، ساختار را به حالت Home برمیگرداند.
واکنش به تغییرات در وضعیت خانه/خارج از خانه طیف وسیعی از فرصتها را برای محصولات شما باز میکند. به عنوان مثال، محصولات شما می توانند:
- برای صرفه جویی در مصرف انرژی، وقتی خانه به خانه رفت، چراغ ها را خاموش کنید
- در صورت باز بودن درب گاراژ زمانی که خانه خارج است، اعلان ارسال کنید
- وقتی خانه به صفحه اصلی تغییر می کند، موسیقی پخش کنید
نحوه کار ETA
در برخی موارد، کاربران یک برنامه شخص ثالث دارند که از GPS برای ارائه داده های تخمینی زمان رسیدن (ETA) به Nest API استفاده می کند. در موارد دیگر، کاربر ممکن است از یک برنامه برای وارد کردن دستی ETA خود استفاده کند. یا شاید ETA بر اساس برنامه منظم کاربر محاسبه می شود.
برنامههای ETA که با Nest Thermostat یکپارچه شدهاند باعث میشوند که ترموستات قبل از ورود کاربر شروع به گرم کردن یا خنک کردن خانه کند.
وقتی ادغام ETA/ترموستات در حساب کاربر وجود دارد، داده های ETA برای سایر توسعه دهندگان Works with Nest در دسترس است تا در ادغام های Works with Nest خود از آن استفاده کنند.
پس از ورود ETA به سرویس Nest، ادغام Works with Nest دیگری می تواند از آن به عنوان سیگنالی برای آماده کردن خانه برای ورود کاربر استفاده کند.
- ETA توسط یک توسعه دهنده Nest با استفاده از تماس
PUT eta
و API فقط نوشتنی نوشته شده است. - Nest Thermostat از این داده ها استفاده می کند.
- اگر توسعهدهندگان دیگر نیز بخواهند از آن استفاده کنند، میتوانند از تماس API فقط
GET eta_begin
استفاده کنند .

نکته مهمی که باید در نظر داشت این است که داده های ETA باید توسط شخص ثالث وارد شود. Nest در حال حاضر داده های ETA را ارائه نمی دهد. اگر دادههای ETA نوشته نشده باشند، Nest API مقدار پیشفرض «1970-01-01T00:00:00.000Z» را برمیگرداند.
برای مثال فرض کنید که شما یک فروشنده روشنایی هستید. می توانید داده های ETA ارائه شده توسط ادغام ETA/ترموستات را دریافت کرده و از آن به عنوان سیگنال برای روشن کردن چراغ ها استفاده کنید.
به این ترتیب، نه تنها دما راحت است، بلکه هنگام ورود کاربر به خانه، چراغ ها نیز روشن می شوند.
واکنش به تغییرات در وضعیت ETA طیف گسترده ای از فرصت ها را برای محصولات شما باز می کند. به عنوان مثال، محصولات شما می توانند:
- وقتی کاربر به خانه نزدیک می شود، تلویزیون را روشن کنید
- زمانی که کاربر تقریباً در خانه است، درب گاراژ را باز کنید
- وقتی کاربر به خانه برمی گردد، از قبل موسیقی پخش شده باشد
مجوزهای دور
سطوح مجوز دسترسی زیر برای مقادیر داده مربوط به Away موجود است:
دسترسی داشته باشید | دور بخوانید دور خواندن/نوشتن | ETA خوانده شود | خواندن/نوشتن ETA | هشدار دود + CO خوانده شد | ترموستات خوانده شد خواندن/نوشتن ترموستات |
---|---|---|---|---|---|
away | آره | آره | آره | ||
eta_begin (فقط خواندنی) | آره | آره | |||
شی eta (فقط نوشتن) | آره |
برای اطلاعات بیشتر، به نمای کلی مجوزها مراجعه کنید.
ویژگی های دور
خانه و دور
مقدار داده away
میتواند به شما بگوید که آیا Nest فکر میکند ساختار اشغال شده است یا خیر. مقادیر ممکن عبارتند از:
مقدار | شرح |
---|---|
home | یک نفر در ساختار وجود دارد. این حالت را می توان تنظیم کرد: • توسط Nest اگر از دادههای حسگر حرکت اطمینان بالایی دارد • توسط کاربر از طریق برنامه Nest ، ترموستات Nest یا محصول شما • الگوریتمی از طریق ETA |
away | هیچ کس در ساختار وجود ندارد. کاربر صراحتاً از طریق برنامه Nest ، Nest Thermostat یا محصول شما، ساختار را روی دور تنظیم کرده است. |
unknown | اگر هیچ دستگاهی با ساختار مرتبط نباشد، وضعیت دور unknown . |
Nest API امکان تنظیم مستقیم خانه و خارج از خانه و همچنین گوش دادن به تغییرات این حالت ها را فراهم می کند. با این حال، هنگام تنظیم خانه و خارج از خانه، باید همانطور که برنامه Nest این کار را انجام می دهد انجام شود: در نتیجه درخواست صریح کاربر. تلاش برای تنظیم الگوریتمی این حالت خطر ایجاد یک تجربه کاربر گیج کننده را دارد و توسط خط مشی های طراحی Nest ممنوع است.
توجه داشته باشید که کاربران همیشه این امکان را دارند که حالت خانه/خارج از خانه را به صورت دستی تنظیم کنند.
درباره نحوه تنظیم وضعیت خانه و خارج از خانه توسط کاربران بیشتر بیاموزید.
ETA

ETA یک شی با فیلدهایی است که می توان روی یک ساختار تنظیم کرد. از آن برای اطلاع دادن به Nest استفاده می شود که انتظار می رود کاربر در یک زمان خاص به خانه بازگردد. هنگام تنظیم ETA، یک محصول یک trip_id
منحصربهفرد ایجاد میکند و یک پنجره ورود مورد انتظار را ارائه میکند که با مقادیر زیر مشخص میشود:
-
estimated_arrival_window_begin
-
estimated_arrival_window_end
از آنجایی که شرایط اطراف سفرها میتواند به دلیل ترافیک، برنامههای کاربر تغییر یافته و سایر رویدادها تغییر کند، محصولات باید بهطور دورهای ETA را با پیشرفت سفر بهروزرسانی کنند و جریانی از زمانهای تخمینی رسیدن به Nest را ارائه کنند (5 دقیقه فاصله زمانی ایدهآل است).
هرچه اطلاعات بیشتری دریافت کنیم، می توانیم به قابلیت اطمینان ورودی های ETA اطمینان بیشتری داشته باشیم، که باعث می شود هنگام اقدام برای آماده سازی خانه، اطمینان بیشتری داشته باشیم.
ETA مستقل از کشور اصلی است. اگر زمان رسیدن یک ETA با یک ETA دیگر در تضاد باشد، زودترین زمان ورود اولویت دارد.
یک تماس نوشتن ETA برقرار کنید
منطق ETA به وجود ترموستات در ساختار بستگی دارد. اگر هیچ ترموستاتی در ساختار وجود نداشته باشد، تماسهای برقرار شده با شی ETA با پیام خطای «دستگاههای جفتشده وجود ندارد» با شکست مواجه میشوند. این خطا حتی اگر انواع دیگری از دستگاهها در ساختار وجود داشته باشند (به عنوان مثال، Nest Cam یا Nest Protect) رخ میدهد.
مقادیر داده ها
یک تماس ETA به مقادیر داده زیر نیاز دارد:
نام | تایپ کنید | شرح |
---|---|---|
trip_id | رشته | شناسه منحصر به فرد سفر ETA |
estimated_arrival_window_begin | رشته | مهر زمان باید بزرگتر از NOW در قالب ISO 8601 باشد |
estimated_arrival_window_end | رشته | مهر زمان در قالب ISO 8601 باید بیشتر از estimated_arrival_window_begin زده_arrival_window_begin باشد |
به دلیل احتمال قطع اتصال در ارتباطات GPS، ما یک جریان نمونه را پیشنهاد می کنیم، در حالت ایده آل هر 5 دقیقه یک بار.
هر تماس ETA باید شامل یک رشته trip_id
منحصر به فرد باشد که در تماس اولیه تعریف می کنید. سایر پارامترها می توانند با تماس های متوالی به همان trip_id
کنند.
یک تماس ETA در صورت موفقیت یک کد وضعیت HTTP 200 OK را برمی گرداند.
مثال ها
curl --location-trusted -X PUT -d \ '{"trip_id":"sample-trip-id","estimated_arrival_window_begin":"2014-10-31T22:42:00.000Z","estimated_arrival_window_end":"2014-10-31T23:59:59.000Z"}' \ "http://developer-api.nest.com/structures/5af48890-b516-11e3-9eff-123139166438/eta.json?auth=c.VG6bfzyOxAltaih6P4v..."
لغو ETA
برای لغو یک eta، estimated_arrival_window_begin = 0
را ارسال کنید. بررسی کنید که در این تماس یک عدد صحیح (0) ارسال می کنید، نه رشته ("0")، در غیر این صورت تماس ناموفق خواهد بود.
پیغام خطا
برای اطلاعات در مورد اینکه خطاهای فراخوانی API به چه معنا هستند و نحوه رسیدگی به آنها، به پیام های خطا مراجعه کنید.