이제 새 Search Ads 360 Reporting API를 사용할 수 있습니다. searchads-api-announcements Google 그룹에 가입하여 향후 개선사항 및 출시에 관한 최신 정보를 받아 보세요.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Search Ads 360 Reporting API에서 검색 보고서 만들기

아래 섹션을 읽고 Search Ads 360 Reporting API에서 검색 보고서를 만드는 방법을 알아보세요.

검색 서비스

Search Ads 360 Reporting API는 검색 및 보고를 위한 특별한 서비스를 제공합니다.

SearchAds360Service은 SearchStream 및 Search의 두 가지 검색 방법을 제공하는 통합 객체 검색 및 보고 서비스입니다. 검색은 Search Ads 360 쿼리 언어로 작성된 쿼리 문자열로 전달됩니다. 다음을 수행하는 쿼리를 정의할 수 있습니다.

객체의 특정 속성을 가져옵니다.
기간을 기반으로 객체의 실적 측정항목을 가져옵니다.
속성을 기준으로 객체를 정렬합니다.
반환할 객체를 지정하는 조건을 사용하여 결과를 필터링합니다.
반환되는 객체 수를 제한합니다.

두 검색 방법 모두 쿼리와 일치하는 모든 행을 반환합니다. 예를 들어 campaign.id, campaign.name, metrics.clicks를 검색하면 API는 id 및 name 필드가 설정된 캠페인 객체가 포함된 SearchAds360Row와 clicks 필드가 설정된 metrics 객체를 반환합니다.

검색 방법

SearchStream

보고서 크기에 관계없이 단일 요청을 전송하고 Search Ads 360 Reporting API와의 지속적인 연결을 시작합니다.

데이터 패킷이 즉시 다운로드되기 시작하고 전체 결과가 데이터 버퍼에 캐시됩니다.
전체 스트림이 완료될 때까지 기다리지 않고도 코드가 버퍼링된 데이터를 읽기 시작할 수 있습니다.

Search

전체 보고서를 다운로드하기 위해 페이지로 나눈 여러 요청을 전송합니다.

SearchStream는 개별 페이지를 요청하는 데 필요한 왕복 네트워크 시간을 없애므로 일반적으로 성능이 더 좋습니다. 행이 10,000개를 초과하는 모든 보고서에는 SearchStream를 사용하는 것이 좋습니다. 행이 10,000개 미만인 작은 보고서의 경우 메서드 간에 성능 차이가 크지 않습니다.

사용하는 메서드는 API 할당량 및 한도에 영향을 미치지 않습니다. 결과가 페이지로 나뉘는지 스트리밍되는지와 관계없이 단일 쿼리 또는 보고서는 하나의 작업으로 계산됩니다.

검색어 예시

이 예시 쿼리는 지난 30일 동안의 계정 실적 데이터를 캠페인별로 반환하고 기기별로 분류합니다.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

요청하기

요청을 발행하려면 customer_id 및 query 문자열을 SearchAds360Service.SearchStream 또는 SearchAds360Service.Search 인터페이스에 전달해야 합니다.

요청은 다음 URL 중 하나의 Search Ads 360 Reporting API 서버에 대한 HTTP POST로 구성됩니다.

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

다음은 HTTP POST 요청에 포함된 searchStream에 대한 보고서 정의의 전체 예입니다.

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

응답 처리

SearchAds360Service은 SearchAds360Row 객체 목록을 반환합니다.

각 SearchAds360Row는 쿼리에서 반환된 객체를 나타냅니다. 각 객체는 쿼리의 SELECT 절에서 요청된 필드를 기반으로 채워지는 속성 집합으로 구성됩니다. SELECT 절에 포함되지 않은 속성은 응답의 객체에 채워지지 않습니다.

예를 들어 아래 쿼리는 각 SearchAds360Row 객체를 campaign.id, campaign.name, campaign.status로만 채웁니다. campaign.engine_id 또는 campaign.bidding_strategy_type과 같은 다른 속성은 생략됩니다.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

참조 문서

참조 섹션에는 각 아티팩트를 올바르게 사용하는 데 필요한 모든 정보가 포함되어 있습니다. 각 리소스(예: ad_group 및 campaign)마다 하나의 페이지가 있습니다. segments 및 metrics 페이지에는 사용 가능한 모든 세그먼트 및 측정항목 필드가 나열되어 있습니다.

일부 리소스, 세그먼트, 측정항목은 호환되지 않아 함께 사용할 수 없지만, 다른 리소스, 세그먼트, 측정항목은 완전히 호환되어 서로 보완합니다. 각 리소스 페이지에는 다음 정보 (사용 가능하고 적절한 경우) 등이 포함됩니다.

기여도가 부여된 리소스

