对象、方法和服务

本指南以一些常见的广告系列管理任务作为示例,介绍了 AdWords API 对象和方法,接着说明了 API 提供的服务,并提供了指向相应参考页面的链接。

本指南中的代码示例使用的是 AdWords API Java 库。对于其他编程语言,请参阅客户端库的完整列表

AdWords API 主要供 AdWords 的高级用户使用。如果您是 AdWords 新手,或需要复习 AdWords 基本概念,请查看 AdWords 基础知识页面

对象层级结构和范围

可以将每个 AdWords 帐号视为由多个对象组成的层级结构。

每个帐号下都有一个或多个 Campaigns,表示您正在投放的广告系列。

每个广告系列有多个 AdGroups,用来按逻辑将您的广告加以组合。

每个 AdGroup 中有多个 AdGroupAdsAdGroupCriteria。AdGroupAd 表示您正在投放的广告。AdGroupCriterion 代表用于定义广告触发方式的条件,即关键字。

您可以指定广告系列条件,以定义整个广告系列广告触发方式的规则。您还可以指定整个广告系列的预算和日期。

最后,在广告系列一级可以使用广告附加信息,可让您在广告中提供额外信息,例如电话号码、街道地址等。

AdWords 中的每个对象都由自己的 ID 标识。其中某些 ID 在所有 AdWords 帐号中具有全局唯一性,而其他 ID 仅在限定范围内是唯一的。AdWords 中每个对象 ID 的唯一性如下表所示。

对象 ID 唯一性的范围 是否在全局级别具有唯一性?
预算 ID 全局
广告系列 ID 全局
AdGroup ID 全局
广告 ID 广告组 否。(AdGroupId, AdId) 对在全局级别具有唯一性。
AdGroupCriterion ID 广告组 否。(AdGroupId, CriterionId) 对在全局级别具有唯一性。
CampaignCriterion ID 广告系列 否。(CampaignId, CriterionId) 对在全局级别具有唯一性。
广告附加信息 广告系列 否。(CampaignId, AdExtensionId) 对在全局级别具有唯一性。
Feed ID 全局
Feed Item ID 全局
Feed Attribute ID Feed
Feed Mapping ID 全局
标签 ID 全局

在设计本地数据库以存储 AdWords 对象时,这些 ID 规则很有用。

如果某个对象是从其他对象衍生出来的,那么该对象还会有一个 Type 字段。例如,TextAd 有一个表示它是衍生自 Ad 对象的 Type 字段。如果您使用动态语言,可以使用此字段来检查对象的类型,例如,查看 Ad 对象是否为 TextAd 类型。

方法和操作

AdWords API 提供管理 AdWords 对象的服务。例如,CampaignService 用于管理 Campaign,而 AdGroupService 用于管理 AdGroup,依此类推。

所有这些服务都提供两种标准方法:get()mutate()

get() 方法

get() 方法用于获取 AdWords 对象。例如,您可以使用 CampaignService.get() 来获取广告系列列表。

每个 get() 方法将 selector 作为输入条件,并返回一个 page 作为结果。默认情况下,AdWords API 不会返回相应对象的所有字段,您需要在构建选择器时指定您想要获取的 fields 列表。

您可以使用 predicates 过滤结果,使用 ordering 对结果排序,使用 dateRange 限制获取结果的时间段。

如果您要拉取很多对象,则还需要指定 paging;否则,AdWords API 会产生 SizeLimitError.RESPONSE_SIZE_LIMIT_EXCEEDED 错误。

以下代码段用于获取和显示帐号中的所有广告系列,展示了这些概念的实际应用:

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

int offset = 0;

// Create selector.
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 {
  // Get all campaigns.
  page = campaignService.get(selector);

  // Display campaigns.
  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 查询语言 (AWQL),不使用选择器。在 AWQL 中对相同的请求进行编码通常更有效率。大多数常见服务都支持 query() 方法。请注意,AWQL 不支持对数据进行转变。

要展现 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);
  // Get all campaigns.
  page = campaignService.query(pageQuery);

  // Display campaigns.
  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 编写相同请求的方式更为简洁和直观。要了解更多信息,请参阅 AWQL 指南

mutate() 方法

mutate() 方法用于转变(创建、更新或移除)AdWords 对象。

要转变对象,您必须构建相应的 Operation 对象。例如,要转变 Campaign,您必须创建 CampaignOperation

operator 字段定义要执行的操作类型(ADDSETREMOVE)。操作数字段保留要转变的对象。以下代码段会添加广告系列:

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Create campaign.
Campaign campaign = new Campaign();
campaign.setName("Interplanetary Cruise #" + System.currentTimeMillis());

