گزارش وضعیت

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

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

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

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

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

شروع کنید

برای اجرای Report State ، مراحل زیر را دنبال کنید:

• Google HomeGraph API را فعال کنید
• یک کلید حساب سرویس ایجاد کنید
• با API تماس بگیرید

Google HomeGraph API را فعال کنید

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

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

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

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

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

   به صفحه Create Service Account Key بروید
2. از لیست حساب سرویس ، حساب سرویس جدید را انتخاب کنید.
3. در قسمت نام حساب سرویس ، یک نام وارد کنید.
4. در قسمت شناسه حساب سرویس ، یک شناسه وارد کنید.

5. از فهرست نقش ، حساب‌های خدمات > ایجاد کننده رمز حساب حساب را انتخاب کنید.

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

7. روی ایجاد کلیک کنید. یک فایل 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);
}
    

وضعیت گزارش تست

برای اینکه اقدام خود را برای صدور گواهینامه آماده کنید، مهم است که Report State آزمایش کنید.

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

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

گزارش داشبورد ایالتی

پیش نیازها

قبل از اینکه بتوانید اقدام خود را آزمایش کنید، به Key Account Service و agentUserId خود نیاز دارید. اگر از قبل کلید حساب سرویس و agentUserId خود را دارید، به Deploy the Report State Dashboard مراجعه کنید.

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

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

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

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

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

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

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

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

پاسخ های خطا

هنگام تماس با Report State ممکن است یکی از پاسخ های خطای زیر را دریافت کنید. این پاسخ ها در قالب کدهای وضعیت HTTP ارائه می شوند.

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