Mutate

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

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

다음은 이 가이드를 계속 진행하기 전에 숙지해야 할 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 스크립트는 AdsApp.mutateAll 메서드를 사용하여 단일 요청에서 여러 작업을 변경하는 기능도 지원합니다. 단일 요청에서 전체 캠페인 계층 구조와 같이 서로 종속된 항목을 만들 수 있습니다. 원하는 경우 전체 작업 집합을 원자적으로 만들 수 있으므로 하나라도 실패하면 아무것도 수행되지 않습니다.

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

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

단일 요청에서 여러 작업을 수행하려면 모든 작업을 배열로 수집한 다음 AdsApp.mutateAll를 호출합니다. mutateAll 호출은 작업 배열을 첫 번째 인수로 사용하고 선택적인 두 번째 인수로 다음을 포함한 옵션을 사용합니다.

  • apiVersion: 스크립트 기본값 이외의 버전을 사용하려면 커스텀 API 버전(예: V26)을 지정할 수 있습니다. 당시 공개적으로 제공되는 모든 버전을 사용할 수 있습니다.
  • 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});