Pembaruan menggunakan mask kolom

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

Bantuan mask kolom

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

Jika None diteruskan sebagai parameter pertama, daftar mask kolom 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.

Memperbarui 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 mask kolom baru dengan membandingkannya dengan None, yang menghasilkan mask kolom 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)

Memperbarui resource yang ada

Contoh berikut mengupdate 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 mask kolom 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 menyetel pesan kosong

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