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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

בקשת webhook גמישה

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

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

כדי לשלוח ערכים של פרמטרים של סשן באמצעות כתובת ה-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
          }
        }
      ]
    }
  ]
}

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

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

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

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

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

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

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

  1. בכרטיסייה Manage (ניהול), לוחצים על Webhooks (ווּבּהוּקים) ואז על + Create (יצירה).

  2. בקטע סוג משנה, בוחרים באפשרות גמיש.

  3. לוחצים על הגדרה באמצעות תבנית מוגדרת מראש כדי להפעיל את התכונה.

  4. בתפריט הנפתח סוג השילוב, בוחרים באפשרות Salesforce.

  5. בתפריט הנפתח API name (שם ה-API), בוחרים שם של API. התבנית ממלאת באופן אוטומטי את טופס ה-webhook על סמך שם ה-API שתבחרו.

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

      • כתובת ה-URL של ה-webhook
      • ‏Method
      • תוכן בקשת JSON
      • הגדרת התשובה

    2. שדות החובה של OAuth יסומנו בהדגשה בקטע אימות.

  6. לוחצים על שמירה כדי ליצור את ה-webhook.

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

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

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

אימות

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

מונח הגדרה
כותרות אימות בהגדרות של 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.
אסימוני גישה של סוכני שירות Discontinued
חשבון שירות אפשר להשתמש בחשבון שירות לצורך אימות. אפשר להשתמש בזה כדי לגשת לממשקי Google Cloud API אחרים.
אסימונים מזהים של סוכני שירות אתם יכולים לבחור באפשרות 'אסימון מזהה' באימות סוכן שירות כדי להשתמש באסימוני מזהה של סוכן שירות לצורך אימות. אפשר להשתמש בזה כדי לגשת למשאבים של Cloud Run.
אימות TLS בו-זמני (mTLS) מידע נוסף זמין במאמר בנושא אימות TLS בו-זמני (mTLS).

OAuth של צד שלישי

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

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

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

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

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

‫Dialogflow CX יכול ליצור אסימון מזהה באמצעות סוכן השירות של Dialogflow CX.

האסימון מתווסף לכותרת ההרשאה של HTTP כש-Dialogflow CX קורא ל-Webhook.

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

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
 אם משאבי 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 או ספריות קוד פתוח כמו github.com/googleapis/google-auth-library-nodejs.

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

חשבון השירות

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

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

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

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

  • roles/iam.serviceAccountUser

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

  • roles/iam.serviceAccountTokenCreator

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

אימות ב-Secret Manager

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

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

אימות אישור HTTPS

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

ווּבּהוּקים ספציפיים לסביבה

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

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

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

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

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

המסוף

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

API

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

בוחרים פרוטוקול וגרסה להפניה ל-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.

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

פרוטוקול 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 Server fault
  • 503 השירות לא זמין

בכל אחת מהשגיאות הבאות,‏ Dialogflow CX מפעיל שגיאה או זמן קצוב לתפוגה של webhook, אירוע מובנה וממשיך את העיבוד כרגיל:

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

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

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

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

כדי להקטין את הסיכוי לשיחות כפולות:

  • הגדרת ספי תפוגה ארוכים יותר של Webhook.
  • תמיכה באידמפוטנטיות בלוגיקה של ה-webhook או ביטול כפילויות.

שימוש ב-Cloud Run

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

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

  1. חשבון השירות של סוכן השירות של Dialogflow CX עם הכתובת הבאה צריך להתקיים בפרויקט הסוכן: 
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     חשבון השירות המיוחד הזה והמפתח המשויך אליו נוצרים בדרך כלל באופן אוטומטי כשיוצרים את הסוכן הראשון לפרויקט. אם הסוכן שלכם נוצר לפני 1 בנובמבר 2020, אתם יכולים להפעיל את היצירה של חשבון השירות המיוחד הזה:
    1. יוצרים סוכן חדש לפרויקט.
    2. מריצים את הפקודה הבאה: 
      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
  2. אם פונקציית ה-webhook נמצאת בפרויקט אחר מהסוכן, צריך להקצות את תפקיד IAM Cloud Run Invoker או Cloud Functions Invoker לחשבון השירות Dialogflow CX Service Agent בפרויקט של משאב Cloud Run.
  3. בקטע Auth configuration (הגדרת אימות), בוחרים באפשרות Service Agent Auth -> ID Token (אימות סוכן שירות -> אסימון מזהה).

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

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

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

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

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

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

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

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

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

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

    מקצים לחשבון השירות 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 ואת פרטי האימות האופציונליים.

    המסוף

    צילום מסך של webhook של Service Directory.

    API

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

    בוחרים פרוטוקול וגרסה להפניה ל-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

הקודם
Fulfillments
הבא
Generators