«درخواست همگام‌سازی» برای هر کاربر Google که دستگاه‌هایش agentUserId مشخص‌شده را داشته باشند (که در درخواست SYNC اصلی ارسال کرده‌اید)، درخواست SYNC را برای تحقق شما راه‌اندازی می‌کند. این کار به شما امکان می‌دهد دستگاه‌های کاربران را
بدون لغو پیوند و پیوند مجدد حسابشان به‌روز کنید. همه کاربران پیوندشده به این شناسه، درخواست SYNC دریافت خواهند کرد.
باید درخواست SYNC را راه‌اندازی کنید:
- اگر کاربر دستگاه جدیدی اضافه کند.
- اگر کاربر دستگاه موجودی را بردارد.
- اگر کاربر نام دستگاه موجودی را تغییر دهد.
- اگر نوع دستگاه یا مشخصه جدیدی را پیاده‌سازی کنید یا ویژگی دستگاه جدیدی را اضافه کنید.
شروع کنید
برای پیاده‌سازی «درخواست همگام‌سازی»، این مراحل را دنبال کنید:
فعال کردن Google HomeGraph API
-
در Google Cloud Console، به صفحه HomeGraph API بروید.
رفتن به صفحه HomeGraph API - پروژه‌ای را که با شناسه پروژه smart home شما مطابقت دارد انتخاب کنید.
- روی فعال کردن کلیک کنید.
ایجاد کردن کلید حساب سرویس
برای تولید کلید حساب سرویس از Google Cloud Console، این دستورالعمل‌ها را دنبال کنید:
-
در Google Cloud Console، به صفحه حساب‌های سرویس بروید.
به صفحه «حساب‌های سرویس» بروید.شاید لازم باشد پروژه‌ای را انتخاب کنید تا به صفحه «حساب‌های سرویس» هدایت شوید.
روی ایجاد حساب سرویس کلیک کنید.
در فیلد نام حساب سرویس، نامی وارد کنید.
در فیلد شناسه حساب سرویس، شناسه‌ای وارد کنید.
در فیلد شرح حساب سرویس، شرحی وارد کنید.
روی ایجاد و ادامه کلیک کنید.
از منوِ کرکره‌ای نقش، حساب‌های سرویس > ایجادکننده شناسه توکن OpenID Connect حساب سرویس را انتخاب کنید.
روی ادامه کلیک کنید.
روی تمام کلیک کنید.
حساب سرویسی را که به‌تازگی ایجاد کرده‌اید از فهرست حساب‌های سرویس انتخاب کنید و مدیریت کلیدها را از منوِ کنش‌ها انتخاب کنید.
افزودن کلید > ایجاد کلید جدید را انتخاب کنید.
برای نوع کلید، گزینه JSON را انتخاب کنید.
روی ایجاد کردن کلیک کنید. فایل JSON حاوی کلیدتان در رایانه بارگیری می‌شود.
فراخوانی میانای برنامه‌سازی کاربردی
HTTP
Home Graph API یک نقطه پایان HTTP ارائه می‌دهد
- از فایل JSON حساب سرویس بارگیری‌شده برای ایجاد «نشان وب JSON» (JWT) استفاده کنید. برای اطلاعات بیشتر، به اصالت‌سنجی بااستفاده از حساب سرویس مراجعه کنید.
- بااستفاده از oauth2l، کد دسترسی OAuth 2.0 را با دامنه
https://www.googleapis.com/auth/homegraphدریافت کنید: - درخواست JSON را با
agentUserIdایجاد کنید. در اینجا نمونه درخواست JSON برای «درخواست همگام‌سازی» آورده شده است: - درخواست همگام‌سازی JSON و توکن را در درخواست HTTP POST خود به نقطه پایانی Google Home Graph ترکیب کنید. در اینجا مثالی از نحوه
ارسال درخواست در خط فرمان بااستفاده از
curl، به‌عنوان آزمایش آورده شده است:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:requestSync"
gRPC
Home Graph API یک نقطه پایانی gRPC ارائه می‌دهد
- تعریف سرویس میان‌گیری پروتکل را برای Home Graph API دریافت کنید.
- برای تولید کدهای آماده کارخواه برای یکی از زبان‌های پشتیبانی‌شده، اسناد توسعه‌دهنده gRPC را دنبال کنید.
- روش RequestSync را فراخوانی کنید.
Node.js
Google APIs Node.js Client برای Home Graph API اتصال فراهم می‌کند.
- سرویس
google.homegraphرا بااستفاده از اعتبارنامه پیش‌فرض برنامه مقداردهی اولیه کنید. - روش
requestSyncرا با RequestSyncDevicesRequest فراخوانی کنید. این هدفPromiseرا با RequestSyncDevicesResponse خالی برمی‌گرداند.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.requestSync({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', async: false } });
جاوا
کتابخانه کارخواه HomeGraph API برای Java اتصال‌هایی برای Home Graph API ارائه می‌دهد.
HomeGraphApiServiceرا بااستفاده از اعتبارنامه پیش‌فرض برنامه مقداردهی اولیه کنید.- روش
requestSyncرا باRequestSyncDevicesRequestفراخوانی کنید.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(); // Request sync. RequestSyncDevicesRequest request = new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false); homegraphService.devices().requestSync(request);
پاسخ‌های خطا
ممکن است هنگام فراخوانی «درخواست همگام‌سازی»، یکی از پاسخ‌های خطای زیر را دریافت کنید. این پاسخ‌ها به‌صورت کدهای وضعیت HTTP ارائه می‌شوند.
400 Bad Request- سرور نتوانست درخواست ارسال‌شده توسط کارخواه را به‌دلیل نحو نامعتبر پردازش کند. دلایل رایج شامل JSON بدشکل یا استفاده ازnullبه‌جای «» برای مقدار رشته است.403 Forbidden- سرور نتوانست درخواستagentUserIdرا پردازش کند زیرا هنگام بازآوری کردن کد خطایی رخ داد. مطمئن شوید که نقطه پایانی OAuth شما به‌درستی به درخواست‌های ژتون بازآوری پاسخ می‌دهد و وضعیت پیوند حساب کاربر را بررسی کنید.404 Not Found- منبع درخواستی پیدا نشد اما ممکن است در آینده دردسترس قرار گیرد. معمولاً این یعنی حساب کاربر به Google پیوند نشده است یاagentUserIdنامعتبر دریافت کرده‌ایم. مطمئن شویدagentUserIdبا مقدار ارائه‌شده در پاسخ SYNC شما مطابقت داشته باشد و هدف‌های DISCONNECT را به‌درستی مدیریت کنید.429 Too Many Requests- حداکثر تعداد درخواست‌های همگام‌سازی همزمان برایagentUserIdداده‌شده فراتر رفته است. فراخواننده فقط می‌تواند یک درخواست همگام‌سازی همزمان صادر کند، مگراینکه پرچمasyncروی درست تنظیم شده باشد.