Reports API: 엔티티 사용 보고서

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

항목 사용 보고서는 계정 사용자가 사용한 항목과 관련된 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_namenum_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: 자세한 경고 정보를 제공하는 키-값 쌍 목록입니다.