ברוכים הבאים למרכז למפתחים של Google Home, היעד החדש ללמידה על פיתוח פעולות לבית חכם.

דף זה תורגם על ידי Cloud Translation API.

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