이전 Search Ads 360 Reporting API의 지원이 종료되며 2024년 6월 30일에 사용 중단됩니다. Search Ads 360 Conversion API는 영향을 받지 않으며 계속 지원됩니다. 모든 보고 개발에서는 새 Search Ads 360 Reporting API를 사용해야 합니다.

2024년 4월부터 보고서를 요청할 때 지원되지 않는 APIVersion 오류가 반환됩니다. 자세한 내용은 여기를 참조하세요.

또한 기존 Search Ads 360 구현을 새 API로 이전하는 것이 좋습니다. 자세한 내용은 새 Search Ads 360 Reporting API 시작하기 및 이전 가이드를 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Reports: request

보고 요청을 보고 시스템에 삽입합니다. 지금 사용해 보기

요청

HTTP 요청

POST https://www.googleapis.com/doubleclicksearch/v2/reports

승인

다음 범위를 사용하여 이 요청을 인증받아야 합니다.

범위
`https://www.googleapis.com/auth/doubleclicksearch`

자세한 내용은 인증 및 승인 페이지를 참고하세요.

요청 본문

요청 본문에서 다음과 같은 구조의 데이터를 제공합니다.

{
  "reportScope": {
    "agencyId": long,
    "advertiserId": long,
    "engineAccountId": long,
    "campaignId": long,
    "adGroupId": long,
    "keywordId": long,
    "adId": long
  },
  "reportType": string,
  "columns": [
    {
      "columnName": string,
      "savedColumnName": string,
      "customDimensionName": string,
      "customMetricName": string,
      "headerText": string,
      "startDate": string,
      "endDate": string,
      "groupByColumn": boolean,
      "platformSource": string,
      "productReportPerspective": string
    }
  ],
  "timeRange": {
    "startDate": string,
    "endDate": string,
    "changedMetricsSinceTimestamp": datetime,
    "changedAttributesSinceTimestamp": datetime
  },
  "filters": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "operator": string,
      "values": [
        (value)
      ]
    }
  ],
  "orderBy": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "sortOrder": string
    }
  ],
  "includeDeletedEntities": boolean,
  "includeRemovedEntities": boolean,
  "verifySingleTimeZone": boolean,
  "downloadFormat": string,
  "statisticsCurrency": string,
  "startRow": integer,
  "rowCount": integer,
  "maxRowsPerFile": integer
}

