아래 섹션에서 검색 광고에서 검색 보고서를 만드는 방법을 알아보세요. 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 할당량 및 한도에 영향을 주지 않습니다. 단일 쿼리 또는 보고서는 결과가 페이징되든 스트리밍되든 상관없이 1개의 연산으로 집계됩니다.
검색어 예시
이 쿼리 예시는 지난 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
에 공유
인터페이스에 추가되었습니다.
요청이 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
다음은 보고서에 포함된 searchStream
보고서 정의의 전체 예입니다.
HTTP POST
요청:
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
참조 문서
참조 섹션
각 아티팩트를 올바르게 사용하는 데 필요한 모든 정보가 포함되어 있습니다. 현재
리소스당 페이지 1개(예: ad_group
및
campaign
segments
및 metrics
페이지
사용 가능한 모든 세그먼트 및 측정항목 필드를 나열합니다.
일부 리소스, 세그먼트, 측정항목이 호환되지 않아 사용할 수 없습니다. 서로 완전히 호환되고 상호 보완되는 다른 것들이 있습니다. 각 리소스 페이지에는 다음 정보가 포함되어 있습니다 (있는 경우). 기타 등등:
- 기여 분석 리소스
일부 리소스의 경우 암시적으로 관련 리소스 필드를 함께 선택하여
FROM
절. 예를 들어campaign
리소스는ad_group
리소스의 저작자가 표시된 리소스입니다. 즉,campaign.id
및campaign.bidding_strategy_type
등의 필드를FROM
절에서ad_group
를 사용할 때 쿼리를 실행합니다.기여 분석 리소스 섹션에는 사용 가능한 기여 분석 리소스가 나열됩니다. 비 모든 리소스에는 지정된 리소스가 있습니다.
- 리소스 필드 열
리소스의 모든 필드는 리소스 필드 열에 포함됩니다. 각 리소스 필드는 설명, 카테고리, 데이터 유형, 유형 URL, 필터링 가능, 선택 가능 정렬이 가능하고 반복 설정이 있습니다.
- 분류 기준 열
특정 리소스로 모든 세그먼트 필드를 선택할 수 있는 것은 아닙니다.
세그먼트 열에는
segments
리소스 필드와 동일한SELECT
절을 사용합니다. 각 필드는 전체 설명, 카테고리, 데이터 유형, 유형 등 필드에 대한 세부정보 URL, 필터링, 선택, 정렬, 반복이 가능합니다. 만약FROM
절의 리소스를 사용하여 원하는 경우 Yes/No 드롭다운을 사용할 수 있습니다. 사용할 수 없는 세그먼트를 필터링할 수 있습니다.- 측정항목 열
특정 리소스로 모든 측정항목 필드를 선택할 수 있는 것은 아닙니다.
Metrics(측정항목) 열에는
metrics
필드 목록이 리소스 필드와 동일한SELECT
절을 사용합니다. 각 필드는 전체 설명, 카테고리, 데이터 유형, 유형 등 필드에 대한 세부정보 URL, 필터링, 선택, 정렬, 반복이 가능합니다. 만약FROM
절의 리소스를 사용하려면 Yes/No 드롭다운을 사용하여 사용할 수 없는 측정항목을 필터링합니다. 를 통해 개인정보처리방침을 정의할 수 있습니다.
- 리소스 세분화
일부 리소스에는 다음과 같은 경우에 선택할 수 있는 세분화 리소스 필드가 있습니다. 리소스는
FROM
절에 있습니다. 예를 들어 다음과 같은campaign
리소스 필드를 선택하는 경우campaign.name
인 경우FROM
절에서campaign_budget
사용,campaign.resource_name
campaign
가campaign_budget
의 세분화 리소스.리소스 세분화 섹션에는 사용 가능한 세분화 리소스가 나열됩니다. 비 모든 리소스에는 분할 리소스가 있습니다.
- 선택 가능한 옵션
일부
segments
필드가 다른 리소스, 세그먼트 및 필드와 호환되지 않습니다. 측정항목입니다.segments
페이지 여기에는 Selectable with(선택 가능 함수)가 포함되어 있습니다.segments
호환되는 모든 리소스 필드,metrics
필드, 기타segments
를 나열합니다.SELECT
절에 포함할 수 있는 필드입니다. 를 통해 개인정보처리방침을 정의할 수 있습니다.
세분화
검색 결과를 분류할 수 있는
segments.FIELD_NAME
필드를 쿼리의 SELECT
절에 추가합니다.
예를 들어segments.device
쿼리를 실행하면 각 항목의 impressions
에 대한 행이 포함된 보고서가 생성됩니다.
FROM
절에 지정된 리소스의 기기입니다.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
SearchAds360Service.SearchStream
에서 반환된 결과가 표시됩니다.
다음과 같습니다.
{
"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
절에서 여러 세그먼트를 지정할 수 있습니다. 이
응답의 각 조합당 하나의 SearchAds360Row
객체가 포함됩니다.
FROM
절에 지정된 기본 리소스의 인스턴스 및
선택한 각 필드의 값입니다.segment
예를 들어 다음 쿼리는
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
핵심 날짜 세그먼트 필드는 일반 규칙의 예외입니다.
는 WHERE
절에 세그먼트 필드를 사용할 수 없습니다.
필드를 SELECT
절에 포함합니다. 자세한 내용은 금지된 필터링을 참고하세요.
확인할 수 있습니다
핵심 기간 세그먼트 규칙:
핵심 날짜 필드를
WHERE
절에 포함하지 않고도 사용할 수 있습니다.SELECT
절. 원하는 경우 두 절 모두에 필드를 포함할 수도 있습니다.이 쿼리 예시는 해당 날짜 동안 캠페인 이름별로
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 유형
리소스가 UNKNOWN
enum 데이터 유형으로 반환되면
유형이 API 버전에서 완전히 지원되지 않습니다. 이러한 리소스는
다른 인터페이스를 통해 생성된 소스입니다. 예를 들어 새 캠페인이나 광고는
Search Ads 360 UI에 도입되었지만 API 버전에서는 아직 지원되지 않습니다.
확인할 수 있습니다
리소스가 UNKNOWN
유형인 경우에도 측정항목을 선택할 수 있지만
다음 사항에 유의해야 합니다.
UNKNOWN
유형의 리소스는 나중에 지원될 수도 있지만 그대로 유지될 수도 있습니다.UNKNOWN
무기한- 유형이
UNKNOWN
인 새 객체는 언제든지 나타날 수 있습니다. 이러한 객체는 enum 값을 이미 사용할 수 있으므로 이전 버전과 호환됩니다. Google은 이 변경사항으로 리소스를 모두 사용할 수 있게 되면 확인할 수 있습니다.UNKNOWN
리소스는 새로운 리소스 및 기타 상호작용으로 인해 더 이상 공식적으로 지원되지 않습니다. - 리소스
UNKNOWN
개에 다음과 같은 세부 측정항목이 연결되어 있을 수 있습니다. 쿼리합니다. UNKNOWN
리소스는 일반적으로 Search Ads 360 UI에 전체가 표시됩니다.