使用字段掩码进行更新

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

字段掩码帮助程序

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

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

构建完成后,字段掩码对象应复制到将发送到服务器的操作对象上。

根据新的本地对象进行更新

在以下示例中,您将创建一个空的 CampaignOperation对象,并从其update字段检索一个 空的Campaign对象。然后,您将修改该广告系列对象,并通过将其与 None 进行比较来创建新的字段掩码,这将生成一个包含经过修改的 network_settings.target_search_network 字段的字段掩码:

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

# 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 and set its resource
# name.
campaign = campaign_operation.update
campaign.resource_name = client.get_service("CampaignService").campaign_path(
    customer_id, campaign_id
)

# Mutate the campaign (use direct attribute assignment in proto-plus).
campaign.network_settings.target_search_network = False

# Create a field mask using the updated campaign.
# The field_mask helper is compatible with raw protobuf message instances,
# which you 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)

更新现有资源

以下示例会更新从 API 检索到的现有广告系列,并假定存在有效的 resource_name 和 customer_id。使用此策略,updated_campaign 会共享在 initial_campaign 上检索到的所有字段(包括其 resource_name),并且生成的字段掩码会告知 API 只有 network_settings.target_search_network 字段发生了更改:

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

# 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 the campaign. Quote string literals in GAQL.
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.
initial_campaign = None
for batch in response:
    for row in batch.results:
        initial_campaign = row.campaign
        break

if not initial_campaign:
    raise ValueError(f"Campaign '{resource_name}' not found.")

# 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.
# client.copy_from works with both native protobuf messages and messages
# wrapped by the proto-plus library.
client.copy_from(updated_campaign, initial_campaign)

# Mutate the new campaign.
updated_campaign.network_settings.target_search_network = False

# Create a field mask by comparing initial and updated protobuf objects.
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 works with both native messages
# and messages wrapped by proto-plus, including google.protobuf.field_mask_pb2.
client.copy_from(campaign_operation.update_mask, field_mask)

清除字段或设置空消息

与 None 进行比较时,field_mask 帮助程序会忽略设置为空值或默认值的字段。如需明确清除字段或设置空消息字段,请将字段路径直接附加到 campaign_operation.update_mask.paths。 如需了解详情,请参阅 将空消息对象设置为字段。