יצירת פעולות ל-Google Assistant באמצעות Actions Builder (רמה 2)

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

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

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

ב-codelab הזה נסביר מושגים ברמה בינונית לפיתוח באמצעות Google Assistant, והוא מבוסס על הפעולה שנוצרה ב-codelab ברמה 1. מומלץ מאוד להשלים את ה-codelab לרמה 1 לפני שמתחילים את ה-codelab הזה.

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

מה תפַתחו

ב-codelab הזה תבנו פעולה מתקדמת לניהול שיחות עם הפונקציות הבאות:

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

לפני שמתחילים לבנות, אפשר לקיים אינטראקציה עם הפעולה הפעילה במכשיר עם Google Assistant על ידי אמירת "Ok Google, talk to Fate and Fortune". נתיב ברירת המחדל דרך הפעולה הזו למשתמש חוזר נראה כך:

מה תלמדו

• איך משתמשים במשבצות כדי לאסוף נתונים מהמשתמש
• איך משתמשים בתנאים כדי להוסיף לוגיקה לסצנה
• איך מוסיפים game loop
• איך מוסיפים נתיב תומך

מה נדרש

הדרישות המוקדמות ל-codelab הזה כוללות את הדברים הבאים:

• דפדפן אינטרנט, כמו Google Chrome
• פרויקט Actions שהושלם ברמה 1 ( Build Actions for Google Assistant using Actions Builder Level 1)

מומלץ מאוד להכיר את JavaScript (ES6) כדי להבין את קוד הביצוע של Codelab הזה, אבל זה לא חובה.

2. המשך בניית ממשק שיחה

ב-Codelab הראשון יצרתם פעולה פשוטה לשיחה עם סצנה אחת, Start.

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

• מעבר לFortune סצנה חדשה כשהמשתמש רוצה לשמוע את העתיד שלו
• שואלים את המשתמש איזו עזרה הוא רוצה לבחור לתהליך שלו
• הצגת ניבוי מותאם אישית על סמך הבחירה של המשתמש

יצירת סצנה Fortune

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

כדי ליצור סצנה חדשה בשם Fortune, פועלים לפי השלבים הבאים:

1. פותחים את פרויקט הפעולות ברמה 1 של ה-codelab.
2. בסרגל הניווט, לוחצים על פיתוח.
3. בקטע סצנות, לוחצים על הסצנה התחלה.
4. לוחצים על כוונת yes (התיבה When yes is matched) כדי לפתוח את האפשרויות.
5. כדי להסיר את ההנחיה, מבטלים את הסימון של שליחת הנחיות.
6. בקטע מעבר, לוחצים על התפריט הנפתח, לוחצים בתיבת הטקסט ומקלידים Fortune.
7. לוחצים על Add (הוספה). הפעולה הזו יוצרת סצנה חדשה בשם Fortune. בנוסף, מתווסף מעבר מסצנת Start לסצנת Fortune כשהמשתמש רוצה לשמוע את העתיד שלו.

הגדרת לוגיקה לשיחה בסצנה Fortune

ב-codelab הזה, מגדירים את סצנת Fortune השאלה למשתמש: What do you choose to help you on your quest, a dragon, a translator, or a compass?‎ (מה תבחר שיעזור לך במסע שלך, דרקון, מתרגם או מצפן?) כדי לאסוף את המידע הנדרש מהמשתמש לפני שממשיכים, אפשר להשתמש בתכונה שנקראת מילוי משבצות.

מונחי מפתח:

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

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

מונחי מפתח:

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

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

יצירת סוג available_options

בקטע הזה יוצרים סוג חדש בשם available_options, שמציין את שלוש האפשרויות שהמשתמשים יכולים לבחור (dragon, translator ו-compass) בתגובה להנחיה. אתם גם מגדירים כמה מילים נרדפות לאפשרויות האלה, למקרה שמשתמש יגיד משהו דומה. בקטע מאוחר יותר, מוסיפים את הסוג available_options למקום שמור כדי לציין שרוצים לקבל את הבחירה של המשתמש.

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

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

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

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

