action.devices.SYNC

הכוונה הזו מבקשת את רשימת המכשירים שמשויכים למשתמש שצוין ואת היכולות שלהם.

היא מופעלת במהלך קישור החשבון או כשמשתמש מסנכרן מחדש את המכשירים שלו באופן ידני. ההשלמה צריכה להגיב עם מאפיינים וסוגי traits נתמכים לכל מכשיר.

התשובה של SYNC צריכה להחזיר את כל המכשירים שמשויכים למשתמש. ההגדרה הזו לא קובעת אם אפשר להגיע למכשיר מסוים. התשובות QUERY ו-EXECUTE מטפלות בזה.

פרטים נוספים זמינים במאמר בנושא זיהוי וסנכרון.

פורמט הבקשה

שדות סוג תיאור
requestId String

חובה.

מזהה הבקשה.

inputs מערך

חובה.

רשימה של קלטים שתואמים לבקשת הכוונה.

[item, ...] אובייקט

הסוג והמטען הייעודי (payload) שמשויכים לבקשת הכוונה.

intent

חובה.

(ערך קבוע: "action.devices.SYNC")

סוג בקשת הכוונה.

דוגמאות

בקשת כוונה לסנכרון

{
  "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

(ברירת מחדל: false)

התנאי מציין אם ההתראות מופעלות במכשיר.

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"
        }
      }
    ]
  }
}