Общие сведения о службах фидов

Это руководство дает основное представление о фидах. Фиды – очень гибкий и удобный формат для работы с табличными данными. Эти данные используются такими функциями AdWords, как, например, расширения и модификаторы объявлений, а также динамический ремаркетинг. В этом руководстве использование фидов иллюстрируется на примере расширений объявлений, однако процесс работы аналогичен для других типов табличных данных (разница только в типе меток-заполнителей).

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

Сценарий

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

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

Название Конечные URL дополнительных ссылок
Главная страница http://www.example.com
Поиск филиалов http://www.example.com/locations
Скидки http://www.example.com/discounts
Поддержка http://www.example.com/support
Продукты http://www.example.com/prods
О нас http://www.example.com/about

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

Службы фидов

Для создания фидов и управления ими предназначено несколько взаимосвязанных служб.

FeedService
Используется для описания структуры табличных данных в AdWords, включая название или заголовок объекта Feed (таблицы), а также названия и типы столбцов.
FeedItemService
Используется для наполнения фида данными. Каждому FeedItem соответствует строка таблицы.
FeedMappingService
Определяет, как будет использоваться фид, то есть как столбцы таблицы соответствуют полям, которые требуются определенной функции AdWords. Ниже мы покажем, как использовать фид для дополнительных ссылок.
CustomerFeedService
Включает фид для всего аккаунта, то есть всех кампаний и групп объявлений в нем.
CampaignFeedService
Включает фид для всей кампании, то есть всех групп объявлений в ней.
AdGroupFeedService
Включает фид для определенной группы объявлений.

Пример Java-кода

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

Добавление дополнительных ссылок в кампанию включает следующие этапы:

  1. Создание фида.
  2. Наполнение фида.
  3. Сопоставление фида и полей меток-заполнителей.
  4. Установление связи фида с клиентом, кампанией или группой объявлений.
  5. Добавление расписания для элементов фида (необязательно).


1. Создание фида дополнительных ссылок

Мы используем FeedService, чтобы описать структуру загружаемых данных. Фиду назначается имя и присваивается набор атрибутов FeedAttribute (столбцов). Каждый атрибут FeedAttribute имеет имя и тип.

В приведенном ниже примере createSiteLinksFeed() использует службу FeedService для создания объекта Feed с объектами FeedAttribute (столбцами), в которых могут храниться табличные данные для дополнительных ссылок:

private static void createSiteLinksFeed(AdWordsServices adWordsServices, AdWordsSession session,
    SiteLinksDataHolder siteLinksData, String feedName) throws Exception {
  // Get the FeedService.
  FeedServiceInterface feedService = adWordsServices.get(session, FeedServiceInterface.class);

  // Create attributes.
  FeedAttribute textAttribute = new FeedAttribute();
  textAttribute.setType(FeedAttributeType.STRING);
  textAttribute.setName("Link Text");
  FeedAttribute finalUrlAttribute = new FeedAttribute();
  finalUrlAttribute.setType(FeedAttributeType.URL_LIST);
  finalUrlAttribute.setName("Link Final URLs");
  FeedAttribute line1Attribute = new FeedAttribute();
  line1Attribute.setType(FeedAttributeType.STRING);
  line1Attribute.setName("Line 1 Description");
  FeedAttribute line2Attribute = new FeedAttribute();
  line2Attribute.setType(FeedAttributeType.STRING);
  line2Attribute.setName("Line 2 Description");

  // Create the feed.
  Feed siteLinksFeed = new Feed();
  siteLinksFeed.setName(feedName);
  siteLinksFeed.setAttributes(
      new FeedAttribute[] {textAttribute, finalUrlAttribute, line1Attribute, line2Attribute});
  siteLinksFeed.setOrigin(FeedOrigin.USER);

  // Create operation.
  FeedOperation operation = new FeedOperation();
  operation.setOperand(siteLinksFeed);
  operation.setOperator(Operator.ADD);

  // Add the feed.
  FeedReturnValue result = feedService.mutate(new FeedOperation[] {operation});

  Feed savedFeed = result.getValue()[0];
  siteLinksData.siteLinksFeedId = savedFeed.getId();
  FeedAttribute[] savedAttributes = savedFeed.getAttributes();
  siteLinksData.linkTextFeedAttributeId = savedAttributes[0].getId();
  siteLinksData.linkFinalUrlFeedAttributeId = savedAttributes[1].getId();
  siteLinksData.line1FeedAttributeId = savedAttributes[2].getId();
  siteLinksData.line2FeedAttributeId = savedAttributes[3].getId();
  System.out.printf("Feed with name '%s' and ID %d with linkTextAttributeId %d"
      + " and linkFinalUrlAttributeId %d and line1AttributeId %d"
      + " and line2AttributeId %d was created.%n",
      savedFeed.getName(),
      savedFeed.getId(),
      savedAttributes[0].getId(),
      savedAttributes[1].getId(),
      savedAttributes[2].getId(),
      savedAttributes[3].getId());
}

