Мутировать

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

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

Вот несколько основных ресурсов по REST-интерфейсу 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 , по одному для каждой указанной вами операции и в том же порядке, что и исходные операции.

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

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

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