תגובות לפעולה מאתר אחר (webhook)

‫Webhooks הם שירותים שמארחים את הלוגיקה העסקית שלכם או קוראים לשירותים אחרים. במהלך סשן, ה-webhook מאפשר לכם להשתמש בנתונים שחולצו על ידי עיבוד השפה הטבעית (NLP) של Dialogflow CX כדי ליצור תגובות דינמיות, לאמת נתונים שנאספו או להפעיל פעולות בשרת העורפי.

‫Webhook יכול להיות Webhook רגיל או Webhook גמיש. ב-webhook רגיל, שדות הבקשה והתגובה מוגדרים על ידי Dialogflow CX. ב-webhook גמיש, אתם מגדירים את שדות הבקשה והתגובה.

אפשר לגשת לקוד סטטוס של HTTP של קריאת ה-webhook גם באמצעות הפרמטר $request.webhook_status_code request.

תגובות לפעולות מאתרים אחרים (webhooks) רגילות

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

בקשה רגילה מ-webhook

כשמתבצעת קריאה לfulfillment עם webhook, ‏ Dialogflow CX שולח בקשת webhook מסוג HTTPS POST לשירות ה-webhook שלכם. גוף הבקשה הזו הוא אובייקט WebhookRequest JSON עם מידע על הסשן.

חלק מהאינטגרציות מאכלסות את השדה WebhookRequest.payload במידע נוסף. לדוגמה, השילוב של Dialogflow CX Phone Gateway מספק את מזהה המתקשר של משתמש הקצה.

פרטים נוספים מופיעים במאמרי העזרה של WebhookRequest (גרסה 3) או של WebhookRequest (גרסה 3Beta1).

תגובה סטנדרטית לפעולה מאתר אחר (webhook)

אחרי ששירות ה-webhook מקבל בקשה, הוא צריך לשלוח תשובה שעומדת בדרישות הבאות:

• התגובה צריכה להתקבל לפני תום הזמן הקצוב לתפוגה שהוגדר כשיוצרים את משאב ה-webhook.
• התשובה צריכה להיות בגודל של 64KiB או פחות.

פרטים נוספים מופיעים במאמרי העזרה של WebhookResponse (גרסה 3) או של WebhookResponse (גרסה 3Beta1).

הגדרות רגילות של משאבי webhook

בטבלה הבאה מפורטות הגדרות משאבי ה-webhook עבור webhooks רגילים:

X	פריט
השם המוצג	השם שמוצג במסוף עבור ה-webhook.
תם הזמן שהוקצב ל-webhook	כש-Dialogflow CX שולח בקשת HTTP לשירות ה-webhook שלכם, ההגדרה הזו קובעת את הזמן הקצוב לתפוגה בשניות לכל ניסיון בקשה בנפרד, ולא לכל תור השיחה. אם ניסיון נכשל או שחלף הזמן הקצוב לתגובה שלו בגלל שגיאה זמנית, Dialogflow CX ינסה שוב באופן אוטומטי. ניסיון החיבור מחדש הזה יכול לגרום לכך שזמן הטיפול הכולל יהיה כפול מהערך של הזמן הקצוב לתפוגה שהוגדר, לפני שהמערכת תחזיר שגיאה. אם מתרחש פסק זמן אחרי ניסיון חוזר, Dialogflow CX מפעיל אירוע של פסק זמן בשליחת בקשת webhook. פרטים נוספים זמינים במאמר ניסיונות חוזרים אוטומטיים.
סוג	אם משתמשים בספריית שירותים לגישה לרשת פרטית, בוחרים באפשרות ספריית שירותים. אחרת, בוחרים באפשרות שירות אינטרנט כללי.
webhook URL	מזינים את כתובת ה-URL של שירות ה-webhook.
סוג משנה	מגדירים את האפשרות Standard (רגילה).
ווּבק ספציפי לסביבה	אפשר לספק ווּבּהוּקים ספציפיים לסביבה.
אימות	מידע נוסף על אימות
אישור CA בהתאמה אישית	האפשרות הזו משמשת להעלאה של אישורי CA בהתאמה אישית.

תגובות לפעולה מאתר אחר (webhook) גמישות

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

בקשת webhook גמישה

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

