שימוש ב-Metrics API

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

במאמר סקירה כללית של Apigee Analytics מוסבר איך להשתמש ב-Analytics בממשק המשתמש של Apigee.

מידע על Metrics API

יש שתי דרכים להשתמש ב-API של המדדים:

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

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

    • מספר השגיאות שקשורות למדיניות
    • זמן תגובה ממוצע
    • סך כל התנועה

  • קבלת מדדים מאורגנים לפי מאפיין לאורך תקופה מסוימת עבור ארגון וסביבה.

    לדוגמה, לגבי השבוע הקודם, אפשר להשתמש במאפיינים כדי לקבץ מדדים לפי מוצר API, שרת proxy ל-API, ודואר אלקטרוני של מפתח (שיכול להיות גם מזהה AppGroup) כדי לקבל:

    • מספר שגיאות המדיניות לכל מוצר API
    • זמן תגובה ממוצע לכל proxy ל-API
    • סך התנועה לכל אימייל של מפתח

    כדי לנהל את התוצאות שמוחזרות, Metrics API תומך בתכונות הבאות:

    מידע נוסף זמין במאמר הפניה למדדים של API.

    תחילת השימוש ב-Metrics API

    כתובת ה-URL של הבקשה ל-Metrics API היא:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]

    לדוגמה, כדי לקבל מדדים שמקובצים לפי proxy ל-API, משתמשים בכתובת ה-URL הבאה כדי להפעיל את Apigee API:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00

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

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00

    ציון המדדים שיוחזרו

    משתמשים בפרמטר השאילתה select כדי לציין את המדדים לאחזור, ופונקציית צבירה אופציונלית, באופן הבא:

    ?select=metric

    או:

    ?select=aggFunction(metric)

    כאשר:

    • ‫metric מציין את הנתונים שרוצים להחזיר. לדוגמה, מספר בקשות ה-API, מספר הפעמים שהנתונים נלקחו מהמטמון או מספר שגיאות המדיניות. בטבלה metrics מפורט שם המדד שמשמש עם פרמטר השאילתה select.

    • ‫aggFunction מציין את פונקציית הצבירה האופציונלית שמופעלת על המדד. לדוגמה, אפשר להשתמש בפונקציות הצבירה הבאות עם מדד זמן האחזור של העיבוד:

      • ‫avg: מחזירה את זמן האחזור הממוצע של העיבוד.
      • ‫min: מחזירה את זמן האחזור המינימלי של העיבוד.
      • ‫max: מחזירה את זמן האחזור המקסימלי של העיבוד.
      • ‫sum: מחזירה את סכום זמני האחזור של כל העיבודים.
      • ‫p50: מחזירה את האחוזון ה-50 של זמני האחזור של העיבוד, שמחושב באמצעות percentile(latency_metric,50)&aggTable=agg_percentile.
      • ‫p95: מחזירה את האחוזון ה-95 של זמני האחזור של העיבוד, שמחושב באמצעות percentile(latency_metric,95)&aggTable=agg_percentile.
      • ‫p99: מחזירה את האחוזון ה-99 של זמני האחזור של העיבוד, שמחושבים באמצעות percentile(latency_metric,99)&aggTable=agg_percentile.

      האפליקציה latency_metric יכולה להיות:

      • total_response_time
      • target_response_time
      • response_processing_latency
      • request_processing_latency

      לא כל המדדים תומכים בכל פונקציות הצבירה. במסמכי התיעוד בנושא מדדים יש טבלה שמצוינים בה שם המדד והפונקציות (sum, ‏ avg, ‏ min, ‏ max) שהמדד תומך בהן.

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

    ?select=tps

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

    ?select=sum(cache_hit)

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

    ?select=sum(policy_error),avg(request_size)

    ציון תקופת הזמן

    ממשק ה-API של המדדים מחזיר נתונים לתקופה מסוימת. משתמשים בפרמטר השאילתה timeRange (עד 6 חודשים) כדי לציין את תקופת הזמן, בפורמט:

    ?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.

    דוגמאות לקריאה ל-Metrics API

    בקטע הזה מופיעות דוגמאות לשימוש ב-Metrics API. דוגמאות נוספות לשימוש ב-Metrics API

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

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

    curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)\
