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

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

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

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

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

מה תפתחו

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

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

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

מה תלמדו

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

הדרישות

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

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

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

2. הגדרה

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

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

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

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

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

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

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

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

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

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

4. לוחצים על Create project.
5. במסך What kind of Action do you want to build?, בוחרים בכרטיס Custom.
6. לוחצים על הבא.
7. במסך איך ברצונך ליצור את הפרויקט?, בוחרים בכרטיס פרויקט ריק.
8. לוחצים על התחלת הפיתוח.

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

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

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

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

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

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

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

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

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

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

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

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

מונח מרכזי:

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

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

הורדת פרויקט Actions

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

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

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

mkdir myproject
cd myproject

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

gactions pull --project-id <projectID>

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

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

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

• ‫actions/: מייצג את הפרויקט שלכם ב-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, talk to <display name>", ההפעלה הראשית מופעלת ומגיבה למשתמש.

כברירת מחדל, הפעולה מספקת הנחיה כללית כשההפעלה מופעלת ("Start building your Action by defining main invocation."‎).

מונח מרכזי:

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

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

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

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

אתם יכולים להשתמש בפקודה gactions deploy preview כדי לבדוק את הפעולה במסוף בלי לעדכן את הגרסה של פרויקט הפעולות. כשמריצים את הפקודה הזו, השינויים שמבצעים במערכת הקבצים המקומית לא מופצים לגרסאות הפרוסות של פרויקט Actions, אבל אפשר לבדוק אותם בגרסת טרום-השקה (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 מגיבה בברכה. בקטע הבא, תשנו את הפעולה כדי שהשיחה תימשך.

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

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

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

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

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

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

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

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

מונחי מפתח:

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

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

לדוגמה, נניח שיש פעולה היפותטית שמספקת למשתמש עובדות על בעלי חיים. כשהמשתמש מפעיל את הפעולה הזו, מתבצעת התאמה ל-intent‏ Main invocation והוא מפעיל את המעבר לסצנה בשם Facts.. המעבר הזה מפעיל את הסצנה Facts, ששולחת למשתמש את ההנחיה הבאה: Would you like to hear a fact about cats or dogs?. בסצנה Facts יש intent בהתאמה אישית בשם Cat, שמכיל ביטויי אימון שהמשתמש עשוי לומר כדי לשמוע עובדה על חתולים, כמו "אני רוצה לשמוע עובדה על חתולים" או "חתול". כשהמשתמש מבקש לשמוע עובדה על חתולים, מתבצעת התאמה ל-intent‏ 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 בשדה Input ולוחצים על Enter. הפעולה אמורה להגיב עם ההנחיה Main invocation וההנחיה של הסצנה שנוספה Start, "Before you continue on your quest, would you like your fortune told?"‎, עם הצגת הצעות קשורות.

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

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

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

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

מונחים מרכזיים:

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

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

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

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

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

הוספת כוונה אחת (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 בסימולטור

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

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

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

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

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

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

הוספת כוונה אחת (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 בסימולטור

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

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

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

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

5. הטמעת מילוי בקשות

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

מונח מרכזי:

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

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

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

מונח מרכזי:

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

הפעולה יכולה להפעיל תגובות לפעולה מאתר אחר (webhooks) שמודיעות למילוי הבקשה על אירוע שמתרחש במהלך הפעלה או בחלקים ספציפיים של ביצוע סצנה. כש-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 מגדיר את ה-handlers של ה-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(&#>39;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, שבודק אם המשתמש ביקר בעבר ב-Action עם המאפיין lastSeenTime. אם המאפיין lastSeenTime לא מוגדר, המשתמש חדש ומקבל את הודעת הפתיחה שמיועדת למשתמשים חדשים. אחרת, ההודעה תציין שהמשתמש חזר ותיצור פתיח שונה.

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

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

כדי להגדיר את הפעולה כך שתפעיל את ה-handler החדש של greeting, פועלים לפי השלבים הבאים:

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

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

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

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

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

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

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 הזה, אתם לא משתמשים חדשים, ולכן אתם מקבלים את הודעת הפתיחה המקוצרת הבאה: "A wondrous greeting, adventurer!‎ ברוכים השבים לארץ המיתולוגית של גריפינברג!…"

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

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

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

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

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

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

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

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

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

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

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

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

7. מעולה!

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

מה כיסיתם

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

מידע נוסף

במקורות המידע הבאים מוסבר איך לפתח פעולות ל-Google Assistant:

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

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

סקר משוב

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