이 가이드에서는 Google Ads API를 구성하는 기본 구성요소를 소개합니다. Google Ads API는 리소스와 서비스로 구성됩니다. 리소스는 Google Ads 항목을 나타내고 서비스는 Google Ads 항목을 가져오고 조작합니다.
객체 계층 구조
Google Ads 계정은 객체의 계층 구조로 볼 수 있습니다.
계정의 최상위 리소스는 고객입니다.
각 고객은 하나 이상의 활성 캠페인을 포함합니다.
각 캠페인에는 광고를 논리적 모음으로 그룹화하는 데 사용되는 하나 이상의 광고 그룹이 포함됩니다.
광고 그룹 광고는 광고 그룹에서 게재하는 광고를 나타냅니다. 광고 그룹당 하나의 광고 그룹 광고만 포함할 수 있는 앱 캠페인을 제외하고 각 광고 그룹에는 하나 이상의 광고 그룹 광고가 포함됩니다.
실적 최대화 캠페인은 다른 캠페인 유형과 다른 구조를 사용합니다. 실적 최대화 캠페인에는 광고 그룹 및 광고 그룹 광고 대신 애셋 그룹이 포함됩니다. AssetGroupAsset를 사용하여 광고 소재 애셋을 애셋 그룹에 연결하고 AssetGroupSignal를 사용하여 잠재고객 또는 검색 테마 신호를 연결합니다.
하나 이상의 AdGroupCriterion 또는 CampaignCriterion 리소스를 광고 그룹 또는 캠페인에 연결할 수 있습니다. 광고가 트리거되는 방식을 정의하는 기준을 나타냅니다.
키워드, 연령대, 위치 등 다양한 기준 유형이 있습니다. 캠페인 수준에서 정의된 기준은 캠페인 내의 다른 모든 리소스에 영향을 미칩니다. AdGroupAd.start_date_time 및 AdGroupAd.end_date_time를 사용하여 캠페인 또는 개별 광고의 예산, 시작 및 종료 날짜와 시간을 지정할 수도 있습니다.
마지막으로 계정, 캠페인, 광고 그룹 또는 애셋 그룹 수준에서 확장 소재를 연결할 수 있습니다. 확장 소재를 사용하면 전화번호, 상세 주소, 프로모션과 같은 추가 정보를 광고에 제공할 수 있습니다. 애셋 개요를 참고하세요.
리소스
리소스는 Google Ads 계정 내의 항목을 나타냅니다.
Campaign 및 AdGroup은 리소스의 두 가지 예입니다.
객체 ID
Google Ads의 모든 객체는 자체 ID로 식별됩니다. 이러한 ID 중 일부는 모든 Google Ads 계정에서 전역적으로 고유한 반면, 일부는 제한된 범위 내에서만 고유합니다.
| 객체 ID | 고유성 식별 범위 | 글로벌 수준에서 식별 가능 |
|---|---|---|
| 예산 ID | 전역 | 예 |
| 캠페인 ID | 글로벌 수준 | 예 |
| AdGroup ID | 전역 | 예 |
| 광고 ID | 광고그룹 | 아니요. 하지만 (AdGroupId, AdId) 쌍은 전역적으로 고유합니다. 여러 광고 그룹에서 AdId을 공유하는 것은 금지됩니다. |
| AdGroupCriterion ID | 광고그룹 | 아니요, 하지만 (AdGroupId, CriterionId) 쌍은 전역적으로 고유합니다. |
| CampaignCriterion ID | 캠페인 | 아니요, 하지만 (CampaignId, CriterionId) 쌍은 전역적으로 고유합니다. |
| 라벨 ID | 고객 | 아니요, 하지만 (CustomerId, LabelId) 쌍은 전역적으로 고유합니다. |
| UserList ID | 전역 | 예 |
| 저작물 ID | 전역 | 예 |
이러한 ID 규칙은 Google Ads 객체의 로컬 스토리지를 설계할 때 유용할 수 있습니다.
일부 객체는 여러 항목 유형에 사용할 수 있습니다. 이 경우 객체에는 콘텐츠를 설명하는 type 필드가 포함됩니다. 예를 들어 AdGroupAd는 반응형 검색 광고, 호텔 광고, 디맨드젠 광고와 같은 객체를 나타낼 수 있습니다. 이 값은 AdGroupAd.ad.type 필드를 통해 액세스할 수 있으며 AdType enum의 값을 반환합니다. 변경 가능성은 버전에 따라 다를 수 있습니다 (예: Ad의 VideoResponsiveAdInfo는 v24 이상에서 변경 가능).
리소스 이름
각 리소스는 리소스와 상위 요소를 경로로 연결하는 resource_name 문자열로 고유하게 식별됩니다. 예를 들어 캠페인 리소스 이름은 다음 형식을 갖습니다.
customers/customer_id/campaigns/campaign_id
따라서 고객 ID가 1234567인 Google Ads 계정에서 ID가 987654인 캠페인의 경우 resource_name는 다음과 같습니다.
customers/1234567/campaigns/987654
서비스
서비스를 사용하면 Google Ads 항목을 가져오고 수정할 수 있습니다. 수정, 객체 및 통계 검색, 메타데이터 검색 서비스 등 세 가지 유형의 서비스가 있습니다.
객체 수정
리소스별 서비스는 mutate 요청을 사용하여 연결된 리소스 유형의 인스턴스를 수정합니다. GoogleAdsService.Mutate를 사용하여 단일 요청에서 여러 리소스 유형에 걸쳐 원자적 변형을 실행할 수도 있습니다 (예: 캠페인 예산, 캠페인, 광고 그룹을 함께 생성).
리소스별 서비스의 예:
고객을 수정하는
CustomerService캠페인을 수정하는
CampaignService광고 그룹을 수정하는
AdGroupService
각 mutate 요청에는 해당 operation 객체가 포함되어야 합니다. 예를 들어 CampaignService.MutateCampaigns 메서드는 하나 이상의 CampaignOperation 인스턴스를 예상합니다. 작업에 관한 자세한 내용은 객체 변경을 참고하세요.
동시 변이
Google Ads 객체는 두 개 이상의 소스에서 동시에 수정할 수 없습니다. 앱으로 동일한 객체를 업데이트하는 사용자가 여러 명인 경우 또는 여러 스레드를 사용하여 Google Ads 객체를 동시에 변경하는 경우 오류가 발생할 수 있습니다. 여기에는 동일한 애플리케이션의 여러 스레드 또는 서로 다른 애플리케이션 (예: 앱과 동시 Google Ads UI 세션)에서 객체를 업데이트하는 것이 포함됩니다.
API는 업데이트 전에 객체를 잠그는 방법을 제공하지 않습니다. 두 소스가 동시에 객체를 변경하려고 하면 API에서 DatabaseError.CONCURRENT_MODIFICATION_ERROR이 발생합니다.
비동기 변이와 동기 변이 비교
Google Ads API mutate 메서드는 동기식입니다. API 호출은 객체가 변경된 후에만 응답을 반환하므로 각 요청에 대한 응답을 기다려야 합니다. 이 접근 방식은 코딩하기가 비교적 간단하지만 프로세스가 호출이 완료될 때까지 기다리도록 강제되는 경우 부하 분산에 부정적인 영향을 미치고 리소스를 낭비할 수 있습니다.
다른 방법은 BatchJobService를 사용하여 객체를 비동기적으로 변환하는 것입니다. 이 방법은 완료를 기다리지 않고 여러 서비스에서 작업 배치를 실행합니다. 일괄 작업이 제출되면 Google Ads API 서버는 작업을 비동기식으로 실행하여 프로세스가 다른 작업을 실행할 수 있도록 합니다. 주기적으로 작업 상태를 확인하여 완료 여부를 확인할 수 있습니다.
비동기 처리에 관한 자세한 내용은 일괄 처리 가이드를 참고하세요.
변형 유효성 검사
대부분의 변이 요청은 실제 데이터에 대해 호출을 실행하지 않고도 유효성을 검사할 수 있습니다. 실제로 작업을 실행하지 않고 누락된 매개변수와 잘못된 필드 값에 대한 요청을 테스트할 수 있습니다.
이 기능을 사용하려면 요청의 선택적 validate_only 불리언 필드를 true로 설정합니다. 요청이 실행될 것처럼 완전히 검증되지만 최종 실행은 건너뜁니다. 오류가 발견되지 않으면 변형된 결과가 채워지지 않은 응답이 반환됩니다 (results이 비어 있음). 유효성 검사에 실패하면 기본적으로 GoogleAdsFailure RPC 오류 (partial_failure = false)로 요청이 실패하거나 partial_failure = true인 경우 partial_failure_error에 작업별 오류가 포함된 일반 응답이 반환됩니다.
validate_only는 일반적인 정책 위반에 대한 광고를 테스트하는 데 특히 유용합니다. 특정 단어, 구두점, 대문자 사용 또는 길이와 같은 정책을 위반하는 광고는 자동으로 거부됩니다. 악성 광고 하나로 인해 전체 일괄 처리가 실패할 수 있습니다. validate_only 요청 내에서 새 광고를 테스트하면 이러한 위반사항을 확인할 수 있습니다. 정책 위반 오류 처리 코드 예시를 참고하여 실제로 작동하는 것을 확인하세요.
객체 및 성능 통계 가져오기
GoogleAdsService은 객체와 성능 통계를 가져오는 단일 통합 서비스입니다.
GoogleAdsService에 대한 모든 Search 및 SearchStream 요청에는 쿼리할 리소스, 가져올 리소스 속성 및 실적 측정항목, 요청을 필터링하는 데 사용할 조건자, 실적 통계를 추가로 분류하는 데 사용할 세그먼트를 지정하는 쿼리가 필요합니다. 쿼리 형식에 대한 자세한 내용은 Google Ads 쿼리 언어 가이드를 참고하세요.
메타데이터 검색
GoogleAdsFieldService는 리소스의 사용 가능한 속성 및 데이터 유형과 같은 Google Ads API의 리소스에 관한 메타데이터를 가져옵니다. 이 서비스를 쿼리하는 방법에 관한 자세한 내용은 리소스 메타데이터 가이드를 참고하세요.
이 서비스는 GoogleAdsService에 대한 쿼리를 구성하는 데 필요한 정보를 제공합니다. 편의를 위해 GoogleAdsFieldService에서 반환하는 정보는 필드 참고 문서에서도 확인할 수 있습니다.