การอัปเดตโดยใช้ฟิลด์มาสก์

ใน Google Ads API การอัปเดตจะทำโดยใช้มาสก์ฟิลด์ ฟิลด์มาสก์จะแสดงรายการฟิลด์ทั้งหมดที่คุณต้องการเปลี่ยนแปลงด้วยการอัปเดต และระบบจะละเว้นฟิลด์ที่ระบุซึ่งไม่ได้อยู่ในฟิลด์มาสก์ แม้ว่าจะส่งไปยังเซิร์ฟเวอร์ก็ตาม

ตัวช่วยฟิลด์มาสก์

วิธีที่แนะนำในการสร้างมาสก์ของฟิลด์คือการใช้ฟังก์ชันตัวช่วย field_mask ที่รวมอยู่ในแพ็กเกจ google.api_core โดยจะรับออบเจ็กต์ Protobuf 2 รายการและแสดงผลออบเจ็กต์มาสก์ของฟิลด์ที่มีpathsซึ่งมีฟิลด์ทั้งหมดที่แตกต่างกันระหว่างออบเจ็กต์ทั้ง 2 รายการ

หากส่ง None เป็นพารามิเตอร์แรก รายการมาสก์ฟิลด์จะมี ฟิลด์ทั้งหมดในออบเจ็กต์ Protobuf ที่ 2 ซึ่งไม่ได้ตั้งค่าเป็น ค่าเริ่มต้น

เมื่อสร้างแล้ว ควรก๊อปปี้ออบเจ็กต์ฟิลด์มาสก์ไปยังออบเจ็กต์การดำเนินการ ที่จะส่งไปยังเซิร์ฟเวอร์

อัปเดตจากออบเจ็กต์ในเครื่องใหม่

ในตัวอย่างต่อไปนี้ คุณจะสร้างออบเจ็กต์ CampaignOperation ที่ว่างเปล่าและเรียกออบเจ็กต์ Campaign ที่ว่างเปล่าจากฟิลด์ update จากนั้นคุณจะแก้ไขออบเจ็กต์แคมเปญนั้นและสร้างมาสก์ฟิลด์ใหม่ได้โดยเปรียบเทียบกับ 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)

อัปเดตทรัพยากรที่มีอยู่

ตัวอย่างต่อไปนี้จะอัปเดตแคมเปญที่มีอยู่ซึ่งดึงมาจาก API โดยสมมติว่ามี resource_name และ customer_id ที่ถูกต้อง กลยุทธ์นี้จะupdated_campaignแชร์ฟิลด์ทั้งหมดที่ดึงข้อมูลใน initial_campaign (รวมถึง resource_name) และฟิลด์มาสก์ที่สร้างขึ้นจะบอก API ว่า มีการเปลี่ยนแปลงเฉพาะฟิลด์ 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()

# 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 โดยตรง ดูรายละเอียดเพิ่มเติมได้ที่หัวข้อ ตั้งค่าออบเจ็กต์ข้อความว่างเป็นฟิลด์