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

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

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

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

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

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

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

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

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

سمة فعاليات
ObjectDetection الأشياء التي يرصدها الجهاز، مثلاً عند التعرّف على وجه عند الباب. على سبيل المثال: "يوسف وهبة عند الباب الأمامي".
RunCycle يكمل الجهاز دورة. على سبيل المثال: "دورة غسّالة الملابس" قد اكتمل".
SensorState يرصد الجهاز حالة جهاز استشعار متوافقة. مثل: "رصد دخان الدخان"

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

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

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

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

أضِف إشعارات إلى الإجراء "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 API. يجب أن يحتوي طلب 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 API من Google عمليات ربط لواجهة برمجة تطبيقات 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 API من Google عمليات ربط لواجهة برمجة تطبيقات 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).