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.
Truy cập vào tài liệu 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 chức năng liên quan. Tuy nhiên, các tính năng này được thiết kế để tương tác: bạn gửi yêu cầu API hoặc yêu cầu 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ả vào một thời điểm sau đó. Bạn có thể cân nhắc sử dụng truy vấn ngoại tuyến khi thấy truy vấn tương tác của mình hết thời gian chờ. Một số trường hợp mà việc xử lý truy vấn không đồng bộ có thể là một lựa chọn thay thế phù hợp:

• Phân tích và tạo báo cáo trong khoảng thời gian dài.
• Phân tích dữ liệu bằng nhiều phương diện nhóm và các điều kiện 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 lượng dữ liệu đã tăng đáng kể đối với một số người dùng hoặc tổ chức.

Tài liệu này mô tả cách bắt đầu các 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 đó một cách đồ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 được tích hợp 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.

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

Giới hạn trong Apigee Hybrid

Apigee hybrid áp dụng giới hạn kích thước 30 MB cho tập dữ liệu kết quả.

Cách thực hiện 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 cụm từ tìm kiếm.

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 câu hỏi

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 gửi truy vấn thành công, API sẽ trả về trạng thái 201 và một mã nhận dạng mà bạn 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 yêu cầu là nội dung mô tả JSON về truy vấn. 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à ví dụ về tệp json-query-file:

{ 
   "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. Lấy trạng thái truy vấn

Thực hiện một 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 được xử lý, 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 thành công, 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 để truy xuất kết quả, trong đó mã truy vấn một lần nữa 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ụ đó sẽ 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ể dùng các lựa chọn -O -J như minh hoạ ở trên.

• Nếu sử dụng Postman, bạn cần chọn nút 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ì quá trình tải xuống sẽ tự động được chấp nhận.

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

OfflineQueryResult-<query-id>.zip

Ví dụ:

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

Tệp zip chứa một 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 đó 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 tham số mà bạn có thể sử dụng trong 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 tham chiếu này mô tả các mã thông báo mà bạn có thể dùng để tạo biểu thức bộ lọc trong 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)

Ràng buộc và giá trị mặc định

Sau đâ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à một ví dụ về kết quả ở định dạng JSON. Đầu ra 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 Các ràng buộc và giá trị mặc định.

Ví dụ

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

Truy vấn tổng số lượng 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 một khoảng 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ố 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ừ tệp 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

Đoạn trích 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 thực hiện truy vấn báo cáo kiếm tiền không đồng bộ

Bạn có thể ghi lại 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 cho 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.

Tương tự như truy vấn phân tích không đồng bộ, bạn thực hiện 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ả dưới đây.

Bước 2 và 3 hoàn toàn giống với các bước dành cho 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 thực hiện một 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 gửi 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 được chỉ định. Ngày và giờ fromDate và toDate trong báo cáo là 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