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

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

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

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

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

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

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

مقایسه API گزارش ها با UI

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

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

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

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

Apigee هیبرید محدودیت اندازه 30 مگابایتی را در مجموعه داده های نتیجه اعمال می کند.

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

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

1. درخواست را ارسال کنید .

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

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

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

شما باید یک درخواست POST به API /queries ارسال کنید. این API به Edge می‌گوید درخواست شما را در پس‌زمینه پردازش کند. اگر ارسال پرس و جو با موفقیت انجام شود، API وضعیت 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",
}

مرحله 2. وضعیت پرس و جو را دریافت کنید

برای درخواست وضعیت پرس و جو با 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"
}

مرحله 3. نتایج پرس و جو را بازیابی کنید

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

نمونه ها

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

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

پرس و جو

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

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

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

پرس و جو

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

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

پرس و جو در متریک برای تراکنش در دقیقه (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"}
...

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

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

پرس و جو

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

مثال 5: انتقال عبارت در پارامتر متریک

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

پرس و جو

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) نتایج پرس و جو را بازیابی کنید.

مرحله 1 ، ارسال پرس و جو، در زیر توضیح داده شده است.

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

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

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