Работа с объектами

API AdWords часто используется для управления кампаниями в аккаунте AdWords. Из этого руководства вы узнаете об основных объектах (кампаниях, группах объявлений и т. д.), с которыми вам предстоит работать, а также о связи между ними.

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

  1. Объекты AdWords
  2. Службы управления кампаниями в API AdWords
    1. Метод get
    2. Метод query
    3. Метод mutate
    4. Поле operator
    5. Одновременное изменение
    6. Асинхронный или синхронный?
    7. Проверка вызовов mutate
  3. Следующий шаг

Объекты AdWords

Аккаунт AdWords представляет собой иерархическую структуру, состоящую из объектов разного уровня. На первом уровне находятся объекты типа Campaign. Это рекламные кампании, которые вы проводите. В каждую кампанию входит несколько групп объявлений, то есть объектов типа AdGroup. Они, в свою очередь, включают несколько объектов AdGroupAd и AdGroupCriteria. Каждый объект AdGroupAd представляет собой объявление, а AdGroupCriterion – критерий таргетинга (например, ключевое слово), определяющий, в каких случаях должна показываться реклама. Критерии таргетинга можно задавать и на уровне всей кампании. И наконец, на уровне кампании работают расширения объявлений (объекты типа CampaignAdExtension), которые позволяют добавлять в объявления разного рода дополнительную информацию: телефонные номера, адреса и т. д.

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

Идентификатор объекта Уровень уникальности Глобальный или нет
Campaign ID (идентификатор кампании) Глобальный Да
AdGroup ID (идентификатор группы объявлений) Глобальный Да
Ad ID (идентификатор объявления) Только на уровне группы объявлений Нет. Пара (AdGroupId, AdId) уникальна на глобальном уровне.
AdGroupCriterion ID (идентификатор критериев группы объявлений) Только на уровне группы объявлений Нет. Пара (AdGroupId, CriterionId) уникальна на глобальном уровне.
CampaignCriterion ID (идентификатор критериев кампании) Только на уровне кампании Нет. Пара (CampaignId, CriterionId) уникальна на глобальном уровне.
Ad Extensions (расширения объявлений) Только на уровне кампании Нет. Пара (CampaignId, AdExtensionId) уникальна на глобальном уровне.
Feed ID (идентификатор фида) Глобальный Да
Feed Item ID (идентификатор элемента фида) Глобальный Да
Feed Attribute ID (идентификатор атрибута фида) Только на уровне фида Нет
Feed Mapping ID (идентификатор сопоставления фида) Глобальный Да

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

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

Службы управления кампаниями в API AdWords

API AdWords предлагает ряд служб для управления кампаниями, позволяющие работать с доступными в AdWords объектами. Так, служба CampaignService предназначена для управлениями объектами Campaign, служба AdGroupService – для работы с объектами AdGroup и т. д. Все службы управления кампаниями используют два стандартных метода: get и mutate.

Метод get

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

Метод get принимает при вводе объект типа Selector и возвращает в качестве результата экземпляр объекта Page. По умолчанию API AdWords не возвращает все поля объекта. Список полей необходимо предоставить при создании селектора. Затем результаты можно отфильтровать с помощью поля predicates, упорядочить с помощью поля ordering или сузить с помощью поля dateRange, ограничив диапазон дат. Поле paging также необходимо установить, если вы извлекаете большое количество объектов. Если этого не сделать, API AdWords выдаст ошибку SizeLimitError.RESPONSE_SIZE_LIMIT_EXCEEDED. В приведенном ниже примере иллюстрируется практическая реализация описанных выше принципов. Этот код извлекает и отображает все кампании в аккаунте:

final int PAGE_SIZE = 100;
int offset = 0;

// Создание селектора.
Selector selector = new Selector();
selector.setFields(new String[] {"Id", "Name"});
selector.setOrdering(new OrderBy[] {new OrderBy("Name", SortOrder.ASCENDING)});
selector.setPaging(new Paging(offset, PAGE_SIZE));

CampaignPage page = null;

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

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

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

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

В предоставляемых нами клиентских библиотеках содержатся примеры кода, демонстрирующие использование метода get в различных службах управления кампаниями. В частности, в папках basicoperations и campaignmanagement в разделе примеров кода вы найдете образцы для клиентских библиотек Java.

Метод query

Метод query является альтернативой get, в котором не используются селекторы. Вместо них применяется AWQL – язык, похожий на SQL. Метод query поддерживается большинством распространенных служб, хотя в некоторых случаях придется использовать get. AWQL не поддерживает изменение данных с помощью метода mutate.

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

