1. לפני שמתחילים
שילובים של בית חכם מאפשרים ל-Google Assistant לשלוט במכשירים מחוברים בבתים של המשתמשים. כדי ליצור שילוב בין עננים, צריך לספק נקודת קצה של webhook בענן שיכולה לטפל בכוונות של בית חכם. לדוגמה, כשמשתמש אומר "Ok Google, turn on the lights" (הפעלת האורות), ה-Assistant שולח את הפקודה ל-fulfillment בענן כדי לעדכן את מצב המכשיר.
ה-Local Home SDK משפר את השילוב של הפתרון שלכם לבתים חכמים על ידי הוספת נתיב מקומי לניתוב כוונות (intents) של הבית החכם ישירות למכשיר תואם Google Home. כך משתפרת המהימנות וזמן האחזור בעיבוד הפקודות של המשתמשים מתקצר. היא מאפשרת לכתוב ולפרוס אפליקציה מקומית לביצוע הזמנות ב-TypeScript או ב-JavaScript, שמזהה מכשירים ומבצעת פקודות בכל רמקול חכם של Google Home או במסך חכם של Google Nest. לאחר מכן, האפליקציה מתקשרת ישירות עם המכשירים החכמים הקיימים של המשתמשים ברשת המקומית באמצעות פרוטוקולים סטנדרטיים קיימים כדי לבצע פקודות.

