از API های متریک استفاده کنید

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

Apigee Edge طیف گسترده ای از داده های عملیاتی و تجاری را که در میان API ها جریان دارند، ثبت می کند. معیارهای به دست آمده از این داده ها برای نظارت عملیاتی و نظارت تجاری مفید هستند. برای مثال، با استفاده از Edge API Analytics، می‌توانید تعیین کنید که کدام APIها خوب یا ضعیف عمل می‌کنند، کدام توسعه‌دهندگان بیشترین ترافیک را ارائه می‌دهند، و کدام برنامه‌ها بیشترین مشکلات را برای خدمات باطن شما ایجاد می‌کنند.

برای کمک به دسترسی آسان به این داده‌های معیارها، Edge یک API RESTful را در معرض نمایش قرار می‌دهد. زمانی که نیاز به خودکارسازی عملکردهای خاص Analytics، مانند بازیابی دوره‌ای معیارها با استفاده از یک کلاینت یا اسکریپت اتوماسیون دارید، می‌توانید از API متریک استفاده کنید. همچنین می‌توانید از API برای ایجاد تجسم‌های خود در قالب ویجت‌های سفارشی استفاده کنید که می‌توانید در پورتال‌ها یا برنامه‌های سفارشی جاسازی کنید.

برای یادگیری نحوه استفاده از Analytics در رابط کاربری مدیریت API Edge به نمای کلی API Analytics مراجعه کنید.

درباره APIهای متریک

Edge دو API معیار را ارائه می دهد:

• Get Metrics معیارهایی را برای یک سازمان و محیط در یک دوره زمانی مشخص مانند یک ساعت، روز یا هفته برمی‌گرداند.

  به عنوان مثال، برای هفته قبل که می خواهید به دست آورید:

  • تعداد خطاهای خط مشی
  • میانگین زمان پاسخگویی
  • کل ترافیک

• دریافت معیارهای سازماندهی شده بر اساس ابعاد، معیارها را در یک دوره زمانی برای یک سازمان و محیط گروه بندی شده بر اساس بعد برمی گرداند.

  برای مثال، برای هفته قبل از ابعاد برای گروه‌بندی معیارها بر اساس محصول API، پروکسی API و ایمیل برنامه‌نویس استفاده می‌کنید تا به دست آورید:

  • تعداد خطاهای خط مشی در هر محصول API
  • میانگین زمان پاسخگویی به ازای هر پروکسی API
  • کل ترافیک به ازای هر ایمیل توسعه دهنده

  Get Metrics Organized by dimensions API از ویژگی‌های اضافی پشتیبانی می‌کند که توسط Get Metrics API پشتیبانی نمی‌شود، از جمله:

  • مرتب سازی
  • فیلتر کردن
  • صفحه بندی

درباره سهمیه های API متریک

Edge سهمیه های زیر را در این تماس ها اعمال می کند. سهمیه بر اساس سیستم پشتیبان است که تماس را مدیریت می کند:

• 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 سازماندهی شده بر اساس ابعاد به شما امکان می دهد معیارها را بر اساس انواع مختلف موجودیت، مانند محصول API، توسعه دهنده و برنامه گروه بندی کنید.

URL درخواست برای Get Metrics API این است:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats

برای دریافت معیارهای سازمان‌دهی‌شده بر اساس ابعاد API، یک منبع اضافی به نشانی اینترنتی پس از /stats اضافه می‌کنید که بعد مورد نظر را مشخص می‌کند:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension

به عنوان مثال، برای گروه بندی معیارها بر اساس پروکسی API، از URL زیر برای فراخوانی API مدیریت استفاده کنید:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy

تعیین معیارهای بازگشت

برای معیارهای Get و Get Metrics سازماندهی شده بر اساس ابعاد API، از پارامتر پرس و جو select برای تعیین معیارهای بازیابی و یک تابع تجمیع اختیاری به شکل زیر استفاده می کنید:

?select=metric

یا:

?select=aggFunction(metric)

کجا:

• متریک داده هایی را که می خواهید برگردانید را مشخص می کند. به عنوان مثال، تعداد درخواست های API، بازدیدهای حافظه پنهان یا خطاهای خط مشی. معیارهای جدولی را ببینید که نام متریک را برای استفاده با پارامتر select کوئری مشخص می کند.

