درخواست همگامسازی برای هر کاربر Google با دستگاههایی که agentUserId
مشخص شده مرتبط با آنها (که شما در درخواست SYNC اصلی ارسال کردهاید) یک درخواست SYNC
را برای انجام شما آغاز میکند. این به شما امکان میدهد دستگاههای کاربران را بدون لغو پیوند و پیوند مجدد حساب آنها بهروزرسانی کنید. همه کاربرانی که به این شناسه پیوند داده شده اند یک درخواست SYNC
دریافت خواهند کرد.
شما باید یک درخواست SYNC
را راه اندازی کنید:
- اگر کاربر دستگاه جدیدی اضافه کند.
- اگر کاربر دستگاه موجود را حذف کند.
- اگر کاربر یک دستگاه موجود را تغییر نام دهد.
- اگر نوع، ویژگی یا ویژگی دستگاه جدیدی را اضافه کنید.
شروع کنید
برای اجرای Request Sync، مراحل زیر را دنبال کنید:
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 API یک نقطه پایانی HTTP ارائه می دهد
- از فایل JSON حساب سرویس دانلود شده برای ایجاد یک رمز وب JSON (JWT) استفاده کنید. برای اطلاعات بیشتر، احراز هویت با استفاده از حساب سرویس را ببینید.
- یک نشانه دسترسی OAuth 2.0 را با
https://www.googleapis.com/auth/homegraph
با استفاده از oauth2l دریافت کنید: - درخواست JSON را با
agentUserId
ایجاد کنید. در اینجا یک نمونه درخواست JSON برای درخواست همگام سازی آمده است: - Request Sync 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
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
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 Client Library برای جاوا اتصالاتی را برای Home Graph API فراهم می کند.
-
HomeGraphApiService
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
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
روی درست تنظیم شود.
درخواست همگامسازی برای هر کاربر Google با دستگاههایی که agentUserId
مشخص شده مرتبط با آنها (که شما در درخواست SYNC اصلی ارسال کردهاید) یک درخواست SYNC
را برای انجام شما آغاز میکند. این به شما امکان میدهد دستگاههای کاربران را بدون لغو پیوند و پیوند مجدد حساب آنها بهروزرسانی کنید. همه کاربرانی که به این شناسه پیوند داده شده اند یک درخواست SYNC
دریافت خواهند کرد.
شما باید یک درخواست SYNC
را راه اندازی کنید:
- اگر کاربر دستگاه جدیدی اضافه کند.
- اگر کاربر دستگاه موجود را حذف کند.
- اگر کاربر یک دستگاه موجود را تغییر نام دهد.
- اگر نوع، ویژگی یا ویژگی دستگاه جدیدی را اضافه کنید.
شروع کنید
برای اجرای Request Sync، مراحل زیر را دنبال کنید:
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 API یک نقطه پایانی HTTP ارائه می دهد
- از فایل JSON حساب سرویس دانلود شده برای ایجاد یک رمز وب JSON (JWT) استفاده کنید. برای اطلاعات بیشتر، احراز هویت با استفاده از حساب سرویس را ببینید.
- یک نشانه دسترسی OAuth 2.0 را با
https://www.googleapis.com/auth/homegraph
با استفاده از oauth2l دریافت کنید: - درخواست JSON را با
agentUserId
ایجاد کنید. در اینجا یک نمونه درخواست JSON برای درخواست همگام سازی آمده است: - Request Sync 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
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
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 Client Library برای جاوا اتصالاتی را برای Home Graph API فراهم می کند.
-
HomeGraphApiService
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
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
روی درست تنظیم شود.
درخواست همگامسازی برای هر کاربر Google با دستگاههایی که agentUserId
مشخص شده مرتبط با آنها (که شما در درخواست SYNC اصلی ارسال کردهاید) یک درخواست SYNC
را برای انجام شما آغاز میکند. این به شما امکان میدهد دستگاههای کاربران را بدون لغو پیوند و پیوند مجدد حساب آنها بهروزرسانی کنید. همه کاربرانی که به این شناسه پیوند داده شده اند یک درخواست SYNC
دریافت خواهند کرد.
شما باید یک درخواست SYNC
را راه اندازی کنید:
- اگر کاربر دستگاه جدیدی اضافه کند.
- اگر کاربر دستگاه موجود را حذف کند.
- اگر کاربر یک دستگاه موجود را تغییر نام دهد.
- اگر نوع، ویژگی یا ویژگی دستگاه جدیدی را اضافه کنید.
شروع کنید
برای اجرای Request Sync، مراحل زیر را دنبال کنید:
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 API یک نقطه پایانی HTTP ارائه می دهد
- از فایل JSON حساب سرویس دانلود شده برای ایجاد یک رمز وب JSON (JWT) استفاده کنید. برای اطلاعات بیشتر، احراز هویت با استفاده از حساب سرویس را ببینید.
- یک نشانه دسترسی OAuth 2.0 را با
https://www.googleapis.com/auth/homegraph
با استفاده از oauth2l دریافت کنید: - درخواست JSON را با
agentUserId
ایجاد کنید. در اینجا یک نمونه درخواست JSON برای درخواست همگام سازی آمده است: - Request Sync 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
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
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 Client Library برای جاوا اتصالاتی را برای Home Graph API فراهم می کند.
-
HomeGraphApiService
را با استفاده از Application Default Credentials راه اندازی کنید. - روش
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
روی درست تنظیم شود.