Feed 服务简介

本指南介绍了 Feed,它提供了一种供您在 AdWords 帐号中提供并使用表格数据的通用且灵活的方式。使用表格数据的 AdWords 功能有广告附加信息、广告定制工具和动态再营销等等。本指南使用附加链接作为运行示例来说明如何使用 Feed 服务,不过其他表格数据类型的过程与此类似,只是要用到不同的占位符类型,如下所述。

本指南使用 Java 作为代码示例。如要查看其他编程语言的代码示例,请参阅本指南末尾的表格

客户场景

假设您是一位广告客户,希望使用 AdWords 为您的网站获取更多流量。您想随广告一起展示附加链接,方便用户更快捷地访问您网站上的特定版块。

以下是您要在广告下展示的附加链接的一些详细信息:

附加链接名称 附加链接最终到达网址
首页 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

请注意,数据是表格式的:每列都是一个附加链接属性,每行都为一个附加链接提供值。

Feed 服务

可以使用多种相互关联的服务创建和管理 Feed。

FeedService
此服务用于向 AdWords 说明您的表格数据的构成,即 Feed(表格)的名称或标题以及列名称和类型。
FeedItemService
此服务用于为 Feed 填充数据。每个 FeedItem 表示表格中的一行。
FeedMappingService
此服务用于指定 Feed 的使用方式,即如何将表格的列与特定 AdWords 功能所需的字段相对应。本指南展示了如何映射要用于附加链接的 Feed。
CustomerFeedService
此服务会在客户的整个帐号(即所有广告系列和广告组)中启用您的 Feed。
CampaignFeedService
此服务会在整个广告系列(即该广告系列中的所有广告组)中启用您的 Feed。
AdGroupFeedService
此服务会为特定广告组启用您的 Feed。

Java 代码示例

以下代码示例演示了如何添加附加链接 Feed,并使用 Java 客户端库将其与广告系列相关联。有关完整的代码示例,请参阅文档末尾提供的表格

要向广告系列添加附加链接,您需要完成以下几个步骤:

  1. 创建 Feed。
  2. 填充 Feed。
  3. 将 Feed 映射到附加链接占位符字段。
  4. 将 Feed 与客户、广告系列或广告组关联
  5. 安排应启用 Feed 项的时间(可选)。


1. 创建附加链接 Feed

我们使用 FeedService 来描述要上传的数据的构成,包括 Feed(表格)的名称或标题以及一组 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());
}

为了描述将用于附加链接的表格数据,此方法创建一个 Feed,其 FeedAttribute(列)名为链接文字最终到达网址第 1 行第 2 行。为便于参考,我们赋予该 Feed 一个有说明作用的名称:用于附加链接的 Feed。Feed 的来源设置为 FeedOrigin.USER,表示其 FeedItem(行)将由广告客户填充。(另一种相对的情况是,Feed 由 AdWords 填充数据。)

系统会在 FeedService 上调用 Mutate 操作,从而创建 Feed。成功添加 Feed 后,FeedService 将返回其 ID 以及每个 FeedAttribute(列)的所有 ID。请务必存储这些 ID,以用于之后的其他服务。为简单起见,我们的示例假设已创建一个类型为 SiteLinksDataHolder 的名为 siteLinksData 的对象,并且具有相应字段可用来保存 ID。我们将在后续步骤中使用此对象来提取 ID。您可以用自己的实现语言创建类似的对象。

请注意,我们 Feed 的列数与附加链接所需完全一致。但是,我们将在后面看到,您还可以创建一个包含更多列的 Feed,而其中只有部分列包含 AdWords 功能所需的数据。您之所以这么做,一种可能的原因是要使用其他列中的值,以借助于匹配函数过滤并确定要将哪个 FeedItem(行)用于哪个广告系列或广告组,如下所述。

2. 填充 Feed

现在已经向 AdWords 说明了数据的构成,接下来就可以通过使用 FeedItemService 添加 FeedItem(行)来填充附加链接数据。

我们从一个辅助方法 newSiteLinkFeedItemAddOperation() 开始构造 FeedItem。此辅助方法会获取关于附加链接的信息(其文字标签、finalUrl 和内容描述行)以及关于 Feed 的 FeedAttribute(列)ID 的信息,以创建使用所提供信息填充的新的 FeedItem(行)。然后,新的 FeedItem 会被封装在 ADD 操作中并返回。

