استفاده از API گزارش‌های سفارشی غیرهم‌زمان

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

Edge Analytics مجموعه‌ای غنی از داشبوردهای تعاملی، تولیدکنندگان گزارش سفارشی، و قابلیت‌های مرتبط را ارائه می‌دهد. بااین‌حال، این ویژگی‌ها تعاملی هستند: شما درخواست API یا رابط کاربری ارسال می‌کنید و درخواست تا زمانی که سرور تجزیه‌وتحلیل پاسخ دهد مسدود می‌شود.

بااین‌حال، اگر درخواست‌های تجزیه‌وتحلیل بیش‌ازحد طول بکشند، ممکن است زمان آن‌ها به‌پایان برسد. اگر درخواست پُرسمانی نیاز به پردازش مقدار زیادی داده داشته باشد (برای مثال، صدها گیگابایت)، ممکن است به‌دلیل اتمام زمان با خطا مواجه شود.

پردازش پرسمان ناهمزمان به شما امکان می‌دهد مجموعه‌های داده بسیار بزرگ را پُرسمان کنید و نتایج را در زمانی دیگر بازیابی کنید. وقتی متوجه شدید که پُرسمان‌های تعاملی‌تان زمان‌بَر است، می‌توانید از پُرسمان آفلاین استفاده کنید. برخی‌از موقعیت‌هایی که پردازش پُرسمان ناهم‌زمان می‌تواند جایگزین خوبی باشد عبارت‌اند از:

• تجزیه‌وتحلیل و ایجاد گزارش‌هایی که بازه‌های زمانی طولانی را دربرمی‌گیرند.
• تجزیه‌وتحلیل داده‌ها با ابعاد گروه‌بندی متنوع و محدودیت‌های دیگری که به پیچیدگی پُرسمان می‌افزایند.
• مدیریت کردن پُرسمان‌ها وقتی متوجه می‌شوید حجم داده برای برخی‌از کاربران یا سازمان‌ها به‌طور قابل‌توجهی افزایش یافته است.

این سند نحوه شروع کردن پُرسمان‌های ناهم‌زمان را بااستفاده از API توضیح می‌دهد. همچنین می‌توانید از واسط کاربر، همان‌طور که در اجرای گزارش سفارشی توضیح داده شده است، استفاده کنید.

مقایسه API گزارش‌ها با رابط کاربری

ایجاد و مدیریت گزارش‌های سفارشی نحوه استفاده از واسط کاربر Edge برای ایجاد و اجرای گزارش‌های سفارشی را توضیح می‌دهد. می‌توانید آن گزارش‌ها را به‌صورت هم‌زمان یا ناهم‌زمان اجرا کنید.

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

تفاوت‌های عمده بین گزارش‌های تولیدشده در رابط کاربری و در API این است که گزارش‌های تولیدشده با API به‌جای گزارش تصویری نمایش‌داده‌شده در رابط کاربری، در فایل‌های CSV یا JSON (محدودشده با خط جدید) نوشته می‌شوند.

محدودیت‌ها در Apigee hybrid

Apigee hybrid حد مجاز ۳۰ مگابایت را برای مجموعه داده‌های نتیجه اعمال می‌کند.

نحوه ایجاد پُرسمان تحلیلی غیرهم‌زمان

شما در سه مرحله پُرسمان‌های تجزیه‌وتحلیل ناهم‌زمان می‌سازید:

1. پُرسمان را ارسال کنید.

2. وضعیت پُرسمان را دریافت کنید.

3. نتایج پُرسمان را بازیابی کنید.

مرحله ۱. ارسال پُرسمان

باید درخواست POST به API /queries ارسال کنید. این «میانای برنامه‌سازی کاربردی» به Edge می‌گوید درخواستتان را در پس‌زمینه پردازش کند. اگر ارسال پُرسمان موفقیت‌آمیز باشد، میانای برنامه کاربردی وضعیت 201 و شناسه‌ای را برمی‌گرداند که از آن برای ارجاع به پُرسمان در مراحل بعدی استفاده خواهید کرد.

برای مثال:

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

بدنه درخواست شرحی از پُرسمان در قالب JSON است. در بدنه JSON، سنجه‌ها، ابعاد، و فیلترهایی را که گزارش را تعریف می‌کنند مشخص کنید.

در زیر نمونه‌ای از فایل json-query-file نشان داده شده است:

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

برای شرح کامل دستورگان متن درخواست، درباره متن درخواست در زیر را ببینید.

پاسخ نمونه:

توجه داشته باشید که شناسه پُرسمان 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd در پاسخ گنجانده شده است. علاوه‌بر وضعیت HTTP 201، state از enqueued به این معنی است که درخواست موفقیت‌آمیز بوده است.

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

مرحله ۲. دریافت وضعیت پُرسمان

برای درخواست وضعیت پُرسمان، تماس GET برقرار کنید. شناسه پُرسمانی را که از تماس POST برگردانده شده است ارائه می‌کنید. برای مثال:

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

پاسخ‌های نمونه:

اگر پُرسمان هنوز درحال انجام باشد، پاسخی مانند این دریافت خواهید کرد که در آن state برابر با running است:

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

پس‌از اینکه پُرسمان باموفقیت تکمیل شد، پاسخی مانند این خواهید دید که در آن state روی completed تنظیم شده است:

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

مرحله ۳. بازیابی نتایج پُرسمان

پس‌از اینکه وضعیت پُرسمان completed شد، می‌توانید از get results API برای بازیابی نتایج استفاده کنید، که در آن شناسه پُرسمان دوباره 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd است.

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

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