• ה-method של ה-HTTP שמשמשת לבקשות webhook שנשלחות לשירות ה-webhook שלכם.
• ערכי פרמטרים של סשן ש-Dialogflow CX צריך לשלוח לשירות ה-webhook שלכם באמצעות כתובת ה-URL.
• ערכי פרמטרים של סשן ש-Dialogflow CX צריך לשלוח לשירות ה-webhook שלכם דרך גוף ה-JSON של הבקשה, אם בוחרים באפשרות POST, PUT או PATCH כשיטה.

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

כשמשתמשים בהפניה לפרמטר בגוף ה-JSON, צריך להוסיף מרכאות להפניה, בלי קשר לסוג הפרמטר. אם הפרמטר הוא למעשה ערך מספרי סקלרי, רשימה או ערך מורכב, מערכת Dialogflow CX תסיר את המירכאות כשתשלח את הבקשה בזמן הריצה כדי לשמור על סוג הנתונים של הפרמטר. סוגי סקלר של מחרוזות יישארו מוקפים במירכאות. אם יש הפניה לערך מספרי סקלרי, לרשימה או לערך מורכב בתוך ערך מחרוזת (לדוגמה: 'This is a number: $session.params.size'), הפרמטר יטופל כמחרוזת ('This is a number: 3').

לדוגמה, אפשר לספק את ערכי הפרמטרים של הסשן fruit ו-size בכתובת ה-URL של הבקשה באופן הבא:

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

ובתוכן בקשת ה-JSON באופן הבא:

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

תגובה גמישה לפעולה מאתר אחר (webhook)

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

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

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

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

$.fully.qualified.path.to.field

לדוגמה, נניח שזו תגובת ה-JSON:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

כדי לציין את השדה 'ערך', משתמשים בערכים הבאים:

$.routes[0].legs[0].distance.value

הגדרות גמישות של משאבי webhook

בטבלה הבאה מתוארות הגדרות של משאבי webhook עבור webhooks גמישים.

X	פריט
השם המוצג	השם שמוצג במסוף עבור ה-webhook.
תם הזמן שהוקצב ל-webhook	כש-Dialogflow CX שולח בקשת HTTP לשירות ה-webhook שלכם, ההגדרה הזו קובעת את הזמן הקצוב לתפוגה בשניות לכל ניסיון בקשה בנפרד, ולא לכל תור השיחה. אם ניסיון נכשל או שחלף הזמן הקצוב לתגובה שלו בגלל שגיאה זמנית, Dialogflow CX ינסה שוב באופן אוטומטי. ניסיון החיבור מחדש הזה יכול לגרום לכך שזמן הטיפול הכולל יהיה כפול מהערך של הזמן הקצוב לתפוגה שהוגדר, לפני שהמערכת תחזיר שגיאה. אם מתרחש פסק זמן אחרי ניסיון חוזר, Dialogflow CX מפעיל אירוע של פסק זמן בשליחת בקשת webhook. פרטים נוספים זמינים במאמר ניסיונות חוזרים אוטומטיים.
סוג	אם משתמשים בספריית שירותים לגישה לרשת פרטית, בוחרים באפשרות ספריית שירותים. אחרת, בוחרים באפשרות שירות אינטרנט כללי.
webhook URL	מזינים את כתובת ה-URL של שירות ה-webhook, שיכולה לכלול הפניות לפרמטרים של הסשן.
סוג משנה	מגדירים את האפשרות גמישה.
‏Method	הגדרת ה-method של ה-HTTP לבקשת ה-webhook.
גוף הבקשה	צריך לספק את תוכן בקשת JSON כפי שמתואר למעלה.
הגדרת התשובה	מזינים את פרמטרים של הסשן שצריך להגדיר לשדות התגובה כמו שמתואר למעלה.
ווּבק ספציפי לסביבה	אפשר לספק ווּבּהוּקים ספציפיים לסביבה
אימות	מידע על אימות
אישור CA בהתאמה אישית	האפשרות הזו משמשת להעלאה של אישורי CA בהתאמה אישית.

שימוש בתבנית מותאמת אישית מוגדרת מראש

