Pembaruan menggunakan mask kolom

Di Google Ads API, pembaruan dilakukan menggunakan mask kolom. Masker kolom mencantumkan semua kolom yang ingin Anda ubah dengan update, dan kolom tertentu yang tidak ada dalam masker kolom akan diabaikan, meskipun dikirim ke server.

Helper mask kolom

Cara yang direkomendasikan untuk membuat mask kolom adalah menggunakan fungsi bantuan field_mask yang disertakan dalam paket google.api_core. Metode ini menerima dua objek protobuf dan menampilkan objek field mask dengan daftar paths yang berisi semua kolom yang berbeda di antara kedua objek tersebut.

Jika None diteruskan sebagai parameter pertama, daftar field mask akan berisi semua kolom pada objek protobuf kedua yang tidak ditetapkan ke nilai defaultnya.

Setelah dibuat, objek mask kolom harus disalin ke objek operasi yang akan dikirim ke server.

Mengupdate dari objek lokal baru

Dalam contoh berikut, Anda membuat objek CampaignOperation kosong dan mengambil objek Campaign kosong dari kolom update-nya. Kemudian, Anda mengubah objek kampanye tersebut dan membuat field mask baru dengan membandingkannya dengan None, yang menghasilkan field mask yang berisi kolom network_settings.target_search_network yang diubah:

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)

Mengupdate resource yang ada

Contoh berikut memperbarui kampanye yang ada yang diambil dari API, dengan asumsi resource_name dan customer_id yang valid. Dengan strategi ini, updated_campaign membagikan semua kolom yang diambil di initial_campaign (termasuk resource_name-nya), dan field mask yang dihasilkan memberi tahu API bahwa hanya kolom network_settings.target_search_network yang berubah:

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)

Menghapus kolom atau menetapkan pesan kosong

Saat membandingkan dengan None, helper field_mask mengabaikan kolom yang ditetapkan ke nilai kosong atau default. Untuk menghapus kolom secara eksplisit atau menetapkan kolom pesan kosong, tambahkan jalur kolom langsung ke campaign_operation.update_mask.paths. Untuk mengetahui detail selengkapnya, lihat Menetapkan objek pesan kosong sebagai kolom.