Sử dụng API báo cáo tùy chỉnh không đồng bộ

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Edge Analytics cung cấp một bộ trang tổng quan tương tác, trình tạo báo cáo tuỳ chỉnh và các tính năng liên quan phong phú. Tuy nhiên, các tính năng này được thiết kế để tương tác: bạn gửi một yêu cầu API hoặc giao diện người dùng và yêu cầu đó sẽ bị chặn cho đến khi máy chủ phân tích cung cấp phản hồi.

Tuy nhiên, các yêu cầu phân tích có thể hết thời gian chờ nếu mất quá nhiều thời gian để hoàn tất. Nếu một yêu cầu truy vấn cần xử lý một lượng lớn dữ liệu (ví dụ: hàng trăm GB), thì yêu cầu đó có thể không thành công do hết thời gian chờ.

Tính năng xử lý truy vấn không đồng bộ cho phép bạn truy vấn các tập dữ liệu rất lớn và truy xuất kết quả sau. Bạn có thể cân nhắc sử dụng truy vấn ngoại tuyến khi thấy rằng truy vấn tương tác của mình hết thời gian chờ. Sau đây là một số trường hợp mà việc xử lý truy vấn không đồng bộ có thể là một giải pháp thay thế hiệu quả:

• Phân tích và tạo báo cáo trong khoảng thời gian lớn.
• Phân tích dữ liệu bằng nhiều phương diện nhóm và các quy tắc ràng buộc khác làm tăng độ phức tạp cho truy vấn.
• Quản lý truy vấn khi bạn nhận thấy rằng một số người dùng hoặc tổ chức đã tăng đáng kể về số lượng dữ liệu.

Tài liệu này mô tả cách bắt đầu truy vấn không đồng bộ bằng cách sử dụng API. Bạn cũng có thể sử dụng giao diện người dùng như mô tả trong phần Chạy báo cáo tuỳ chỉnh.

So sánh API báo cáo với giao diện người dùng

Bài viết Tạo và quản lý báo cáo tuỳ chỉnh mô tả cách sử dụng giao diện người dùng Edge để tạo và chạy báo cáo tuỳ chỉnh. Bạn có thể chạy các báo cáo đó đồng bộ hoặc không đồng bộ.

Hầu hết các khái niệm để tạo báo cáo tuỳ chỉnh bằng giao diện người dùng đều áp dụng cho việc sử dụng API. Tức là khi tạo báo cáo tuỳ chỉnh bằng API, bạn chỉ định chỉ số, phương diện và bộ lọc tích hợp sẵn trong Edge, cũng như mọi chỉ số tuỳ chỉnh mà bạn đã tạo bằng cách sử dụng chính sách StatisticsCollector.

Sự khác biệt chính giữa các báo cáo được tạo trong giao diện người dùng và trong API là các báo cáo được tạo bằng API được ghi vào tệp CSV hoặc JSON (được phân tách bằng dòng mới) thay vì báo cáo trực quan hiển thị trong giao diện người dùng.

Giới hạn trong Apigee Hybrid

Apigee hybrid thực thi giới hạn kích thước 30 MB đối với tập dữ liệu kết quả.

Cách tạo truy vấn phân tích không đồng bộ

Bạn thực hiện các truy vấn phân tích không đồng bộ theo 3 bước:

1. Gửi truy vấn.

2. Nhận trạng thái truy vấn.

3. Truy xuất kết quả truy vấn.

Bước 1. Gửi truy vấn

Bạn phải gửi yêu cầu POST đến API /queries. API này yêu cầu Edge xử lý yêu cầu của bạn ở chế độ nền. Nếu bạn gửi truy vấn thành công, API sẽ trả về trạng thái 201 và mã nhận dạng mà bạn sẽ sử dụng để tham chiếu đến truy vấn đó trong các bước sau.

Ví dụ:

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

Nội dung của yêu cầu là nội dung mô tả truy vấn ở định dạng JSON. Trong phần nội dung JSON, hãy chỉ định chỉ số, phương diện và bộ lọc xác định báo cáo.

Dưới đây là tệp json-query-file mẫu:

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

Hãy xem phần Giới thiệu về nội dung yêu cầu bên dưới để biết nội dung mô tả đầy đủ về cú pháp nội dung yêu cầu.

Phản hồi mẫu:

Xin lưu ý rằng mã truy vấn 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd có trong phản hồi. Ngoài trạng thái HTTP 201, state của enqueued có nghĩa là yêu cầu đã thành công.

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

Bước 2. Nhận trạng thái truy vấn

Thực hiện lệnh gọi GET để yêu cầu trạng thái của truy vấn. Bạn cung cấp mã truy vấn được trả về từ lệnh gọi POST. Ví dụ:

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

Câu trả lời mẫu:

Nếu truy vấn vẫn đang diễn ra, bạn sẽ nhận được phản hồi như sau, trong đó state là 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"
}

Sau khi truy vấn hoàn tất, bạn sẽ thấy một phản hồi như sau, trong đó state được đặt thành 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"
}

Bước 3. Truy xuất kết quả truy vấn

Sau khi trạng thái truy vấn là completed, bạn có thể sử dụng API get results (lấy kết quả) để truy xuất kết quả, trong đó mã truy vấn lại là 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

Để truy xuất tệp đã tải xuống, bạn cần định cấu hình công cụ mà bạn sử dụng để công cụ đó lưu tệp đã tải xuống vào hệ thống của bạn. Ví dụ:

