שימוש ב-Metrics API

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

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

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

כדי לגשת לנתוני המדדים האלה בקלות, אפשר להשתמש בממשק Metrics 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 כחלק מהבקשה.

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

    הפרמטר 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 יוצרות שגיאות לכל שירות קצה עורפי. כדי לעשות זאת, משתמשים במאפיין 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"