API Báo cáo: Báo cáo về việc sử dụng thực thể

Báo cáo mức sử dụng thực thể trả về các hoạt động sử dụng dịch vụ của Google Workspace liên quan đến các thực thể do người dùng trong tài khoản của bạn sử dụng. Bạn có thể tuỳ chỉnh và lọc các báo cáo này để xem thông tin sử dụng cụ thể. Dữ liệu có sẵn trong 30 ngày qua.

Bạn chỉ có thể sử dụng báo cáo mức sử dụng thực thể cho các mục đích hợp pháp theo Thoả thuận khách hàng. Các báo cáo này cũng áp dụng cho Google Workspace và Education.

Truy xuất tất cả hoạt động sử dụng thực thể

Loại thực thể duy nhất mà 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 các 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à đưa mã thông báo uỷ quyền được mô tả trong tài liệu uỷ quyền. Để dễ đọc, ví dụ sau đây được định dạng bằng dấu xuống 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ờ của tài khoản 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ố báo cáo mức sử dụng thực thể, hãy xem Tài liệu tham khảo về tham số mức sử dụng thực thể.

applicationParameters là danh sách được phân tách bằng dấu phẩy các tham số 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ố có sẵn được ghi lại trong Tài liệu tham khảo về tham số mức sử dụng thực thể. Nếu không có tham số nào được chỉ định, thì tất cả các tham số sẽ được trả về.

parameterFilters là danh sách được phân tách bằng dấu phẩy các bộ lọc để á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 những 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 cần trả về trong một lần tìm nạp. Nếu tổng số kết quả lớn hơn số này, thì phản hồi sẽ bị cắt bớt và một 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 lấy một báo cáo chứa tất cả các tham số cho tất cả 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 lấy một báo cáo chứa tham số community_name cho tất 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. Để xem 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à đưa mã thông báo uỷ quyền được mô tả trong tài liệu uỷ quyền. Để dễ đọc, ví dụ sau đây được định dạng bằng dấu xuống 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 nơi thực thể tồn tại. 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ước đó trong phần Truy xuất tất cả hoạt động sử dụng 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ố báo cáo mức sử dụng thực thể, hãy xem Tài liệu tham khảo về tham số mức 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 "1234".

https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11

Ví dụ về phản hồi JSON của báo cáo mức 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 không có sẵn tại thời điểm đưa ra yêu cầu. 
{
 "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 trong mảng warnings có các tham số sau:
  • code: mã cảnh báo mà máy có thể đọc được
  • message: thông báo cảnh báo mà người dùng có thể đọc được
  • data: danh sách các cặp khoá-giá trị cung cấp thông tin cảnh báo chi tiết