בקשת SYNC
מפעילה את מילוי הבקשה לכל משתמש ב-Google עם מכשירים שמשויכים אליהם agentUserId
שצוין (שנשלחה בבקשת SYNC המקורית). כך אפשר לעדכן מכשירים של משתמשים בלי לבטל את הקישור של החשבון שלהם ולקשר אותו מחדש. כל המשתמשים שמקושרים למזהה הזה יקבלו בקשה לאימות SYNC
.
צריך להפעיל בקשת SYNC
:
- אם המשתמש מוסיף מכשיר חדש.
- אם המשתמש מסיר מכשיר קיים.
- אם המשתמש משנה את השם של מכשיר קיים.
- אם מטמיעים סוג מכשיר חדש, trait או מוסיפים תכונה חדשה במכשיר.
שנתחיל?
כדי להטמיע את הבקשה לסנכרון, יש לפעול לפי השלבים הבאים:
הפעלת ממשק ה-API של Google HomeGraph
-
ב-Google Cloud Console, עבור לדף HomeGraph API.
כניסה לדף HomeGraph API - בוחרים את הפרויקט שתואם למזהה הפרויקט שלכם ב-smart home.
- לוחצים על הפעלה.
יצירת מפתח לחשבון שירות
יש לפעול לפי ההוראות הבאות כדי ליצור מפתח של חשבון שירות מ-Google Cloud Console:
-
בGoogle Cloud Console, נכנסים לדף Create service account key.
כניסה לדף Create Service Account Key - מהרשימה Service account בוחרים את האפשרות New service account.
- כותבים שם בשדה Service account name.
- מזינים מזהה בשדה Service account ID.
ברשימה Role בוחרים Service Accounts > Service Account Token Creator.
בשדה סוג מפתח, בוחרים באפשרות JSON.
- לוחצים על יצירה. קובץ JSON שמכיל את המפתחות שהורדת למחשב.
קריאה ל-API
HTTP
ה-Home Graph API מספק נקודת קצה (endpoint) של HTTP
- תוכלו להשתמש בקובץ ה-JSON של חשבון השירות שהורדתם כדי ליצור אסימון JSON Web Token (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
{ "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
- איך לקבל את הגדרת השירות למאגר אחסון של פרוטוקולים (buffers) עבור ממשק ה-API של Home Graph.
- יש לפעול לפי התיעוד למפתחים של gRPC כדי ליצור מאמרי לקוח באחת מהשפות הנתמכות.
- מפעילים את method RequestSync.
Node.js
לקוח Node.js של Google APIs מספק קישורים עבור ממשק ה-API של Home Graph.
- מפעילים את השירות
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 } });
Java
ספריית הלקוח של HomeGraph API עבור Java מספקת קישורים לממשק ה-API של Home Graph.
- מפעילים את
HomeGraphApiService
באמצעות Application Default Credentials. - מפעילים את method
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, ושאתם מטפלים כראוי באובייקטים מסוג ניתוק.429 Too Many Requests
– חרגת מהמספר המקסימלי של בקשות סנכרון בו-זמניות עבורagentUserId
שצוינו. המתקשר יכול לשלוח רק בקשת סנכרון אחת בו-זמנית, אלא אם הדגלasync
מוגדר ל-True.