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 填充数据。每个 Feed 项表示表格中的一行。
FeedMappingService
此服务用于指定 Feed 如何将表格的列映射到特定 AdWords 功能字段。本指南展示了如何映射要用于附加链接的 Feed。
CustomerFeedService
此服务会在客户的整个帐号(即所有广告系列和广告组)中启用您的 Feed。
CampaignFeedService
此服务会在整个广告系列(即该广告系列中的所有广告组)中启用您的 Feed。
AdGroupFeedService
此服务会为特定广告组启用您的 Feed。

Java 代码示例

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

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

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


1. 创建 Feed。

使用 FeedService 来描述要上传的数据的构成,包括 Feed(表格)的名称或标题以及一组 Feed 属性(列)。每个 Feed 属性还具有自己的名称(列标题)和类型。

在下面的示例代码中,createSiteLinksFeed() 使用 FeedService 创建 FeedAttribute 实例适合附加链接的 Feed

private static void createSiteLinksFeed(
    AdWordsServicesInterface adWordsServices,
    AdWordsSession session,
    SiteLinksDataHolder siteLinksData,
    String feedName)
    throws RemoteException {
  // 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 line2Attribute = new FeedAttribute();
  line2Attribute.setType(FeedAttributeType.STRING);
  line2Attribute.setName("Line 2");
  FeedAttribute line3Attribute = new FeedAttribute();
  line3Attribute.setType(FeedAttributeType.STRING);
  line3Attribute.setName("Line 3");

  // Create the feed.
  Feed siteLinksFeed = new Feed();
  siteLinksFeed.setName(feedName);
  siteLinksFeed.setAttributes(
      new FeedAttribute[] {textAttribute, finalUrlAttribute, line2Attribute, line3Attribute});
  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.line2FeedAttributeId = savedAttributes[2].getId();
  siteLinksData.line3FeedAttributeId = savedAttributes[3].getId();
  System.out.printf("Feed with name '%s' and ID %d with linkTextAttributeId %d"
      + " and linkFinalUrlAttributeId %d and line2AttributeId %d"
      + " and line3AttributeId %d was created.%n",
      savedFeed.getName(),
      savedFeed.getId(),
      savedAttributes[0].getId(),
      savedAttributes[1].getId(),
      savedAttributes[2].getId(),
      savedAttributes[3].getId());
}

为了描述将用于附加链接的表格数据,此方法创建具有以下 Feed 属性的 Feed:

  • 链接文字
  • 链接最终到达网址
  • 第 1 行
  • 第 2 行
  • 第 3 行

我们设置了 Feed 名称和 Feed 来源 FeedOrigin.USER,表示相应的 Feed 项将由广告客户(而非 AdWords)填充。

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

请注意,我们 Feed 的列数与附加链接所需的列数完全一致。但是,我们将在后面看到,您还可以创建一个包含更多列(超出 AdWords 功能所需的列数)的 Feed。这么做的一个原因是使用额外列中的值,以便通过匹配函数进行过滤,从而确定要将每个 Feed 项(行)用于哪个广告系列或广告组。

2. 填充 Feed

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

我们从一个辅助方法 newSiteLinkFeedItemAddOperation() 开始构造 Feed 项。此辅助方法会获取关于附加链接和 Feed 属性 ID 的信息,以填充新的 Feed 项。然后,新的 Feed 项会被封装在 ADD 操作中并返回。

要理解如何构造 FeedItem,请记住表格的这一特征:每行是一组单元格,每个单元格位于特定列中,并包含一些内容。类似地,FeedItem(行)是一组 FeedItemAttributeValue 实例(单元格),每个 FeedItemAttributeValue(单元格)包含 FeedAttribute(单元格所在的列)的 ID 和 stringValue(如果是字符串,则为单元格的内容)。

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

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line2, String line3,
    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 line2TextAttributeValue = new FeedItemAttributeValue();
  line2TextAttributeValue.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2TextAttributeValue.setStringValue(line2);
  FeedItemAttributeValue line3TextAttributeValue = new FeedItemAttributeValue();
  line3TextAttributeValue.setFeedAttributeId(siteLinksData.line3FeedAttributeId);
  line3TextAttributeValue.setStringValue(line3);

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

  // 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() 为每个要创建的附加链接调用包含不同信息的辅助方法,从而创建所有 Feed 项和包含它们的 Feed 项操作。

mutate 调用返回的 Feed 项包括我们存储在 siteLinksData 中供以后使用的 ID。(同样,我们假设此对象已经创建完成,并且具有相应字段来保存 ID。)