Чтобы описать табличные данные, которые будут использоваться для дополнительных ссылок, метод создает фид с объектами FeedAttribute (столбцами): Link Text, Final URLs, Line 1 и Line 2. Назовем его Feed For Sitelinks (Фид для дополнительных ссылок). Поскольку строки фида заполняются рекламодателем, в качестве источника фида используется FeedOrigin.USER (данные могут указываться и системой AdWords).

Для создания фида вызывается операция feedService.mutate. После успешного добавления фида служба FeedService возвращает идентификатор фида, а также все идентификаторы FeedAttribute (столбцов). Сохраните их для последующего использования в других службах. Для простоты предположим, что был создан объект siteLinksData типа SiteLinksDataHolder с соответствующими полями для идентификаторов. Мы будем использовать этот объект позже для получения идентификаторов. Вы можете создать аналогичный объект на своем языке программирования.

Обратите внимание, что в нашем фиде ровно столько столбцов, сколько необходимо для дополнительных ссылок. Однако, как вы увидите позже, можно создать фид с большим числом столбцов, только некоторые из которых будут содержать данные, необходимые функции AdWords. Это может быть полезно, если вы хотите использовать значения в других столбцах, чтобы указать, какие объекты FeedItem (строки) должны применяться к определенным кампаниям или группам объявлений, с помощью функции сопоставления (подробнее читайте ниже).

2. Наполнение фида

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

Сначала применим вспомогательный метод newSiteLinkFeedItemAddOperation(), который позволит создать объекты FeedItem (строки) на основе информации о дополнительных ссылках (текст, конечный URL и строки описания) и идентификаторах объектов FeedAttribute (столбцов). После этого объекты FeedItem добавляются с помощью операции ADD и возвращаются методом.

Чтобы лучше понять, как создать FeedItem, запомните следующее описание таблицы: каждая строка представляет собой набор ячеек, а каждая ячейка расположена в определенном столбце и имеет некое содержание. Аналогичным образом, FeedItem (строка) представляет собой набор объектов FeedItemAttributeValue (ячеек), каждый из которых имеет идентификатор FeedAttribute (столбца, в котором расположена эта ячейка) и stringValue (содержимое ячейки, если это строка).

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line1, String line2) {
  return newSiteLinkFeedItemAddOperation(siteLinksData, text, finalUrl, line1, line2, null);
}

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line1, String line2,
    Long locationId) {
  // Create the FeedItemAttributeValues for our text values.
  FeedItemAttributeValue linkTextAttributeValue = new FeedItemAttributeValue();
  linkTextAttributeValue.setFeedAttributeId(siteLinksData.linkTextFeedAttributeId);
  linkTextAttributeValue.setStringValue(text);
  FeedItemAttributeValue linkFinalUrlAttributeValue = new FeedItemAttributeValue();
  linkFinalUrlAttributeValue.setFeedAttributeId(siteLinksData.linkFinalUrlFeedAttributeId);
  linkFinalUrlAttributeValue.setStringValues(new String[] {finalUrl});
  FeedItemAttributeValue line1TextAttributeValue = new FeedItemAttributeValue();
  line1TextAttributeValue.setFeedAttributeId(siteLinksData.line1FeedAttributeId);
  line1TextAttributeValue.setStringValue(line1);
  FeedItemAttributeValue line2TextAttributeValue = new FeedItemAttributeValue();
  line2TextAttributeValue.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2TextAttributeValue.setStringValue(line2);

  // Create the feed item and operation.
  FeedItem item = new FeedItem();
  item.setFeedId(siteLinksData.siteLinksFeedId);
  item.setAttributeValues(new FeedItemAttributeValue[] {linkTextAttributeValue,
      linkFinalUrlAttributeValue, line1TextAttributeValue, line2TextAttributeValue});

  // OPTIONAL: Use geographical targeting on a feed item.
  // IDs can be found in the documentation or retrieved with the
  // LocationCriterionService.
  if (locationId != null) {
    Location location = new Location();
    location.setId(locationId);
    item.setGeoTargeting(location);
    // OPTIONAL: Restrict targeting only to people physically within the location.
    FeedItemGeoRestriction geoTargetingRestriction = new FeedItemGeoRestriction();
    geoTargetingRestriction.setGeoRestriction(GeoRestriction.LOCATION_OF_PRESENCE);
    item.setGeoTargetingRestriction(geoTargetingRestriction);
  }

  // Optional: use item.setStartTime() and item.setEndTime() to specify the
  // time period for the feed to deliver.  The example below will make the feed
  // start now and stop in one month.
  // Make sure you specify the DateTime in the customer's time zone.  You can
  // retrieve this from customer.getDateTimeZone().
  //   item.setStartTime(new DateTime(customerTimeZone).toString("yyyyMMdd HHmmss"));
  //   item.setEndTime(new DateTime(customerTimeZone).plusMonths(1).toString("yyyyMMdd HHmmss"));

  // Optional: use item.setScheduling() to specify time and days of the week for feed to deliver.
  FeedItemOperation operation = new FeedItemOperation();
  operation.setOperand(item);
  operation.setOperator(Operator.ADD);
  return operation;
}