• اگر از cURL استفاده می‌کنید، می‌توانید از گزینه‌های -O -J، همان‌طور که در بالا نشان داده شده است، استفاده کنید.

• اگر از Postman استفاده می‌کنید، باید دکمه ذخیره و بارگیری را انتخاب کنید. در این مورد، فایل zip به‌نام response بارگیری می‌شود.

• اگر از مرورگر Chrome استفاده می‌کنید، بارگیری به‌طور خودکار پذیرفته می‌شود.

اگر درخواست موفقیت‌آمیز باشد و مجموعه نتایج غیرصفر وجود داشته باشد، نتیجه به‌صورت فایل JSON فشرده (محدودشده با خط جدید) در کلاینت بارگیری می‌شود. نام فایل بارگیری‌شده این خواهد بود:

OfflineQueryResult-<query-id>.zip

برای مثال:

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

فایل zip حاوی فایل بایگانی .gz از نتایج JSON است. برای دسترسی به فایل JSON، فایل بارگیری‌شده را از حالت فشرده خارج کنید، سپس از دستور gzip برای استخراج فایل JSON استفاده کنید:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

درباره متن درخواست

این بخش هریک از پارامترهایی را که می‌توانید در بدنه درخواست JSON برای پُرسمان استفاده کنید شرح می‌دهد. برای جزئیات مربوط به سنجه‌ها و ابعادی که می‌توانید در پُرسمان خود استفاده کنید، به مرجع Analytics مراجعه کنید.

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

نحو عبارت فیلتر

این بخش مرجع نشانگرهایی را که می‌توانید برای ساختن عبارت‌های فیلتر در بدنه درخواست استفاده کنید شرح می‌دهد. برای مثال، عبارت زیر از نشان «ge» (بزرگ‌تر یا مساوی) استفاده می‌کند:

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

محدودیت‌ها و پیش‌فرض‌ها

در زیر فهرستی از محدودیت‌ها و پیش‌فرض‌های ویژگی پردازش پرسمان ناهم‌زمان آورده شده است.

درباره نتایج پُرسمان

در زیر نمونه‌ای از نتیجه در قالب JSON آمده است. برونداد شامل ردیف‌های JSON است که با یک جداکننده خط جدید از هم جدا شده‌اند:

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

تا زمان انقضای داده‌ها در مخزن می‌توانید نتایج را از نشانی وب واکشی کنید. محدودیت‌ها و پیش‌فرض‌ها را ببینید.

مثال‌ها

مثال ۱: مجموع تعداد پیام‌ها

پرسش برای مجموع تعداد پیام‌ها در ۶۰ دقیقه گذشته.

پُرسمان

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

متن درخواست از last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

مثال ۲: محدوده زمانی سفارشی

بااستفاده از محدوده زمانی سفارشی پُرسمان کنید.

پُرسمان

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

درخواست بدنه از last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

مثال ۳: تراکنش در دقیقه

پرسش درباره سنجه تراکنش در دقیقه (tpm).

پُرسمان

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

درخواست بدنه از tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

نتیجه نمونه

گزیده فایل نتایج:

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

مثال ۴: استفاده از عبارت فیلتر

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

پُرسمان

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

متن درخواست از filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

مثال ۵: عبور دادن عبارت در پارامتر سنجه‌ها

پُرسمان با عبارتی که به‌عنوان بخشی از پارامتر سنجه‌ها ارسال می‌شود. فقط می‌توانید از عبارت‌های ساده یک‌عملگری استفاده کنید.

پُرسمان

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

متن درخواست از metricsExpression.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

نحوه ایجاد یک پرسمان گزارش درآمدزایی غیرهمزمان

بااستفاده از مراحل شرح‌داده‌شده در این بخش، می‌توانید همه تراکنش‌های موفق درآمدزایی را در یک محدوده زمانی معین برای مجموعه خاصی از معیارها ضبط کنید.

همانند پُرسمان‌های تجزیه‌وتحلیل ناهمزمان، پُرسمان‌های گزارش درآمدزایی ناهمزمان را در سه مرحله انجام می‌دهید: (۱) ارسال پُرسمان، (۲) دریافت وضعیت پُرسمان، و (۳) بازیابی نتایج پُرسمان.

مرحله ۱، ارسال پُرسمان، در زیر توضیح داده شده است.

مراحل ۲ و ۳ دقیقاً مشابه مراحل مربوط به پُرسمان‌های تجزیه‌وتحلیل ناهم‌زمان است. برای اطلاعات بیشتر، نحوه ایجاد پُرسمان تجزیه‌وتحلیل ناهمزمان را ببینید.

برای ارسال پُرسمان برای گزارش درآمدزایی غیرهم‌زمان، درخواست POST به /mint/organizations/org_id/async-reports ارسال کنید.

درصورت تمایل، می‌توانید محیط را با ارسال پارامتر پُرسمان environment مشخص کنید. اگر مشخص نشده باشد، پارامتر پُرسمان به‌طور پیش‌فرض روی prod تنظیم می‌شود. برای مثال:

/mint/organizations/org_id/async-reports?environment=prod

در بدنه درخواست، معیارهای جستجوی زیر را مشخص کنید.

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

برای مثال، درخواست زیر گزارش درآمدزایی ناهم‌زمان را برای ماه ژوئن ۲۰۱۷ برای محصول API و شناسه توسعه‌دهنده مشخص‌شده تولید می‌کند. تاریخ‌ها و زمان‌های گزارش fromDate و toDate به ساعت هماهنگ جهانی/زمان گرینویچ است و می‌تواند شامل زمان‌ها باشد.

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password