הגדרת התראות באמצעות webhook

אתם מציגים את מסמכי התיעוד של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

מהו webhook?

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

כדי להגדיר התראות באמצעות webhooks, מבצעים את השלבים הבאים באמצעות ממשק המשתמש של Edge Management או באמצעות Management and Monetization API:

  1. מוסיפים webhooks שמגדירים את הטיפולים בקריאה החוזרת (callback) של אירועי ההתראות באמצעות ממשק המשתמש או ממשק ה-API.
  2. מגדירים את הטיפול בקריאה החוזרת.
  3. מגדירים את ההתראה לתוכנית עם שיעור משתנה באמצעות ממשק המשתמש או ה-API.

ניהול ה-webhooks

הוספה וניהול של webhooks שמגדירים את פונקציות ה-callback של אירועי ההתראות באמצעות ממשק המשתמש או ה-API.

ניהול webhooks באמצעות ממשק המשתמש

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

הדף Webhooks

נכנסים לדף Webhooks כפי שמתואר בהמשך.

Edge

כך נכנסים לדף ה-webhooks באמצעות ממשק המשתמש של Edge:

  1. נכנסים לכתובת apigee.com/edge.
  2. בוחרים באפשרות פרסום > מונטיזציה > Webhooks בסרגל הניווט הימני.

הדף Webhooks מוצג.

כפי שמודגש באיור, בדף Webhooks אפשר:

Classic Edge (ענן פרטי)

כדי לגשת לדף Webhooks באמצעות ממשק המשתמש הקלאסי של Edge:

  1. מתחברים אל http://ms-ip:9000, כאשר ms-ip היא כתובת ה-IP או שם ה-DNS של צומת שרת הניהול.

  2. בוחרים באפשרות ניהול > Webhooks.

הדף Webhooks מוצג.

בדף Webhooks אפשר:

הוספת webhook באמצעות ממשק המשתמש

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

  1. נכנסים אל הדף Webhooks.
  2. לוחצים על + Webhook.
  3. מזינים את הפרטים הבאים (כל השדות נדרשים).
    שדה תיאור
    שם השם של ה-webhook.
    כתובת אתר כתובת ה-URL של ה-handler של הקריאה החוזרת (callback) שתיקרא כשההתראה על האירוע תופעל. הגדרת הטיפול בקריאה החוזרת
  4. לוחצים על שמירה.

ה-webhook מתווסף לרשימה ומופעל כברירת מחדל.

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

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

  1. נכנסים לדף ה-webhooks.
  2. מעבירים את הסמן מעל ה-webhook שרוצים לערוך ולוחצים על בתפריט הפעולות.
  3. עורכים את שדות ה-webhook לפי הצורך.
  4. לוחצים על עדכון ה-Webhook.

הפעלה או השבתה של webhook באמצעות ממשק המשתמש

כדי להפעיל או להשבית webhook באמצעות ממשק המשתמש:

  1. נכנסים אל הדף Webhooks.
  2. מציבים את הסמן מעל ה-webhook ומחליפים את מצב המתג כדי להפעיל או להשבית אותו.

מחיקת webhook באמצעות ממשק המשתמש

כדי למחוק webhook באמצעות ממשק המשתמש:

  1. נכנסים אל הדף Webhooks.
  2. מציבים את הסמן מעל ה-webhook שרוצים למחוק ולוחצים על .

ה-webhook נמחק ומוסרה מהרשימה.

ניהול webhooks באמצעות ה-API

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

הצגת כל ה-webhooks באמצעות ה-API

כדי להציג את כל ה-webhooks יש לשלוח בקשת GET אל /mint/organizations/{org_name}/webhooks. לדוגמה:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

הדוגמה הבאה מציגה את התשובה שחזרה:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

הצגת webhook באמצעות ה-API

כדי להציג webhook יחיד, שולחים בקשת GET אל /mint/organizations/{org_name}/webhooks/{webhook_id}.

לדוגמה:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

דוגמה לתגובה:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

הוספת webhook באמצעות ה-API

כדי להוסיף webhook, צריך לשלוח בקשת POST אל /mint/organizations/{org_name}/webhooks. צריך להעביר את השם של ה-webhook ואת כתובת ה-URL של פונקציית הקריאה החוזרת (callback) שתופעל כשהתראה על האירוע מופעלת.