• Nếu sử dụng cURL, bạn có thể sử dụng các tuỳ chọn -O -J như minh hoạ ở trên.

• Nếu sử dụng Postman, bạn cần chọn nút Save and Download (Lưu và tải xuống). Trong trường hợp này, một tệp zip có tên là response sẽ được tải xuống.

• Nếu bạn sử dụng trình duyệt Chrome, thì yêu cầu tải xuống sẽ tự động được chấp nhận.

Nếu yêu cầu thành công và có tập hợp kết quả khác 0, kết quả sẽ được tải xuống ứng dụng dưới dạng tệp JSON nén (được phân tách bằng dòng mới). Tên của tệp đã tải xuống sẽ là:

OfflineQueryResult-<query-id>.zip

Ví dụ:

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

Tệp zip chứa tệp lưu trữ .gz của kết quả JSON. Để truy cập vào tệp JSON, hãy giải nén tệp đã tải xuống, sau đó sử dụng lệnh gzip để trích xuất tệp JSON:

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

Giới thiệu về nội dung yêu cầu

Phần này mô tả từng thông số mà bạn có thể sử dụng trong phần nội dung yêu cầu JSON cho một truy vấn. Để biết thông tin chi tiết về các chỉ số và phương diện mà bạn có thể sử dụng trong truy vấn, hãy xem Tài liệu tham khảo về 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"
}

Cú pháp biểu thức bộ lọc

Phần tài liệu tham khảo này mô tả các mã thông báo mà bạn có thể sử dụng để tạo biểu thức bộ lọc trong phần nội dung yêu cầu. Ví dụ: biểu thức sau đây sử dụng mã thông báo "ge" (lớn hơn hoặc bằng):

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

Quy tắc ràng buộc và giá trị mặc định

Dưới đây là danh sách các điều kiện ràng buộc và giá trị mặc định cho tính năng xử lý truy vấn không đồng bộ.

Giới thiệu về kết quả truy vấn

Sau đây là kết quả mẫu ở định dạng JSON. Kết quả bao gồm các hàng JSON được phân tách bằng dấu phân cách dòng mới:

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

Bạn có thể tìm nạp kết quả từ URL cho đến khi dữ liệu trong kho lưu trữ hết hạn. Xem phần Giới hạn và giá trị mặc định.

Ví dụ

Ví dụ 1: Tổng số tin nhắn

Truy vấn tổng số tin nhắn trong 60 phút qua.

Cụm từ tìm kiếm

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

Nội dung yêu cầu từ last60minutes.json

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

Ví dụ 2: Phạm vi thời gian tuỳ chỉnh

Truy vấn bằng cách sử dụng phạm vi thời gian tuỳ chỉnh.

Cụm từ tìm kiếm

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

Nội dung yêu cầu từ 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"
   }
}

Ví dụ 3: Số giao dịch mỗi phút

Truy vấn về chỉ số số giao dịch mỗi phút (tpm).

Cụm từ tìm kiếm

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

Nội dung yêu cầu từ tpm.json

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

Kết quả mẫu

Trích đoạn từ tệp kết quả:

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

Ví dụ 4: Sử dụng biểu thức bộ lọc

Truy vấn bằng biểu thức bộ lọc sử dụng toán tử boolean.

Cụm từ tìm kiếm

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

Nội dung yêu cầu từ 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"
   }
}

Ví dụ 5: Truyền biểu thức trong tham số chỉ số

Truy vấn bằng một biểu thức được truyền vào dưới dạng một phần của tham số chỉ số. Bạn chỉ có thể sử dụng các biểu thức đơn giản có một toán tử.

Cụm từ tìm kiếm

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

Nội dung yêu cầu từ metricsExpression.json

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

Cách tạo truy vấn báo cáo không đồng bộ về hoạt động kiếm tiền

Bạn có thể thu thập tất cả giao dịch kiếm tiền thành công trong một khoảng thời gian nhất định theo một bộ tiêu chí cụ thể bằng cách làm theo các bước được mô tả trong phần này.

Cũng giống như các truy vấn phân tích không đồng bộ, bạn thực hiện các truy vấn báo cáo kiếm tiền không đồng bộ theo 3 bước: (1) gửi truy vấn, (2) nhận trạng thái truy vấn và (3) truy xuất kết quả truy vấn.

Bước 1 (gửi truy vấn) được mô tả bên dưới.

Bước 2 và 3 giống hệt như đối với các truy vấn phân tích không đồng bộ. Để biết thêm thông tin, hãy xem bài viết Cách tạo truy vấn phân tích không đồng bộ.

Để gửi truy vấn cho báo cáo kiếm tiền không đồng bộ, hãy đưa ra yêu cầu POST đến /mint/organizations/org_id/async-reports.

Bạn có thể chỉ định môi trường bằng cách truyền tham số truy vấn environment (không bắt buộc). Nếu bạn không chỉ định, tham số truy vấn sẽ mặc định là prod. Ví dụ:

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

Trong phần nội dung yêu cầu, hãy chỉ định các tiêu chí tìm kiếm sau.

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

Ví dụ: yêu cầu sau đây sẽ tạo một báo cáo kiếm tiền không đồng bộ cho tháng 6 năm 2017 cho sản phẩm API và mã nhận dạng nhà phát triển đã chỉ định. Ngày và giờ của báo cáo fromDate và toDate được tính theo giờ UTC/GMT và có thể bao gồm cả thời gian.

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