前向兼容映射

借助 forwardCompatibilityMap 字段,您可以在一些最前沿的功能在 API 中正式公开之前先行研究它们。一些主要的 API 实体(例如 Campaign)中都包含了此字段。

forwardCompatibilityMap 属于 String_StringMapEntry 类型,表示字符串到字符串的映射。该映射用于获取和设置 API 实体的某些属性,即那些尚不可用作对象或其后代的正式属性的属性。这些属性通过 forwardCompatibilityMap 中的键加以公开。具有 forwardCompatibilityMap 字段的对象包括 CampaignAdGroupAdGroupAd

读取映射

您不需要将 forwardCompatibilityMap 字段引用为 Selector.fields 数组的一部分。如果您使用的 API 版本和服务中至少公开了一个键,则 forwardCompatibilityMap 字段将显示在响应中。

映射可包含一组键(每个对象类型对应一个键),这些键公开为对象或其后代之一的正式属性的扩展。对象的 forwardCompatibilityMap 中的键可能会引用该对象的后代的属性,而不是对象本身。例如,您可能会在 AdGroupAd 的映射中看到键 Ad.devicePreferred,但实际上,该键属于 Ad 对象(AdGroupAd 的后代)。

映射值的类型为 string,但根据相关键及其所表示的属性,这类值可以是其他基本数据类型(如整数或布尔值)的字符串表示形式。您可能需要先转换类型,然后再使用。

获取示例

以下是在 CampaignService 中调用 get() 方法的示例,该调用从 forwardCompatibilityMap 中获取 Campaign.enhanced 键。此示例产生自我们的 Java 客户端库

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

 // Create selector.
 Selector selector = new Selector();
 // Set the selector fields.
 // Notice there is no need to explicitly request the
 // forwardCompatibilityMap, indeed adding to the list of fields
 // will throw an error.
 selector.setFields(new String[] {"Id", "Name"});

 CampaignPage page = campaignService.get(selector);

 // Display campaigns.
 if (page.getEntries() != null) {
   for (Campaign campaign : page.getEntries()) {
     Map forwardCompatibilityMap =
         Maps.toMap(campaign.getForwardCompatibilityMap());
     System.out.println(String.format(
         "Campaign ID %d has enhanced value of '%s'",
         campaign.getId(),
         forwardCompatibilityMap.get("Campaign.enhanced")));
   }
 } else {
   System.out.println("No campaigns were found.");
 }

从映射中更改属性

通过 forwardCompatibilityMap 转变键(比如 Campaign.enhanced 键)与转变其他任何属性并无二致。您只需要调用 mutate() 方法,确保 forwardCompatibilityMap 中填充了您要更改的键和值。常规 ADDSET mutate 操作接受 forwardCompatibilityMap 数据,但可能需要一些配置。

务必为键传递有效的值,否则会产生 ApiException。另外,应确保使用正确的键名,因为使用错误或未定义的键名会被 API 忽略且不会发出相应的提示,从而可能导致难以诊断的错误。

Mutate 示例

以下示例演示如何通过在 forwardCompatibilityMap 中发送值为 trueCampaign.enhanced 键,将广告系列转变为增强型广告系列。此示例产生自 Java 客户端库

// This is an example on how to enhance a campaign using the
// CampaignService and the forwardCompatibilityMap field.

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

// Create campaign with updated status.
Campaign campaign = new Campaign();
campaign.setId(campaignId);
// Set the "Campaign.enhanced" as "true" to update the campaign.
campaign.setForwardCompatibilityMap(new String_StringMapEntry[] {
    new String_StringMapEntry("Campaign.enhanced",
        Boolean.TRUE.toString())});

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.SET);

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

// Update campaign.
CampaignReturnValue result = campaignService.mutate(operations);

处理错误

某些操作(比如在 forwardCompatibilityMap 中传递某个键的无效)会产生包含 ApiErrorApiException。该错误将包含指向 forwardCompatibilityMapfieldPath 以及填充了非法值的 trigger

传递无效的键名可能导致难以诊断的错误,因为 API 会允许传递该无效键名而不发出相关提示。

另外值得注意的是,键与具体的 API 版本相关联。对某个版本有效的键在其功能在 API 中正式实现后,将不再被未来的版本所接受。如果将某个键传递到不再接受它的 API 版本,将返回 ApiException

常见问题解答

如何请求在响应中填充 forwardCompatibilityMap?我在文档中没有看到它的字段名。

不必作为 Selector.fields 的一部分请求该字段,只要应返回到映射中的对象附加有数据,就会填充该字段。

为何未填充 forwardCompatibilityMap

一般来说是因为对象中没有任何数据附加到您期望在映射中看到的键。

如果在映射中发送了错误的键,会收到错误吗?

不会,在指定键的名称时要小心,因为 API 会在不发出提示的情况下忽略无法识别的键。

我知道对象中有受支持的新字段/键,但是该对象似乎没有 forwardCompatibilityMap

只有最高一级的 API 实体(比如 CampaignAdGroupAdGroupAd)才可公开 forwardCompatibilityMap。但是,有些键会影响底层对象。

如果在映射中发送了错误的值,会发生什么情况?

如果您设置了正确的键,但使用了不受支持的值,将返回 ApiException

键会在所有 API 版本中都公开吗?

不会,只有在尚未公开此功能的 API 版本中才会公开和接受键。

发送以下问题的反馈:

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