לדוגמה, הפקודה הבאה יוצרת תגובה לפעולה מאתר אחר (webhook) בשם webhook3 ומקצה את callbackhandler3 לתגובה לפעולה מאתר אחר:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

הדוגמה הבאה ממחישה את התשובה:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

עריכת webhook באמצעות ה-API

כדי לערוך webhook, שולחים בקשת PUT אל /mint/organizations/{org_name}/webhooks/{webhook_id}. צריך להעביר את העדכונים בגוף הבקשה.

לדוגמה, הקוד הבא מעדכן את פונקציית הטיפול בקריאה החוזרת (callback) שמשויכת ל-webhook1:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

דוגמה לתגובה:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

הפעלה או השבתה של webhook באמצעות ה-API

כדי להפעיל או להשבית webhook, שולחים בקשת POST אל /mint/organizations/{org_name}/webhooks/{webhook_id}, כמו שעושים כשמעדכנים webhook, ומגדירים את המאפיין enabled בגוף הבקשה כ-true או כ-false, בהתאמה. אם משביתים את ה-webhook, הוא לא יופעל כשמתרחש אירוע.

לדוגמה, הפקודה הבאה מפעילה את webhook3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

דוגמה לתגובה:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

מחיקת webhook באמצעות ה-API

כדי למחוק webhook, שולחים בקשת DELETE אל /mint/organizations/{org_name}/webhooks/{webhook_id}.

כדי לציין אם לאלץ את המחיקה של ה-webhook אם יש תהליכים שנמצאים בטיפול, מגדירים את פרמטר השאילתה forceDelete לערך true או לערך false. הפרמטר forceDelete של השאילתה מופעל (true) כברירת מחדל.

לדוגמה, הפקודה הבאה מוחקת את webhook3:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

הגדרת הטיפול בקריאה החוזרת

בהמשך מוצג הפורמט של בקשת ה-JSON שנשלחת למטפל בקריאה החוזרת (callback) שמוגדר על ידי webhook כשמתקבלת התראה על אירוע. חשוב לוודא שהבקשה תעובד כראוי על ידי הטיפול החוזר.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

הגדרת התראות לתוכנית עם שיעור משתנה

מגדירים התראות באמצעות webhooks לתוכנית עם תמחור גמיש באמצעות ממשק המשתמש או ה-API.

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

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

גישה לתיבת הדו-שיח 'התראות' בתוכנית עם שיעור משתנה

נכנסים לתיבת הדו-שיח 'התראות' כדי לקבל תוכנית תמחור ותשלומים שאפשר לשנות, כמו שמתואר בהמשך.

Edge

כדי לגשת לתיבת הדו-שיח של ההתראות באמצעות ממשק המשתמש של Edge:

  1. יוצרים ומפרסמים תוכנית לשינוי תדירות ההתראות, כפי שמתואר בקטע ציון פרטי התוכנית לשינוי תדירות ההתראות.
  2. כדי לגשת לדף 'חבילות מינויים', בוחרים באפשרות פרסום > מונטיזציה > חבילות מינויים בסרגל הניווט הימני.
  3. מעבירים את הסמן מעל התוכנית שפורסמה לשינוי שיעור ההתראות כדי להציג את הפעולות.
  4. לוחצים על +Notify.

    תיבת הדו-שיח 'התראות' מוצגת.

    הערה: כדי שהפעולה '+התראה' תוצג, חבילת השירות צריכה להיות מפורסמת.

Classic Edge (ענן פרטי)

כדי לגשת לדף 'התראות':

  1. יוצרים תוכנית עם שיעור התראות שניתן לשינוי, כפי שמתואר במאמר ציון פרטי תוכנית עם שיעור התראות שניתן לשינוי.
  2. בוחרים באפשרות פרסום > חבילות כדי להציג את תוכניות התמחור.
  3. לוחצים על +Notify (הוספת התראה) בעמודה Actions (פעולות) של תוכנית התמחור.

    תיבת הדו-שיח 'התראות' תוצג.

הוספת התראות לתוכנית עם שיעור משתנה באמצעות ממשק המשתמש

