Изменить

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

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

Ниже приведены ссылки на основные ресурсы, посвященные 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});