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

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

הפעולה של smart home יכולה לשלוח למשתמשים את סוגי ההתראות הבאים:

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

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

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

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

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

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

המאפיינים הבאים תומכים בתשובות המשך:

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

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

מוסיפים התראות לפעולה smart home בשלבים הבאים:

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

הפעלת Google HomeGraph API

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

   לדף Home Graph API
2. צריך לבחור את הפרויקט שתואם למזהה הפרויקט ב-smart home.
3. לוחצים על ENABLE.

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

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

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. בKey type, בוחרים באפשרות JSON.

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

שליחת ההתראה

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

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

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

• שליחת מטען ייעודי (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) של תגובת המשך

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

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

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

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

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

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