יצירת שירות webhook

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

יצירת הפונקציה

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

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

   כניסה לדף לבחירת הפרויקט

2. פותחים את דף הסקירה הכללית של Cloud Run functions.

   כניסה לדף הסקירה הכללית של Cloud Run functions

3. לוחצים על Create Function (יצירת פונקציה) ומגדירים את השדות הבאים:

   • סביבה: דור ראשון
   • שם הפונקציה: tutorial-banking-webhook
   • ‫Region: אם ציינתם אזור לסוכן, צריך להשתמש באותו אזור.
   • HTTP Trigger type: HTTP
   • כתובת URL: לוחצים על לחצן ההעתקה ושומרים את הערך. תצטרכו את כתובת ה-URL הזו כשמגדירים את ה-webhook.
   • אימות: נדרש אימות
   • נדרש HTTPS: מסומן

4. לוחצים על Save.

5. לוחצים על הבא (אין צורך בהגדרות מיוחדות של זמן ריצה, build, חיבורים או אבטחה).

6. מגדירים את השדות הבאים:

   • ‫Runtime: בוחרים את זמן הריצה האחרון של Go.
   • קוד מקור: עורך מוטבע
   • נקודת כניסה: HandleWebhookRequest

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

   package estwh
   
   import (
   	"context"
   	"encoding/json"
   	"fmt"
   	"log"
   	"net/http"
   	"os"
   	"strings"
   
   	"cloud.google.com/go/spanner"
     "google.golang.org/grpc/codes"
   )
   
   // client is a Spanner client, created only once to avoid creation
   // for every request.
   // See: https://cloud.google.com/functions/docs/concepts/go-runtime#one-time_initialization
   var client *spanner.Client
   
   func init() {
   	// If using a database, these environment variables will be set.
   	pid := os.Getenv("PROJECT_ID")
   	iid := os.Getenv("SPANNER_INSTANCE_ID")
   	did := os.Getenv("SPANNER_DATABASE_ID")
   	if pid != "" && iid != "" && did != "" {
   		db := fmt.Sprintf("projects/%s/instances/%s/databases/%s",
   			pid, iid, did)
   		log.Printf("Creating Spanner client for %s", db)
   		var err error
   		// Use the background context when creating the client,
   		// but use the request context for calls to the client.
   		// See: https://cloud.google.com/functions/docs/concepts/go-runtime#contextcontext
   		client, err = spanner.NewClient(context.Background(), db)
   		if err != nil {
   			log.Fatalf("spanner.NewClient: %v", err)
   		}
   	}
   }
   
   type queryResult struct {
   	Action     string         `json:"action"`
   	Parameters map[string]any `json:"parameters"`
   }
   
   type text struct {
   	Text []string `json:"text"`
   }
   
   type message struct {
   	Text text `json:"text"`
   }
   
   // 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://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookRequest
   type webhookRequest struct {
   	Session     string      `json:"session"`
   	ResponseID  string      `json:"responseId"`
   	QueryResult queryResult `json:"queryResult"`
   }
   
   // 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://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookResponse
   type webhookResponse struct {
   	FulfillmentMessages []message `json:"fulfillmentMessages"`
   }
   
   // accountBalanceCheck handles the similar named action
   func accountBalanceCheck(ctx context.Context, request webhookRequest) (
   	webhookResponse, error) {
   	account := request.QueryResult.Parameters["account"].(string)
   	account = strings.ToLower(account)
   	var table string
   	if account == "savings account" {
   		table = "Savings"
   	} else {
   		table = "Checking"
   	}
   	s := "Your balance is $0"
   	if client != nil {
   		// A Spanner client exists, so access the database.
   		// See: https://pkg.go.dev/cloud.google.com/go/spanner#ReadOnlyTransaction.ReadRow
   		row, err := client.Single().ReadRow(ctx,
   			table,
   			spanner.Key{1}, // The account ID
   			[]string{"Balance"})
   		if err != nil {
   			if spanner.ErrCode(err) == codes.NotFound {
   				log.Printf("Account %d not found", 1)
   			} else {
   				return webhookResponse{}, err
   			}
   		} else {
   			// A row was returned, so check the value
   			var balance int64
   			err := row.Column(0, &balance)
   			if err != nil {
   				return webhookResponse{}, err
   			}
   			s = fmt.Sprintf("Your balance is $%.2f", float64(balance)/100.0)
   		}
   	}
   	response := webhookResponse{
   		FulfillmentMessages: []message{
   			{
   				Text: text{
   					Text: []string{s},
   				},
   			},
   		},
   	}
   	return response, nil
   }
   
   // Define a type for handler functions.
   type handlerFn func(ctx context.Context, request webhookRequest) (
   	webhookResponse, error)
   
   // Create a map from action to handler function.
   var handlers map[string]handlerFn = map[string]handlerFn{
   	"account.balance.check": accountBalanceCheck,
   }
   
   // handleError handles internal errors.
   func handleError(w http.ResponseWriter, err error) {
   	log.Printf("ERROR: %v", err)
   	http.Error(w,
   		fmt.Sprintf("ERROR: %v", err),
   		http.StatusInternalServerError)
   }
   
   // 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 action from the request, and call the corresponding
   	// function that handles that action.
   	action := request.QueryResult.Action
   	if fn, ok := handlers[action]; ok {
   		response, err = fn(r.Context(), request)
   	} else {
   		err = fmt.Errorf("Unknown action: %s", action)
   	}
   	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 קיים כשירות, צריך לשייך אותו לסוכן. הפעולה הזו מתבצעת באמצעות מילוי הזמנות. כדי להפעיל ולנהל את תהליך השלמת ההזמנה של הסוכן:

1. עוברים אל מסוף Dialogflow ES.
2. בוחרים את הסוכן המובנה שיצרתם.
3. בתפריט הצדדי הימני, לוחצים על השלמת הזמנות.
4. מעבירים את המתג בשדה Webhook למצב Enabled (מופעל).
5. מזינים את כתובת ה-URL שהעתקתם למעלה. משאירים את כל שאר השדות ריקים.
6. לוחצים על שמירה בתחתית הדף.

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

1. בתפריט הצדדי הימני, בוחרים באפשרות כוונות.
2. בוחרים את כוונת המשתמש account.balance.check.
3. גוללים למטה לקטע Fulfillment (מימוש).
4. מפעילים את האפשרות הפעלת קריאה ל-webhook עבור הכוונה הזו.
5. לוחצים על Save.

התנסות בסוכן

הסוכן מוכן עכשיו לשימוש. לוחצים על הלחצן Test Agent (בדיקת הסוכן) כדי לפתוח את הסימולטור. נסו לנהל את השיחה הבאה עם הסוכן:

תור בשיחה	את/ה	סוכן
1	שלום	שלום, תודה שבחרת ב-ACME Bank.
2	אני רוצה לדעת מה היתרה בחשבון שלי	מהי היתרה שאתה רוצה לדעת: בחשבון החיסכון או בחשבון העובר ושב?
3	עובר ושב	היתרה האחרונה שלך: 0.00 $

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

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

פתרון בעיות

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

מידע נוסף

מידע נוסף על השלבים שלמעלה:

• המדריך למתחילים של Cloud Run functions Go