‫Dialogflow מציע תבניות מותאמות אישית מוגדרות מראש שאפשר להשתמש בהן כדי לשלב תגובות גמישות לפעולות מאתר אחר (webhook) עם מערכת Salesforce CRM.

1. עוברים לכרטיסייה ניהול, בוחרים באפשרות Webhooks ולוחצים על יצירה.
2. בקטע סוג משנה, בוחרים באפשרות גמיש.
3. לוחצים על הגדרה באמצעות תבנית מוגדרת מראש.
4. בתפריט סוג השילוב, בוחרים באפשרות Salesforce.
5. בתפריט API name (שם ה-API), בוחרים שם של API. התבנית ממלאת באופן אוטומטי את טופס ה-webhook על סמך שם ה-API שבחרתם.
   1. אם רלוונטי, מגדירים ידנית את השדות הבאים על סמך הפרמטרים:
      • webhook URL
      • ‏Method
      • תוכן בקשת JSON
      • הגדרת התשובה
   2. שדות החובה של OAuth יסומנו בהדגשה בקטע Authentication (אימות).
6. לוחצים על Save.

דרישות לגבי שירות webhook

שירות ה-webhook צריך לעמוד בדרישות הבאות:

• טיפול בבקשות HTTPS. אין תמיכה ב-HTTP. אם אתם מארחים את שירות ה-webhook ב- Google Cloud באמצעות פתרון Compute או Serverless computing, תוכלו לעיין במסמכי התיעוד בנושא הגשה באמצעות HTTPS. אפשרויות אירוח אחרות מפורטות במאמר קבלת אישור SSL לדומיין.
• מוודאים שכתובת ה-URL של שירות ה-webhook נגישה לכולם, אלא אם היא מתארחת כמשאב Cloud Run או שהגישה אליה היא כ-webhook של Service directory.
• מטפלים בבקשות ובתשובות כמו שמתואר בקטע standard webhook או flexible webhook.
• אם הסוכן שלכם לא משולב עם גישה לרשת פרטית של Service Directory, קריאות ה-webhook נמצאות מחוץ לגבולות גזרה לשירות ונחסמות כשמפעילים את VPC Service Controls. ‫Service Directory תומך במספר מוגבל של נקודות קצה. פרטים נוספים זמינים במאמר בנושא Service Directory.

אימות

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

X	פריט
כותרות אימות	בהגדרות של webhook, אפשר לציין צמדים אופציונליים של מפתח/ערך בכותרת HTTP. אם מספקים כותרות HTTP, מערכת Dialogflow CX מוסיפה אותן לבקשות ל-webhook. מקובל לספק זוג אחד עם מפתח של authorization. ערכי הכותרת תומכים בהפניות לפרמטרים של סשן ובניתוח של פונקציות מערכת כמו בהודעות תגובה סטטיות. אם אתם משתמשים בפרטי כניסה סטטיים בכותרת authorization, מומלץ לספק את פרטי הכניסה באמצעות Secret Manager.
אימות בסיסי עם שם משתמש וסיסמה	בהגדרות של webhook, אפשר לציין ערכים אופציונליים של שם משתמש וסיסמה להתחברות. אם מספקים את הכותרת, Dialogflow CX מוסיף כותרת HTTP של הרשאה לבקשות של webhook. הכותרת הזו היא מהסוג הבא: "authorization: Basic <base 64 encoding of the string username:password>". מומלץ לספק את שם המשתמש והסיסמה באמצעות Secret Manager.
OAuth של צד שלישי	ניתן לציין את תצורת OAuth של צד שלישי כך ש-Dialogflow CX יחליף אסימון גישה ממערכת OAuth ויוסיף אותו לכותרת HTTP של ההרשאה. יש תמיכה רק בתהליך העברת נתוני הכניסה של הלקוח. מומלץ לספק את הסוד של הלקוח באמצעות Secret Manager.
אסימוני גישה של סוכני שירות	הוצא משימוש.
חשבון שירות	אפשר להשתמש בחשבון שירות לצורך אימות. אפשר להשתמש ב-API הזה כדי לגשת ל-API אחרים Google Cloud .
אסימונים מזהים של סוכני שירות	אפשר לבחור באפשרות 'טוקן של מזהה' בקטע 'אימות סוכן שירות', כדי להשתמש בטוקן של מזהה של סוכן שירות לצורך אימות. כך תוכלו לגשת למשאבים של Cloud Run.
אימות TLS הדדי	מידע נוסף זמין במאמר בנושא אימות TLS בו-זמני (mTLS).

