action.devices.SYNC

يطلب هذا الغرض قائمة الأجهزة المرتبطة بالمستخدم المحدّد وإمكاناتها.

يتم تفعيلها أثناء ربط الحساب أو عندما يعيد المستخدم مزامنة أجهزته يدويًا. يجب أن يستجيب التنفيذ بالسمات والخصائص المتوافقة لكل جهاز.

يجب أن يعرض ردّك على طلب SYNC جميع الأجهزة المرتبطة بالمستخدم. لا يحدّد هذا الإعداد ما إذا كان يمكن الوصول إلى أي جهاز معيّن. ويتم التعامل مع ذلك من خلال الردود QUERY وEXECUTE.

لمزيد من التفاصيل، يمكنك الاطّلاع على التعرّف على الأغاني ومزامنتها.

تنسيق الطلب

الحقول النوع الوصف
requestId String

مطلوبة

معرّف الطلب.
inputs المصفوفة

مطلوبة

قائمة بالمدخلات التي تتطابق مع طلب الهدف
[item, ...] الكائن

النوع والحمولة المرتبطان بطلب الهدف
intent

مطلوبة

(القيمة الثابتة: "action.devices.SYNC")

نوع طلب الهدف
أمثلة

طلب SYNC intent

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}

تنسيق الردّ

الحقول النوع الوصف
requestId String

مطلوبة

معرّف الطلب ذي الصلة
payload الكائن

مطلوبة

حمولة ردّ الهدف
agentUserId String

مطلوبة

تعرض هذه السمة رقم تعريف المستخدم الفريد (والثابت) على منصة الوكيل. السلسلة غير شفافة بالنسبة إلى Google، لذا إذا كان هناك نموذج غير قابل للتغيير مقابل نموذج قابل للتغيير من جهة الوكيل، استخدِم النموذج غير القابل للتغيير (مثل رقم حساب بدلاً من عنوان البريد الإلكتروني).
errorCode String

بالنسبة إلى الأخطاء المنهجية في SYNC
debugString String

خطأ تفصيلي لن يتم عرضه أبدًا للمستخدمين ولكن قد يتم تسجيله أو استخدامه أثناء التطوير.
devices المصفوفة

مطلوبة

قائمة بالأجهزة التي يملكها المستخدم يتم عرض صفر أو أكثر من الأجهزة (يشير صفر جهاز إلى أنّ المستخدم ليس لديه أي أجهزة أو أنّه ألغى ربطها جميعًا).
[item, ...] الكائن

البيانات الوصفية للجهاز
id String

مطلوبة

رقم تعريف الجهاز في السحابة الإلكترونية الخاصة بالمطوّر يجب أن يكون هذا المعرّف فريدًا للمستخدم والمطوّر، لأنّه في حالات المشاركة، قد نستخدمه لإزالة تكرار المشاهدات المتعددة للجهاز نفسه. يجب أن يكون هذا المعرّف غير قابل للتغيير بالنسبة إلى الجهاز، وإذا تغيّر، سيتعامل معه "مساعد Google" على أنّه جهاز جديد.
type String

مطلوبة

نوع معدّات الجهاز
traits المصفوفة

مطلوبة

قائمة بالسمات التي يتضمّنها هذا الجهاز. تحدّد هذه السمة الأوامر والسمات والحالات التي يتيحها الجهاز.
[item, ...] String

اسم السمة المتوافقة
name الكائن

مطلوبة

أسماء هذا الجهاز.
defaultNames المصفوفة

قائمة بالأسماء التي يقدّمها المطوّر وليس المستخدم، وغالبًا ما تكون أسماء الشركات المصنّعة أو رموز التخزين التعريفية أو غير ذلك
[item, ...] String

الاسم التلقائي للجهاز
name String

مطلوبة

الاسم الأساسي للجهاز، ويقدّمه المستخدم عادةً. وهذا هو الاسم الذي يفضّله "مساعد Google" لوصف الجهاز في الردود. سيتم اقتطاع الأسماء إذا تجاوزت الحد الأقصى المسموح به وهو 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

مطلوبة

رقم تعريف الجهاز الذي يحدّده الوكيل. يجب أن يكون رقم تعريف الجهاز فريدًا.
أمثلة

استجابة SYNC intent

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