בניית פעולות ל-Google Assistant באמצעות Actions SDK (רמה 1)

1. סקירה כללית

אזהרה: ב-13 ביוני 2023 הוצאנו משימוש את התכונה 'פעולות בממשק שיחה'. למידע נוסף, ראו סגירה של 'פעולות בשיחה'.

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

ה-Codelab הזה עוסק במושגים ברמה מתחילים לפיתוח באמצעות Actions SDK ל-Google Assistant; אין צורך בניסיון קודם עם הפלטפורמה כדי להשלים אותה. בשיעור ה-Codelab הזה, אתם מפתחים פעולה פשוטה ל-Google Assistant שמספרת למשתמשים את מזלם כשהם מתחילים את ההרפתקה שלהם בארץ המיתית גריפינברג. ב-Codelab של Actions SDK ברמה 2, אפשר לפתח את הפעולה הזו עוד יותר כדי להתאים אישית את מזל המשתמש על סמך הקלט שלו.

מה תפַתחו

ב-Codelab הזה, מפתחים פעולה פשוטה עם הפונקציות הבאות:

• מענה למשתמשים עם הודעת ברכה
• מציג למשתמשים שאלה ומגיב בהתאם לבחירות של המשתמשים
• מספק צ'יפים של הצעות שהמשתמשים יכולים ללחוץ עליהם כדי לספק קלט
• שינוי הודעת הפתיח למשתמש בהתאם לשאלה אם הוא משתמש חוזר

בסיום ה-Codelab הזה, הפעולה שהושלמה תתחיל את תהליך השיחה הבא (הטקסט ליד המיקרופון מייצג את הקלט של המשתמש, ואילו הטקסט לצד הדובר מייצג את התגובה של הפעולה):

מה תלמדו

• איך יוצרים פרויקט במסוף Actions
• איך משתמשים בכלי gactions כדי לדחוף ולייצא את פרויקט הפעולה בין מסוף הפעולות למערכת הקבצים המקומית
• איך לשלוח הודעה למשתמש אחרי שהוא הפעיל את הפעולה
• איך לעבד קלט של משתמש ולהחזיר תשובה
• איך בודקים את הפעולה בסימולטור הפעולות
• איך מטמיעים מילוי הזמנות באמצעות עורך Cloud Functions

מה נדרש

הכלים הבאים חייבים להיות בסביבה שלכם:

• סביבת פיתוח משולבת (IDE) או עורך טקסט לבחירתך
• טרמינל להרצת פקודות מעטפת עבור Node.js ו-npm
• דפדפן אינטרנט, כמו Google Chrome

אם אתם מעדיפים לעבוד עם כלים חזותיים יותר כדי ליצור פעולות, אתם יכולים במקום זאת לבצע Build Actions for Google Assistant באמצעות Codelab ב-Actions Builder (רמה 1), שבו נבנה את אותה הפעולה באמצעות Actions Builder IDE במסוף.

2. הגדרה

בקטעים הבאים מוסבר איך להגדיר את סביבת הפיתוח וליצור פרויקט Actions.

איך בודקים את הגדרות ההרשאות ב-Google

כדי לבדוק את הפעולה שאתם יוצרים ב-Codelab הזה, צריך להפעיל את ההרשאות הדרושות כדי שהסימולטור יוכל לגשת לפעולה.

כדי להפעיל הרשאות, מבצעים את השלבים הבאים:

1. עוברים אל בקרת הפעילות בחשבון.
2. נכנסים לחשבון Google, אם עוד לא עשיתם זאת.
3. מפעילים את ההרשאות הבאות:

• פעילות באינטרנט ובאפליקציות
• בקטע אינטרנט ו פעילות באפליקציות, מסמנים את התיבה הכללה של ההיסטוריה והפעילות של Chrome מאתרים, מאפליקציות וממכשירים המשתמשים בשירותי Google**.

יוצרים פרויקט ב-Actions

פרויקט הפעולות הוא מאגר של הפעולה.

כדי ליצור פרויקט פעולות עבור ה-Codelab הזה, מבצעים את השלבים הבאים:

1. פותחים את מסוף Actions.
2. לוחצים על פרויקט חדש.
3. מזינים Project name, לדוגמה actions-codelab. (השם מיועד לעיונך הפנימי. לאחר מכן, אפשר להגדיר שם חיצוני לפרויקט.)

4. לוחצים על Create project.
5. במסך איזה סוג של פעולה ברצונך ליצור?, בוחרים את הכרטיס בהתאמה אישית.
6. לוחצים על הבא.
7. במסך איך ברצונך לבנות אותו?, בוחרים את הכרטיס פרויקט ריק.
8. לוחצים על התחלת הבנייה.

