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
Apigee Edge ghi lại nhiều loại dữ liệu hoạt động và dữ liệu kinh doanh truyền qua các API. Các chỉ số bắt nguồn từ dữ liệu này rất hữu ích cho việc giám sát hoạt động và giám sát doanh nghiệp. Ví dụ: khi sử dụng Edge API Analytics, bạn có thể xác định những API đang hoạt động tốt hoặc kém, những nhà phát triển đang mang lại lưu lượng truy cập có giá trị cao nhất và những ứng dụng đang gây ra nhiều vấn đề nhất cho các dịch vụ phụ trợ của bạn.
Để giúp bạn dễ dàng truy cập vào dữ liệu chỉ số này, Edge cung cấp một API RESTful. Bạn có thể sử dụng API chỉ số khi cần tự động hoá một số chức năng của Analytics, chẳng hạn như truy xuất chỉ số định kỳ bằng cách sử dụng một tập lệnh hoặc ứng dụng tự động hoá. Bạn cũng có thể dùng API này để tạo hình ảnh trực quan của riêng mình dưới dạng các tiện ích tuỳ chỉnh mà bạn có thể nhúng vào các cổng thông tin hoặc ứng dụng tuỳ chỉnh.
Để tìm hiểu cách sử dụng Analytics trong giao diện người dùng quản lý API Edge, hãy xem bài viết Tổng quan về API Analytics.
Giới thiệu về các API chỉ số
Edge cung cấp 2 API chỉ số:
Nhận chỉ số trả về chỉ số cho một tổ chức và môi trường trong một khoảng thời gian, chẳng hạn như một giờ, một ngày hoặc một tuần.
Ví dụ: đối với tuần trước, bạn muốn nhận được:
- Số lỗi về chính sách
- Thời gian phản hồi trung bình
- Tổng lưu lượng truy cập
Nhận các chỉ số được sắp xếp theo phương diện trả về các chỉ số trong một khoảng thời gian cho một tổ chức và môi trường được nhóm theo phương diện.
Ví dụ: đối với tuần trước, bạn sử dụng phương diện để nhóm các chỉ số theo sản phẩm API, proxy API và email của nhà phát triển để nhận được:
- Số lượng lỗi vi phạm chính sách trên mỗi sản phẩm API
- Thời gian phản hồi trung bình trên mỗi proxy API
- Tổng lưu lượng truy cập cho mỗi email của nhà phát triển
API Nhận chỉ số được sắp xếp theo phương diện hỗ trợ các tính năng bổ sung mà API Nhận chỉ số không hỗ trợ, bao gồm:
Giới thiệu về hạn mức API chỉ số
Edge áp dụng các hạn mức sau đây cho những lệnh gọi này. Hạn mức dựa trên hệ thống phụ trợ xử lý lệnh gọi:
- Postgres: 40 lệnh gọi mỗi phút
- BigQuery: 12 lệnh gọi mỗi phút
Xác định hệ thống phụ trợ xử lý lệnh gọi bằng cách kiểm tra đối tượng phản hồi.
Mỗi đối tượng phản hồi đều chứa một thuộc tính metaData liệt kê dịch vụ đã xử lý lệnh gọi trong thuộc tính Source. Ví dụ: đối với Postgres:
{
...
"metaData": {
"errors": [],
"notices": [
"Source:Postgres",
"Table used: xxxxxx.yyyyy",
"query served by:111-222-333"
]
}
}Đối với BigQuery, tài sản Source là:
"Source:Big Query"
Nếu bạn vượt quá hạn mức gọi, API sẽ trả về phản hồi HTTP 429.
Nhận các chỉ số bằng API quản lý
Điểm khác biệt chính giữa hai API này là Nhận chỉ số trả về chỉ số thô cho toàn bộ tổ chức và môi trường, trong khi Nhận chỉ số được sắp xếp theo phương diện cho phép bạn nhóm chỉ số theo nhiều loại thực thể, chẳng hạn như sản phẩm API, nhà phát triển và ứng dụng.
URL yêu cầu cho API Lấy chỉ số là:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/statsĐối với API Nhận chỉ số được sắp xếp theo phương diện, bạn sẽ thêm một tài nguyên khác vào URL sau /stats để chỉ định phương diện mong muốn:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimensionVí dụ: để nhận các chỉ số được nhóm theo proxy API, bạn sẽ dùng URL sau để gọi API quản lý:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxyChỉ định các chỉ số cần trả về
Đối với cả API Lấy chỉ số và Lấy chỉ số được sắp xếp theo phương diện, bạn đều sử dụng tham số truy vấn select để chỉ định chỉ số cần truy xuất và một hàm tổng hợp không bắt buộc, theo dạng:
?select=metric
hoặc:
?select=aggFunction(metric)
Trong trường hợp:
- metric chỉ định dữ liệu bạn muốn trả về. Ví dụ: số lượng yêu cầu API, lượt truy cập vào bộ nhớ đệm hoặc lỗi chính sách. Hãy xem metrics (chỉ số) để biết bảng chỉ định tên chỉ số cần dùng với tham số truy vấn
select. aggFunction chỉ định hàm tổng hợp không bắt buộc chạy theo chỉ số. Ví dụ: bạn có thể sử dụng các hàm tổng hợp sau đây với chỉ số độ trễ xử lý:
avg: Trả về độ trễ trung bình của quy trình xử lý.min: Trả về độ trễ xử lý tối thiểu.max: Trả về độ trễ xử lý tối đa.-
sum: Trả về tổng độ trễ xử lý.
Không phải chỉ số nào cũng hỗ trợ tất cả các hàm tổng hợp. Tài liệu về các chỉ số có chứa một bảng chỉ định tên chỉ số và hàm (
sum,avg,min,max) mà chỉ số đó hỗ trợ.
Ví dụ: để trả về số giao dịch trung bình (nghĩa là yêu cầu của proxy API) mỗi giây:
?select=tps
Lưu ý rằng ví dụ này không yêu cầu hàm tổng hợp. Ví dụ tiếp theo sử dụng một hàm tổng hợp để trả về tổng số lượt truy cập vào bộ nhớ đệm:
?select=sum(cache_hit)
Bạn có thể trả về nhiều chỉ số cho một lệnh gọi API. Để nhận chỉ số cho tổng số lỗi chính sách và kích thước yêu cầu trung bình, hãy đặt tham số truy vấn select bằng cách sử dụng danh sách chỉ số được phân tách bằng dấu phẩy:
?select=sum(policy_error),avg(request_size)
Chỉ định khoảng thời gian
API chỉ số trả về dữ liệu trong một khoảng thời gian cụ thể. Sử dụng tham số truy vấn timeRange để chỉ định khoảng thời gian, theo dạng:
?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
Hãy lưu ý %20 trước HH:MM. Tham số timeRange yêu cầu ký tự khoảng trắng được mã hoá URL trước HH:MM hoặc ký tự +, như trong: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.
Ví dụ:
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
Đừng sử dụng 24:00 làm thời gian vì thời gian này sẽ chuyển thành 00:00. Hãy sử dụng 23:59.
Sử dụng dấu phân cách
Để phân tách nhiều phương diện trong một lệnh gọi API, hãy dùng dấu phẩy (,) làm dấu phân cách.
Ví dụ: trong lệnh gọi API
curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day
các phương diện apis và apps được phân tách bằng ,.
Lệnh gọi API mẫu
Phần này chứa các ví dụ sử dụng API Lấy chỉ số và Lấy chỉ số được sắp xếp theo phương diện. Hãy xem Ví dụ về Metrics API để biết thêm ví dụ.
Trả về tổng số lệnh gọi được thực hiện đến API của bạn trong một tháng
Để xem tổng số lệnh gọi được thực hiện cho tất cả API trong tổ chức và môi trường của bạn trong một tháng, hãy sử dụng API Nhận chỉ số:
curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password
Phản hồi mẫu:
{
"environments": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
"7.44944088E8"
]
}
],
"name": "prod"
}
],
...
}Trả về tổng số thông báo cho mỗi proxy API trong 2 ngày
Trong ví dụ này, bạn sẽ trả về các chỉ số về số lượng yêu cầu mà tất cả các proxy API nhận được trong khoảng thời gian 2 ngày. Tham số truy vấn select xác định hàm tổng hợp sum cho chỉ số message_count trên phương diện apiproxy. Báo cáo này trả về thông lượng thông báo yêu cầu cho tất cả các API đối với lưu lượng truy cập nhận được từ đầu ngày 20/6/2018 đến cuối ngày 21/6/2018, theo giờ UTC:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password
Phản hồi mẫu:
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1498003200000,
"value" : "1100.0"
} ]
} ],
"name" : "target-reroute"
} ],
"name" : "test"
} ]...
}Phản hồi này cho biết một proxy API có tên là "target-reroute" đang chạy trong môi trường thử nghiệm đã nhận được 1.100 thông báo trong khoảng thời gian từ đầu ngày 20/6/2018 đến cuối ngày 21/6/2018.
Để nhận chỉ số cho các phương diện khác, hãy chỉ định một phương diện khác làm tham số URI. Ví dụ: bạn có thể chỉ định phương diện developer_app để truy xuất các chỉ số cho ứng dụng của nhà phát triển. Lệnh gọi API sau đây trả về tổng công suất (số lượng thông báo nhận được) từ mọi ứng dụng trong Khoảng thời gian đã chỉ định:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:passwordPhản hồi mẫu:
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "886.0"
}
]
}
],
"name": "Test-App"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "6645.0"
}
]
}
],
"name": "johndoe_app"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "1109.0"
}
]
}
],
"name": "marys_app"
}
]...
}Sắp xếp kết quả theo thứ hạng tương đối
Nhiều lần khi nhận chỉ số, bạn chỉ muốn nhận kết quả cho một nhóm nhỏ trong tổng số tập dữ liệu. Thông thường, bạn cần nhận được kết quả cho "10" kết quả hàng đầu, ví dụ: "10 API chậm nhất", "10 ứng dụng hoạt động nhiều nhất". Bạn có thể thực hiện việc này bằng cách sử dụng tham số truy vấn topk trong yêu cầu.
Ví dụ: bạn có thể muốn biết những nhà phát triển hàng đầu của mình (được đo lường bằng thông lượng) hoặc những nhà phát triển có hiệu suất kém nhất (tức là API mục tiêu "chậm nhất") là theo độ trễ.
topk (nghĩa là "k thực thể hàng đầu") cho phép báo cáo về các thực thể được liên kết với giá trị cao nhất cho một chỉ số nhất định. Điều này cho phép bạn lọc các chỉ số cho danh sách các thực thể minh hoạ một điều kiện cụ thể. Ví dụ: để tìm URL mục tiêu nào dễ xảy ra lỗi nhất trong tuần qua, tham số topk sẽ được thêm vào yêu cầu, với giá trị là 1:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
-u email:password
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(is_error)",
"values": [
{
"timestamp": 1494201600000,
"value": "12077.0"
}
]
}
],
"name": "http://api.company.com"
}
]...
}Kết quả của yêu cầu này là một tập hợp các chỉ số cho thấy URL đích có nhiều lỗi nhất là http://api.company.com.
Bạn cũng có thể sử dụng tham số topk để sắp xếp các API có thông lượng cao nhất. Ví dụ sau đây truy xuất các chỉ số về API được xếp hạng hàng đầu, được xác định bằng thông lượng cao nhất trong tuần qua:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password
Phản hồi mẫu
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1494720000000,
"value": "5750.0"
},
{
"timestamp": 1494633600000,
"value": "5752.0"
},
{
"timestamp": 1494547200000,
"value": "5747.0"
},
{
"timestamp": 1494460800000,
"value": "5751.0"
},
{
"timestamp": 1494374400000,
"value": "5753.0"
},
{
"timestamp": 1494288000000,
"value": "5751.0"
},
{
"timestamp": 1494201600000,
"value": "5752.0"
}
]
}
],
"name": "testCache"
}
],
"name": "test"
}
]...
}Đang lọc kết quả
Để có độ chi tiết cao hơn, bạn có thể lọc kết quả để giới hạn dữ liệu được trả về. Khi sử dụng bộ lọc, bạn phải dùng phương diện làm thuộc tính bộ lọc.
Ví dụ: giả sử bạn cần truy xuất số lượng lỗi từ các dịch vụ phụ trợ được lọc theo động từ HTTP của yêu cầu. Mục tiêu của bạn là tìm hiểu xem có bao nhiêu yêu cầu POST và PUT đang tạo ra lỗi cho mỗi dịch vụ phụ trợ. Để thực hiện việc này, bạn hãy sử dụng phương diện target_url cùng với bộ lọc request_verb:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password
Phản hồi mẫu:
{
"environments" : [
{
"dimensions" : [
{
"metrics" : [
{
"name" : "sum(is_error)",
"values" : [
{
"timestamp" : 1519516800000,
"value" : "1.0"
}
]
}
],
"name" : "testCache"
}
],
"name" : "test"
}
]...
}Phân trang kết quả
Trong môi trường phát hành, một số yêu cầu đối với API phân tích Edge sẽ trả về các tập dữ liệu rất lớn. Để dễ dàng hiển thị các tập dữ liệu lớn trong ngữ cảnh của một ứng dụng dựa trên giao diện người dùng, API này hỗ trợ phân trang một cách tự nhiên.
Để phân trang kết quả, hãy sử dụng các tham số truy vấn offset và limit, cùng với tham số sắp xếp sortby để đảm bảo thứ tự nhất quán của các mục.
Ví dụ: yêu cầu sau đây có khả năng trả về một tập dữ liệu lớn, vì yêu cầu này truy xuất các chỉ số cho tất cả lỗi trên tất cả API trong môi trường sản phẩm trong tuần qua.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password
Nếu ứng dụng dựa trên giao diện người dùng của bạn có thể hiển thị 50 kết quả trên mỗi trang một cách hợp lý, thì bạn có thể đặt giới hạn là 50. Vì 0 được tính là mục đầu tiên, nên lệnh gọi sau đây sẽ trả về các mục từ 0 đến 49 theo thứ tự giảm dần (sort=DESC là giá trị mặc định).
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password
Đối với "trang" kết quả thứ hai, hãy sử dụng tham số truy vấn về độ lệch như sau. Xin lưu ý rằng giới hạn và độ lệch là giống nhau. Đó là vì 0 được tính là mục đầu tiên. Với giới hạn là 50 và độ lệch là 0, các mục 0-49 sẽ được trả về. Với độ lệch là 50, các mục từ 50 đến 99 sẽ được trả về.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password