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

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

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

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

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

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

בקשת webhook רגילה

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

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

לפרטים נוספים, קראו את מאמרי העזרה של WebhookRequest (V3) או של WebhookRequest (V3Beta1).

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

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

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

לפרטים נוספים, קראו את מאמרי העזרה של WebhookResponse (V3) או של WebhookResponse (V3Beta1).

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

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

X	פריט
השם המוצג	השם שמוצג במסוף של ה-webhook.
תם הזמן הקצוב לתפוגה של ה-webhook	כש-Dialogflow CX שולח בקשת HTTP לשירות ה-webhook, ההגדרה הזו קובעת את משך הזמן הקצוב לתפוגה בשניות לכל ניסיון שליחת בקשה, ולא לכל התור בשיחה. אם הזמן הקצוב לניסיון נגמר או שהניסיון נכשל בגלל שגיאה זמנית, Dialogflow CX מנסה שוב באופן אוטומטי. הניסיון החוזר הזה יכול להוביל לזמן כולל של עד פי שניים מערך הזמן הקצוב לתפוגה שהוגדר לפני החזרת שגיאה. אם מתרחש זמן קצוב לתפוגה אחרי ניסיון חוזר, Dialogflow CX מפעיל אירוע webhook.error.timeout. פרטים נוספים זמינים במאמר ניסיונות חוזרים אוטומטיים.
סוג	אם אתם משתמשים ב-Service Directory כדי לגשת לרשת פרטית, מגדירים את האפשרות Service Directory. אחרת, מגדירים את האפשרות Generic web service.
webhook URL	מזינים את כתובת ה-URL של שירות ה-webhook.
סוג משנה	מגדירים את האפשרות רגיל.
תגובה לפעולה מאתר אחר (Webhook) ספציפית לסביבה	אתם יכולים לספק תגובות לפעילות אינטרנט (webhooks) ספציפיות לסביבה.
אימות	למידע נוסף על אימות
אישור CA בהתאמה אישית	ההגדרה הזו משמשת להעלאת אישורי CA בהתאמה אישית.

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

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

בקשת webhook גמישה

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

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

כדי לשלוח ערכים של פרמטרים של סשן באמצעות כתובת ה-URL של הבקשה או גוף ה-JSON, משתמשים בהפניות לפרמטרים. אין צורך להוסיף תווי בריחה (escape) לכתובת ה-URL של ההפניה לפרמטר או להקיף אותה במירכאות. בזמן הריצה, Dialogflow CX מוסיף תווי בריחה (escape) לערך הפרמטר לפי הצורך. רשימה או ערך מורכב מסופקים כ-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
          }
        }
      ]
    }
  ]
}

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

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

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

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

X	פריט
השם המוצג	השם שמוצג במסוף של ה-webhook.
תם הזמן הקצוב לתפוגה של ה-webhook	כש-Dialogflow CX שולח בקשת HTTP לשירות ה-webhook, ההגדרה הזו קובעת את משך הזמן הקצוב לתפוגה בשניות לכל ניסיון שליחת בקשה, ולא לכל התור בשיחה. אם הזמן הקצוב לניסיון נגמר או שהניסיון נכשל בגלל שגיאה זמנית, Dialogflow CX מנסה שוב באופן אוטומטי. הניסיון החוזר הזה יכול להוביל לזמן כולל של עד פי שניים מערך הזמן הקצוב לתפוגה שהוגדר לפני החזרת שגיאה. אם מתרחש זמן קצוב לתפוגה אחרי ניסיון חוזר, Dialogflow CX מפעיל אירוע webhook.error.timeout. פרטים נוספים זמינים במאמר ניסיונות חוזרים אוטומטיים.
סוג	אם אתם משתמשים ב-Service Directory לגישה לרשת פרטית, מגדירים את האפשרות Service Directory. אחרת, מגדירים את האפשרות Generic web service.
webhook URL	מזינים את כתובת ה-URL של שירות ה-webhook, שיכולה לכלול הפניות לפרמטרים של סשן.
סוג משנה	מגדירים את האפשרות גמיש.
‏Method	מגדירים את שיטת ה-HTTP לבקשת ה-webhook.
גוף הבקשה	מזינים את גוף בקשת ה-JSON כפי שמתואר למעלה.
הגדרת התשובה	מציינים את הפרמטרים של הסשן שצריך להגדיר לשדות התגובה כמו שמתואר למעלה.
תגובה לפעולה מאתר אחר (Webhook) ספציפית לסביבה	אפשר לספק תגובות לפעולה מאתר אחר (webhooks) ספציפיות לסביבה
אימות	למידע נוסף על אימות
אישור CA בהתאמה אישית	ההגדרה הזו משמשת להעלאת אישורי CA בהתאמה אישית.

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

ב-Dialogflow יש תבניות מוגדרות מראש בהתאמה אישית, שמאפשרות לשלב תגובות גמישות לפעולות מאתר אחר (webhooks) עם Salesforce CRM.

1. עוברים לכרטיסייה Manage, בוחרים באפשרות Webhooks ולוחצים על Create.
2. בקטע סוג משנה, בוחרים באפשרות גמיש.
3. לוחצים על הגדרה באמצעות תבנית מוגדרת מראש.
4. בתפריט סוג השילוב, בוחרים באפשרות Salesforce.
5. בתפריט API name, בוחרים שם של 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.
• מטפלים בבקשות ובתגובות כמו שמתואר בקטע תגובת Webhook רגילה או תגובת Webhook גמישה.
• אם הנציג לא משולב עם גישה לרשת פרטית של Service Directory, הקריאות ל-webhook נמצאות מחוץ לגבולות הגזרה לשירות ונחסמות כשמפעילים את VPC Service Controls. ב-Service Directory יש תמיכה בנקודות קצה מוגבלות. לפרטים, קראו את המאמר Service Directory.

