Mutate

Google Ads 스크립트는 Google Ads API에서 사용할 수 있는 일반적인 변경을 지원합니다. 캠페인 생성 및 관리를 비롯하여 GoogleAdsService.mutate에서 실행할 수 있는 대부분의 작업은 Google Ads 스크립트에서도 실행할 수 있습니다.

이 기능을 사용하면 Google Ads API의 많은 부분에 액세스할 수 있으므로 이 기능을 사용하려면 Google Ads API 규칙을 기본적으로 이해해야 합니다. 개발자 토큰 및 승인과 같은 여러 측면은 Google Ads 스크립트에서 처리하므로 건너뛸 수 있지만 유효한 변경 요청을 구성해야 합니다.

이 가이드를 계속하기 전에 숙지해야 하는 Google Ads API REST 인터페이스에 관한 몇 가지 기본 리소스는 다음과 같습니다.

기본 예시

기능을 보여주기 위해 캠페인 예산을 만드는 다음 기본 예시를 살펴보세요.

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

AdsApp.mutate 호출은 단일 MutateOperation을 나타내는 JSON 객체를 가져옵니다. 이 객체 내에서 실행 중인 작업의 종류(이 경우 campaignBudgetOperation)를 지정합니다. 그런 다음 create, remove 또는 update와 updateMask를 모두 지정합니다. create 및 update 내의 특정 필드는 작업 중인 특정 리소스 유형에 따라 다릅니다.

작업 빌드

유효한 작업을 빌드하는 데 사용할 수 있는 몇 가지 전략이 있습니다. 캠페인 예시를 계속 사용하면 캠페인 예산의 REST 참고 문서 를 조회하여 모든 유효한 필드 목록을 확인한 다음 적절한 필드를 작성하거나 스크립트에서 맞춤 JavaScript 코드를 작성하여 적절한 객체를 구성할 수 있습니다.

또는 캠페인 예산의 '사용해 보기' 기능을 사용하여 작업을 동적으로 빌드해 볼 수 있습니다. 이 기능을 사용하면 추가할 필드를 선택하여 요청 본문을 동적으로 빌드할 수 있습니다. 그런 다음 생성된 결과에서 작업의 콘텐츠를 추출하고 작업 유형을 지정한 후 mutate 호출에 추가할 수 있습니다.

작업 유형

만들기

만들려는 리소스의 객체 표현을 전달하여 작업에서 create를 지정합니다.

create 작업의 예는 앞에서 제공된 스니펫을 참고하세요.

삭제

삭제하려는 리소스의 리소스 이름을 전달하여 작업에서 remove를 지정합니다. 예를 들면 다음과 같습니다.

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

항목의 리소스 이름을 모르는 경우 Adsapp.search 요청을 사용하여 가져올 수 있습니다.

업데이트

시스템에서 업데이트하려는 객체를 결정할 수 있도록 리소스 이름이 지정된 객체를 전달하여 작업에서 update를 지정합니다. 또한 값을 업데이트하려는 필드를 작성하고 이 요청에서 변경하려는 필드를 정확하게 나타내는 updateMask를 지정합니다. 업데이트 마스크에 리소스 이름을 포함하지 마세요.

update 작업의 예:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

결과 처리

작업 유형과 관계없이 반환 값은 MutateResult입니다. 반환된 리소스 이름을 사용하여 변경 후 리소스의 현재 상태를 쿼리하고 작업이 성공했는지 또는 오류가 발생했는지 확인할 수 있습니다.

다음은 결과를 확인하고 일부 정보를 로그에 출력하는 기본 흐름을 보여주는 예입니다.

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

여러 작업

Google Ads 스크립트는 단일 요청에서 여러 작업을 변경하는 것도 지원합니다. the AdsApp.mutateAll 메서드를 사용하여 단일 요청에서 전체 캠페인 계층 구조와 같이 서로 종속된 항목을 만들 수 있습니다. 선택적으로 전체 작업 집합을 원자적으로 만들 수 있으므로 작업 중 하나라도 실패하면 작업이 실행되지 않습니다.

반환 값은 제공된 각 작업에 대해 하나씩, MutateResult 객체의 배열이며 초기 작업과 동일한 순서입니다.

이 기능은 Google Ads API 기능과 동일하게 작동하므로 임시 ID 및 기타 고려사항에 관한 자세한 설명은 Google Ads API 권장사항 가이드를 참고하세요. 가이드에서는 필드 이름을 나타내기 위해 snake_case를 사용하는 반면 Google Ads 스크립트 문서에서는 lowerCamelCase를 사용합니다. 이 두 가지 사례 모두 Google Ads 스크립트에서 허용되므로 해당 가이드에서 코드를 직접 복사할 수 있습니다.

단일 요청에서 여러 작업을 실행하려면 모든 작업을 배열로 수집한 다음 AdsApp.mutateAll을 호출합니다. mutateAll 호출은 작업 배열을 첫 번째 인수로, 다음을 비롯한 선택적 두 번째 인수 옵션을 가져옵니다.

  • apiVersion: 스크립트 기본값이 아닌 버전을 사용하려면 V24와 같은 맞춤 API 버전을 지정할 수 있습니다. 당시 공개적으로 사용 가능한 버전을 사용할 수 있습니다.
  • partialFailure: 이 필드는 기본적으로 true입니다. true로 설정하면 유효한 작업이 실행되고 실패한 작업은 오류를 반환합니다. false로 설정하면 작업이 실패하는 경우 작업이 실행되지 않으므로 이 작업 집합이 원자적으로 실행됩니다.

다음은 원자적 요청에서 캠페인 예산, 캠페인, 광고 그룹을 만드는 여러 작업이 포함된 예입니다.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});