action.devices.SYNC
הכוונה הזו מבקשת את רשימת המכשירים שמשויכים למשתמש שצוין ואת היכולות שלהם.
היא מופעלת במהלך קישור החשבון או כשמשתמש מסנכרן מחדש את המכשירים שלו באופן ידני. ההשלמה צריכה להגיב עם מאפיינים וסוגי traits נתמכים לכל מכשיר.
התשובה של SYNC
צריכה להחזיר את כל המכשירים שמשויכים למשתמש.
ההגדרה הזו לא קובעת אם אפשר להגיע למכשיר מסוים. התשובות QUERY
ו-EXECUTE
מטפלות בזה.
פרטים נוספים זמינים במאמר בנושא זיהוי וסנכרון.
פורמט הבקשה
שדות | סוג | תיאור |
---|---|---|
requestId |
String |
חובה. מזהה הבקשה. |
inputs |
מערך |
חובה. רשימה של קלטים שתואמים לבקשת הכוונה. |
[item, ...] |
אובייקט |
הסוג והמטען הייעודי (payload) שמשויכים לבקשת הכוונה. |
intent |
חובה. (ערך קבוע: סוג בקשת הכוונה. |
דוגמאות
בקשת כוונה לסנכרון
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [ { "intent": "action.devices.SYNC" } ] }
פורמט התשובה
שדות | סוג | תיאור |
---|---|---|
requestId |
String |
חובה. המזהה של הבקשה התואמת. |
payload |
אובייקט |
חובה. מטען ייעודי (payload) של תגובה להצהרת כוונות. |
agentUserId |
String |
חובה. מזהה המשתמש הייחודי (שלא ניתן לשינוי) בפלטפורמה של הסוכן. המחרוזת אטומה ל-Google, ולכן אם יש טופס קבוע לעומת טופס שניתן לשינוי בצד הסוכן, צריך להשתמש בטופס הקבוע (למשל, מספר חשבון ולא כתובת אימייל). |
errorCode |
String |
שגיאות שיטתיות ב-SYNC |
debugString |
String |
שגיאה מפורטת שלא תוצג למשתמשים, אבל יכול להיות שהיא תתועד או תשמש במהלך הפיתוח. |
devices |
מערך |
חובה. רשימת המכשירים שבבעלות המשתמש. מוחזרים אפס מכשירים או יותר (אפס מכשירים פירושו שלמשתמש אין מכשירים, או שהוא ניתק את כולם). |
[item, ...] |
אובייקט |
מטא-נתונים של המכשיר. |
id |
String |
חובה. המזהה של המכשיר בענן של המפתח. הערך הזה צריך להיות ייחודי למשתמש ולמפתח, כי במקרים של שיתוף יכול להיות שנשתמש בו כדי לבטל כפילויות של צפיות מאותו מכשיר. הוא צריך להיות קבוע במכשיר. אם הוא משתנה, Assistant מתייחסת למכשיר כאל מכשיר חדש. |
type |
String |
חובה. סוג החומרה של המכשיר. |
traits |
מערך |
חובה. רשימת ה-Traits של המכשיר. המאפיין הזה מגדיר את הפקודות, המאפיינים והמצבים שהמכשיר תומך בהם. |
[item, ...] |
String |
השם של התכונה הנתמכת. |
name |
אובייקט |
חובה. השמות של המכשיר הזה. |
defaultNames |
מערך |
רשימה של שמות שסופקו על ידי המפתח ולא על ידי המשתמש, לרוב שמות יצרנים, מק"טים וכו'. |
[item, ...] |
String |
שם ברירת המחדל של המכשיר. |
name |
String |
חובה. השם הראשי של המכשיר, בדרך כלל השם שהמשתמש סיפק. זה גם השם ש-Assistant תעדיף להשתמש בו כדי לתאר את המכשיר בתשובות שלה. שמות שיכילו יותר מ-60 תווים יחתכו, ולא יוצגו שגיאות. המפתחים אחראים לטיפול בשמות ארוכים. |
nicknames |
מערך |
שמות נוספים שהמשתמש סיפק למכשיר. |
[item, ...] |
String |
הכינוי של המכשיר. |
willReportState |
Boolean |
חובה. ההגדרה מציינת אם המצבים של המכשיר הזה יעודכנו על ידי הפיד בזמן אמת. (true כדי להשתמש בפיד בזמן אמת לדיווח על מצב, ו-false כדי להשתמש במודל של שליחת בקשות לשרת). |
notificationSupportedByAgent |
Boolean |
(ברירת מחדל: התנאי מציין אם ההתראות מופעלות במכשיר. |
roomHint |
String |
כדי לפשט את ההגדרה, המידע הזה מספק את החדר הנוכחי של המכשיר בבית של המשתמש. |
deviceInfo |
אובייקט |
השדה מכיל תיאור של המכשיר לשימוש בלוגיקה חד-פעמית אם יש צורך בכך (למשל: 'גרסת קושחה X פגומה של מכשיר Y דורשת התאמת צבע', או 'פרצת אבטחה דורשת הודעה לכל המשתמשים בגרסת קושחה Z'). |
manufacturer |
String |
האפשרות הזו שימושית במיוחד כשהמכשיר של המפתח הוא מרכז של מכשירים אחרים. יכול להיות ש-Google תספק כאן רשימה סטנדרטית של יצרנים, כדי ש-TP-Link ו-Smartthings יתארו את osram באותו אופן. |
model |
String |
מזהה הדגם או המק"ט של המכשיר הספציפי. |
hwVersion |
String |
מספר גרסה ספציפי שמשויך לחומרה, אם זמין. |
swVersion |
String |
מספר גרסה ספציפי שמצורף לתוכנה או לקושחה, אם זמין. |
attributes |
אובייקט |
המאפיינים האלה תואמים למאפיינים של כל תכונה שמתוארים בכל הפניה לסכימת תכונות. |
customData |
אובייקט |
אובייקט שמוגדר על ידי המפתח ויצורף לבקשות QUERY ו-EXECUTE עתידיות. הגודל המקסימלי הוא 512 בייטים לכל מכשיר. אפשר להשתמש באובייקט הזה כדי לאחסן מידע נוסף על המכשיר ששירות הענן עשוי להזדקק לו, כמו האזור הגלובלי של המכשיר. יש כמה מגבלות על הנתונים באובייקט הזה: אסור לכלול מידע רגיש, כולל, בין היתר, פרטים אישיים מזהים. |
otherDeviceIds |
מערך |
רשימת מזהים חלופיים שמשמשים לזיהוי מכשיר שמסונכרן עם הענן לצורך הפעלה מקומית. |
[item, ...] |
אובייקט |
מזהה מכשיר חלופי. |
agentId |
String |
המזהה של הסוכן. בדרך כלל זה מזהה הפרויקט בקונסולה ל-Actions. |
deviceId |
String |
חובה. מזהה המכשיר שהוגדר על ידי הסוכן. מזהה המכשיר חייב להיות ייחודי. |
דוגמאות
תגובה לכוונה לסנכרון
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "agentUserId": "1836.15267389", "devices": [ { "id": "123", "type": "action.devices.types.OUTLET", "traits": [ "action.devices.traits.OnOff" ], "name": { "defaultNames": [ "My Outlet 1234" ], "name": "Night light", "nicknames": [ "wall plug" ] }, "willReportState": false, "roomHint": "kitchen", "deviceInfo": { "manufacturer": "lights-out-inc", "model": "hs1234", "hwVersion": "3.2", "swVersion": "11.4" }, "otherDeviceIds": [ { "deviceId": "local-device-id" } ], "customData": { "fooValue": 74, "barValue": true, "bazValue": "foo" } }, { "id": "456", "type": "action.devices.types.LIGHT", "traits": [ "action.devices.traits.OnOff", "action.devices.traits.Brightness", "action.devices.traits.ColorSetting" ], "name": { "defaultNames": [ "lights out inc. bulb A19 color hyperglow" ], "name": "lamp1", "nicknames": [ "reading lamp" ] }, "willReportState": false, "roomHint": "office", "attributes": { "colorModel": "rgb", "colorTemperatureRange": { "temperatureMinK": 2000, "temperatureMaxK": 9000 }, "commandOnlyColorSetting": false }, "deviceInfo": { "manufacturer": "lights out inc.", "model": "hg11", "hwVersion": "1.2", "swVersion": "5.4" }, "customData": { "fooValue": 12, "barValue": false, "bazValue": "bar" } } ] } }