إشعارات بشأن إجراءات المنزل المزوّد بأجهزة ذكية

تسمح الإشعارات لعملية دمج Cloud-to-cloud باستخدام Google Assistant للتواصل مع المستخدمين بشأن الأحداث أو التغييرات المهمة المتعلقة بالجهاز. يمكنك تنفيذ الإشعارات لتنبيه المستخدمين بأحداث الجهاز في الوقت المناسب، على سبيل المثال عندما يكون هناك شخص عند الباب، أو للإبلاغ عن تغيير مطلوب في حالة الجهاز، مثل عندما يتم قفل الباب بنجاح أو عندما يتعطل القفل.

يمكن أن يرسل دمج "Cloud-to-cloud" الأنواع التالية من الإشعارات إلى المستخدمين:

• الإشعارات الاستباقية: تنبّه المستخدم بحدث على جهاز smart home بدون أي طلبات سابقة من المستخدم إلى أجهزته، مثل رنين جرس الباب.

• الردود على طلبات المتابعة: تأكيد على نجاح أو فشل طلب تنفيذ أمر على الجهاز، مثل قفل الباب استخدِم هذه التنبيهات لأوامر الجهاز التي تستغرق وقتًا لإكمالها. لا تتوفّر الردود على طلبات المتابعة إلا عند إرسال طلبات الأوامر من مكبّرات الصوت الذكية والشاشات الذكية.

يقدّم "Assistant" هذه الإشعارات للمستخدمين كإشعارات على مكبّرات الصوت الذكية والشاشات الذكية. تكون الإشعارات الاستباقية غير مفعَّلة تلقائيًا. يمكن للمستخدمين تفعيل جميع الإشعارات الاستباقية أو إيقافها من خلال Google Home app (GHA).

الأحداث التي تؤدي إلى ظهور الإشعارات

عند وقوع أحداث على الجهاز، يرسل التنفيذ طلب إشعار إلى Google. تحدّد سمات الجهاز التي يتيحها دمج Cloud-to-cloud أنواع أحداث الإشعارات المتاحة والبيانات التي يمكنك تضمينها في هذه الإشعارات.

تتيح السمات التالية الإشعارات الاستباقية:

تتيح السمات التالية الردود على أسئلة المتابعة:

تتيح جميع أنواع الأجهزة إرسال الإشعارات للسمات السارية.

إنشاء إشعارات لعملية الدمج من السحابة الإلكترونية إلى السحابة الإلكترونية

يمكنك إضافة الإشعارات إلى عملية دمج Cloud-to-cloud في هذه المراحل:

1. أشِر إلى Google إذا كانت الإشعارات مفعَّلة من تطبيق التحكّم بجهاز آخر "smart home". إذا فعّل المستخدمون الإشعارات أو أوقفوها في تطبيقك، أرسِل طلب SYNC لإعلام Google بالتغيير في الجهاز.
2. عند وقوع حدث ذي صلة بالجهاز أو تغيير في الحالة يؤدي إلى ظهور إشعار، يمكنك إرسال طلب إشعار من خلال استدعاء واجهة برمجة تطبيقات Report State reportStateAndNotification. إذا تغيّرت حالة الجهاز، يمكنك إرسال حمولة الحالة والإشعار معًا في طلب Report State والإشعار.

تتناول الأقسام التالية هذه الخطوات بمزيد من التفصيل.

الإشارة إلى ما إذا كانت الإشعارات مفعَّلة في تطبيقك

يمكن للمستخدمين اختيار ما إذا كانوا يريدون تلقّي إشعارات استباقية من خلال تفعيل هذه الميزة في "GHA". في التطبيق الخاص بجهاز smart home، يمكنك أيضًا إضافة إمكانية تفعيل الإشعارات أو إيقافها بشكل صريح من الجهاز، على سبيل المثال، من إعدادات التطبيق.

أشِر إلى Google بأنّ الإشعارات مفعَّلة لجهازك من خلال إجراء طلب SYNC لتعديل بيانات الجهاز. يجب إرسال طلب SYNC مثل هذا كلما غيّر المستخدمون هذا الإعداد في تطبيقك.

في ردّك على SYNC، أرسِل أحد التعديلات التالية:

• إذا فعّل المستخدم الإشعارات صراحةً في تطبيق التحكّم بجهاز آخر، أو إذا لم توفّر خيار التبديل، اضبط السمة devices.notificationSupportedByAgent على true.
• إذا أوقف المستخدم الإشعارات صراحةً في تطبيق التحكّم بجهاز آخر، اضبط السمة devices.notificationSupportedByAgent على false.

