מצב דוח

Report StateCloud-to-cloud

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

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

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

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

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

שנתחיל?

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

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

gRPC

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

  1. אפשר לקבל את הגדרת השירות של Protocol Buffers עבור Home Graph API.
  2. פועלים לפי ההוראות בתיעוד למפתחים של gRPC כדי ליצור stub של לקוח לאחת מהשפות הנתמכות.
  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 מספקת קשירות ל-Home Graph API.

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

מצב דוח הבדיקה

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

כדי להכין את השילוב של Cloud-to-cloud לאישור, חשוב לבדוק את Report State.

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

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

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

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

כדי לבדוק את השילוב של Cloud-to-cloud, צריך את מפתח חשבון השירות ואת agentUserId. אם כבר יש לכם מפתח לחשבון שירות וagentUserId אתם רואים את האפשרות Deploy the Report State Dashboard.

פריסת מרכז הבקרה Report State

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

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

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

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

  • בחירת קובץ מפתח החשבון
  • הוספת agentUserId

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

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

דיווח על אי התאמה במצב

המדד 'דיוק מצב הדוח מבוסס-השאילתה' מודד את מידת ההתאמה בין המצב העדכני של הדוח במכשיר לבין הסטטוס של המכשיר בזמן שמשתמש שולח שאילתה לגביו. הערך הזה צפוי להיות 99.5%.

תשובות שגיאה

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

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

דיווח על מצב אונליין ואופליין

כשמכשיר נמצא במצב אופליין, צריך לדווח על <code{"online": code="" dir="ltr" false}<="" translate="no"> אל Report State תוך חמש דקות מההתנהגות של המכשיר. לעומת זאת, כשמכשיר חוזר למצב אונליין, צריך לשלוח את הערך <code{"online": code="" dir="ltr" translate="no" true}<=""> אל Report State תוך חמש דקות מההתנהגות של המכשיר. בכל פעם שמכשיר חוזר למצב אונליין, השותף צריך לדווח על כל מצבי המכשיר הנוכחיים באמצעות reportStateAndNotification API. בדוגמה הזו אפשר לראות שסוג המכשיר light מחובר לאינטרנט, ומוצגים כל מצבי המכשיר הנוכחיים.
"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }
</code{"online":></code{"online":>