보고서 작업 기본 사항

보고서 작업을 사용하면 장기 실행 비동기 요청을 시작하여 Google 애널리틱스 이벤트 데이터의 맞춤 보고서를 만들 수 있습니다.

이 요청에서 생성된 보고서 작업 리소스는 Google 애널리틱스 속성에 대한 읽기 액세스 권한이 있는 모든 사용자가 맞춤 보고서에 액세스하는 데 사용할 수 있습니다.

맞춤 보고서는 준비된 후 72시간 동안 사용할 수 있습니다. 이 기간이 지나면 해당 보고서 작업 리소스와 콘텐츠가 자동으로 삭제됩니다.

보고서 태스크 만들기

Google 애널리틱스 Data API v1은 비동기 접근 방식을 사용하여 보고서 작업을 만듭니다. 먼저 보고서 작업을 만들려면 reportTasks.create 메서드에 대한 요청이 필요합니다. 그런 다음 reportTasks.query 메서드를 사용하여 생성된 맞춤설정된 보고서를 가져옵니다.

또한 reportTasks.get를 사용하여 특정 보고서 작업에 관한 구성 메타데이터를 검색하고 reportTasks.list를 사용하여 속성의 모든 보고서 작업을 나열할 수 있습니다.

보고 항목 선택

Data API v1의 모든 메서드에는 Google 애널리틱스 속성 식별자를 URL 요청 경로 내에 properties/GA_PROPERTY_ID 형식으로 지정해야 합니다(예:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

이 보고서는 지정된 Google 애널리틱스 속성에서 수집된 Google 애널리틱스 이벤트 데이터를 기반으로 생성됩니다.

Data API 클라이언트 라이브러리 중 하나를 사용하는 경우 요청 URL 경로를 수동으로 조작할 필요가 없습니다. 대부분의 API 클라이언트는 properties/GA_PROPERTY_ID 형식의 문자열을 예상하는 property 매개변수를 제공합니다. 클라이언트 라이브러리 사용 예는 빠른 시작 가이드를 참고하세요.

보고서 작업 생성 요청

보고서 작업을 만들려면 요청에서 ReportTask 객체를 사용하여 reportTasks.create 메서드를 호출합니다. 다음 매개변수가 필요합니다.

보고서 태스크 생성 요청 예시:

HTTP 요청

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

reportTasks.create 메서드의 응답에는 name 필드에 보고서 작업 이름 (예: properties/1234567/reportTasks/123)이 포함되며, 이는 후속 쿼리에서 보고서 작업의 상태를 가져오고 결과 보고서를 검색하는 데 사용할 수 있습니다.

HTTP 응답

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

보고서 작업 준비 상태 가져오기

reportTasks.create 호출 후 보고서를 생성하는 데 몇 분 정도 걸릴 수 있습니다. reportTasks.get 메서드를 호출하여 보고서 작업의 준비 상태를 가져올 수 있습니다.

reportTasks.create 응답에서 수신한 보고서 작업 이름 (예: properties/1234567/reportTasks/123)을 사용하여 보고서 작업을 지정합니다.

예:

HTTP 요청

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

보고서 작업의 준비 상태는 응답의 state 필드에 반환됩니다. 보고서 생성이 완료되면 보고서 작업의 상태가 CREATING에서 ACTIVE로 변경됩니다.

reportMetadata 필드에는 생성된 보고서에 관한 대략적인 정보(예: 행 수, 청구된 할당량 토큰 수)가 포함됩니다.

HTTP 응답

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

reportTasks.list 메서드를 호출하여 모든 보고서 작업의 상태를 가져올 수 있습니다.

생성된 보고서 가져오기

reportTasks.create 메서드를 사용하여 만든 보고서 작업이 생성되면 reportTasks.query 메서드를 호출하고 보고서 작업 이름(예: properties/1234567/reportTasks/123)을 지정합니다.

HTTP 요청

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

보고서 작업이 준비되면 생성된 보고서가 포함된 응답이 반환됩니다.

HTTP 응답

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}