בקשה לסנכרון

הבקשה Request Sync מפעילה בקשת SYNC לביצוע הזמנה עבור כל משתמש Google עם מכשירים שמשויך אליהם agentUserId ספציפי (ששלחתם בבקשת הסנכרון המקורית). כך תוכלו לעדכן את המכשירים של המשתמשים בלי לבטל את הקישור של החשבון שלהם ולקשר אותו מחדש. כל המשתמשים שמקושרים למזהה הזה יקבלו בקשה.SYNC

צריך להפעיל בקשת SYNC:

  • אם המשתמש מוסיף מכשיר חדש.
  • אם המשתמש מסיר מכשיר קיים.
  • אם המשתמש משנה את השם של מכשיר קיים.
  • אם מטמיעים סוג מכשיר חדש, מאפיין חדש או מוסיפים תכונה חדשה למכשיר.

שנתחיל?

כדי להטמיע את התכונה 'בקשת סנכרון', פועלים לפי השלבים הבאים:

הפעלת Google HomeGraph API

  1. ב-Google Cloud Console, עוברים לדף HomeGraph API.

    כניסה לדף HomeGraph API
  2. בוחרים את הפרויקט שתואם למזהה הפרויקט smart home.
  3. לוחצים על הפעלה.

יצירת מפתח של חשבון שירות

כדי ליצור מפתח לחשבון שירות מ-Google Cloud Console, פועלים לפי ההוראות הבאות:

הערה: חשוב להקפיד להשתמש בפרויקט הנכון ב-GCP כשמבצעים את השלבים האלה. זהו הפרויקט שתואם למזהה הפרויקט smart home.

  1. ב-Google Cloud Console, עוברים לדף Service accounts.

    מעבר לדף Service Accounts

    יכול להיות שתצטרכו לבחור פרויקט לפני שתועברו לדף 'חשבונות שירות'.

  2. לוחצים על יצירת חשבון שירות.

  3. כותבים שם בשדה Service account name.

  4. מזינים מזהה בשדה Service account ID.

  5. כותבים תיאור בשדה Service account description.

  6. לוחצים על יצירה והמשך.

  7. בתפריט הנפתח Role, בוחרים באפשרות Service Accounts > Service Account OpenID Connect Identity Token Creator.

  8. לוחצים על המשך.

  9. לוחצים על סיום.

  10. בוחרים את חשבון השירות שיצרתם מהרשימה של חשבונות השירות ובוחרים באפשרות ניהול מפתחות בתפריט פעולות.

  11. בוחרים באפשרות Add key (הוספת מפתח) > Create new key (יצירת מפתח חדש).

  12. בסוג המפתח, בוחרים באפשרות JSON.

  13. לוחצים על יצירה. קובץ JSON שמכיל את המפתח יורד למחשב.

הוראות מפורטות ומידע על יצירת מפתחות של חשבונות שירות זמינים במאמר יצירה ומחיקה של מפתחות של חשבונות שירות באתר העזרה של מסוף Google Cloud.

שליחת קריאה ל-API

HTTP

‫Home Graph API מספק נקודת קצה (endpoint) של HTTP

  1. משתמשים בקובץ ה-JSON של חשבון השירות שהורד כדי ליצור אסימון אינטרנט מסוג JSON ‏ (JWT). מידע נוסף זמין במאמר אימות באמצעות חשבון שירות.
  2. מקבלים אסימון גישה מסוג OAuth 2.0 עם ההיקף https://www.googleapis.com/auth/homegraph באמצעות oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. יוצרים את בקשת ה-JSON עם agentUserId. דוגמה לבקשת JSON לסנכרון בקשות:
    4. {
  "agentUserId": "user-123"
}
  4. משלבים את ה-JSON של סנכרון הבקשה ואת האסימון בבקשת HTTP POST אל נקודת הקצה של Google Home Graph. הנה דוגמה לאופן שבו אפשר לשלוח את הבקשה בשורת הפקודה באמצעות curl, כבדיקה:
    5. 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 מספק נקודת קצה (endpoint) של gRPC

  1. אפשר לקבל את הגדרת השירות של Protocol Buffers עבור Home Graph API.
  2. פועלים לפי ההוראות בתיעוד למפתחים של gRPC כדי ליצור stub של לקוח לאחת מהשפות הנתמכות.
  3. מפעילים את ה-method‏ RequestSync.

Node.js

הלקוח של Google APIs Node.js מספק קשירות ל-Home Graph API.

  1. מאתחלים את שירות google.homegraph באמצעות Application Default Credentials.
  2. מבצעים קריאה לשיטה 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 מספקת קשירות ל-Home Graph API.

  1. מאתחלים את HomeGraphApiService באמצעות Application Default Credentials.
  2. מפעילים את השיטה 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);

תגובות שגיאה

יכול להיות שתקבלו אחת מהתגובות הבאות של שגיאה כשמתקשרים אל Request Sync. התשובות האלה מגיעות בצורה של קודי סטטוס HTTP.

  • ‫400 Bad Request – השרת לא הצליח לעבד את הבקשה שנשלחה מהלקוח בגלל תחביר לא תקין. סיבות נפוצות לכך הן JSON לא תקין או שימוש ב-null במקום '' לערך מחרוזת.
  • ‫403 Forbidden – השרת לא הצליח לעבד את הבקשה עבור agentUserId בגלל שגיאה במהלך רענון האסימון. מוודאים שנקודת הקצה (endpoint) של OAuth מגיבה בצורה נכונה לבקשות לרענון טוקן, ובודקים את סטטוס קישור החשבון של המשתמש.
  • ‫404 Not Found – לא נמצא המשאב המבוקש, אבל יכול להיות שהוא יהיה זמין בעתיד. בדרך כלל, המשמעות היא שחשבון המשתמש לא מקושר ל-Google או שקיבלנו agentUserId לא תקין. חשוב לוודא שהערך של agentUserId זהה לערך שצוין בתגובת SYNC, ושהטיפול בכוונות DISCONNECT מתבצע בצורה תקינה.
  • 429 Too Many Requests - חלה חריגה מהמספר המקסימלי של בקשות סנכרון בו-זמניות עבור agentUserId. המתקשר יכול להגיש רק בקשת סנכרון אחת בו-זמנית, אלא אם הדגל async מוגדר כ-true.
הקודם
ניתוק
הבא
הטמעה של מצב הדוח