Мутировать

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

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

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

Базовый пример

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

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 Рекламы также поддерживают изменение нескольких операций в одном запросе с помощью метода AdsApp.mutateAll . Вы можете создавать сущности, которые зависят друг от друга, например полную иерархию кампании, в одном запросе. При желании вы можете сделать весь набор операций атомарным, чтобы в случае сбоя какой-либо операции ни одна из них не выполнялась.

Возвращаемое значение представляет собой массив объектов MutateResult , по одному для каждой предоставленной вами операции и в том же порядке, что и начальные операции.

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

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

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