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

ההתראות מאפשרות לשילוב 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 אם ההתראות מופעלות באפליקציית המכשיר שלכם. אם המשתמשים מפעילים או משביתים את ההתראות באפליקציה שלכם, צריך לשלוח SYNCבקשה כדי לעדכן את Google לגבי השינוי במכשיר.smart home
2. כשמתרחש אירוע רלוונטי במכשיר או שינוי במצב שמפעיל התראה, שולחים בקשה להתראה על ידי קריאה ל-Report State reportStateAndNotification API. אם מצב המכשיר השתנה, אפשר לשלוח גם מטען ייעודי (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. בוחרים את חשבון השירות שיצרתם מהרשימה של חשבונות השירות ובוחרים באפשרות ניהול מפתחות בתפריט more_vert פעולות.

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

12. בסוג המפתח, בוחרים באפשרות 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).