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

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

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

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

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

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

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

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

  • הנחיות מגדירות תשובות סטטיות או דינמיות שבהן משתמשים כדי להשיב למשתמשים.

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

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

יצירת פרויקט

עליכם ליצור פרויקט במסוף Actions לפני שתוכלו לפתח עבור Google Assistant כדי ליצור פרויקט:

  1. נכנסים אל מסוף הפעולות.
  2. לוחצים על פרויקט חדש.
  3. נותנים שם לפרויקט ולוחצים על Create Project.
  4. במסך איזה סוג של פעולה ברצונך ליצור?, בוחרים באפשרות לבחור קטגוריה שמייצגת את הפרויקט בצורה הטובה ביותר. לאחר מכן לוחצים על הבא.
  5. במסך איך ברצונך לבנות אותו, בוחרים את שיטת הבנייה ולוחצים על התחלת הבנייה. לדוגמה, אפשר להתחיל עם או באמצעות דגימה.

יצירת פרויקט SDK של פעולות מקומיות

אחרי שיוצרים פרויקט 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.

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

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

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

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

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

    בקטע הקוד הבא מוצג קובץ 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
...

הוספת משאבים

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

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

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

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

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

  1. מריצים את הפקודה gactions deploy preview כדי לפרוס את הפעולה בתצוגה מקדימה ולהפעיל את הבדיקה בסימולטור.
  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