מצב דוח

התכונה Report State היא תכונה חשובה שמאפשרת לפעולה Home לדווח באופן יזום על הסטטוס העדכני של המכשיר של המשתמש אל Google Home Graph, במקום להמתין ל-QUERY Intent.

Report State מדווח ל-Google על המצבים של מכשירי המשתמשים שמשויכים אליהם agentUserId שצוין (נשלח בבקשת SYNC המקורית). כאשר Google Assistant רוצה לבצע פעולה שמחייבת הבנה של המצב הנוכחי של המכשיר, הוא יכול פשוט לחפש את פרטי המצב ב-Home Graph במקום להנפיק כוונה (QUERY) לעננים שונים של צד שלישי לפני הנפקת ה-Intent ב-EXECUTE.

בלי Report State, בהתחשב בתאורה של מספר ספקים בסלון, הפקודה Ok Google, Bright my living room מחייבת לפתור כמה אובייקטים מסוג QUERY Intent שנשלחו לכמה עננים, ולא לחפש רק את ערכי הבהירות הנוכחיים על סמך מה שדווח. כדי לספק את חוויית המשתמש הטובה ביותר, Assistant צריך להיות במצב הנוכחי של המכשיר, ללא צורך בהעברה הלוך ושוב למכשיר.

אחרי SYNC הראשוני של המכשיר, הפלטפורמה שולחת Intent מסוג QUERY שאוספת את המצב של המכשיר כדי לאכלס את Home Graph. לאחר מכן, ב-Home Graph נשמרים רק המצב שנשלח עם Report State.

כשקוראים לפונקציה Report State, חשוב לספק את נתוני המצב המלאים של תכונה נתונה. הפונקציה Home Graph מעדכנת מצבים על בסיס של כל תכונה, ומחליפה את כל הנתונים של התכונה הזו בכל פעם שמבוצעת קריאה ל-Report State. לדוגמה, אם רוצים לדווח על המצב של ה-trait StartStop, המטען הייעודי צריך לכלול ערכים של isRunning וגם של isPaused.

שנתחיל?

כדי להטמיע את Report State, צריך לפעול לפי השלבים הבאים:

הפעלת ממשק ה-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 מספק נקודת קצה (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
  3. יוצרים את בקשת ה-JSON באמצעות agentUserId. לפניכם בקשת JSON לדוגמה למצב הדוח ולהתראות:
    4. {
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}
  4. צריך לשלב בין מצב הדוח לבין קובץ JSON של ההתראות, יחד עם האסימון בבקשת ה-HTTP POST, לנקודת הקצה של תרשים הבית של Google Home. כך שולחים את הבקשה בשורת הפקודה באמצעות 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:reportStateAndNotification"

gRPC

השדה Home Graph מספק נקודת קצה ל-gRPC

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

Node.js

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

  1. מפעילים את השירות google.homegraph באמצעות Application Default Credentials.
  2. מפעילים את השיטה reportStateAndNotification באמצעות ReportStateAndNotificationRequest. הוא מחזיר Promise עם ReportStateAndNotificationResponse.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});

Java

ספריית הלקוח של HomeGraph API עבור Java מספקת קישורים לממשק ה-API של Home Graph.

  1. מפעילים את HomeGraphApiService באמצעות Application Default Credentials.
  2. מפעילים את method reportStateAndNotification באמצעות המספר ReportStateAndNotificationRequest. מוחזר 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();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request);
}

מצב דוח בדיקה

כלים מומלצים למשימה הזו

כדי להתכונן לקבלת אישור, חשוב לבדוק את Report State.

לשם כך, מומלץ להשתמש בכלי Viewer של Home Graph, שהוא אפליקציית אינטרנט עצמאית שלא מצריכה הורדה או פריסה.

מרכז הבקרה של Report State עדיין זמין, אבל הוא הוצא משימוש ולא נתמך יותר.

מרכז הבקרה של מצב הדוח

דרישות מוקדמות

כדי לבדוק את הפעולה, תצטרכו את המַפְתח לחשבון השירות ואת agentUserId. אם כבר יש לכם מפתח לחשבון השירות ו agentUserId עיינו בפריסת Report State מרכז השליטה.

פריסת מרכז הבקרה של מצב הדוח

אחרי שמקבלים את המפתח של חשבון השירות ואת מזהה המשתמש של הסוכן לפרויקט, מורידים את הגרסה האחרונה ופורסים אותה מReport Stateמרכז הבקרה. אחרי שמורידים את הגרסה האחרונה, צריך לפעול לפי ההוראות מהקובץ README.MD הכלול.

אחרי שפורסים את מרכז הבקרה של Report State, צריך להיכנס למרכז הבקרה מכתובת ה-URL הבאה (צריך להחליף את your_project_id במזהה הפרויקט):

http://<your-project-id>.appspot.com

במרכז השליטה, מבצעים את הפעולות הבאות:

  • בחירת קובץ מפתח של חשבון
  • הוספת מזהה של סוכן

לאחר מכן לוחצים על רשימה.

כל המכשירים שלך מופיעים ברשימה. כשהרשימה תאוכלס, תוכלו ללחוץ על רענן כדי לעדכן את מצבי המכשיר. אם חל שינוי במצב המכשיר, השורה תודגש בירוק.

תגובות שגיאה

יכול להיות שתקבלו את אחת מהשגיאות הבאות בהתקשרות אל Report State. התגובות האלה מופיעות בצורת קודי סטטוס HTTP.

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