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: 자세한 경고 정보를 제공하는 키-값 쌍 목록입니다.