حالة التقرير

Report State ميزة مهمة تسمح للإجراء Home بالإبلاغ بشكل استباقي عن أحدث حالة لجهاز المستخدم حتى Google Home Graph rather than waiting for a QUERY intent.

تُبلِغ Report State Google عن حالات أجهزة المستخدمين مع agentUserId المحدّدة المرتبطة بها (تم إرسالها في طلب SYNC الأصلي). الوقت المناسب Google Assistant wants to take an action that requires understanding the current state of a device, it can simply look up the state information in the Home Graph instead of issuing a QUERY intent to various third-party clouds prior to issuing the EXECUTE intent.

بدون استخدام Report State، مع الأخذ في الاعتبار المصابيح من عدّة مزوّدين في غرفة المعيشة، يتطلّب الأمر Ok Google, Brighting my المعيشة في غرفة النوم حلّ عدة أغراض من QUERY تم إرسالها إلى عدّة سحب، بدلاً من البحث عن قيم السطوع الحالية بناءً على ما تم الإبلاغ عنه سابقًا. لتحقيق أفضل تجربة للمستخدم، يحتاج Assistant إلى معرفة الحالة الحالية للجهاز، بدون الحاجة إلى الذهاب ذهابًا وإيابًا إلى الجهاز.

بعد SYNC الأوليّ للجهاز، تُرسل المنصة النظام QUERY intent الذي يجمع حالة الجهاز لتعبئة 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 , go to the HomeGraph API page.

   الانتقال إلى صفحة واجهة برمجة التطبيقات HomeGraph
2. اختَر المشروع الذي يتطابق مع smart home project ID.
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

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

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

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

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

إجابات الأخطاء

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

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