在 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。詳情請參閱「將空白訊息物件設為欄位」。