حالة التقرير

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

يُبلغ Report State Google بحالات أجهزة المستخدمين التي تتضمّن agentUserId المحدّد المرتبط بها (الذي تم إرساله في طلب SYNC الأصلي). عندما تريد خدمة Google Assistant تنفيذ إجراء يتطلّب معرفة الحالة الحالية للجهاز، بإمكانها ببساطة البحث عن معلومات الحالة في Home Graph بدلاً من إصدار intent 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 API
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 Viewer، وهي تطبيق ويب مستقل لا يتطلّب تنزيله أو نشره.

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

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

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

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

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

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

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

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

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

• اختيار ملف مفتاح الحساب
• أضِف agentUserId.

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

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

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

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

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