쿼리 구조

리소스, 세그먼트, 측정항목 필드의 쿼리를 GoogleAdsService Search 또는 SearchStream 메서드를 참조하세요. Google Ads 쿼리 언어로 쿼리를 작성하려면 언어 문법. 쿼리는 절:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

절에서는 필드 이름, 리소스 이름, 연산자, 조건, orderings: 올바른 데이터를 선택하는 데 도움이 됩니다. 이 작업은 Google Ads API를 사용하여 요청할 수 있습니다.

핵심사항: GoogleAdsFieldService 모든 리소스에 대한 메타데이터가 포함된 Google Ads 쿼리 언어 클라이언트용 카탈로그를 제공합니다. 세그먼트 필드, 측정항목, 각 측정항목과의 관계 '기타'와 '가용성'이라는 표현이 포함될 수 있습니다. 자세한 내용은 GoogleAdsField 문서를 참고하세요.

조항

동영상: GAQL 필드 호환성

SELECT

SELECT 절은 요청에서 가져올 필드 집합을 지정합니다. SELECT는 쉼표로 구분된 리소스 필드, 세그먼트 필드, 응답에서 값을 반환합니다. SELECT 절은 다음과 같습니다. 필수입니다.

아래 샘플 쿼리는 지정된 리소스:

SELECT
  campaign.id,
  campaign.name
FROM campaign

단일 요청에서 다양한 필드 유형을 요청할 수 있습니다. 예를 들면 다음과 같습니다.

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

• 리소스 필드

  • campaign.id
  • campaign.name

• 리소스 필드

  • bidding_strategy.id
  • bidding_strategy.name

• 세그먼트 필드

  • segments.device
  • segments.date

• 측정항목

  • metrics.impressions
  • metrics.clicks

다음과 같은 이유로 일부 필드는 SELECT 절에서 허용되지 않을 수 있습니다. 제한:

• 선택할 수 없는 필드 쿼리 이러한 필드에는 Selectable 메타데이터 속성이 false(으)로 표시되었습니다.
• 반복되는 필드의 속성 선택 이러한 필드에는 isRepeated 메타데이터 속성이 true(으)로 표시되었습니다.
• FROM에서 지정된 리소스에 사용할 수 없는 필드 선택 절. 일부 리소스의 속성은 함께 선택할 수 없으며 모든 측정항목 및 세그먼트의 하위 집합을 FROM 절.
• 서로 호환되지 않는 세그먼트 또는 측정항목을 선택하는 경우 대상 자세한 내용은 세분화 섹션을 참조하세요.

위 조건과 관련된 정보는 참조 문서에서 확인할 수 있습니다. 또는 GoogleAdsFieldService부터.

FROM

FROM 절은 반환될 기본 리소스를 지정합니다. 이 FROM 절의 리소스는 다른 모든 필드를 사용할 수 있는 필드를 정의합니다. 절을 반환합니다. 하나의 리소스만 FROM 절. FROM 절은 다음 쿼리에서 필수입니다. GoogleAdsService Search 또는 SearchStream 그러나 GoogleAdsFieldService를 탭합니다.

주어진 쿼리의 FROM 절에는 리소스가 1개만 존재할 수 있지만 도 사용할 수 있습니다. 이러한 리소스는 암시적으로 FROM 절의 리소스와 조인되므로 다음과 같은 작업만 수행하면 됩니다. SELECT 절에 해당 속성을 추가하여 값을 반환합니다. 일부 리소스에 기여 분석 리소스가 있습니다. 다음 예에서는 광고 그룹 ID 및 광고 그룹의 캠페인 ID:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

기본 리소스의 resource_name 필드는 항상 반환됩니다. 다음 예에서 ad_group.resource_name는 명시적으로 선택되지 않은 경우에도 응답을 반환할 수 있습니다.

SELECT ad_group.id
FROM ad_group

하나 이상의 필드가 선택된 경우 다른 리소스도 마찬가지입니다. 예를 들어 campaign.resource_name는 다음 항목에 대한 응답에 포함됩니다. 다음 쿼리를 실행합니다.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

핵심사항: FROM 절의 리소스가 다른 리소스를 segment를 클릭한 다음 해당 리소스의 속성을 선택하면 세그먼트로 작동합니다.

WHERE

WHERE 절은 합니다. WHERE 절을 사용하면 조건을 하나 이상 지정할 수 있습니다. AND를 사용하여 구분합니다. 각 조건은 패턴을 따라야 합니다. field_name Operator value 쿼리에서 WHERE 절은 선택사항입니다.

다음은 WHERE를 사용하여 지정된 시간의 측정항목을 반환하는 예입니다. 기간:

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

여러 조건을 결합하여 데이터를 필터링할 수 있습니다. 이 예에서는 모바일에서 노출이 발생한 모든 캠페인에 대해 최근 30일

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

WHERE 절의 세그먼트는 SELECT 절 내에 있어야 하며 핵심 기간이라고 하는 다음 기간 세그먼트 다음과 같은 예외가 적용됩니다.

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