ניפוי באגים בשילובים בין עננים הוא שלב קריטי בפיתוח שילובים באיכות הפקה, אבל הוא מאתגר וגוזל זמן אם אין כלים אינפורמטיביים וקלים לשימוש לפתרון בעיות ולבדיקה. כדי להקל על ניפוי הבאגים בשילובים בין עננים, אפשר להשתמש במדדים, ביומנים ובחבילת הבדיקות לבית חכם של Google Cloud Platform (GCP). הם יעזרו לכם לזהות ולפתור בעיות בשילובים.
דרישות מוקדמות
- מדריך למפתחים בנושא שילוב בין עננים
- הפעלת ה-codelab Enable local fulfillment for Cloud-to-cloud integrations
מה תפַתחו
ב-codelab הזה תבנו שרשור פעולות (fulfillment) מקומי לשילובים בין ענן לענן, תחברו אותו ל-Assistant ותנפו באגים באפליקציית Home באמצעות חבילת הבדיקות למדדים ולרישום ביומן של בית חכם ו-Google Cloud Platform (GCP).
מה תלמדו
- איך משתמשים ב-GCP Metrics וב-Logging כדי לזהות ולפתור בעיות בייצור.
- איך משתמשים בחבילת הבדיקות כדי לזהות בעיות פונקציונליות ובעיות ב-API.
- איך משתמשים בכלים למפתחים ב-Chrome במהלך פיתוח אפליקציית Local Home.
הדרישות
- הגרסה העדכנית של Google Chrome
- מכשיר iOS או Android עם אפליקציית Google Home
- רמקול חכם של Google Home או מסך חכם של Google Nest
- Node.js מגרסה 10.16 ואילך
- חשבון Google
- חשבון לחיוב ב-Google Cloud
2. הפעלת אפליקציית מכונת הכביסה
קבלת קוד המקור
כדי להוריד את הדוגמה ל-codelab הזה למחשב הפיתוח, לוחצים על הקישור הבא:
…או שאפשר לשכפל את מאגר GitHub משורת הפקודה:
$ git clone https://github.com/google-home/smarthome-debug-local.git
מידע על הפרויקט
אפליקציה לתחילת הדרך מכילה ספריות משנה ופונקציות ענן דומות לאלה שב-Codelab הפעלת שירותי הפצה מקומיים לשילובים בין ענן לענן. אבל במקום app-start, יש לנו כאן app-faulty. נתחיל עם אפליקציית בית מקומית שעובדת, אבל לא בצורה מושלמת.
התחברות אל Firebase
נשתמש באותו פרויקט שיצרתם ב-codelab הפעלת שילובים מקומיים של Cloud-to-cloud, אבל נפריס את הקבצים שהורדתם ב-codelab הזה.
עוברים אל הספרייה app-faulty ומגדירים את Firebase CLI עם פרויקט השילוב שיצרתם ב-codelab הפעלת מימוש מקומי לשילובים בין ענן לענן:
$ cd app-faulty $ firebase use <project-id>
פריסה ב-Firebase
עוברים לתיקייה app-faulty/functions ומתקינים את כל הרכיבים התלויים הנדרשים באמצעות npm:
$ cd functions $ npm install
הערה: אם מוצגת ההודעה שלמטה, אפשר להתעלם ממנה ולהמשיך. האזהרה מוצגת בגלל תלות ישנה יותר, ופרטים נוספים זמינים כאן.
found 5 high severity vulnerabilities run `npm audit fix` to fix them, or `npm audit` for details
עוברים לספרייה app-faulty/local/ ומריצים את הפקודות הבאות כדי להוריד את מהדר TypeScript ולבצע קומפילציה של האפליקציה:
$ cd ../local $ npm install $ npm run build
הפקודה הזו מבצעת קומפילציה של המקור index.ts (TypeScript) ומציבה את התוכן הבא בספרייה app-faulty/public/local-home/:
-
bundle.js– פלט JavaScript שעבר קומפילציה ומכיל את האפליקציה המקומית ואת יחסי התלות. -
index.html—דף אירוח מקומי שמשמש להצגת האפליקציה לבדיקה במכשיר.
אחרי שמתקינים את יחסי התלות ומגדירים את הפרויקט, אפשר להריץ את האפליקציה בפעם הראשונה.
$ firebase deploy
זה הפלט שיוצג במסוף:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<project-id>/overview Hosting URL: https://<projectcd -id>.web.app
הפקודה הזו פורסת אפליקציית אינטרנט, יחד עם כמה פונקציות Cloud Functions for Firebase.
עדכון HomeGraph
פותחים את כתובת ה-URL של האירוח בדפדפן (https://<project-id>.web.app) כדי לראות את אפליקציית האינטרנט. בממשק המשתמש באינטרנט, לוחצים על לחצן רענון
כדי לעדכן את HomeGraph עם המטא-נתונים העדכניים של המכשיר מאפליקציית מכונת הכביסה הפגומה באמצעות בקשת סנכרון.

פותחים את אפליקציית Google Home ומוודאים שמכשיר הכביסה מופיע עם השם החדש 'מכונת כביסה תקולה'. חשוב להקצות את המכשיר לחדר שיש בו מכשיר Nest.

3. הפעלה של מכונת הכביסה החכמה
אם הפעלתם את ה-codelab הפעלת שירותים מקומיים לשילובים בין עננים, כבר הפעלתם את מכונת הכביסה הווירטואלית החכמה. אם הוא הופסק, צריך להפעיל מחדש את המכשיר הווירטואלי.
הפעלת המכשיר
עוברים לספרייה virtual-device/ ומריצים את הסקריפט של המכשיר, ומעבירים את פרמטרי ההגדרה כארגומנטים:
$ cd ../../virtual-device $ npm install $ npm start -- \ --deviceId=deviceid123 --projectId=<project-id> \ --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK
מוודאים שהסקריפט של המכשיר פועל עם הפרמטרים הצפויים:
(...): UDP Server listening on 3311 (...): Device listening on port 3388 (...): Report State successful
4. בדיקה של אפליקציית Local Home
שולחים פקודות למכשיר באמצעות פקודות קוליות למכשיר תואם Google Home, למשל:
"Ok Google, turn on my washer" (הפעלת מכונת הכביסה)
"Ok Google, start my washer" (הפעלת מכונת הכביסה)
"Ok Google, force local" (הפעלת חיפוש מקומי).
"Ok Google, stop my washer"
תשימו לב ש-Google Assistant משיבה "מצטערת, נראה שמכונת הכביסה התקולה לא זמינה כרגע" כשמנסים לשלוט במכונת הכביסה אחרי שמפעילים את האפשרות 'הפעלת המכשיר באופן מקומי'.
כלומר, אי אפשר להגיע למכשיר דרך נתיב מקומי. היא פעלה לפני שהוצאה הפקודה 'Ok Google, force local' כי המערכת תשתמש בנתיב הענן אם אי אפשר להגיע למכשיר דרך נתיב מקומי. אבל אחרי שמפעילים את האפשרות 'כפיית מקומי', אי אפשר לחזור לנתיב הענן.
כדי לגלות מה הבעיה, נשתמש בכלים שיש לנו: מדדים ורישום ביומן של Google Cloud Platform (GCP) וכלים למפתחים ב-Chrome.
5. ניפוי באגים באפליקציית Local Home
בקטע הבא נסביר איך להשתמש בכלים ש-Google מספקת כדי לגלות למה אי אפשר להגיע למכשיר דרך הנתיב המקומי. אתם יכולים להשתמש בהכלים למפתחים ב-Chrome כדי להתחבר למכשיר תואם Google Home, להציג את יומני המסוף ולנפות באגים באפליקציית Local Home. אתם יכולים גם לשלוח יומנים בהתאמה אישית אל Cloud Logging כדי לדעת מהן השגיאות הנפוצות ביותר שהמשתמשים שלכם מוצאים באפליקציית Local Home.
חיבור הכלים למפתחים ב-Chrome
כדי לחבר את מאתר הבאגים לאפליקציה המקומית לביצוע הזמנות, פועלים לפי השלבים הבאים:
- מוודאים שקישרתם את מכשיר תואם Google Home למשתמש שיש לו הרשאה לגשת לפרויקט ב-Developer Console.
- מפעילים מחדש את מכשיר תואם Google Home כדי שהוא יוכל לקבל את כתובת ה-URL של ה-HTML ואת הגדרת הסריקה שהזנתם ב-Play Console.
- מפעילים את Chrome במחשב הפיתוח.
- פותחים כרטיסייה חדשה ב-Chrome ומזינים
chrome://inspectבשדה הכתובת כדי להפעיל את כלי הבדיקה.
בדף אמורה להופיע רשימת מכשירים, וכתובת ה-URL של האפליקציה אמורה להופיע מתחת לשם של מכשיר תואם Google Home.

הפעלת הכלי לבדיקת פריסות
לוחצים על Inspect (בדיקה) מתחת לכתובת ה-URL של האפליקציה כדי להפעיל את הכלים למפתחים ב-Chrome. בוחרים בכרטיסייה Console ומוודאים שאפשר לראות את התוכן של הכוונה IDENTIFY שהודפס על ידי אפליקציית TypeScript.

הפלט הזה מצביע על כך שהפונקציה לטיפול ב-IDENTIFY הופעלה בהצלחה, אבל הערך verificationId שמוחזר ב-IdentifyResponse לא תואם לאף אחד מהמכשירים ב-HomeGraph. כדי לגלות למה, ננסה להוסיף כמה יומנים בהתאמה אישית.
הוספת יומנים מותאמים אישית
למרות שמוצגת שגיאה DEVICE_VERIFICATION_FAILED על ידי Local Home SDK, היא לא עוזרת במיוחד למצוא את שורש הבעיה. כדאי להוסיף כמה יומנים בהתאמה אישית כדי לוודא שאנחנו קוראים ומעבדים את נתוני הסריקה בצורה נכונה. חשוב לדעת שאם נדחה את אובייקט ה-promise עם שגיאה, הודעת השגיאה תישלח גם אל Cloud Logging.
local/index.ts
identifyHandler(request: IntentFlow.IdentifyRequest):
Promise<IntentFlow.IdentifyResponse> {
console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));
const scanData = request.inputs[0].payload.device.udpScanData;
if (!scanData) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_request', 'Invalid scan data');
return Promise.reject(err);
}
// In this codelab, the scan data contains only local device id.
// Is there something wrong here?
const localDeviceId = Buffer.from(scanData.data);
console.log(`IDENTIFY handler: received local device id
${localDeviceId}`);
// Add custom logs
if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_device', 'Invalid device id from scan data ' +
localDeviceId);
return Promise.reject(err);
}
const response: IntentFlow.IdentifyResponse = {
intent: Intents.IDENTIFY,
requestId: request.requestId,
payload: {
device: {
id: 'washer',
verificationId: localDeviceId.toString(),
}
}
};
console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));
return Promise.resolve(response);
}
בנוסף, צריך לשנות את הגרסה של אפליקציית הבית המקומית כדי שנוכל לזהות אם אנחנו משתמשים בגרסה הנכונה.
local/index.ts
const localHomeSdk = new App('1.0.1');
אחרי שמוסיפים את היומנים המותאמים אישית, צריך לקמפל מחדש את האפליקציה ולפרוס אותה מחדש ב-Firebase.
$ cd ../app-faulty/local $ npm run build $ firebase deploy --only hosting
עכשיו צריך להפעיל מחדש את מכשיר תואם Google Home כדי שיוכל לטעון את אפליקציית הבית המקומית המעודכנת. כדי לבדוק אם מכשיר תואם Google Home משתמש בגרסה הצפויה, אפשר לעיין ביומני המסוף ב הכלים למפתחים ב-Chrome.