1. גוללים לקטע הוספת רשומות.
2. בשדה New entry, מקלידים dragon ולוחצים על Enter. הפעולה הזו יוצרת מפתח dragon.
3. מקלידים hydra בשדה הוספת ערכים ולוחצים על Enter כדי להוסיף אותו כערך (מילה נרדפת). לאחר מכן, חוזרים על השלב הזה עבור הערך lizard.
4. מוסיפים את שאר המפתחות והערכים התואמים:

• translator | translator,‏ communicator,‏ machine,‏ decoder,‏ translate
• compass | compass,‏ direction,‏ guide

5. לוחצים על שמירה.

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

הגדרת מילוי משבצות

בשלב הבא, צריך להגדיר מילוי משבצות בסצנה Fortune. כדי להגדיר את הלוגיקה של מילוי המשבצות:

1. בסרגל הניווט, בקטע סצנות, לוחצים על מזל.
2. בסצנה Fortune, לוחצים על + (סימן הפלוס) לצד מילוי משבצת.
3. בשדה Enter slot name (הזנת שם משבצת), מוסיפים את chosenOptions כשם המשבצת.
4. ברשימה הנפתחת בחירת סוג בוחרים באפשרות available_options כסוג המיקום.
5. מסמנים את תיבת הסימון חובה למלא את המשבצת הזו.

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

candidates:
  - first_simple:
      variants:
        - speech: >-
            What do you choose to help you on your quest, a dragon, a
            translator, or a compass?
    suggestions:
      - title: 'Dragon'
      - title: 'Translator'
      - title: 'Compass'

7. לוחצים על שמירה.

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

שימו לב: כשנתתם שם למשבצת chosenOptions, השם הזה ($session.params.chosenOptions) התעדכן גם בשדה Customize slot value writeback. תוכלו לגשת לפרמטר הזה באמצעות השם הזה ב-Actions Builder וב-fulfillment דרך ספריית הלקוח.

הגדרת תנאי scene.slots.status == "FINAL"

כשמוסיפים משבצת, התנאי scene.slots.status == "FINAL" מתווסף אוטומטית לרשימת התנאים.

מונחי מפתח:

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

התנאי scene.slots.status == "FINAL" בודק אם מילוי המשבצת הושלם. כשכל המשבצות מלאות, התנאי יכול להפעיל webhook, לעבור לסצנה חדשה או להוסיף הנחיות לתור ההנחיות.

בקטע הזה מגדירים את scene.slots.status == "FINAL" כך שיוסיף הנחיה לתור ההנחיות אחרי שהמשבצות יתמלאו.

כדי להוסיף את ההנחיה הזו לתנאי FINAL, פועלים לפי השלבים הבאים:

1. לוחצים על scene.slots.status == "FINAL" כדי לפתוח את חלון האפשרויות.
2. בוחרים באפשרות שליחת הנחיות ומוסיפים את ההנחיה הבאה:

candidates:
  - first_simple:
      variants:
        - speech: You picked $session.params.chosenOptions.

3. לוחצים על שמירה.

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

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

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

