Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Google Ads 쿼리 언어

주요 용어

리소스: Google Ads의 항목(예: campaign 또는 ad_group)입니다.
세그먼트: 데이터를 그룹화하는 데 사용되는 측정기준입니다(예: segments.date 또는 segments.device). 세그먼트가 측정항목과 함께 SELECT 절에 포함되면 측정항목이 세그먼트별로 분할됩니다.
측정항목: metrics.impressions 또는 metrics.clicks와 같은 실적 측정입니다.
기여 리소스: FROM 절에서 기본 리소스에 암시적으로 조인되어 기본 리소스 속성과 함께 해당 속성을 선택할 수 있는 리소스입니다.

리소스 또는 메타데이터 정보 쿼리

Google Ads 쿼리 언어는 Google Ads API에서 다음 유형의 정보를 쿼리할 수 있습니다.

GoogleAdsService 검색 또는 SearchStream을 사용하는 리소스 및 관련 속성, 세그먼트, 측정항목: GoogleAdsService 쿼리의 결과는 GoogleAdsRow 인스턴스의 목록이며, 각 GoogleAdsRow는 리소스를 나타냅니다.

속성 또는 측정항목이 요청되면 행에 해당 필드도 포함됩니다. 세그먼트가 요청되면 응답에는 각 세그먼트-리소스 튜플에 대한 추가 행도 표시됩니다.
GoogleAdsFieldService의 사용 가능한 필드 및 리소스에 대한 메타데이터: 이 서비스는 호환성 및 유형에 대한 세부정보가 포함된 쿼리 가능한 필드의 카탈로그를 제공합니다.

GoogleAdsFieldService 쿼리의 결과는 GoogleAdsField 인스턴스의 목록이며, 각 GoogleAdsField에는 요청된 필드에 대한 세부정보가 포함됩니다.

쿼리 구조에 대한 자세한 내용은 쿼리 구조 및 Google Ads Query Language 문법을 참고하세요.

리소스 속성 쿼리

다음은 캠페인 ID, 이름, 상태를 반환하는 방법을 보여주는 캠페인 리소스 속성에 대한 기본 쿼리의 예입니다.

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

이 쿼리는 캠페인 ID를 기준으로 정렬합니다. 각 결과 GoogleAdsRow는 캠페인의 resource_name를 포함하여 선택한 필드로 채워진 campaign 객체를 나타냅니다.

캠페인 쿼리에 사용할 수 있는 다른 필드를 알아보려면 Campaign 참고 문서를 참고하세요.

측정항목 쿼리

특정 리소스에 대해 선택한 속성과 함께 관련 측정항목을 쿼리할 수도 있습니다.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

이 쿼리는 상태가 PAUSED이고 노출수가 1, 000회를 초과하는 캠페인만 필터링하고 캠페인 ID를 기준으로 정렬합니다. 각 결과 GoogleAdsRow에는 선택한 측정항목으로 채워진 metrics 필드가 있습니다.

쿼리 가능한 측정항목 목록은 Metrics 문서를 참조하세요.

세그먼트 쿼리

특정 리소스에 대해 선택한 속성과 함께 관련 세그먼트를 쿼리할 수도 있습니다.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

측정항목을 쿼리하는 것과 마찬가지로 이 쿼리는 상태가 PAUSED이고 노출수가 1, 000회를 초과하는 캠페인만 필터링합니다. 하지만 이 쿼리는 데이터를 날짜별로 분류합니다. 이렇게 하면 각 결과 GoogleAdsRow가 캠페인과 날짜 세그먼트의 튜플을 나타냅니다. 분류는 선택한 측정항목을 분할하여 SELECT 절의 각 세그먼트별로 그룹화합니다.

쿼리 가능한 세그먼트 목록은 Segments 문서를 참고하세요.

특정 리소스에 대한 쿼리에서 가능한 경우 다른 관련 리소스와 조인할 수 있습니다. 이러한 관련 리소스를 '기여 분석 리소스'라고 합니다. 쿼리에서 속성을 선택하여 속성이 지정된 리소스에 암시적으로 조인할 수 있습니다.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

이 쿼리는 캠페인 속성을 선택할 뿐만 아니라 선택한 각 캠페인에서 관련 속성을 가져옵니다. 각 결과 GoogleAdsRow는 선택한 캠페인 속성과 선택한 입찰 전략 속성 bidding_strategy.name로 채워진 campaign 객체를 나타냅니다.

캠페인 쿼리에 사용할 수 있는 기여 분석 리소스를 확인하려면 Campaign 참고 문서를 참고하세요.

권장사항

긴 응답 시간과 시간 초과를 방지하려면 필요한 필드만 선택하세요.
개발 및 테스트 중에 LIMIT를 사용하여 대규모 결과 집합을 처리하지 않도록 합니다.
WHERE 절에 필터를 적용하여 데이터 전송 및 응답 크기를 최소화합니다.
복잡한 쿼리를 구성하기 전에 GoogleAdsFieldService를 사용하여 필드 호환성과 데이터 유형을 확인합니다.
일부 필드, 특히 대량의 데이터나 복잡한 계산이 포함된 필드는 쿼리 비용을 증가시킬 수 있습니다.

쿼리 결과를 기반으로 변형

특정 리소스를 쿼리할 때 반환된 결과를 즉시 객체로 가져와 수정하고 해당 리소스 서비스의 변형 메서드로 다시 보낼 수 있습니다. 다음은 샘플 워크플로입니다.

