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

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

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

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

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

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

מה תפַתחו

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

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

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

מה תלמדו

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

למה תזדקק?

הדרישות המוקדמות ל-Codelab הזה כוללות:

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

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

אופציונלי: מקבלים את הקוד לדוגמה

אפשר גם לקבל את קוד הפרויקט המלא ברמה 1 ממאגר GitHub של Actions Builder Codelab ברמה 1, כדי להמשיך להשתמש ב-Codelab הזה. תוכלו גם לראות את הקוד המלא של הפרויקט ברמה 2 במאגר הזה של GitHub.

2. המשך פיתוח ממשק שיחה

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

ב-Codelab הזה, אפשר להרחיב את השיחה של הפעולה. בקטעים הבאים, הגדרתם לפעולה את הפעולות הבאות:

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

מעבר לסצנה אחת בFortune ויצירת סצנה אחת

בקטע הזה מבצעים את הפעולות הבאות:

• הסרת ההנחיה הקיימת מהסצנה Start, שמגיבה למשתמש ומסיימת את השיחה
• הגדרת המעבר מהסצנה Start לסצנה Fortune
• יצירת הסצנה Fortune

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

1. פותחים את פרויקט Actions מ-codelab ברמה 1 בכלי לעריכת טקסט.
2. פותחים את הקובץ custom/scenes/Start.yaml.
3. צריך לעדכן את handler עבור ה-Intent yes כדי שהקוד יתאים לקטע הקוד הבא:

Start.yaml

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

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

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

1. עוברים לפרויקט Actions (פעולות) ברמה 1 של Codelab בטרמינל.
2. יוצרים קובץ חדש בשם Fortune.yaml בספרייה scenes:

touch custom/scenes/Fortune.yaml

בקטע הבא תערכו את הקובץ.

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

ב-Codelab הזה, מגדירים את הסצנה של Fortune כך שתשאל את המשתמש: "What do you choose to help you in the Quest, a Dragon, a מתרגם או במצפן?" אפשר להשתמש ביכולת שנקראת מילוי של יחידות קיבולת (Slot) כדי לאסוף את המידע הנדרש מהמשתמש לפני שממשיכים.

מונחי מפתח:

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

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

מונח מפתח:

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

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

יצירה של סוג available_options

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

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

1. יוצרים ספרייה חדשה בשם types:

mkdir custom/types

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

touch custom/types/available_options.yaml

3. פותחים את custom/types/available_options.yaml בכלי לעריכת טקסט.

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

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

1. מוסיפים את ה-entities וה-synonyms הבאים לקובץ available_options.yaml:

available_options.yaml

synonym:
  entities:
    dragon:
      synonyms:
      - dragon
      - hydra
      - lizard
    translator:
      synonyms:
      - translator
      - communicator
      - machine
      - decoder
      - translate
    compass:
      synonyms:
      - compass
      - direction
      - guide
      - navigator
  matchType: EXACT_MATCH

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

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

הגדרת מילוי של יחידות קיבולת (Slot)

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

1. פותחים את custom/scenes/Fortune.yaml בכלי לעריכת טקסט.
2. מוסיפים את נתוני slots הבאים לקובץ Fortune.yaml:

Fortune.yaml

slots:
- commitBehavior:
    writeSessionParam: chosenOptions
  name: chosenOptions
  promptSettings:
    initialPrompt:
      staticPrompt:
        candidates:
        - promptResponse:
            firstSimple:
              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
  required: true
  type:
    name: available_options

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

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

כשתגדירו שם למשבצת chosenOptions, השדה writeSessionsParam יתעדכן באותו השם ($session.params.chosenOptions). תוכלו לגשת לפרמטר הזה לפי השם שמופיע בהנחיה ובמילוי הבקשה דרך ספריית הלקוח.

כאן אפשר להוסיף תנאי

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

מונחי מפתח:

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

בקטע הזה מוסיפים את התנאי scene.slots.status == "FINAL", שבודק אם יש להשלים את מילוי המשבצות. אחרי שכל המשבצות יתמלאו, התנאי יוסיף הנחיה (You picked $session.params.chosenOptions.) לתור ההנחיות.

כדי להגדיר את התנאי scene.slots.status == "FINAL", פועלים לפי השלבים הבאים:

1. פותחים את custom/scenes/Fortune.yaml בכלי לעריכת טקסט.
2. צריך להוסיף את הנתונים של conditionalEvents בחלק העליון של הקובץ Fortune.yaml:

