وضعیت گزارش

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

‫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 داشبورد بارگیری و مستقر کنید. پس‌از بارگیری جدیدترین نسخه، دستورالعمل‌های فایل 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، ممکن است یکی از پاسخ‌های خطای زیر را دریافت کنید. این پاسخ‌ها به‌صورت کدهای وضعیت HTTP ارائه می‌شوند.

‫۴۰۰ درخواست نادرست

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

‫404 یافت نشد

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

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

برای رسیدگی به خطاهای 404 از «گزارش وضعیت»، از روش زیر استفاده کنید:

1. بررسی وضعیت حساب کاربر: برای agentUserId که خطای ۴۰۴ برگردانده است، devices.sync را فراخوانی کنید. این کار کمک می‌کند تعیین شود خطا مربوط به کل حساب کاربری است یا دستگاهی خاص.
   • اگر 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": {},
        }
      }
    }