גישה ל-Cloud Logging
נבדוק איך אפשר להשתמש ב-Cloud Logging כדי למצוא את השגיאות. כדי לגשת ל-Cloud Logging בפרויקט:
- במסוף Cloud Platform, עוברים לדף Projects.
- בוחרים את הפרויקט של הבית החכם.
- בקטע Operations, בוחרים באפשרות Logging > Logs Explorer.
הגישה לנתוני הרישום ביומן מנוהלת באמצעות ניהול זהויות והרשאות גישה (IAM) למשתמשים בפרויקט השילובים. לפרטים נוספים על תפקידים והרשאות לנתוני רישום ביומן, אפשר לעיין במאמר בנושא בקרת גישה ב-Cloud Logging.
שימוש במסננים מתקדמים
אנחנו יודעים שמתרחשות שגיאות בכוונת IDENTIFY, כי הנתיב המקומי לא פועל בגלל שהמכשיר המקומי לא מזוהה. עם זאת, אנחנו רוצים לדעת בדיוק מה הבעיה, ולכן נסנן קודם את השגיאות שמתרחשות ב-handler IDENTIFY.
לוחצים על המתג הצגת שאילתה, והוא אמור להפוך לתיבה כלי ליצירת שאילתות. מזינים jsonPayload.intent="IDENTIFY" בתיבה Query builder ולוחצים על הלחצן Run query.

