تتيح الإشعارات لـ "الإجراء" في "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" في المراحل التالية:
- يُرجى إبلاغ 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 API - اختَر المشروع الذي يتطابق مع رقم تعريف مشروع "smart home".
- انقر على تفعيل.
إنشاء مفتاح حساب الخدمة
يُرجى اتّباع هذه التعليمات لإنشاء مفتاح حساب خدمة من Google Cloud Console:
-
في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب خدمة.
الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة" - من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
- في حقل اسم حساب الخدمة، أدخِل اسمًا.
- في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.
من قائمة الدور، اختَر حسابات الخدمة >. منشئ الرمز المميّز لحساب الخدمة
بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.
- انقر على إنشاء. ملف JSON يحتوي على مفتاحك عمليات التنزيل على جهاز الكمبيوتر.
إرسال الإشعار
يمكنك الاتصال بطلب الإشعار باستخدام
devices.reportStateAndNotification
API.
يجب أن يحتوي طلب 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 Home Graph. فيما يلي مثال على كيف
إرسال الطلب في سطر الأوامر باستخدام
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 API من Google عمليات ربط لواجهة برمجة تطبيقات 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 للغة Java عمليات ربط لواجهة برمجة تطبيقات 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
الصالحة
المقدمة أثناء طلب النية 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 Home Graph. فيما يلي مثال على كيف
إرسال الطلب في سطر الأوامر باستخدام
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 API من Google عمليات ربط لواجهة برمجة تطبيقات 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 للغة Java عمليات ربط لواجهة برمجة تطبيقات 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);
التسجيل
تتيح الإشعارات تسجيل الأحداث على النحو المبيَّن في مقالة الوصول إلى سجلّات الأحداث باستخدام تسجيل الأحداث في السحابة الإلكترونية. هذه السجلات مفيدة للاختبار والحفاظ على جودة الإشعارات داخل الإجراء الخاص بك.
في ما يلي مخطط لإدخال 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
).