حالة التقرير

المحتوى

إنّ ميزة 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 API

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

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

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

اتّبِع هذه التعليمات لإنشاء مفتاح حساب خدمة من Google Cloud Console:

ملاحظة: تأكَّد من استخدام مشروع Google Cloud Platform الصحيح عند تنفيذ هذه الخطوات. هذا هو المشروع الذي يطابق رقم تعريف مشروع smart home الخاص بك.
  1. في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب الخدمة.

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

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

  7. انقر على إنشاء. ملف JSON يحتوي على المفتاح الذي يتم تنزيله على جهاز الكمبيوتر.

استدعاء واجهة برمجة التطبيقات

حدِّد خيارًا من علامات التبويب أدناه:

HTTP

توفر Home Graph نقطة نهاية HTTP

  1. يمكنك استخدام ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). ولمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب الخدمة.
  2. يمكنك الحصول على رمز دخول OAuth 2.0 من خلال نطاق https://www.googleapis.com/auth/homegraph باستخدام oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. أنشِئ طلب JSON باستخدام agentUserId. إليك نموذج طلب JSON لحالة التقرير والإشعار:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. يمكنك دمج حالة التقرير والإشعار JSON والرمز المميز في طلب HTTP POST في نقطة نهاية Google Home Graph. في ما يلي مثال على كيفية إنشاء الطلب في سطر الأوامر باستخدام curl كاختبار:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

توفر Home Graph نقطة نهاية gRPC

  1. يمكنك الحصول على تعريف خدمة المخازن المؤقتة للبروتوكول لواجهة برمجة التطبيقات Home Graph.
  2. اتّبِع مستندات المطوِّر الخاصة بـ gRPC لإنشاء رموز برمجية للعميل لإحدى اللغات المعتمَدة.
  3. عليك استدعاء الإجراء ReportStateAndNotification.

Node.js

يوفر عميل Node.js في Google APIs روابط لواجهة برمجة تطبيقات Home Graph.

  1. اضبط خدمة google.homegraph باستخدام بيانات الاعتماد التلقائية للتطبيق.
  2. عليك استدعاء الإجراء reportStateAndNotification باستخدام ReportStateAndNotificationRequest. وتعرض Promise مع ReportStateAndNotificationResponse.
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
          }
        }
      }
    }
  }
});
    

Java

توفّر مكتبة برامج Home Graph API للغة Java روابط لواجهة برمجة التطبيقات Home Graph.

  1. اضبط HomeGraphApiService باستخدام بيانات الاعتماد التلقائية للتطبيق.
  2. عليك استدعاء طريقة reportStateAndNotification باستخدام ReportStateAndNotificationRequest. وتعرض ReportStateAndNotificationResponse.
  // 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

في لوحة البيانات، قم بما يلي:

  • اختيار ملف مفتاح حسابك
  • إضافة رقم تعريف الوكيل (UserId) الخاص بك

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

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

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

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

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