همگام‌سازی دستگاه‌ها

این intent لیست دستگاه‌های مرتبط با کاربر داده شده و قابلیت‌های آنها را درخواست می‌کند.

این قابلیت در حین اتصال حساب کاربری یا زمانی که کاربر به صورت دستی دستگاه‌های خود را دوباره همگام‌سازی می‌کند، فعال می‌شود. عملکرد شما باید با ویژگی‌ها و مشخصه‌های پشتیبانی‌شده برای هر دستگاه پاسخ دهد.

پاسخ SYNC شما باید تمام دستگاه‌های مرتبط با کاربر را برگرداند. این مشخص نمی‌کند که آیا دستگاه خاصی قابل دسترسی است یا خیر. این کار توسط پاسخ‌های QUERY و EXECUTE انجام می‌شود.

برای جزئیات بیشتر، به شناسایی و همگام‌سازی مراجعه کنید.

قالب درخواست

فیلدها نوع توضیحات
requestId رشته

الزامی است.

شناسه درخواست.

inputs آرایه

الزامی است.

فهرست ورودی‌هایی که با درخواست intent مطابقت دارند.

[ item, ... ] شیء

نوع و میزان بار مرتبط با درخواست intent.

intent

الزامی است.

(مقدار ثابت: "action.devices.SYNC" )

نوع درخواست قصد.

مثال‌ها

درخواست قصد همگام‌سازی

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

قالب پاسخ

فیلدها نوع توضیحات
requestId رشته

الزامی است.

شناسه درخواست مربوطه.

payload شیء

الزامی است.

بار مفید پاسخ قصد.

agentUserId رشته

الزامی است.

شناسه کاربری منحصر به فرد (و تغییرناپذیر) را در پلتفرم عامل نشان می‌دهد. این رشته برای گوگل مبهم است، بنابراین اگر در سمت عامل یک فرم تغییرناپذیر در مقابل یک فرم تغییرپذیر وجود دارد، از فرم تغییرناپذیر استفاده کنید (مثلاً شماره حساب به جای ایمیل).

errorCode رشته

برای خطاهای سیستماتیک در SYNC

debugString رشته

خطای جزئی که هرگز به کاربران نمایش داده نمی‌شود اما ممکن است در طول توسعه ثبت یا استفاده شود.

devices آرایه

الزامی است.

فهرست دستگاه‌های متعلق به کاربر. صفر یا چند دستگاه برگردانده می‌شود (صفر دستگاه به این معنی است که کاربر هیچ دستگاهی ندارد یا همه آنها را از شبکه جدا کرده است).

[ item, ... ] شیء

فراداده دستگاه.

id رشته

الزامی است.

شناسه دستگاه در فضای ابری توسعه‌دهنده. این شناسه باید برای کاربر و توسعه‌دهنده منحصر به فرد باشد، زیرا در موارد اشتراک‌گذاری ممکن است از آن برای حذف چندین نمای تکراری از یک دستگاه استفاده کنیم. این شناسه باید برای دستگاه تغییرناپذیر باشد؛ در صورت تغییر، دستیار با آن به عنوان یک دستگاه جدید رفتار خواهد کرد.

type رشته

الزامی است.

نوع سخت‌افزار دستگاه.

باید با الگوی زیر مطابقت داشته باشد: ^action.devices.types.[a-zA-z]+$ .

traits آرایه

الزامی است.

فهرست ویژگی‌های این دستگاه. این فهرست، دستورات، ویژگی‌ها و حالت‌هایی را که دستگاه پشتیبانی می‌کند، تعریف می‌کند.

[ item, ... ] رشته

نام ویژگی پشتیبانی شده.

باید با الگوی زیر مطابقت داشته باشد: ^action.devices.traits.[a-zA-z]+$ .

name شیء

الزامی است.

نام‌های این دستگاه

defaultNames آرایه

