حالة التقرير

Report State هي ميزة مهمة تسمح بالإجراء 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
• إنشاء مفتاح لحساب خدمة
• الاتصال بواجهة برمجة التطبيقات

تفعيل Google HomeGraph API

1. في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.

   الانتقال إلى صفحة واجهة برمجة التطبيقات HomeGraph
2. اختَر المشروع الذي يطابق رقم تعريف مشروع smart home.
3. انقر على تفعيل.

إنشاء مفتاح لحساب الخدمة

يُرجى اتّباع التعليمات التالية لإنشاء مفتاح حساب خدمة من Google Cloud Console:

1. في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب الخدمة.

   الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة"
2. من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
3. في حقل اسم حساب الخدمة، أدخِل اسمًا.
4. في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.

5. من قائمة الأدوار، اختَر حسابات الخدمة > منشئ الرموز المميّزة لحساب الخدمة.

6. بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.

7. انقر على إنشاء. هو ملف 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);
}
    

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

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

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

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

لوحة البيانات الخاصة بالحالة في التقرير

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

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

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

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

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

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

في لوحة البيانات، يمكنك إجراء ما يلي:

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

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

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

الردود على الأخطاء

قد تتلقى أحد ردود الأخطاء التالية عند الاتصال Report State. وتكون هذه الردود على شكل رموز حالة HTTP.

• 400 Bad Request: تعذّر على الخادم معالجة الطلب الذي أرسله العميل بسبب بنية غير صالحة. من الأسباب الشائعة لتنسيق JSON غير صحيح أو استخدام null بدلاً من "" في قيمة السلسلة.
• 404 Not Found - تعذّر العثور على المورد المطلوب ولكنه قد يكون متاحًا في المستقبل. ويعني ذلك عادةً أنه لا يمكننا العثور على الجهاز المطلوب. قد يعني هذا أيضًا أنّ حساب المستخدم غير مرتبط بخدمة Google أو أننا تلقّينا agentUserId غير صالح. يُرجى التأكد من أنّ agentUserId يتطابق مع القيمة المقدَّمة في مزامنة، وأنّك تتعامل بشكل صحيح مع DISCONNECT.