אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע
Apigee Edge מתעד מגוון רחב של נתונים תפעוליים ועסקיים שזורמים דרך ממשקי API. המדדים שנגזרים מהנתונים האלה שימושיים למעקב תפעולי ולמעקב עסקי. בעזרת Edge API Analytics, תוכלו למשל לקבוע אילו ממשקי API פועלים בצורה טובה או גרועה, אילו מפתחים מספקים את התנועה בעלת הערך הגבוה ביותר ואילו אפליקציות גורמות לבעיות הכי רבות בשירותי ה-Backend שלכם.
כדי לגשת לנתוני המדדים האלה בקלות, Edge חושף RESTful API. אפשר להשתמש ב-Metrics API כשרוצים להפעיל אוטומטית פונקציות מסוימות של Analytics, כמו אחזור מדדים באופן תקופתי באמצעות סקריפט או לקוח אוטומציה. אפשר גם להשתמש ב-API כדי ליצור ויזואליזציות משלכם בצורה של ווידג'טים בהתאמה אישית שאפשר להטמיע בפורטלים או באפליקציות בהתאמה אישית.
מידע על השימוש ב-Analytics בממשק המשתמש של API Edge זמין במאמר סקירה כללית של API Analytics.
מידע על ממשקי API של מדדים
Edge מספק שני ממשקי API של מדדים:
Get metrics מחזירה מדדים של ארגון וסביבה במהלך פרק זמן מסוים, כמו שעה, יום או שבוע.
לדוגמה, אם רוצים לקבל את הנתונים הבאים לגבי השבוע הקודם:
- מספר השגיאות שקשורות למדיניות
- זמן התגובה הממוצע
- סך כל התנועה
קבלת מדדים מאורגנים לפי מאפיינים מחזירה מדדים לאורך תקופה עבור ארגון וסביבה grouped by dimension.
לדוגמה, בשבוע הקודם השתמשתם במאפיינים כדי לקבץ מדדים לפי מוצר API, שרת proxy ל-API וכתובת אימייל של מפתח, כדי לקבל:
- מספר שגיאות המדיניות לכל מוצר API
- זמן התגובה הממוצע לכל proxy ל-API
- נפח התנועה הכולל לכל כתובת אימייל של מפתח
Get metrics organized by dimensions API תומך בתכונות נוספות שלא נתמכות על ידי Get metrics API, כולל:
מידע על מכסות ל-Metrics API
Edge אוכף את המכסות הבאות על השיחות האלה. המכסה מבוססת על מערכת ה-Backend שמטפלת בקריאה:
- Postgres: 40 קריאות לדקה
- BigQuery: 12 קריאות לדקה
בודקים את אובייקט התגובה כדי לזהות את מערכת ה-Backend שמטפלת בשיחה.
כל אובייקט תגובה מכיל מאפיין 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 הוא שב-Get metrics מוחזרים מדדים גולמיים עבור הארגון והסביבה כולה, ואילו ב-Get metrics organized by dimensions אפשר לקבץ מדדים לפי סוגים שונים של ישויות, כמו מוצר API, מפתח ואפליקציה.
כתובת ה-URL של הבקשה ל-API של Get metrics היא:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/statsב-API Get metrics organized by dimensions
צריך לכלול משאב נוסף בכתובת ה-URL אחרי /stats שמציין את המאפיין הרצוי:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimensionלדוגמה, כדי לקבל מדדים שמקובצים לפי proxy ל-API, משתמשים בכתובת ה-URL הבאה כדי להפעיל את Management API:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxyציון המדדים שיוחזרו
גם ב-API של קבלת מדדים וגם ב-API של קבלת מדדים לפי מאפיינים, משתמשים בפרמטר השאילתה select כדי לציין את המדדים לאחזור, ופונקציית צבירה אופציונלית, בפורמט הבא:
?select=metric
או:
?select=aggFunction(metric)
כאשר:
- metric מציין את הנתונים שרוצים להחזיר. לדוגמה,
מספר בקשות ה-API, מספר הפעמים שהנתונים נלקחו מהמטמון או מספר שגיאות המדיניות. בטבלה metrics מפורט שם המדד שמשמש עם פרמטר השאילתה
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 Get metrics ו-Get metrics organized by dimensions. דוגמאות נוספות לשימוש ב-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 במשך יומיים
בדוגמה הזו, המערכת מחזירה מדדים לגבי מספר הבקשות שהתקבלו מכל פרוקסי ה-API במהלך יומיים. פרמטר השאילתה select מגדיר את פונקציית הצבירה sum למדד message_count במאפיין apiproxy. הדוח מחזיר את קצב העברת הנתונים של הודעות הבקשה לכל ממשקי ה-API עבור תנועת המשתמשים שהתקבלה בין תחילת התאריך 20/6/2018 לסוף התאריך 21/6/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 בשם target-reroute שפועל בסביבת הבדיקה בין תחילת התאריך 20 ביוני 2018 לסוף התאריך 21 ביוני 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 כחלק מהבקשה.
לדוגמה, יכול להיות שתרצו לדעת מי המפתחים המובילים שלכם, לפי נפח העברת הנתונים, או מי המפתחים עם הביצועים הכי נמוכים (כלומר, 'האיטיים ביותר') לפי זמן האחזור.
הפונקציה 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
יוצרות שגיאות לכל שירות backend. כדי לעשות את זה, משתמשים במימד 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
כדי להציג את 'העמוד' השני של התוצאות, משתמשים בפרמטר השאילתה offset, באופן הבא. שימו לב שהערכים של limit ו-offset זהים. הסיבה לכך היא שהפריט הראשון נספר כ-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