ספריית הלקוח Actions on Google Node.js היא הדרך המומלצת לקבלת גישה לפלטפורמת Actions on Google ולאינטראקציה איתה, אם אתם יוצרים תגובה לפעולה מאתר אחר (webhook) של מילוי בקשה ב-JavaScript.
מבוא
ספריית הלקוח של Node.js היא ספריית מילוי הזמנות ל-Actions on Google, שכוללת את התכונות הבאות:
- תמיכה בכל התכונות של Actions on Google, כולל תגובות טקסט ומולטימדיה עשירה, כניסה לחשבון, אחסון נתונים, עסקאות ועוד.
- מספקת שכבה אידיומטית של הפשטה ב-JavaScript, שאורזת את Call HTTP/JSON webhook API.
- טיפול בפרטים הנמוכים של התקשורת בין מילוי ההזמנה לבין פלטפורמת Actions on Google.
- אפשר להתקין את האפליקציה באמצעות כלים מוכרים לניהול חבילות, כמו
npmאוyarn. - מאפשר לכם לפרוס בקלות את ה-webhook של מילוי הבקשה בפלטפורמות מחשוב ללא שרת, כמו 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 של מילוי הבקשה משתמש בספריית הלקוח כדי לעבד בקשות של משתמשים ש-Actions on Google שולח למילוי הבקשה.
כשיוצרים webhook למילוי הזמנה ב-JavaScript, אפשר לפרוס את הקוד ולארח אותו בסביבת מחשוב ללא שרת, כמו Cloud Functions for Firebase של Google או AWS Lambda אתם יכולים גם לארח את הקוד בעצמכם בלי צורך בפעולות נוספות, באמצעות Express web framework.
בסביבת זמן הריצה, ה-webhook של מילוי הבקשה יכול להפעיל פונקציות בספריית הלקוח כדי לעבד בקשות של משתמשים ולשלוח תשובות חזרה ל-Actions on Google לצורך רינדור לפלט של המשתמש.
בסיכום קצר של המשימות העיקריות שבהן ה-webhook של מילוי הבקשה מטפל בעזרת ספריית הלקוח:
- קבלת בקשות ממשתמשים: כשמשתמש שולח שאילתה ל-Google Assistant, פלטפורמת Actions on Google שולחת בקשת HTTP אל ה-webhook של מילוי הבקשה. הבקשה כוללת מטען ייעודי (payload) של JSON שמכיל את ה-Intent ונתונים נוספים, כמו הטקסט הגולמי של קלט המשתמש ויכולות הפלטפורמה של המכשיר של המשתמש. לדוגמאות נוספות של תוכן מטען ייעודי (payload) של JSON, תוכלו לקרוא את המדריכים בנושא פורמט Dialogflow webhook ופורמט של תגובה לפעולה מאתר אחר (webhook).
- זיהוי פורמט קריאה ל-framework: במסגרות נתמכות, ספריית הלקוח מזהה באופן אוטומטי את פורמט הקריאה של ה-framework (לדוגמה, אם הבקשה הגיעה מ-Express Web framework או מ-AWS Lambda) ויודע איך לטפל בתקשורת בצורה חלקה עם פלטפורמת Actions on Google.
- עיבוד של Service handler: ספריית הלקוח מייצגת את פונקציית השירות HTTP/JSON webhook API עבור Dialogflow ו-Actions SDK. ה-webhook של מילוי הבקשה משתמש בשירות המתאים כדי ליצור מופע גלובלי של
app. המכונהappמשמשת כ-handler לבקשות HTTP ומבינה את הפרוטוקול הספציפי של השירות. - עיבוד שיחה: ספריית הלקוח מייצגת מידע לכל שיחה כאובייקט
Conversationשמצורף למופע שלapp. ה-webhook של מילוי הבקשה יכול להשתמש באובייקטConversationכדי לאחזר נתונים או מצב שנשמרו בין שיחות, לשלוח תשובות למשתמשים או לסגור את המיקרופון. - עיבוד תוכנה זדונית: ספריית הלקוח מאפשרת ליצור תווכה משלכם של שירותי שיחות, שכוללת פונקציה אחת או יותר שאתם מגדירים שספריית הלקוח תפעל באופן אוטומטי לפני שמפעילים את ה-handler של Intent. ה-webhook של מילוי הבקשה יכול להשתמש בתווכה שלך כדי להוסיף נכסים או מחלקות מסייעות לאובייקט
Conversation. - עיבוד handler של Intent: ספריית הלקוח מאפשרת להגדיר רכיבי handler של אובייקטים מסוג 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) למילוי הזמנות, צריך להתקין את ספריית הלקוח.
התקנה של ספריית הלקוח
הדרך הקלה ביותר להתקין את ספריית הלקוח בסביבת הפיתוח המקומית היא להשתמש במנהל חבילות כמו npm או yarn.
כדי להתקין, מריצים את אחת מהפקודות הבאות מהטרמינל:
- אם משתמשים ב-npm:
npm install actions-on-google - אם משתמשים בצמר:
yarn add actions-on-google
הגדרה של תיקיות הפרויקט
בהתאם למיקום שבו אתם מתכננים לפרוס את ה-webhook של מילוי הבקשה (Cloud Functions של Google for Firebase, AWS Lambda או Express באירוח עצמי), יכול להיות שתצטרכו ליצור מבנה ספציפי של תיקיות פרויקטים כדי לשמור את הקבצים שלכם.
לדוגמה, אם אתם משתמשים ב-Cloud Functions for Firebase, אתם יכולים להגדיר את תיקיות הפרויקט הנדרשות על ידי ביצוע השלבים שמתוארים במאמר הגדרת Node.js ו-CLI של Firebase והפעלה של Firebase for Cloud Functions. כשמשתמשים ב-Cloud Functions for Firebase, בדרך כלל כותבים את ה-webhook של מילוי הבקשה בקובץ /functions/index.js.
בניית מופע של אפליקציה
ב-Actions on Google נעשה שימוש בפורמטים ספציפיים של העברת הודעות כדי לשלוח בקשות ותשובות עם ה-webhook למילוי הזמנות, בהתאם לשיטה שאתם יוצרים באמצעות Dialogflow או Actions SDK, או ליצור פעולה בבית חכם.
כדי לייצג את הפרוטוקולים השונים של הבקשות והתגובה, ספריית הלקוח מספקת שלוש פונקציות שירות:
פרוטוקול webhook משמש גם לשירותי שיחה (Dialogflow ו-Actions SDK), אבל כל שירות עוטף את ההודעות באופן שונה.
כדי ליצור מכונה של app צריך להשתמש בשירות. המכונה app כוללת את המצב הגלובלי ואת הלוגיקה למילוי הבקשה של ה-webhook, ומטפלת בתקשורת בין Actions on Google לבין מילוי הבקשה באמצעות פרוטוקול ספציפי לשירות.
אפשר להגדיר את המאפיינים של המכונה app ולהפעיל את השיטות שלה
כדי להנחות את ההתנהגות של ה-webhook של מילוי הבקשה. אפשר גם לחבר בקלות את המכונה app לסביבת מחשוב ללא שרת, כמו 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, אפשר לציין מחלקות שמייצגות תגובות מתקדמות, כוונות של עזרה ופונקציות נוספות של Actions on Google שבהן רוצים להשתמש. הרשימה המלאה של המחלקות התקפות שאפשר לטעון מופיעה במסמכי התיעוד של המודולים של תגובת השיחה וכוונת העזרה.כדי ליצור מכונה של
app, מתקשרים לשירות שטענתם. לדוגמה:const app = dialogflow();
כדי להגדיר את המופע של
appבזמן האתחול, אפשר לספק אובייקטoptionsכארגומנט הראשון כשמפעילים את השירות. (לפרטים נוספים, ראוDialogflowOptions). לדוגמה, קטע הקוד הבא מראה איך לתעד את המטען הייעודי (payload) הגולמי של JSON מהבקשה או מהתגובה של המשתמש, על ידי הגדרת הדגל{ debug: true }:
const app = dialogflow({
debug: true
});
הגדרת גורמי handler לאירועים
כדי לעבד פעולות באירועים שקשורים ל-Google, שנוצרו על ידי ספריית הלקוח במהלך מחזור החיים של אינטראקציית המשתמש עם הפעולה, תשתמשו בספריית הלקוח כדי ליצור רכיבי handler לעיבוד של בקשות ממשתמשים ולשליחת תגובות בחזרה.
אתם יכולים ליצור פונקציות שפועלות כרכיבי handler לסוגים המרכזיים של האירועים שספריית הלקוח מזהה:
- אירועי Intent: אובייקטים מסוג Intent הם מזהים ייחודיים ש-Actions on Google שולח למילוי הבקשה בכל פעם שמשתמש מבקש פונקציונליות ספציפית. אם משתמשים ב-Dialogflow, ההתאמה של Dialogflow בין שאילתות של משתמשים ל-Intents בסוכן Dialogflow היא התאמה של Dialogflow ל-Intent.
- אירועי שגיאה: כשמתרחשת שגיאה ב-JavaScript או בספריית לקוח, אפשר להשתמש בפונקציה
catchשל המכונהappכדי לעבד כראוי את החריגה של השגיאה. כדאי להטמיע פונקצייתcatchאחת שתטפל בכל השגיאות שחשובות למילוי הבקשה. - אירועי חלופי: אירוע חלופי מתרחש כשהמשתמש שולח שאילתה ש-Actions on Google לא מצליח לזהות. אפשר להשתמש בפונקציה
fallbackשל המכונהappכדי לרשום handler חלופי גנרי, שיופעל אם לא הותאם handler של Intent לבקשה הנכנסת למילוי הבקשה. צריך להטמיע פונקצייתfallbackאחת כדי לטפל בכל אירועי החלופה. אם משתמשים ב-Dialogflow, ל-Dialogflow יש אפשרות להפעיל כוונה חלופית ספציפית אם אין התאמה ל-Intent אחר. עליכם ליצור handler תואם של Intent ל-Intent החלופי הזה.
בכל פעם שמשתמש שולח בקשה לפעולה שלכם, המכונה app יוצרת אובייקט Conversation שמייצג את הסשן של השיחה. הגישה לאובייקט הזה מתבצעת דרך שם המשתנה conv שמועבר בפונקציית ה-handler של ה-Intent כארגומנט
הראשון של הפונקציה. בדרך כלל משתמשים באובייקט conv ב-handlers כדי לשלוח תגובה למשתמש.
שאילתות משתמש יכולות לכלול גם פרמטרים שהפעולה יכולה לחלץ ולהשתמש בהם כדי לצמצם את התשובות.
- אם אתם משתמשים ב-Actions SDK, אתם מגדירים פרמטרים בחבילת פעולות. כדי לראות דוגמה לאופן שבו מחלצים פרמטרים מ-Intents, עיינו בדוגמה של קוד אליזה.
- אם אתם משתמשים ב-Dialogflow, אפשר לגשת לערכי הפרמטרים דרך המשתנה
params. במאמר פרמטרים והקשרים של גישה מפורטות דוגמאות לטיפול באובייקטים מסוג Intent עם פרמטרים ב-Dialogflow.
הגדרת רכיבי handler ל-Intents
כדי להגדיר את ה-handler ל-Intent, צריך להפעיל את הפונקציה intent() של המכונה app. לדוגמה, אם משתמשים ב-Dialogflow, זו הפונקציה DialogflowApp#intent(). בארגומנטים, מציינים את שם ה-Intent ומספקים פונקציית handler.
אם אתם משתמשים ב-Dialogflow, לא צריך להגדיר handlers לכל Intent אצל הנציג. במקום זאת, תוכלו להשתמש ב-handler המובנה של Dialogflow כדי לטפל בכוונות באופן אוטומטי בלי להטמיע פונקציות של handler משלכם. לדוגמה, אפשר להעניק ל-Dialogflow את כוונת ברירת המחדל לקבלת פנים.
בדוגמה הבאה מוצגים רכיבי handler של Intent לכוונות 'פתיח' ו 'ביי'. פונקציות ה-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(), אלא שהיא סוגרת את המיקרופון והשיחה הסתיימה.
במאמר יצירת רכיבי handler של Intent תוכלו לקרוא מידע נוסף על יצירת רכיבי handler של Intents.
הגדרת handlers לאירועי שגיאה
כדי להגדיר את רכיבי ה-handler לשגיאות, צריך לקרוא לפונקציה catch() של המכונה app. (לדוגמה, אם משתמשים ב-Dialogflow, זו הפונקציה DialogflowApp#catch()).
בדוגמה הבאה מוצג handler פשוט של שגיאות תפיסה, ששולח את השגיאה לפלט המסוף ושולח תגובת מחרוזת פשוטה כדי לבקש מהמשתמש באמצעות הפונקציה conv.ask():
app.catch((conv, error) => {
console.error(error);
conv.ask('I encountered a glitch. Can you say that again?');
});
הגדרת גורמי handler לאירועי חלופה
כדי להגדיר handler חלופי גנרי כשאין התאמה ל-Intent לבקשה הנכנסת למילוי הבקשה, צריך לקרוא לפונקציה fallback() של המכונה של app. (לדוגמה, אם משתמשים ב-Dialogflow, זו הפונקציה DialogflowApp#fallback()).
בדוגמה הבאה מוצג handler פשוט חלופי, ששולח תגובת מחרוזת
פשוטה כדי לבקש מהמשתמש באמצעות הפונקציה conv.ask():
app.fallback((conv) => {
conv.ask(`I couldn't understand. Can you say that again?`);
});
יצירת ה-handler של Intent
בקטע הזה מתוארים כמה תרחישים נפוצים שבהם מטמיעים רכיבי handler של Intent בספריית הלקוח. כדי לראות איך ספריית הלקוח תואמת ל-Intent, תוכלו לעיין בקטע 'עיבוד של handler של Intent' במאמר הסבר על התהליך.
פרמטרים והקשרים של גישה
אם אתם משתמשים ב-Dialogflow, אפשר להגדיר פרמטרים והקשרים בסוכן Dialogflow כדי לשמור את פרטי המצב ולשלוט בזרימת השיחה.
פרמטרים שימושיים לתיעוד מילים, ביטויים וערכים חשובים בשאילתות של משתמשים. Dialogflow מחלץ את הפרמטרים המתאימים משאילתות של משתמשים בזמן הריצה, ואפשר לעבד את ערכי הפרמטרים האלה ב-webhook של מילוי הבקשה כדי לקבוע איך להגיב למשתמשים.
בכל פעם שמשתמש שולח בקשה ל-Action, המכונה 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 של המסייע
לנוחיותכם, בספריית הלקוח יש מחלקות של כוונת עזרה של עזרה שעוטפות בסוגים נפוצים של נתוני משתמשים שפעולות מסוימות מבקשות לעיתים קרובות. הן כוללות מחלקות שמייצגות את התוצאות של כוונות העזרה השונות של Actions on Google. כשאתם רוצים ש-Google Assistant תטפל בחלקים של השיחה שבהם המשתמשים צריכים לספק קלט כדי להמשיך את השיחה, כדאי להשתמש בכוונות של העוזר.
דוגמה: תוצאות של כלי האישור
בקשת האישור המסייע מאפשרת לך לבקש מהמשתמש אישור של 'כן/לא' ולקבל את התשובה שהתקבלה.
קטע הקוד הבא מראה איך התגובה לפעולה מאתר אחר (webhook) יכולה להתאים אישית את התגובה שלה על סמך התוצאות שהוחזרו על ידי Intent של גורם מסייע. דוגמה מלאה יותר זמינה במסמכי התיעוד של הכיתה 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',
}));
});
ביצוע קריאות לפונקציה אסינכרונית
ספריית הלקוח Actions on Google Node.js מיועדת לתכנות אסינכרוני. ה-handler של ה-Intent יכול להחזיר הבטחה שמתבטלת כשה-webhook של מילוי הבקשה יסיים ליצור תגובה.
בקטע הקוד הבא מוסבר איך לבצע קריאה אסינכרונית של פונקציה כדי להחזיר אובייקט הבטחה, ואז להגיב באמצעות הודעה אם התגובה לפעולה מאתר אחר (webhook) מקבלת את Intent ה 'ברכה'. בקטע הקוד הזה, ההבטחה מבטיחה שה-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!`);
}
});
התאמה לקנה מידה באמצעות תווכה
אפשר להרחיב את ספריית הלקוח באמצעות תווכה.
שכבת התווכה מורכבת מפונקציה אחת או יותר שאתם מגדירים, שספריית הלקוח מריצה באופן אוטומטי לפני שמפעילים את ה-handler של כוונת הרכישה. באמצעות שכבת תווכה (Mediation) אפשר לשנות את המכונה של 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 באינטרנט או לפלטפורמת מחשוב ללא שרת,
צריך לייצא את האובייקט 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);
דוגמה: שרת Express באירוח עצמי (מסלולים מרובים)
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;