private static void createSiteLinksFeedItems(AdWordsServicesInterface adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws RemoteException {
  // 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 2", "Home line 3");
  FeedItemOperation stores = newSiteLinkFeedItemAddOperation(siteLinksData, "Stores",
      "http://www.example.com/stores", "Stores line 2", "Stores line 3");
  FeedItemOperation onSale = newSiteLinkFeedItemAddOperation(siteLinksData, "On Sale",
      "http://www.example.com/sale", "On Sale line 2", "On Sale line 3");
  FeedItemOperation support = newSiteLinkFeedItemAddOperation(siteLinksData, "Support",
      "http://www.example.com/support", "Support line 2", "Support line 3");
  FeedItemOperation products = newSiteLinkFeedItemAddOperation(siteLinksData, "Products",
      "http://www.example.com/prods", "Products line 2", "Products line 3");
  // 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 2", "About Us line 3", 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 用于将 Feed 映射到占位符类型,指示如何使用 Feed;并将一些 Feed 属性(列)映射到占位符字段,指示如何针对此 AdWords 功能解释这些 Feed 属性。

// 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_2_TEXT = 3;
private static final int PLACEHOLDER_FIELD_LINE_3_TEXT = 4;

private static void createSiteLinksFeedMapping(AdWordsServicesInterface adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws RemoteException {
  // 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 line2FieldMapping = new AttributeFieldMapping();
  line2FieldMapping.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_2_TEXT);
  AttributeFieldMapping line3FieldMapping = new AttributeFieldMapping();
  line3FieldMapping.setFeedAttributeId(siteLinksData.line3FeedAttributeId);
  line3FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_3_TEXT);

  // Create the FeedMapping and operation.
  FeedMapping feedMapping = new FeedMapping();
  feedMapping.setPlaceholderType(PLACEHOLDER_SITELINKS);
  feedMapping.setFeedId(siteLinksData.siteLinksFeedId);
  feedMapping.setAttributeFieldMappings(new AttributeFieldMapping[] {linkTextFieldMapping,
      linkFinalUrlFieldMapping, line2FieldMapping, line3FieldMapping});
  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。此方法还会将 Feed 属性映射到附加链接所需的占位符字段。此映射可让 AdWords 了解:每个 Feed 属性(列)对应的是附加链接的哪个方面。

并非所有 Feed 属性都必须映射到占位符字段。如前所述,Feed 所拥有的 Feed 属性可以超过 AdWords 功能的需要。这些额外的 Feed 属性可用于通过匹配函数来过滤 Feed 项。

同一 Feed 可用于多个 FeedMapping,这对有多个 AdWords 功能需要类似的表格数据的情况非常有用。

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

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

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

关联 Feed 时,您可以过滤出实际为要该客户、广告系列或广告组启用哪些 Feed 项(行)。例如,您可以有一个 Feed,其中的某些 Feed 项(通过过滤器)应用于一个广告系列,而其他 Feed 项(通过另一个过滤器)应用于另一个广告系列等。在应用过滤器时,需要提供可对每个 Feed 项进行求值的匹配函数。

private static void createSiteLinksCampaignFeed(
    AdWordsServicesInterface adWordsServices,
    AdWordsSession session,
    SiteLinksDataHolder siteLinksData,
    Long campaignId)
    throws RemoteException {
  // 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 间建立了关联。此数据中有两个部分配置了这一关联:占位符类型和匹配函数(过滤器)。

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

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

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

5. 安排 Feed 项(可选)

您可以通过设置 Feed 项的 schedules 属性来选择指定 Feed 项的具体启用日期和时段。只需将 schedules 设置为包含 FeedItemScheduleFeedItemScheduling,即可指定您希望在一周中的每一天启用 Feed 项的开始/结束时间。

要从 Feed 项中移除所有时间安排,请将其 schedules 设置为具有空 feedItemSchedules 集合的 FeedItemScheduling 对象。

有关如何构造 FeedItemSchedule 的示例,请查看用于更新广告附加信息的代码段

6. 为 Feed 项设置定位条件(可选)

从 201802 版开始,您可以使用 FeedItemTargetService 限制单个 Feed 项,让其仅定位特定广告系列、广告组或条件。

例如,如果您想限制某个给定的 Feed 项,让其应用到广告系列中的某个广告组,则请创建一个包含 feedIdfeedItemIdadGroupIdFeedItemAdGroupTargetFeedItemAdGroupTarget 可确保该 Feed 项将只会在该广告组中投放。

请记住,以这种方式定位只发挥限制作用,这意味着您要定位的实体必须已包含在先前设置的匹配函数中。设置 FeedItemTarget 会限制该 Feed 项仅能针对该实体进行投放,但不会扩展该匹配函数,使之包含该实体(如果尚未包含)。

移除 Feed 项

要移除 Feed 项,请将其 status 设置为 REMOVED。已移除且没有关联统计信息的 Feed 项将在一段时间后被永久删除。

代码示例

请参阅我们客户端库中的以下完整代码示例,了解有关 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
C# AddSitelinksUsingFeeds.cs
VB.NET AddSitelinksUsingFeeds.vb

发送以下问题的反馈:

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