تتيح الإشعارات لـ smart home اتخاذ إجراء باستخدام Google Assistant للتواصل مع المستخدمين بشأن الأحداث أو التغييرات المهمة ذات الصلة بالأجهزة. يمكنك تنفيذ إشعارات لتنبيه المستخدمين بشأن أحداث الجهاز في الوقت المناسب، مثلاً عندما يكون أحدهم عند الباب أو للإبلاغ عن تغيير في حالة الجهاز المطلوبة، مثلاً عندما يتم تفعيل برغي قفل الباب أو عندما يكون عالِقًا.
يمكن أن يؤدي الإجراء smart home إلى إرسال أنواع الإشعارات التالية إلى المستخدمين:
الإشعارات الاستباقية: تنبه المستخدم إلى حدث smart home جهاز بدون أي طلبات سابقة من المستخدمين على أجهزته، مثل جرس الباب.
ردود المتابعة: تأكيد لتأكيد أنّ طلب الجهاز قد نجح أو تعذّر، مثلاً عندما يتم قفل أحد الأبواب. يمكنك استخدام هذه التنبيهات لتوجيهات الأجهزة التي تستغرق بعض الوقت لإكمالها. لا تتوفّر ردود المتابعة إلا عندما يتم إرسال طلبات أوامر الجهاز من مكبرات الصوت الذكية والشاشات الذكية.
Assistant يقدّم هذه الإشعارات للمستخدمين من خلال إشعارات على مكبّرات الصوت الذكية والشاشات الذكية. تكون الإشعارات الاستباقية غير مفعّلة تلقائيًا. يمكن للمستخدمين تفعيل كل الإشعارات الاستباقية أو إيقافها من Google Home app (GHA).
الأحداث التي تؤدي إلى ظهور الإشعارات
عند وقوع أحداث على الجهاز، يرسل تنفيذ الإجراء طلب إشعار إلى Google. يحدّد السمات التي يوفّرها الإجراء smart home الخاص بك أنواع الأحداث المتاحة الإشعارات والبيانات التي يمكنك تضمينها في هذه الإشعارات.
تتوافق السمات التالية مع الإشعارات الاستباقية:
سمة | فعاليات |
---|---|
رصد العناصر | الأشياء التي يرصدها الجهاز، مثلاً عندما يتم رصد وجه محدَّد عند الباب على سبيل المثال: "منى ويوسف عند الباب الأمامي". |
RunCycle | الجهاز يُكمل دورة. على سبيل المثال: "انتهت دورة الغسّالة". |
SensorState | يرصد الجهاز حالة جهاز استشعار متوافقة. على سبيل المثال: "كاشِف الدخان يرصد الدخان". |
التحكّم في درجة الحرارة | وصول الجهاز إلى درجة الحرارة المطلوبة على سبيل المثال: "تم التدفئة مسبقًا للفرن إلى 350 درجة". |
إيقاف جهاز الإنذار | يُدخل النظام حالة "منبّه مسبقًا" مع عد تنازلي يبدأ بباب مفتوح. |
كاميرا البث | لإنشاء رابط إلى البث المباشر للكاميرا بعد رصد الجهاز أو أي حركة. |
كشف الحركة | "تم رصد حركة في الساعة 12 ظهرًا في 1 تموز (يوليو) 2020". |
تتيح السمات التالية ردود المتابعة:
سمة | فعاليات |
---|---|
إيقاف جهاز الإنذار | بعد اكتمال أمر الجهاز action.devices.commands.ArmDisarm ، ستظهر حالة الإضافة والحالة. على سبيل المثال:
"تم تفعيل نظام الأمان".
|
قفل القفل | بعد اكتمال أمر الجهاز action.devices.commands.LockUnlock ، ستظهر حالة الإضافة والحالة. على سبيل المثال: "تم قفل الباب الأمامي" أو "الباب الأمامي عالِق".
|
التحكّم في الشبكة | بعد اكتمال أمر الجهاز action.devices.commands.TestNetworkSpeed ، ستظهر حالة الإضافة والحالة. على سبيل المثال: "انتهى اختبار سرعة الشبكة. إنّ سرعة التنزيل على
جهاز توجيه المكتب هي 80.2 كيلوبت في الثانية حاليًا، وسرعة التحميل هي 9.3 كيلوبت في الثانية."
|
OpenClose | بعد اكتمال أمر الجهاز action.devices.commands.OpenClose ، ستظهر حالة الإضافة والحالة. على سبيل المثال: "تم فتح الباب الأمامي" أو "تعذّر فتح الباب الأمامي".
|
بدء الإيقاف | بعد اكتمال أمر الجهاز action.devices.commands.StartStop ، ستظهر حالة الإضافة والحالة. على سبيل المثال: "تم بدء المكنسة".
|
توفّر جميع أنواع الأجهزة إشعارات للسمات السارية.
إنشاء إشعارات لإجراءات المنزل الذكية
أضِف إشعارات إلى الإجراء smart home في هذه المراحل:
- أشِر إلى Google في حال تفعيل الإشعارات من
تطبيق الجهاز smart home. وإذا فعَّل المستخدمون الإشعارات أو أوقفها
في تطبيقك، أرسِل طلب
SYNC
لإعلام Google بتغيير الجهاز. - عند حدوث حدث ذي صلة بالجهاز أو تغيير في الحالة يؤدي إلى ظهور إشعار، يمكنك إرسال طلب إشعار من خلال الاتصال بواجهة برمجة التطبيقات 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
-
في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.
الانتقال إلى صفحة واجهة برمجة التطبيقات HomeGraph - اختَر المشروع الذي يطابق رقم تعريف مشروع smart home.
- انقر على تفعيل.
إنشاء مفتاح لحساب الخدمة
يُرجى اتّباع التعليمات التالية لإنشاء مفتاح حساب خدمة من Google Cloud Console:
-
في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب الخدمة.
الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة" - من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
- في حقل اسم حساب الخدمة، أدخِل اسمًا.
- في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.
من قائمة الأدوار، اختَر حسابات الخدمة > منشئ الرموز المميّزة لحساب الخدمة.
بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.
- انقر على إنشاء. هو ملف JSON يحتوي على عمليات تنزيل المفتاح على جهاز الكمبيوتر.
إرسال الإشعار
يمكنك إجراء طلب الحصول على إشعار باستخدام واجهة برمجة التطبيقات
devices.reportStateAndNotification
.
يجب أن يتضمّن طلب JSON السمة eventId
، وهي عبارة عن معرّف فريد يتم إنشاؤه بواسطة النظام الأساسي الخاص بك للحدث الذي يؤدي إلى ظهور الإشعار. يجب أن تكون السمة eventId
معرّفًا عشوائيًا يختلف في كل مرة ترسل فيها طلب إشعار.
في العنصر notifications
الذي تمرِّره في طلب البيانات من واجهة برمجة التطبيقات، يمكنك تضمين قيمة
priority
التي تحدّد كيفية عرض الإشعار. قد يتضمن الكائن notifications
حقولاً مختلفة حسب سمة الجهاز.
اتّبِع أحد المسارات التالية لضبط الحمولة واستدعاء واجهة برمجة التطبيقات:
إرسال حمولة استباقية للإشعارات
لاستدعاء واجهة برمجة التطبيقات، حدّد خيارًا من إحدى علامات التبويب التالية:
HTTP
توفّر واجهة برمجة التطبيقات Home Graph نقطة نهاية HTTP.
- استخدِم ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). لمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب خدمة.
- يمكنك الحصول على رمز الدخول عبر بروتوكول OAuth 2.0 باستخدام نطاق
https://www.googleapis.com/auth/homegraph
باستخدام oauth2l: - يمكنك إنشاء طلب JSON باستخدام
agentUserId
. إليك نموذج طلب JSON لـ Report State والإشعار: - عليك دمج Report State والرمز JSON الخاص بالإشعارات والرمز المميّز في طلب HTTP POST إلى نقطة نهاية "الرسم البياني للمنزل" من Google. إليك مثال على كيفية تقديم الطلب في سطر الأوامر باستخدام
curl
:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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.
- ويمكنك الحصول على تعريف خدمة مخازن البروتوكولات المؤقتة لواجهة برمجة التطبيقات Home Graph.
- اتّبِع مستندات مطوِّري برامج gRPC لإنشاء رموز عميل بديلة لإحدى اللغات المعتمَدة.
- يجب استدعاء طريقة ReportStateAndNotification.
Node.js
يوفّر عميل Node.js في Google APIs روابط لواجهة برمجة التطبيقات Home Graph.
- عليك إعداد خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - يمكنك استدعاء الطريقة
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 للغة روابط تؤدي إلى واجهة برمجة التطبيقات Home Graph.
- عليك إعداد
HomeGraphApiService
باستخدام بيانات الاعتماد التلقائية للتطبيق. - يمكنك استدعاء طريقة
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
الصالحة، التي تم تقديمها أثناء طلب intent في 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.
- استخدِم ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). لمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب خدمة.
- يمكنك الحصول على رمز الدخول عبر بروتوكول OAuth 2.0 باستخدام نطاق
https://www.googleapis.com/auth/homegraph
باستخدام oauth2l: - يمكنك إنشاء طلب JSON باستخدام
agentUserId
. إليك نموذج طلب JSON لـ Report State والإشعار: - عليك دمج Report State والرمز JSON الخاص بالإشعارات والرمز المميّز في طلب HTTP POST إلى نقطة نهاية "الرسم البياني للمنزل" من Google. إليك مثال على كيفية تقديم الطلب في سطر الأوامر باستخدام
curl
:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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.
- ويمكنك الحصول على تعريف خدمة مخازن البروتوكولات المؤقتة لواجهة برمجة التطبيقات Home Graph.
- اتّبِع مستندات مطوِّري برامج gRPC لإنشاء رموز عميل بديلة لإحدى اللغات المعتمَدة.
- يجب استدعاء طريقة ReportStateAndNotification.
Node.js
يوفّر عميل Node.js في Google APIs روابط لواجهة برمجة التطبيقات Home Graph.
- عليك إعداد خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - يمكنك استدعاء الطريقة
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 للغة روابط تؤدي إلى واجهة برمجة التطبيقات Home Graph.
- إعداد
HomeGraphApiService
باستخدام بيانات الاعتماد التلقائية للتطبيق - يمكنك استدعاء طريقة
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);
التسجيل
وتتيح الإشعارات تسجيل الأحداث كما هو موضَّح في سجلّات أحداث الوصول من خلال Cloud Logging. تُعدّ هذه السجلّات مفيدة لاختبار جودة الإشعارات والحفاظ عليها ضمن الإجراء الذي تتخذه.
في ما يلي مخطّط إدخال 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
).