Изменить

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

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

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

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

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

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 Рекламы – lowerCamelCase. Оба варианта допустимы в скриптах Google Рекламы, поэтому вы можете копировать код непосредственно из этого руководства.

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

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