הערה: אם מופעלות כמה אפשרויות אימות, לאפשרויות עם עדיפות גבוהה יותר יש עדיפות. סדר העדיפות הוא כזה: כותרות אימות, אימות בסיסי, OAuth של צד שלישי, אימות של סוכן שירות.

הערה: לא מומלץ להשתמש בטווחי כתובות IP כדי לאמת בקשות של webhook. אם בחרתם להשתמש בכתובת ה-IP של המקור של הבקשה כדי לאפשר קישוריות להיקף הרשת שלכם, צריך לאשר בקשות מהטווחים שמפורטים בכתובת https://www.gstatic.com/ipranges/goog.json ולדחות חיבורים מהטווחים שמפורטים בכתובת https://www.gstatic.com/ipranges/cloud.json (אלה כתובות של Google שאפשר להשתמש בהן כדי לפרוס עומסי עבודה של צד שלישי). ‫Dialogflow לא יכול להבטיח טווחי כתובות IP למכונות ששולחות בקשות webhook.

הערה: אחרי 15 באוגוסט 2025, סוכנים מיוצאים לא יכללו יותר פרטי כניסה של ערכים גולמיים עבור כותרות אימות, אימות בסיסי עם שם משתמש וסיסמה או OAuth של צד שלישי.

OAuth של צד שלישי

‫Dialogflow CX אוסף טוקן גישה מספק OAuth של צד שלישי ומוסיף אותו לכותרת ההרשאה של HTTP כשמתבצעות בקשות webhook.

בטבלה הבאה מתוארות הגדרות המשאבים ל-OAuth של צד שלישי:

X	פריט
מזהה לקוח	מזהה הלקוח שבו משתמשים כשמבקשים טוקן OAuth.
סוד לקוח	הסוד שבו משתמשים כשמבקשים טוקן OAuth. מומלץ לספק את הסוד של הלקוח באמצעות Secret Manager.
כתובת ה-URL של נקודת הקצה של OAuth	כתובת האתר שמשמשת לבקשת טוקן OAuth.
היקפי OAuth	רשימה מופרדת בפסיקים של היקפים שאפשר להשתמש בהם בטוקן OAuth.

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

הערה: נעשה שימוש חוזר בטוקנים של OAuth מצד שלישי לבקשות של webhook באמצעות אותו מזהה לקוח, כתובת URL של נקודת קצה והיקפי הרשאה באותו סוכן Dialogflow CX, כל עוד הבקשה מתבצעת באותו שרת Dialogflow CX והתוקף של הטוקן לא פג. כדי להשיג זמינות גבוהה, הסוכנים נפרסים על פני שרתים נפרדים רבים שלא משתפים מטמוני טוקנים של OAuth. כשפורסים פתרון שמשתמש בטוקנים של OAuth של צד שלישי, מומלץ להטמיע פרוקסי של API כדי לעזור בניהול נפח הבקשות שהסוכן עשוי לשלוח לספק OAuth של צד שלישי.

טוקן של מזהה של סוכן שירות

‫Dialogflow CX יכול ליצור טוקן של מזהה באמצעות סוכן השירות של Dialogflow CX. האסימון הזה מתווסף לכותרת Authorization ב-HTTP כש-Dialogflow CX קורא ל-webhook.

אפשר להשתמש בטוקן של מזהה כדי לגשת למשאבי Cloud Run אחרי שמקצים את התפקיד Cloud Run Invoker (roles/run.invoker)

service-agent-project-number@gcp-sa-dialogflow.

אם משאבי Cloud Run נמצאים באותו פרויקט משאבים, לא צריך הרשאה נוספת לניהול זהויות והרשאות גישה (IAM) כדי לקרוא להם.

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

לדוגמה, אם כתובת ה-URL של ה-webhook היא:

https://myproject.cloudfunctions.net/my-function/method1?query=value

כתובת ה-URL הבאה צריכה להיות בפלחים של קהלים בהתאמה אישית:

https://myproject.cloudfunctions.net/my-function/method1