String awql = "SELECT Id, Name ORDER BY Name ASC LIMIT " + offset + "," + PAGE_SIZE;

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

page = campaignService.query(awql);

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

Метод mutate

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

Чтобы изменить какой-либо объект, необходимо создать соответствующий объект Operation. Например, CampaignOperation позволяет модифицировать объект Campaign. Поле operator определяет тип выполняемой операции (ADD, SET, REMOVE), а поле operand содержит изменяемый объект. Например, код, добавляющий кампанию, может выглядеть так:

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

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

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

// В качестве сетей выберите поиск (Search) и поисковую сеть (Search Network).
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);
KeywordMatchSetting keywordMatch = new KeywordMatchSetting();
keywordMatch.setOptIn(Boolean.FALSE);

TargetRestrictSetting targetRestrict = new TargetRestrictSetting();
targetRestrict.setUseAdGroup(Boolean.TRUE);
campaign.setSettings(new Setting[] {geoTarget, keywordMatch, targetRestrict});

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

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

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

// Отображение кампаний.
for (Campaign campaignResult : result.getValue()) {
   System.out.println("Campaign with name \"" + campaignResult.getName()
       + "\" and id \"" + campaignResult.getId() + "\" was added.");
}

В предоставляемых нами клиентских библиотеках содержатся примеры кода, демонстрирующие применение метода mutate в различных службах управления кампаниями. В частности, в папках basicoperations и campaignmanagement в разделе примеров кода вы найдете образцы для клиентских библиотек Java.

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

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

Поле operator

Как упоминалось выше в разделе, посвященном методу mutate, поле operator указывает на характер операции изменения: добавление нового объекта (ADD) либо изменение (SET) или удаление (REMOVE) существующего. Однако не все операторы применимы ко всем службам – это зависит от способа обработки конкретного типа объектов в AdWords.

Например, созданную кампанию AdWords удалить нельзя – можно только присвоить ей статус удаленной. Позже вы всегда сможете ее восстановить, выбрав статус "Приостановлено" или "Активно". Поэтому оператор REMOVE не поддерживается службой CampaignService. Чтобы присвоить кампании статус удаленной, необходимо использовать оператор SET. Аналогичным образом цель кампании нельзя изменить (SET), а можно только добавить (ADD) или удалить (REMOVE). Далее показано, как в AdWords обрабатываются различные типы объектов.

Тип Недавно добавлено Включено/активно Приостановлено Удалено/отключено
Campaign Действие: mutate
Операция: ADD
Статус: "Активно"
Действие: mutate
Операция: SET
Статус: "Активно"
Действие: mutate
Операция: SET
Статус: "Приостановлено"
Действие: mutate
Операция: SET
Статус: "Удалено"
AdGroup Действие: mutate
Операция: ADD
Статус: "Включено"
Действие: mutate
Операция: SET
Статус: "Включено"
Действие: mutate
Операция: SET
Статус: "Приостановлено"
Действие: mutate
Операция: SET
Статус: "Удалено"
AdGroupAd Действие: mutate
Операция: ADD
Статус: "Включено"
Действие: mutate
Операция: SET
Статус: "Включено"
Действие: mutate
Операция: SET
Статус: "Приостановлено"
Действие: mutate
Операция: REMOVE
Статус: "Отключено"
BiddableAdGroupCriterion Действие: mutate
Операция: ADD
Статус: "Активно"
Действие: mutate
Операция: SET
Статус: "Активно"
Действие: mutate
Операция: SET
Статус: "Приостановлено"
Действие: mutate
Операция: REMOVE
Статус: "Удалено"
CampaignAdExtension Действие: mutate
Операция: ADD
Статус: "Активно"
Нет Нет Действие: mutate
Операция: SET
Статус: "Удалено"
UserList Действие: mutate
Операция: ADD
Статус: "Открыто"
Нет Нет Действие: mutate
Операция: SET
Статус: "Закрыто"
Experiment Действие: mutate
Операция: ADD
Статус: "Активно"
Нет Нет Действие: mutate
Операция: SET
Статус: "Удалено"

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

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

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

Асинхронный или синхронный?

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

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

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

Заголовок SOAP validateOnly позволяет проверять вызовы API, не изменяя при этом данные. Эта возможность очень полезна для проверки пропущенных параметров и неверных значений полей. Для использования данной функции полю RequestHeader validateOnly нужно задать значение true. По умолчанию клиентские библиотеки задают значение false.

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

Ниже приведен пример настройки 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 позволяет без труда выявлять ошибки. Практическое применение показано в этом примере кода.

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

Следующий шаг

Теперь вы готовы к первому созданию запросов.

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

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