객체 검색

목표: GoogleAdsService를 사용하여 객체와 성능 통계를 검색하는 방법을 이해합니다. 보고 개념은 보고 가이드를 참고하세요.

GoogleAdsService는 Google Ads API의 통합 객체 검색 및 보고 서비스입니다. 이 서비스에는 다음과 같은 메서드가 있습니다.

• 객체의 특정 속성을 검색합니다.
• 기간을 기준으로 객체의 성능 측정항목을 가져옵니다.
• 속성에 따라 객체의 순서를 지정합니다.
• 조건을 사용하여 응답으로 반환될 객체를 지정하세요.
• 반환되는 객체의 수를 제한합니다.

GoogleAdsService는 다음 두 가지 방법으로 결과를 반환할 수 있습니다.

• GoogleAdsService.SearchStream는 단일 스트리밍 응답으로 모든 행을 반환하며 이는 행 수가 10,000개를 초과하는 큰 결과 집합에 더 효율적입니다. 일괄 애플리케이션이 가능한 한 많은 데이터를 빠르게 다운로드하려는 경우 이 방법이 더 적합할 수 있습니다.
• GoogleAdsService.Search는 큰 응답을 관리하기 쉬운 결과 페이지로 나눕니다. 대화형 애플리케이션이 한 번에 결과 페이지를 표시하는 경우에 더 적합할 수 있습니다.

페이징과 스트리밍 비교에 대해 자세히 알아보세요.

요청하기

검색 메서드에는 다음 속성으로 구성된 SearchGoogleAdsRequest가 필요합니다.

• customer_id
• Google Ads 쿼리 언어 query는 쿼리할 리소스, 검색할 속성, 세그먼트, 측정항목, 반환되는 객체를 제한하는 데 사용할 조건을 나타냅니다.
• (GoogleAdsService.Search만 해당) 페이징을 사용할 때 단일 응답으로 반환할 객체 수를 나타내는 page_size.
• (GoogleAdsService.Search만 해당) 페이징을 사용할 때 다음 결과 배치를 검색할 선택적 page_token입니다.

Google Ads 쿼리 언어에 대한 자세한 내용은 Google Ads 쿼리 언어 가이드를 참고하세요.

응답 처리

GoogleAdsService는 GoogleAdsRow 객체 목록을 반환합니다.

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

예를 들어 ad_group_criterion에 status 속성이 있지만 SELECT 절에 ad_group_criterion.status가 포함되지 않은 쿼리의 응답에서 행의 ad_group_criterion 속성의 status 필드는 채워지지 않습니다. 마찬가지로, SELECT 절에 campaign 리소스의 필드가 없으면 행의 campaign 속성이 채워지지 않습니다.

각 GoogleAdsRow은 동일한 결과 집합에 있는 다른 행의 속성과 측정항목을 가질 수 있습니다. 따라서 행은 테이블의 고정된 행이 아닌 객체로 보아야 합니다.

알 수 없는 enum 유형

UNKNOWN 유형으로 반환되는 리소스는 해당 API 버전에서 완전히 지원되지 않습니다. 이러한 리소스는 Google Ads UI와 같은 다른 인터페이스를 통해 생성되었을 수 있습니다. 리소스의 유형이 UNKNOWN인 경우 측정항목을 선택할 수 있지만 API를 통해 리소스를 변경할 수는 없습니다. UI에서 도입되었지만 쿼리 중인 API 버전에서는 지원되지 않는 새 캠페인 또는 광고를 예로 들 수 있습니다.

다음은 유의해야 할 몇 가지 고려사항입니다.

• UNKNOWN 유형의 리소스는 나중에 지원되거나 UNKNOWN로 무기한 유지될 수 있습니다.
• UNKNOWN 유형의 새 객체는 언제든지 표시될 수 있습니다. 이러한 객체는 enum 값을 이미 사용할 수 있으므로 이전 버전과 호환됩니다. 계정을 정확하게 확인할 수 있도록 사용 가능해지면 이 변경사항과 함께 리소스가 도입됩니다. UNKNOWN 리소스는 다른 인터페이스를 통한 계정의 새 활동으로 인해 또는 리소스가 더 이상 지원되지 않는 경우에 표시될 수 있습니다.
• UNKNOWN 리소스에는 쿼리 가능한 세부 측정항목이 연결될 수 있습니다.
• UNKNOWN 리소스는 일반적으로 Google Ads UI에 완전히 표시됩니다.
• UNKNOWN 리소스는 일반적으로 변경할 수 없습니다.

세분화

응답에는 다음의 조합마다 하나의 GoogleAdsRow가 포함됩니다.

• FROM 절에 지정된 기본 리소스의 인스턴스입니다.
• 선택한 각 segment 필드의 값

예를 들어 FROM campaign을 선택하고 SELECT 절에 segments.ad_network_type과 segments.date가 있는 쿼리의 응답에는 다음 조합마다 행이 하나씩 포함됩니다.

• campaign
• segments.ad_network_type
• segments.date

결과는 선택한 개별 필드의 값이 아닌 기본 리소스의 각 인스턴스별로 암시적으로 세분화됩니다. 예를 들면 다음과 같습니다.

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

그러면 campaign.status 필드의 고유한 값당 하나의 행이 아니라 캠페인당 하나의 행이 됩니다.