일부 리소스의 경우 FROM 절에서 리소스의 필드와 함께 필드를 선택하여 관련 리소스에 암시적으로 조인할 수 있습니다. 예를 들어 campaign 리소스는 ad_group 리소스의 속성이 지정된 리소스입니다. 즉, FROM 절에서 ad_group를 사용할 때 쿼리에 campaign.id 및 campaign.bidding_strategy_type과 같은 필드를 포함할 수 있습니다.

기여 리소스 섹션에는 사용 가능한 기여 리소스가 나열됩니다. 일부 리소스에는 저작자 표시 리소스가 없습니다.

리소스 필드 열

리소스의 모든 필드가 리소스 필드 열에 포함됩니다. 각 리소스 필드는 설명, 카테고리, 데이터 유형, 유형 URL, 필터링 가능, 선택 가능, 정렬 가능, 반복 설정 등 필드에 관한 자세한 정보로 연결됩니다.

세그먼트 열

특정 리소스에서는 일부 세그먼트 필드를 선택할 수 없습니다.

세그먼트 열에는 리소스의 필드와 동일한 SELECT 절에서 사용할 수 있는 segments 필드가 나열됩니다. 각 필드는 설명, 카테고리, 데이터 유형, 유형 URL, 필터링 가능, 선택 가능, 정렬 가능, 반복 설정 등 필드에 관한 전체 세부정보로 연결됩니다. FROM 절에서 리소스를 사용하는 경우 예/아니요 드롭다운을 사용하여 사용할 수 없는 세그먼트를 필터링할 수 있습니다.

측정항목 열

일부 측정항목 필드는 지정된 리소스와 함께 선택할 수 없습니다.

측정항목 열에는 리소스의 필드와 동일한 SELECT 절에서 사용할 수 있는 metrics 필드가 나열됩니다. 각 필드는 설명, 카테고리, 데이터 유형, 유형 URL, 필터링 가능, 선택 가능, 정렬 가능, 반복 설정 등 필드에 관한 전체 세부정보로 연결됩니다. FROM 절에서 리소스를 사용하는 경우 예/아니요 드롭다운을 사용하여 사용할 수 없는 측정항목을 필터링합니다.

리소스 분할

일부 리소스에는 리소스가 FROM 절에 있을 때 선택할 수 있는 세분화 리소스 필드가 있습니다. 예를 들어 FROM 절에서 campaign_budget를 사용할 때 campaign.name과 같은 campaign 리소스 필드를 선택하면 campaign이 campaign_budget의 세분화 리소스이므로 campaign.resource_name이 자동으로 반환되고 세분화됩니다.

세그먼트 리소스 섹션에는 사용 가능한 세그먼트 리소스가 나열되어 있습니다. 일부 리소스에는 세분화 리소스가 없습니다.

다음과 함께 선택 가능

일부 segments 필드는 다른 리소스, 세그먼트, 측정항목과 호환되지 않습니다.

segments 페이지에는 SELECT 절에 포함할 수 있는 모든 호환 리소스 필드, metrics 필드, 기타 segments 필드를 나열하는 각 segments 필드에 대해 선택 가능 확장 프로그램이 포함되어 있습니다.

세분화

쿼리의 SELECT 절에 segments.FIELD_NAME 필드를 추가하여 검색 결과를 분류할 수 있습니다.

예를 들어 아래 쿼리의 segments.device은 FROM 절에 지정된 리소스의 각 기기 impressions에 대한 행이 있는 보고서를 생성합니다.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

SearchAds360Service.SearchStream에서 반환된 결과는 다음과 같은 JSON 문자열과 비슷합니다.

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

사용할 수 있는 세그먼트 필드 목록은 segments을 참고하세요.

여러 세그먼트

쿼리의 SELECT 절에 여러 세그먼트를 지정할 수 있습니다. 대답에는 FROM 절에 지정된 기본 리소스의 인스턴스와 선택된 각 segment 필드의 값의 각 조합에 대해 하나의 SearchAds360Row 객체가 포함됩니다.

예를 들어 다음 쿼리는 campaign, segments.ad_network_type, segments.date의 각 조합에 대해 하나의 행을 반환합니다.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

결과는 선택한 개별 필드의 값이 아닌 기본 리소스의 각 인스턴스별로 암시적으로 분류됩니다.

다음 예시 쿼리는 campaign.status 필드의 고유 값당 하나의 행이 아닌 캠페인당 하나의 행을 반환합니다.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

암시적 분할

모든 보고서는 처음에는 FROM 절에 지정된 리소스별로 분류됩니다. 측정항목은 이 리소스의 resource_name 필드로 분류됩니다.

이 예시 쿼리는 ad_group.resource_name를 자동으로 반환하고 이를 암시적으로 사용하여 ad_group 수준에서 측정항목을 분류합니다.

SELECT metrics.impressions
FROM ad_group

반환된 JSON 문자열은 다음과 유사합니다.

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

핵심 날짜 세그먼트

