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

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

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

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

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

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

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

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

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

תכונה אירועים
ObjectDetection אובייקטים שהמכשיר מזהה, למשל זיהוי פנים מוכרות בדלת. לדוגמה: "יוסי ובוב נמצאים בדלת הכניסה"
RunCycle המכשיר משלים מחזור. לדוגמה: "מחזור הכביסה במכונת הכביסה הסתיים".
SensorState המכשיר מזהה מצב חיישן נתמך. לדוגמה: "גלאי העשן מזהה עשן"
TemperatureControl המכשיר מגיע לנקודת הגדרה של הטמפרטורה. לדוגמה: "התנור חם מראש ל-350 מעלות"
ArmDisarm המערכת נכנסת למצב טרום-התראה עם ספירה לאחור של הכניסה, שמופעלת על ידי דלת פתוחה.
CameraStream ביצוע קישור לשידור החי של המצלמה לאחר שהמכשיר מזהה אובייקט או תנועה.
MotionDetection "זוהתה תנועה בשעה 12:00 ב-1 ביולי 2020".

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

תכונה אירועים
ArmDisarm שינוי סטטוס ההשלמה והמצב לאחר הרצת פקודת המכשיר action.devices.commands.ArmDisarm. לדוגמה: "מערכת האבטחה הופעלה במכשיר".
LockUnlock שינוי סטטוס ההשלמה והמצב לאחר הרצת פקודת המכשיר action.devices.commands.LockUnlock. לדוגמה: "הדלת הקדמית ננעלה" או "הדלת הקדמית תקועה".
NetworkControl שינוי סטטוס ההשלמה והמצב לאחר הרצת פקודת המכשיר action.devices.commands.TestNetworkSpeed. לדוגמה: "בדיקת מהירות הרשת הסתיימה. מהירות ההורדה בנתב המשרדי היא כרגע 80.2Kbps ומהירות ההעלאה היא 9.3Kbps."
OpenClose שינוי סטטוס ההשלמה והמצב לאחר הרצת פקודת המכשיר action.devices.commands.OpenClose. לדוגמה: "הדלת הקדמית נפתחה" או "לא ניתן היה לפתוח את הדלת הקדמית".
StartStop שינוי סטטוס ההשלמה והמצב לאחר הרצת פקודת המכשיר action.devices.commands.StartStop. לדוגמה: "שואב האבק הופעל".

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

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

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

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

בחלקים הבאים נרחיב על השלבים האלה.

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

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

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

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

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

בקטע הבא מוצגת דוגמה להגדרה של תגובת SYNC:

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

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

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

הפעלת ממשק ה-API של Google HomeGraph

  1. ב-Google Cloud Console, עבור לדף HomeGraph API.

    כניסה לדף HomeGraph API
  2. בוחרים את הפרויקט שתואם למזהה הפרויקט שלכם ב-smart home.
  3. לוחצים על הפעלה.

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

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

הערה: חשוב לוודא שאתם משתמשים בפרויקט GCP הנכון בזמן ביצוע השלבים האלה. זהו הפרויקט שתואם למזהה הפרויקט שלך ב-smart home.

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

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

שליחת ההתראה

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

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

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

שליחת מטען ייעודי (payload) של התראות יזומות

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

HTTP

ה-API של Home Graph מספק נקודת קצה (endpoint) של HTTP

  1. תוכלו להשתמש בקובץ ה-JSON של חשבון השירות שהורדתם כדי ליצור אסימון JSON Web Token (JWT). מידע נוסף זמין במאמר אימות באמצעות חשבון שירות.
  2. מקבלים אסימון גישה מסוג OAuth 2.0 עם ההיקף של https://www.googleapis.com/auth/homegraph באמצעות oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. יוצרים את בקשת ה-JSON באמצעות agentUserId. דוגמה לבקשת JSON עבור Report State והתראה:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. צריך לשלב את ה-JSON של Report State ושל Notification JSON והאסימון בבקשת ה-HTTP POST שלך, עם נקודת הקצה של Google Home Graph. כך שולחים את הבקשה בשורת הפקודה באמצעות curl, כבדיקה:
    5. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

ה-API של Home Graph מספק נקודת קצה ל-gRPC

  1. לקבלת הגדרת השירות למאגר אחסון של פרוטוקולים (buffers) עבור ה-API של Home Graph.
  2. יש לפעול לפי התיעוד למפתחים של gRPC כדי ליצור מאמרי לקוח באחת מהשפות הנתמכות.
  3. מפעילים את השיטה ReportStateAndNotification.

