حالة التقرير

<a href="/intl/ar/ads/">البرنامج الإعلاني</a>

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
  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. إليك مثال على كيفية تقديم الطلب في سطر الأوامر باستخدام 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 API.
  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

توفّر مكتبة برامج HomeGraph API للغة Java روابط إلى Home Graph API.

  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

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

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

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

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

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

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

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