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

דף זה תורגם על ידי Cloud Translation API.

יצירת מילוי הזמנות באמצעות ספריית הלקוח של Actions on Google Node.js (Dialogflow)

ספריית הלקוח Actions on Google Node.js היא הדרך המומלצת לגישה ול אינטראקציה עם פלטפורמת Actions on Google אם אתם יוצרים תגובה לפעולה מאתר אחר (webhook) ב-JavaScript.

מבוא

ספריית הלקוח של Node.js היא ספרייה למילוי הזמנות של פעולות ב-Google שמספקות את התכונות הבאות:

תמיכה בכל התכונות של Actions on Google, כולל טקסט ותשובות עשירות במולטימדיה, כניסה לחשבון, אחסון נתונים, עסקאות ועוד.
ההגדרה הזו מספקת שכבה אידיומטית של הפשטה ב-JavaScript שעטופה ה-API של התגובה לפעולה מאתר אחר (webhook) ב-HTTP/JSON.
טיפול בפרטים ברמה נמוכה של התקשורת בין מילוי ההזמנה פלטפורמת Actions on Google.
ניתן להתקין באמצעות כלים מוכרים לניהול חבילות, כמו npm או yarn.
מאפשר לפרוס בקלות את התגובה לפעולה מאתר אחר (webhook) בפלטפורמות מחשוב ללא שרת (serverless computing) כמו Cloud Functions for Firebase או AWS Lambda. אפשר גם לארח את התגובה לפעולה מאתר אחר (webhook) בספק שירותי ענן או בסביבה באירוח עצמי ובניהול עצמי.
תואמת ל-Node.js גרסה 6.0.0 ואילך.

אפשר להשתמש בספריית הלקוח יחד עם שילוב של Dialogflow עם Actions on Google או באמצעות Actions SDK.

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

הצגת הפניית ה-API

הפניית ה-API מתארחת בספריית הלקוח Actions on Google Node.js דף ב-GitHub.

אפשר גם ליצור עותק מקומי של קובץ העזר באמצעות הפקודה הבאה מהפקודה שאליה הורדתם את ספריית הלקוח קוד:

yarn docs

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

איך זה עובד

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

כשיוצרים תגובה לפעולה מאתר אחר (webhook) ב-JavaScript, אפשר לפרוס את הקוד ולארח אותו בסביבת מחשוב ללא שרת (serverless), כמו Cloud Functions for Firebase או AWS Lambda. יש לך אפשרות גם לארח את הקוד בעצמך בלי צורך בפעולות נוספות באמצעות Express web framework.

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

המשימות העיקריות שבהן ה-webhook שלכם מטפל כאן מופיע סיכום קצר של ספריית הלקוח:

**איור 1.** ארכיטקטורה ברמה גבוהה של ספריית הלקוח של Node.js

