פורמטים של תגובה לפעולה מאתר אחר (webhook) ב-Actions on Google (Dialogflow)

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

הערה: אם יש לכם שרת קצה עורפי של Node.js, מומלץ מאוד להשתמש בספריית הלקוח של Actions on Google Node.js כדי לפשט את יצירת ה-webhook. ספריית הלקוח מספקת wrapper לפורמט ה-webhook. אם אתם מעדיפים לבצע בעצמכם את ההטמעה של הקצה העורפי בלי להשתמש בספריית הלקוח, הקצה העורפי אחראי לצריכה ולעיבוד של הודעות ה-JSON שנשלחות על ידי Actions on Google דרך HTTP POST.

חשוב להבין איך הפעולות ב-Actions on Google ומילוי ההזמנות מתקשרים באמצעות הפורמטים של תגובה לפעולה מאתר אחר (webhook) ב-Actions on Google:

• כדי להשתתף בשיחות באמצעות Actions on Google, מילוי הבקשה כולל webhook שיכול להגיב לבקשות HTTP מ-Actions on Google.
• כשמשתמשים מפעילים את הפעולה, מילוי הבקשה מקבל HTTP POST עם מטען ייעודי (payload) של JSON שמתאר את הבקשה של המשתמש.
• לאחר מכן, מילוי הבקשה אחראי לקריאת הפרמטרים מהמטען הייעודי (payload) של הבקשה, יצירת תגובה מתאימה בפורמט JSON ושליחת תשובה ל-Assistant עם התשובה הזו.

מונחי מפתח:

• פורמט של תגובה לפעולה מאתר אחר (webhook) מסוג Dialogflow: פורמט של המטען הייעודי (payload) של JSON כש-Actions on Google מפעילה את מילוי ההזמנה דרך Dialogflow.
• פורמט של תגובה לפעולה מאתר אחר (webhook): פורמט המטען הייעודי (payload) של JSON כאשר Actions on Google מפעיל את מילוי ההזמנה דרך Actions SDK.

סוגי בקשות

בטבלה הבאה מופיע סיכום של סוגי הבקשות שה-webhook שלכם עשוי לקבל מ-Assistant:

תיאור	התיאור	דוגמאות ל-JSON
בקשות הפעלה	ביטויים של משתמשים שמובילים לשיחה עם מילוי ההזמנה, או מובילים לפעולות של קישור עומק (למשל, "Talk to Personal Chef to find עונת החגים"). אם משתמשים ב-Dialogflow, הבקשות האלה תואמות לאובייקטים מסוג Intent שהוגדרו בקטע Discovery בהגדרות השילוב של Google Assistant. אם נעשה שימוש ב-Actions SDK, הבקשות האלה תואמות לאובייקטים מסוג Intent שהוגדרו בחבילת הפעולות.	תגובה לפעולה מאתר אחר (webhook) ב-Dialogflow תגובה לפעולה מאתר אחר (webhook)
בקשות לשיחות	ביטויים של משתמשים באותו סשן, אחרי שהשיחה עם מילוי הבקשה התחילה. בפורמט של תגובה לפעולה מאתר אחר (webhook) של שיחה, אלו תגובות הטקסט הגולמיות מהמשתמש שתואמות לכוונות actions.intent.TEXT שבקשות מילוי הבקשה שלך ביקשו בתור הקודם.	תגובה לפעולה מאתר אחר (webhook) ב-Dialogflow תגובה לפעולה מאתר אחר (webhook)
תוצאות של כלי העזרה	בקשות ש-Assistant שלחה למילוי הבקשה שלך כשהתגובה לפעולה מאתר אחר (webhook) ביקשה כוונת עזרה בסבב הקודם של השיחה כדי לטפל בחלקים מהשיחה (לדוגמה, actions.intent.OPTION וגם actions.intent.PERMISSION).	תגובה לפעולה מאתר אחר (webhook) ב-Dialogflow תגובה לפעולה מאתר אחר (webhook)

בקשות לשיחות ותגובות

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

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

איור 1. Actions on Google מפעיל את תהליך מילוי ההזמנה דרך Actions SDK.

מידע נוסף על הפורמט של המטען הייעודי (payload) של JSON כאשר Actions on Google מפעיל את מילוי ההזמנה דרך Actions SDK, ראו פורמט של תגובה לפעולה מאתר אחר (webhook).

בקשות ותשובות ב-Dialogflow

כשיוצרים פעולות, אפשר להשתמש ב-Dialogflow כדי לפשט את המשימה של בניית ממשקי שיחה. בתרחיש הזה, Dialogflow הוא למעשה שרת proxy בין Actions on Google לבין מילוי הזמנות. במקום לשלוח את בקשת ה-HTTP או JSON ישירות לנקודת הקצה של מילוי הבקשה, Actions on Google שולחת אותה אל Dialogflow.

Dialogflow כולל את המטען הייעודי (payload) של JSON שכלול בבקשה המקורית בפורמט של תגובה לפעולה מאתר אחר (webhook) ומעביר את הבקשה שמתקבלת למילוי הבקשה ב-Dialogflow.

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

איור 2. פעולות ב-Google מפעילה את מילוי ההזמנה דרך Dialogflow.

מידע נוסף על הפורמט של המטען הייעודי (payload) של JSON כאשר שירות Actions on Google מפעיל את מילוי ההזמנה דרך Dialogflow, אפשר למצוא במאמר בנושא פורמט של תגובה לפעולה מאתר אחר (webhook) ב-Dialogflow.