action.devices.SYNC

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

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

התשובה של 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

חובה.

סוג החומרה של המכשיר.

חייב להתאים לתבנית: ^action.devices.types.[a-zA-z]+$.
traits מערך

חובה.

רשימת המאפיינים של המכשיר. המאפיינים מגדירים את הפקודות, המאפיינים והמצבים שהמכשיר תומך בהם.
[item, ...] String

השם של התכונה הנתמכת.

חייב להתאים לתבנית: ^action.devices.traits.[a-zA-z]+$.
name אובייקט

חובה.

השמות של המכשיר הזה.
defaultNames מערך

רשימה של שמות שסופקו על ידי המפתח ולא על ידי המשתמש, לרוב שמות יצרנים, מק"טים וכו'.
[item, ...] String

שם ברירת המחדל של המכשיר.
name String

חובה.

השם הראשי של המכשיר, בדרך כלל מסופק על ידי המשתמש. זה גם השם שבו העוזר הדיגיטלי יעדיף לתאר את המכשיר בתשובות. שמות ייחתכו אם הם ארוכים יותר מהמגבלה של 60 נקודות קוד Unicode (תווים), ולא יוצגו שגיאות. המפתחים אחראים לטיפול בשמות ארוכים.
nicknames מערך

שמות נוספים שהמשתמש סיפק למכשיר.
[item, ...] String

הכינוי של המכשיר.
willReportState בוליאני

חובה.

ההגדרה מציינת אם המצבים של המכשיר הזה יעודכנו על ידי פיד בזמן אמת. (true כדי להשתמש בפיד בזמן אמת לדיווח על מצב, ו-false כדי להשתמש במודל של שליחת בקשות לשרת).
notificationSupportedByAgent בוליאני

(ברירת מחדל: 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"
        }
      }
    ]
  }
}