שמירת מזהה הפרויקט לפעולה

מזהה הפרויקט הוא מזהה ייחודי של הפעולה. צריך את מזהה הפרויקט למספר שלבים ב-Codelab הזה.

כדי לאחזר את מזהה הפרויקט, פועלים לפי השלבים הבאים:

1. במסוף הפעולות, לוחצים על שלוש הנקודות האנכיות (הוספת הסמל כאן).
2. לוחצים על Project settings (הגדרות הפרויקט).

3. מעתיקים את מזהה הפרויקט**.**

שיוך של חשבון לחיוב

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

כדי לשייך חשבון לחיוב לפרויקט, מבצעים את השלבים הבאים:

1. נכנסים לדף החיוב של Google Cloud Platform.
2. לוחצים על הוספת חשבון לחיוב או על יצירת חשבון.
3. מזינים את פרטי התשלום.
4. לוחצים על התחלת תקופת הניסיון בחינם או על שליחה והפעלת החיוב.
5. נכנסים לדף החיוב של Google Cloud Platform.
6. לוחצים על הכרטיסייה הפרויקטים שלי.
7. לוחצים על תפריט שלוש הנקודות בקטע Actions (פעולות) לצד הפרויקט Actions (פעולות) ב-Codelab.
8. לוחצים על שינוי החיוב.
9. בתפריט הנפתח, בוחרים את החשבון לחיוב שהגדרתם.
10. לוחצים על Set account.

כדי להימנע מחיובים, פועלים לפי השלבים שבקטע 'ניקוי הפרויקט' בסוף השיעור הזה.

התקנה של ממשק שורת הפקודה gactions

ב-Codelab הזה משתמשים בכלי שורת הפקודה (CLI) של gactions כדי לסנכרן את הפרויקט ב-Actions בין מסוף הפעולות למערכת הקבצים המקומית.

מונח מפתח:

• gactions CLI: כלי שמאפשר לאתחל קבצים של פרויקטים של פעולות, לדחוף עדכונים למסוף Actions, לפרוס פרויקטים של 'פעולות' ועוד.

כדי להתקין את ה-CLI של gactions, פועלים לפי ההוראות במאמר התקנת כלי שורת הפקודה gactions.

מורידים את פרויקט Actions

כדי להתחיל לפתח את הפעולה, מורידים את פרויקט Actions ממסוף הפעולות.

כדי להוריד את פרויקט הפעולות, פועלים לפי השלבים הבאים:

1. כדי ליצור ספרייה חדשה ולבצע בה שינויים, מריצים את הפקודות הבאות:

mkdir myproject
cd myproject

2. כדי להעתיק את ההגדרות של פרויקט Actions למערכת הקבצים המקומית, מריצים את הפקודה הבאה:

gactions pull --project-id <projectID>

הסבר על מבנה הקובץ

פרויקט הפעולות שמורידים ממסוף הפעולות מיוצג במבנה קבצים YAML. התמונה הבאה מציגה ייצוג ברמה גבוהה של מבנה הקובץ:

מבנה הקובץ מורכב מהרכיבים הבאים:

• actions/: מייצג את פרויקט הפעולות שלכם. כשהפעולה מופעלת, המערכת קוראת ל-actions.yaml, וקוראת לקובץ custom/global/actions.intent.MAIN.yaml.
• custom/: הספרייה שבה אתם עובדים כדי לשנות את הפעולה.
• global/: הספרייה הזו מכילה אובייקטים מסוג Intent של המערכת שהפלטפורמה מוסיפה לפרויקט באופן אוטומטי. בהמשך נסביר ב-Codelab הזה מידע נוסף על כוונות מערכת.
• manifest.yaml: קובץ שמכיל מידע שניתן להעביר או לא ספציפי לפרויקט נתון, ואפשר להעביר אותו בין פרויקטים.
• settings/: מייצג את ההגדרות של פרויקט פעולות, כמו השם המוצג, הלוקאל והקטגוריה שמוגדרים כברירת מחדל.

3. התחלת שיחה