1. בסרגל הניווט, לוחצים על בדיקה.
2. לוחצים על Talk to my test app או מקלידים אותו בשדה Input (קלט) ומקישים על Enter.
3. מקלידים Yes בשדה Input ומקישים על Enter. (אפשרות אחרת היא ללחוץ על הצ'יפ עם ההצעה כן).

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

4. לוחצים, מקלידים או אומרים dragon. אמורה להופיע ההנחיה "בחרת דרקון".

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

התאמה אישית של הנחיות באמצעות תנאים

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

התאמה אישית של הניחוש dragon

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

1. בסרגל הניווט, לוחצים על פיתוח.
2. בסרגל הניווט, לוחצים על הסצנה Fortune.
3. לוחצים על scene.slots.status == "FINAL" כדי לפתוח את חלון האפשרויות.
4. מעדכנים את משפט התנאי ל: scene.slots.status == "FINAL" && session.params.chosenOptions == "dragon"
5. בוחרים באפשרות שליחת הנחיות.
6. מעדכנים את ההנחיה עם הניחוש הבא בעורך הקוד:

candidates:
  - first_simple:
      variants:
        - speech: >-
            The people of Gryffinberg will be awestruck by the beauty and power
            of the ancient dragon. Much to your dismay, the townspeople fall
            into dispute over who will receive the honor of riding the dragon
            first. You return home from your quest without everlasting glory or
            a dragon.

7. לוחצים על שמירה.

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

התאמה אישית של הניחוש translator

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

1. לוחצים על + (סמל הפלוס) לצד תנאי.
2. מוסיפים את scene.slots.status == "FINAL" && session.params.chosenOptions == "translator" לשדה else if.
3. לוחצים על שליחת הנחיות.
4. מוסיפים את ההנחיה הבאה בעורך הקוד:

candidates:
  - first_simple:
      variants:
        - speech: >-
            With the help of the translator, the rival factions in Gryffinberg
            are finally able to communicate with each other and resolve their
            disputes. You will complete your quest to restore peace in the town.
            The translator will be used on many subsequent journeys across the
            earth. After its work is done, it retires honorably to a premier
            location in the Gryffinberg History Museum.

4. לוחצים על שמירה.

התאמה אישית של הניחוש compass

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

1. לוחצים על + (סמל הפלוס) לצד תנאי.
2. מוסיפים את scene.slots.status == "FINAL" && session.params.chosenOptions == "compass" לתיבת הטקסט else if.
3. לוחצים על שליחת הנחיות.
4. מוסיפים את ההנחיה הבאה בעורך הקוד:

candidates:
  - first_simple:
      variants:
        - speech: >-
            The compass will help you find the mystical and ancient Library of
            Gryffinberg. Among its infinite stacks of dusty books, you find one
            entitled "Wisdom of the Ages". By the time you've read the
            50,000-page tome, the townspeople have forgotten their problems. You
            will write a second edition of "Wisdom of the Ages", but have
            limited commercial success.

5. לוחצים על שמירה.

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

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

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

1. בסרגל הניווט, לוחצים על בדיקה.
2. מקלידים Talk to my test app בשדה Input ומקישים על Enter.
3. מקלידים Yes בשדה Input ומקישים על Enter. אפשר גם ללחוץ על הצ'יפ של ההצעה כן.
4. לוחצים, מקלידים או אומרים Translator.

אמורה להתקבל התוצאה המתאימה לאפשרות 'מתרגם'.

3. הוספת game loop

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

יצירת סצנה Again

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

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

1. בסרגל הניווט, לוחצים על פיתוח.
2. לוחצים על + (סימן הפלוס) בקטע סצנות.
3. מקלידים Again ומקישים על Enter.
4. בסרגל הניווט, לוחצים על הסצנה Again.
5. לוחצים על + (סמל הפלוס) לצד On enter (בכניסה).
6. בוחרים באפשרות שליחת הנחיות ומוסיפים את ההנחיה הבאה ואת הצ'יפים של ההצעות:

candidates:
  - first_simple:
      variants:
        - speech: >-
            That is what I see for you. Would you like to choose a different option and
            explore another future?
    suggestions:
      - title: 'Yes'
      - title: 'No'

7. לוחצים על שמירה.

הוספת מעבר מסצנה Fortune לסצנה Again

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

כדי להוסיף מעבר מסצנה Fortune לסצנה Again, פועלים לפי השלבים הבאים:

1. לוחצים על הסצנה מזל.
2. לוחצים על התנאי הראשון (scene.slots.status == "FINAL" && session.params.chosenOptions == "dragon") כדי לפתוח את חלון האפשרויות.
3. גוללים ובוחרים באפשרות Again בקטע מעבר.
4. לוחצים על שמירה.
5. לוחצים על התנאי השני כדי לפתוח את חלון האפשרויות.
6. גוללים ובוחרים באפשרות Again בקטע מעבר.
7. לוחצים על שמירה.
8. לוחצים על התנאי השלישי כדי לפתוח את חלון האפשרויות.
9. גוללים ובוחרים באפשרות Again בקטע מעבר.
10. לוחצים על שמירה.

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

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

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

1. בסרגל הניווט, לוחצים על בדיקה.
2. מקלידים Talk to my test app בשדה Input ומקישים על Enter.
3. מקלידים Yes בשדה Input ומקישים על Enter. אפשר גם ללחוץ על הצ'יפ של ההצעה כן.
4. לוחצים, מקלידים או אומרים dragon.

אחרי שתבחרו באפשרות של הדרקון, תקבלו את הניחוש ואת ההנחיה Again.

הוספת כוונות ומעבר לסצנה Again

בקטע הזה, מוסיפים כוונות (intent) של yes ושל no לסצנה Again כדי שהפעולה תבין אם המשתמש רוצה לבחור אפשרות חדשה או לא. מוסיפים גם את המעברים המתאימים לכוונות yes ו-no. הכוונה yes עוברת לסצנה Fortune, והכוונה no עוברת לסצנת המערכת End conversation.

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

1. בסרגל הניווט, לוחצים על פיתוח.
2. לוחצים על הסצנה Again.
3. לוחצים על + (סמל הפלוס) לצד User intent handling (טיפול בכוונת המשתמש).
4. בתפריט הנפתח של הכוונה, בוחרים באפשרות כן.
5. בתפריט הנפתח מעבר, בוחרים באפשרות Fortune.
6. לוחצים על שמירה.

7. לוחצים על + (סמל הפלוס) לצד User intent handling (טיפול בכוונת המשתמש).
8. בתפריט הנפתח של הכוונה, בוחרים באפשרות לא.
9. בתפריט הנפתח מעבר, בוחרים באפשרות סיום השיחה.
10. בוחרים באפשרות שליחת הנחיות ומוסיפים את ההנחיה הבאה בעורך הקוד:

candidates:
  - first_simple:
      variants:
        - speech: >-
            It pleases me that you are satisfied with your choice. Best of luck on your quest. Farewell.

11. לוחצים על שמירה.

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

הפעולה שלכם אמורה להבין עכשיו אם המשתמש רוצה לבחור אפשרות חדשה או לסיים את השיחה.

כדי לבדוק את כוונת המשתמש yes, פועלים לפי השלבים הבאים:

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

צריכה להופיע ההנחיה "What do you choose to help you on your quest, a dragon, a translator, or a compass?" (מה תבחר שיעזור לך במסע שלך, דרקון, מתרגם או מצפן?)

כדי לבדוק את כוונת המשתמש no, פועלים לפי השלבים הבאים:

1. לוחצים על אחת מהאפשרויות, מקלידים אותה או אומרים אותה.
2. מקלידים No בשדה הקלט ומקישים על Enter.

צריכה להופיע ההודעה End conversation: "שמחתי לשמוע שאתה מרוצה מהבחירה שלך. בהצלחה בקווסט. להתראות".

4. הוספת נתיב תומך

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

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

מונחי מפתח:

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

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

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

יצירת סוג unavailable_options

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

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

1. בסרגל הניווט, לוחצים על פיתוח.
2. לוחצים על + (סמל הפלוס) בקטע סוגים.
3. מקלידים unavailable_options ומקישים על Enter.
4. לוחצים על unavailable_options כדי לפתוח את האפשרויות.
5. בקטע Add entries (הוספת רשומות), מזינים את הרשומות הבאות ואת הערכים התואמים:

horse	horse,‏ stallion,‏ steed
magic	magic,‏ enchanted,‏ spells
money	money,‏ cash,‏ gold
phone	phone,‏ cell,‏ apps

טבלת זוגות מפתח/ערך צריכה להיראות כך:

6. לוחצים על שמירה.

יצירת כוונת other_option

לאחר מכן יוצרים כוונת משתמש בשם other_option ומוסיפים ביטויי אימון שכוללים את האפשרויות בסוג unavailable_options. הכוונה הזו מתאימה כשמשתמש בוחר אפשרות שכלולה בסוג unavailable_options.

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

1. לוחצים על + (סמל הפלוס) בקטע קהלים בהתאמה אישית עם כוונת רכישה.
2. מקלידים other_option ומקישים על Enter.
3. לוחצים על other_option כדי לפתוח את החלון.
4. מוסיפים את הביטויים הבאים להדרכה ולוחצים על Enter אחרי כל אחד מהם:

• I want to use spells
• I really really want to use a phone
• magic!
• cash
• I want to ride a horse

5. בקטע Add intent parameters (הוספת פרמטרים של כוונת המשתמש), מעדכנים את שם הפרמטר ל-chosenUnavailableOption.
6. לוחצים על שמירה.

כשמזינים את הביטויים לאימון, הכלי Actions Builder מזהה את spells,‏ phone,‏ magic,‏ cash ו-horse מהסוג unavailable_options ומדגיש (מסמן) את המילים האלה באופן אוטומטי. כלי בניית הפעולות מוסיף באופן אוטומטי פרמטר של Intent בקטע Add intent parameters (הוספת פרמטרים של Intent), כמו שמוצג בתמונה הבאה.

אם הסוגים לא מסומנים אוטומטית, מסמנים את המילים שרוצים להוסיף להן הערות (spells,‏ phone,‏ magic,‏ cash ו-horse)) ובוחרים את הפרמטר chosenUnavailableOption. בקטע סוג הנתונים, בוחרים באפשרות unavailable_options.