يوضّح المقتطف التالي مثالاً على كيفية ضبط استجابة SYNC:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

إرسال طلبات الإشعارات إلى Google

لتفعيل الإشعارات على "Assistant"، يرسل تنفيذ الطلب حمولة إشعار إلى "Google Home Graph" من خلال طلب بيانات من واجهة برمجة التطبيقات Report State وNotification API.

تفعيل Google HomeGraph API

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

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

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

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

1. في Google Cloud Console، انتقِل إلى صفحة حسابات الخدمة.

   انتقِل إلى صفحة "حسابات الخدمة".

   قد تحتاج إلى اختيار مشروع قبل الانتقال إلى صفحة "حسابات الخدمة".

2. انقر على addإنشاء حساب خدمة.

3. في حقل اسم حساب الخدمة، أدخِل اسمًا.

4. في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.

5. في حقل وصف حساب الخدمة، أدخِل وصفًا.

6. انقر على إنشاء ومتابعة.

7. من القائمة المنسدلة الدور، اختَر حسابات الخدمة > أداة إنشاء الرمز المميّز لهوية OpenID Connect لحساب الخدمة.

8. انقر على متابعة.

9. انقر على تم.

10. اختَر حساب الخدمة الذي أنشأته للتو من قائمة حسابات الخدمة، ثم اختَر إدارة المفاتيح من قائمة more_vert الإجراءات.

11. انقر على إضافة مفتاح > إنشاء مفتاح جديد.

12. بالنسبة إلى نوع المفتاح، اختَر JSON.

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

إرسال الإشعار

أرسِل طلب الإشعار باستخدام واجهة برمجة التطبيقات devices.reportStateAndNotification. يجب أن يتضمّن طلب JSON السمة eventId، وهي معرّف فريد تنشئه منصتك للحدث الذي يؤدي إلى إرسال الإشعار. يجب أن يكون eventId رقم تعريف عشوائي يختلف في كل مرة ترسل فيها طلب إشعار.

في عنصر notifications الذي يتم تمريره في طلب البيانات من واجهة برمجة التطبيقات، يجب تضمين قيمة priority التي تحدّد طريقة عرض الإشعار. قد يتضمّن عنصر notifications حقولاً مختلفة حسب سمة الجهاز.

اتّبِع أحد المسارات التالية لضبط الحمولة واستدعاء واجهة برمجة التطبيقات:

• إرسال حمولة إشعار استباقي
• إرسال حمولة ردّ متابعة

إرسال حمولة إشعار استباقي

لطلب بيانات من واجهة برمجة التطبيقات، حدِّد خيارًا من إحدى علامات التبويب التالية:

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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    

إرسال حمولة استجابة للمتابعة

تحتوي الحمولة لردّ المتابعة على حالة الطلب ورموز الخطأ لأحداث الإخفاق، إن وُجدت، وfollowUpToken الصالحة التي تم تقديمها أثناء طلب الغرض EXECUTE. يجب استخدام followUpToken في غضون خمس دقائق ليظل صالحًا ولربط الردّ بالطلب الأصلي بشكل صحيح.

يعرض المقتطف التالي مثالاً على حمولة طلب EXECUTE مع حقل followUpToken.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

تستخدم Google السمة followUpToken لإخراج الإشعار فقط على الجهاز الذي كان المستخدم يتفاعل معه في الأصل، وليس لبثه على جميع أجهزة المستخدم.

لطلب بيانات من واجهة برمجة التطبيقات، حدِّد خيارًا من إحدى علامات التبويب التالية:

const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

// 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();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

التسجيل

تتيح الإشعارات تسجيل الأحداث كما هو موضّح في Cloud logging for Cloud-to-cloud. هذه السجلات مفيدة لاختبار جودة الإشعارات والحفاظ عليها ضمن الإجراء الخاص بك.

في ما يلي مخطط إدخال notificationLog:

يتضمّن الحقل status حالات مختلفة قد تشير إلى أخطاء في حمولة الإشعار. قد لا يتوفّر بعضها إلا في الإجراءات التي لم يتم إطلاقها في مرحلة الإنتاج.

تشمل الحالات النموذجية ما يلي:

بالإضافة إلى هذه الحالات العامة التي يمكن تطبيقها على جميع الإشعارات، قد يتضمّن الحقل status أيضًا حالات خاصة بالسمات حيثما ينطبق ذلك (على سبيل المثال، OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).