字段掩码

在 Google Ads API 中，字段掩码用于提供 API 请求应更新的字段列表。即使发送到服务器，系统也会忽略字段掩码中未指定的任何字段。

FieldMaskUtil 类

建议使用内置的 FieldMaskUtil 类生成字段掩码，这样您就可以从修改后的对象生成字段掩码，而无需从头开始构建。

以下示例展示了如何更新广告系列，其中使用 FieldMasks.AllSetFieldsOf 方法生成一个枚举所有已设置字段的字段掩码。然后，您可以将生成的字段掩码直接传递给更新调用。

// Update campaign by setting its status to paused, and "Search network" to false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

有时，您可能需要处理现有对象，并更新一些字段。在这种情况下，您需要修改代码以改用 FieldMasks.FromChanges 方法。此方法会生成一个表示两个对象之间差异的字段掩码。

Campaign existingCampaign;

// Obtain existingCampaign from elsewhere.
...

// Create a new campaign based off the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
}

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

如何处理 FieldMaskError.FIELD_HAS_SUBFIELDS 错误

在极少数情况下，您可能需要设置某个字段，而不更新该类型的任何子字段。请参考以下示例：

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
};

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

此 API 调用将失败并显示 FieldMaskError.FIELD_HAS_SUBFIELDS 错误。 由于 MaximizeConversions 具有三个子字段，因此 Google Ads API 服务器希望请求中包含这些字段的字段掩码。不过，在这种情况下，FieldMaskUtil 无法正确生成字段掩码，因为请求未设置这些字段。

在这种情况下，您可以手动修改字段掩码，如下所示：

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
// Only include 'maximize_conversions.target_cpa_micros' in the field mask
// as it is the only mutable subfield on MaximizeConversions when used as a
// standard bidding strategy.
//
// Learn more about standard and portfolio bidding strategies here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

如何清除字段

Google Ads API 支持清除某些字段值。如需清除某个字段，您必须手动为该字段设置字段掩码。将字段设置为其默认值（例如 int64 字段的零）不会清除该字段。

以下代码示例展示了如何清除 MaximizeConversions 出价策略的 target_cpa_micros 字段。

正确代码

以下代码会清除 target_cpa_micros 字段，因为我们在字段掩码中设置了 maximize_conversions.target_cpa_micros，但未设置 campaign.MaximizeConversions.TargetCpaMicros 字段。

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

验证码不正确

以下代码不会清除 target_cpa_micros 字段，因为我们将此字段设置为零。FieldMaskUtils 和 Google Ads API 服务器都会忽略此值。此外，在这种情况下，您可能也不会收到错误，因为服务器忽略了该值。

// Creates a campaign with the proper resource name and a MaximizeConversions
// object. Attempt to clear the target_cpa_micros field by setting it to 0.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// Constructs an operation, using the FieldMasks' AllSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because 'maximize_conversions.target_cpa_micros'
// was not included in the field mask.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });