وضعیت گزارش

Report State is an important feature which lets the Google Home Action proactively report the latest status of the user's device back to Google Home Graph rather than waiting for a QUERY intent.

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

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

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

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

شروع کنید

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

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

فعال کردن Google HomeGraph API

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

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

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

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

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

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

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

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

3. در فیلد نام حساب سرویس، نامی وارد کنید.

4. در فیلد شناسه حساب سرویس، شناسه‌ای وارد کنید.

5. در فیلد شرح حساب سرویس، شرحی وارد کنید.

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

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

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

9. روی تمام کلیک کنید.

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

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

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

13. روی ایجاد کردن کلیک کنید. فایل JSON حاوی کلیدتان در رایانه بارگیری می‌شود.

فراخوانی میانای برنامه‌سازی کاربردی

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

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).execute();
}
    

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

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

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

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

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

پیش‌نیازها

قبل‌از اینکه بتوانید ادغام Cloud-to-cloud را آزمایش کنید، به «کلید حساب سرویس» و agentUserId نیاز دارید. اگر ازقبل «کلید حساب سرویس» خود را دارید و agentUserId پیاده‌سازی Report State داشبورد را می‌بینید.

پیاده‌سازی داشبورد Report State

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

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

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

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

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

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

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

گزارش کردن مغایرت وضعیت

دقت وضعیت گزارش مبتنی بر پُرسمان میزان مطابقت آخرین وضعیت گزارش دستگاه با وضعیت دستگاه را هنگام پُرسمان کاربر برای آن می‌سنجد. انتظار می‌رود این مقدار روی ۹۹٫۵٪ باشد. برای جزئیات بیشتر درباره وضعیت فعلی دقت وضعیت گزارش پروژه خود، به سلامت دستگاه - دقت وضعیت مراجعه کنید. همچنین می‌توانید جزئیات گزارش ثبت مغایرت وضعیت را در کاوشگر گزارش‌ها ببینید.

در اینجا نمونه‌ای از گزارش ثبت مغایرت وضعیت آورده شده است:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

تعاریف فیلد گزارش ثبت مغایرت وضعیت

پاسخ‌های خطا

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

خطای ۴۰۰ - درخواست نامناسب

سرور نتوانست درخواست ارسال‌شده ازسوی کارخواه را به‌دلیل نحو نامعتبر پردازش کند. دلایل رایج شامل JSON بدشکل یا استفاده از null به‌جای «» برای مقدار رشته‌ای است.

‫404 یافت نشد

منبع درخواستی پیدا نشد اما ممکن است در آینده دردسترس قرار گیرد. معمولاً این یعنی نمی‌توانیم دستگاه درخواست‌شده را پیدا کنیم. همچنین ممکن است به این معنی باشد که حساب کاربر به Google پیوند داده نشده است یا agentUserId نامعتبری دریافت کرده‌ایم. مطمئن شوید که agentUserId با مقدار ارائه‌شده در پاسخ SYNC شما مطابقت داشته باشد و هدف‌های DISCONNECT را به‌درستی مدیریت می‌کنید.

وقتی تماس ReportState با خطای 404 NOT_FOUND ناموفق می‌شود، نشان‌دهنده عدم تطابق همگام‌سازی بین فضای ابری شما و Home Graph است. این اتفاق ممکن است زمانی رخ دهد که دستگاهی از Home Graph برداشته شود، یا اگر کاربری پیوند حسابش را لغو کند.

برای رسیدگی به خطاهای 404 از Report State، از روال زیر استفاده کنید:

1. بررسی وضعیت حساب کاربر: devices.sync را برای agentUserId که خطای ۴۰۴ برگردانده است فراخوانی کنید. این کار کمک می‌کند مشخص شود خطا مربوط به کل حساب کاربری است یا دستگاهی خاص.
   • اگر SYNC خطای ۴۰۴ برگرداند، حساب کاربر دیگر با Google پیوند ندارد. ارسال «وضعیت گزارش» و «درخواست همگام‌سازی» را برای دستگاه‌های این کاربر متوقف کنید.
   • اگر SYNC کد 200 OK را برگرداند، حساب کاربر همچنان پیوندشده است، یعنی خطای 404 مختص دستگاه است.
2. تطبیق دادن فهرست دستگاه: اگر SYNC کد 200 OK را برگرداند، باید مشخص کنید کدام دستگاه(ها) دیگر برای Google شناخته‌شده نیستند. توصیه می‌کنیم فهرست دستگاه‌هایی را که Google برای کاربر دارد با پایگاه داده دستگاهتان مقایسه کنید و دستگاه‌هایی را که در فهرست Google وجود ندارند در سیستم خود شناسایی کنید. اگر دستگاهی باید با Google همگام‌سازی شود اما هنوز با Google هم‌رسانی نشده است، از SYNC استفاده کنید تا مطمئن شوید دستگاه با Google همگام‌سازی شده است. اگر دستگاهی باید از Google لغو پیوند شود، گزارش وضعیت را برای آن دستگاه خاص متوقف کنید و گزارش‌دهی را برای سایر دستگاه‌های معتبر تحت آن agentUserId ادامه دهید.

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

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