בקשה לסנכרון

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

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

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

שנתחיל?

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

הפעלת ממשק ה-API של Google HomeGraph

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

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

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

יש לפעול לפי ההוראות הבאות כדי ליצור מפתח של חשבון שירות מ-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. בשדה סוג מפתח, בוחרים באפשרות JSON.

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

קריאה ל-API

HTTP

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

  1. תוכלו להשתמש בקובץ ה-JSON של חשבון השירות שהורדתם כדי ליצור אסימון JSON Web Token (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
    
  4. יוצרים את בקשת ה-JSON באמצעות agentUserId. לפניכם בקשת JSON לדוגמה לסנכרון של הבקשה:
  5. {
      "agentUserId": "user-123"
    }
    
  6. צריך לשלב את ה-JSON של בקשת סנכרון עם האסימון בבקשת ה-HTTP POST שלך עם נקודת הקצה של Google Home Graph. כך שולחים את הבקשה בשורת הפקודה באמצעות curl, כבדיקה:
  7. 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

  1. איך לקבל את הגדרת השירות למאגר אחסון של פרוטוקולים (buffers) עבור ממשק ה-API של Home Graph.
  2. יש לפעול לפי התיעוד למפתחים של gRPC כדי ליצור מאמרי לקוח באחת מהשפות הנתמכות.
  3. מפעילים את method RequestSync.

Node.js

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

  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 מספקת קישורים לממשק ה-API של Home Graph.

  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);
    

תשובות לשגיאות

ייתכן שתקבלו את אחת מהתגובות הבאות לשגיאות כשהתקשרו אל 'בקשה לסנכרון'. התגובות האלה מופיעות בצורת קודי מצב HTTP.

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