Вернемся к нашему примеру. Метод createSiteLinksFeedItems() создает все объекты FeedItem и содержащие их объекты FeedItemOperation, вызывая вспомогательный метод с разной информацией для каждой дополнительной ссылки.

Элементы фида, возвращаемые вызовом mutate, включают идентификаторы, которые сохраняются в siteLinksData для последующего использования (опять же, предполагается, что этот объект уже был создан и включает необходимые поля для идентификаторов).

private static void createSiteLinksFeedItems(AdWordsServices adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws Exception {
  // Get the FeedItemService.
  FeedItemServiceInterface feedItemService =
      adWordsServices.get(session, FeedItemServiceInterface.class);

  // Create operations to add FeedItems.
  FeedItemOperation home = newSiteLinkFeedItemAddOperation(siteLinksData, "Home",
      "http://www.example.com", "Home line 1", "Home line 2");
  FeedItemOperation stores = newSiteLinkFeedItemAddOperation(siteLinksData, "Stores",
      "http://www.example.com/stores", "Stores line 1", "Stores line 2");
  FeedItemOperation onSale = newSiteLinkFeedItemAddOperation(siteLinksData, "On Sale",
      "http://www.example.com/sale", "On Sale line 1", "On Sale line 2");
  FeedItemOperation support = newSiteLinkFeedItemAddOperation(siteLinksData, "Support",
      "http://www.example.com/support", "Support line 1", "Support line 2");
  FeedItemOperation products = newSiteLinkFeedItemAddOperation(siteLinksData, "Products",
      "http://www.example.com/prods", "Products line 1", "Products line 2");
  // This site link is using geographical targeting by specifying the
  // criterion ID for California.
  FeedItemOperation aboutUs = newSiteLinkFeedItemAddOperation(siteLinksData, "About Us",
      "http://www.example.com/about", "About Us line 1", "About Us line 2", 21137L);

  FeedItemOperation[] operations =
      new FeedItemOperation[] {home, stores, onSale, support, products, aboutUs};

  FeedItemReturnValue result = feedItemService.mutate(operations);
  for (FeedItem item : result.getValue()) {
    System.out.printf("FeedItem with feedItemId %d was added.%n", item.getFeedItemId());
    siteLinksData.siteLinkFeedItemIds.add(item.getFeedItemId());
  }
}

3. Сопоставление фида и полей меток-заполнителей

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

// See the Placeholder reference page for a list of all the placeholder types and fields.
// https://developers.google.com/adwords/api/docs/appendix/placeholders
private static final int PLACEHOLDER_SITELINKS = 1;

// See the Placeholder reference page for a list of all the placeholder types and fields.
// https://developers.google.com/adwords/api/docs/appendix/placeholders
private static final int PLACEHOLDER_FIELD_SITELINK_LINK_TEXT = 1;
private static final int PLACEHOLDER_FIELD_SITELINK_FINAL_URL = 5;
private static final int PLACEHOLDER_FIELD_LINE_1_TEXT = 3;
private static final int PLACEHOLDER_FIELD_LINE_2_TEXT = 4;

private static void createSiteLinksFeedMapping(AdWordsServices adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws Exception {
  // Get the FeedItemService.
  FeedMappingServiceInterface feedMappingService =
      adWordsServices.get(session, FeedMappingServiceInterface.class);

  // Map the FeedAttributeIds to the fieldId constants.
  AttributeFieldMapping linkTextFieldMapping = new AttributeFieldMapping();
  linkTextFieldMapping.setFeedAttributeId(siteLinksData.linkTextFeedAttributeId);
  linkTextFieldMapping.setFieldId(PLACEHOLDER_FIELD_SITELINK_LINK_TEXT);
  AttributeFieldMapping linkFinalUrlFieldMapping = new AttributeFieldMapping();
  linkFinalUrlFieldMapping.setFeedAttributeId(siteLinksData.linkFinalUrlFeedAttributeId);
  linkFinalUrlFieldMapping.setFieldId(PLACEHOLDER_FIELD_SITELINK_FINAL_URL);
  AttributeFieldMapping line1FieldMapping = new AttributeFieldMapping();
  line1FieldMapping.setFeedAttributeId(siteLinksData.line1FeedAttributeId);
  line1FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_1_TEXT);
  AttributeFieldMapping line2FieldMapping = new AttributeFieldMapping();
  line2FieldMapping.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_2_TEXT);

  // Create the FeedMapping and operation.
  FeedMapping feedMapping = new FeedMapping();
  feedMapping.setPlaceholderType(PLACEHOLDER_SITELINKS);
  feedMapping.setFeedId(siteLinksData.siteLinksFeedId);
  feedMapping.setAttributeFieldMappings(new AttributeFieldMapping[] {linkTextFieldMapping,
      linkFinalUrlFieldMapping, line1FieldMapping, line2FieldMapping});
  FeedMappingOperation operation = new FeedMappingOperation();
  operation.setOperand(feedMapping);
  operation.setOperator(Operator.ADD);

  // Save the field mapping.
  FeedMappingReturnValue result =
      feedMappingService.mutate(new FeedMappingOperation[] {operation});
  for (FeedMapping savedFeedMapping : result.getValue()) {
    System.out.printf(
        "Feed mapping with ID %d and placeholderType %d was saved for feed with ID %d.%n",
        savedFeedMapping.getFeedMappingId(), savedFeedMapping.getPlaceholderType(),
        savedFeedMapping.getFeedId());
  }
}

