Google Ads API는 사용 사례에 따라 리소스를 변경하는 여러 방법을 제공합니다.
- 리소스 서비스가 변경됨: 변경 가능한 각 리소스에는 해당 특정 리소스 유형의 작업을 실행하는 전용 서비스가 있습니다. 예를 들어
Campaign리소스는 캠페인을 생성, 업데이트 또는 삭제하기 위해CampaignService.MutateCampaigns엔드포인트를 사용합니다. - 일괄 변경:
GoogleAdsService.Mutate엔드포인트는 여러 리소스 유형 (및 v23 이상에서는 캠페인 예약 또는 견적과 같은 지원되는 작업 작업)에 걸쳐 일련의 변경 작업을 단일 동기 요청으로 래핑합니다. - 비동기 일괄 작업: 대규모 변형 또는 장기 실행 워크로드의 경우
BatchJobService은 동기 요청 시간 초과 위험 없이 비동기적으로 작업을 실행합니다.GoogleAdsService.Mutate와 달리BatchJobService는 항상 부분 실패 시맨틱에서 실행되며validate_only모드 또는 작업 작업 (book_campaigns_operation,quote_campaigns_operation)을 지원하지 않습니다. 부분 실패가 항상 활성 상태이므로BatchJobService는 기본 서비스가 부분 실패를 지원하지 않는 리소스 작업 (예:CustomerOperation,CampaignConversionGoalOperation,ConversionGoalCampaignConfigOperation,CustomConversionGoalOperation,CustomerConversionGoalOperation)을MutateError.OPERATION_DOES_NOT_SUPPORT_PARTIAL_FAILURE로 거부합니다.
일괄 변경의 이점
GoogleAdsService.Mutate을 사용하면 다음과 같은 혜택이 있습니다(구현 안내는 변이 권장사항 참고).
- 여러 리소스 서비스에 걸쳐 그룹화된 작업: 개별 리소스 서비스 호출은 단일 리소스 유형의 작업만 허용하지만
GoogleAdsService.Mutate를 사용하면 하나의 호출에서 여러 리소스 유형을 변경할 수 있습니다. - 임시 리소스 이름: 새로 생성된 상위 항목에 음수 정수 ID (예:
customers/CUSTOMER_ID/campaigns/-1)를 할당하고 동일한 요청 내에서 하위 작업에서 이러한 임시 ID를 참조할 수 있습니다.
이러한 기능을 사용하면 GoogleAdsService.Mutate를 사용하여 모든 작업이 함께 성공하거나 실패하도록 전체 캠페인 계층 구조를 원자적으로 만들거나 partial_failure를 true로 설정하여 유효한 작업을 독립적으로 커밋할 수 있습니다.