המשתמשים מתחילים את השיחה עם הפעולה באמצעות הפעלה. לדוגמה, אם יש פעולה בשם MovieTime, המשתמשים יכולים להפעיל את הפעולה על ידי אמירת ביטוי כמו "Ok Google, talk to Movies to MovieTime", כאשר MovieTime הוא השם המוצג. לפעולה חייב להיות שם לתצוגה אם רוצים לפרוס אותה לסביבת הייצור. עם זאת, כדי לבדוק את הפעולה אין צורך להגדיר את השם המוצג. במקום זאת, אפשר להשתמש בביטוי "דיבור אל אפליקציית הבדיקה שלי" בסימולטור כדי להפעיל את הפעולה. מידע נוסף על הסימולטור מופיע בהמשך הקטע הזה.

צריך לערוך את ההפעלה הראשית כדי להגדיר מה קורה אחרי שמשתמש מפעיל את הפעולה.

מונח מפתח:

• הפעלה ראשית: נקודת כניסה שבה המשתמשים יכולים להתחיל שיחות עם הפעולה. כשמשתמשים אומרים ביטוי שדומה ל-"Ok Google, talk to <display name>", ההפעלה הראשית מופעלת ומגיבה למשתמש.

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

מונח מפתח:

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

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

בקטע הבא תתבצע התאמה אישית של ההנחיה להפעלה הראשית של הקובץ custom/global/actions.intent.MAIN.yaml.

הגדרת ההפעלה הראשית

אפשר לערוך את בקשת ההפעלה הראשית בקובץ actions.intent.MAIN.yaml.

כדי לשנות את ההנחיה שהפעולה שולחת חזרה למשתמש כשהוא מפעיל את הפעולה, פועלים לפי השלבים הבאים:

1. פותחים את custom/global/actions.intent.MAIN.yaml בכלי לעריכת טקסט.
2. מחליפים את הטקסט שבשדה speech (Start building your action...) בהודעת הפתיחה הבאה: A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: A wondrous greeting, adventurer! Welcome to the mythical land of 
                Gryffinberg! Based on your clothes, you are not from around these lands. 
                It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION

3. שומרים את הקובץ.

בודקים את ההפעלה הראשית בסימולטור

מסוף הפעולות הוא כלי אינטרנטי לבדיקת הפעולה שלך, שנקרא הסימולטור. הממשק מדמה מכשירי חומרה ואת ההגדרות שלהם, כך שאפשר לשוחח עם הפעולה כאילו היא פועלת במסך חכם, בטלפון, ברמקול או ב-KaiOS.

לקבלת המידע העדכני ביותר על השימוש בסימולטור של מסוף הפעולות, או אם נתקלים בבעיות בשלבים הבאים, עיינו בדף הסימולטור.

עכשיו, כשמפעילים את הפעולה, היא אמורה להגיב עם ההנחיה המותאמת אישית שהוספתם ("פתיח מדהים, הרפתקנים!...").

אפשר להשתמש בפקודה gactions deploy preview כדי לבדוק את הפעולה במסוף בלי לעדכן את הגרסה של פרויקט הפעולות. כשמריצים את הפקודה הזו, השינויים שמתבצעים במערכת הקבצים המקומית לא מופצים לגרסאות פרוסות של פרויקט הפעולות שלכם, אבל אפשר לבדוק אותם בגרסת תצוגה מקדימה.

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

1. כדי לפרוס את הפרויקט במסוף Actions לבדיקה, מריצים את הפקודה הבאה בטרמינל:

gactions deploy preview

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

הפלט אמור להיראות כך:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. מעתיקים את כתובת ה-URL שצוינה ומדביקים אותה בדפדפן.
3. כדי להפעיל את הפעולה בסימולטור, מקלידים Talk to my test app בשדה קלט ולוחצים על Enter.

טיפ: אפשר גם ללחוץ על צ'יפ ההצעה דיבור אל אפליקציית הבדיקה שלי בקטע הצעות, שמעובד באותו אופן כמו קלט של משתמשים בדיבור או בהקלדה.

לחלופין, אפשר ללחוץ על סמל המיקרופון ולומר "Talk to my test app" כדי להפעיל את הפעולה.

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

צפייה ביומני אירועים

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

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

אם תלחצו על החץ למטה שליד Talk to my test app ביומן האירועים, תוכלו לראות את האירועים, בסדר כרונולוגי, שהתרחשו באותה שיחה:

• userInput: תואם לקלט של המשתמש ("דיבור אל אפליקציית הבדיקה שלי")
• interactionMatch: תואמת לתגובת ההפעלה הראשית של הפעולה, שהופעלה על ידי הקלט של המשתמש. אם תרחיב את השורה הזו באמצעות לחיצה על החץ, תהיה לך אפשרות לראות את ההנחיה שהוספת להפעלה הראשית (A wondrous greeting, adventurer!...)
• endConversation: תואם למעבר שנבחר ב-Intent Main invocation, שמסתיים עכשיו בשיחה. בקטע הבא ב-Codelab הזה יש מידע נוסף על מעברים.

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