אימות

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

X	פריט
כותרות אימות	בהגדרות של ה-webhook, אתם יכולים לציין צמדי מפתח/ערך אופציונליים של כותרת HTTP. אם מספקים אותן, Dialogflow CX מוסיף את כותרות ה-HTTP האלה לבקשות של ה-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 אחרים של Google Cloud .
טוקנים של מזהי סוכני שירות	בקטע Service agent authentication, אתם יכולים לבחור באפשרות ID token כדי להשתמש בטוקן של מזהה סוכן השירות לאימות. כך תוכלו לגשת למשאבים של Cloud Run.
אימות TLS בו-זמני (mTLS)	למידע נוסף, קראו את המאמר אימות 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	כתובת ה-URL שמשמשת לבקשת טוקן OAuth.
היקפי OAuth	רשימה מופרדת בפסיקים של היקפי הרשאות שאפשר להשתמש בהם עם אסימון ה-OAuth.

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

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

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

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

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

[e-mail]

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

הקהל שמשמש ליצירת הטוקן של המזהה הוא כתובת ה-URL המלאה של ה-webhook, לא כולל פרמטרים של שאילתה. אם אתם משתמשים ב-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. מידע נוסף על קהלים בהתאמה אישית זמין במאמר הגדרת קהלים בהתאמה אישית לשירותים.

חשבון השירות

אפשר להשתמש בחשבונות שירות כדי לאמת בקשות של תגובות לפעילות אינטרנט בכל ממשקי ה-API של Google שתומכים בהן.

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

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

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

• roles/iam.serviceAccountUser

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

• roles/iam.serviceAccountTokenCreator

לחשבון השירות צריכות להיות גם הרשאות גישה לשירות שמארח את ה-webhook.

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

אימות ב-Secret Manager

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

1. אם אין לכם סוד, צרו סוד.
2. מקצים לסוכן השירות של Dialogflow את התפקיד מנהל גישה לסודות ב-Secret Manager (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. קובעים את הגדרות האימות:
   • אם אתם משתמשים בכותרות אימות, צרו כותרת בקשה חדשה לגרסת סוד. בשדה Key מזינים Authorization, ובשדה Secret version מדביקים את שם הגרסה של הסוד.
   • לאימות בסיסי של שם משתמש וסיסמה, לוחצים על Secret version בקטע Basic Auth ומדביקים את שם הגרסה הסודית בשדה Secret version.
   • אם אתם משתמשים ב-Third-party OAuth, לוחצים על Secret version בקטע Third-party OAuth ומדביקים את שם הגרסה של הסוד בשדה Secret version.
8. לוחצים על Save.

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

אימות אישור HTTPS

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

תגובות לפעולה מאתר אחר (webhooks) ספציפיות לסביבה

אם אתם משתמשים בסביבות כדי להפריד בין סביבת הייצור לסביבת הפיתוח, אתם יכולים להגדיר את ה-webhooks כך שיהיו ספציפיים לסביבה. אתם יכולים לספק הגדרות אימות וכתובת 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. למאמרי העזרה של Environment API

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

פרוטוקול	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 לא זמין.

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

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

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

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

תקציב מצטבר לזמן אחזור ולזמן קצוב לתפוגה

מכיוון ש-Dialogflow CX מנסה שוב פעם אחת כשיש כשלים זמניים, נקודת קצה (endpoint) של webhook שלא מגיבה יכולה לגרום לזמן תגובה מצטבר של עד פי שניים מערך הזמן הקצוב לתפוגה שהוגדר, לפני ש-Dialogflow CX מחזיר שגיאה. לדוגמה, אם הגדרתם את ברירת המחדל של זמן קצוב לתפוגה של 5 שניות, נקודת קצה (endpoint) שלא מגיבה תגרום לזמן קצוב לתפוגה אחרי 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 בשביל לפעולות לפיתוח Webhook ב-Dialogflow CX. מומלץ לשמור על אבטחת המשאבים. אם בחרתם לאמת באמצעות שם משתמש וסיסמה שמבוססים על כתובת URL, או באמצעות כותרות HTTP, אתם צריכים לאפשר גישה ללא אימות למשאב של Cloud Run.

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

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

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

   [e-mail]

   חשבון השירות המיוחד הזה והמפתח שמשויך אליו נוצרים בדרך כלל באופן אוטומטי כשיוצרים את הנציג הראשון בפרויקט. אם הנציג נוצר לפני 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 Service Agent בפרויקט של משאב Cloud Run.

בקטע Auth configuration, בוחרים באפשרות Service Agent Auth > טוקן של מזהה.

שימוש ב-webhooks בקונטיינרים וב-framework‏ ezcx של Go

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

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

הערה: אי אפשר להשתמש ב-Cloud Run מחוץ להיקף של VPC Service Controls בפרויקט של סוכן Dialogflow CX בשביל לפעולות לפיתוח API (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. כדי להגדיר את רשת ה-VPC ואת נקודת הקצה של Service Directory, פועלים לפי ההוראות במאמר הגדרת רשת פרטית של Service Directory.

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

2. חשבון השירות Dialogflow CX Service Agent עם הכתובת הבאה חייב להיות קיים בפרויקט של הנציג:

   [e-mail]

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

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

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

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.