קבלת בקשות ממשתמשים: כשמשתמש שולח שאילתה ל-Google Assistant, פלטפורמת Actions on Google שולחת בקשת HTTP ל-webhook של מילוי הבקשה. הבקשה השדה הזה כולל מטען ייעודי (payload) של JSON שמכיל את ה-Intent ונתונים נוספים כמו נתוני ה-RAW. של טקסט הקלט של המשתמש, ויכולות השטח של המכשיר של המשתמש. לדוגמאות נוספות של תוכן מטען ייעודי (payload) של JSON, אפשר לעיין הפורמט של Dialogflow webhook וגם פורמט webhook לשיחה במדריכים שלכם.
זיהוי פורמט שיחה של Framework: עבור frameworks נתמכות, ספריית הלקוח מזהה באופן אוטומטי את פורמט הקריאה של ה-framework (לדוגמה, אם הבקשה הגיעה מ-Express Webframework או מ-AWS Lambda) איך לנהל תקשורת חלקה עם פלטפורמת Actions on Google.
עיבוד של handler של שירות: ספריית הלקוח מייצגת שיחה עם HTTP/JSON webhook API ל-Dialogflow ול-Actions SDK בתור פונקציית שירות. ב-webhook webhook הזה משתמשים בשירות המתאים כדי יוצרים מכונה של app באופן גלובלי. המכונה app משמשת כ-handler של HTTP מבקש ומבין את הפרוטוקול הספציפי של השירות.
עיבוד שיחה: ספריית הלקוח מייצגת מידע לכל שיחה כאובייקט Conversation שמצורף מופע app. התגובה לפעולה מאתר אחר (webhook) של מילוי הבקשות יכולה להשתמש באובייקט Conversation כדי לאחזר נתונים מאוחסנים או מידע על מצב בין שיחות, לשלוח תשובות למשתמשים, או לסגור את המיקרופון.
עיבוד תוכנות מדיה (Middleware): ספריית הלקוח מאפשרת ליצור תווכה של שירותי שיחה, שמורכבת מפונקציה אחת או יותר אפשר להגדיר שספריית הלקוח תפעל באופן אוטומטי לפני הקריאה את ה-Intent. התגובה לפעולה מאתר אחר (webhook) של מילוי הבקשות יכולה להשתמש בתווכה שלך כדי להוסיף נכסים או מחלקות מסייעות לאובייקט Conversation.
עיבוד של ה-handler של Intent: ספריית הלקוח מאפשרת להגדיר גורמים המטפלים באובייקטים של Intent שה-webhook של המענה מבינה. ב-Dialogflow, ספריית הלקוח מנתבת את הבקשה ל-handler הנכון של Intent על ידי מיפוי למחרוזת המדויקת של שם ה-Intent שמוגדר מסוף של Dialogflow. ב-Actions SDK, הניתוב מחדש על סמך הנכס intent שנשלח מתוך Actions on Google.
שליחת תשובות למשתמשים: כדי ליצור תשובות, ה-webhook של מילוי הבקשות קוראת לפונקציה Conversation#ask(). הפונקציה ask() יכולה להיות שנקראות מספר פעמים כדי לבנות את התגובה באופן מצטבר. ספריית הלקוח מחזירה את התשובה לבקשת HTTP באמצעות מטען ייעודי (payload) של JSON ושולח אותו אל Actions on Google. לפונקציה close() יש התנהגות דומה לזו של ask(), אבל השיחה נסגרת.

הגדרת סביבת הפיתוח המקומית

לפני שמטמיעים את ה-webhook webhook, צריך להתקין אותו ספריית לקוח.

התקנת ספריית הלקוח

הדרך הקלה ביותר להתקין את ספריית הלקוח בפיתוח המקומי היא להשתמש במנהל חבילות, כמו npm או yarn.

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

אם משתמשים ב-NPM: npm install actions-on-google
אם משתמשים בצמר: yarn add actions-on-google

מגדירים את תיקיות הפרויקט

בהתאם למקום שבו אתם מתכננים לפרוס את ה-webhook (ה-Cloud Functions של Google) עבור Firebase, AWS Lambda או Express באירוח עצמי), יכול להיות שתצטרכו ליצור את המבנה של תיקיות פרויקט ספציפיות כדי לשמור את הקבצים שלכם.

לדוגמה, אם משתמשים ב-Cloud Functions for Firebase, אפשר להגדיר תיקיות הפרויקט הנדרשות על ידי ביצוע השלבים שמתוארים מגדירים את Node.js ואת ה-CLI של Firebase ואז מפעילים את Firebase ל-Cloud Functions. ב-Cloud Functions for Firebase, בדרך כלל צריך לכתוב webhook webhook בקובץ /functions/index.js.

פיתוח מופע של אפליקציה

הפעולות ב-Google מתבססות על פורמטים ספציפיים של הודעות כדי לשלוח בקשות ותשובות באמצעות ה-webhook שלכם, בהתאם למה שאתם יוצרים בממשק שיחה פעולה באמצעות Dialogflow או Actions SDK או ליצור פעולה לבית חכם.

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

פרוטוקול התגובה לפעולה מאתר אחר (webhook) בשיחה משמש גם שירותי שיחה (Dialogflow ו-Actions SDK), אבל כל אחד מהם שירות אוטף הודעות באופן שונה.

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