// Recommendation: Set the campaign to PAUSED when creating it to prevent
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
campaign.setStatus(CampaignStatus.PAUSED);

BiddingStrategyConfiguration biddingStrategyConfiguration = new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);

// You can optionally provide a bidding scheme in place of the type.
ManualCpcBiddingScheme cpcBiddingScheme = new ManualCpcBiddingScheme();
cpcBiddingScheme.setEnhancedCpcEnabled(false);
biddingStrategyConfiguration.setBiddingScheme(cpcBiddingScheme);

campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// You can optionally provide these field(s).
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));

// Only the budgetId should be sent, all other fields will be ignored by CampaignService.
Budget budget = new Budget();
budget.setBudgetId(budgetId);
campaign.setBudget(budget);

campaign.setAdvertisingChannelType(AdvertisingChannelType.SEARCH);

// Set the campaign network options to Search and Search Network.
NetworkSetting networkSetting = new NetworkSetting();
networkSetting.setTargetGoogleSearch(true);
networkSetting.setTargetSearchNetwork(true);
networkSetting.setTargetContentNetwork(false);
networkSetting.setTargetPartnerSearchNetwork(false);
campaign.setNetworkSetting(networkSetting);

// Set options that are not required.
GeoTargetTypeSetting geoTarget = new GeoTargetTypeSetting();
geoTarget.setPositiveGeoTargetType(GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE);
campaign.setSettings(new Setting[] {geoTarget});

// You can create multiple campaigns in a single request.
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);

// Create operations.
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};

// Add campaigns.
CampaignReturnValue result = campaignService.mutate(operations);

// Display campaigns.
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 字段指示希望执行的转变操作的类型:ADDSETREMOVE

ADD 用于创建新对象,SET 用于更新现有对象,REMOVE 用于移除现有对象。然而,某些运算符可能不适用于某些服务。

例如,AdWords 广告系列一经创建将无法永久移除,您只能将其标记为 REMOVED。虽然它的状态是 REMOVED,您仍然可以查询其详细信息和统计数据。

AdWords API 在 CampaignService 中不支持 REMOVE 运算符;您需要更新广告系列,方法是使用 SET 运算符将其状态更改为 REMOVED

相比而言,广告系列定位无法更改:您只能对这些对象使用 ADDREMOVE

下表详细说明了如何控制不同 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 如何处理针对同一对象的并发 mutate 请求。

不能同时由多个来源并行修改 AdWords 对象。这包括从同一应用的多个线程或通过其他应用(例如,您的应用和一个同时进行的 AdWords 编辑器会话)更新对象。API 不提供在更新之前锁定对象的方法:如果两个源试图同时转变对象,则 API 会引发 CONCURRENT_MODIFICATION_ERROR 错误。

您可以在这篇博文中了解有关 AdWords API 并发管理的详情。

异步转变与同步转变

AdWords API mutate() 方法是同步的:只有在对象发生转变后,API 调用才会返回响应,因此需要等待对每个请求的响应。虽然这种方法在代码编写方面相对简单,但它可能会对负载平衡造成负面影响,在机器等待调用完成时会造成资源浪费。

另一种方法是使用 BatchJobService 异步转变对象,这种方法无需等待操作完成,即可对多个服务执行批处理操作。提交批处理作业后,AdWords API 服务器会异步执行操作,释放计算机的资源,以便执行其他操作,并定期检查作业状态是否为已完成。

有关异步处理的更多信息,请参见批处理指南

转变验证

validateOnly SOAP 标头允许测试 API 调用,而不对真实数据实际执行调用:您可以测试缺少的参数和不正确的字段值,而不实际执行操作。

要使用此功能,请在 RequestHeader 中将 validateOnly 字段设置为 true。默认情况下,客户端库会将此字段设置为 false

系统会对您的请求进行充分验证,就像即将执行该请求一样,但会跳过最终的执行步骤。如果没有找到错误,则返回空响应。如果验证失败,错误消息会指明失败点。

下面是一个使用 Java 库设置 validateOnly 的示例。

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 测试新广告可让您轻松查看哪些广告会被拒绝。请参阅处理违规错误的代码示例以查看实际操作情况。

如果不使用客户端库,则只需设置正确的 SOAP 标头,您仍可以验证您的 mutate() 请求。

AdWords API 服务

本节介绍了 AdWords API 提供的服务,并提供了指向各项服务其他详细信息所在参考页的链接。

