בניית פרויקטים

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

רכיבי פרויקט פעולות
איור 1. מבנה פרויקט הפעולות

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

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

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

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

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

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

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

  • Interactive Canvas מאפשר ליצור חוויות משתמש עשירות ועשירות באפליקציות אינטרנט שמשתמשות ב-HTML, ב-CSS וב-JavaScript.

יוצרים פרויקט

כדי לפתח פרויקט ב-Google Assistant, צריך ליצור פרויקט במסוף Actions. כדי ליצור פרויקט:

  1. נכנסים אל Actions Console.
  2. לוחצים על פרויקט חדש.
  3. מזינים את שם הפרויקט ולוחצים על Create Project.
  4. במסך איזה סוג של פעולה ברצונך ליצור? בוחרים קטגוריה שמייצגת בצורה הטובה ביותר את הפרויקט ולוחצים על הבא.
  5. במסך How do you want to build it, בוחרים את אופן הבנייה ולוחצים על Start started (התחלת הבנייה). לדוגמה, אפשר להתחיל עם פרויקט ריק או עם דגימה.

יצירת פרויקט מקומי ל-Actions SDK

אחרי שיוצרים פרויקט Actions במסוף Actions, אפשר לאתחל פרויקט בסביבת הפיתוח המקומית.

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

  1. יוצרים ספרייה ריקה לפרויקט Actions במערכת הקבצים המקומית.
  2. בספרייה הריקה הזו, צריך ליצור ספרייה sdk.
  3. צריך לשנות את ספריית העבודה לספרייה sdk בטרמינל.

התחלה עם פרויקט ריק

כדי להתחיל מהפרויקט הריק שיצרתם במסוף, צריך להריץ את gactions pull --project-id <my-project-id>. 

$ mkdir myAction
$ cd myAction
$ mkdir sdk
$ cd sdk
$ gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk

התחלה עם פרויקט לדוגמה

כדי להתחיל מפרויקט לדוגמה, מריצים את הפקודה gactions init <sample name>. 

$ mkdir actions-test
$ cd actions-test
$ mkdir sdk
$ cd sdk
$ gactions init question
Writing sample files for question.
✔ Done. Please checkout the following documentation - https://developers.google.com/assistant/conversational/build on the next steps on how to get started.

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

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

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

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

  1. קביעת הגדרות גלובליות לפרויקט הפעולות שלך ב-sdk/settings/settings.yaml. אפשר להיעזר במסמכי התיעוד בנושא Settings כדי לראות את הערכים הנתמכים.

    קטע הקוד הבא מציג קובץ sdk/settings/settings.yaml לדוגמה: 

    accountLinking:
  enableAccountCreation: true
  linkingType: GOOGLE_SIGN_IN
category: GAMES_AND_TRIVIA
projectId: my-project-id
...

  2. אפשר להגדיר הגדרות שעשויות להשתנות בהתאם ללוקאל של המשתמש (לדוגמה, ביטויי הפעלה בשפות שונות) בקובץ sdk/settings/<locale>/settings.yaml, ומחליפים את הלוקאל בלוקאל היעד.

    הערכים הנתמכים מופיעים במסמכי התיעוד של LocalizedSettings.

    קטע הקוד הבא הוא דוגמה להגדרות באנגלית שמוגדרות בקובץ sdk/settings/en/settings.yaml:

    localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action
  largeBannerImage: https://path/to/large/banner
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action
  smallLogoImage: https://path/to/small/logo
  voice: female_1
...

הוספת משאבים

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

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

כדי לבצע לוקליזציה של משאבים, אפשר ליצור תיקיות ספציפיות ללוקאל בתיקייה סוג המשאב. לדוגמה, אפשר לשמור גרסאות בספרדית של המחרוזות ב-resources/strings/es/<filename>.yaml.

תמונות

קובצי התמונות נשמרים ב-resources/images/, ואפשר להפנות אליהם באמצעות $resources.images.<name of the image file without file extension>. סיומות הקובץ המותרות הן:

  • gif
  • png
  • jpg
  • jpeg

לדוגמה, אם הגרסה באנגלית של הלוגו הקטן נשמרת ב-resources/images/en/square.png והגרסה באנגלית של הבאנר הגדול נשמרת ב-resources/images/en/landscape.jpg בהתאמה, sdk/settings/en/settings.yaml מהדוגמה הקודמת יהפוך לערך:

localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action

  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action

  smallLogoImage: $resources.images.square
  voice: female_1
...

קובצי אודיו

קובצי האודיו מאוחסנים ב-resources/audio/, ואפשר להפנות אליהם באמצעות $resources.audio.<name of the audio file without file extension>.

סיומות הקובץ המותרות הן:

  • mp3
  • mpeg

לדוגמה, אפשר להפנות להקלטות אודיו מהנחיות:

candidates:
  - first_simple:
      variants:
        - speech: your speech response
    content:
      media:
        mediaType: audio
        mediaObjects:
          - name: media name
            description: media description
            url: $resources.audio.intro

מחרוזת

המחרוזות מאוחסנות ב-resources/strings/ כקובצי .yaml. כל קובץ מכיל מפה של מפתחות מחרוזות וערכים משויכים, שיכולים להיות מחרוזות בודדות או רשימות של מחרוזות. אפשר להפנות לערכים באמצעות הפקודה $resources.strings.<name of the image file without file extension>.<key> לערכי מחרוזת יחידה או לקבלת ערך אקראי מרשימה, ו-$resources.strings.<name of the image file without file extension>.<key>.<numerical index> לערך מחרוזת ספציפי בתוך רשימה.

לדוגמה, שימוש במחרוזות משאבים כדי לבצע לוקליזציה של מחרוזות, הערך sdk/settings/en/settings.yaml מהדוגמה הקודמת יכול להפוך ל:

localizedSettings:
  developerEmail: developer@developers.com
  developerName: $resources.strings.appinfo.developerName
  displayName: $resources.strings.appinfo.displayName
  fullDescription: $resources.strings.appinfo.fullDescription
  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: $resources.strings.appinfo.privacyPolicyUrl
  sampleInvocations:
  - $resources.strings.invocations.sample
  shortDescription: $resources.strings.appinfo.shortDescription
  smallLogoImage: $resources.images.square
  voice: female_1
...

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

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

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

כדי לבדוק פרויקט:

  1. מריצים את gactions deploy preview כדי לפרוס את Action (תצוגה מקדימה) ולהפעיל את הבדיקה בסימולטור.
  2. פותחים את כתובת ה-URL בפלט הפקודה כדי לגשת לסימולטור.
$ gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview