Объекты, методы и службы

В этом руководстве представлены объекты и методы AdWords API на примере основных задач управления кампаниями. Затем описываются службы, предлагаемые API, со ссылками на соответствующие справочные страницы.

Примеры кода в этом руководстве основаны на клиентской библиотеке Java. Для других языков программирования ознакомьтесь с полным списком клиентских библиотек.

AdWords API предназначен для опытных пользователей, хорошо знакомых с системой AdWords. Если вы новичок или хотите освежить свои знания, рекомендуем ознакомиться с этим руководством.

Иерархия и область действия объекта

Аккаунт AdWords представляет собой иерархическую структуру, состоящую из объектов разного уровня.

В каждом аккаунте есть одна или несколько рекламных кампаний, представленных объектами Campaign.

В каждую кампанию входит несколько групп объявлений, то есть объектов типа AdGroup.

Они, в свою очередь, включают несколько объектов AdGroupAd и AdGroupCriterion. Каждый объект AdGroupAd представляет собой объявление, а AdGroupCriterion – критерий таргетинга (например, ключевое слово), определяющий, в каких случаях должна показываться реклама.

Критерии таргетинга можно задавать и на уровне всей кампании. На этом же уровне можно задавать бюджеты и даты.

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

У каждого объекта в AdWords есть собственный идентификатор. Некоторые из них уникальны на глобальном уровне, а другие – только на строго определенном. В таблице ниже описывается уникальность идентификаторов каждого объекта в AdWords.

Идентификатор объекта Уровень уникальности Глобальный или нет
Идентификатор бюджета Глобальный Да
Идентификатор кампании Глобальный Да
Идентификатор группы объявлений Глобальный Да
Идентификатор объявления Группа объявлений Нет. Пара (AdGroupId, AdId) уникальна на глобальном уровне.
Идентификатор критерия группы объявлений Группа объявлений Нет. Пара (AdGroupId, CriterionId) уникальна на глобальном уровне.
Идентификатор критерия кампании Кампания Нет. Пара (CampaignId, CriterionId) уникальна на глобальном уровне.
Расширения объявлений Кампания Нет. Пара (CampaignId, AdExtensionId) уникальна на глобальном уровне.
Идентификатор фида Глобальный Да
Идентификатор элемента фида Глобальный Да
Идентификатор атрибута фида Фид Нет
Идентификатор сопоставления фида Глобальный Да
Идентификатор ярлыка Глобальный Да

Эти правила можно использовать при создании локальной базы данных для хранения объектов AdWords.

Если объект является производным от другого, он также будет содержать поле Type. Например, у объекта TextAd будет поле Type, указывающее на то, что он является производным от объекта Ad. При использовании динамического языка с помощью этого поля можно проверить, относится ли объект к какому-либо конкретному типу (например, принадлежит ли объект Ad к типу TextAd.

Методы и операции

AdWords API предлагает ряд служб для управления объектами AdWords. Так, служба CampaignService предназначена для управлениями кампаниями, служба AdGroupService – для работы с группами объявлений и т. д.

Все такие службы используют два стандартных метода: get и mutate.

Метод get

Метод get используется для извлечения объектов AdWords. Например, CampaignService.get позволяет получить список кампаний.

Метод get в качестве входных данных принимает селектор, а в качестве результата возвращает страницу. По умолчанию AdWords API не возвращает все поля объекта. Список полей необходимо предоставить при создании селектора.

Затем результаты можно отфильтровать с помощью поля predicates, упорядочить с помощью поля ordering или сузить с помощью поля dateRange, ограничив диапазон дат.

Если вы извлекаете большое количество объектов, необходимо также установить поле paging. Если этого не сделать, AdWords API выдаст ошибку SizeLimitError.RESPONSE_SIZE_LIMIT_EXCEEDED.

В приведенном ниже примере иллюстрируется практическая реализация описанных выше принципов. Этот код извлекает и отображает все кампании в аккаунте.

// Получение CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

int offset = 0;

// Создание селектора.
SelectorBuilder builder = new SelectorBuilder();
Selector selector = builder
    .fields(CampaignField.Id, CampaignField.Name)
    .orderAscBy(CampaignField.Name)
    .offset(offset)
    .limit(PAGE_SIZE)
    .build();

CampaignPage page = null;
do {
  // Получение всех кампаний.
  page = campaignService.get(selector);

  // Отображение кампаний.
  if (page.getEntries() != null) {
    for (Campaign campaign : page.getEntries()) {
      System.out.printf("Campaign with name '%s' and ID %d was found.%n", campaign.getName(),
          campaign.getId());
    }
  } else {
    System.out.println("No campaigns were found.");
  }

  offset += PAGE_SIZE;
  selector = builder.increaseOffsetBy(PAGE_SIZE).build();
} while (offset < page.getTotalNumEntries());

Подробнее о доступных полях селектора для разных служб...

Наши клиентские библиотеки содержат примеры кода с использованием метода get для всех служб управления кампаниями. Ниже приведены примеры клиентских библиотек для служб управления кампаниями на разных языках программирования.

Метод query

Метод query является альтернативой методу get. Вместо селекторов в нем используется SQL-подобный язык AdWords Query Language (AWQL). Создание того же запроса на AWQL обычно является более эффективным. Метод query поддерживается большинством основных служб. Обратите внимание, что AWQL не поддерживает изменение данных с помощью метода mutate.

Продемонстрируем возможности AWQL с помощью приведенного выше примера. Вместо селектора из четырех строк используется всего одна строка, которая содержит всю нужную информацию.

String query = "SELECT Id, Name, Status ORDER BY Name";

Обратите внимание, что предложение FROM отсутствует. Это связано с тем, что выбор уже определяется службой, которой принадлежит используемый метод query. AWQL поддерживает предложение FROM только при создании отчетов. Для использования этой строки нужно просто вызвать метод query требуемой службы.

CampaignPage page = null;
do {
  String pageQuery = query + String.format(" LIMIT %d, %d", offset, PAGE_SIZE);
  // Получение всех кампаний.
  page = campaignService.query(pageQuery);

  // Отображение кампаний.
  if (page.getEntries() != null) {
    for (Campaign campaign : page.getEntries()) {
      System.out.printf("Campaign with name '%s' and ID %d was found.%n", campaign.getName(),
          campaign.getId());
    }
  } else {
    System.out.println("No campaigns were found.");
  }

  offset += PAGE_SIZE;
} while (offset < page.getTotalNumEntries());

Результаты этого вызова будут аналогичны результатам вызова get в примере выше. В целом это более лаконичный и интуитивный способ написания запросов по сравнению с вызовом get. Подробнее читайте в руководстве по AWQL.

Метод mutate

Метод mutate используется для изменения (создания, обновления или удаления) объектов AdWords.

Чтобы изменить какой-либо объект, необходимо создать соответствующий объект Operation. Например, CampaignOperation позволяет модифицировать объект Campaign.

Поле operator определяет тип выполняемой операции (ADD, SET, REMOVE), а поле operand содержит изменяемый объект. Например, код добавления кампании может выглядеть так:

// Получение CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Создание кампании.
Campaign campaign = new Campaign();
campaign.setName("Interplanetary Cruise #" + System.currentTimeMillis());
campaign.setStatus(CampaignStatus.PAUSED);
BiddingStrategyConfiguration biddingStrategyConfiguration = new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);

// При желании вместо типа можно предоставить схему назначения ставок.
ManualCpcBiddingScheme cpcBiddingScheme = new ManualCpcBiddingScheme();
cpcBiddingScheme.setEnhancedCpcEnabled(false);
biddingStrategyConfiguration.setBiddingScheme(cpcBiddingScheme);

campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// При желании можно предоставить эти поля.
campaign.setStartDate(new DateTime().plusDays(1).toString("yyyyMMdd"));
campaign.setEndDate(new DateTime().plusDays(30).toString("yyyyMMdd"));
campaign.setAdServingOptimizationStatus(AdServingOptimizationStatus.ROTATE);
campaign.setFrequencyCap(new FrequencyCap(5L, TimeUnit.DAY, Level.ADGROUP));

// Необходимо заполнить только поле budgetId. Все остальные поля служба CampaignService игнорирует.
Budget budget = new Budget();
budget.setBudgetId(budgetId);
campaign.setBudget(budget);

campaign.setAdvertisingChannelType(AdvertisingChannelType.SEARCH);

// Параметры сети кампании: Google Поиск и поисковая сеть.
NetworkSetting networkSetting = new NetworkSetting();
networkSetting.setTargetGoogleSearch(true);
networkSetting.setTargetSearchNetwork(true);
networkSetting.setTargetContentNetwork(false);
networkSetting.setTargetPartnerSearchNetwork(false);
campaign.setNetworkSetting(networkSetting);

// Необязательные параметры.
GeoTargetTypeSetting geoTarget = new GeoTargetTypeSetting();
geoTarget.setPositiveGeoTargetType(GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE);
campaign.setSettings(new Setting[] {geoTarget});

// За один запрос можно создать несколько кампаний.
Campaign campaign2 = new Campaign();
campaign2.setName("Interplanetary Cruise banner #" + System.currentTimeMillis());
campaign2.setStatus(CampaignStatus.PAUSED);
BiddingStrategyConfiguration biddingStrategyConfiguration2 = new BiddingStrategyConfiguration();
biddingStrategyConfiguration2.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);
campaign2.setBiddingStrategyConfiguration(biddingStrategyConfiguration2);

Budget budget2 = new Budget();
budget2.setBudgetId(budgetId);
campaign2.setBudget(budget2);

campaign2.setAdvertisingChannelType(AdvertisingChannelType.DISPLAY);

// Создание операций.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.ADD);
CampaignOperation operation2 = new CampaignOperation();
operation2.setOperand(campaign2);
operation2.setOperator(Operator.ADD);

CampaignOperation[] operations = new CampaignOperation[] {operation, operation2};

// Добавление кампаний.
CampaignReturnValue result = campaignService.mutate(operations);

// Отображение кампаний.
for (Campaign campaignResult : result.getValue()) {
  System.out.printf("Campaign with name '%s' and ID %d was added.%n", campaignResult.getName(),
      campaignResult.getId());
}

Наши клиентские библиотеки содержат примеры кода, в которых метод mutate используется для всех служб управления кампаниями.

При изменении количество однотипных объектов, которые могут содержаться в одном аккаунте AdWords, ограничено. Лимиты для различных типов объектов AdWords приведены в этой статье Справочного центра. Ориентируйтесь на них при планировании кампаний, однако не определяйте их в коде своего приложения.

При вызове метода mutate следует также иметь в виду, что предпочтительнее отправлять несколько операций в одном запросе, чем несколько запросов с одной операцией в каждом. Это сокращает число обращений к серверу и таким образом повышает быстродействие приложения.

С этой целью также рекомендуется объединять запросы, относящиеся к одному родительскому элементу. Например, вместо того чтобы добавлять объявления в разные группы в одном запросе, сформируйте набор запросов, добавляющих объявления в одну и ту же группу. Другие полезные советы вы найдете в этом руководстве.

Поле operator

Как упоминалось выше, поле operator указывает на характер операции изменения.

Оператор ADD осуществляет добавление, SET – изменение, а REMOVE – удаление объекта. Однако эти операторы применимы не ко всем службам.

Например, созданную кампанию AdWords удалить нельзя – можно только присвоить ей статус удаленной. При этом можно по-прежнему запрашивать информацию о компании и ее статистику.

Оператор REMOVE не поддерживается службой CampaignService. Чтобы присвоить кампании статус REMOVED, необходимо использовать оператор SET.

Аналогичным образом, цель кампании нельзя изменить (SET) – ее можно только добавить (ADD) или удалить (REMOVE).

Далее показано, как в AdWords обрабатываются различные типы объектов.

Тип Добавление нового объекта Включение Приостановка Удаление/отключение
Campaign Действие: mutate
Операция: ADD
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: PAUSED
Действие: mutate
Операция: SET
Статус: REMOVED
AdGroup Действие: mutate
Операция: ADD
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: PAUSED
Действие: mutate
Операция: SET
Статус: REMOVED
AdGroupAd Действие: mutate
Операция: ADD
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: PAUSED
Действие: mutate
Операция: REMOVE
Статус: DISABLED
BiddableAdGroupCriterion Действие: mutate
Операция: ADD
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: ENABLED
Действие: mutate
Операция: SET
Статус: PAUSED
Действие: mutate
Операция: REMOVE
Статус: REMOVED
UserList Действие: mutate
Операция: ADD
Статус: OPEN
Нет Нет Действие: mutate
Операция: SET
Статус: CLOSED
Experiment Действие: mutate
Операция: ADD
Статус: ENABLED
Нет Нет Действие: mutate
Операция: SET
Статус: REMOVED
Feed Действие: mutate
Операция: ADD
Статус: ENABLED
Нет Нет Действие: mutate
Операция: REMOVE
Статус: REMOVED
FeedMapping Действие: mutate
Операция: ADD
Статус: ENABLED
Нет Нет Действие: mutate
Операция: REMOVE
Статус: REMOVED
FeedItem Действие: mutate
Операция: ADD
Статус: ENABLED
Нет Нет Действие: mutate
Операция: REMOVE
Статус: REMOVED
CustomerFeed Действие: mutate
Операция: ADD
Статус: ENABLED
Нет Нет Действие: mutate
Операция: REMOVE
Статус: REMOVED
CampaignFeed Действие: mutate
Операция: ADD
Статус: ENABLED
Нет Нет Действие: mutate
Операция: REMOVE
Статус: REMOVED
AdGroupFeed Действие: mutate
Операция: ADD
Статус: ENABLED
Нет Нет Действие: mutate
Операция: REMOVE
Статус: REMOVED

Одновременное изменение

Если у вас несколько пользователей, которые одновременно изменяют один и тот же объект с помощью приложения, или если в целях быстродействия вы осуществляете параллельное изменение объектов AdWords с использованием нескольких потоков, важно понимать, как AdWords обрабатывает одновременные запросы на изменение одного и того же объекта.

Одновременное изменение одного объекта AdWords из нескольких источников невозможно. Это касается в том числе обновления объекта сразу несколькими процессами через одно и то же или через разные приложения (например, из вашего приложения и Редактора AdWords). AdWords API не позволяет блокировать объекты перед их изменением. При попытке одновременного изменения объекта из двух источников API выдает ошибку CONCURRENT_MODIFICATION_ERROR.

Подробнее об управлении параллелизмом в AdWords API можно прочитать в нашем блоге.

Синхронные и асинхронные изменения

В AdWords API метод mutate является синхронным. Это означает, что при вызове API ответ поступит только после того, как объекты будут изменены. Таким образом, необходимо ожидать ответа на каждый запрос. Плюс этого метода состоит в относительной простоте программирования. Однако он может негативно влиять на балансировку нагрузки и приводить к расходованию ресурсов впустую в ожидании, когда завершится обработка вызова.

В качестве альтернативы можно изменять объекты асинхронно, используя службу BatchJobService. Она позволяет выполнять задачи, состоящие из больших пакетов операций, в нескольких службах, не ожидая завершения операций. После отправки задания серверы AdWords API выполняют операции асинхронно. Тем временем ваш компьютер может выполнять другие операции, периодически проверяя статус задачи.

Подробнее читайте в руководстве по пакетной обработке.

Проверка вызовов mutate

Заголовок SOAP validateOnly позволяет проверять вызовы API, не изменяя при этом данные. Эта возможность очень полезна для проверки пропущенных параметров и неверных значений полей.

Для использования данной функции полю validateOnly в RequestHeader нужно задать значение true. По умолчанию клиентские библиотеки задают значение false.

В этом случае ваш запрос полностью проверяется, однако шаг выполнения пропускается. Если ошибок не обнаружено, возвращается пустой ответ. В противном случае возвращаются подробные сообщения об ошибках.

Ниже приведен пример настройки validateOnly с помощью нашей библиотеки Java.

Credential oAuth2Credential = new OfflineCredentials.Builder()
    .forApi(Api.ADWORDS)
    .fromFile()
    .build()
    .generateCredential();

AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(oAuth2Credential)
    .build();

session.setValidateOnly(true);

У всех вызовов API, выполненных в этом сеансе, заголовок validateOnly будет иметь значение true.

Заголовок validateOnly позволяет проверить объявления на предмет соответствия правилам. Объявления автоматически отклоняются, если они не соответствуют правилам, например в отношении определенных слов, пунктуации, использования заглавных букв или длины. При массовой загрузке всего одна ошибка приведет к отклонению всех объявлений. Проверка нового объявления в режиме validateOnly позволяет без труда выявлять ошибки. Практическое применение показано в этом примере кода.

Проверку запросов mutate можно выполнять даже без клиентской библиотеки, если настроить заголовок SOAP.

Службы AdWords API

В этом разделе описываются службы, предлагаемые AdWords API, со ссылками на соответствующие справочные страницы с дополнительной информацией.

Службы AdWords API можно разделить на четыре функциональные категории:

Управление данными кампаний

Службы управления кампаниями используются для работы с кампаниями AdWords и элементами, которые с ними связаны. Каждая служба управления кампаниями соответствует элементу в иерархии данных кампании.

Служба Описание
CampaignService Позволяет создавать, изменять и удалять кампании. Кампания содержит одну или несколько групп объявлений. Для нее определяются отдельный бюджет, стратегия назначения ставок, диапазон дат активности и настройки таргетинга.
AdGroupService Позволяет создавать, изменять и удалять группы объявлений. Группа объявлений включает в себя набор объявлений и критериев, а также содержит значение ставки по умолчанию, соответствующей этим критериям.
AdGroupAdService Позволяет создавать, изменять и удалять объявления.
CampaignExtensionSettingService Позволяет создавать, изменять и удалять расширения объявлений. Расширения объявлений – это дополнительная информация (например, адрес компании, номер телефона или дополнительные ссылки), которая добавляется в стандартные текстовые объявления, заданные в кампании.
CampaignCriterionService
AdGroupCriterionService
Позволяют создавать, изменять и удалять критерии. Критерий описывает условия показа объявления.
ConversionTrackerService
OfflineConversionFeedService
Позволяют оценивать эффективность объявлений и ключевых слов, определяя, что происходит после совершения клика. Служба OfflineConversionFeedService обрабатывает импорт офлайн-конверсий.
DataService Возвращает данные управления рекламной кампанией, соответствующие указанным критериям.
FeedService
FeedItemService
FeedMappingService
AdGroupFeedService
CampaignFeedService
Позволяют создавать собственные фиды данных для управления расширениями.
AdwordsUserListService Позволяет создавать, изменять и удалять списки пользователей. Списки пользователей и критерии списков пользователей позволяют показывать рекламу пользователям, которые уже совершали конверсию на вашем сайте.
BudgetService Позволяет создавать, изменять и удалять бюджеты. Используется для управления бюджетами, которые могут использоваться в нескольких кампаниях.

Оптимизация

Службы оптимизации используются для получения статистики эффективности и поиска идей для новых критериев.

Служба Описание
ReportDefinitionService Позволяет создавать и скачивать различные отчеты по эффективности.
TargetingIdeaService Используется для подбора новых вариантов ключевых слов и мест размещения по определенным параметрам.
TrafficEstimatorService Предоставляет оценочные данные по трафику для предлагаемых кампаний, групп объявлений и ключевых слов.
ExperimentService Позволяет создавать и запускать эксперименты в кампаниях, в рамках которых можно тестировать ключевые слова, ставки и места размещения.

Управление аккаунтом

Службы управления аккаунтом используются для отслеживания активности в аккаунте.

Служба Описание
CustomerService Позволяет получать основные сведения о клиентском аккаунте.
CustomerSyncService Позволяет получать сведения об изменении данных кампании за определенный диапазон дат.
ManagedCustomerService Используется для управления клиентскими аккаунтами и связями между управляющим и клиентскими аккаунтами.

Вспомогательные службы

Вспомогательные службы используются для выполнения других задач в AdWords API.

Служба Описание
BatchJobService Используется для асинхронной обработки крупных пакетов операций с данными кампании. Выполнение задач массового изменения занимает больше времени, чем синхронные вызовы стандартных веб-служб, но обеспечивает другие преимущества, описанные в руководстве по пакетной обработке.
GeoLocationService Используется для извлечения географических координат и канонической формы определенного адреса.
MediaService Позволяет загружать и получать идентификаторы объектов, которые используются в медиарекламе (например, в графических и видеообъявлениях).
ConstantDataService Возвращает постоянные значения, используемые в API.
LocationCriterionService Возвращает идентификатор критерия местоположения.

Данные кампании

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

Элемент
Дочерние элементы (количество)
Тип данных Описание
Кампания
Группы объявлений (1+)
Списки таргетинга кампании (7)
Расширения объявлений кампании (0+)
Критерии кампании (0+)
Campaign Кампания содержит одну или несколько групп объявлений. Для нее определяются отдельный бюджет, стратегия назначения ставок, диапазон дат активности и настройки таргетинга.
Группа объявлений
Объявления (1+)
Критерии (1+)
AdGroup
Группа объявлений включает в себя набор объявлений и критериев, а также содержит значение ставки по умолчанию, соответствующей этим критериям.
Объявление
Переопределения расширений объявлений (0+)
AdGroupAd Доступные типы объявлений являются подклассами абстрактного типа Ad и представлены в документации по API.
Критерий
Нет
AdGroupCriterion, CampaignCriterion Критерии описывают условия включения (положительный критерий) либо отключения (отрицательный критерий) показа объявления. Критерий группы объявлений применяется к объявлениям в родительской группе. Критерий кампании всегда является отрицательным и определяет условия, запрещающие показ объявлений.
Расширение объявления
Нет
CampaignExtensionSetting Расширения объявлений – это дополнительная информация (например, адрес компании, номер телефона или дополнительные ссылки), которая добавляется в стандартные текстовые объявления, заданные в кампании.
Фид
Нет
Feed Фиды выступают в качестве поставщиков данных для расширений объявлений (дополнительных ссылок, номеров телефонов, приложений).
Список пользователей
Нет
UserList Списки пользователей позволяют отслеживать пользователей, которые уже проявили интерес к вашему веб-сайту. Чтобы показывать объявления таким пользователям, нужно создать критерий списка пользователей и связать его с существующим списком пользователей.
Бюджет
Нет
Budget Бюджеты используются для управления расходами в кампаниях. Бюджет может использоваться сразу в нескольких кампаниях, и система определит его оптимальное распределение.

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.