Báo cáo mức sử dụng thực thể trả về các hoạt động dịch vụ của Google Workspace liên quan đến những thực thể mà người dùng tài khoản của bạn sử dụng. Bạn có thể tuỳ chỉnh và lọc những báo cáo này theo thông tin sử dụng cụ thể. Dữ liệu có sẵn trong 30 ngày qua.
Bạn chỉ được sử dụng báo cáo về việc sử dụng pháp nhân cho các mục đích hợp pháp theo Thoả thuận khách hàng của bạn. Các báo cáo này cũng áp dụng cho Google Workspace và Education.
Truy xuất tất cả các hoạt động sử dụng thực thể
Hiện tại, loại pháp nhân duy nhất được API này hỗ trợ là cộng đồng Google+. Để truy xuất báo cáo về tất cả hoạt động liên quan đến thực thể ứng dụng trong tài khoản của bạn, hãy sử dụng yêu cầu HTTP GET sau đây và cung cấp mã thông báo uỷ quyền được mô tả trong tài liệu về việc uỷ quyền. Để dễ đọc, ví dụ sau được định dạng bằng phương thức trả về dòng:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
Giá trị date là ngày sử dụng và dấu thời gian ở định dạng ISO 8601, yyyy-mm-dd. Bạn nên sử dụng múi giờ trong tài khoản của mình cho việc này. Để biết thêm thông tin về các tham số chuỗi truy vấn và thuộc tính phản hồi, hãy xem Tài liệu tham khảo API. Để biết thông tin về các tham số trong báo cáo về việc sử dụng thực thể, hãy xem Tài liệu tham khảo về tham số sử dụng thực thể.
applicationParameters là danh sách các thông số được phân tách bằng dấu phẩy mà bạn muốn truy xuất.
Mỗi tham số được định dạng là application:parameter_name, ví dụ: gplus:community_name. Các tham số hiện có được ghi lại trong Tài liệu tham khảo về tham số sử dụng thực thể. Nếu không có tham số nào được chỉ định, tất cả đều được trả về.
parameterFilters là danh sách các bộ lọc được phân tách bằng dấu phẩy để áp dụng cho kết quả. Mỗi bộ lọc được định dạng là application:parameter_name[relational_operator]parameter_value. Ví dụ: bộ lọc gplus:num_total_members>100 lọc kết quả để chỉ chứa kết quả mà tham số gplus:num_total_members có giá trị lớn hơn 100.
maxResults là số lượng kết quả tối đa trả về trong một lần tìm nạp. Nếu tổng số kết quả lớn hơn con số này, thì phản hồi sẽ bị cắt bớt và nextPageToken sẽ được đưa vào (xem ví dụ về phản hồi JSON bên dưới).
Ví dụ
Ví dụ sau đây nhận một báo cáo chứa tất cả thông số cho mọi thực thể gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11
Ví dụ sau đây nhận một báo cáo chứa tham số community_name
cho tất cả các thực thể gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11?parameters=gplus:community_name
Ví dụ sau đây lấy một báo cáo về community_name và num_total_members cho mỗi thực thể gplus_communities, được lọc theo các cộng đồng có hơn 100 thành viên. Để biết ví dụ về phản hồi API, hãy xem Ví dụ về phản hồi JSON.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11 ?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members>100
Truy xuất báo cáo cho một thực thể cụ thể
Để truy xuất báo cáo cho một thực thể cụ thể, hãy sử dụng yêu cầu HTTP GET sau đây và bao gồm mã thông báo uỷ quyền được mô tả trong tài liệu uỷ quyền. Để dễ đọc, ví dụ sau được định dạng bằng phương thức trả về dòng.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
entityKey là giá trị nhận dạng thực thể dành riêng cho ứng dụng chứa thực thể đó. Hãy xem Tài liệu tham khảo API để biết thông tin chi tiết về cách lấy entityKey cho thực thể cụ thể mà bạn quan tâm. Các tham số khác được ghi lại ở trên trong mục Truy xuất tất cả hoạt động sử dụng của thực thể.
Để biết thêm thông tin về các tham số chuỗi truy vấn và thuộc tính phản hồi, hãy xem Tài liệu tham khảo API. Để biết thông tin về các tham số trong báo cáo về việc sử dụng thực thể, hãy xem Tài liệu tham khảo về tham số sử dụng thực thể.
Ví dụ
Ví dụ sau đây lấy báo cáo thực thể cho một thực thể gplus_community có entityKey là "1234".
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Phản hồi JSON mẫu về báo cáo sử dụng
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Cùng với mã trạng thái, phản hồi sẽ trả về một báo cáo. Một số tham số trong phản hồi đã bị bỏ qua để dễ đọc.
Ví dụ về phản hồi JSON cho báo cáo thực thể
{
"kind": "reports#usageReports",
"nextPageToken": "NjQ1OTgwODk0MzkxNDAwNjQ0OA",
"usageReports": [
{
"kind": "admin#reports#usageReport",
"date": "2017-12-11",
"entity": {
"type": "OBJECT",
"customerId": "C03az79cb",
"objectType": "GPLUS_COMMUNITY",
"objectId": "1234",
},
"parameters": [
{
"name": "gplus:community_name",
"stringValue": "My Community"
},
{
"name": "gplus:num_total_members",
"intValue": 37
},
{
"name": "gplus:num_7day_active_members",
"intValue": 12
},
{
"name": "gplus:num_30day_active_members",
"intValue": 17
},
]
}
]
}
Ví dụ về phản hồi JSON cho báo cáo thực thể có cảnh báo
Một hoặc nhiều cảnh báo có thể được trả về trong phản hồi nếu không thể thực hiện yêu cầu. Trong ví dụ này, báo cáo sẽ không có sẵn tại thời điểm yêu cầu được đưa ra.{
"kind": "reports#usageReports",
"warnings": [
{
"code": "PARTIAL_DATA_AVAILABLE"
"message": "Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours."
"data": [
{
"key": "date"
"value": "2017-12-11"
}
]
}
],
"usageReports": [],
}
Mỗi mục nhập trong mảng warnings có các tham số sau:
code: mã cảnh báo mà máy có thể đọcmessage: nội dung cảnh báo mà con người có thể đọc đượcdata: danh sách các cặp khoá-giá trị cung cấp thông tin cảnh báo chi tiết