Fortune.yaml

conditionalEvents:
- condition: scene.slots.status == "FINAL"
  handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: You picked $session.params.chosenOptions.

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

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

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

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

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. לוחצים או מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
4. מקלידים Yes בשדה קלט ומקישים על Enter. לחלופין, אפשר ללחוץ על צ'יפ ההצעה כן.

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

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

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

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

התאמה אישית של המזל בdragon

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

1. פותחים את custom/scenes/Fortune.yaml בכלי לעריכת טקסט.
2. מחליפים את הנתונים conditionalEvents בקטע הקוד הבא בקובץ Fortune.yaml:

Fortune.yaml

conditionalEvents:
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "dragon"
  handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            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.

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

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

התאמה אישית של translator וcompass

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

1. בקובץ custom/scenes/Fortune.yaml, מוסיפים את שני התנאים האחרים במסגרת התנאי dragon:

Fortune.yaml

- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "translator"
  handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            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 other journeys across the
                earth. After its work is done, it retires honorably to a premier location
                in the Gryffinberg History Museum.
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "compass"
  handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            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.

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

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

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

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

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. מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
4. מקלידים 'כן' בשדה קלט ומקישים על Enter. לחלופין, לוחצים על צ'יפ ההצעה כן.
5. לוחצים, מקלידים או אומרים Translator.

אתה אמור לקבל את המזל המתאים ל"המתרגם" כאפשרות.

3. הוספה של לולאת משחק

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

יצירת סצנה אחת (Again)

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

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

1. יוצרים קובץ חדש בשם Again.yaml בספרייה scenes:

touch custom/scenes/Again.yaml

2. פותחים את custom/scenes/Again.yaml בכלי לעריכת טקסט.
3. צריך להוסיף את נתוני onEnter הבאים אל Again.yaml:

Again.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          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"

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

הוספת מעבר מFortune לסצנה אחת (Again)

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

כדי להוסיף מעבר מהסצנה Fortune לסצנה Again:

1. פותחים את custom/scenes/Fortune.yaml בכלי לעריכת טקסט.
2. מוסיפים transitionToScene: Again לכל תנאי, כפי שמוצג בקטע הקוד הבא:

Fortune.yaml

conditionalEvents:
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "dragon"
  handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            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.
  transitionToScene: Again
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "translator"
  handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            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 other journeys across the
                earth. After its work is done, it retires honorably to a premier location
                in the Gryffinberg History Museum.
  transitionToScene: Again
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "compass"
  handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            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.
  transitionToScene: Again

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

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

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

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

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. מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
4. מקלידים Yes בשדה קלט ומקישים על Enter. אפשר גם ללחוץ על צ'יפ ההצעה כן.
5. לוחצים, מקלידים או אומרים dragon.

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

הוספת כוונות ומעבר לסצנה אחת (Again)

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

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

1. פותחים את custom/scenes/Again.yaml בכלי לעריכת טקסט.
2. צריך להוסיף נתונים של intentEvents בחלק העליון של קובץ Again.yaml, מעל OnEnter:

Again.yaml

intentEvents:
- intent: "yes"
  transitionToScene: Fortune
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: It pleases me that you are satisfied with your choice. Best
                of luck on your quest. Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

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

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

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

כדי לבדוק את הכוונה של 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. מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
4. מקלידים Yes בשדה קלט ומקישים על Enter. לחלופין, לוחצים על צ'יפ ההצעה כן.
5. לוחצים על האפשרויות, מקלידים או אומרים אותה.
6. מקלידים Yes בשדה הקלט ומקישים על Enter.

אמורה להופיע השאלה "What do you choose to help you in your Quest, a דרקון, a מתרגם או מצפן?"

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

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

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

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

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

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

מונחי מפתח:

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

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

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

יצירה של סוג unavailable_options

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

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

1. יוצרים קובץ חדש בשם unavailable_options.yaml בספרייה types:

touch custom/types/unavailable_options.yaml

2. פותחים את custom/types/unavailable_options.yaml בכלי לעריכת טקסט.
3. מוסיפים את נתוני synonyms הבאים לקובץ unavailable_options.yaml:

unavailable_options.yaml

synonym:
  entities:
    money:
      synonyms:
      - money
      - cash
      - gold
    horse:
      synonyms:
      - horse
      - stallion
      - steed
    magic:
      synonyms:
      - magic
      - enchanted
      - spells
    phone:
      synonyms:
      - phone
      - cell
      - apps
  matchType: EXACT_MATCH

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

