객체 검색

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는 동일한 결과 집합의 다른 행과 다른 속성과 측정항목을 가질 수 있으므로 행은 테이블의 고정된 행이 아닌 객체로 간주되어야 합니다.

UNKNOWN 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 필드의 고유한 값당 하나의 행이 아니라 캠페인당 하나의 행이 생성됩니다.

이전
객체 변경 및 검사
다음
리소스 메타데이터