객체 가져오기

GoogleAdsService는 Google Ads API의 통합 객체 검색 및 보고 서비스입니다. 서비스에는 다음을 수행하는 메서드가 있습니다.

  • 객체의 특정 속성을 가져옵니다.
  • 기간을 기반으로 객체의 성능 측정항목을 가져옵니다.
  • 속성을 기준으로 객체를 정렬합니다.
  • 조건을 사용하여 응답에서 반환할 객체를 나타냅니다.
  • 반환되는 객체 수를 제한합니다.

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

  • GoogleAdsService.SearchStream는 단일 스트리밍 응답에서 모든 행을 반환하므로 대규모 (10,000개 이상의 행) 결과 세트에 더 효율적입니다. 애플리케이션이 전체 결과 집합을 다운로드하거나 스트림으로 행을 처리하는 경우 이 방법을 사용하는 것이 좋습니다.
  • GoogleAdsService.Search는 큰 대답을 관리 가능한 결과 페이지로 나눕니다. 대화형 애플리케이션이 한 번에 결과 페이지를 표시하는 경우에 유용합니다.

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

요청하기

GoogleAdsService.SearchStream에는 SearchGoogleAdsStreamRequest이 필요하고 GoogleAdsService.Search에는 SearchGoogleAdsRequest이 필요합니다. 두 요청 유형 모두 다음을 포함합니다.

  • customer_id
  • 쿼리할 리소스, 가져올 속성, 세그먼트, 측정항목, 반환되는 객체를 제한하는 데 사용할 조건을 나타내는 Google Ads 쿼리 언어 query

메서드에 따라 요청은 메서드별 필드도 지원합니다.

  • SearchGoogleAdsStreamRequest (SearchStream만 해당):
  • SearchGoogleAdsRequest (Search만 해당):
    • 페이지로 나누기를 사용할 때 다음 결과 배치를 가져오는 선택적 page_token입니다 (page_size는 10,000개 행으로 고정됨. 요청에서 page_size를 설정하면 RequestError.PAGE_SIZE_NOT_SUPPORTED 오류가 발생함).
    • return_summary_row, return_total_results_count, omit_results을 구성하는 선택적 search_settings 메시지
    • 쿼리를 실행하지 않고 검증하는 선택적 validate_only 불리언입니다.

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

응답 처리

GoogleAdsService는 스트리밍된 SearchGoogleAdsStreamResponse 배치 내 또는 페이지로 구분된 SearchGoogleAdsResponse에 있는 GoogleAdsRow 객체 목록을 반환합니다.

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

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

각 GoogleAdsRow에는 동일한 결과 집합의 다른 행과 다른 속성과 측정항목이 있을 수 있으므로 행은 테이블의 고정된 행이 아닌 객체로 간주해야 합니다.

UNKNOWN 및 UNSPECIFIED enum 유형

열거형 값이 UNKNOWN인 리소스는 해당 API 버전에서 완전히 지원되지 않으며, UNSPECIFIED는 열거형 필드가 설정되지 않았거나 SELECT 절에서 요청되지 않았음을 나타냅니다. UNKNOWN 열거형 값이 있는 리소스는 Google Ads UI와 같은 다른 인터페이스를 통해 생성되었을 수 있습니다. 리소스 유형이 UNKNOWN인 경우 측정항목을 선택할 수 있지만 API를 통해 리소스를 변경할 수는 없습니다. 이러한 예로는 UI에서 사용할 수 있지만 쿼리하는 API 버전에서는 지원되지 않는 캠페인 또는 광고 유형이 있습니다.

다음과 같은 사항을 고려해 보세요.

  • UNKNOWN 유형의 리소스는 이후 API 버전에서 지원되거나 무기한 UNKNOWN로 유지될 수 있습니다.
  • UNKNOWN 유형의 새 객체는 언제든지 표시될 수 있습니다. 이러한 객체는 UNKNOWN enum 값이 API의 모든 enum에 있으므로 하위 호환됩니다. 계정의 전반적인 실적 측정항목을 정확하게 파악할 수 있도록 리소스가 UNKNOWN와 함께 반환됩니다.
  • UNKNOWN 리소스에는 쿼리할 수 있는 자세한 측정항목이 연결될 수 있습니다.
  • UNKNOWN 리소스는 일반적으로 Google Ads UI에 완전히 표시됩니다.
  • UNKNOWN 리소스는 일반적으로 API를 통해 변경할 수 없습니다.

세분화

응답에는 다음 각 조합에 대한 GoogleAdsRow가 하나씩 포함됩니다.

  • FROM 절에 지정된 기본 리소스의 인스턴스
  • 선택한 각 segments 필드의 값

예를 들어 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 필드의 고유 값당 하나의 행이 아닌 캠페인당 하나의 행이 표시됩니다.

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