노출수가 1,000회를 초과하는 모든 PAUSED 캠페인에 대해 쿼리를 실행합니다.
응답에서 각 GoogleAdsRow의 campaign 필드에서 Campaign 객체를 가져옵니다.
각 캠페인의 상태를 PAUSED에서 ENABLED(으)로 변경합니다.
수정된 캠페인과 해당 FieldMask를 사용하여 CampaignService.MutateCampaigns를 호출하여 업데이트합니다.

필드 메타데이터

GoogleAdsFieldService에 전송되는 쿼리는 필드 메타데이터를 검색하기 위한 것입니다. 이 정보를 사용하여 쿼리에서 필드를 함께 사용하는 방법을 이해할 수 있습니다. API에서 데이터를 사용할 수 있고 쿼리를 검증하거나 빌드하는 데 필요한 메타데이터를 제공하므로 개발자가 프로그래매틱 방식으로 이를 수행할 수 있습니다. 다음은 메타데이터에 대한 일반적인 쿼리입니다.

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

이 쿼리의 <INSERT_RESOURCE_OR_FIELD>를 리소스 (예: customer 또는 campaign) 또는 필드 (예: campaign.id, metrics.impressions 또는 ad_group.id)로 바꿀 수 있습니다.

쿼리 가능한 필드 목록은 GoogleAdsField 문서를 참조하세요.

버전별 차이점

Google Ads Query Language 문법, 절, 연산자는 지원되는 모든 Google Ads API 버전 (v23, v24, v25, v26)에서 동일하지만 쿼리 가능한 리소스, 세그먼트, 측정항목, 보고 동작의 카탈로그는 메이저 버전에 따라 다릅니다. 대상 API 버전 엔드포인트에서 GoogleAdsFieldService를 쿼리하여 해당 버전의 필드와 호환성 규칙을 검사합니다.

최종 URL 확장 확장 소재 보기:
- 쇼핑 캠페인 지원 (v26 이상): final_url_expansion_asset_view는 실적 최대화 캠페인 및 검색 캠페인 외에도 쇼핑 캠페인 (campaign.advertising_channel_type = 'SHOPPING')을 지원합니다. 쇼핑 캠페인의 경우 ad_group 필드를 선택하고 필터링할 수 있지만 asset_group 필드는 선택할 수 없습니다.
- 선택 가능한 측정항목 (v25 이상): final_url_expansion_asset_view를 쿼리하면 뷰에 선택 가능한 모든 측정항목이 반환됩니다. v24 이하에서는 응답에 실적 최대화 캠페인의 경우 metrics.conversions 및 metrics.conversions_value만, 검색 캠페인의 경우 metrics.impressions만 포함됩니다.
라이프사이클 목표 리소스: v25 이상에서는 모든 라이프사이클 목표 (신규 고객 확보, 이탈 고객 확보, 충성도 유지)가 통합된 goal 및 campaign_goal_config 리소스에서 쿼리되어 customer_lifecycle_goal 및 campaign_lifecycle_goal (v24 이하에서 신규 고객 확보 목표에 사용되었으며 이탈 고객 확보 목표에는 goal 및 campaign_goal_config가 사용됨)를 대체합니다.
앱 캠페인의 쇼핑 제품 보고: v24 이상에서 shopping_product 리소스는 쇼핑, 실적 최대화, 디맨드젠 캠페인, 동영상 캠페인 외에도 앱 캠페인의 제품 행을 반환합니다 (v23에서는 앱 캠페인이 shopping_product 결과에서 제외됨).
버전별 리소스, 세그먼트, 측정항목:
- v26 이상: search_lift_keyword_bundle 리소스, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property, 검색 광고효과 측정항목 (예: metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros, metrics.search_lift_impressions)이 포함됩니다.
- v25 이상: 광고효과 측정 리소스(예: lift_measurement_config), 세그먼트(예: segments.ad_sub_format_type 및 segments.loyalty_membership), YouTube 참여도 측정항목(metrics.youtube_likes, metrics.youtube_comments, metrics.youtube_shares)이 포함됩니다. local_services_lead.contact_details.email(v24 이하에서 선택 가능)가 삭제됩니다.
- v24 이상: cart_data_sales_view 리소스, shopping_performance_view의 segments.conversion_attribution_event_type, segments.mobile_device_platform, performance_max_placement_view의 segments.ad_network_type가 포함됩니다. campaign.video_brand_safety_suitability(customer.video_brand_safety_suitability로 대체됨), campaign_budget의 segments.ad_sub_network_type, ad_group_asset, campaign_asset, customer_asset의 segments.click_type(v23에서만 선택 가능)를 삭제합니다.
세분화된 날짜 전환 확인 기간 오류 코드: 37개월 전환 확인 기간을 초과하여 segments.date, segments.week 또는 segments.hour로 분류하거나 월 미만의 기간으로 필터링하는 쿼리는 v24 이상에서 DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED를 반환하거나 v23에서 DateRangeError.UNKNOWN를 반환합니다. 자세한 내용은 기간을 참고하세요.

코드 예시

클라이언트 라이브러리에는 GoogleAdsService에서 Google Ads Query Language를 사용하는 예가 있습니다. 기본 작업 폴더에는 GetCampaigns, GetKeywords, SearchForGoogleAdsFields와 같은 예시가 있습니다.

쿼리 문법