使用欄位遮罩更新

在 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 欄位。