reportData.query 메서드는 보고서 데이터를 동기적
으로 가져오는 방법을 제공합니다. 파일 기반 보고서 (CSV 또는 Excel)를 생성하는 표준 Reports
서비스와 달리 이 메서드는
구조화된 JSON 데이터를 응답에 직접 반환합니다. 이 메서드를 사용하면 Report 리소스를 미리 정의, 생성, 저장할 필요가 없으므로 실시간 데이터 검색 및 탐색에 적합합니다.
개요
이 가이드를 통해 이 엔드포인트를 사용하여 Campaign Manager 360 보고 데이터를 쿼리하는 방법을 알아보세요.
요청 준비
ReportDataQueryRequest
측정기준, 측정항목, 기간, 필터, 정렬 기준을 지정하는 를 구성합니다.
REST
{
"body": {
"dateRange": "LAST_7_DAYS",
"dimensionNames": [
"advertiser",
"campaign"
],
"metricNames": [
"impressions",
"clicks"
],
"sortBys": [
{
"name": "clicks",
"sortOrder": "DESCENDING"
}
],
"maxResults": 100
}
}
dateRange- 쿼리의 기간을 지정하는
DateRange객체입니다. 맞춤 기간 또는 상대 기간일 수 있습니다. dimensionNames- 그룹화할 표준 측정기준 이름 목록입니다.
metricNames- 필수사항. 포함할 표준 측정항목 이름 목록입니다.
dimensionFilters- 보고서 데이터를 필터링하는 데 사용되는 DimensionValue 객체 목록입니다. 이를 사용하여 쿼리 결과를 측정기준의 특정 값으로 제한합니다.
sortBys- 측정기준 또는 측정항목의 정렬 구성입니다. 각 구성에는 필드 이름과 정렬 순서가 포함됩니다.
maxResults- 페이지당 반환할 최대 행 수입니다 (기본값:
100, 최대값:1000).
페이지로 나누기
maxResults 필드는 단일 응답에서 반환되는 결과 수를 제어합니다. 예를 들어 maxResults를 10으로 설정하면 API는 최대 10개의 결과를 반환합니다. 요청과 일치하는 결과가 10개 미만인 경우 API에서 10개 미만의 결과를 반환할 수 있습니다.
추가 결과를 사용할 수 있는 경우 응답에 nextPageToken이 포함됩니다. 결과의 다음 페이지를 가져오려면 pageToken 필드를 이 토큰으로 설정하여 동일한 요청을 다시 보냅니다. 다른 모든 요청 매개변수는 동일하게 유지합니다.
요청 전송
HTTP POST 요청을 reportdata/query
엔드포인트로 보냅니다.
POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query
요청이 표준 OAuth 2.0 사용자 인증 정보 및 필요한 범위로 인증되었는지 확인합니다. 자세한 내용은 요청 승인을 참고하세요.
성공적인 응답
성공적인 쿼리는 columnHeaders, rows, totalRow가 포함된 JSON 페이로드가 포함된 HTTP 200 OK 응답을 반환합니다.
{
"columnHeaders": [
{ "name": "advertiser", "type": "DIMENSION" },
{ "name": "campaign", "type": "DIMENSION" },
{ "name": "impressions", "type": "METRIC" },
{ "name": "clicks", "type": "METRIC" }
],
"rows": [
{
"values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
},
{
"values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
}
],
"totalRow": {
"values": [ "", "", "150831", "422" ]
},
"nextPageToken": "1234567890"
}
columnHeaders- 반환된 필드의 이름과 유형 (
DIMENSION또는METRIC)입니다. rows- 쿼리 결과가 포함된
ReportDataRow객체 목록입니다. 각 행의 문자열 값은columnHeaders와 위치별로 정렬됩니다. totalRow- 일치하는 모든 측정항목의 합계를 나타내는 단일 집계 행입니다. 합산할 수 없는 측정기준 필드 및 측정항목(예:
도달범위 측정항목(
uniqueReachTotalReach))은 이 행에서 비어 있습니다(""). nextPageToken- 추가 행이 있는 경우 다음 페이지를 가져오기 위해 후속 요청에서 사용되는 토큰입니다.
지연 시간 및 제한 시간
이 엔드포인트는 동기식이므로 쿼리가 즉시 실행되고 데이터가 응답에 직접 반환됩니다 (최대 maxResults 페이지로 나누기 한도).
쿼리의 최대 실행 시간은 60초 입니다. 쿼리가 이
한도를 초과하면 API가 작업을 종료하고 HTTP 503 Service
Unavailable 오류를 반환합니다.
이 오류가 발생하면 기간을 좁히거나 필터를 좁히거나 (예: 특정 광고주 또는 캠페인별로 필터링) 요청된 측정기준 및 측정항목 수를 줄여 보세요. 또는 Report
을 사용하여 reports.run를 실행하여 다운로드 가능한 보고서
파일을 비동기적으로 생성합니다.
쿼리 한도 및 제약조건
reportdata.query 엔드포인트는 안정적인 응답을 보장하기 위해 여러
한도를 적용합니다. 이러한 제약조건을 위반하는 요청은 HTTP 400 Bad Request 응답과 함께 거부됩니다.
기간 한도
- 맞춤 기간의 경우
startDate는 요청된 보고서 데이터 유형의 데이터 가용성 기간 내에 있어야 합니다. 자세한 내용은 데이터 가용성을 참고하세요.
측정항목 및 측정기준 제약조건
metricNames에 측정항목이 하나 이상 제공되어야 합니다.metricNames및dimensionNames목록의 측정항목과 측정기준은 고유해야 합니다.- 다운로드 전용으로 라벨이 지정된 측정항목과 측정기준은 이러한 쿼리에서 사용할 수 없습니다.
할당량 한도
이 엔드포인트에 대한 요청은 다음 할당량을 사용합니다.
- 사용자 비율 한도: 사용자별 분당 120개 요청 (2 QPS)
- 프로젝트별 일일 한도: 프로젝트당 일일 10,000개 요청
이러한 한도를 초과하는 요청은 HTTP 429 Too Many Requests 오류와 함께 실패합니다. 결과를 페이지로 나누는 경우 새 페이지에 대한 각 요청 (pageToken 매개변수 사용)은 별도의 쿼리로 계산되며 이 할당량에서 사용됩니다.