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

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

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

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

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

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

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

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

בקטע הקוד הבא מוצגת דוגמה להגדרה של תגובת סנכרון:

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

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

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

הפעלת Google Home Graph API

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

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

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

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

1. באפליקציית Google Cloud Console, עוברים לדף Create service account key.

   כניסה לדף Create Service Account Key
2. מהרשימה Service Account, בוחרים חשבון שירות חדש.
3. כותבים שם בשדה Service account name.
4. מזינים מזהה בשדה Service account ID.

5. ברשימה Role בוחרים באפשרות Service Accounts > יצירת אסימונים בחשבון שירות.

6. בשדה Key type, בוחרים באפשרות JSON.

7. לוחצים על יצירה. קובץ 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) של תגובת המשך

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

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

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

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

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