استفاده از میاناهای برنامه‌سازی کاربردی سنجه‌ها

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

‫Apigee Edge انواع مختلفی از داده‌های عملیاتی و کسب‌وکار را که در سراسر میاناهای برنامه‌سازی کاربردی جریان دارد ضبط می‌کند. سنجه‌های برگرفته از این داده‌ها برای پایش عملیاتی و پایش کسب‌وکار مفید هستند. بااستفاده از «تحلیل Edge API»، می‌توانید، برای مثال، تعیین کنید کدام میاناهای برنامه‌سازی کاربردی عملکرد خوب یا ضعیفی دارند، کدام توسعه‌دهندگان بالاترین مقدار ترافیک را ارائه می‌دهند، و کدام برنامه‌ها بیشترین مشکلات را برای سرویس‌های زیرین شما ایجاد می‌کنند.

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

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

درباره میاناهای برنامه‌سازی کاربردی سنجه‌ها

‫Edge دو میانای برنامه‌سازی کاربردی سنجه ارائه می‌دهد:

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

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

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

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

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

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

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

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

درباره سهمیه‌های API سنجه‌ها

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

• Postgres: ۴۰ تماس در دقیقه
• BigQuery: ۱۲ تماس در دقیقه

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

نشانی وب درخواست برای میانای برنامه‌سازی کاربردی دریافت سنجه‌ها به‌صورت زیر است:

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

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

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

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

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

مشخص کردن سنجه‌هایی که باید برگردانده شود

برای هر دو میانای برنامه‌سازی کاربردی دریافت سنجه‌ها و میانای برنامه‌سازی کاربردی دریافت سنجه‌های سازمان‌دهی‌شده براساس ابعاد از پارامتر پُرسمان 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)

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

«میانای برنامه‌سازی کاربردی» سنجه‌ها داده‌های مربوط به دوره زمانی مشخصی را برمی‌گرداند. از پارامتر پُرسمان timeRange برای مشخص کردن دوره زمانی، به این شکل استفاده کنید:

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

‫%20 را قبل‌از HH:MM متوجه شوید. پارامتر timeRange به نویسه فاصله کدبندی‌شده با نشانی وب قبل‌از 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 با , از هم جدا می‌شوند.

فراخوانی‌های نمونه میانای برنامه‌سازی کاربردی

این بخش شامل نمونه‌هایی از استفاده از دریافت سنجه‌ها و دریافت سنجه‌های سازمان‌دهی‌شده براساس ابعاد میاناهای برنامه‌سازی کاربردی است. برای نمونه‌های بیشتر، نمونه‌های 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 تعریف می‌کند. این گزارش توان عملیاتی پیام درخواست را برای همه میاناهای برنامه‌سازی کاربردی برای ترافیک دریافتی بین ابتدای ۲۰/‏۰۶/‏۲۰۱۸ و انتهای ۲۱/‏۰۶/‏۲۰۱۸، در زمان هماهنگ جهانی برمی‌گرداند:

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» که در محیط آزمایش اجرا می‌شود ۱۱۰۰ پیام دریافت کرده است.

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

درحال مرتب کردن نتایج براساس رتبه‌بندی نسبی

در بسیاری از موارد هنگام دریافت سنجه‌ها، فقط می‌خواهید نتایج را برای زیرمجموعه‌ای از مجموعه کامل داده‌ها دریافت کنید. معمولاً باید نتایج مربوط به «۱۰ مورد برتر» را دریافت کنید، برای مثال، «۱۰ مورد برتر از کندترین میاناهای برنامه‌سازی کاربردی»، «۱۰ مورد برتر از فعال‌ترین برنامه‌ها». می‌توانید این کار را بااستفاده از پارامتر پُرسمان topk به‌عنوان بخشی از درخواست انجام دهید.

برای مثال، ممکن است علاقه‌مند باشید بدانید توسعه‌دهندگان برتر شما چه کسانی هستند، که براساس توان عملیاتی اندازه‌گیری می‌شوند، یا بدترین عملکردها (یعنی «میاناهای برنامه‌سازی کاربردی هدف» (top slowest) براساس تأخیر است.

‫topk (به‌معنای نهادهای «برتر k») امکان گزارش‌دهی درباره نهادهای مرتبط با بالاترین مقدار برای یک سنجه معین را فراهم می‌کند. این کار به شما امکان می‌دهد سنجه‌ها را برای فهرستی از نهادهایی که شرایط خاصی را نشان می‌دهند فیلتر کنید. برای مثال، برای اینکه ببینید کدام نشانی وب مقصد در هفته گذشته بیشترین خطا را داشته است، پارامتر 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"
        }
      ]...
}

نتیجه این درخواست مجموعه‌ای از سنجه‌ها است که نشان می‌دهد پرباگ‌ترین نشانی وب هدف http://api.company.com است.

همچنین می‌توانید از پارامتر topk برای مرتب کردن براساس میاناهای برنامه‌سازی کاربردی که بیشترین گذردهی را دارند استفاده کنید. مثال زیر سنجه‌های مربوط به 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"
    }
  ]...
}

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

در محیط‌های تولید، برخی‌از درخواست‌های Edge analytics API مجموعه‌های داده بسیار بزرگی را برمی‌گردانند. برای اینکه نمایش مجموعه‌های داده بزرگ در زمینه یک برنامه مبتنی بر میانای کاربری آسان شود، میانای برنامه‌سازی کاربردی به‌طور بومی از صفحه‌بندی پشتیبانی می‌کند.

برای صفحه‌بندی نتایج، از پارامترهای پُرسمان offset و limit، همراه با پارامتر مرتب‌سازی sortby استفاده کنید تا ترتیب یکسانی برای موارد تضمین شود.

برای مثال، درخواست زیر احتمالاً مجموعه داده بزرگی را برمی‌گرداند، زیرا سنجه‌های مربوط به همه خطاهای همه «میاناهای برنامه‌سازی کاربردی» در محیط محصول را برای هفته گذشته بازیابی می‌کند.

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

برای «صفحه» دوم نتایج، از پارامتر پُرسمان افست به‌صورت زیر استفاده کنید. توجه داشته باشید که حد و جبران یکسان هستند. به‌این دلیل که ۰ به‌عنوان اولین مورد درنظر گرفته می‌شود. با محدودیت ۵۰ و انحراف ۰، موارد ۰ تا ۴۹ برگردانده می‌شوند. با انحرافی برابر با ۵۰، موارد ۵۰ تا ۹۹ برگردانده می‌شوند.

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