פרמטר הכוונה מאפשר לכם לחלץ את שם האפשרות ולהשתמש באפשרות הזו בהנחיה.

הוספת כוונה other_option לסצנה Fortune

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

כדי להוסיף את כוונת המשתמש other_option לסצנה Fortune, פועלים לפי השלבים הבאים:

1. לוחצים על הסצנה מזל.
2. לוחצים על + (סמל הפלוס) לצד User intent handling (טיפול בכוונת המשתמש).
3. בתפריט הנפתח של הכוונה, בוחרים באפשרות other_option.
4. בוחרים באפשרות שליחת הנחיות ומוסיפים את ההנחיה הבאה:

candidates:
  - first_simple:
      variants:
        - speech: >-
            I have seen the future and a $intent.params.chosenUnavailableOption.original
            will not aid you on your journey. 

הביטוי $intent.params.chosenUnavailableOption מתייחס לאובייקט של פרמטר ה-Intent, והביטוי $intent.params.chosenUnavailableOption.original מתייחס לערך של האובייקט הזה. השדה original property מתייחס לקלט הגולמי שהמשתמש מציין.

5. לוחצים על שמירה.

כשמשתמש אומר אפשרות שמופיעה ברשימה של unavailable_options type במהלך Fortune scene, המערכת מתאימה את הכוונה other_option ומוסיפה הנחיה לתור ההנחיות. מכיוון שלא צוין מעבר, לולאת הביצוע של הסצנה ממשיכה בהערכה מחדש של שלב התנאים. לאחר מכן, המשבצת chosenOptions מוסיפה את ההנחיה שלה לתור ההנחיות, והתור מועבר למשתמש.

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

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

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

