Cập nhật bằng cách sử dụng mặt nạ tại hiện trường

Trong API Google Ads, quá trình cập nhật được thực hiện bằng cách sử dụng mặt nạ trường. Danh sách mặt nạ trường tất cả các trường mà bạn dự định thay đổi trong bản cập nhật và mọi trường được chỉ định không có trong mặt nạ trường sẽ bị bỏ qua, ngay cả khi được gửi đến máy chủ.

Trình trợ giúp mặt nạ trường

Bạn nên tạo mặt nạ trường bằng cách sử dụng trình trợ giúp field_mask hàm có trong gói google.api_core. Phương thức này chấp nhận hai đối tượng protobuf và trả về một đối tượng mặt nạ trường có trường list chứa tất cả các trường khác nhau giữa hai đối tượng.

Nếu None được truyền dưới dạng tham số đầu tiên, thì danh sách mặt nạ trường sẽ chỉ chứa tất cả các trường trên đối tượng protobuf thứ hai không được đặt thành giá trị mặc định của chúng.

Sau khi tạo xong, đối tượng mặt nạ trường phải được sao chép vào thao tác đối tượng sẽ được gửi đến máy chủ:

Dưới đây là ví dụ về cách cập nhật chiến dịch:

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)

Trước tiên, chúng ta tạo một đối tượng CampaignOperation trống. Sau đó, chúng ta đặt truy xuất một trống đối tượng Chiến dịch khỏi đối tượng này. Sau đó, chúng ta cập nhật đối tượng chiến dịch đó và tạo một mặt nạ trường mới, so sánh mặt nạ trường đó với None. Thao tác này sẽ tạo một danh sách mặt nạ trường chỉ chứa trường network_settings.target_search_network đã thay đổi.

Dưới đây là ví dụ về việc cập nhật một chiến dịch hiện tại. Ở đây, chúng tôi giả định tập lệnh có đã được cung cấp tham số resource_name. Đây là tên tài nguyên hợp lệ cho chiến dịch và một customer_id hợp lệ:

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)

Với chiến lược này, updated_campaign sẽ chia sẻ tất cả các trường giống như initial_campaign được truy xuất từ API, cụ thể là tên tài nguyên. Mặt nạ trường được tạo sẽ cho API biết rằng chỉ cần thay đổi trường network_settings.target_search_network.