אפשר להגדיר את המאפיינים של המכונה app ולקרוא ל-methods שלה מנחים את ההתנהגות של תגובה לפעולה מאתר אחר (webhook). אפשר גם לחבר את המכונה של app בקלות. בסביבת מחשוב ללא שרת (serverless computing), כמו Cloud Functions for Firebase, שמקבל פונקציות של JavaScript כרכיבי handler של בקשות HTTP.

כדי ליצור מופע app ב-webhook של מילוי הבקשה, פועלים לפי השלבים הבאים:

צריך להפעיל את הפונקציה require() כדי לייבא את הפונקציה 'actions-on-google' מודול וגם טוענים את השירות הרצוי. לדוגמה, קטע הקוד הבא מראה איך עשוי לטעון את השירות dialogflow וחלק מהרכיבים המשמשים ליצירת תשובות, ומקצים אותו קבוע בשם dialogflow:
```
// Import the service function and various response classes
const {
  dialogflow,
  actionssdk,
  Image,
  Table,
  Carousel,
} = require('actions-on-google');
```
כאן, actions-on-google מתייחס לתלות שמצוינת קובץ package.json בתיקיית הפרויקט (למשל קובץ package.json לדוגמה כדוגמה).

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

הערה: ספריית הלקוח מתעדכנת לעיתים קרובות. אפשר לעיין בעדכניות ביותר נתוני גרסה לכל שינוי ב-API.
כדי ליצור מכונה של app, שולחים קריאה לשירות שטענתם. לדוגמה:
```
const app = dialogflow();
```
כדי להגדיר את המכונה app באתחול, אפשר לספק options אובייקט כארגומנט הראשון כשקוראים לשירות. (ראו DialogflowOptions לקבלת פרטים נוספים). לדוגמה, קטע הקוד הבא מראה איך לתעד את המטען הייעודי (payload) הגולמי של JSON מ- את הבקשה או התגובה של המשתמש באמצעות הגדרת הדגל { debug: true }:

const app = dialogflow({
  debug: true
});

הגדרת רכיבי handler של אירועים

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

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

אירועי Intent: מנגנוני Intent הם מזהים ייחודיים שנשלחים על ידי Actions on Google למילוי ההזמנות בכל פעם שמשתמש מבקש פונקציונליות ספציפית. אם המיקום בחרת להשתמש ב-Dialogflow, שתואם לשאילתת המשתמש של Dialogflow ל-Intent בסוכן Dialogflow.
אירועי שגיאה: כשמתרחשת שגיאה של JavaScript או ספריית לקוח, אפשר להשתמש בפונקציה catch במכונה app כדי לעבד את חריגה מהשגיאה המתאים. צריך להטמיע פונקציית catch אחת כדי לטפל בכל הפריטים שגיאות שקשורות למילוי ההזמנות.
אירועים חלופיים: אירוע חלופי מתרחש כשהמשתמש שולחת שאילתה ש-Actions on Google לא יכול לזהות. אפשר להשתמש ב-app את הפונקציה fallback במכונה, כדי לרשום handler גנרי חלופי מופעלת אם לא נמצאה התאמה בין Intent מרומז למילוי ההזמנות. בקשה. צריך להטמיע פונקציית fallback אחת כדי לטפל בכל הפריטים אירועים חלופיים. אם משתמשים ב-Dialogflow, אפשר להשתמש ב-Dialogflow כדי להפעיל Intent חלופי כאשר אין התאמה לכוונת רכישה אחרת. עליך ליצור של ה-Intent התואם, עבור ה-Intent החלופי הזה.

בכל פעם שמשתמש שולח בקשה לפעולה, המופע של app יוצר Conversation שמייצג את הסשן של השיחה. הגישה לאובייקט הזה מתבצעת דרך שם המשתנה conv שמועבר בפונקציה של ה-handler של Intent בתור הארגומנט של הפונקציה הראשונה. בדרך כלל תשתמש ב-conv אובייקט ב-handlers של שליחת תגובה למשתמש.

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

