בקשה לסנכרון

בקשת סנכרון מפעילה בקשה מסוג 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, עוברים לדף Create service account key.

    כניסה לדף Create Service Account Key
  2. ברשימה Service account, בוחרים באפשרות New service account.
  3. כותבים שם בשדה Service account name.
  4. מזינים מזהה בשדה Service account ID.

  5. ברשימה Role בוחרים באפשרות Service Accounts > Service Account Token Creator.

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

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

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

gRPC

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

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

Node.js

לקוח 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
  }
});

Java

ספריית הלקוח של 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.
הקודם
ניתוק
הבא
הטמעה של מצב הדוח