4. יצירת השיחה של הפעולה

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

מונחי מפתח:

• תרחיש: אבן בניין של הפעולה, שמעבדת את הקלט של המשתמשים ולרוב יוצרת את התגובה למשתמש. הרבה פעמים, אובייקטים בהתאמה אישית עם כוונת רכישה מפעילים סצנות אחרות, אבל אפשר להפעיל סצנות גם בדרכים אחרות.
• קהל בהתאמה אישית לפי העדפות תוכן: מגדיר קלט של משתמשים שהפעולה יכולה להבין. אתם מגדירים את ביטויי האימון לכוונות האלה. כשמשתמשים אומרים משהו שתואם לביטוי אימון או דומה לו, מתבצעת התאמה לכוונה המתאימה.
• ביטויים לאימון: דוגמאות למה שמשתמש עשוי לומר כדי להתאים לכוונה. המנוע של 'הבנת שפה טבעית' (NLU) של Assistant מרחיב באופן טבעי את ביטויי האימון האלה כך שיכללו ביטויים דומים אחרים.
• מעבר: הגדרת הסצנה שאליה צריך לעבור אחרי שמתקיים התנאי.

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

לדוגמה, נניח על פעולה היפותטית שמספקת למשתמש עובדות לגבי בעלי החיים. כשהמשתמש מפעיל את הפעולה הזו, ה-Intent Main invocation תואם ומפעיל את המעבר לסצנה בשם Facts.. המעבר הזה מפעיל את הסצנה Facts, ששולחת למשתמש את ההנחיה הבאה: Would you like to hear a fact about cats or dogs? בתוך הסצנה Facts קיימת כוונת בהתאמה אישית בשם Cat, שמכילה ביטויי אימון שהמשתמשים עשויים לומר כדי לשמוע עובדה על חתולים, כמו "אני רוצה לשמוע עובדה על חתול" או "חתול". כשהמשתמש מבקש לשמוע עובדה על חתולים, המערכת תואמת לכוונה Cat ומופעלת מעבר לסצנה שנקראת Cat fact. הסצנה Cat fact מופעלת ושולחת למשתמש הנחיה שכוללת עובדה על חתולים.

איור 1. התהליך של הפעלה אופיינית של שיחה בפעולה שנוצרה באמצעות Actions SDK.

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

מעבר מההפעלה הראשית לסצנה

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

כדי ליצור את הסצנה הזו ולהוסיף לה מעבר:

1. פותחים את custom/global/actions.intent.MAIN.yaml בכלי לעריכת טקסט.
2. מחליפים את הטקסט שבשדה transitionToScene (actions.scene.END_CONVERSATION) בערך הבא: transitionToScene: Start

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Welcome to the mythical land of  Gryffinberg! Based on your clothes,
              you are not from around these lands. It looks like you're on your way
              to an epic journey.
transitionToScene: Start

הפעולה הזו מנחה את הפעולה לעבור מההפעלה הראשית לסצנה של Start.

3. שומרים את הקובץ.
4. בטרמינל, יוצרים ספריית scenes חדשה בספרייה custom:

mkdir custom/scenes 

5. יוצרים בספרייה scenes קובץ חדש בשם Start.yaml, שמייצג את הסצנה start בפעולה:

touch custom/scenes/Start.yaml 

6. פותחים את Start.yaml בכלי לעריכת טקסט.
7. מדביקים את הקוד הבא בקובץ Start.yaml:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

בקוד הקובץ Start.yaml יש שדה בשם onEnter, שהוא השלב הראשון שפועל במחזור החיים של סצנה.

מונחי מפתח:

• OnEnter: השלב שמופעל כשסצנה מופעלת. OnEnter מגדיר מה קורה כשהמשתמש נכנס לסצנה.

במקרה הזה, ההנחיה (Before you continue on your quest...) מתווספת לתור ההנחיות כשהמשתמש נכנס לסצנה Start בפעם הראשונה.

מונחי מפתח:

• תור ההנחיות: ההנחיות מצורפות זו לזו בתור ההנחיות. לפני שהמשתמש יוכל להגיב, Assistant מציגה למשתמש את כל ההנחיות בתור ההנחיות.

הוספת צ'יפים של הצעות

