حالة التقرير

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

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

بدون Report State، إذا كانت هناك مصابيح من عدة مقدّمي خدمات في غرفة المعيشة، يتطلّب الأمر Ok Google, brighten my living room حلّ عدة طلبات 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، يمكنك الوصول إلى لوحة البيانات من عنوان URL التالي (استبدِل your_project_id برقم تعريف مشروعك):

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

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

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

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

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

الإبلاغ عن اختلاف في الحالة

تقيس دقة حالة التقرير المستندة إلى طلب البحث مدى تطابق أحدث حالة تقرير لجهاز مع حالة الجهاز عندما يطلب المستخدم معلومات عنه. ومن المتوقع أن تصل هذه القيمة إلى %99.5 لمزيد من التفاصيل حول الحالة الحالية لدقة الإبلاغ عن الحالة لمشروعك، يُرجى الاطّلاع على سلامة الجهاز - دقة الحالة. يمكنك أيضًا الاطّلاع على تفاصيل سجلّ الاختلافات في 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. تأتي هذه الردود في شكل رموز حالة 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 وRequest Sync لأجهزة هذا المستخدم.
   • إذا عرضت نقطة النهاية 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": {},
        }
      }
    }