אם משתמשים ב-Actions SDK, מגדירים פרמטרים בחבילת הפעולות. כדי לראות דוגמה לאופן שבו אפשר לחלץ פרמטרים מאובייקטים מסוג Intent, אפשר לעיין במאמר דוגמת קוד של Elza.
אם משתמשים ב-Dialogflow, אפשר לגשת לערכי הפרמטרים דרך משתנה params. כדי לראות דוגמאות לטיפול בכוונות עם פרמטרים ב-Dialogflow זמינים במאמר גישה לפרמטרים ולהקשרים.

הגדרת handlers של Intent

כדי להגדיר את ה-handler של Intent, צריך להפעיל את הפונקציה intent() של app מכונה. לדוגמה, אם משתמשים ב-Dialogflow, זו DialogflowApp#intent() מותאמת אישית. בארגומנטים, מציינים את שם ה-Intent ומספקים פונקציית handler.

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

הדוגמה הבאה מציגה גורמים מטפלים של כוונות עבור 'הודעת פתיחה' ו'להתראות'. את הכוונות שלכם. פונקציות ה-handler האנונימיות שלהם מקבלות ארגומנט conv ושולחות חזרה תגובת מחרוזת פשוטה למשתמש באמצעות הפונקציה conv.ask():

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('How are you?');
});

app.intent('bye', (conv) => {
  conv.close('See you later!');
});

חשוב לשים לב שהפונקציה close() דומה לפונקציה ask() אבל היא נסגרת המיקרופון והשיחה תסתיים.

למידע נוסף על בניית handlers של Intents אפשר לעיין במאמר יצירת הגורם המטפל ב-Intent

הגדרת handlers לאירועי שגיאה