צ'יפים של הצעות מכילים הצעות למשתמש שניתן ללחוץ עליהן, שאותן הפעולה מעבדת כקלט של משתמשים. בקטע הזה מוסיפים צ'יפים של הצעות Yes ו-No שמופיעים מתחת להנחיה שהגדרת עכשיו (Before you continue on your quest, would you like your fortune told?) כדי לתמוך במשתמשים במכשירים עם מסכים.

כדי להוסיף צ'יפים של הצעות להנחיה של הסצנה Start, פועלים לפי השלבים הבאים:

1. צריך לעדכן את הקוד ב-Start.yaml כך שיתאים לקטע הקוד הבא, שכולל את הקוד להגדרת צ'יפים של הצעות:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. שומרים את הקובץ.

בדיקת הפעולה בסימולטור

בשלב הזה, הפעולה צריכה לעבור מההפעלה הראשית לסצנה של Start, ולשאול את המשתמש אם הוא רוצה לשמוע את עתידו. צ'יפים של הצעות אמורים להופיע גם בתצוגה הסימולציה.

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

1. בטרמינל, מריצים את הפקודה הבאה:

gactions deploy preview

הפלט אמור להיראות כך:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. מעתיקים את כתובת ה-URL שצוינה ומדביקים אותה בדפדפן.
3. לוחצים על בדיקה כדי לעבור לסימולטור.
4. מקלידים Talk to my test app בשדה קלט ומקישים על Enter. הפעולה אמורה לכלול את ההנחיה Main invocation והנחיה נוספת לסצנה Start, "לפני שממשיכים בקווסט", יופיעו הצ'יפים של ההצעות.

האינטראקציה הזו מוצגת בצילום המסך הבא:

יומני האירועים מתעדים כל אחת מהאינטראקציות שלך בסימולטור בסשן הנוכחי, כך שיומן האירועים מהבדיקה שביצעת קודם לכן ב-Codelab הזה מופיע כיומן האירועים הראשון. כדי לנקות את יומני האירועים, לוחצים על Reset Test (איפוס הבדיקה).

5. לוחצים על הצ'יפ כן או לא כדי לענות להנחיה. (אפשר גם לומר "כן" או "לא" או להזין Yes או No בשדה קלט).

כשמגיבים להנחיה, הפעולה משיבה הודעה שמציינת שהיא לא מבינה את הנתונים שהזנת: "סליחה, לא הבנתי. תוכל לנסות שוב?" עדיין לא הגדרת את הפעולה כך שהיא תבין את הקלט "כן" או "לא" ושתענה עליה, ולכן הפעולה מתאימה את הקלט ל-Intent מסוג NO_MATCH.

מונחי מפתח:

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

כברירת מחדל, הכוונה של המערכת NO_MATCH מספקת תגובות כלליות, אבל אפשר להתאים אישית את התשובות האלה כדי לציין למשתמש שלא הבנת את הקלט שלו. Assistant מסיימת את השיחה של המשתמש עם הפעולה אחרי שהיא לא יכולה להתאים לקלט של משתמשים שלוש פעמים.

הוספת yes ו-no כוונות

עכשיו המשתמשים יכולים להגיב לשאלה שהפעולה יוצרת, אתם יכולים להגדיר את הפעולה כדי להבין את המשתמשים תשובות ("כן" או "לא"). בקטעים הבאים, צריך ליצור קהלים בהתאמה אישית עם כוונת רכישה שמולאו כשהמשתמש אומר "כן" או "לא", ולהוסיף את הכוונות האלה לסצנה Start.

יצירת Intent מסוג yes

כדי ליצור את Intent מסוג yes, צריך לפעול לפי השלבים הבאים:

1. בטרמינל, יוצרים ספרייה חדשה בשם intents בספרייה custom:

mkdir custom/intents 

2. יוצרים קובץ חדש בשם yes.yaml בספרייה intents:

touch custom/intents/yes.yaml

3. פותחים את yes.yaml בכלי לעריכת טקסט.
4. מדביקים ב-yes.yaml את קטע הקוד הבא שמכיל ביטויי אימון:

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. שומרים את הקובץ.

הוספת Intent מסוג yes לסצנה אחת (Start)

עכשיו הפעולה יכולה להבין מתי משתמש מביע הכוונה מסוג כן. אפשר להוסיף את yes בהתאמה אישית עם כוונת רכישה לסצנה Start, כי המשתמש מגיב להנחיה Start ("לפני שממשיכים בקווסט, רוצה לדעת על זה?").

כדי להוסיף את הקהל בהתאמה אישית עם כוונת רכישה לסצנה Start, צריך לבצע את השלבים הבאים:

