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

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

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

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

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

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

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

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

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

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

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

יצירת התראות לשילוב בין שירותי ענן

כדי להוסיף התראות לשילוב של Cloud-to-cloud, צריך לבצע את השלבים הבאים:

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

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

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

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

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

2. לוחצים על addCreate service account.

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 שמכיל את המפתח יורד למחשב.

שליחת ההתראה

מבצעים את הקריאה לבקשת ההתראה באמצעות ה-API של devices.reportStateAndNotification. בקשת ה-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 שסופק במהלך בקשת ה-Intent של 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. היומנים האלה שימושיים לבדיקה ולשמירה על איכות ההתראות ב-Action.

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

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

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

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