Мутировать

Скрипты Google Ads поддерживают универсальные мутации, доступные в API Google Ads . Большинство операций, которые можно выполнить из GoogleAdsService.mutate , также можно выполнить в скриптах Google Ads, включая создание и управление кампаниями.

Поскольку эта функция обеспечивает доступ к столь значительной части API Google Ads, для её использования важно иметь базовые знания о соглашениях API Google Ads. Многие аспекты, такие как токены разработчика и авторизация, можно пропустить, поскольку их обрабатывают скрипты Google Ads, но вам необходимо сформировать корректный запрос на изменение.

Вот некоторые основные ресурсы по интерфейсу REST API Google Ads, с которыми вам следует ознакомиться, прежде чем продолжить изучение этого руководства:

Простой пример

Чтобы продемонстрировать функциональность, рассмотрим этот простой пример, который создает бюджет кампании:

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

Вызов AdsApp.mutate принимает JSON-объект, представляющий одну MutateOperation . В этом объекте указывается тип выполняемой операции — в данном случае, 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 , по одному для каждой предоставленной вами операции и в том же порядке, что и исходные операции.

Эта функция работает так же, как и функция API Google Ads, поэтому обратитесь к руководству по лучшим практикам API Google Ads, чтобы получить полное объяснение временных идентификаторов и других аспектов. Обратите внимание, что в руководстве для обозначения имён полей используется snake_case , тогда как в документации по скриптам Google Ads используется lowerCamelCase . Оба эти варианта принимаются в скриптах Google Ads, поэтому вы можете скопировать код непосредственно из этого руководства.

Чтобы выполнить несколько операций в одном запросе, соберите все операции в массив и вызовите AdsApp.mutateAll . Вызов mutateAll принимает массив операций в качестве первого аргумента и необязательный второй аргумент с параметрами, включая:

  • apiVersion : Вы можете указать пользовательскую версию API, например V22 , если хотите использовать версию, отличную от версии скрипта по умолчанию. Можно использовать любую общедоступную версию на данный момент.
  • 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});