כתוצאה מכך, תקבלו את כל יומני השגיאות שמוצגים ב-handler של IDENTIFY. אחר כך מרחיבים את השגיאה האחרונה. אפשר לראות את הערכים errorCode ו-debugString שהגדרתם כשדוחים את ה-Promise ב-handler IDENTIFY.

מהפרמטר debugString אפשר לראות שמזהה המכשיר המקומי לא בפורמט הצפוי. אפליקציית Local Home מצפה לקבל את מזהה המכשיר המקומי כמחרוזת שמתחילה ב-deviceid ואחריה 3 ספרות, אבל מזהה המכשיר המקומי כאן הוא מחרוזת הקסדצימלית.
תיקון השגיאה
אם נחזור לקוד המקור שבו אנחנו מנתחים את מזהה המכשיר המקומי מנתוני הסריקה, נראה שלא סיפקנו את הקידוד כשביצענו המרה של המחרוזת לבייטים. נתוני הסריקה מתקבלים כמחרוזת הקסדצימלית, ולכן צריך להעביר את hex כקידוד התווים כשקוראים ל-Buffer.from().
local/index.ts
identifyHandler(request: IntentFlow.IdentifyRequest):
Promise<IntentFlow.IdentifyResponse> {
console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));
const scanData = request.inputs[0].payload.device.udpScanData;
if (!scanData) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_request', 'Invalid scan data');
return Promise.reject(err);
}
// In this codelab, the scan data contains only local device id.
const localDeviceId = Buffer.from(scanData.data, 'hex');
console.log(`IDENTIFY handler: received local device id
${localDeviceId}`);
if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_device', 'Invalid device id from scan data ' +
localDeviceId);
return Promise.reject(err);
}
const response: IntentFlow.IdentifyResponse = {
intent: Intents.IDENTIFY,
requestId: request.requestId,
payload: {
device: {
id: 'washer',
verificationId: localDeviceId.toString(),
}
}
};
console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));
return Promise.resolve(response);
}
בנוסף, צריך לשנות את הגרסה של אפליקציית הבית המקומית כדי שנוכל לזהות אם אנחנו משתמשים בגרסה הנכונה.
local/index.ts
const localHomeSdk = new App('1.0.2');
אחרי שמתקנים את השגיאה, קומפילציה של האפליקציה ופריסה מחדש ב-Firebase. ב-app-faulty/local, מריצים את הפקודה:
$ npm run build $ firebase deploy --only hosting
בדיקת התיקון
אחרי הפריסה, מפעילים מחדש את מכשיר תואם Google Home כדי שיוכל לטעון את אפליקציית הבית המקומי המעודכנת. מוודאים שגרסת אפליקציית הבית המקומי היא 1.0.2, והפעם לא אמורות להופיע שגיאות במסוף של הכלים למפתחים ב-Chrome.