כל webhook יכול גם לאמת את האסימון באמצעות ספריות לקוח של Google או ספריות בקוד פתוח כמו Google Auth Library for Node.js.

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

חשבון השירות

אפשר להשתמש בחשבונות שירות כדי לאמת בקשות של webhook לכל Google APIs שתומכים בהם.

אם עדיין לא עשיתם זאת, צרו חשבון שירות.

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

כדי להגדיר את ה-webhook לשימוש בחשבונות שירות, צריכות להיות לכם ההרשאות הבאות:

• roles/iam.serviceAccountUser

כדי ליצור אסימונים, לסוכן השירות של Dialogflow צריכות להיות ההרשאות הבאות:

• roles/iam.serviceAccountTokenCreator

בנוסף, לחשבון השירות צריכות להיות הרשאות גישה לשירות שמארח את ה-webhook.

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

אימות ב-Secret Manager

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

1. אם אין לכם סוד, צריך ליצור אותו.
2. מקצים לסוכן השירות של Dialogflow‏ (Dialogflow Service Agent) את התפקיד Secret Manager Secret Accessor‏ (roles/secretmanager.secretAccessor) בסוד החדש.
3. מעתיקים את פרטי הכניסה ללוח.
4. מוסיפים גרסה חדשה של הסוד לסוד ומדביקים את פרטי הכניסה כערך הסוד:
   • אם אתם משתמשים בכותרות אימות, מזינים Bearer <YOUR_CREDENTIAL>.
   • אם אתם משתמשים באימות בסיסי של שם משתמש וסיסמה, מזינים <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • אין להוסיף תו מעבר לשורה בסוף.
5. מעתיקים את השם של גרסת הסוד שהוספתם. פורמט השם הוא projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. פותחים את המסך לעריכת ה-webhook.
7. קובעים את הגדרות האימות:
   • אם משתמשים בכותרות אימות, צריך ליצור כותרת בקשה חדשה של גרסה סודית. מזינים Authorization בשדה Key (מפתח) ומדביקים את שם הגרסה הסודית בשדה Secret version (גרסה סודית).
   • כדי להשתמש באימות בסיסי של שם משתמש וסיסמה, לוחצים על Secret version (גרסת הסוד) בקטע Basic Auth (אימות בסיסי) ומדביקים את שם גרסת הסוד בשדה Secret version (גרסת הסוד).
   • אם משתמשים ב-OAuth של צד שלישי, לוחצים על גרסת הסוד בקטע OAuth של צד שלישי ומדביקים את השם של גרסת הסוד בשדה גרסת הסוד.
8. לוחצים על Save.

הערה: אנחנו תומכים רק בסודות גלובליים ב-Secret Manager. אנחנו לא תומכים בסודות אזוריים.

אימות אישור HTTPS

כברירת מחדל, מערכת Dialogflow CX משתמשת במאגר האישורים של Google כדי לאמת אישורי HTTPS. אם אתם מתכוונים להשתמש באישורים שלא מוכרים על ידי מאגר האישורים המהימנים שמוגדר כברירת מחדל ב-Google עבור שרת ה-HTTPS שלכם, כמו אישורים בחתימה עצמית או אישורי בסיס מותאמים אישית, כדאי לעיין במאמר בנושא אישורי CA מותאמים אישית.

‫Webhooks ספציפיים לסביבה

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

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

יצירה או עריכה של משאבי webhook

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

כדי ליצור או לערוך משאב webhook:

המסוף

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

API

מידע על יצירת משאב webhook זמין בשיטה create של הסוג Webhook. מידע על עריכת משאב של webhook (למעט הגדרות ספציפיות לסביבה) זמין בשיטה patch או update עבור הסוג Webhook. מעבר להפניית Webhook API

בוחרים פרוטוקול וגרסה להפניה של ה-Webhook:

פרוטוקול	V3	V3beta1
REST	משאב webhook	משאב webhook
RPC	ממשק webhook	ממשק webhook
C++‎	WebhooksClient	לא זמין
C#‎	WebhooksClient	לא זמין
המשך	WebhooksClient	לא זמין
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	לא זמין	לא זמין
Python	WebhooksClient	WebhooksClient
Ruby	לא זמין	לא זמין

