Report State یک ویژگی مهم است که به Home Action اجازه میدهد بهجای انتظار QUERY
، آخرین وضعیت دستگاه کاربر را فعالانه به Google Home Graph گزارش دهد.
Report State به Google وضعیت دستگاه های کاربر با agentUserId
مشخص شده مرتبط با آنها را گزارش می دهد (ارسال شده در درخواست SYNC
اصلی). وقتی Google Assistant میخواهد اقدامی انجام دهد که نیاز به درک وضعیت فعلی یک دستگاه دارد، میتواند به سادگی اطلاعات وضعیت را در Home Graph بهجای ارسال یک QUERY
به ابرهای شخص ثالث قبل از صدور هدف EXECUTE
جستجو کند.
بدون Report State ، با توجه به چراغهای چندین ارائهدهنده در یک اتاق نشیمن، دستور Ok Google، روشن کردن اتاق نشیمن من مستلزم حل چندین هدف QUERY
ارسال شده به ابرهای متعدد است، برخلاف جستجوی ساده مقادیر روشنایی فعلی بر اساس آنچه قبلاً گزارش شده است. . برای بهترین تجربه کاربری، Assistant باید وضعیت فعلی دستگاه را داشته باشد، بدون اینکه نیازی به رفت و برگشت به دستگاه داشته باشد.
پس از SYNC
اولیه برای یک دستگاه، پلتفرم یک هدف QUERY
ارسال میکند که وضعیت دستگاه را جمعآوری میکند تا Home Graph را پر کند. پس از آن نقطه، Home Graph فقط حالتی را ذخیره می کند که با Report State ارسال می شود.
هنگام فراخوانی Report State ، مطمئن شوید که دادههای حالت کامل را برای یک ویژگی مشخص ارائه میکنید. نمودار Home Graph وضعیت ها را بر اساس هر صفت به روز می کند و هنگام برقراری تماس Report State ، همه داده های آن ویژگی را بازنویسی می کند. برای مثال، اگر وضعیت را برای ویژگی StartStop گزارش میدهید، payload باید مقادیری برای isRunning
و isPaused
داشته باشد.
شروع کنید
برای اجرای Report State ، مراحل زیر را دنبال کنید:
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 تماس بگیرید
یک گزینه را از برگه های زیر انتخاب کنید:
HTTP
Home Graph یک نقطه پایانی HTTP را ارائه می دهد
- از فایل JSON حساب سرویس دانلود شده برای ایجاد یک رمز وب JSON (JWT) استفاده کنید. برای اطلاعات بیشتر، احراز هویت با استفاده از حساب سرویس را ببینید.
- یک نشانه دسترسی OAuth 2.0 را با
https://www.googleapis.com/auth/homegraph
با استفاده از oauth2l دریافت کنید: - درخواست JSON را با
agentUserId
ایجاد کنید. در اینجا یک نمونه درخواست JSON برای گزارش وضعیت و اعلان آمده است: - وضعیت گزارش و اعلان JSON و نشانه موجود در درخواست HTTP POST خود را با نقطه پایانی Google Home Graph ترکیب کنید. در اینجا مثالی از نحوه ایجاد درخواست در خط فرمان با استفاده از
curl
به عنوان آزمایش آورده شده است:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
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 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', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
جاوا
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 state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
وضعیت گزارش تست
برای اینکه اقدام خود را برای صدور گواهی آماده کنید، مهم است که Report State آزمایش کنید.
برای انجام این کار، توصیه می کنیم از ابزار Home Graph Viewer استفاده کنید، که یک برنامه وب مستقل است که نیازی به دانلود یا استقرار ندارد.
داشبورد Report State هنوز در دسترس است، اما منسوخ شده و دیگر پشتیبانی نمیشود.
گزارش داشبورد ایالتی
پیش نیازها
قبل از اینکه بتوانید اقدام خود را آزمایش کنید، به Key Account Service و agentUserId
خود نیاز دارید. اگر از قبل کلید حساب سرویس و agentUserId
خود را دارید، به Deploy the Report State Dashboard مراجعه کنید.
داشبورد گزارش وضعیت را مستقر کنید
هنگامی که کلید حساب سرویس و شناسه کاربری عامل پروژه خود را دارید، آخرین نسخه را از داشبورد Report State دانلود و اجرا کنید. پس از دانلود آخرین نسخه، دستورالعملهای موجود در فایل README.MD
را دنبال کنید.
پس از استقرار داشبورد Report State ، از آدرس اینترنتی زیر به داشبورد دسترسی پیدا کنید (شناسه پروژه خود را جایگزین your_project_id کنید):
http://<your-project-id>.appspot.com
در داشبورد، موارد زیر را انجام دهید:
- فایل کلید حساب خود را انتخاب کنید
- agentUserId خود را اضافه کنید
سپس، روی فهرست کلیک کنید.
همه دستگاههای شما فهرست شدهاند. پس از پر شدن لیست، میتوانید از دکمه Refresh برای بهروزرسانی وضعیت دستگاه استفاده کنید. اگر وضعیت دستگاه تغییر کند، ردیف با رنگ سبز برجسته می شود.
پاسخ های خطا
هنگام تماس با Report State ممکن است یکی از پاسخ های خطای زیر را دریافت کنید. این پاسخ ها در قالب کدهای وضعیت HTTP ارائه می شوند.
-
400 Bad Request
- سرور نتوانست درخواست ارسال شده توسط مشتری را به دلیل نحو نامعتبر پردازش کند. دلایل رایج عبارتند از JSON نادرست یا استفاده ازnull
به جای "" برای مقدار رشته. -
404 Not Found
- منبع درخواستی یافت نشد اما ممکن است در آینده در دسترس باشد. به طور معمول، این بدان معنی است که ما نمی توانیم دستگاه درخواست شده را پیدا کنیم. همچنین ممکن است به این معنی باشد که حساب کاربری با Google مرتبط نیست یا یکagentUserId
نامعتبر دریافت کردهایم. مطمئن شوید کهagentUserId
با مقدار ارائه شده در پاسخ SYNC شما مطابقت دارد و به درستی مقاصد DISCONNECT را مدیریت می کنید.