اعلانها به Action smart home شما اجازه میدهند از Google Assistant برای برقراری ارتباط با کاربران درباره رویدادها یا تغییرات مهم مرتبط با دستگاه استفاده کند. میتوانید اعلانهایی را برای هشدار به کاربران در مورد رویدادهای بهموقع دستگاه، بهعنوان مثال زمانی که شخصی در درب منزل است، یا گزارش در مورد تغییر وضعیت دستگاه درخواستی، مانند زمانی که پیچ قفل در با موفقیت درگیر شده یا گیر کرده است، اجرا کنید.
اکشن smart home شما میتواند انواع اعلانهای زیر را برای کاربران ارسال کند:
اعلانهای پیشگیرانه : به کاربر از رویداد دستگاه smart home بدون هیچ درخواست قبلی از دستگاههای خود، مانند زنگ در، هشدار میدهد.
پاسخهای بعدی : تأیید موفقیت یا شکست درخواست فرمان دستگاه، برای مثال هنگام قفل کردن یک در. از این هشدارها برای دستورات دستگاه استفاده کنید که تکمیل آنها زمان بر است. پاسخهای پیگیری تنها زمانی پشتیبانی میشوند که درخواستهای فرمان دستگاه از بلندگوهای هوشمند و نمایشگرهای هوشمند ارسال شوند.
Assistant این اعلانها را بهعنوان اعلانهایی روی بلندگوهای هوشمند و نمایشگرهای هوشمند در اختیار کاربران قرار میدهد. اعلان های فعال به طور پیش فرض خاموش هستند. کاربران میتوانند همه اعلانهای فعال را از Google Home app (GHA) روشن یا خاموش کنند.
رویدادهایی که اعلانها را راهاندازی میکنند
وقتی رویدادهای دستگاه رخ میدهد، Action përmbush شما یک درخواست اعلان به Google ارسال میکند. ویژگیهای دستگاهی که Action 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 خود اضافه کنید:
- اگر اعلانها از برنامه دستگاه smart home شما فعال است، به Google نشان دهید. اگر کاربران اعلانها را در برنامه شما روشن یا خاموش میکنند، یک درخواست
SYNC
ارسال کنید تا Google را از تغییر دستگاه مطلع کنید. - هنگامی که یک رویداد یا تغییر وضعیت مربوط به دستگاه رخ می دهد که باعث ایجاد اعلان می شود، با تماس با Report State
reportStateAndNotification
API یک درخواست اعلان ارسال کنید. اگر وضعیت دستگاه تغییر کرد، میتوانید هر دو حالت و اعلان را در تماس Report State و اعلان ارسال کنید.
بخش های زیر این مراحل را با جزئیات بیشتری پوشش می دهند.
مشخص کنید که آیا اعلان ها در برنامه شما فعال هستند یا خیر
کاربران می توانند با فعال کردن این ویژگی در GHA انتخاب کنند که آیا می خواهند اعلان های پیشگیرانه را دریافت کنند. در برنامه دستگاه smart home خود، همچنین میتوانید به صورت اختیاری این قابلیت را برای کاربران اضافه کنید که به طور صریح اعلانها را از دستگاه، به عنوان مثال، از تنظیمات برنامه خود تغییر دهند.
با برقراری تماس درخواست SYNC برای بهروزرسانی دادههای دستگاه، به Google نشان دهید که اعلانها برای دستگاه شما فعال هستند. هر زمان که کاربران این تنظیم را در برنامه شما تغییر دهند، باید درخواست SYNC
مانند این ارسال کنید.
در پاسخ SYNC
، یکی از این بهروزرسانیها را ارسال کنید:
- اگر کاربر صراحتاً اعلانها را در برنامه دستگاه شما روشن کرده است، یا اگر گزینه جابجایی را ارائه نمیدهید، ویژگی
devices.notificationSupportedByAgent
را رویtrue
تنظیم کنید. - اگر کاربر صراحتاً اعلانها را در برنامه دستگاه شما خاموش کرد، ویژگی
devices.notificationSupportedByAgent
را رویfalse
تنظیم کنید.
قطعه زیر نمونه ای از نحوه تنظیم پاسخ SYNC را نشان می دهد:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
درخواستهای اعلان را به Google ارسال کنید
برای فعال کردن اعلانها در Assistant ، اجرای شما یک بار اعلان را از طریق یک تماس Report State و API اعلان به Google Home Graph ارسال میکند.
Google HomeGraph API را فعال کنید
در Google Cloud Console ، به صفحه HomeGraph API بروید.
به صفحه HomeGraph API بروید- پروژه ای را انتخاب کنید که با شناسه پروژه smart home شما مطابقت دارد.
- روی ENABLE کلیک کنید.
یک کلید حساب سرویس ایجاد کنید
برای ایجاد یک کلید حساب سرویس از Google Cloud Console این دستورالعمل ها را دنبال کنید:
در Google Cloud Console ، به صفحه کلید ایجاد حساب سرویس بروید.
به صفحه Create Service Account Key بروید- از لیست حساب سرویس ، حساب سرویس جدید را انتخاب کنید.
- در قسمت نام حساب سرویس ، یک نام وارد کنید.
- در قسمت شناسه حساب سرویس ، یک شناسه وارد کنید.
از فهرست نقش ، حسابهای خدمات > ایجاد کننده رمز حساب حساب را انتخاب کنید.
برای نوع کلید ، گزینه JSON را انتخاب کنید.
- روی ایجاد کلیک کنید. یک فایل JSON که حاوی دانلودهای کلید شما در رایانه شما است.
اطلاعیه را ارسال کنید
تماس درخواست اعلان را با استفاده از API devices.reportStateAndNotification
برقرار کنید. درخواست JSON شما باید شامل یک eventId
باشد که یک شناسه منحصربهفرد است که توسط پلتفرم شما برای رویدادی که اعلان را راهاندازی میکند ایجاد میکند. eventId
باید یک شناسه تصادفی باشد که هر بار که درخواست اعلان ارسال می کنید متفاوت باشد.
در شی notifications
که در تماس API خود ارسال میکنید، یک مقدار priority
قرار دهید که نحوه ارائه اعلان را مشخص میکند. بسته به ویژگی دستگاه، شی notifications
شما ممکن است شامل فیلدهای مختلفی باشد.
برای تنظیم بار و فراخوانی API یکی از این مسیرها را دنبال کنید:
ارسال یک محموله اعلان پیشگیرانه
برای فراخوانی API، یکی از این تب ها را انتخاب کنید:
HTTP
Home Graph API یک نقطه پایانی 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 API یک نقطه پایانی gRPC را ارائه می دهد
- تعریف سرویس بافرهای پروتکل را برای Home Graph API دریافت کنید.
- مستندات توسعهدهنده gRPC را دنبال کنید تا برای یکی از زبانهای پشتیبانیشده، خرد کلاینت ایجاد کنید.
- با روش ReportStateAndNotification تماس بگیرید.
Node.js
Google APIs Node.js Client اتصالاتی را برای Home Graph API فراهم می کند.
- سرویس
google.homegraph
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
reportStateAndNotification
را با ReportStateAndNotificationRequest فراخوانی کنید. با ReportStateAndNotificationResponse یکPromise
برمی گرداند.
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 } } } } } } } });
جاوا
HomeGraph API Client Library برای جاوا اتصالاتی را برای Home Graph API فراهم می کند.
-
HomeGraphApiService
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
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
request payload را با فیلد 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
استفاده میکند تا اعلان را فقط در دستگاهی که کاربر در ابتدا با آن تعامل داشت، ارسال کند و در همه دستگاههای کاربر پخش نشود.
برای فراخوانی API، یکی از این تب ها را انتخاب کنید:
HTTP
Home Graph API یک نقطه پایانی 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 API یک نقطه پایانی gRPC را ارائه می دهد
- تعریف سرویس بافرهای پروتکل را برای Home Graph API دریافت کنید.
- مستندات توسعهدهنده gRPC را دنبال کنید تا برای یکی از زبانهای پشتیبانیشده، خرد کلاینت ایجاد کنید.
- با روش ReportStateAndNotification تماس بگیرید.
Node.js
Google APIs Node.js Client اتصالاتی را برای Home Graph API فراهم می کند.
- سرویس
google.homegraph
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
reportStateAndNotification
را با ReportStateAndNotificationRequest فراخوانی کنید. با ReportStateAndNotificationResponse یکPromise
برمی گرداند.
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, } } } } } } } });
جاوا
HomeGraph API Client Library برای جاوا اتصالاتی را برای Home Graph API فراهم می کند.
-
HomeGraphApiService
را با استفاده از Application Default Credentials راه اندازی کنید - روش
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);
ورود به سیستم
اعلانها از ثبت رویداد پشتیبانی میکنند، همانطور که در گزارشهای رویداد Access با Cloud Logging مشخص شده است. این گزارشها برای آزمایش و حفظ کیفیت اعلانها در Action شما مفید هستند.
شکل زیر طرح یک ورودی notificationLog
است:
اموال | توضیحات |
---|---|
requestId | شناسه درخواست اعلان |
structName | نام ساختار اعلان، مانند "ObjectDetection". |
status | وضعیت اعلان را نشان می دهد. |
فیلد status
شامل وضعیت های مختلفی است که ممکن است نشان دهنده خطا در بار اعلان باشد. برخی از این موارد ممکن است فقط در Actions در دسترس باشند که برای تولید راه اندازی نشده اند.
وضعیت های مثال عبارتند از:
وضعیت | توضیحات |
---|---|
EVENT_ID_MISSING | نشان می دهد که قسمت eventId مورد نیاز وجود ندارد. |
PRIORITY_MISSING | نشان می دهد که یک فیلد priority وجود ندارد. |
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE | نشان می دهد که ویژگی notificationSupportedByAgent دستگاه اعلان ارائه شده در SYNC نادرست است. |
NOTIFICATION_ENABLED_BY_USER_FALSE | نشان می دهد که کاربر اعلان ها را در دستگاه اعلان در GHA فعال نکرده است. این وضعیت فقط در Actions موجود است که برای تولید راه اندازی نشده اند. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE | نشان می دهد که کاربر دستگاه اعلان را به خانه/ساختار اختصاص نداده است. این وضعیت فقط در Actions موجود است که برای تولید راه اندازی نشده اند. |
علاوه بر این وضعیتهای عمومی که میتوانند برای همه اعلانها اعمال شوند، فیلد status
ممکن است در صورت لزوم شامل وضعیتهای خاص باشد (مانند OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).