Этот метод настраивает фид для использования с дополнительными ссылками. При этом в качестве типа метки-заполнителя для FeedMapping задается константа PLACEHOLDER_SITELINKS со значением 1. Этот метод также сопоставляет атрибуты FeedAttribute с полями меток-заполнителей, которые требуются для дополнительных ссылок: текстом, конечными URL и строками описания. Такое сопоставление сообщает системе, какие объекты FeedAttribute (столбцы) используются для различных аспектов дополнительных ссылок.

4. Установление связи фида с клиентом, кампанией или группой объявлений

К этому моменту фид готов к использованию с дополнительными ссылками. Теперь осталось связать фид с клиентом (CustomerFeedService), кампанией (CampaignFeedService) или группой объявлений (AdGroupFeedService). Это позволит включить дополнительные ссылки для определенного набора объявлений.

При выборе между клиентом, кампанией и группой объявлений следует учитывать необходимый уровень контроля. Например, если во всех группах объявлений в кампании должны быть одни и те же дополнительные ссылки, то можно связать фид с кампанией. Если вы хотите, чтобы ссылки использовались во всех кампаниях, свяжите фид с аккаунтом. А если в разных группах объявлений должны использоваться разные дополнительные ссылки, то следует связать фид с кампанией.

Устанавливая связь с фидом, можно указать, какие объекты FeedItem (строки) должны активироваться для этого клиента, кампании или группы объявлений. Например, у вас может быть всего один фид, где некоторые элементы (с помощью фильтра) используются для одной кампании, а другие элементы – (с помощью другого фильтра) – для другой кампании. Чтобы применить фильтры, необходимо предоставить функцию сопоставления, которая оценивается для каждого объекта FeedItem.