Node.js

לקוח Google APIs Node.js מספק קישורים ל-API של Home Graph.

  1. מפעילים את השירות google.homegraph באמצעות Application Default Credentials.
  2. מפעילים את השיטה reportStateAndNotification באמצעות ReportStateAndNotificationRequest. הוא מחזיר Promise עם ReportStateAndNotification Response.
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
              }
            }
          }
        }
      }
    }
  }
});

Java

ספריית הלקוח של HomeGraph API עבור Java מספקת קישורים ל-API של Home Graph.

  1. מפעילים את HomeGraphApiService באמצעות Application Default Credentials.
  2. מפעילים את method reportStateAndNotification באמצעות המספר ReportStateAndNotificationRequest. מוחזר ReportStateAndNotificationResponse.
// 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, בוחרים אפשרות באחת מהכרטיסיות הבאות:

HTTP

ה-API של Home Graph מספק נקודת קצה (endpoint) של HTTP

  1. תוכלו להשתמש בקובץ ה-JSON של חשבון השירות שהורדתם כדי ליצור אסימון JSON Web Token (JWT). מידע נוסף זמין במאמר אימות באמצעות חשבון שירות.
  2. מקבלים אסימון גישה מסוג OAuth 2.0 עם ההיקף של https://www.googleapis.com/auth/homegraph באמצעות oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. יוצרים את בקשת ה-JSON באמצעות agentUserId. דוגמה לבקשת JSON עבור Report State והתראה:
    4. {
  "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": "PLACEHOLDER",
              "networkDownloadSpeedMbps": 23.3,
              "networkUploadSpeedMbps": 10.2
            }
          }
        }
      }
    }
  }
}
  4. צריך לשלב את ה-JSON של Report State ושל Notification JSON והאסימון בבקשת ה-HTTP POST שלך, עם נקודת הקצה של Google Home Graph. כך שולחים את הבקשה בשורת הפקודה באמצעות curl, כבדיקה:
    5. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

ה-API של Home Graph מספק נקודת קצה ל-gRPC

  1. לקבלת הגדרת השירות למאגר אחסון של פרוטוקולים (buffers) עבור ה-API של Home Graph.
  2. יש לפעול לפי התיעוד למפתחים של gRPC כדי ליצור מאמרי לקוח באחת מהשפות הנתמכות.
  3. מפעילים את השיטה ReportStateAndNotification.

Node.js

לקוח Google APIs Node.js מספק קישורים ל-API של Home Graph.

  1. מפעילים את השירות google.homegraph באמצעות Application Default Credentials.
  2. מפעילים את השיטה reportStateAndNotification באמצעות ReportStateAndNotificationRequest. הוא מחזיר Promise עם ReportStateAndNotification Response.
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,
              }
            }
          }
        }
      }
    }
  }
});

Java

ספריית הלקוח של HomeGraph API עבור Java מספקת קישורים ל-API של Home Graph.

  1. מפעילים את HomeGraphApiService באמצעות Application Default Credentials
  2. מפעילים את method reportStateAndNotification באמצעות המספר ReportStateAndNotificationRequest. הוא יחזיר ReportStateAndNotificationResponse
// 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. היומנים האלה שימושיים לבדיקה ולשמירה על איכות ההתראות ב-Action.

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

נכס תיאור
requestId המזהה של בקשת ההתראה.
structName השם של מבנה ההתראה, למשל "ObjectDetection".
status מציין את הסטטוס של ההתראה.

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

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

סטטוס תיאור
EVENT_ID_MISSING שדה החובה eventId חסר.
PRIORITY_MISSING שדה priority חסר.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE מציין שמאפיין notificationSupportedByAgent של המכשיר לשליחת הודעות שצוין ב-SYNC הוא False.
NOTIFICATION_ENABLED_BY_USER_FALSE השדה הזה מציין שהמשתמש לא הפעיל את ההתראות במכשיר לשליחת ההודעה ב-GHA. הסטטוס הזה זמין רק בפעולות שלא הושקו לסביבת הייצור.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE מציין שהמשתמש לא הקצה את המכשיר לשליחת הודעות לבית/מבנה. הסטטוס הזה זמין רק בפעולות שלא הושקו לסביבת הייצור.

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

הקודם
הטמעה של מצב הדוח
הבא
בדיקה ושיתוף של פעולות