فهرست نام‌هایی که توسط توسعه‌دهنده به جای کاربر ارائه شده است، اغلب نام سازنده، SKU و غیره.

[ item, ... ] رشته

نام پیش‌فرض دستگاه

name رشته

الزامی است.

نام اصلی دستگاه، که معمولاً توسط کاربر ارائه می‌شود. این نامی است که دستیار برای توصیف دستگاه در پاسخ‌ها ترجیح می‌دهد. اگر نام‌ها بیش از ۶۰ کاراکتر (کد پوینت) یونیکد باشند، کوتاه می‌شوند و هیچ خطایی ایجاد نمی‌شود. توسعه‌دهندگان مسئول مدیریت نام‌های طولانی هستند.

nicknames آرایه

نام‌های اضافی ارائه شده توسط کاربر برای دستگاه.

[ item, ... ] رشته

نام مستعار دستگاه.

willReportState بولی

الزامی است.

نشان می‌دهد که آیا وضعیت این دستگاه توسط فید بلادرنگ به‌روزرسانی خواهد شد یا خیر. (برای استفاده از فید بلادرنگ جهت گزارش وضعیت، مقدار true و برای استفاده از مدل نظرسنجی، مقدار false است.)

notificationSupportedByAgent بولی

(پیش‌فرض: false )

نشان می‌دهد که آیا اعلان‌ها برای دستگاه فعال هستند یا خیر.

roomHint رشته

فضای فعلی دستگاه در خانه کاربر را برای ساده‌سازی راه‌اندازی ارائه می‌دهد.

deviceInfo شیء

شامل فیلدهایی است که دستگاه را برای استفاده در منطق یک‌باره در صورت نیاز توصیف می‌کنند (مثلاً «نسخه‌ی X میان‌افزار چراغ Y نیاز به تنظیم رنگ دارد» یا «نقص امنیتی نیاز به اطلاع‌رسانی به تمام کاربران میان‌افزار Z دارد»).

manufacturer رشته

مخصوصاً زمانی مفید است که توسعه‌دهنده، مرکزی برای دستگاه‌های دیگر باشد. گوگل ممکن است فهرست استانداردی از تولیدکنندگان را در اینجا ارائه دهد، به طوری که مثلاً TP-Link و Smartthings هر دو «osram» را به یک شکل توصیف کنند.

model رشته

مدل یا شناسه SKU دستگاه خاص.

hwVersion رشته

در صورت وجود، شماره نسخه خاص متصل به سخت‌افزار.

swVersion رشته

در صورت وجود، شماره نسخه خاص پیوست شده به نرم‌افزار/میان‌افزار.

attributes شیء

با ویژگی‌های هر صفت که در مرجع هر طرحواره صفت شرح داده شده است، همسو شده است.

customData شیء

شیء تعریف‌شده توسط توسعه‌دهنده که به درخواست‌های QUERY و EXECUTE آینده متصل خواهد شد، حداکثر ۵۱۲ بایت برای هر دستگاه. از این شیء برای ذخیره اطلاعات اضافی در مورد دستگاهی که سرویس ابری شما ممکن است به آن نیاز داشته باشد، مانند منطقه جهانی دستگاه، استفاده کنید. داده‌های موجود در این شیء دارای چند محدودیت هستند: بدون اطلاعات حساس، از جمله اما نه محدود به اطلاعات شخصی قابل شناسایی.

otherDeviceIds آرایه

فهرست شناسه‌های جایگزین مورد استفاده برای شناسایی دستگاه همگام‌سازی‌شده با ابر جهت اجرای محلی.

[ item, ... ] شیء

شناسه دستگاه جایگزین.

agentId رشته

شناسه عامل. معمولاً این شناسه پروژه در کنسول Actions است.

deviceId رشته

الزامی است.

شناسه دستگاه توسط عامل تعریف می‌شود. شناسه دستگاه باید منحصر به فرد باشد.

مثال‌ها

پاسخ قصد همگام‌سازی

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