돌연변이

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 참조 문서를 검색하여 유효한 모든 필드의 목록을 확인한 후 적절한 필드를 작성하거나 스크립트에 맞춤 자바스크립트 코드를 작성하여 적절한 객체를 생성할 수 있습니다.

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