יצירת webhook

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

קוד ה-webhook לדוגמה מבצע את הפעולות הבאות:

• קריאת ערכי הפרמטרים מבקשת ה-webhook.
• כותב ערך פרמטר בתגובת ה-webhook.
• מספק תשובה שהיא טקסט בתגובת ה-webhook.

לפני שמתחילים

אם אתם לא מתכננים להשתמש ב-webhook, אתם יכולים לדלג על המדריך הזה.

לפני שתקראו את המדריך הזה:

1. מידע בסיסי על תהליכי עבודה
2. לבצע את השלבים להגדרה.
3. פועלים לפי השלבים במדריך למתחילים בנושא יצירת סוכן באמצעות רצפי פעולות. השלבים שבהמשך מתייחסים לאותו Agent. אם אין לכם יותר את הסוכן הזה, אתם יכולים להוריד את הסוכן ולשחזר אותו.

יצירת הפונקציה של Cloud Functions

אפשר ליצור Cloud Functions באמצעות מסוף Google Cloud (למשאבי העזרה, לפתיחת המסוף). כדי ליצור פונקציה למדריך הזה:

1. חשוב שהסוכן של Dialogflow CX והפונקציה יהיו באותו פרויקט. זו הדרך הכי קלה לתת ל-Dialogflow CX גישה מאובטחת לפונקציה שלכם. כדי לבחור את הפרויקט, עוברים לדף לבחירת הפרויקט.
2. עוברים אל דף הסקירה הכללית של Cloud Functions.
3. לוחצים על יצירת פונקציה ומגדירים את השדות הבאים:
   • סביבה: דור ראשון
   • שם הפונקציה: shirts-agent-webhook
   • ‫Region: אם ציינתם אזור לסוכן, צריך להשתמש באותו אזור.
   • HTTP Trigger type: HTTP
   • כתובת URL: לוחצים על לחצן ההעתקה ושומרים את הערך. תצטרכו את כתובת ה-URL הזו כשמגדירים את ה-webhook.
   • אימות: נדרש אימות
   • נדרש HTTPS: מסומן
4. לוחצים על Save.
5. לוחצים על הבא (אין צורך בהגדרות מיוחדות של זמן ריצה, build, חיבורים או אבטחה).
6. מגדירים את השדות הבאים:
   • ‫Runtime: בוחרים את זמן הריצה האחרון של Go.
   • קוד מקור: עורך מוטבע
   • נקודת כניסה: HandleWebhookRequest

7. מחליפים את הקוד בקוד הבא:

   // Package cxwh contains an example Dialogflow CX webhook
   package cxwh
   
   import (
   	"encoding/json"
   	"fmt"
   	"log"
   	"net/http"
   )
   
   type fulfillmentInfo struct {
   	Tag string `json:"tag"`
   }
   
   type sessionInfo struct {
   	Session    string         `json:"session"`
   	Parameters map[string]any `json:"parameters"`
   }
   
   type text struct {
   	Text []string `json:"text"`
   }
   
   type responseMessage struct {
   	Text text `json:"text"`
   }
   
   type fulfillmentResponse struct {
   	Messages []responseMessage `json:"messages"`
   }
   
   // webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that
   // not all members need to be defined--just those that you need to process.
   // As an alternative, you could use the types provided by the Dialogflow protocol buffers:
   // https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookRequest
   type webhookRequest struct {
   	FulfillmentInfo fulfillmentInfo `json:"fulfillmentInfo"`
   	SessionInfo     sessionInfo     `json:"sessionInfo"`
   }
   
   // webhookResponse is used to marshal a WebhookResponse JSON object. Note that
   // not all members need to be defined--just those that you need to process.
   // As an alternative, you could use the types provided by the Dialogflow protocol buffers:
   // https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookResponse
   type webhookResponse struct {
   	FulfillmentResponse fulfillmentResponse `json:"fulfillmentResponse"`
   	SessionInfo         sessionInfo         `json:"sessionInfo"`
   }
   
   // confirm handles webhook calls using the "confirm" tag.
   func confirm(request webhookRequest) (webhookResponse, error) {
   	// Create a text message that utilizes the "size" and "color"
   	// parameters provided by the end-user.
   	// This text message is used in the response below.
   	t := fmt.Sprintf("You can pick up your order for a %s %s shirt in 5 days.",
   		request.SessionInfo.Parameters["size"],
   		request.SessionInfo.Parameters["color"])
   
   	// Create session parameters that are populated in the response.
   	// The "cancel-period" parameter is referenced by the agent.
   	// This example hard codes the value 2, but a real system
   	// might look up this value in a database.
   	p := map[string]any{"cancel-period": "2"}
   
   	// Build and return the response.
   	response := webhookResponse{
   		FulfillmentResponse: fulfillmentResponse{
   			Messages: []responseMessage{
   				{
   					Text: text{
   						Text: []string{t},
   					},
   				},
   			},
   		},
   		SessionInfo: sessionInfo{
   			Parameters: p,
   		},
   	}
   	return response, nil
   }
   
   // handleError handles internal errors.
   func handleError(w http.ResponseWriter, err error) {
   	w.WriteHeader(http.StatusInternalServerError)
   	fmt.Fprintf(w, "ERROR: %v", err)
   }
   
   // HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse.
   func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) {
   	var request webhookRequest
   	var response webhookResponse
   	var err error
   
   	// Read input JSON
   	if err = json.NewDecoder(r.Body).Decode(&request); err != nil {
   		handleError(w, err)
   		return
   	}
   	log.Printf("Request: %+v", request)
   
   	// Get the tag from the request, and call the corresponding
   	// function that handles that tag.
   	// This example only has one possible tag,
   	// but most agents would have many.
   	switch tag := request.FulfillmentInfo.Tag; tag {
   	case "confirm":
   		response, err = confirm(request)
   	default:
   		err = fmt.Errorf("Unknown tag: %s", tag)
   	}
   	if err != nil {
   		handleError(w, err)
   		return
   	}
   	log.Printf("Response: %+v", response)
   
   	// Send response
   	if err = json.NewEncoder(w).Encode(&response); err != nil {
   		handleError(w, err)
   		return
   	}
   }