עכשיו אפשר לנסות לשלוח שוב פקודות למכשיר.
"Ok Google, force local".
"Ok Google, stop my washer"
"Ok Google, turn on my washer" (הפעלת מכונת הכביסה)
...
"Ok Google, force default" (הגדרת ברירת מחדל)
6. הפעלת חבילת בדיקות לבית חכם
אחרי שמאמתים את המכשיר באמצעות שליטה באמצעות מגע באפליקציית Google Home או באמצעות פקודות קוליות, אפשר להשתמש בחבילת הבדיקות האוטומטית לבית חכם כדי לאמת תרחישי שימוש על סמך סוגי המכשירים והמאפיינים שמשויכים לשילוב. חבילת הבדיקות מריצה סדרה של בדיקות כדי לזהות בעיות בשילוב, ומציגה הודעות אינפורמטיביות לגבי תרחישי בדיקה שנכשלו כדי לזרז את תהליך ניפוי הבאגים לפני שמתעמקים ביומני האירועים.
הפעלת חבילת הבדיקות לבית חכם
כדי לבדוק את השילוב בין ענן לענן באמצעות Test Suite, פועלים לפי ההוראות הבאות:
- בדפדפן האינטרנט, פותחים את חבילת הבדיקות לבית חכם.
- לוחצים על הכפתור בפינה השמאלית העליונה כדי להיכנס לחשבון Google. כך חבילת הבדיקה יכולה לשלוח את הפקודות ישירות אל Google Assistant.
- בשדה Project ID (מזהה הפרויקט), מזינים את מזהה הפרויקט של השילוב בין ענן לענן. ואז לוחצים על הבא כדי להמשיך.
- בשלב Test Settings (הגדרות בדיקה), מכונת הכביסה הפגומה אמורה להופיע בקטע Devices and Traits (מכשירים ומאפיינים).
- משביתים את האפשרות Test Request Sync כי לאפליקציית הדוגמה למכונת הכביסה אין ממשק משתמש להוספה, להסרה או לשינוי שם של מכונת הכביסה. במערכת ייצור, צריך להפעיל את בקשת סנכרון בכל פעם שהמשתמש מוסיף, מסיר או משנה את השם של מכשירים.
- משאירים את האפשרות Local Home SDK מופעלת כי אנחנו הולכים לבדוק גם נתיבים מקומיים וגם נתיבים בענן.
- כדי להתחיל להריץ את הבדיקה, לוחצים על הבא: סביבת בדיקה.