סגירה

מידע על עריכת ההגדרות הספציפיות לסביבה של webhook זמין בשיטה patch או update עבור הסוג Environment. מעבר למאמרי העזרה של ה-API של Environment

בוחרים פרוטוקול וגרסה עבור הפניה לסביבה:

פרוטוקול	V3	V3beta1
REST	משאב סביבה	משאב סביבה
RPC	ממשק הסביבה	ממשק הסביבה
C++‎	EnvironmentsClient	לא זמין
C#‎	EnvironmentsClient	לא זמין
המשך	EnvironmentsClient	לא זמין
Java	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	לא זמין	לא זמין
Python	EnvironmentsClient	EnvironmentsClient
Ruby	לא זמין	לא זמין

סגירה

שגיאות ב-webhook

אם שירות ה-webhook שלך נתקל בשגיאה בעת טיפול בבקשת webhook, קוד ה-webhook שלך אמור להחזיר אחד מקודי סטטוס ה-HTTP הבאים:

• 400: בקשה שגויה
• 401: לא מורשה
• 403: הגישה אסורה
• 404: לא נמצא
• 500: שגיאה בחיבור לשרת
• ‫503: השירות לא זמין

Dialogflow CX מפעיל שגיאת webhook או אירוע מובנה של timeout וממשיך לעבד כרגיל במצבי השגיאה הבאים:

• הזמן הקצוב לתשובה חרג.
• מתקבל קוד סטטוס של שגיאה.
• התגובה לא תקינה.
• שירות ה-webhook לא זמין.

אם הקריאה לשירות ה-webhook הופעלה על ידי קריאה ל-API של זיהוי כוונות, השדה queryResult.webhookStatuses בתגובה לזיהוי הכוונות מכיל את פרטי הסטטוס של ה-webhook.

ניסיונות חוזרים אוטומטיים

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

מערכת Dialogflow CX מבצעת ניסיון חוזר אחד לשגיאות זמניות, כמו זמנים קצובים לתפוגה של בקשות, ניתוקים של חיבורי רשת וקודי סטטוס של HTTP בטווח 5xx (כמו 500 Server fault או 503 Service unavailable). שגיאות סופיות של לקוח, כמו קוד הסטטוס 404 Not found של HTTP, נכשלות באופן מיידי ללא ניסיון חוזר.

תקצוב של זמן אחזור מצטבר ופסק זמן

מכיוון ש-Dialogflow CX מנסה שוב לתקן כשלים זמניים פעם אחת, נקודת קצה של webhook שלא מגיבה עלולה לגרום לזמן תגובה מצטבר של עד פי שניים מערך הזמן הקצוב לתפוגה שהוגדר לפני ש-Dialogflow CX מחזיר שגיאה. לדוגמה, אם הגדרת ברירת המחדל של הזמן הקצוב לתפוגה היא 5 שניות, נקודת קצה שלא מגיבה תגיע לזמן הקצוב לתפוגה אחרי 5 שניות בניסיון הראשוני, ואחרי 5 שניות נוספות בניסיון החוזר. התוצאה היא זמן אחזור כולל של כ-10 שניות לפני ש-Dialogflow CX מפעיל את הגורמים המטפלים בשגיאות, כמו webhook.error.timeoutגורם מטפל באירועים או sys.no-match-defaultגורם מטפל באירועים.

אם לארכיטקטורה שלכם יש מגבלות מחמירות על זמן האחזור של נתונים שנשלחים לשרת (למשל, מערכות טלפוניה או מערכות תגובה קולית אינטראקטיבית (IVR) שמנתקות שיחות אחרי חלון זמן של 10 שניות), כדאי להקצות תקציב לשני הניסיונות על ידי הגדרת פסק הזמן של ה-webhook למחצית חלון הזמן המותר (לדוגמה, בין 2.5 ל-4 שניות).

שיטות מומלצות לניסיונות חוזרים

כדי לטפל ביעילות בניסיונות חוזרים בשירות ה-webhook:

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

שימוש ב-Cloud Run

