گزارش وضعیت

Report State یک ویژگی مهم است که به Google Home Action اجازه می‌دهد تا به جای انتظار برای یک درخواست QUERY ، آخرین وضعیت دستگاه کاربر را به صورت پیشگیرانه به Google Home Graph گزارش دهد.

Report State وضعیت دستگاه‌های کاربر را با agentUserId مشخص‌شده مرتبط با آنها (که در درخواست SYNC اصلی ارسال شده است) به گوگل گزارش می‌دهد. وقتی Google Assistant می‌خواهد اقدامی انجام دهد که نیاز به درک وضعیت فعلی یک دستگاه دارد، می‌تواند به جای ارسال یک QUERY intent به ابرهای شخص ثالث مختلف قبل از صدور EXECUTE intent، به سادگی اطلاعات وضعیت را در Home Graph جستجو کند.

بدون Report State ، با توجه به چراغ‌های چندین ارائه‌دهنده در یک اتاق نشیمن، دستور Ok Google, brighten my living room نیاز به حل چندین درخواست QUERY intent) ارسال شده به چندین cloud دارد، برخلاف جستجوی ساده مقادیر روشنایی فعلی بر اساس آنچه قبلاً گزارش شده است. برای بهترین تجربه کاربری، Assistant باید وضعیت فعلی یک دستگاه را داشته باشد، بدون اینکه نیاز به رفت و برگشت به دستگاه باشد.

پس از SYNC اولیه برای یک دستگاه، پلتفرم یک هدف QUERY ارسال می‌کند که وضعیت دستگاه را برای پر کردن Home Graph جمع‌آوری می‌کند. پس از آن نقطه، Home Graph فقط وضعیتی را که با Report State ارسال می‌شود، ذخیره می‌کند.

هنگام فراخوانی Report State ، مطمئن شوید که داده‌های وضعیت کامل را برای یک ویژگی مشخص ارائه می‌دهید. Home Graph وضعیت‌ها را بر اساس هر ویژگی به‌روزرسانی می‌کند و هنگام فراخوانی Report State ، تمام داده‌های آن ویژگی را بازنویسی می‌کند. به عنوان مثال، اگر وضعیت را برای ویژگی StartStop گزارش می‌کنید، payload باید شامل مقادیری برای isRunning و isPaused باشد.

شروع کنید

برای پیاده‌سازی Report State ، مراحل زیر را دنبال کنید:

• فعال کردن API گوگل هوم‌گراف
• ایجاد کلید حساب سرویس
• فراخوانی API

فعال کردن API گوگل هوم‌گراف

1. در Google Cloud Console ، به صفحه HomeGraph API بروید.

   به صفحه HomeGraph API بروید
2. پروژه‌ای را انتخاب کنید که با شناسه پروژه smart home شما مطابقت داشته باشد.
3. روی فعال کردن (ENABLE) کلیک کنید.

ایجاد کلید حساب سرویس

برای تولید کلید حساب سرویس از Google Cloud Console این دستورالعمل‌ها را دنبال کنید:

1. در Google Cloud Console ، به صفحه حساب‌های سرویس بروید.

   به صفحه حساب‌های سرویس بروید .

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

2. روی add کلیک کنید. ایجاد حساب کاربری سرویس .

3. در قسمت نام حساب سرویس ، یک نام وارد کنید.

4. در قسمت شناسه حساب سرویس ، یک شناسه وارد کنید.

5. در قسمت توضیحات حساب سرویس ، توضیحی وارد کنید.

6. روی ایجاد کلیک کنید و ادامه دهید .

7. از منوی کشویی نقش ، حساب‌های سرویس > حساب سرویس OpenID Connect Identity Token Creator را انتخاب کنید.

8. روی ادامه کلیک کنید.

9. روی انجام شد کلیک کنید.

10. حساب سرویسی که ایجاد کرده‌اید را از فهرست حساب‌های سرویس انتخاب کنید و از منوی more_vert Actions گزینه Manage keys را انتخاب کنید.

11. افزودن کلید > ایجاد کلید جدید را انتخاب کنید.

12. برای نوع کلید ، گزینه JSON را انتخاب کنید.

13. روی «ایجاد» کلیک کنید. یک فایل JSON که حاوی کلیدهای دانلود شده روی رایانه شماست.