1. בסרגל הניווט, לוחצים על בדיקה.
2. מקלידים Talk to my test app בשדה Input ומקישים על Enter.
3. מקלידים Yes בשדה Input ומקישים על Enter. אפשר גם ללחוץ על הצ'יפ של ההצעה כן.
4. מקלידים magic בשדה Input ומקישים על Enter.

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

הוספת handler של unavailable_options

כדי להוסיף את המילה a לפני האפשרויות המתאימות מהסוג unavailable_options, אפשר להגדיר את הפונקציה event handler בלוגיקת האספקה כדי לבדוק אם צריך להוסיף את המילה a לפני האפשרות שהמשתמש בוחר. קודם צריך להגדיר את הפעולה כך שתפעיל את ה-handler במסוף.

כדי להוסיף את רכיב ה-handler‏ unavailable_options, פועלים לפי השלבים הבאים:

1. בסרגל הניווט, לוחצים על פיתוח.
2. לוחצים על הסצנה Fortune.
3. בקטע User intent handling, לוחצים על When other_option is matched כדי לפתוח את החלון.
4. מבטלים את הסימון של התיבה שליחת הנחיות.
5. מסמנים את תיבת הסימון התקשרות אל ה-webhook.
6. מזינים unavailable_options בתיבת הטקסט של הגורם המטפל באירועים.