שימו לב: בקטע הזה מוסבר איך להשתמש במשאבי Cloud Run מאובטחים עבור וווב-הוקים של Dialogflow CX. מומלץ לשמור על אבטחת המשאבים. אם בוחרים באימות באמצעות שם משתמש וסיסמה מבוססי-URL או באמצעות כותרות HTTP, צריך לאפשר גישה לא מאומתת למשאב Cloud Run.

‫Dialogflow CX משתלב עם Cloud Run, כך שאפשר ליצור webhook מאובטח ללא שרת (serverless). אם יוצרים משאב Cloud Run שנמצא באותו פרויקט כמו הסוכן, בוחרים באפשרות Service Agent Auth ואז באפשרות טוקן של מזהה בהגדרת האימות, כדי שהסוכן יוכל להתקשר בבטחה אל ה-webhook.

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

1. חשבון השירות של סוכן השירות של Dialogflow CX עם הכתובת הבאה צריך להתקיים בפרויקט הסוכן:

   service-agent-project-number@gcp-sa-dialogflow.

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

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

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

בקטע Auth configuration, בוחרים באפשרות Service Agent Auth > ID Token.

שימוש בוווב-הוקים מבוססי-קונטיינר ובמסגרת Go ezcx

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

שימוש ב-Cloud Run עם תעבורה פנימית בלבד

הערה: השימוש ב-Cloud Run מחוץ להיקף של VPC Service Controls בפרויקט של סוכן Dialogflow CX עבור webhook לא נתמך.

אתם יכולים להשתמש במשאבי Cloud Run שהוגדרו לקבל תעבורה פנימית מרשתות של ענן וירטואלי פרטי (VPC) באותו פרויקט או באותו מתחם היקפי של VPC Service Controls כ-webhook, בתנאי שהסוכן נמצא באותו פרויקט או באותו מתחם היקפי של VPC Service Controls.

שימוש ב-Service Directory לגישה לרשת פרטית

‫Dialogflow CX משתלב עם גישה לרשת פרטית של Service Directory, כך שהוא יכול להתחבר ליעדי webhook בתוך רשת ה-VPC שלכם. כך התנועה נשארת בתוך רשת Google Cloud ומאפשרת לאכוף את IAM ואת VPC Service Controls.

כדי להגדיר תגובה לפעולה מאתר אחר (webhook) שמטרגטת רשת פרטית:

1. פועלים לפי ההוראות להגדרת רשת פרטית ב-Service Directory כדי להגדיר את רשת ה-VPC ואת נקודת הקצה של Service Directory.

   הערה: ‏ Dialogflow CX שומר במטמון את המידע של Service Directory למשך 90 שניות. המשמעות היא שכשתעדכנו את נקודת הקצה של ספריית השירותים, השינוי יתרחש תוך 90 שניות.

2. חשבון השירות של סוכן השירות של Dialogflow CX עם הכתובת הבאה צריך להתקיים בפרויקט של הסוכן:

   service-agent-project-number@gcp-sa-dialogflow.

   מקצים לחשבון השירות Dialogflow CX Service Agent את התפקידים הבאים בפרויקט שבו נמצא Service Directory:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   בנוסף, אם Service Directory נמצא בפרויקט אחר מהסוכן שלכם ב-Dialogflow CX, אתם צריכים גם להעניק את התפקיד servicedirectory.viewer לחשבון של סוכן השירות של Dialogflow CX בפרויקט שמארח את הסוכן שלכם ב-Dialogflow CX.

3. כשיוצרים את ה-webhook, מציינים את השירות של Service Directory, את כתובת ה-URL ופרטי אימות אופציונליים.

   המסוף

   

   API

   אפשר לעיין בשדה serviceDirectory של הסוג Webhook. מעבר להפניית Webhook API

   בוחרים פרוטוקול וגרסה להפניה של ה-Webhook:

   פרוטוקול	V3	V3beta1
   REST	משאב webhook	משאב webhook
   RPC	ממשק webhook	ממשק webhook
   C++‎	WebhooksClient	לא זמין
   C#‎	WebhooksClient	לא זמין
   המשך	WebhooksClient	לא זמין
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	לא זמין	לא זמין
   Python	WebhooksClient	WebhooksClient
   Ruby	לא זמין	לא זמין

   סגירה

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

דוגמאות ופתרון בעיות

מידע נוסף זמין במדריך בנושא Webhook.