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

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

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

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

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

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

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

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

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

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

מאפיין	אירועים
ObjectDetection	אובייקטים שזוהו על ידי המכשיר, למשל כשזיהינו פנים מוכרים בדלת. לדוגמה: "Alice and Bob are at the front door"
RunCycle	המכשיר משלים מחזור. לדוגמה: "The washing machine cycle has completed"
SensorState	המכשיר מזהה מצב חיישן נתמך. לדוגמה: "גלאי העשן מזהה עשן"

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

מאפיין	אירועים
LockUnlock	סטטוס השלמה ושינוי המצב לאחר ביצוע הפקודה `action.devices.commands.LockUnlock` במכשיר. לדוגמה: "The front door has been locked" או "The front door is jammed".
NetworkControl	סטטוס השלמה ושינוי המצב לאחר ביצוע הפקודה `action.devices.commands.TestNetworkSpeed` במכשיר. לדוגמה: "בדיקת מהירות הרשת הסתיימה. מהירות ההורדה בנתב המשרד היא 80.2Kbps וקצב ההעלאה הוא 9.3Kbps."
OpenClose	סטטוס השלמה ושינוי המצב לאחר ביצוע הפקודה `action.devices.commands.OpenClose` במכשיר. לדוגמה: "The front door has opened" או "The front door couldn’t be opened"

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

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

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

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

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

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

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

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

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

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

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

{
  "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 ואת Notification 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 מספק נקודת קצה (endpoint) של gRPC

מקבלים את הגדרת השירות של protocol buffers עבור API ‏Home Graph.
פועלים לפי ההוראות בתיעוד למפתחים של gRPC כדי ליצור stubs של לקוח לאחת מהשפות הנתמכות .
קוראים ל-method‏ ReportStateAndNotification .

Node.js

לקוח Node.js של Google APIs מספק קישורים ל-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

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

מאתחלים את HomeGraphApiService באמצעות Application Default Credentials.
קוראים ל-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);

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

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

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 ו-Notification:

{
  "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 ואת Notification 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 מספק נקודת קצה (endpoint) של gRPC

מקבלים את הגדרת השירות של protocol buffers עבור API ‏Home Graph.
פועלים לפי ההוראות בתיעוד למפתחים של gRPC כדי ליצור stubs של לקוח לאחת מהשפות הנתמכות.
קוראים ל-method‏ ReportStateAndNotification.

Node.js

לקוח Node.js של Google APIs מספק קישורים ל-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

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

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

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

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

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

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

סטטוס	תיאור
`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).

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

בדיקת שילוב בין עננים