&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    ‫$TOKEN מוגדר כאסימון הגישה מסוג OAuth 2.0, כפי שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. מידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו מופיע במאמר שימוש ב-curl. תיאור של משתני הסביבה שבהם אפשר להשתמש מופיע במאמר בנושא הגדרת משתני סביבה לבקשות API של Apigee.

    זוהי דוגמה לתשובה:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?\
select=sum(message_count)\
&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    ‫$TOKEN מוגדר כאסימון הגישה מסוג OAuth 2.0, כפי שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. מידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו מופיע במאמר שימוש ב-curl. תיאור של משתני הסביבה שבהם אפשר להשתמש מופיע במאמר בנושא הגדרת משתני סביבה לבקשות API של Apigee.

    זוהי דוגמה לתשובה:

    {
  "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/6/2018 לסוף התאריך 21/6/2018.

    כדי לקבל מדדים למאפיינים אחרים, מציינים מאפיין אחר כפרמטר URI. לדוגמה, אפשר לציין את מאפיין developer_app כדי לאחזר מדדים של אפליקציות למפתחים. הקריאה הבאה ל-API מחזירה את התפוקה הכוללת (הודעות שהתקבלו) מכל האפליקציות במרווח הזמן שצוין:

    curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?\
select=sum(message_count)\
&timeRange=06/20/2018%2000:00~06/21/2018%2023:59\
&timeUnit=day" \
  -H "Authorization: Bearer $TOKEN"

    זוהי דוגמה לתשובה:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    ‫$TOKEN מוגדר כאסימון הגישה מסוג OAuth 2.0, כפי שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. מידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו מופיע במאמר שימוש ב-curl. תיאור של משתני הסביבה שבהם אפשר להשתמש מופיע במאמר בנושא הגדרת משתני סביבה לבקשות API של Apigee.

    זוהי דוגמה לתשובה:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    זוהי דוגמה לתשובה:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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')" \
  -H "Authorization: Bearer $TOKEN"

    ‫$TOKEN מוגדר כאסימון הגישה מסוג OAuth 2.0, כפי שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. מידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו מופיע במאמר שימוש ב-curl. תיאור של משתני הסביבה שבהם אפשר להשתמש מופיע במאמר בנושא הגדרת משתני סביבה לבקשות API של Apigee.

    זוהי דוגמה לתשובה:

    {
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

    עימוד תוצאות

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

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

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

    curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?\
select=sum(is_error)\
&timeRange=05/08/2018%2000:00~05/15/2018%2000:00\
&timeUnit=week\
&sortby=sum(is_error)" \
  -H "Authorization: Bearer $TOKEN"

    ‫$TOKEN מוגדר כאסימון הגישה מסוג OAuth 2.0, כפי שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. מידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו מופיע במאמר שימוש ב-curl. תיאור של משתני הסביבה שבהם אפשר להשתמש מופיע במאמר בנושא הגדרת משתני סביבה לבקשות API של Apigee.

    אם אפליקציה שמבוססת על ממשק משתמש יכולה להציג באופן סביר 50 תוצאות בכל דף, אפשר להגדיר את המגבלה ל-50. הפריט הראשון נספר כ-0, ולכן הקריאה הבאה מחזירה את הפריטים 0-49 בסדר יורד (sort=DESC הוא ברירת המחדל).

    curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    כדי להציג את 'הדף' השני של התוצאות, משתמשים בפרמטר השאילתה offset, באופן הבא. שימו לב שהערכים של limit ו-offset זהים. הסיבה לכך היא שהפריט הראשון נספר כ-0. עם מגבלה של 50 והיסט של 0, הפריטים 0-49 מוחזרים. אם ההיסט הוא 50, הפריטים 50 עד 99 יוחזרו.

    curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"