private static void createSiteLinksCampaignFeed(AdWordsServices adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData, Long campaignId) throws Exception {
  // Get the CampaignFeedService.
  CampaignFeedServiceInterface campaignFeedService =
      adWordsServices.get(session, CampaignFeedServiceInterface.class);

  // Construct a matching function that associates the sitelink feed items to the campaign, and
  // sets the device preference to mobile. See the matching function guide at
  // https://developers.google.com/adwords/api/docs/guides/feed-matching-functions
  // for more details.
  String matchingFunctionString = String.format(
      "AND( IN(FEED_ITEM_ID, {%s}), EQUALS(CONTEXT.DEVICE, 'Mobile') )",
      Joiner.on(',').join(siteLinksData.siteLinkFeedItemIds));

  CampaignFeed campaignFeed = new CampaignFeed();
  campaignFeed.setFeedId(siteLinksData.siteLinksFeedId);
  campaignFeed.setCampaignId(campaignId);

  Function matchingFunction = new Function();
  matchingFunction.setFunctionString(matchingFunctionString);

  campaignFeed.setMatchingFunction(matchingFunction);
  // Specifying placeholder types on the CampaignFeed allows the same feed
  // to be used for different placeholders in different Campaigns.
  campaignFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_SITELINKS});

  CampaignFeedOperation operation = new CampaignFeedOperation();
  operation.setOperand(campaignFeed);
  operation.setOperator(Operator.ADD);
  CampaignFeedReturnValue result =
      campaignFeedService.mutate(new CampaignFeedOperation[] {operation});
  for (CampaignFeed savedCampaignFeed : result.getValue()) {
    System.out.printf("Campaign with ID %d was associated with feed with ID %d.%n",
        savedCampaignFeed.getCampaignId(), savedCampaignFeed.getFeedId());
  }
}

Этот метод устанавливает связь между кампанией и фидом. При этом настраивается функция сопоставления и типы меток-заполнителей.

У вас может возникнуть вопрос, почему для CampaignFeed необходимо снова настраивать тип меток-заполнителей (в нашем примере – дополнительные ссылки), хотя он уже задан в объекте FeedMapping для всего фида в целом. Дело в том, что это позволяет использовать фид с несколькими объектами FeedMapping лишь для некоторых типов меток-заполнителей в одних кампаниях, а в других – для других типов меток-заполнителей.

Назначение функции сопоставления в CampaignFeed сообщает системе показа, какие объекты FeedItem (строки) следует использовать в качестве дополнительных ссылок. Подробнее читайте в руководстве Функции сопоставления. В этом примере мы использовали FEED_ITEM_ID как RequestContextOperand в функции сопоставления. Однако можно было бы использовать другой тип RequestContextOperand или выполнить сопоставление с использованием FeedAttributeOperand (например, FeedAttributeId).

Такая же процедура может применяться для аккаунтов и групп объявлений. Чтобы установить связь с группами объявлений, создайте объект AdGroupFeed с помощью службы AdGroupFeedService, а для установки связи с аккаунтами – объект CustomerFeed с помощью службы CustomerFeedService.

5. Добавление расписания для элементов фида (необязательно)

При желании можно указать дни и часы активации элементов фида путем добавления FeedItemScheduling в объект FeedItem:

// Create and set the days and time.
FeedItemSchedule schedule = new FeedItemSchedule();
schedule.setDayOfWeek(dayOfWeek);
schedule.setStartHour(startHour);
schedule.setEndHour(endHour);
schedule.setStartMinute(startMinute);
schedule.setEndMinute(endMinute);

// Create the feed item scheduling.
FeedItemScheduling scheduling = new FeedItemScheduling();
scheduling.setFeedItemSchedules(new FeedItemSchedule[] {schedule});
item.setScheduling(scheduling);
Если нужно сбросить расписание, задайте пустой объект FeedItemScheduling, как показано ниже.

private static FeedItemOperation newSiteLinkFeedItemOperationResetScheduling(
    Long feedId, Long feedItemId) {
  // Create the feed item and operation.
  FeedItem feedItem = new FeedItem();
  feedItem.setFeedId(feedId);
  feedItem.setFeedItemId(feedItemId);

  FeedItemScheduling scheduling = new FeedItemScheduling();
  feedItem.setScheduling(scheduling);

  FeedItemOperation operation = new FeedItemOperation();
  operation.setOperand(feedItem);
  operation.setOperator(Operator.SET);
  return operation;
}

Полный исходный код

Дополнительную информацию о службах фидов можно найти в следующих примерах кода в наших клиентских библиотеках:
Библиотека Пример AddSitelinksUsingFeeds
Java AddSitelinksUsingFeeds.java
Perl add_site_links_using_feeds.pl
PHP AddSitelinksUsingFeeds.php
Python add_site_links_using_feeds.py
Ruby add_site_links_using_feeds.rb
.NET (C#) AddSitelinksUsingFeeds.cs
.NET (VB) AddSitelinksUsingFeeds.vb

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

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