AdWords API 服务可组合为四个功能类别:

广告系列数据管理

使用广告系列数据管理服务来处理 AdWords 广告系列及其相关联的实体。每个广告系列数据管理服务都对应于广告系列数据层级结构中的实体。

服务 说明
CampaignService 创建、更新和移除广告系列。广告系列由一个或多个广告组组成,并且有自己的预算、出价策略、投放日期范围和定位设置。
AdGroupService 创建、更新和移除广告组。广告组由一组广告和条件组成,并为其条件提供默认出价。
AdGroupAdService 创建、更新和移除广告。
CampaignExtensionSettingService 创建、更新和移除广告附加信息。广告系列的广告附加信息通过向广告系列中的所有广告添加地址信息、附加链接或电话号码来丰富标准文字广告。
CampaignCriterionService
AdGroupCriterionService
创建、更新和移除条件。条件决定广告是否应该展示。
ConversionTrackerService
OfflineConversionFeedService
了解用户点击您的广告后会发生什么,以衡量广告和关键字的效果。OfflineConversionFeedService 处理离线转化数据的导入。
DataService 根据指定的条件获取广告系列管理数据。
FeedService
FeedItemService
FeedMappingService
AdGroupFeedService
CampaignFeedService
创建自定义数据 Feed 以管理网站、电话和应用附加链接信息。
AdwordsUserListService 创建、更新和移除用户列表。用户列表和用户列表条件会向之前在您的网站上触发了转化事件的用户展示广告。
BudgetService 创建、更新和移除预算。用于管理可在广告系列之间共享的预算。

优化

使用优化服务获取效果统计信息并查找新条件的参考提示。

服务 说明
ReportDefinitionService 创建和下载各种效果报告。
TargetingIdeaService 根据您指定的参数生成新的关键字和展示位置参考提示。
TrafficEstimatorService 获取所提议的广告系列、广告组和关键字的流量估算值。
ExperimentService 创建并运行广告系列实验,供您在其中测试关键字、出价和展示位置。

帐号管理

使用帐号管理服务来跟踪您的帐号活动。

服务 说明
CustomerService 获取有关客户帐号的基本详细信息。
CustomerSyncService 获取指定日期范围内广告系列数据的更改记录。
ManagedCustomerService 管理客户帐号以及经理帐号和客户帐号之间的关联。

实用工具

使用这些实用工具服务通过 AdWords API 执行各种实用任务。

服务 说明
BatchJobService 异步处理大批量的广告系列数据操作。与对标准网络服务的同步调用相比,完成批处理作业所需的时间更长,不过具有其他优势(如批处理指南中所述)。
MediaService 上传和获取您在基于媒体的广告(例如图片广告或视频广告)中使用的媒体的 ID。
ConstantDataService 获取 API 使用的常量值。
LocationCriterionService 获取地理位置条件的 ID。

广告系列数据

处理广告系列数据是使用 AdWords API 执行的基本任务之一。下表说明了各个广告系列数据实体及各实体与其他广告系列数据的关系。

实体
子实体(数量)
数据类型 说明
广告系列
广告组 (1+)
广告系列定位列表 (7)
广告系列广告附加信息 (0+)
广告系列条件 (0+)
Campaign 广告系列由一个或多个广告组组成,并且有自己的预算、出价策略和投放日期范围。
广告组
广告 (1+)
条件 (1+)
AdGroup
广告组由一组广告和条件组成,并为其条件提供默认出价。
广告
广告附加信息覆盖 (0+)
AdGroupAd 可用广告类型在 API 参考中作为为抽象 Ad 类型的子类记录。
条件
AdGroupCriterionCampaignCriterion 条件决定广告是应该得到展示(可出价条件)还是不应得到展示(排除条件)。广告组条件会影响父级广告组中的广告。广告系列条件(始终是排除条件)定义了阻止广告系列的广告进行展示的条件。
广告附加信息
CampaignExtensionSetting 广告系列的广告附加信息通过向广告系列中的所有广告添加地址信息、附加链接或电话号码来丰富标准文字广告。
Feed
Feed Feed 可用作广告附加信息(附加链接、电话、应用)的数据渠道。
用户列表
UserList 用户列表跟踪曾对您的网站感兴趣的用户。通过创建用户列表条件并将其关联到现有用户列表,可以将广告定位到这组用户。
预算
Budget 预算用于管理在广告系列上花费的金额。可以在不同的广告系列之间共享预算,系统将确定最佳分配方式。

发送以下问题的反馈:

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