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

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

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

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

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

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

מה תפַתחו

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

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

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

מה תלמדו

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

הדרישות

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

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

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

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

אם רוצים, אפשר לקבל את קוד הפרויקט המלא ברמה 1 ממאגר GitHub של Codelab Level 1 Actions Builder, כדי לעקוב אחרי ה-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 עבור כוונת 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. עוברים לפרויקט Level 1 Actions של codelab במסוף.
2. יוצרים קובץ חדש בשם Fortune.yaml בספרייה scenes:

touch custom/scenes/Fortune.yaml

בקטע הבא נסביר איך לערוך את הקובץ הזה.

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

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

מונחי מפתח:

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

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

מונח מפתח:

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

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

יצירת סוג available_options

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

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

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

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

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

בקטע הזה מוסיפים כוונות (intents) של yes ושל no לסצנה Again כדי שהפעולה תבין אם המשתמש רוצה לבחור אפשרות חדשה או לא. מוסיפים גם את המעברים המתאימים לכוונות yes ו-no. הכוונה yes עוברת לסצנה Fortune, והכוונה 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.

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

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

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

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

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

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

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

מונחי מפתח:

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

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

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

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

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

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

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

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

touch custom/intents/other_option.yaml

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

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)

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

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

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

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

כדי להוסיף את כוונת המשתמש 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 type במהלך Fortune scene, המערכת מתאימה את other_option intent ומוסיפה הנחיה לתור ההנחיות. מכיוון שלא צוין מעבר בין סצנות, לולאת ההרצה של הסצנה ממשיכה בהערכה מחדש של שלב התנאים. לאחר מכן, המשבצת 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, אפשר להגדיר גורם מטפל באירועים בלוגיסטיקה של אספקת ההזמנה כדי לבדוק אם צריך להוסיף את המילה 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. שומרים את הקובץ.

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

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

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

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)

עדכון של רכיבי handler

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

5. הדמיה של פעולה בקונסולה ל-Actions

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

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

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

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

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

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

6. מעולה!

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

מה כיסיתם

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

מידע נוסף

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

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

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

סקר משוב

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