בקשה לסנכרון

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

צריך להפעיל בקשה מסוג SYNC:

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

שנתחיל?

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

הפעלת Google HomeGraph API

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

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

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

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

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

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

    כניסה לדף Service Accounts.

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

  2. לוחצים על Create service account.

  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. בוחרים את חשבון השירות שיצרתם מרשימת חשבונות השירות, ואז בוחרים באפשרות Manage keys בתפריט Actions של .

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

  12. בKey type, בוחרים באפשרות JSON.

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

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

קריאה ל-API

HTTPgRPCNode.jsJava

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 של בקשת הסנכרון ואת האסימון בבקשת ה-POST של ה-HTTP לנקודת הקצה של 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"

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

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

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

  1. מאתחלים את השירות google.homegraph באמצעות Application Default Credentials.
  2. קוראים ל-method‏ 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.

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

תגובות שגיאה

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

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