1. פותחים את custom/scenes/Start.yaml בכלי לעריכת טקסט.
2. מוסיפים את ה-handler intentEvents ו-yes לסוף הקובץ Start.yaml:

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

כאשר מתבצעת התאמה ל-Intent של yes, ההנחיה "העתיד שלך תלוי בפריט שבו תבחר להשתמש בקווסט..." תתווסף לתור ההנחיות. אחר כך הסצנה Start עוברת לסצנת המערכת של actions.scene.END_CONVERSATION, שבה יוצגו ההנחיות בתור ההנחיות ותסיים את השיחה.

בדיקת ה-Intent של yes בסימולטור

בשלב הזה, הפעולה מבינה מתי המשתמש רוצה לשמוע את מזלו ומחזירה את התשובה המתאימה.

כדי לבדוק את הכוונה הזו בסימולטור, פועלים לפי השלבים הבאים:

1. בטרמינל, מריצים את הפקודה הבאה:

gactions deploy preview

הפלט אמור להיראות כך:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. מעתיקים את כתובת ה-URL שצוינה ומדביקים אותה בדפדפן.
3. לוחצים על בדיקה כדי לעבור לסימולטור.
4. כדי לבדוק את הפעולה בסימולטור, מקלידים Talk to my test app בשדה קלט ולוחצים על Enter.
5. מקלידים Yes בשדה קלט ומקישים על Enter. לחלופין, לוחצים על צ'יפ ההצעה כן.

הפעולה מגיבה למשתמש ואומרת לו שמזלו תלוי בסיוע שהוא בוחר. לאחר מכן הפעולה מסיימת את הסשן כי הגדרת את המעבר של End conversation ל-Intent מסוג yes.

יצירת Intent מסוג no

עכשיו אפשר ליצור את הכוונה מסוג no כדי שהפעולה תוכל להבין את המשתמש ולהגיב לו כשהוא לא רוצה לשמוע את מזלו.

כדי ליצור את Intent, צריך לפעול לפי השלבים הבאים:

1. בטרמינל, יוצרים קובץ חדש בשם no.yaml בספרייה intents:

touch custom/intents/no.yaml

2. פותחים את no.yaml בכלי לעריכת טקסט.
3. מדביקים את ביטויי האימון הבאים בקובץ no.yaml:

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. שומרים את הקובץ.

הוספת Intent מסוג no לסצנה אחת (Start)

עכשיו הפעולה יכולה לזהות מתי משתמש אומר "לא" או משהו בסגנון "לא", כמו "לא". צריך להוסיף את no בהתאמה אישית עם כוונת רכישה לסצנה Start כי המשתמש מגיב להנחיה Start ("לפני שממשיכים בקווסט, רוצה לדעת על זה?").

כדי להוסיף את ה-Intent הזה לסצנה Start, צריך לבצע את השלבים הבאים:

1. פותחים את custom/scenes/Start.yaml בכלי לעריכת טקסט.
2. מוסיפים את ה-handler הבא של no מתחת ל-handler של yes ב-Start.yaml:

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. שומרים את הקובץ.

בדיקת ה-Intent של no בסימולטור

בשלב הזה, הפעולה מבינה מתי המשתמש לא רוצה לשמוע את מזלו ומחזירה את התשובה המתאימה.

כדי לבדוק את הכוונה הזו בסימולטור, פועלים לפי השלבים הבאים:

1. בטרמינל, מריצים את הפקודה הבאה:

gactions deploy preview

הפלט אמור להיראות כך:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. מעתיקים את כתובת ה-URL שצוינה ומדביקים אותה בדפדפן.
3. לוחצים על בדיקה כדי לעבור לסימולטור.
4. מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
5. מקלידים No בשדה קלט ומקישים על Enter. אפשר גם ללחוץ על הצ'יפ של ההצעה No.

במקום לתת למשתמש את מזלו, הפעולה מאחלת לו הצלחה במסע. לאחר מכן הפעולה מסיימת את הסשן כי הגדרת את המעבר של End conversation ל-Intent מסוג no.

5. הטמעת מילוי הזמנות

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

מונח מפתח:

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

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

ב-Codelab הזה, משתמשים בעורך Cloud Functions כדי לערוך ולפרוס את הקוד למילוי ההזמנות.

מונח מפתח:

• עורך Cloud Functions: כלי עריכה משולב לפרויקטים של פעולות, שבו אפשר להשתמש כדי לערוך ולפרוס את קוד מילוי ההזמנות באמצעות Cloud Functions for Firebase.

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

