10월 15일 오전 10시(동부 표준시)에 Google 광고 및 측정 커뮤니티 서버의 Discord와 YouTube에서 라이브로 참여하세요. Google Ads API v26에 추가된 새로운 기능에 대해 논의할 예정입니다.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

객체 변경

API 구조 가이드에서 설명한 대로 Google Ads API의 각 최상위 리소스에는 리소스의 인스턴스 수정을 지원하는 리소스 유형별 서비스가 있습니다. 또한 GoogleAdsService.Mutate를 사용하여 단일 요청에서 여러 리소스 유형을 원자적으로 변경할 수 있습니다.

이 가이드에서는 CampaignService를 사용하여 Campaign 객체를 수정하는 방법을 보여주지만 다른 모든 리소스 유형별 서비스에도 동일한 개념이 적용됩니다.

mutate 요청

각 리소스 유형별 서비스에는 변형 요청을 수락하는 변형 메서드가 있습니다. 이 요청은 다음으로 구성됩니다.

customer_id (또는 REST URL의 customerId)
operations 컬렉션
partial_failure, validate_only, response_content_type(변형 후 변경 가능한 리소스 또는 리소스 이름만 반환되는지 여부를 결정함)과 같은 실행 설정(선택사항)

예를 들어 MutateCampaigns의 CampaignService 메서드는 다음으로 구성된 MutateCampaignsRequest를 허용합니다.

customer_id
CampaignOperation 객체 (operations) 컬렉션
실행 설정(선택사항)(partial_failure, validate_only, response_content_type은 선호하는 응답 유형을 나타냄)

작업

CampaignOperation과 같은 작업 객체를 사용하면 operation 필드를 설정하여 단일 리소스에서 수행하려는 작업을 지정할 수 있습니다. 이 필드는 다음 속성으로 구성된 oneof 필드입니다.

create: 리소스의 새 인스턴스를 만듭니다.
update: update 리소스의 속성과 일치하도록 리소스를 업데이트합니다. 이 필드를 설정할 때는 업데이트 작업 중에 수정할 속성을 Google Ads API에 알려주는 작업의 update_mask도 설정해야 합니다. 각 클라이언트 라이브러리에는 update_mask를 생성하는 필드 마스크 유틸리티 또는 도우미 메서드가 포함되어 있습니다.
remove: 리소스 이름 문자열 (예: customers/1234567890/campaigns/987654321)로 지정된 리소스를 삭제합니다.

operation 필드는 oneof 필드이므로 단일 작업을 사용하여 여러 객체를 수정할 수 없습니다. 예를 들어 캠페인 하나를 만들고 다른 캠페인을 삭제하려면 요청에 CampaignOperation 인스턴스 두 개를 추가합니다. 하나는 create가 설정된 인스턴스이고 다른 하나는 remove가 설정된 인스턴스입니다.

일괄 작업

단일 작업은 단일 리소스를 만들거나 업데이트하거나 삭제할 수 있지만 단일 mutate 요청에는 여러 작업이 포함될 수 있습니다. 각각 단일 작업을 포함하는 여러 mutate 요청을 전송하는 대신 작업을 단일 mutate 요청으로 결합해야 합니다.

예를 들어 캠페인 10개를 만들려면 CampaignOperation 객체가 10개 있는 단일 MutateCampaignsRequest를 전송해야 합니다. 여러 리소스 유형의 작업을 단일 요청으로 그룹화하려면 GoogleAdsService.Mutate 또는 리소스 변형을 사용합니다.

변형 응답

응답에서 반환되는 내용은 mutate 요청의 response_content_type 필드에서 전송된 내용에 따라 다릅니다. 예를 들어 MUTABLE_RESOURCE가 지정되면 응답에는 리소스의 resource_name와 campaign의 캠페인 변경 가능한 필드가 모두 포함됩니다. 기본적으로 (RESOURCE_NAME_ONLY) 각 MutateCampaignResult에는 resource_name만 채워집니다.

변형 오류

기본적으로 (partial_failure = false) mutate 요청의 작업은 요청의 모든 작업이 성공한 경우에만 Google Ads 계정에 적용됩니다. 작업이 실패하면 전체 요청이 롤백됩니다. 부분 실패를 지원하는 변형 요청 (요청 메시지에 partial_failure 필드가 있는 요청)의 경우 partial_failure = true를 설정하면 유효한 작업이 커밋되고 실패한 작업은 응답의 partial_failure_error 필드에서 작업별 오류를 반환합니다. 오류 처리에 관한 자세한 내용은 부분 실패 가이드 및 일반적인 오류 가이드를 참고하세요.