حالة التقرير

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 (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" وهو تطبيق ويب مستقل لا يتطلب تنزيله أو نشره.

لا تزال لوحة تحكم 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 تتطابق مع القيمة المقدمة في عند SYNC الاستجابة، أنت على دراية بذلك. جارٍ معالجة أغراض إلغاء الربط.