돌연변이

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 코드를 작성하여 적절한 객체를 생성할 수 있습니다.

또는 캠페인 예산에 'Try this' 기능을 사용하여 작업을 동적으로 빌드해 볼 수 있습니다. 이 기능을 사용하면 추가할 필드를 선택하여 요청 본문을 동적으로 빌드할 수 있습니다. 그런 다음 생성된 결과에서 작업 내용을 추출하고 작업 유형을 지정한 후 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: 스크립트 기본값이 아닌 버전을 사용하려면 V18와 같은 맞춤 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});