7. לוחצים על שמירה.

עדכון ופריסה של תהליך מילוי ההזמנה

עכשיו, אחרי שהגדרתם את הפעולה לקריאה ל-handler של האירוע unavailable_options, אתם יכולים לעדכן את ה-handler ב-fulfillment ולפרוס אותו.

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

1. בסרגל הניווט, לוחצים על Webhook.
2. מוסיפים את הקוד הבא מתחת ל-handler‏ greeting:

app.handle('unavailable_options', conv => {
  const option = conv.intent.params.chosenUnavailableOption.original;
  const optionKey = conv.intent.params.chosenUnavailableOption.resolved;
  let message = 'I have seen the future and ';
  if(optionsNeedA.has(optionKey)){
    message = message + 'a ';
  }
  message = message + `${option} will not aid you on your journey. `;
  conv.add(message);
});

3. מוסיפים את הקוד הבא מתחת ל-const app = conversation();:

const optionsNeedA = new Set();
optionsNeedA.add('horse').add('phone');

4. לוחצים על שמירת ההזמנה.
5. לוחצים על Deploy Fulfillment (פריסת מילוי הזמנות). בסיום הפריסה, תוצג הודעה מעל העורך: Your Cloud Function deployment is up to date (הפריסה של הפונקציה ב-Cloud Functions עדכנית).

הסבר על הקוד

ה-handler‏ unavailable_options מבצע את הפעולות הבאות:

• מקבל נתוני option מאובייקט conv ומקצה את option למאפיין original, שהוא הקלט הגולמי מהמשתמש
• הפונקציה מקצה את הערך optionKey למאפיין resolved, שהוא המפתח לסוג unavailable_options
• בודק אם optionKey היא אחת מהאפשרויות שצריך להוסיף להן את האות a. אם כן, יוצר את ההודעה עם האות a.
• הוספת ההודעה דרך conv.add(message)

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

הפעולה אמורה להתאים את ההנחיה בהתאם לבחירה של המשתמש מתוך סוג unavailable_options, ולבדוק אם צריך להוסיף את המילה "a" לפני הבחירה.

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

1. בסרגל הניווט, לוחצים על בדיקה.
2. לוחצים על Talk to my test app או מקלידים אותו בשדה Input (קלט) ומקישים על Enter.
3. מקלידים Yes בשדה Input ומקישים על Enter. אפשר גם ללחוץ על הצ'יפ של ההצעה כן.
4. מקלידים magic בשדה Input ומקישים על Enter.
5. מקלידים horse בשדה Input ומקישים על Enter.

הפעולה שלכם צריכה להוסיף את המילה 'a' לפני האפשרות 'horse', וליצור את ההנחיה בלי המילה 'a' לפני האפשרות 'magic'.

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

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

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

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

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

5. מעולה!

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

מה כיסיתם

• איך מפתחים פעולות לשיחה באמצעות ספריית ה-fulfillment של Node.js
• איך משתמשים במשבצות כדי לאסוף נתונים מהמשתמש
• איך משתמשים בתנאים כדי להוסיף לוגיקה לסצנה
• איך מוסיפים game loop
• איך מוסיפים נתיב תומך

מידע נוסף

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

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

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

סקר משוב

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