要理解如何构造 FeedItem,请记住表格的这一特征:每行是一组单元格,每个单元格位于特定列中,并包含一些内容。类似地,FeedItem(行)是一组 FeedItemAttributeValue(单元格),每个 FeedItemAttributeValue(单元格)包含 FeedAttribute(单元格所在的列)的 ID 和 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 调用返回的 FeedItem 包括我们存储在 siteLinksData 中供以后使用的 ID。(同样,我们假设此对象已经创建完成,并且具有相应字段可用于保存 ID。)

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. 将 Feed 映射到占位符字段

使用表格数据的每个受支持的 AdWords 功能都有一个占位符类型,用于指定该功能所需的字段和数据类型。FeedMappingService 用于将 Feed 映射到占位符类型,指示如何使用 Feed;并将一些 FeedAttribute(列)映射到占位符字段,指示如何针对此 AdWords 功能解释这些 FeedAttribute。

// 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());
  }
}

在此示例中,此方法将 Feed 配置为用于附加链接。具体配置方法是将 FeedMapping 上的一个占位符类型设置为常量 PLACEHOLDER_SITELINKS。此常量的值为 1。此方法还会将 FeedAttribute 映射到附加链接所需的占位符字段:链接文字、最终到达网址和内容描述行。此映射告诉 AdWords,哪个 FeedAttribute(列)与附加链接的哪个方面相对应。

4. 将 Feed 与客户、广告系列或广告组关联

至此,我们创建的 Feed 已经可以用于附加链接了。最后一步是将 Feed 与客户 (CustomerFeedService)、广告系列 (CampaignFeedService) 或广告组 (AdGroupFeedService) 关联起来,以便针对特定的一组广告启用附加链接。

是否将 Feed 与某个客户、广告系列或广告组相关联取决于 Feed 中的数据和您希望获得的控制级别。再次以附加链接为例,如果广告系列中的所有广告组都应展示相同的附加链接,则您可以将 Feed 与广告系列相关联。同样,如果您希望每个广告系列都使用附加链接,请将 Feed 与帐号相关联。另一方面,如果同一个广告系列中的不同广告组应展示不同的附加链接,则您应该仅将该 Feed 与特定广告组相关联。

关联 Feed 时,您可以过滤实际为该客户、广告系列或广告组启用哪些 FeedItem(行)。例如,您可以有一个 Feed,其中的某些 FeedItem(通过过滤器)应用于一个广告系列,而其他 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());
  }
}

此方法在广告系列和 Feed 间建立了关联。此数据中有两个部分配置了此关联:占位符类型和匹配函数(过滤器)。

您可能希望了解,为什么已经在 FeedMapping 中为 Feed 进行了整体配置,还需要为 CampaignFeed 再次配置占位符类型(在此示例中为附加链接)。之所以要求再次配置占位符,原因在于这可以提高具有多个 FeedMapping 的 Feed 的灵活性:这些 FeedMapping 在一些广告系列中仅用于某些占位符类型,在其他广告系列中用于其他占位符类型。

在 CampaignFeed 中设置匹配函数可告知投放系统,哪些 FeedItem(行)能够实际用作附加链接。有关更多详细信息,请参阅匹配函数指南。在本例中,我们使用了 FEED_ITEM_ID 作为匹配函数中的 RequestContextOperand;但我们也可以使用另一种简便的方法,即:使用其他 RequestContextOperand 类型,或者使用 FeedAttributeOperand(例如 FeedAttributeId)实现匹配。

对广告组和客户也可以使用相同的流程。您可以使用 AdGroupFeedService 创建 AdGroupFeed,或使用 CustomerFeedService 创建 CustomerFeed,以连接 Feed。

5. 安排应启用 Feed 项的时间(可选)

您可以选择指定 FeedItem 的具体启用日期和时段,具体方法是将 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;
}

完整的源代码

请参阅我们的客户端库中的以下代码示例,详细了解 Feed 服务。
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

发送以下问题的反馈:

此网页
AdWords API
AdWords API
需要帮助?请访问我们的支持页面