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

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

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

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

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

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

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

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

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

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

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

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

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

چگونه یک کوئری تحلیلی ناهمزمان ایجاد کنیم

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

1. استعلام را ارسال کنید .

2. وضعیت درخواست را دریافت کنید .

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

مرحله 1. ارسال درخواست

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

برای مثال:

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 انجام دهید. شما شناسه پرس‌وجوی (query ID) که از فراخوانی 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 وضعیت پرس‌وجو، می‌توانید از 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 استفاده می‌کنید، باید دکمه‌ی ذخیره و دانلود را انتخاب کنید. در این حالت، یک فایل زیپ به نام response دانلود می‌شود.

• اگر از مرورگر کروم استفاده می‌کنید، دانلود به صورت خودکار انجام می‌شود.

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

OfflineQueryResult-<query-id>.zip

برای مثال:

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.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"}    
…

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

مثال‌ها

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

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

پرس و جو

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"
   }
}

مثال ۵: ارسال عبارت در پارامتر metrics

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

پرس و جو

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"
}

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

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

همانند پرس‌وجوهای تحلیلی ناهمزمان، شما پرس‌وجوهای گزارش کسب درآمد ناهمزمان را در سه مرحله انجام می‌دهید: (1) ارسال پرس‌وجو، (2) دریافت وضعیت پرس‌وجو، و (3) بازیابی نتایج پرس‌وجو.

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

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

برای ارسال درخواست گزارش کسب درآمد ناهمزمان، یک درخواست 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 بر اساس UTC/GMT هستند و می‌توانند شامل زمان نیز باشند.

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