בונים את אופן מילוי ההזמנות

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

כדי להוסיף את הלוגיקה הזו למילוי ההזמנות:

1. בטרמינל, מוודאים שנמצאים בתיקיית השורש של הפרויקט ויוצרים ספריית webhooks חדשה:

mkdir webhooks 

2. יוצרים קובץ חדש בשם ActionsOnGoogleFulfillment.yaml בספרייה webhooks:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. פותחים את ActionsOnGoogleFulfillment.yaml בכלי לעריכת טקסט.
4. מוסיפים את ה-handler של greeting ואת התוכן inlineCloudFunction לקובץ ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

הקובץ ActionsOnGoogleFulfillment.yaml מגדיר את הגורמים המטפלים ב-webhook (כמו ה-handler של greeting) ואומר לפעולה להשתמש ב-Cloud Functions כנקודת הקצה (endpoint) של התגובה לפעולה מאתר אחר (webhook).

5. יוצרים ספריית ActionsOnGoogleFulfillment חדשה בספרייה webhooks:

mkdir webhooks/ActionsOnGoogleFulfillment

6. יוצרים קובץ חדש בשם index.js בספרייה ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. פותחים את index.js בכלי לעריכת טקסט.
8. מוסיפים ל-index.js את הקוד הבא:

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});


exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

הקוד הזה מגדיר את ה-handler של greeting, ששולח את הודעת הפתיחה המתאימה

משתמש.

9. שומרים את הקובץ.
10. יוצרים קובץ חדש בשם package.json בספרייה ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/package.json

בקובץ package.json מפורטים יחסי תלות ומטא-נתונים נוספים של ה-webhook.

11. פותחים את package.json בכלי לעריכת טקסט.
12. מעתיקים את הקוד ממאגר ה-GitHub הזה ומדביקים אותו בקובץ package.json.
13. שומרים את הקובץ.

הסבר על הקוד

מילוי הבקשה, שמשתמש בספריית Actions on Google Fulfillment ל-Node.js, מגיב לבקשות HTTP מ-Google Assistant.

בקטע הקוד הקודם, מגדירים את ה-handler greeting, שבודק אם המשתמש ביקר בעבר בפעולה עם המאפיין lastSeenTime. אם המאפיין lastSeenTime לא מוגדר, המשתמש חדש ומקבל את הודעת הפתיחה שמיועדת למשתמשים חדשים. אם לא, ההודעה מאשרת את חזרת המשתמש ותיצור הודעת פתיחה עם שינוי.

עדכון ההפעלה הראשית כדי להפעיל webhook

אחרי שמגדירים את הפונקציה greeting, אפשר להגדיר את הגורם המטפל באירועים של greeting בכוונת ההפעלה הראשית, כדי שהפעולה תדע לקרוא לפונקציה הזו כשהמשתמש יפעיל את הפעולה.

כדי להגדיר לפעולה קריאה ל-handler החדש greeting:

1. פותחים את custom/global/actions.intent.MAIN.yaml בכלי לעריכת טקסט.
2. מחליפים את הקוד שב-actions.intent.MAIN.yaml בקוד הבא:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. שומרים את הקובץ.

עכשיו, כשכוונת ההפעלה העיקרית תואמת, מתבצעת קריאה ל-handler של ה-webhook greeting.

בדיקת ההפעלה הראשית המעודכנת בסימולטור

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

1. בטרמינל, מריצים את הפקודה הבאה:

הפקודה הזו פורסת את התגובה לפעולה מאתר אחר (webhook) ומתקינה יחסי תלות, ולכן יכול להיות שייקח יותר זמן מהפקודות הקודמות.

gactions deploy preview

אם מקבלים שגיאת 403 לגבי Cloud Build API או שגיאה 403 לגבי שיוך החשבון לחיוב, כדאי לעיין במאמר הפעלה, השבתה ושינוי של חיוב בפרויקט. כדי לפרוס באמצעות Cloud Functions, עליכם לשייך חשבון לחיוב לפרויקט שלכם ב-Google Cloud. אחרי שיוך חשבון לחיוב, מריצים שוב את gactions deploy preview. כדי להימנע מחיובים, פועלים לפי השלבים שבקטע 'ניקוי הפרויקט' בסוף השיעור הזה.

הפלט אמור להיראות כך:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. מעתיקים את כתובת ה-URL שצוינה ומדביקים אותה בדפדפן.
3. כדי לבדוק את הפעולה בסימולטור, מקלידים Talk to my test app בשדה קלט ולוחצים על Enter.