כדי להגדיר את הגורמים המטפלים בשגיאות, צריך להפעיל את הפונקציה catch() של app מכונה. (לדוגמה, אם משתמשים ב-Dialogflow, זו DialogflowApp#catch() function.)

בדוגמה הבאה מוצג handler פשוט של שגיאות מאפיס ששולח את השגיאה אל פלט של המסוף ושולח תשובת מחרוזת פשוטה בהתאם להנחיות של המשתמש. הפונקציה conv.ask():

app.catch((conv, error) => {
  console.error(error);
  conv.ask('I encountered a glitch. Can you say that again?');
});

הגדרת handlers לאירועים חלופיים

כדי להגדיר handler גנרי חלופי כשאין התאמה ל-Intent בקשה נכנסת למילוי הזמנה, צריך להפעיל את הפונקציה fallback() של במכונה של app. (לדוגמה, אם משתמשים ב-Dialogflow, זו DialogflowApp#fallback() function.)

בדוגמה הבאה מוצג handler פשוט של חלופה ששולחת חזרה תגובת מחרוזת לבקשת המשתמש באמצעות הפונקציה conv.ask():

app.fallback((conv) => {
  conv.ask(`I couldn't understand. Can you say that again?`);
});

בניית ה-Intent שלך

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

גישה לפרמטרים ובהקשרים

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

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

בכל פעם שהמשתמש שולח בקשה לפעולה, המופע DialogflowApp יוצרת parameters שמייצג את ערכי הפרמטרים ש-Dialogflow חילץ ממנו בקשה. ניתן לגשת לאובייקט הזה דרך שם המשתנה params.

קטע הקוד הבא מראה איך אפשר לגשת לנכס name דרך אובייקט params כשהמשתמש שולח בקשה:

app.intent('Default Welcome Intent', (conv, params) => {
  conv.ask(`How are you, ${params.name}?`);
});

הנה קטע קוד חלופי שעושה את אותו הדבר. סוגר מסולסל ({}) ביצוע הרס של JavaScript לקחת את המאפיין name מהאובייקט parameters ולהשתמש בו בתור משתנה:

app.intent('Default Welcome Intent', (conv, {name}) => {
  conv.ask(`How are you, ${name}?`);
});

בקטע הקוד הבא, שם הפרמטר הוא full-name, אבל הוא מוקצה למשתנה מקומי בשם name:

app.intent('Default Welcome Intent', (conv, {'full-name': name}) => {
  conv.ask(`How are you, ${name}?`);
});

הקשרים הם תכונה מתקדמת של Dialogflow. אפשר להשתמש בהקשרים כדי לנהל את מצב השיחה, את זרימת השיחה הסתעפות. ספריית הלקוח מספקת גישה להקשר דרך DialogflowConversation#contexts לאובייקט. קטע הקוד הבא מראה איך להגדיר הקשר באופן פרוגרמטי ב-webhook של מילוי הבקשה ואיך מאחזרים את אובייקט ההקשר:

app.intent('intent1', (conv) => {
  const lifespan = 5;
  const contextParameters = {
    color: 'red',
  };
  conv.contexts.set('context1', lifespan, contextParameters);
  // ...
  conv.ask('...');
});

app.intent('intent2', (conv) => {
  const context1 = conv.contexts.get('context1');
  const contextParameters = context1.parameters;
  // ...
  conv.ask('...');
});

app.intent('intent3', (conv) => {
  conv.contexts.delete('context1');
  // ...
  conv.ask('...');
});

גישה לתוצאות של מסמך Intent של עוזר

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

דוגמה: תוצאות של כלי אישור

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

// Create Dialogflow intent with `actions_intent_CONFIRMATION` event
app.intent('get_confirmation', (conv, input, confirmation) => {
  if (confirmation) {
    conv.close(`Great! I'm glad you want to do it!`);
  } else {
    conv.close(`That's okay. Let's not do it now.`);
  }
});

דוגמה: תוצאות קרוסלה

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

app.intent('carousel', (conv) => {
  conv.ask('Which of these looks good?');
  conv.ask(new Carousel({
    items: {
      car: {
        title: 'Car',
        description: 'A four wheel vehicle',
        synonyms: ['automobile', 'vehicle'],
      },
      plane: {
        title: 'Plane',
        description: 'A flying machine',
        synonyms: ['aeroplane', 'jet'],
      }
    }
  }));
});

// Create Dialogflow intent with `actions_intent_OPTION` event
app.intent('get_carousel_option', (conv, input, option) => {
  if (option === 'one') {
    conv.close(`Number one is a great choice!`);
  } else {
    conv.close(`Number ${option} is a great choice!`);
  }
});

הגדרת אובייקטים של תשובות לשיחה

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

דוגמה: תמונה

קטע הקוד הבא מראה איך התגובה לפעולה מאתר אחר (webhook) של מילוי ההזמנות יכולה לשלוח Image בתשובה שתצורף לתשובה BasicCard באופן אוטומטי באמצעות הספרייה:

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('Hi, how is it going?');
  conv.ask(`Here's a picture of a cat`);
  conv.ask(new Image({
    url: '/web/fundamentals/accessibility/semantics-builtin/imgs/160204193356-01-cat-500.jpg',
    alt: 'A cat',
  }));
});

ביצוע קריאות לפונקציות אסינכרוניות

ספריית הלקוח Node.js של Actions on Google מיועדת לשימוש אסינכרוני בלי לתכנת. ה-Intent שלך יכול להחזיר הבטחה שנשמעת כאשר ה-webhook webhook הסתיים.

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

בדוגמה הזו אנחנו משתמשים ב-API מזויף כדי לקבל את נתוני מזג האוויר.

/**
 * Make an external API call to get weather data.
 * @return {Promise<string>}
 */
const forecast = () => {
  // ...
};

app.intent('Default Welcome Intent', (conv) => {
  return forecast().then((weather) => {
    conv.ask('How are you?');
    conv.ask(`Today's weather is ${weather}.`);
  });
});

לקטע הקוד הפשוט הבא יש את אותה ההשפעה, אבל הוא משתמש התכונה async await הושקה ב-ECMA 2017 (גרסה 8 של Node.js). כדי להשתמש ב- בקוד הזה ב-Cloud Functions for Firebase, צריך לוודא שאתם משתמשים הגרסה הנכונה של firebase-tools ולוודא שההגדרות נכונות.

