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

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

يمكن أن يرسل إجراء smart home الأنواع التالية من الإشعارات إلى المستخدمين:

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

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

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

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

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

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

السمة فعاليات
ObjectDetection الأغراض التي يرصدها الجهاز، مثلاً عند رصد وجه تم التعرّف عليه عند الباب مثال: "سلمى ويوسف عند الباب الأمامي"
RunCycle يُكمل الجهاز دورة. على سبيل المثال: "لقد انتهت دورة تشغيل الغسّالة".
SensorState يرصد الجهاز حالة أداة استشعار متوافقة. على سبيل المثال: "رصَد جهاز كشف الدخان".
TemperatureControl عندما يصل الجهاز إلى نقطة ضبط درجة الحرارة على سبيل المثال: "تم تسخين الفرن مسبقًا على 350 درجة".
ArmDisarm يدخل النظام في وضع ما قبل الإنذار من خلال عد تنازلي يبدأ نشاطه من خلال باب مفتوح.
CameraStream رابط يؤدي إلى البث المباشر للكاميرا بعد أن يرصد الجهاز جسمًا أو حركة.
MotionDetection "تم رصد حركة في 1 تموز (يوليو) 2020 عند الساعة 12 ظهرًا."

تدعم السمات التالية ردود المتابعة:

السمة فعاليات
ArmDisarm تغيير حالة الإكمال والحالة بعد تنفيذ أمر جهاز action.devices.commands.ArmDisarm. على سبيل المثال: "تم تفعيل جهاز الأمن الشخصي".
LockUnlock تغيير حالة الإكمال والحالة بعد تنفيذ أمر جهاز action.devices.commands.LockUnlock. على سبيل المثال: "الباب الأمامي تم قفله" أو "الباب الأمامي عالق".
NetworkControl تغيير حالة الإكمال والحالة بعد تنفيذ أمر جهاز action.devices.commands.TestNetworkSpeed. مثال: "انتهى اختبار سرعة الشبكة. وتبلغ سرعة التنزيل على جهاز التوجيه في المكتب حاليًا 80.2 كيلوبت في الثانية، وسرعة التحميل هي 9.3 كيلوبت في الثانية."
OpenClose تغيير حالة الإكمال والحالة بعد تنفيذ أمر جهاز action.devices.commands.OpenClose. على سبيل المثال: "تم فتح الباب الأمامي" أو "تعذّر فتح الباب الأمامي"
StartStop تغيير حالة الإكمال والحالة بعد تنفيذ أمر جهاز action.devices.commands.StartStop. مثال: "تم تشغيل المكنسة الكهربائية".

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

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

يمكنك إضافة إشعارات إلى إجراء "smart home" في المراحل التالية:

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

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

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

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

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

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

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

ويوضح المقتطف التالي مثالاً لكيفية ضبط استجابة المزامنة:

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:

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

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

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

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

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

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

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

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

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

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

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 للنطاق Report State والإشعار:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. يمكنك دمج Report State والإشعار 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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

Java

توفّر مكتبة برامج HomeGraph 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 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 لإخراج الإشعار فقط على الجهاز الذي كان يتفاعل معه المستخدم في الأصل، وليس على جميع أجهزة المستخدم.

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

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 للنطاق Report State والإشعار:
  5. {
      "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": "PLACEHOLDER",
                  "networkDownloadSpeedMbps": 23.3,
                  "networkUploadSpeedMbps": 10.2
                }
              }
            }
          }
        }
      }
    }
    
  6. يمكنك دمج Report State والإشعار 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 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,
              }
            }
          }
        }
      }
    }
  }
});
    

Java

توفّر مكتبة برامج HomeGraph 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();

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

التسجيل

تتوافق الإشعارات مع تسجيل الأحداث على النحو الموضَّح في الوصول إلى سجلّات الأحداث باستخدام "التسجيل في السحابة الإلكترونية". هذه السجلات مفيدة لاختبار جودة الإشعارات والحفاظ عليها ضمن الإجراء الخاص بك.

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

الموقع الوصف
requestId رقم تعريف طلب الإشعار.
structName اسم بنية الإشعار، مثل ObjectDetection
status يشير إلى حالة الإشعار.

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

تشمل الأمثلة على الحالات ما يلي:

الحالة الوصف
EVENT_ID_MISSING تشير هذه السمة إلى أنّ الحقل eventId المطلوب غير متوفّر.
PRIORITY_MISSING يشير إلى أنّ الحقل priority غير متوفّر.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE يشير إلى أنّ خاصية notificationSupportedByAgent لجهاز إرسال الإشعارات المقدّمة في SYNC غير صحيحة.
NOTIFICATION_ENABLED_BY_USER_FALSE تشير إلى أنّ المستخدم لم يفعّل الإشعارات على الجهاز الذي يُرسل الإشعارات في GHA. لا تتوفّر هذه الحالة إلا على الإجراءات التي لم يتم إطلاقها في مرحلة الإنتاج.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE يشير هذا الرمز إلى أنّ المستخدم لم يختص في المنزل/البنية باستخدام جهاز إرسال الإشعارات. لا تتوفّر هذه الحالة إلا على الإجراءات التي لم يتم إطلاقها في مرحلة الإنتاج.

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