ברוכים הבאים למרכז המפתחים של Google Home. זהו היעד החדש ללימוד פיתוח פעולות לבית חכם. הערה:תצטרכו להמשיך ליצור פעולות במסוף הפעולות.

דף זה תורגם על ידי Cloud Translation API.

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

התראות מאפשרות לפעולה 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 בשלבים הבאים:

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

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

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

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

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

באפליקציית Google Cloud Console, עוברים לדף Create service account key.
כניסה לדף Create Service Account Key
ברשימה Service account בוחרים באפשרות New service account.
כותבים שם בשדה Service account name.
מזינים מזהה בשדה Service account ID.
ברשימה Role בוחרים באפשרות Service Accounts > Service Account Token Creator.
בשדה Key type, בוחרים באפשרות JSON.
לוחצים על יצירה. קובץ JSON שמכיל את ההורדות של המפתח למחשב.

שליחת ההתראה

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

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

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

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

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

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

HTTP

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

משתמשים בקובץ ה-JSON של חשבון השירות שהורדתם כדי ליצור אסימון אינטרנט מסוג JSON (JWT). למידע נוסף, ראו אימות באמצעות חשבון שירות.
משיגים אסימון גישה מסוג OAuth 2.0 עם ההיקף https://www.googleapis.com/auth/homegraph באמצעות oauth2l:

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

יוצרים את בקשת ה-JSON עם התג agentUserId. הנה דוגמה לבקשת JSON עבור Report State והתראה:

{
  "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
            }
          }
        }
      }
    }
  }
}

משלבים את Report State ואת JSON עם התראה ואת האסימון בבקשת ה-HTTP POST עם נקודת הקצה של Google Home Graph. דוגמה לאופן שבו שולחים את הבקשה בשורת הפקודה באמצעות curl, בתור בדיקה:

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

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

Node.js

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

מפעילים את השירות google.homegraph באמצעות Application Default Credentials.
מפעילים את השיטה reportStateAndNotification באמצעות ReportStateAndNotificationRequest. היא מחזירה Promise עם ReportStateAndNotificationResponse.

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

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

מאתחלים את HomeGraphApiService באמצעות Application Default Credentials.
מפעילים את השיטה 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

משתמשים בקובץ ה-JSON של חשבון השירות שהורדתם כדי ליצור אסימון אינטרנט מסוג JSON (JWT). למידע נוסף, ראו אימות באמצעות חשבון שירות.
משיגים אסימון גישה מסוג OAuth 2.0 עם ההיקף https://www.googleapis.com/auth/homegraph באמצעות oauth2l:

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

יוצרים את בקשת ה-JSON עם התג agentUserId. הנה דוגמה לבקשת JSON עבור Report State והתראה:

{
  "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
            }
          }
        }
      }
    }
  }
}

משלבים את Report State ואת JSON עם התראה ואת האסימון בבקשת ה-HTTP POST עם נקודת הקצה של Google Home Graph. דוגמה לאופן שבו שולחים את הבקשה בשורת הפקודה באמצעות curl, בתור בדיקה:

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

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

Node.js

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

מפעילים את השירות google.homegraph באמצעות Application Default Credentials.
מפעילים את השיטה reportStateAndNotification באמצעות ReportStateAndNotificationRequest. היא מחזירה Promise עם ReportStateAndNotificationResponse.

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

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

מאתחלים את HomeGraphApiService באמצעות Application Default Credentials
מפעילים את השיטה 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. היומנים האלה שימושיים לבדיקה ולשמירה על איכות ההתראות בפעולה.

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

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

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

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

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

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

הטמעה של מצב הדוח

בדיקה ושיתוף של פעולות