app.intent('Default Welcome Intent', async (conv) => {
  const weather = await forecast();
  conv.ask('How are you?');
  conv.ask(`Today's weather is ${weather}.`);
});

אחסון נתוני שיחה

ספריית הלקוח מאפשרת ל-webhook של האספקה לשמור נתונים בשיחות למשך לשימוש עתידי. האובייקטים העיקריים שאפשר להשתמש בהם לאחסון נתונים כוללים:

DialogflowConversation#data או ActionsSdkConversation#data: שמירת נתונים בפורמט JSON במשך כל סשן של שיחה אחת בין המשתמש לפעולה.
Conversation#user.storage: שמירת נתונים בפורמט JSON במספר פורמטים סשנים של שיחות.

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

app.intent('Default Welcome Intent', (conv) => {
  conv.user.storage.someProperty = 'someValue';
  conv.ask('...');
});

אפשר להשתמש בConversation#user להשגת מידע על המשתמש, כולל מזהה מחרוזת מידע אישי. שדות מסוימים כמו conv.user.name.display ו conv.user.email נדרש כדי לבקש conv.ask(new Permission) עבור NAME ו-conv.ask(new SignIn) עבור כניסה באמצעות חשבון Google, בהתאמה.

const {Permission} = require('actions-on-google');
app.intent('Default Welcome Intent', (conv) => {
  if (conv.user.last.seen) {
    conv.ask('Welcome back! How are you?');
  } else {
    conv.ask('Nice to meet you! How are you doing?');
  }
});

app.intent('permission', (conv) => {
  conv.ask(new Permission({
    context: 'To greet you personally',
    permissions: 'NAME',
  }));
});

// Create Dialogflow intent with `actions_intent_PERMISSION` event
app.intent('get_permission', (conv, input, granted) => {
  if (granted) {
    conv.close(`Hi ${conv.user.name.display}!`);
  } else {
    // User did not grant permission
    conv.close(`Hello!`);
  }
});

התאמה לעומס (scaling) באמצעות תווכה

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

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

שירותי Dialogflow ו-Actions SDK חושפים את הפונקציה app.middleware() שמאפשר להוסיף נכסים או מחלקות מסייעות אל Conversation מכונה.

בקטע הקוד הבא מוצגת דוגמה לשימוש בתווכה:

class Helper {
  constructor(conv) {
    this.conv = conv;
  }

  func1() {
    this.conv.ask(`What's up?`);
  }
}

app.middleware((conv) => {
  conv.helper = new Helper(conv);
});

app.intent('Default Welcome Intent', (conv) => {
  conv.helper.func1();
});

ייצוא האפליקציה

כדי לחשוף את ה-webhook של מילוי הבקשה ב-framework של אינטרנט או בפלטפורמת מחשוב ללא שרת (serverless computing), צריך לייצא את האובייקט app בתור תגובה לפעולה מאתר אחר (webhook) שנגיש לכולם. ספריית הלקוח תומכת בפריסה למספר סביבות את התיבה.

קטעי הקוד הבאים מראים איך אפשר לייצא את app בסביבות זמן ריצה שונות:

דוגמה: Cloud Functions for Firebase

const functions = require('firebase-functions');
// ... app code here
exports.fulfillment = functions.https.onRequest(app);

דוגמה: עורך מוטבע של Dialogflow

const functions = require('firebase-functions');

// ... app code here

// Exported function name must be 'dialogflowFirebaseFulfillment'
exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);

דוגמה: שרת Express באירוח עצמי (פשוט)

const express = require('express');
const bodyParser = require('body-parser');  

// ... app code here

express().use(bodyParser.json(), app).listen(3000);

דוגמה: שרת אקספרס באירוח עצמי (מספר מסלולים)

const express = require('express');
const bodyParser = require('body-parser');

// ... app code here

const expressApp = express().use(bodyParser.json());

expressApp.post('/fulfillment', app);

expressApp.listen(3000);

דוגמה: שער AWS Lambda API

// ... app code here

exports.fulfillment = app;