엔티티 사용 보고서는 계정 사용자가 사용하는 엔티티와 관련된 Google Workspace 서비스 활동을 반환합니다. 이러한 보고서는 특정 사용 정보에 맞게 맞춤설정하고 필터링할 수 있습니다. 지난 30일 동안의 데이터를 사용할 수 있습니다.
엔티티 사용 보고서는 고객 계약에 따라 합법적인 목적으로만 사용할 수 있습니다. 이러한 보고서는 Google Workspace 및 Education에도 적용됩니다.
모든 항목 사용 활동 가져오기
이 API에서 지원하는 유일한 엔티티 유형은 Google+ 커뮤니티입니다. 계정의 앱 엔티티와 관련된 모든 활동의 보고서를 가져오려면 다음 GET HTTP 요청을 사용하고 승인 문서에 설명된 승인 토큰을 포함합니다. 가독성을 위해 다음 예시에는 줄바꿈이 포함되어 있습니다.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
date 값은 사용이 발생한 날짜이며 타임스탬프는 ISO 8601 형식(yyyy-mm-dd)입니다. 계정의 시간대를 사용하는 것이 좋습니다. 쿼리 문자열 매개변수 및 응답 속성에 대한 자세한 내용은 API 참조를 참고하세요. 엔티티 사용 보고서 매개변수에 대한 자세한 내용은 엔티티 사용 매개변수 참조를 참고하세요.
applicationParameters는 가져올 매개변수의 쉼표로 구분된 목록입니다.
각 매개변수는 application:parameter_name 형식으로 지정됩니다(예: gplus:community_name). 사용 가능한 매개변수는 엔티티 사용 매개변수 참조에 설명되어 있습니다. 매개변수를 지정하지 않으면 모든 매개변수가 반환됩니다.
parameterFilters는 결과에 적용할 필터의 쉼표로 구분된 목록입니다. 각 필터는 application:parameter_name[relational_operator]parameter_value 형식으로 지정됩니다. 예를 들어 gplus:num_total_members>100 필터는 gplus:num_total_members 매개변수의 값이 100보다 큰 결과만 포함하도록 결과를 필터링합니다.
maxResults: 단일 가져오기에서 반환할 최대 결과 수입니다. 총 결과 수가 이보다 크면 응답이 잘리고 nextPageToken가 포함됩니다 (아래 JSON 응답 예 참고).
예
다음 예에서는 모든 gplus_communities 항목의 모든 매개변수가 포함된 보고서를 가져옵니다.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11
다음 예에서는 모든 gplus_communities 항목에 대해 community_name 매개변수가 포함된 보고서를 가져옵니다.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11?parameters=gplus:community_name
다음 예에서는 구성원이 100명을 초과하는 커뮤니티를 기준으로 필터링된 각 gplus_communities 항목의 community_name 및 num_total_members 보고서를 가져옵니다. API 응답의 예는 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
특정 항목의 보고서 가져오기
특정 항목의 보고서를 가져오려면 다음 GET HTTP 요청을 사용하고 승인 문서에 설명된 승인 토큰을 포함합니다. 가독성을 위해 다음 예시에는 줄바꿈이 포함되어 있습니다.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
entityKey는 항목이 있는 애플리케이션에 고유한 항목 식별자입니다. 관심 있는 특정 항목의 entityKey를 획득하는 방법에 관한 자세한 내용은 API 참조를 참고하세요. 다른 매개변수는 모든 항목 사용 활동 가져오기 섹션의 앞부분에 설명되어 있습니다.
쿼리 문자열 매개변수 및 응답 속성에 대한 자세한 내용은 API 참조를 참고하세요. 엔티티 사용 보고서 매개변수에 대한 자세한 내용은 엔티티 사용 매개변수 참조를 참고하세요.
예
다음 예시에서는 entityKey이 '1234'인 gplus_community 항목의 항목 보고서를 가져옵니다.
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
사용 보고서 예시 JSON 응답
성공적인 응답은 HTTP 200 상태 코드를 반환합니다. 응답에는 상태 코드와 함께 보고서가 반환됩니다. 가독성을 위해 대답의 일부 매개변수가 생략되었습니다.
엔티티 보고서의 JSON 응답 예시
{ "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 }, ] } ] }
경고가 포함된 항목 보고서의 JSON 응답 예시
요청을 처리할 수 없는 경우 응답에 하나 이상의 경고가 반환될 수 있습니다. 이 예에서는 요청이 이루어진 시점에 보고서를 사용할 수 없습니다.{
"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": [],
}warnings 배열의 각 항목에는 다음 매개변수가 있습니다.
code: 머신 판독 가능 경고 코드message: 사람이 읽을 수 있는 경고 메시지data: 자세한 경고 정보를 제공하는 키-값 쌍 목록