יצירת Intent מסוג other_option

בשלב הבא יוצרים אובייקט Intent בשם other_option ומוסיפים ביטויי אימון שכוללים את האפשרויות מסוג unavailable_options. המערכת מתאימה ל-Intent הזה כשהמשתמש בוחר בחירה מתוך הסוג unavailable_options.

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

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

touch custom/intents/other_option.yaml

2. פותחים את custom/intents/other_option.yaml בכלי לעריכת טקסט.
3. מוסיפים את נתוני parameters ואת הנתונים הבאים של trainingPhrases לקובץ other_option.yaml:

other_option.yaml

parameters:
- name: chosenUnavailableOption
  type:
    name: unavailable_options
trainingPhrases:
- I want to use ($chosenUnavailableOption 'spells' auto=true)
- I really really want to use a ($chosenUnavailableOption 'phone' auto=true)
- ($chosenUnavailableOption 'magic' auto=true)!
- ($chosenUnavailableOption 'cash' auto=true)
- I want to ride a ($chosenUnavailableOption 'horse' auto=true)

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

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

הוספת Intent מסוג other_option לסצנה אחת (Fortune)

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

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

1. פותחים את custom/scenes/Fortune.yaml בכלי לעריכת טקסט.
2. צריך להוסיף את נתוני intentEvents הבאים בין הנתונים של conditionalEvents לבין הנתונים של slots:

Fortune.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech:  I have seen the future and a $intent.params.chosenUnavailableOption.original will not aid you on your journey.
  intent: other_option

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

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

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

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

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

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

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. מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
4. מקלידים Yes בשדה קלט ומקישים על Enter. אפשר גם ללחוץ על צ'יפ ההצעה כן.
5. מקלידים magic בשדה קלט ומקישים על Enter.

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

הוספת handler של unavailable_options

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

כדי להוסיף את ה-handler של unavailable_options לסצנה Fortune:

1. פותחים את custom/scenes/Fortune.yaml בכלי לעריכת טקסט.
2. מעדכנים את הקובץ Fortune.yaml עם נתוני intentEvents הבאים:

Fortune.yaml

intentEvents:
- handler:
    webhookHandler: unavailable_options
  intent: other_option

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

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

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

כדי לעדכן את מילוי ההזמנות:

1. פותחים את webhooks/ActionsOnGoogleFulfillment/index.js בכלי לעריכת טקסט.
2. מוסיפים את הקוד הבא אל index.js ב-handler של greeting:

index.js

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({debug:true});:

index.js

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

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

הסבר על הקוד

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

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

עדכון handlers

כדי לאפשר לפעולה להשתמש ב-unavailable_options, צריך להוסיף את ה-handler של unavailable_options אל webhooks/ActionsOnGoogleFulfillment.yaml.

1. מוסיפים את שם ה-handler של unavailable_options ל-ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
- name: unavailable_options
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

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

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

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

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

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. לוחצים או מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
4. מקלידים Yes בשדה קלט ומקישים על Enter. לחלופין, לוחצים על צ'יפ ההצעה כן.
5. מקלידים magic בשדה קלט ומקישים על Enter. לאחר מכן, מקלידים horse בשדה קלט ומקישים על Enter.

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

5. הצגת פעולה במסוף Actions

ל-Actions SDK יש יכולת פעולה הדדית עם סביבת פיתוח משולבת (IDE) מבוססת-אינטרנט שנקראת Actions Builder (פעולות) שמשולבת במסוף Actions. אפשר להעביר את מערכת הקבצים המקומית לטיוטה של הפעולה במסוף באמצעות הפקודה 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 הזה, מבצעים את השלבים הבאים:

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

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

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

6. מעולה!

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

מה נכלל בקורס

• איך לפתח פעולות בממשק שיחה באמצעות ספריית מילוי ההזמנות של Node.js
• איך להשתמש ביחידת קיבולת (Slot) כדי לאסוף נתונים מהמשתמש
• איך משתמשים בתנאים כדי להוסיף לוגיקה לסצנה
• איך מוסיפים לולאת משחק
• איך להוסיף נתיב תומך

מידע נוסף

אפשר להיעזר במקורות המידע הבאים כדי ללמוד איך ליצור פעולות ל-Google Assistant:

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

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

סקר משוב

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