התראות על פעולות בבית החכם

ההתראות מאפשרות לשילוב Cloud-to-cloud להשתמש ב-Google Assistant כדי לתקשר עם המשתמשים לגבי אירועים או שינויים חשובים שקשורים למכשיר. אתם יכולים להטמיע התראות כדי להודיע למשתמשים על אירועים במכשיר שקורים בזמן אמת, למשל כשמישהו נמצא בדלת, או כדי לדווח על שינוי במצב המכשיר שביקשתם, למשל כשבריח של מנעול בדלת ננעל בהצלחה או נתקע.

שילוב Cloud-to-cloud יכול לשלוח למשתמשים את סוגי ההתראות הבאים:

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

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

‫Assistant מספקת את ההתראות האלה למשתמשים כהודעות ברמקולים חכמים ובמסכים חכמים. ההתראות היזומות מושבתות כברירת מחדל. המשתמשים יכולים להפעיל או להשבית את כל ההתראות היזומות מGoogle Home app (GHA).

אירועים שמפעילים התראות

כשמתרחשים אירועים במכשיר, מרכז הבקשות שולח בקשת התראה ל-Google. התכונות של המכשיר ששילוב Cloud-to-cloud תומך בהן קובעות אילו סוגים של אירועי התראות זמינים ואילו נתונים אפשר לכלול בהתראות האלה.

התכונות הבאות תומכות בהתראות יזומות:

התכונות הבאות תומכות בתגובות המשך:

כל סוגי המכשירים תומכים בהתראות לגבי ה-traits הרלוונטיים.

הגדרת התראות לגבי גרסאות build בשילוב בין ענן לענן

מוסיפים התראות לשילוב Cloud-to-cloud בשלבים הבאים:

1. צריך לציין ל-Google אם ההתראות מופעלות באפליקציה לניהול מכשיר משני smart home. אם המשתמשים מפעילים או משביתים את ההתראות באפליקציה, צריך לשלוח SYNCבקשה כדי לעדכן את Google לגבי השינוי במכשיר.
2. כשמתרחש אירוע רלוונטי במכשיר או שינוי במצב שמפעיל התראה, שולחים בקשה להתראה על ידי קריאה ל-API‏ Report State reportStateAndNotification. אם מצב המכשיר השתנה, אפשר לשלוח גם מטען ייעודי (payload) של מצב וגם מטען ייעודי (payload) של התראה ביחד בשיחת Report State ובהתראה.

בקטעים הבאים מוסבר בהרחבה על השלבים האלה.

איך מציינים אם ההתראות מופעלות באפליקציה

המשתמשים יכולים לבחור אם הם רוצים לקבל התראות יזומות על ידי הפעלת התכונה הזו בGHA. באפליקציה למכשיר smart home, אפשר גם להוסיף אפשרות למשתמשים להפעיל או להשבית את ההתראות מהמכשיר באופן מפורש, למשל מההגדרות של האפליקציה.

כדי לעדכן את נתוני המכשיר, צריך לשלוח ל-Google קריאה של Request SYNC כדי לציין שההתראות מופעלות במכשיר. עליכם לשלוח בקשת SYNC כזו בכל פעם שהמשתמשים משנים את ההגדרה הזו באפליקציה שלכם.

בתגובה SYNC, שולחים אחד מהעדכונים הבאים:

• אם המשתמש הפעיל באופן מפורש את ההתראות באפליקציה לניהול מכשיר משני, או אם לא סיפקתם אפשרות להפעלה או להשבתה, צריך להגדיר את המאפיין devices.notificationSupportedByAgent לערך true.
• אם המשתמש השבית באופן מפורש את ההתראות באפליקציה לניהול מכשיר משני, צריך להגדיר את המאפיין devices.notificationSupportedByAgent לערך false.

בקטע הקוד הבא אפשר לראות דוגמה להגדרת תגובת SYNC:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

שליחת בקשות להתראות אל Google

כדי להפעיל התראות ב-Assistant, מערכת ניהול ההזמנות שולחת מטען ייעודי (payload) של התראה ל-Google Home Graph באמצעות Report State וקריאה ל-Notification API.

הפעלת Google HomeGraph API

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

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

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

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

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

   מעבר לדף Service Accounts

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

2. לוחצים על addיצירת חשבון שירות.

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 (ניהול מפתחות) מהתפריט more_vert Actions (פעולות).

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

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

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

שליחת ההתראה

מבצעים את הקריאה לבקשת ההתראה באמצעות devices.reportStateAndNotification API. בקשת ה-JSON חייבת לכלול eventId, שהוא מזהה ייחודי שנוצר על ידי הפלטפורמה שלכם לאירוע שמפעיל את ההתראה. הערך של eventId צריך להיות מזהה רנדומלי שמשתנה בכל פעם ששולחים בקשת התראה.

באובייקט notifications שמעבירים בקריאה ל-API, צריך לכלול ערך priority שמגדיר איך ההתראה תוצג. אובייקט notifications עשוי לכלול שדות שונים בהתאם למאפיין המכשיר.

כדי להגדיר את מטען הייעודי (payload) ולקרוא ל-API, פועלים לפי אחת מהדרכים הבאות:

• שליחת מטען ייעודי (payload) של התראה יזומה
• שליחת מטען ייעודי (payload) של תגובה למעקב

שליחת מטען ייעודי (payload) של התראה יזומה

כדי להתקשר אל ה-API, בוחרים באחת מהאפשרויות בכרטיסיות הבאות:

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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

// 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 notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    

שליחת מטען ייעודי (payload) של תגובה למעקב

המטען הייעודי (payload) של תשובה למעקב מכיל את סטטוס הבקשה, קודי שגיאה של אירועים שנכשלו (אם רלוונטי) ואת הערך התקין של followUpToken, שסופק במהלך בקשת הכוונה EXECUTE. צריך להשתמש ב-followUpToken תוך חמש דקות כדי שהוא יישאר תקף וכדי שהתגובה תשויך לבקשה המקורית בצורה נכונה.

בקטע הקוד הבא מוצגת דוגמה למטען ייעודי (payload) של בקשת EXECUTE עם השדה followUpToken.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

‫Google משתמשת ב-followUpToken כדי להציג את ההתראה רק במכשיר שהמשתמש ביצע בו את האינטראקציה המקורית, ולא כדי להציג אותה בכל המכשירים של המשתמש.

כדי להתקשר אל ה-API, בוחרים באחת מהאפשרויות בכרטיסיות הבאות:

const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

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

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

רישום ביומן

התראות תומכות ברישום אירועים ביומן, כמו שמתואר במאמר Cloud Logging עבור Cloud-to-Cloud. היומנים האלה שימושיים לבדיקה ולשמירה על איכות ההתראות בפעולה שלכם.

זוהי הסכימה של רשומה notificationLog:

השדה status כולל סטטוסים שונים שעשויים להצביע על שגיאות במטען הייעודי (payload) של ההתראה. יכול להיות שחלק מהאפשרויות האלה יהיו זמינות רק בפעולות שלא הושקו לייצור.

דוגמאות לסטטוסים:

בנוסף לסטטוסים הכלליים האלה שיכולים לחול על כל ההתראות, השדה status עשוי לכלול גם סטטוסים ספציפיים למאפיינים, במקרים הרלוונטיים (לדוגמה, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).