فراخوانی API

از بین تب‌های زیر، گزینه‌ای را انتخاب کنید:

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

  // Get Application Default credentials.
  GoogleCredentials credentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

  // Create Home Graph service client.
  HomeGraphService homegraphService =
      new HomeGraphService.Builder(
              GoogleNetHttpTransport.newTrustedTransport(),
              GsonFactory.getDefaultInstance(),
              new HttpCredentialsAdapter(credentials))
          .setApplicationName("HomeGraphExample/1.0")
          .build();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request);
}
    

وضعیت گزارش آزمایش

برای اینکه یکپارچه‌سازی Cloud-to-cloud شما برای صدور گواهینامه آماده شود، آزمایش Report State مهم است.

برای انجام این کار، توصیه می‌کنیم از ابزار Home Graph Viewer استفاده کنید که یک برنامه وب مستقل است و نیازی به دانلود یا استقرار ندارد.

داشبورد Report State هنوز در دسترس است، اما منسوخ شده و دیگر پشتیبانی نمی‌شود.

داشبورد گزارش وضعیت

پیش‌نیازها

قبل از اینکه بتوانید یکپارچه‌سازی Cloud-to-cloud خود را آزمایش کنید، به کلید حساب سرویس (Service Account Key) و agentUserId عامل (agentUserId) خود نیاز دارید. اگر از قبل کلید حساب سرویس و agentUserId خود را دارید، به بخش استقرار داشبورد Report State Dashboard) مراجعه کنید.

داشبورد گزارش وضعیت (Report State) را مستقر کنید

پس از دریافت کلید حساب سرویس و شناسه کاربری عامل برای پروژه خود، آخرین نسخه را از داشبورد Report State دانلود و نصب کنید. پس از دانلود آخرین نسخه، دستورالعمل‌های موجود در فایل README.MD موجود را دنبال کنید.

پس از اینکه داشبورد Report State را مستقر کردید، از طریق URL زیر به داشبورد دسترسی پیدا کنید ( your_project_id را با شناسه پروژه خود جایگزین کنید):

http://<your-project-id>.appspot.com

در داشبورد، موارد زیر را انجام دهید:

• فایل کلید حساب خود را انتخاب کنید
• agentUserId خود را اضافه کنید

سپس، روی فهرست کلیک کنید.

تمام دستگاه‌های شما فهرست شده‌اند. پس از پر شدن لیست، می‌توانید از دکمه‌ی «به‌روزرسانی» برای به‌روزرسانی وضعیت دستگاه‌ها استفاده کنید. اگر تغییری در وضعیت دستگاه ایجاد شود، ردیف مربوطه با رنگ سبز برجسته می‌شود.

گزارش اختلاف وضعیت

دقت وضعیت گزارش مبتنی بر پرس‌وجو، میزان تطابق آخرین وضعیت گزارش برای یک دستگاه با وضعیت دستگاه هنگام پرس‌وجوی کاربر را اندازه‌گیری می‌کند. انتظار می‌رود این مقدار ۹۹.۵٪ باشد.

پاسخ‌های خطا

ممکن است هنگام فراخوانی تابع Report State با یکی از خطاهای زیر مواجه شوید. این خطاها به صورت کدهای وضعیت HTTP نمایش داده می‌شوند.

• 400 Bad Request - سرور به دلیل سینتکس نامعتبر قادر به پردازش درخواست ارسال شده توسط کلاینت نبوده است. دلایل رایج شامل JSON ناقص یا استفاده از null به جای "" برای یک مقدار رشته‌ای است.
• 404 Not Found - منبع درخواستی یافت نشد اما ممکن است در آینده در دسترس باشد. معمولاً این بدان معناست که ما نمی‌توانیم دستگاه درخواستی را پیدا کنیم. همچنین ممکن است به این معنی باشد که حساب کاربری به گوگل متصل نیست یا ما یک agentUserId نامعتبر دریافت کرده‌ایم. اطمینان حاصل کنید که agentUserId با مقدار ارائه شده در پاسخ SYNC شما مطابقت دارد و شما به درستی اهداف DISCONNECT را مدیریت می‌کنید.

گزارش وضعیت آنلاین و آفلاین

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }