보고서 작업 기본 사항

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

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

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

보고서 작업 만들기

Google Analytics Data API v1은 비동기식 접근 방식을 사용하여 보고서 작업을 만듭니다. 먼저, 보고서 작업을 만들려면 reportTasks.create 메서드에 대한 요청이 필요합니다. 그런 다음 생성된 맞춤 보고서를 검색하는 데 reportTasks.query 메서드를 사용합니다.

또한 reportTasks.get를 사용하여 특정 Report Task에 대한 구성 메타데이터를 검색하고 reportTasks.list를 사용하여 속성의 모든 Report Tasks를 나열할 수 있습니다.

신고 항목 선택

Data API v1의 모든 메서드는 다음과 같이 properties/GA4_PROPERTY_ID 형식의 URL 요청 경로 내에 Google 애널리틱스 4 속성 식별자를 지정해야 합니다.

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

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

Data API 클라이언트 라이브러리 중 하나를 사용하는 경우 요청 URL 경로를 수동으로 조작할 필요가 없습니다. 대부분의 API 클라이언트는 properties/GA4_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)에 포함됩니다. 이는 후속 쿼리에서 Report 태스크의 상태를 가져오고 결과 보고서를 가져오는 데 사용할 수 있습니다.

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 응답에서 받은 Report 태스크 이름 (예: properties/1234567/reportTasks/123)을 사용하여 Report 태스크를 지정합니다.

예:

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 메서드를 사용하여 만든 Report Task가 생성되면 reportTasks.query 메서드를 호출하고 Report Task 이름(예: 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"
  }
}