Google Ads API では、フィールド マスクを使用して更新を行います。フィールド マスクには、更新によって変更するすべてのフィールドが一覧表示されます。フィールド マスクに含まれていないフィールドは、サーバーに送信されても無視されます。
フィールド マスク ヘルパー
フィールド マスクを生成するには、google.api_core パッケージに含まれている field_mask ヘルパー関数を使用することをおすすめします。この関数は 2 つの protobuf オブジェクトを受け取り、2 つのオブジェクト間で異なるすべてのフィールドを含む paths リストを持つフィールド マスク オブジェクトを返します。
最初のパラメータとして None が渡されると、フィールド マスク リストには、デフォルト値に設定されていない 2 番目の 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)
既存のリソースを更新する
次の例では、有効な resource_name と customer_id があることを前提として、API から取得した既存のキャンペーンを更新します。この方法では、updated_campaign は initial_campaign で取得したすべてのフィールド(resource_name を含む)を共有し、生成されたフィールド マスクは network_settings.target_search_network フィールドのみが変更されたことを API に伝えます。
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 に直接追加します。
詳細については、
空のメッセージ オブジェクトをフィールドとして設定するをご覧ください。