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 tập hợp phong phú các trang tổng quan tương tác, trình tạo báo cáo tùy chỉnh và các tính năng liên quan. Tuy nhiên, các tính năng này nhằm mang tính tương tác: bạn gửi 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, 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 thành. 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ụ: 100 GB), thì yêu cầu đó có thể không thành công do hết thời gian chờ.

Quá trình 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 các 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 phương án thay thế hiệu quả:

• Phân tích và tạo báo cáo trong những khoảng thời gian lớn.
• Phân tích dữ liệu với 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 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 một 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 bài viết 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 sẽ tìm hiểu 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 sẽ chỉ định metrics, phương diện và bộ lọ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 Thu thập dữ liệu thống kê.

Điểm 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à 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 dạng hình ảnh hiển thị trong giao diện người dùng.

Các giới hạn trong phiên bản kết hợp của Apigee

Apigee kết hợp 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 có thể 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 tới 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ẽ 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

Phần nội dung của yêu cầu là nội dung mô tả JSON của truy vấn. Trong nội dung JSON, hãy chỉ định các metrics, 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.

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

Lưu ý rằng mã truy vấn 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd được đưa vào 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. Xem trạng thái của 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 được tiến hành, 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 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 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ụ này 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ư hiển thị ở 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 response sẽ được tải xuống.

• Nếu bạn sử dụng trình duyệt Chrome, 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ó nhóm kết quả khác 0, thì 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 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 truy vấn. Để biết 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 của mình, hãy xem Tài liệu tham khảo 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 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 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)

Quy tắc ràng buộc và chế độ 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ộ.

Thông tin về kết quả truy vấn

Sau đây là ví dụ về kết quả ở đị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 tá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 hết hạn trong kho lưu trữ. Xem phần Các quy tắc ràng buộc và 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 vừa 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ố cho 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 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 lọc

Truy vấn bằng biểu thức 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: Chuyển biểu thức trong thông số chỉ số

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

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ừ indexExpression.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 kiếm tiền không đồng bộ

Bạn có thể nắm bắt 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 nhóm tiêu chí cụ thể bằng cách làm theo các bước được mô tả trong phần này.

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ả dưới đây.

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 phần 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 gửi yêu cầu POST tới /mint/organizations/org_id/async-reports.

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

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

Trong 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 tạo ra 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à phát triển được chỉ định. Ngày và giờ của báo cáo fromDate và toDate theo giờ UTC/GMT và có thể bao gồm cả giờ.

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