8. לוחצים על פריסה.

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

יצירת ה-webhook

עכשיו ה-webhook קיים כפונקציית Cloud, ותקשרו אותו לסוכן. כדי ליצור את ה-webhook לסוכן:

1. פותחים את מסוף Dialogflow CX.
2. בוחרים את הפרויקט ב-Google Cloud.
3. בוחרים את הסוכן.
4. לוחצים על הכרטיסייה ניהול.
5. לוחצים על Webhooks.
6. לוחצים על יצירה.
7. ממלאים את השדות הבאים:
   • השם המוצג: shirts-agent-webhook
   • כתובת ה-URL של ה-webhook: מציינים את כתובת ה-URL של ה-webhook ששמרתם כשיצרתם את הפונקציה.
   • תת-סוג: רגיל.
   • כל שאר השדות משתמשים בערכי ברירת המחדל.
8. לוחצים על Save.

שימוש ב-webhook

עכשיו ה-webhook זמין לסוכן, ותוכלו להשתמש בו בfulfillment. בדף אישור ההזמנה יש רכיב של השלמת הזמנה, שכרגע כולל תשובה של טקסט סטטי. כדי לעדכן את תהליך הביצוע של ההזמנה כך שישתמש ב-webhook:

1. בוחרים בכרטיסייה Build (פיתוח).
2. לוחצים על הדף אישור הזמנה כדי להרחיב את הדף בתרשים של הכלי ליצירת סוכנים.
3. לוחצים על השדה Entry Fulfillment בדף כדי לפתוח את חלונית ה-fulfillment.
4. מוחקים את התשובה הכתובה הקיימת מתחת לכותרת הסוכן אומר. כשמעבירים את הסמן מעל הטקסט, מופיע לחצן המחיקה .
5. לוחצים על הפעלת webhook.
6. בתפריט הנפתח Webhook, בוחרים באפשרות shirts-agent-webhook.
7. מזינים confirm בשדה Tag (תג).
8. לוחצים על Save.
9. סוגרים את חלונית השלמת ההזמנה.

קוד ה-webhook שנפרס שולח תגובה שיוצרת פרמטר בשם cancel-period. מעדכנים את הנציג כך שיפנה לפרמטר הזה בתגובה הסופית של הנציג בדף אישור ההזמנה:

1. לוחצים על התנאי route שמוצג עם התנאי true כדי לפתוח את חלונית המסלול.
2. גוללים למטה לקטע Fulfillment (ביצוע) בחלונית המסלול, מוסיפים את התשובה הכתובה הבאה בכותרת Agent says (מה הסוכן אומר): You can cancel your order within $session.params.cancel-period days. Goodbye.
3. לוחצים על Save.
4. סוגרים את חלונית המסלול.

בדיקת הסוכן בסימולטור

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

1. לוחצים על Test Agent (בדיקת הסוכן).
2. מזינים I want to buy a large red shirt ומקישים על Enter.

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

בקטעים הבאים מפורטות התגובות של הסוכן:

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