אחרי שהבדיקות יסתיימו, תשימו לב שהבדיקות של השהיה/הפעלה מחדש בנתיב המקומי נכשלות, בעוד שהבדיקות של השהיה/הפעלה מחדש בנתיב הענן עוברות.

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

מהודעות השגיאה נראה שבהנתיב המקומי, אנחנו מגדירים את המצב isPaused באופן הפוך.
זיהוי ותיקון השגיאה
נחפש את קוד המקור שבו אפליקציית Local Home שולחת את פקודת ההפעלה למכשיר. getDataCommand() היא הפונקציה שמופעלת על ידי executeHandler() כדי להגדיר את payload בפקודת ההפעלה שנשלחת למכשיר.
local/index.ts
getDataForCommand(command: string, params: IWasherParams): unknown {
switch (command) {
case 'action.devices.commands.OnOff':
return {
on: params.on ? true : false
};
case 'action.devices.commands.StartStop':
return {
isRunning: params.start ? true : false
};
case 'action.devices.commands.PauseUnpause':
return {
// Is there something wrong here?
isPaused: params.pause ? false : true
};
default:
console.error('Unknown command', command);
return {};
}
}
אנחנו אכן מגדירים את isPause במצב ההפוך, הוא צריך להיות מוגדר ל-true כש-params.pause הוא true, ול-false בכל מקרה אחר. אז בואו נפתור את זה.
local/index.ts
getDataForCommand(command: string, params: IWasherParams): unknown {
switch (command) {
case 'action.devices.commands.OnOff':
return {
on: params.on ? true : false
};
case 'action.devices.commands.StartStop':
return {
isRunning: params.start ? true : false
};
case 'action.devices.commands.PauseUnpause':
return {
isPaused: params.pause ? true : false
};
default:
console.error('Unknown command', command);
return {};
}
}
לשנות את הגרסה של אפליקציית הבית המקומית, כדי שנוכל לזהות אם אנחנו משתמשים בגרסה הנכונה.
local/index.ts
const localHomeSdk = new App('1.0.3');
חשוב לזכור לקמפל את האפליקציה שוב ולפרוס אותה מחדש ב-Firebase. ב-app-faulty/local, מריצים את הפקודה:
$ npm run build $ firebase deploy --only hosting
עכשיו מפעילים מחדש את מכשיר תואם Google Home כדי שיוכל לטעון את הגרסה המעודכנת של אפליקציית הבית המקומית. חשוב לוודא שגרסת אפליקציית הבית המקומית היא 1.0.3.
בדיקת התיקון
עכשיו מריצים מחדש את חבילת הבדיקות לבית חכם עם אותן הגדרות, ורואים שכל תרחישי הבדיקה עברו בהצלחה.

7. מזל טוב

מעולה! למדתם איך לפתור בעיות באפליקציית Local Home באמצעות חבילת הבדיקה לבית חכם ו-Cloud Logging.
מידע נוסף
הנה כמה דברים נוספים שאפשר לנסות:
- מוסיפים למכשיר עוד מאפיינים נתמכים ומבצעים בדיקה באמצעות Test Suite.
- מוסיפים עוד יומנים מותאמים אישית לכל אחד מה-intent handlers וצופים בהם ב-Cloud Logging.
- כדי לקבל מדדי שימוש מועילים לגבי השילוב, אפשר ליצור מרכזי בקרה, להגדיר התראות ולגשת לנתוני מדדים באופן פרוגרמטי.
אפשר גם לקרוא מידע נוסף על בדיקה ושליחה של שילוב לבדיקה, כולל תהליך האישור לפרסום השילוב למשתמשים.