숙소 이름	값	설명
`reportScope`	`object`	reportScope는 보고서에 반환될 항목의 하위 집합을 결정하는 데 사용되는 ID 집합입니다. 대행사를 통해 원하는 가장 낮은 범위 수준의 ID에 대한 전체 계보가 필요합니다.
`reportScope.agencyId`	`long`	DS 대행사 ID
`reportScope.advertiserId`	`long`	DS 광고주 ID
`reportScope.engineAccountId`	`long`	DS 엔진 계정 ID입니다.
`reportScope.campaignId`	`long`	DS 캠페인 ID
`reportScope.adGroupId`	`long`	DS 광고그룹 ID입니다.
`reportScope.keywordId`	`long`	DS 키워드 ID
`reportScope.adId`	`long`	DS 광고 ID
`reportType`	`string`	보고서에 반환되는 행의 유형을 결정합니다. 예를 들어 `reportType: keyword`를 지정하면 보고서의 각 행에 키워드에 대한 데이터가 포함됩니다. 각 유형에서 사용할 수 있는 항목은 보고서 유형 참조를 확인하세요.
`columns[]`	`list`	보고서에 포함할 열 여기에는 DoubleClick Search 열과 저장된 열이 모두 포함됩니다. DoubleClick Search 열의 경우 `columnName` 매개변수만 필요합니다. 저장된 열의 경우 `savedColumnName` 매개변수만 필요합니다. `columnName`과 `savedColumnName`을 동일한 스탠자에 설정할 수 없습니다. 요청당 최대 열 수는 300개입니다.
`columns[].columnName`	`string`	보고서에 포함할 DoubleClick Search 열의 이름입니다.
`columns[].savedColumnName`	`string`	보고서에 포함할 저장된 열의 이름입니다. 보고서의 범위를 광고주 이하로 지정해야 하며, 이렇게 저장된 열은 DoubleClick Search UI에서 미리 만들어 두어야 합니다.
`columns[].headerText`	`string`	보고서 출력에서 이 열을 식별하는 데 사용되는 텍스트입니다. 지정되지 않은 경우 기본값은 `columnName` 또는 `savedColumnName`입니다. 이는 DoubleClick Search 열과 이름이 같은 저장된 열 간의 충돌을 방지하는 데 사용할 수 있습니다.
`columns[].startDate`	`string`	YYYY-MM-DD 형식의 날짜를 포함합니다. 제공되는 경우 이 열에 대해서만 보고서의 전체 기간이 재정의됩니다. `endDate`과 함께 제공해야 합니다.
`columns[].endDate`	`string`	YYYY-MM-DD 형식으로 된 날짜입니다. 제공되는 경우 이 열에 대해서만 보고서의 전체 기간이 재정의됩니다. `startDate`과 함께 제공해야 합니다.
`columns[].groupByColumn`	`boolean`	동기식 보고서만 이 열로 그룹화하려면 `true`로 설정합니다. 기본값은 `false`입니다.
`timeRange`	`object`	보고서에서 측정항목을 요청하면 이 인수를 사용하여 측정항목을 특정 기간으로 제한할 수 있습니다.
`timeRange.startDate`	`string`	YYYY-MM-DD 형식의 날짜를 포함합니다.
`timeRange.endDate`	`string`	YYYY-MM-DD 형식의 날짜를 포함합니다.
`timeRange.changedMetricsSinceTimestamp`	`datetime`	RFC 형식의 포괄적인 UTC 타임스탬프입니다(예: `2013-07-16T10:16:23.555Z` 변경된 측정항목 보고서의 작동 방식에 대해 자세히 알아보세요.
`timeRange.changedAttributesSinceTimestamp`	`datetime`	RFC 형식의 포괄적인 UTC 타임스탬프입니다(예: `2013-07-16T10:16:23.555Z` 변경된 속성 보고서의 작동 방식에 대한 추가 참조를 확인하세요.
`filters[]`	`list`	보고서에 적용할 필터의 목록입니다. 요청당 최대 필터 수는 300입니다.
`filters[].column`	`nested object`	필터를 수행할 열입니다. DoubleClick Search 열이거나 저장된 열일 수 있습니다.
`filters[].column.columnName`	`string`	보고서에 포함할 DoubleClick Search 열의 이름입니다.
`filters[].column.savedColumnName`	`string`	보고서에 포함할 저장된 열의 이름입니다. 보고서의 범위를 광고주 이하로 지정해야 하며, 이렇게 저장된 열은 DoubleClick Search UI에서 미리 만들어 두어야 합니다.
`filters[].operator`	`string`	필터에서 사용할 연산자입니다. 사용 가능한 연산자 목록은 필터 참조를 확인하세요.
`filters[].values[]`	`list`	열 값을 필터링할 값 목록입니다. 요청당 최대 필터 값은 300입니다.
`orderBy[]`	`list`	동기식 보고서만 보고서 행에 수행할 정렬을 정의하는 열 및 방향 목록입니다. 요청당 최대 주문 수는 300개입니다.
`orderBy[].column`	`nested object`	정렬을 수행할 열입니다. DoubleClick Search에서 정의한 열이거나 저장된 열일 수 있습니다.
`orderBy[].column.columnName`	`string`	보고서에 포함할 DoubleClick Search 열의 이름입니다.
`orderBy[].column.savedColumnName`	`string`	보고서에 포함할 저장된 열의 이름입니다. 보고서의 범위를 광고주 이하로 지정해야 하며, 이렇게 저장된 열은 DoubleClick Search UI에서 미리 만들어 두어야 합니다.
`orderBy[].sortOrder`	`string`	정렬 방향입니다(`ascending` 또는 `descending`).
`includeDeletedEntities`	`boolean`	삭제된 항목을 보고서에 포함해야 하는지를 결정합니다. 기본값은 `false`입니다. 지원 중단되었습니다. 대신 `includeRemovedEntities`를 사용하세요.
`verifySingleTimeZone`	`boolean`	`true`이면 요청된 모든 통계 데이터를 단일 시간대에서 가져온 경우에만 보고서가 생성됩니다. 기본값은 `false`입니다.
`downloadFormat`	`string`	보고서를 반환해야 하는 형식입니다. 현재 `csv` 또는 `tsv`가 지원됩니다.
`statisticsCurrency`	`string`	금액을 반환할 통화를 지정합니다. 가능한 값은 `usd`, `agency` (보고서의 범위가 대행사 또는 이보다 낮은 경우 유효), `advertiser` (보고서의 범위가 * 광고주로 범위가 지정된 경우 유효), `account` (보고서의 범위가 엔진 계정 이하로 지정된 경우 유효함)입니다.
`startRow`	`integer`	동기식 보고서만 반환할 첫 번째 행의 0부터 시작하는 색인입니다. 사용 가능한 값: `0`~`50000`. 기본값은 `0`입니다.
`rowCount`	`integer`	동기식 보고서만 반환할 최대 행 수입니다. 추가 행은 삭제됩니다. 사용 가능한 값: `0`~`10000`. 기본값은 `10000`입니다.
`maxRowsPerFile`	`integer`	비동기 보고서에만 해당합니다. 보고서 파일당 최대 행 수입니다. 큰 보고서는 이 필드를 기준으로 여러 파일로 나뉩니다. 사용 가능한 값: `1000000`~`100000000`.
`includeRemovedEntities`	`boolean`	삭제된 항목을 보고서에 포함해야 하는지를 결정합니다. 기본값은 `false`입니다.
`columns[].customDimensionName`	`string`	맞춤 측정기준별로 보고서를 분류합니다. 보고서의 범위가 광고주 이하로 지정되어야 하며, 맞춤 측정기준이 이미 DoubleClick Search에서 설정되어 있어야 합니다. DoubleClick Search에 표시되는 맞춤 측정기준 이름은 대소문자를 구분합니다. 전환 보고서에서 사용하는 경우 설정된 경우 지정된 전환에 대해 지정된 맞춤 측정기준의 값을 반환합니다. 이 열은 전환 보고서를 분류하지 않습니다.
`columns[].platformSource`	`string`	맞춤 측정기준에 데이터를 제공하는 데 사용되는 플랫폼입니다. 사용 가능한 값은 '플러드라이트'입니다.
`filters[].column.customDimensionName`	`string`	맞춤 측정기준별로 보고서를 분류합니다. 보고서의 범위가 광고주 이하로 지정되어야 하며, 맞춤 측정기준이 이미 DoubleClick Search에서 설정되어 있어야 합니다. DoubleClick Search에 표시되는 맞춤 측정기준 이름은 대소문자를 구분합니다. 전환 보고서에서 사용하는 경우 설정된 경우 지정된 전환에 대해 지정된 맞춤 측정기준의 값을 반환합니다. 이 열은 전환 보고서를 분류하지 않습니다.
`filters[].column.headerText`	`string`	보고서 출력에서 이 열을 식별하는 데 사용되는 텍스트입니다. 지정되지 않은 경우 기본값은 `columnName` 또는 `savedColumnName`입니다. 이는 DoubleClick Search 열과 이름이 같은 저장된 열 간의 충돌을 방지하는 데 사용할 수 있습니다.
`filters[].column.startDate`	`string`	YYYY-MM-DD 형식의 날짜를 포함합니다. 제공되는 경우 이 열에 대해서만 보고서의 전체 기간이 재정의됩니다. `endDate`과 함께 제공해야 합니다.
`filters[].column.endDate`	`string`	YYYY-MM-DD 형식으로 된 날짜입니다. 제공되는 경우 이 열에 대해서만 보고서의 전체 기간이 재정의됩니다. `startDate`과 함께 제공해야 합니다.
`filters[].column.groupByColumn`	`boolean`	동기식 보고서만 이 열로 그룹화하려면 `true`로 설정합니다. 기본값은 `false`입니다.
`filters[].column.platformSource`	`string`	맞춤 측정기준에 데이터를 제공하는 데 사용되는 플랫폼입니다. 사용 가능한 값은 '플러드라이트'입니다.
`orderBy[].column.customDimensionName`	`string`	맞춤 측정기준별로 보고서를 분류합니다. 보고서의 범위가 광고주 이하로 지정되어야 하며, 맞춤 측정기준이 이미 DoubleClick Search에서 설정되어 있어야 합니다. DoubleClick Search에 표시되는 맞춤 측정기준 이름은 대소문자를 구분합니다. 전환 보고서에서 사용하는 경우 설정된 경우 지정된 전환에 대해 지정된 맞춤 측정기준의 값을 반환합니다. 이 열은 전환 보고서를 분류하지 않습니다.
`orderBy[].column.headerText`	`string`	보고서 출력에서 이 열을 식별하는 데 사용되는 텍스트입니다. 지정되지 않은 경우 기본값은 `columnName` 또는 `savedColumnName`입니다. 이는 DoubleClick Search 열과 이름이 같은 저장된 열 간의 충돌을 방지하는 데 사용할 수 있습니다.
`orderBy[].column.startDate`	`string`	YYYY-MM-DD 형식의 날짜를 포함합니다. 제공되는 경우 이 열에 대해서만 보고서의 전체 기간이 재정의됩니다. `endDate`과 함께 제공해야 합니다.
`orderBy[].column.endDate`	`string`	YYYY-MM-DD 형식으로 된 날짜입니다. 제공되는 경우 이 열에 대해서만 보고서의 전체 기간이 재정의됩니다. `startDate`과 함께 제공해야 합니다.
`orderBy[].column.groupByColumn`	`boolean`	동기식 보고서만 이 열로 그룹화하려면 `true`로 설정합니다. 기본값은 `false`입니다.
`orderBy[].column.platformSource`	`string`	맞춤 측정기준에 데이터를 제공하는 데 사용되는 플랫폼입니다. 사용 가능한 값은 '플러드라이트'입니다.
`columns[].customMetricName`	`string`	보고서에 포함할 맞춤 측정항목의 이름입니다. 보고서의 범위가 광고주 이하로 지정되어야 하며, 맞춤 측정항목이 이미 DoubleClick Search에서 설정되어 있어야 합니다. DoubleClick Search에 표시되는 맞춤 측정항목 이름은 대소문자를 구분합니다.
`filters[].column.customMetricName`	`string`	보고서에 포함할 맞춤 측정항목의 이름입니다. 보고서의 범위가 광고주 이하로 지정되어야 하며, 맞춤 측정항목이 이미 DoubleClick Search에서 설정되어 있어야 합니다. DoubleClick Search에 표시되는 맞춤 측정항목 이름은 대소문자를 구분합니다.
`orderBy[].column.customMetricName`	`string`	보고서에 포함할 맞춤 측정항목의 이름입니다. 보고서의 범위가 광고주 이하로 지정되어야 하며, 맞춤 측정항목이 이미 DoubleClick Search에서 설정되어 있어야 합니다. DoubleClick Search에 표시되는 맞춤 측정항목 이름은 대소문자를 구분합니다.
`columns[].productReportPerspective`	`string`	특정 유형의 제품 활동에 대한 측정항목만 반환합니다. 허용되는 값은 다음과 같습니다. '`sold`': 판매된 제품의 측정항목만 반환합니다. '`advertised`': 쇼핑 캠페인에서 광고되었으며 판매되었을 수도 있고 판매되지 않았을 수 있는 제품의 측정항목만 반환합니다.
`filters[].column.productReportPerspective`	`string`	특정 유형의 제품 활동에 대한 측정항목만 반환합니다. 허용되는 값은 다음과 같습니다. '`sold`': 판매된 제품의 측정항목만 반환합니다. '`advertised`': 쇼핑 캠페인에서 광고되었으며 판매되었을 수도 있고 판매되지 않았을 수 있는 제품의 측정항목만 반환합니다.
`orderBy[].column.productReportPerspective`	`string`	특정 유형의 제품 활동에 대한 측정항목만 반환합니다. 허용되는 값은 다음과 같습니다. '`sold`': 판매된 제품의 측정항목만 반환합니다. '`advertised`': 쇼핑 캠페인에서 광고되었으며 판매되었을 수도 있고 판매되지 않았을 수 있는 제품의 측정항목만 반환합니다.

응답

요청에 성공할 경우 이 메서드는 응답 본문에 Reports 리소스를 반환합니다.

사용해 보기

아래의 API 탐색기를 사용하여 실시간 데이터를 대상으로 이 메소드를 호출하고 응답을 확인해 보세요. 또는 독립형 탐색기를 사용해 보세요.