다음 쿼리에서는 segments.date가 선택되어 있습니다. 이 세그먼트는 핵심 기간 세그먼트이므로 유한한 날짜가 필요합니다. 제공되어야 하는 WHERE 절의 핵심 기간 세그먼트로 구성된 기간입니다.

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

위의 조건을 충족하는 모든 세그먼트는segment.date, segments.week, 세그먼트.개월, 세그먼트.분기, 세그먼트.연도. 이러한 세그먼트 중 하나라도 선택되면 WHERE 절에서 이들 중 하나 이상을 사용해야 합니다.

핵심사항: 구분자 AND는 연산자 조건 사이에만 사용할 수 있습니다. (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") 및 다음 제외: 단일 연산자 조건 (WHERE segments.device != "DESKTOP" AND "MOBILE") 내

필터링할 때 연산자의 대소문자 구분이 중요합니다. 생각해야 합니다. 자세한 내용은 대소문자 구분을 참고하세요.

연산자 전체 목록은 언어 문법을 따릅니다.

ORDER BY

ORDER BY 절은 결과가 나오는 순서를 지정합니다. 반환합니다. 이렇게 하면 데이터를 오름차순 또는 내림차순으로 정렬할 수 있습니다. 필드 이름을 기반으로 합니다 각 순서 지정은 field_name 뒤에 오는 ASC 또는 DESC입니다. ASC와 DESC 중 어느 것도 지정하지 않으면 순서가 기본값으로 설정됩니다. ASC님에게 전송됩니다. 쿼리에서 ORDER BY 절은 선택사항입니다.

다음 쿼리는 내림차순으로:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

쉼표로 구분된 다음 행을 사용하여 ORDER BY 절에 여러 필드를 지정할 수 있습니다. 목록. 순서는 쿼리에 지정된 것과 동일한 순서로 발생합니다. 예를 들어 이 쿼리에서는 광고 그룹 데이터를 선택하면 결과가 정렬됩니다. 캠페인 이름별 오름차순으로 정렬한 다음 클릭수를 클릭수에 따라 내림차순으로 정렬합니다.

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

LIMIT 절을 사용하면 반환할 결과 수를 지정할 수 있습니다. 이 기능은 요약에만 관심이 있는 경우에 유용합니다.

예를 들어 LIMIT를 사용하면 다음 쿼리를 실행합니다.

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

핵심사항: LIMIT를 사용하면 결과를 자를 수 있습니다. page_size 필드 사용 (GoogleAdsService.Search) 처리할 수 있습니다.

PARAMETERS

PARAMETERS 절을 사용하면 요청에 메타 매개변수를 지정할 수 있습니다. 이러한 매개변수는 반환되는 행의 종류에 영향을 줄 수 있습니다.

현재 다음과 같은 메타 매개변수가 지원됩니다.

include_drafts

초안 항목이 반환될 수 있도록 include_drafts를 true로 설정합니다. 기본값은 false입니다.

예를 들어 다음 쿼리는 일반 캠페인과 함께 임시 캠페인을 가져옵니다. 캠페인:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

omit_unselected_resource_names를 true로 설정하여 명시적으로 요청하지 않는 한 응답의 각 리소스 유형이 반환되지 않도록 합니다. (SELECT 절에서) 기본값은 false입니다.

참고: 반환된 객체를 업데이트 또는 삭제에 사용하려는 경우 이 옵션을 false로 설정하는 것이 좋습니다. 리소스 이름이 없는 리소스는 변경 작업에 사용할 수 없습니다. 만약 이 옵션을 true에 할당하려면 두 클러스터의 리소스 이름을 명시적으로 요청해야 합니다. 기본 리소스 및 쿼리를 사용하여 가져오는 모든 속성 리소스에 적용됩니다.

생략_unselected_resource_names 예
SELECT campaign.name, customer.id FROM campaign	Returned resources: <ph type="x-smartling-placeholder">campaign.resource_name customer.resource_name</ph> omit_unselected_resource_names는 기본값이 false이므로 모든 resource_name 필드가 반환됩니다.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: 없음. omit_unselected_resource_names가 true로 지정됩니다. 및 campaign.resource_name 및 customer.resource_name SELECT 절의 일부가 아닙니다.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resource: <ph type="x-smartling-placeholder">campaign.resource_name</ph> omit_unselected_resource_names이 true로 지정됩니다. 및 campaign.resource_name 요청 SELECT 절.

추가 언어 규칙

Google Ads 쿼리 언어는 각 절의 예 외에도 다음과 같은 기능을 제공합니다. 활용할 수 있는 행동은 다음과 같습니다.

• 기본 리소스 필드가 SELECT에 있을 필요는 없습니다. 절이 있어야 합니다. 예를 들어 하나 이상의 기본 데이터를 필터링할 리소스 필드:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• 측정항목은 특정 리소스에 대해서만 선택할 수 있습니다. 다른 필드 없음 가 쿼리에 필요합니다.

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• 수반되는 리소스 필드 없이 세분화 필드를 선택할 수 있음 측정항목:

  SELECT segments.device FROM campaign
  

• resource_name 필드 (예: campaign.resource_name)는 다음과 같을 수 있습니다. 데이터 필터링 또는 정렬에 사용됩니다.

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'