مرحبًا بك في "مركز مطوّري برامج Google Home"، وجهتك الجديدة لتعلّم كيفية تطوير إجراءات منزلية ذكية. ملاحظة: ستواصل إنشاء الإجراءات في وحدة تحكم الإجراءات.

حالة التقرير

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
في YouTube، يمكنك

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 API

  1. في Google Cloud Console , go to the HomeGraph API page.

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

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

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

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

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

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

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

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