WHERE 절에서 핵심 날짜 세그먼트를 사용하여 날짜 또는 기간을 지정할 수 있습니다.

다음 세그먼트 필드를 핵심 날짜 세그먼트라고 합니다. segments.date, segments.week, segments.month, segments.quarter, segments.year

이 예시 쿼리는 지난 30일 동안의 캠페인 clicks 측정항목을 반환합니다.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

핵심 날짜 세그먼트 필드는 SELECT 절에도 필드를 포함하지 않는 한 WHERE 절에서 세그먼트 필드를 사용할 수 없다는 일반 규칙의 예외입니다. 자세한 내용은 금지된 필터링을 참고하세요.

핵심 데이터 세그먼트 규칙:

SELECT 절에 포함하지 않고 WHERE 절에서 핵심 날짜 필드를 사용할 수 있습니다. 원하는 경우 두 절에 모두 필드를 포함할 수도 있습니다.

이 예시 쿼리는 기간 동안 캠페인 이름별로 clicks 측정항목을 반환합니다. segments.date는 SELECT 절에 포함되지 않습니다.
```
SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'
```
SELECT 절에 핵심 날짜 필드를 포함하는 경우 WHERE 절에 유한 날짜 또는 기간을 지정해야 합니다. SELECT 및 WHERE 절에 지정된 필드는 일치하지 않아도 됩니다.

이 예시 쿼리는 기간 내 모든 날짜의 캠페인 이름별 clicks 측정항목을 월별로 분류하여 반환합니다.
```
SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'
```

ISO 8601 날짜

YYYY-MM-DD (ISO 8601) 형식을 사용하여 날짜와 날짜 범위를 지정할 수 있습니다. 예를 들면 다음과 같습니다.

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

기간이 필요한 핵심 날짜 세그먼트 (segments.week, segments.month, segments.quarter)의 경우 기간의 첫 번째 날짜와 함께 = 연산자를 사용할 수 있습니다. 예를 들면 다음과 같습니다.

WHERE segments.month = '2022-06-01'

사전 정의된 날짜

다음과 같은 사전 정의된 날짜 및 기간을 사용할 수도 있습니다.

사전 정의된 날짜
`TODAY`	오늘만
`YESTERDAY`	어제만
`LAST_7_DAYS`	오늘을 제외한 이전 7일
`LAST_BUSINESS_WEEK`	이전 5일 영업주 (월요일~금요일)
`THIS_MONTH`	이번 달의 모든 날짜입니다.
`LAST_MONTH`	지난달의 모든 날짜입니다.
`LAST_14_DAYS`	오늘을 제외한 이전 14일
`LAST_30_DAYS`	오늘을 제외한 이전 30일
`THIS_WEEK_SUN_TODAY`	이전 일요일부터 현재 날짜까지의 기간입니다.
`THIS_WEEK_MON_TODAY`	이전 월요일부터 현재 날짜까지의 기간입니다.
`LAST_WEEK_SUN_SAT`	이전 일요일부터 시작되는 7일 기간입니다.
`LAST_WEEK_MON_SUN`	전주 월요일부터 시작하는 7일 기간입니다.

예:

WHERE segments.date DURING LAST_30_DAYS

측정항목이 0개임

쿼리를 실행할 때 일부 항목의 값이 0인 측정항목이 표시될 수 있습니다. 쿼리에서 0 측정항목을 처리하는 방법 알아보기

알 수 없는 열거형 유형

UNKNOWN enum 데이터 유형으로 리소스가 반환되면 API 버전에서 유형이 완전히 지원되지 않는다는 의미입니다. 이러한 리소스는 다른 인터페이스를 통해 생성되었을 수 있습니다. 예를 들어 Search Ads 360 UI에 새 캠페인 또는 광고가 도입되었지만, 쿼리하는 API 버전에서는 아직 지원되지 않습니다.

리소스 유형이 UNKNOWN인 경우에도 측정항목을 선택할 수 있지만 다음 사항에 유의해야 합니다.

UNKNOWN 유형의 리소스는 나중에 지원될 수 있지만 무기한 UNKNOWN로 유지될 수 있습니다.
UNKNOWN 유형의 새 객체는 언제든지 표시될 수 있습니다. 열거형 값을 이미 사용할 수 있으므로 이러한 객체는 이전 버전과 호환됩니다. 이 변경사항에서는 계정을 정확하게 파악할 수 있도록 리소스를 도입합니다. UNKNOWN 리소스는 다른 인터페이스를 통한 계정의 새 활동으로 인해 또는 리소스가 더 이상 공식적으로 지원되지 않기 때문에 표시될 수 있습니다.
UNKNOWN 리소스에는 쿼리할 수 있는 자세한 측정항목이 연결되어 있을 수 있습니다.
UNKNOWN 리소스는 일반적으로 Search Ads 360 UI에 완전히 표시됩니다.