حالة التقرير

Report State هي ميزة مهمة تتيح لـ Google Home الإبلاغ بشكل استباقي عن أحدث حالة لـ جهاز المستخدم إلى Google Home Graph بدلاً من انتظار هدف QUERY.

Report State تُبلغ Google بحالات أجهزة المستخدمين التي تتضمّن agentUserId المحدّد المرتبط بها (المرسَل في طلب SYNC الأصلي). عندما يريد Google Assistant اتّخاذ إجراء يتطلّب فهم الحالة الحالية لجهاز، يمكنه ببساطة البحث عن معلومات الحالة في Home Graph بدلاً من إصدار هدف QUERY إلى العديد من السُحب الإلكترونية التابعة لجهات خارجية قبل إصدار هدف EXECUTE.

بدون Report State، إذا كانت هناك مصابيح من عدّة مورّدين في غرفة المعيشة، يتطلّب الأمر حلّ عدّة أهداف QUERY يتم إرسالها إلى عدّة سُحب إلكترونية، بدلاً من البحث ببساطة عن قيم السطوع الحالية استنادًا إلى ما تم الإبلاغ عنه سابقًا، وذلك لتنفيذ الأمر Ok Google, brighten my living room. للحصول على أفضل تجربة للمستخدم، 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 لحساب الخدمة.

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

اختبار Report State

لإعداد عملية التكامل Cloud-to-cloud للحصول على الشهادة، من المهم اختبار Report State.

لإجراء ذلك، ننصحك باستخدام أداة Home Graph Viewer، وهي تطبيق ويب مستقل لا يتطلّب التنزيل أو النشر.

لا تزال لوحة بيانات Report State متاحة، ولكن تم إيقافها نهائيًا ولم يعُد يتم دعمها.

لوحة بيانات Report State

المتطلبات الأساسية

قبل أن تتمكّن من اختبار عملية التكامل Cloud-to-cloud، تحتاج إلى مفتاح حساب الخدمة وagentUserId. إذا كان لديك بالفعل مفتاح حساب الخدمة وagentUserId، يُرجى الاطّلاع على نشر Report State لوحة البيانات.

تفعيل لوحة بيانات Report State

بعد الحصول على مفتاح حساب الخدمة ورقم تعريف المستخدم الوكيل لمشروعك، نزِّل أحدث إصدار من Report State لوحة بيانات وانشره. بعد تنزيل أحدث إصدار، اتّبِع التعليمات الواردة في ملف README.MD المضمّن.

بعد تفعيل لوحة بيانات Report State، يمكنك الوصول إلى لوحة البيانات من عنوان URL التالي (استبدِل your_project_id برقم تعريف مشروعك):

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

على لوحة البيانات، نفِّذ ما يلي:

• اختَر ملف مفتاح حسابك
• أضِف agentUserId

بعد ذلك، انقر على قائمة.

يتم عرض جميع أجهزتك. بعد ملء القائمة، يمكنك استخدام الزر إعادة تحميل لتعديل حالات الأجهزة. إذا طرأ تغيير على حالة الجهاز، يتم تمييز الصف باللون الأخضر.

التناقضات في Report State

يقيس مدى دقة حالة التقرير المستندة إلى طلب البحث مدى تطابُق أحدث حالة تقرير لجهاز مع حالة الجهاز عندما يطلبها المستخدم. من المفترض أن تكون هذه القيمة %99.5. لمزيد من التفاصيل حول الحالة الحالية لل دقة Report State في مشروعك، يُرجى الاطّلاع على حالة الجهاز - دقة الحالة. يمكنك أيضًا الاطّلاع على تفاصيل سجلّ التناقضات في Report State من مستكشف السجلّات.

في ما يلي مثال على سجلّ التناقضات في Report State:

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

استجابات الخطأ

قد تتلقّى إحدى استجابات الخطأ التالية عند استدعاء Report State. تأتي هذه الاستجابات في شكل رموز حالة HTTP.

400 طلب غير صالح

تعذّر على الخادم معالجة الطلب الذي أرسله العميل بسبب بنية غير صالحة. تشمل الأسباب الشائعة ملف JSON غير مكتوب بشكل صحيح أو استخدام null بدلاً من "" لقيمة سلسلة.

‫404 لم يتم العثور على الصفحة

تعذَّر العثور على المورد المطلوب، ولكن قد يكون متاحًا في المستقبل. يعني هذا عادةً أنّه لا يمكننا العثور على الجهاز المطلوب. قد يعني أيضًا أنّ حساب المستخدم غير مرتبط بـ Google أو أنّنا تلقّينا agentUserId غير صالح. تأكَّد من أنّ agentUserId يطابق القيمة المقدَّمة في استجابة SYNC، وأنّك تتعامل بشكل صحيح مع أهداف DISCONNECT.

عندما يفشل طلب ReportState بسبب الخطأ 404 NOT_FOUND، يشير ذلك إلى عدم تطابُق المزامنة بين السحابة الإلكترونية وHome Graph. يمكن أن يحدث ذلك إذا تمت إزالة جهاز من Home Graph أو إذا ألغى المستخدم ربط حسابه.

للتعامل مع أخطاء 404 من Report State، استخدِم الإجراء التالي:

1. التحقّق من حالة حساب المستخدم: استدعِ devices.sync لـ agentUserId الذي عرض الخطأ 404. يساعد ذلك في تحديد ما إذا كان الخطأ يخص حساب المستخدم بالكامل أو جهازًا معيّنًا.
   • إذا عرض SYNC الخطأ 404، لم يعُد حساب المستخدم مرتبطًا بـ Google. توقَّف عن إرسال Report State وطلب المزامنة لأجهزة هذا المستخدم.
   • إذا عرض 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": {},
        }
      }
    }