בניית פעולות ל-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 כדי להעביר את פרויקט הפעולה בין קונסולה ל-Actions לבין מערכת הקבצים המקומית
• איך שולחים הנחיה למשתמש אחרי שהוא מפעיל את הפעולה
• איך מעבדים את הקלט של המשתמש ומחזירים תשובה
• איך בודקים את הפעולה בסימולטור הפעולות
• איך מטמיעים מילוי באמצעות העורך של Cloud Functions

הדרישות

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

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

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

2. הגדרה

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

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

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

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

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

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

יצירת פרויקט Actions

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

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

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

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

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

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

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

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

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

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

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

כדי לשייך חשבון לחיוב לפרויקט:

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

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

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

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

מונח מרכזי:

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

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

הורדת פרויקט הפעולות

כדי להתחיל לפתח את ה-Action, מורידים את פרויקט ה-Action מהקונסולה ל-Actions.

כדי להוריד את פרויקט הפעולות:

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

mkdir myproject
cd myproject

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

gactions pull --project-id <projectID>

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

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

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

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

3. התחלת שיחה

המשתמשים מתחילים את השיחה עם הפעולה שלכם באמצעות הפעלה. לדוגמה, אם יש לכם פעולה בשם MovieTime, משתמשים יכולים להפעיל את הפעולה באמצעות אמירת משפט כמו Ok Google, talk to MovieTime, כאשר MovieTime הוא השם לתצוגה. אם רוצים לפרוס את הפעולה בסביבת ייצור, צריך להגדיר לה שם לתצוגה. עם זאת, כדי לבדוק את הפעולה, לא צריך להגדיר את השם לתצוגה. במקום זאת, אפשר להשתמש בביטוי "Talk to my test app" בסימולטור כדי להפעיל את הפעולה. בהמשך הקטע הזה מוסבר על הסימולטור.

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

מונח מרכזי:

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

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

מונח מרכזי:

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

אתם יכולים להשתמש בהנחיה מיוחדת, Canvas, כדי להציג למשתמש תמונות במסך מלא. מידע נוסף על Canvas זמין במסמכי התיעוד של Interactive 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. שומרים את הקובץ.

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

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

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

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

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

טיפ: אפשר גם ללחוץ על הצעת קשורות Talk to my test app בקטע Suggestions (הצעות). ההצעה הזו מעובדת באותו אופן כמו קלט של משתמשים מדובר או מוקלד.

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

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

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

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

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

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

• ‫userInput: תואם לקלט של המשתמש ("Talk to my test app")
• ‫interactionMatch: מתאים לתגובה העיקרית להפעלת הפעולה, שהופעלה על ידי הקלט של המשתמש. אם מרחיבים את השורה הזו על ידי לחיצה על החץ, אפשר לראות את ההנחיה שהוספתם לקריאה הראשית (A wondrous greeting, adventurer!...)
• ‫endConversation: מתאים למעבר שנבחר בMain invocation הכוונה, שמסיים כרגע את השיחה. בקטע הבא של ה-codelab הזה נסביר על מעברים.

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

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

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

מונחי מפתח:

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

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

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

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

בקטע הזה, יוצרים סצנה חדשה בשם 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. יוצרים קובץ חדש בשם Start.yaml בספרייה scenes, שמייצג את סצנת 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 הזה מופיע כיומן האירועים הראשון. כדי לנקות את יומני האירועים, לוחצים על איפוס הבדיקה.

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

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

מונחי מפתח:

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

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

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

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

יצירת כוונה מסוג yes

כדי ליצור את 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. שומרים את הקובץ.

הוספת כוונה 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

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

בדיקת כוונת 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 בשדה Input ומקישים על Enter.
5. מקלידים Yes בשדה קלט ומקישים על Enter. אפשר גם ללחוץ על הצ'יפ עם ההצעה כן.

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

יצירת כוונה מסוג no

עכשיו אפשר ליצור את אובייקט ה-Intent‏ no כדי שהפעולה תוכל להבין את המשתמש ולהגיב לו כשהוא לא רוצה לשמוע את העתיד שלו.

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

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. שומרים את הקובץ.

הוספת כוונה no לסצנה Start

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

כדי להוסיף את הכוונה הזו לסצנה 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. שומרים את הקובץ.

בדיקת כוונת 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 לכוונת no.

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

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

מונח מרכזי:

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

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

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

מונח מרכזי:

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

הפעולה שלכם יכולה להפעיל webhooks ששולחים לכם הודעה על אירוע שמתרחש במהלך הפעלה או בחלקים ספציפיים של ביצוע סצנה. כשמפעילים webhook, הפעולה שולחת בקשה עם מטען ייעודי (payload) בפורמט JSON אל ה-fulfillment, יחד עם שם ה-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 מגדיר את רכיבי ה-handler של ה-webhook (כמו רכיב ה-handler greeting) ומורה לפעולה להשתמש ב-Cloud Functions כנקודת הקצה של ה-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. שומרים את הקובץ.

הסבר על הקוד

ה-fulfillment שלכם, שמשתמש בספריית ה-fulfillment של Actions on Google ל-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. שומרים את הקובץ.

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

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

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

1. במסוף, מריצים את הפקודה הבאה:

הפקודה הזו פורסת את ה-webhook ומתקינה תלויות, ולכן יכול להיות שהיא תימשך יותר זמן מהפקודות הקודמות.

gactions deploy preview

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

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

✔ 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 בשדה Input ומקישים על Enter.

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

6. הצגה חזותית של פעולות באמצעות Actions Builder

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

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

הפעלת הפקודה 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. ב-Actions console, לוחצים על Develop (פיתוח) בסרגל הניווט העליון.
4. לוחצים על החץ לתפריט הנפתח לצד סצנות ואז על התחלה. אמורה להופיע תצוגה חזותית של סצנת Start הפעולה, כמו בצילום המסך הבא:

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

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

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

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

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

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

7. מעולה!

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

מה כיסיתם

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

מידע נוסף

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

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

כדי לקבל את ההודעות האחרונות, אפשר לעקוב אחרי ‎@ActionsOnGoogle בטוויטר ולצייץ עם ההאשטאג ‎#AoGDevs כדי לשתף את מה שאתם יוצרים.

סקר משוב

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