حالة التقرير

Report State هي ميزة مهمة تتيح Google Home "الإجراء" إرسال تقرير استباقي إلى Google Home Graph بشأن آخر حالة لجهاز المستخدم، بدلاً من انتظار طلب QUERY.

ترسل 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، يجب أن يتضمّن الحمولة قيمًا لكلّ من isRunning وisPaused.

البدء

لتنفيذ Report State، اتّبِع الخطوات التالية:

• تفعيل Google HomeGraph API
• إنشاء مفتاح حساب خدمة
• استدعاء واجهة برمجة التطبيقات

تفعيل واجهة برمجة التطبيقات Google HomeGraph

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

حالة تقرير الاختبار

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

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

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

لوحة بيانات حالة التقرير

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

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

نشر لوحة بيانات "حالة التقرير"

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

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

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

في لوحة البيانات، اتّبِع الخطوات التالية:

• اختيار ملف مفتاح حسابك
• إضافة agentUserId

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

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

التناقض في حالة التقرير

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

في ما يلي مثال على سجلّ تباين حالة التقرير:

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

‫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. إيقاف إرسال "حالة التقرير" و"طلب المزامنة" لأجهزة هذا المستخدم
   • إذا عرضت 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": {},
        }
      }
    }