מכיוון שבדקת את הפעולה מוקדם יותר ב-Codelab הזה, אינך משתמש חדש ולכן קיבלת את הודעת הפתיחה המקוצרת הבאה: "שלום לכולם, הרפתקנים! ברוכים השבים לארץ המיתית של גריפינברג!..."

6. המחשת פעולה בעזרת Actions Builder

ל-Actions SDK יש יכולת פעולה הדדית עם סביבת פיתוח משולבת (IDE) מבוססת-אינטרנט שנקראת Actions Builder (פעולות) שמשולבת במסוף Actions. אפשר להעביר את מערכת הקבצים המקומית לטיוטה של הפעולה במסוף באמצעות הפקודה gactions push. בניגוד ל-gactions deploy preview, שמאפשר לבדוק רק את הפעולה בסימולטור, מערכת gactions push מעבירה את כל התוכן מהקבצים המקומיים אל 'הכלי ליצירת פעולות'.

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

הרצה של gactions push מבטלת את הטיוטה הנוכחית של פרויקט הפעולות אם עובדים בשיתוף פעולה.

כדי לדחוף את הפרויקט 'פעולות' ולהציג אותו במסוף הפעולות, מבצעים את השלבים הבאים:

1. בטרמינל, מריצים את הפקודה הבאה כדי לדחוף את הפרויקט למסוף Actions:

gactions push

הפלט אמור להיראות כך:

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. מעתיקים את כתובת ה-URL שצוינה ומדביקים אותה בדפדפן.
3. במסוף הפעולות, לוחצים על פיתוח בסרגל הניווט העליון.
4. לוחצים על החץ לתפריט הנפתח לצד תרחישים ולוחצים על התחלה. אתם אמורים לראות ייצוג חזותי של הסצנה Start של הפעולה, כמו בצילום המסך הבא:

פינוי מקום בפרויקט [מומלץ]

זהירות: ה-Codelab ברמה 2, Build Actions for Google Assistant באמצעות Actions SDK (רמה 2), מבוסס על הפרויקט שיצרתם ב-Codelab הזה. אם אתם מתכננים לבצע את ה-Codelab ברמה 2, אל תמחקו את הפרויקט. במקום זאת, אפשר למחוק אותו בקטע 'ניקוי הפרויקט'. בסוף ה-Codelab ברמה 2.

כדי להימנע מחיובים אפשריים, מומלץ להסיר פרויקטים שלא מתכוונים להשתמש בהם. כדי למחוק את הפרויקטים שיצרתם ב-Codelab הזה, מבצעים את השלבים הבאים:

1. כדי למחוק את הפרויקט והמשאבים ב-Cloud, מבצעים את השלבים שמפורטים בקטע כיבוי (מחיקה) של פרויקטים.

מוודאים שבחרתם את הפרויקט הנכון למחיקה בדף הגדרות Google Cloud Platform.

2. אופציונלי: כדי להסיר מיד את הפרויקט ממסוף הפעולות, מבצעים את השלבים המפורטים בקטע מחיקת פרויקט. אם לא תשלימו את השלב הזה, הפרויקט יוסר באופן אוטומטי אחרי כ-30 ימים.

7. מעולה!

אתם מכירים את היסודות של בניית פעולות ל-Google Assistant בעזרת Actions SDK.

מה נכלל בקורס

• איך מגדירים פרויקט Actions במסוף Actions
• איך משתמשים ב-Actions SDK כדי לבנות את הפרויקט ב-Actions במערכת הקבצים המקומית
• איך להוסיף הנחיה להפעלה הראשית כדי שהמשתמשים יוכלו להתחיל שיחה עם הפעולה
• איך ליצור ממשק שיחה עם סצנות, כוונות, מעברים, צ'יפים של הצעות ומילוי הזמנות
• איך בודקים את הפעולה באמצעות סימולטור הפעולות

מידע נוסף

מידע נוסף על יצירת פעולות ל-Google Assistant זמין במקורות המידע הבאים:

• אתר התיעוד הרשמי לפיתוח פעולות ל-Google Assistant
• פעולות בדף Google GitHub של ספריות וקוד לדוגמה
• הקהילה הרשמית של Reddit למפתחים שעובדים עם Assistant

עוקבים אחרי @ActionsOnGoogle ב-Twitter כדי לקבל את העדכונים האחרונים. לשלוח ציוץ אל #AoGDevs כדי לשתף את הפיתוחים שלכם.

סקר משוב

לפני היציאה לדרך, יש למלא סקר קצר על החוויה שלך.