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

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

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

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

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

درباره APIهای معیارها

Edge دو API برای اندازه‌گیری ارائه می‌دهد:

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

  برای مثال، برای هفته قبل می‌خواهید موارد زیر را بدست آورید:

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

• «معیارها را بر اساس ابعاد سازماندهی کنید» (Get metrics organize by dimensions) معیارها را در یک دوره زمانی برای یک سازمان و محیط گروه‌بندی شده بر اساس ابعاد، برمی‌گرداند.

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

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

  API مربوط به Get metrics که بر اساس ابعاد سازماندهی شده است، از ویژگی‌های اضافی پشتیبانی می‌کند که توسط Get metrics API پشتیبانی نمی‌شوند، از جمله:

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

درباره سهمیه‌های API معیارها

اج سهمیه‌های زیر را برای این تماس‌ها اعمال می‌کند. این سهمیه بر اساس سیستم بک‌اندی است که تماس را مدیریت می‌کند:

• پستگرس : ۴۰ تماس در دقیقه
• بیگ‌کوئری : ۱۲ تماس در دقیقه

با بررسی شیء پاسخ، سیستم 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، توسعه‌دهنده و برنامه، گروه‌بندی کنید.

آدرس درخواست برای API مربوط به Get metrics عبارت است از:

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

برای API مربوط به Get metrics organize by dimensions ، شما یک منبع اضافی به URL بعد از /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

مشخص کردن معیارهای بازگشتی

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

?select=metric

یا:

?select=aggFunction(metric)

کجا:

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

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

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

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

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

?select=tps

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

?select=sum(cache_hit)

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

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

مشخص کردن بازه زمانی

API مربوط به معیارها، داده‌ها را برای یک دوره زمانی مشخص برمی‌گرداند. از پارامتر query timeRange برای مشخص کردن دوره زمانی، به شکل زیر استفاده کنید:

?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

به علامت %20 قبل از HH:MM توجه کنید. پارامتر timeRange به یک کاراکتر فاصله (space) کدگذاری شده توسط URL قبل از HH:MM یا یک کاراکتر + نیاز دارد، مانند: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM .

برای مثال:

?timeRange=03/01/2018%2000:00~03/30/2018%2023: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های ابعاد است. برای مثال‌های بیشتر به مثال‌های API Metrics مراجعه کنید.

تعداد کل فراخوانی‌های انجام‌شده با 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"
    }
  ],
...
}

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

در این مثال، شما معیارهایی را برای تعداد درخواست‌های دریافتی توسط همه پروکسی‌های API در یک دوره دو روزه برمی‌گردانید. پارامتر query 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"
  } ]...
}

این پاسخ نشان می‌دهد که ۱۱۰۰ پیام توسط یک پروکسی API به نام 'target-reroute' که در محیط آزمایشی بین شروع ۲۰/۶/۲۰۱۸ و پایان ۲۱/۶/۲۰۱۸ اجرا می‌شد، دریافت شده است.

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

برای مثال، شاید برایتان جالب باشد که بدانید توسعه‌دهندگان برتر شما، از نظر توان عملیاتی، چه کسانی هستند، یا از نظر تأخیر، بدترین عملکردها (یعنی «کندترین») در 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، مجموعه داده‌های بسیار بزرگی را برمی‌گردانند. برای آسان‌تر کردن نمایش مجموعه داده‌های بزرگ در چارچوب یک برنامه مبتنی بر رابط کاربری، 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

اگر برنامه مبتنی بر رابط کاربری شما می‌تواند به طور منطقی ۵۰ نتیجه را در هر صفحه نمایش دهد، می‌توانید این محدودیت را روی ۵۰ تنظیم کنید. از آنجایی که ۰ به عنوان اولین آیتم شمارش می‌شود، فراخوانی زیر آیتم‌های ۰ تا ۴۹ را به ترتیب نزولی برمی‌گرداند ( 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 به عنوان اولین مورد شمارش می‌شود. با limit برابر با 50 و offset برابر با 0، موارد 0 تا 49 برگردانده می‌شوند. با offset برابر با 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