כדי להוסיף התראות לתוכנית תעריפים שניתנת להתאמה, צריך להשתמש בממשק המשתמש:

  1. עוברים לתיבת הדו-שיח 'התראות'.
  2. מגדירים את תנאי ההתראה בקטע מרווחי זמן להתרעות. לשם כך, מציינים אחוז ממספר העסקאות היעד שבו רוצים שהתראה תופעל. באופן ספציפי:
    • כדי להגדיר אחוז מדויק, מזינים את האחוז בשדה At/From % ומשאירים את השדה To % ריק.
    • כדי להגדיר טווח אחוזים, מזינים את אחוז ההתחלה ואת אחוז הסיום בשדות At/From % ו-To %, בהתאמה, ואת ערך העלייה בשדה Step %. כברירת מחדל, ההתראות נשלחות בקפיצות של 10% בטווח שצוין.

    השדה Notify At מתעדכן ומשקף כל אחוז ממספר היעד של הטרנזקציות שיפעילו אירוע.

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

עריכת התראות לתוכנית עם שיעור משתנה באמצעות ממשק המשתמש

כדי לערוך התראות בתוכנית עם שיעור משתנה בממשק המשתמש:

  1. עוברים לתיבת הדו-שיח 'התראות'.
  2. לוחצים על +התראה בעמודה 'פעולות' של תוכנית התמחור והתשלומים.
  3. לוחצים על עריכה.
  4. משנים את הערכים לפי הצורך.
  5. לוחצים על שמירת ההתראה.

מחיקת התראות לגבי תוכנית עם שיעור מותאם באמצעות ממשק המשתמש

כדי למחוק תנאי והפעלה של התראה:

  1. נכנסים לתיבת הדו-שיח 'התראות'.
  2. לוחצים על +Notify (הוספת התראה) בעמודה Actions (פעולות) של תוכנית התמחור.
  3. לוחצים על מחיקת התזכורת.

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

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

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

מאפיין ערך
RATEPLAN המזהה של תוכנית שיעור ההתראות שניתן לשינוי.
PUBLISHED TRUE כדי לציין שחובה לפרסם את תוכנית קצב ההתראות המתאימה.
UsageTarget אחוז ממספר העסקאות היעד שבו רוצים שתישלח התראה.

המאפיין הזה מאפשר לכם להודיע למפתחים כשהם מתקרבים למספר העסקאות היעד שלהם בתוכנית התמחור שלהם, או כשהם מגיעים למספר הזה, עבור תוכנית התמחור שלהם עם שיעור התראות מותאם אישית. לדוגמה, אם מפתח רכש תוכנית עם שיעור התראות שניתן לשינוי ומספר העסקאות היעד של המפתח הוגדר ל-1,000, תוכלו לשלוח לו התראה כשהוא יגיע ל-800 עסקאות (80% ממספר העסקאות היעד), ל-1,000 עסקאות (100%) או ל-1,500 עסקאות (150%).

  • כדי להגדיר אחוז מדויק, מזינים %= n. לדוגמה, %= 80 ישלח התראות כשאחוז מספר העסקאות היעד יגיע ל-80%.
  • כדי להגדיר טווח אחוזים, מזינים את האחוזים של ההתחלה והסיום ואת הערך שבו רוצים להגדיל את הערך, באופן הבא: %= start to end by n. לדוגמה, כשהערך הוא %= 80 to 100 by 10, תישלח התראה כשאחוז מספר העסקאות היעד יגיע ל-80%, ל-90% ול-100%.

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

מאפיין ערך
actionAttribute WEBHOOK כדי להפעיל webhook.
value המזהה של ה-webhook שהגדרתם בקטע הקודם, יצירת webhooks באמצעות ה-API.

הדוגמה הבאה ממחישה איך ליצור תנאי התראה שמפעיל תגובה לפעולה מאתר אחר (webhook) כשהאחוז ממספר היעד של העסקאות מגיע ל-80%, ל-90%, ל-100%, ל-110% ול-120%.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

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

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

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

קוד תגובה תיאור
2xx הפעולה הצליחה
5xx

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

הערה: זמן הקצאת הזמן לקריאה ולחיבור לבקשות webhook הוא 3 שניות לכל אחת, מה שעלול לגרום לבקשות שנכשלו.
Other response הבקשה נכשלה. המערכת לא תנסה שוב לשלוח את הבקשה.