• aggFunction تابع تجمیع اختیاری را که در برابر متریک اجرا می شود، مشخص می کند. به عنوان مثال، می توانید از توابع تجمع زیر با متریک تأخیر پردازش استفاده کنید:

  • avg : متوسط ​​تأخیر پردازش را برمی‌گرداند.
  • min : حداقل تأخیر پردازش را برمی‌گرداند.
  • max : حداکثر تأخیر پردازش را برمی‌گرداند.
  • sum : مجموع تمام تاخیرهای پردازش را برمی گرداند.

  همه معیارها از همه توابع تجمع پشتیبانی نمی کنند. مستندات مربوط به متریک ها حاوی جدولی است که نام متریک و تابع ( sum ، avg ، min ، max ) پشتیبانی شده توسط متریک را مشخص می کند.

به عنوان مثال، برای برگرداندن میانگین تعداد تراکنش ها، به معنای درخواست های پروکسی API، در هر ثانیه:

?select=tps

توجه داشته باشید که این مثال به تابع تجمیع نیاز ندارد. مثال بعدی از یک تابع تجمع برای برگرداندن مجموع بازدیدهای کش استفاده می کند:

?select=sum(cache_hit)

می‌توانید چندین معیار را برای یک تماس API برگردانید. برای دریافت معیارهای مجموع خطاهای خط‌مشی و اندازه متوسط ​​درخواست، پارامتر پرس و جو select را با استفاده از فهرستی از معیارهای جدا شده با کاما تنظیم کنید:

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

تعیین بازه زمانی

Metrics API داده‌ها را برای یک دوره زمانی مشخص برمی‌گرداند. از پارامتر query 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

این بخش شامل نمونه هایی با استفاده از معیارهای Get و معیارهای Get سازماندهی شده بر اساس ابعاد API است. برای مثال‌های بیشتر به مثال‌های Metrics API مراجعه کنید.

تعداد کل تماس های برقرار شده با API های خود را برای یک ماه برگردانید

برای مشاهده تعداد کل تماس‌های برقرار شده با همه APIهای سازمان و محیط خود به مدت یک ماه، از Get Metrics API استفاده کنید:

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"
    }
  ],
...
}

تعداد کل پیام ها را به ازای هر پروکسی API برای دو روز برگردانید

در این مثال، شما معیارهایی را برای تعداد درخواست‌های دریافت شده توسط همه پراکسی‌های API در یک دوره دو روزه برمی‌گردانید. پارامتر پرس و جو select sum تابع مجموع را برای متریک message_count در آپی apiproxy تعریف می کند. این گزارش خروجی پیام درخواست را برای همه APIها برای ترافیک دریافتی بین آغاز ۲۰۱۸/۶/۲۰ و پایان ۲۰۱۸/۶/۲۱ به وقت 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"
  } ]...
}

این پاسخ نشان می دهد که 1100 پیام توسط یک پروکسی API به نام "target-reroute" در حال اجرا در محیط آزمایشی بین شروع 2018/6/20 تا پایان 2018/6/21 دریافت شده است.

برای دریافت معیارهای سایر ابعاد، بعد دیگری را به عنوان پارامتر 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 query به عنوان بخشی از درخواست انجام دهید.

به عنوان مثال، ممکن است علاقه مند باشید که بدانید توسعه دهندگان برتر شما چه کسانی هستند، بر اساس توان عملیاتی اندازه گیری می شود، یا بدترین عملکرد شما (یعنی «آهسته ترین») 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"
    }
  ]...
}

صفحه بندی نتایج

در محیط های تولیدی، برخی از درخواست ها به API تجزیه و تحلیل Edge مجموعه داده های بسیار بزرگی را برمی گرداند. برای سهولت نمایش مجموعه داده های بزرگ در زمینه یک برنامه کاربردی مبتنی بر UI، 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

اگر برنامه مبتنی بر UI شما می تواند به طور منطقی 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 به شرح زیر استفاده کنید. توجه داشته باشید که حد و افست یکسان هستند. به این دلیل که 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