מוצג המסמך של Apigee Edge.
עוברים אל
מסמכי תיעוד של Apigee X. מידע
Apigee Edge מתעדת מגוון רחב של נתונים תפעוליים ועסקיים שזורמים בין ממשקי API. המדדים שנגזרים מהנתונים האלה שימושי למעקב תפעולי ולמעקב עסקי. באמצעות Edge API Analytics אפשר, לדוגמה, לקבוע אילו ממשקי API מניבים ביצועים טובים או גרועים, אילו מפתחים מספקים התנועה בעלת הערך הגבוה ביותר, ואילו אפליקציות גורמות להכי הרבה בעיות בשירותים לקצה העורפי.
כדי לגשת לנתוני המדדים האלה בקלות, Edge חושף API ל-RESTful. אפשר להשתמש ב-Metric API כדי להפוך פונקציות מסוימות של Analytics לאוטומטיות, כמו אחזור מדדים. מדי פעם באמצעות לקוח או סקריפט של אוטומציה. תוכלו גם להשתמש ב-API כדי ליצור רכיבים חזותיים בצורת ווידג'טים מותאמים אישית שאפשר להטמיע בפורטלים או באפליקציות מותאמות אישית.
כדי ללמוד איך להשתמש ב-Analytics ב-API ממשק המשתמש של ניהול Edge זמין במאמר סקירה כללית על API Analytics.
מידע על ממשקי ה-API למדדים
Edge מספק שני ממשקי API של מדדים:
קבלת מדדים מחזירה מדדים עבור ארגון וסביבה על פני פרק זמן מסוים, כמו שעה, יום או שבוע.
לדוגמה, לגבי השבוע הקודם שרוצים לקבל:
- מספר השגיאות שקשורות למדיניות
- זמן התגובה הממוצע
- סך כל התנועה
סידור המדדים לפי מאפיינים מחזירה מדדים לאורך זמן עבור הארגון והסביבה שמקובצים לפי מאפיין.
לדוגמה, בשבוע הקודם השתמשתם במאפיינים כדי לקבץ מדדים לפי מוצר API, שרת proxy ל-API, ואת כתובת האימייל של המפתח כדי לקבל:
- מספר השגיאות שקשורות למדיניות לכל מוצר API
- זמן התגובה הממוצע לכל שרת proxy ל-API
- נפח התנועה הכולל לכל אימייל של מפתח
סידור המדדים לפי מאפיינים ה-API תומך בתכונות נוספות שלא נתמכות על ידי מדדי אחזור ב-API, כולל:
מידע על המכסות ל-Metric API ב-API
Edge אוכף את המכסות הבאות על הקריאות האלה. המכסה מבוססת על מערכת הקצה העורפי מטפל בשיחה:
- Postgres: 40 קריאות לדקה
- BigQuery: 12 קריאות לדקה
בודקים את אובייקט התגובה כדי לקבוע מהי מערכת הקצה העורפי שמטפלת בשיחה.
כל אובייקט של תשובה מכיל מאפיין metaData שמפרט את השירות שטיפל בהפעלה
בנכס Source. לדוגמה, עבור Postgres:
{
...
"metaData": {
"errors": [],
"notices": [
"Source:Postgres",
"Table used: xxxxxx.yyyyy",
"query served by:111-222-333"
]
}
}
ב-BigQuery, המאפיין Source הוא:
"Source:Big Query"
אם תחרגו ממכסת הקריאות, ה-API יחזיר תגובת HTTP 429.
אחזור מדדים באמצעות ממשק ה-API לניהול
ההבדל העיקרי בין שני ממשקי ה-API הוא קבלת מדדים. מחזירה מדדים גולמיים לכל הארגון והסביבה, סידור המדדים לפי מאפיינים מאפשרת לקבץ מדדים לפי סוגי ישויות שונים, כמו מוצר API, מפתח ואפליקציה.
כתובת ה-URL של הבקשה עבור ה-API Get metrics היא:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/statsסידור המדדים לפי מאפיינים
ב-API, צריך לכלול בכתובת ה-URL משאב נוסף אחרי /stats שמציין את המאפיין הרצוי:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimensionלדוגמה, כדי לקבל מדדים המקובצים לפי שרת proxy ל-API, צריך להשתמש בכתובת ה-URL הבאה כדי להפעיל ממשק ה-API לניהול:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxyציון המדדים שיוחזרו
עבור שתי פלטפורמות הפרסום
קבלת מדדים
סידור המדדים לפי מאפיינים
ממשקי API שבהם משתמשים בפרמטר השאילתה select כדי לציין את המדדים
ופונקציית צבירה אופציונלית, בתבנית:
?select=metric
או:
?select=aggFunction(metric)
כאשר:
- metric מציין את הנתונים שרוצים להחזיר. לדוגמה,
מספר בקשות ה-API, ההיטים במטמון או שגיאות המדיניות. לעיון במדדים
לטבלה שמציינת את שם המדד שבו צריך להשתמש עם פרמטר השאילתה
select. aggFunction מציין את פונקציית הצבירה האופציונלית שפועלת על המדד. לדוגמה, ניתן להשתמש בפונקציות הצבירה הבאות עם המדד 'זמן אחזור' של העיבוד:
avg: הפונקציה מחזירה את זמן האחזור הממוצע בעיבוד.min: הפונקציה מחזירה את זמן האחזור המינימלי לעיבוד.max: הפונקציה מחזירה את זמן האחזור המקסימלי לעיבוד.-
sum: מחזירה את הסכום של כל זמני האחזור של העיבוד.
לא כל המדדים תומכים בכל פונקציות הצבירה. התיעוד בכתובת העמודה מדדים מכילה טבלה שמציינת את שם המדד והפונקציה (
sum,avg,min,max) שנתמכת על ידי המדד.
לדוגמה, כדי להחזיר את מספר העסקאות הממוצע, כלומר בקשות לשרת proxy של API, לשנייה:
?select=tps
שימו לב שלדוגמה הזו לא נדרשת פונקציית צבירה. בדוגמה הבאה משתמשים פונקציית צבירה שתחזיר את סכום ההיטים של המטמון:
?select=sum(cache_hit)
אפשר להחזיר מספר מדדים לקריאה אחת ל-API. כדי לקבל מדדים לגבי סכום השגיאות שקשורות למדיניות
ואת גודל הבקשה הממוצע, מגדירים את פרמטר השאילתה select באמצעות
רשימת מדדים:
?select=sum(policy_error),avg(request_size)
ציון תקופת הזמן
ה-API של המדדים מחזיר נתונים במשך תקופת זמן מסוימת. שימוש בtimeRange
פרמטר של שאילתה שמציין את תקופת הזמן, בצורה הבאה:
?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
חשוב לשים לב ל%20 לפני HH:MM. הפרמטר timeRange
מחייב תו רווח בקידוד כתובת URL לפני HH:MM, או תו +,
כמו: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.
לדוגמה:
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
אל תשתמשו בשעה 24:00 כשעה, כי השעה מסתיימת ב-00:00. במקום זאת, יש להשתמש ב-23:59.
שימוש בתו מפריד
כדי להפריד בין כמה מאפיינים בקריאה ל-API, צריך להשתמש בפסיק (,) כתו מפריד.
לדוגמה, בקריאה ל-API
curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day
המאפיינים apis ו-apps מופרדים באמצעות ,.
קריאות לדוגמה ל-API
הקטע הזה כולל דוגמאות לשימוש באפשרות קבלת מדדים סידור המדדים לפי מאפיינים ממשקי API. דוגמאות נוספות מופיעות בדוגמאות ל-Metrics API.
החזרת המספר הכולל של הקריאות שנשלחו לממשקי ה-API במשך חודש אחד
כדי לראות את המספר הכולל של הקריאות לכל ממשקי ה-API בארגון ובסביבה במשך חודש אחד, צריך להשתמש ב ממשק API של Get metrics:
curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password
תשובה לדוגמה:
{
"environments": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
"7.44944088E8"
]
}
],
"name": "prod"
}
],
...
}
החזרת מספר ההודעות הכולל לכל שרת proxy ל-API למשך יומיים
בדוגמה הזו מחזירים מדדים לגבי מספר הבקשות שהתקבלו בכל שרתי ה-proxy ל-API
בתקופה של יומיים. פרמטר השאילתה select מגדיר את פונקציית הצבירה sum של המדד
message_count במאפיין apiproxy. הדוח מחזיר את התפוקה של הודעת הבקשה
לגבי כל ממשקי ה-API של התנועה שהתקבלה בין תחילת 20 ביוני 2018 לסוף 21 ביוני 2018, ב
שעון UTC:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password
תשובה לדוגמה:
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1498003200000,
"value" : "1100.0"
} ]
} ],
"name" : "target-reroute"
} ],
"name" : "test"
} ]...
}
התגובה הזו מציינת שהתקבלו 1,100 הודעות על ידי שרת proxy אחד של API שנקרא 'יעד-שינוי מסלול' בסביבת הבדיקה שמתחילה ב-20 ביוני 2018 עד סוף 2018 21.06.2018.
כדי לקבל מדדים של מאפיינים אחרים, צריך לציין מאפיין אחר כפרמטר ה-URI. עבור
לדוגמה, אפשר לציין את המאפיין developer_app כדי לאחזר מדדים
של מפתחים. הקריאה הבאה ל-API מחזירה את התפוקה (הודעות שהתקבלו) מכל האפליקציות
לפרק הזמן שצוין:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:passwordתשובה לדוגמה:
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "886.0"
}
]
}
],
"name": "Test-App"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "6645.0"
}
]
}
],
"name": "johndoe_app"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "1109.0"
}
]
}
],
"name": "marys_app"
}
]...
}
מיון התוצאות לפי דירוג יחסי
פעמים רבות, כשיוצרים מדדים, רוצים לקבל תוצאות רק עבור קבוצת משנה מתוך הקבוצה הכוללת
. בדרך כלל צריך לקבל את התוצאות של '10 המובילים', לדוגמה, '10 המובילים האיטיים ביותר
ממשקי API, "10 האפליקציות הפעילות המובילות". אפשר לעשות זאת באמצעות פרמטר השאילתה topk
כחלק מהבקשה.
לדוגמה, אולי תרצו לדעת מיהם המפתחים המובילים שלכם, כאשר הם נמדדים לפי תפוקה, או של האומנים בעלי הביצועים הגרועים ביותר (כלומר ממשקי ה-API המטורגטים 'האיטיים ביותר') הם לפי זמן אחזור.
topk (כלומר ישויות 'k המובילות') מאפשר דיווח על הישויות המשויכות
עם הערך הגבוה ביותר עבור מדד נתון. כך אפשר לסנן מדדים לפי רשימה של
שמדגימות תנאי מסוים. לדוגמה, כדי למצוא את כתובת ה-URL של היעד,
שהכי נפוצות לשגיאות בשבוע האחרון, הפרמטר topk מצורף לבקשה,
עם הערך 1:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
-u email:password
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(is_error)",
"values": [
{
"timestamp": 1494201600000,
"value": "12077.0"
}
]
}
],
"name": "http://api.company.com"
}
]...
}
התוצאה של הבקשה הזו היא קבוצה של מדדים שמראים שכתובת ה-URL של היעד עם הכי הרבה באגים היא
http://api.company.com
אפשר גם להשתמש בפרמטר topk כדי למיין את ממשקי ה-API בעלי האיכות הגבוהה ביותר
תפוקה. הדוגמה הבאה מאחזרת מדדים מה-API בדירוג הגבוה ביותר, לפי ההגדרה הגבוהה ביותר
תפוקה בשבוע האחרון:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password
תשובה לדוגמה
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1494720000000,
"value": "5750.0"
},
{
"timestamp": 1494633600000,
"value": "5752.0"
},
{
"timestamp": 1494547200000,
"value": "5747.0"
},
{
"timestamp": 1494460800000,
"value": "5751.0"
},
{
"timestamp": 1494374400000,
"value": "5753.0"
},
{
"timestamp": 1494288000000,
"value": "5751.0"
},
{
"timestamp": 1494201600000,
"value": "5752.0"
}
]
}
],
"name": "testCache"
}
],
"name": "test"
}
]...
}
סינון התוצאות
כדי ברמת פירוט גבוהה יותר, אפשר לסנן את התוצאות כדי להגביל את הנתונים שמוחזרים. בזמן השימוש מסננים, אתם חייבים להשתמש במאפיינים בתור מאפייני סינון.
לדוגמה, נניח שאתם צריכים לאחזר את מספר השגיאות משירותים לקצה העורפי
מסונן לפי פועל ה-HTTP של הבקשה. המטרה שלכם היא לברר כמה בקשות POST ו-PUT
מייצרים שגיאות לכל שירות לקצה העורפי. כדי לעשות זאת, צריך להשתמש במאפיין
target_url עם המסנן request_verb:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password
דוגמה לתגובה:
{
"environments" : [
{
"dimensions" : [
{
"metrics" : [
{
"name" : "sum(is_error)",
"values" : [
{
"timestamp" : 1519516800000,
"value" : "1.0"
}
]
}
],
"name" : "testCache"
}
],
"name" : "test"
}
]...
}תוצאות בחלוקה לדפים
בסביבות ייצור, בקשות מסוימות ל-Edge analytics API מחזירות נתונים גדולים מאוד למשימות. כדי להקל על הצגה של קבוצות נתונים גדולות בהקשר של אפליקציה מבוססת-ממשק משתמש, ה-API תומך באופן טבעי בעימוד.
כדי לחלק את התוצאות לדפים, צריך להשתמש בפרמטרים של השאילתה offset ו-limit
יחד עם פרמטר המיון sortby כדי להבטיח סדר עקבי של
פריטים.
לדוגמה, סביר להניח שהבקשה הבאה תחזיר קבוצת נתונים גדולה, כי מאחזרת מדדים לכל השגיאות בכל ממשקי ה-API בסביבת המוצר בשבוע האחרון.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password
אם אפליקציה מבוססת ממשק המשתמש יכולה להציג באופן סביר 50 תוצאות בדף, תוכלו להגדיר את המגבלה
ל-50. מכיוון ש-0 נחשב לפריט הראשון, הקריאה הבאה מחזירה פריטים 0-49 בסדר יורד.
הזמנה (ברירת המחדל היא sort=DESC).
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password
ל'דף' השני של התוצאות, להשתמש בפרמטר שאילתת ההיסט, באופן הבא. שימו לב המגבלה וההיסט זהים. הסיבה לכך היא ש-0 נחשב לפריט הראשון. עם מגבלה של 50 ו- קיזוז של 0, מוחזרים פריטים בין 0 ל-49. עם קיזוז של 50, יוחזרו פריטים 50-99.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password