שימוש ב-Metrics API

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

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

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

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

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

מידע על Metrics API

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

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

לדוגמה, לגבי השבוע הקודם, אפשר להשתמש במאפיינים כדי לקבץ מדדים לפי מוצר API, שרת proxy ל-API וכתובת אימייל של מפתח (שיכולה להיות גם מזהה של קבוצת אפליקציות) כדי לקבל:
- מספר שגיאות המדיניות לכל מוצר 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.

הערה: מידע על משך שמירת הנתונים זמין בדף של תוכניות Apigee.

דוגמאות לקריאה ל-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 proxies במשך יומיים. פרמטר השאילתה 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.

הערה: חותמת הזמן, 1498003200000, היא בפורמט של חותמת זמן של מערכת Unix. יש באינטרנט הרבה כלים להמרת חותמות זמן של מערכת Unix שבעזרתם אפשר לפענח את חותמות הזמן האלה.

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

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

זוהי דוגמה לתשובה:
```
{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}
```
עימוד תוצאות

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

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

הערה: כשמחלקים את התוצאות לדפים, חשוב למיין אותן בצורה צפויה באמצעות פרמטר השאילתה sortby. בלי מיון, התוצאות מוחזרות בסדר לא צפוי, מה שמבטל את המטרה של חלוקה לעמודים.
הערך של sortby צריך להיות זהה לערך שמוגדר בפרמטר select של השאילתה. לדוגמה, אם select=sum(message_count), אז sortby=sum(message_count).

לדוגמה, סביר להניח שהבקשה הבאה תחזיר מערך נתונים גדול, כי היא מאחזרת מדדים של כל השגיאות בכל ממשקי ה-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"
```

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

מידע על Metrics API

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

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

ציון התקופה

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

מיון תוצאות לפי דירוג יחסי

סינון התוצאות

עימוד תוצאות

שימוש ב-Metrics API