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

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

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

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

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

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

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

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

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

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

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

יצירת התראות על השילוב של Cloud ל-Cloud

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

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, עוברים לדף HomeGraph API.

   כניסה לדף HomeGraph 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 עשוי לכלול שדות שונים בהתאם למאפיין המכשיר.

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

• שליחת עומס נתונים של התראה יזומה
• שליחת עומס נתונים של תשובה למעקב

שליחת עומס נתונים של התראה יזומה

כדי לקרוא ל-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);
    

שליחת עומס נתונים של תגובה המשך

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

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

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