使用字段掩码进行更新

在 Google Ads API 中，更新是使用字段掩码完成的。字段掩码会列出您打算通过更新更改的所有字段，并且系统会忽略字段掩码中未包含的任何指定字段，即使这些字段已发送到服务器也是如此。

字段掩码帮助程序

生成字段掩码的推荐方法是使用 google.api_core 软件包中包含的 field_mask 辅助函数。它接受两个 protobuf 对象，并返回一个字段掩码对象，其中包含一个 list 字段，该字段包含这两个对象之间不同的所有字段。

如果将 None 作为第一个参数传递，则字段掩码列表将仅包含第二个 protobuf 对象上未设置为默认值的所有字段。

构建完字段掩码对象后，应将其复制到要发送到服务器的操作对象：

下面是一个更新广告系列的示例：

from google.api_core import protobuf_helpers
from google.ads.googleads.client import GoogleAdsClient

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()
# Create a new campaign operation.
campaign_operation = client.get_type('CampaignOperation')
# Retrieve a new campaign object from its update field.
campaign = campaign_operation.update
# Mutate the campaign.
campaign.network_settings.target_search_network.value = False

# Create a field mask using the updated campaign.
# The field_mask helper is only compatible with raw protobuf message
# instances, which we can access using the ._pb attribute.
field_mask = protobuf_helpers.field_mask(None, campaign._pb)

# Copy the field_mask onto the operation's update_mask field.
client.copy_from(campaign_operation.update_mask, field_mask)

首先，我们创建一个空的 CampaignOperation 对象。然后，我们设置从中检索一个空的 Campaign 对象。然后，我们更新该广告系列对象并创建新的字段掩码，将其与 None 进行比较，这将生成一个仅包含已更改的 network_settings.target_search_network 字段的字段掩码列表。

下面是一个更新现有广告系列的示例。在这里，我们假设脚本已提供一个 resource_name 参数，该参数是广告系列的有效资源名称和有效的 customer_id：

import proto

from google.api_core import protobuf_helpers
from google.ads.googleads.client import GoogleAdsClient

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()
# Retrieve an instance of the GoogleAdsService.
googleads_service = client.get_service('GoogleAdsService')

# Search query to retrieve campaign.
query = f"""
    SELECT
      campaign.network_settings.target_search_network,
      campaign.resource_name
    FROM campaign
    WHERE campaign.resource_name = {resource_name}"""

# Submit a query to retrieve a campaign instance.
response = googleads_service.search_stream(customer_id=customer_id, query=query)

# Iterate over results to retrieve the campaign.
for batch in response:
    for row in batch.results:
        initial_campaign = row.campaign

# Create a new campaign operation.
campaign_operation = client.get_type('CampaignOperation')
# Set the copied campaign object to a variable for easy reference.
updated_campaign = campaign_operation.update
# Copy the retrieved campaign into the new campaign.
# Here we use the proto.Message.copy_from method because of its simple
# compatibility with the protobuf message instances, which are wrapped
# by the proto-plus library.
proto.Message.copy_from(updated_campaign, initial_campaign)
# Mutate the new campaign.
updated_campaign.network_settings.target_search_network = False

# Create a field mask using the updated campaign.
field_mask = protobuf_helpers.field_mask(
    initial_campaign._pb, updated_campaign._pb
)

# Copy the field mask onto the operation's update_mask field.
# Note that the client's copy_from  method is designed to work with both native
# messages and messages wrapped by proto-plus, so it works here for the
# update_mask, even though it's an instance of the native message class
# google.protobuf.field_mask_pb2.FieldMask.
client.copy_from(campaign_operation.update_mask, field_mask)

采用此策略后，updated_campaign 将与从 API 检索的 initial_campaign 共享所有相同的字段，即资源名称。生成的字段掩码会告知 API 只需更改 network_settings.target_search_network 字段。