التعديلات باستخدام أقنعة الحقول

في Google Ads API، يتم إجراء التعديلات باستخدام قناع حقل. يسرد قناع الحقل جميع الحقول التي تريد تغييرها من خلال التعديل، ويتم تجاهل أي حقول محددة غير مضمّنة في قناع الحقل، حتى إذا تم إرسالها إلى الخادم.

أداة مساعدة في إنشاء قناع الحقل

الطريقة المقترَحة لإنشاء أقنعة الحقول هي استخدام الدالة المساعدة field_mask المضمّنة في حزمة google.api_core. تقبل هذه الدالة عنصرَين من نوع protobuf وتعرض عنصرًا من نوع field mask يتضمّن قائمة paths تحتوي على جميع الحقول المختلفة بين العنصرَين.

إذا تم تمرير None كالمَعلمة الأولى، ستتضمّن قائمة قناع الحقل جميع الحقول في عنصر protobuf الثاني التي لم يتم ضبطها على قيمتها التلقائية.

بعد إنشاء عنصر قناع الحقل، يجب نسخه إلى عنصر العملية الذي سيتم إرساله إلى الخادم.

التعديل من عنصر محلي جديد

في المثال التالي، يتم إنشاء كائن 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)

تعديل مرجع حالي

يعدّل المثال التالي حملة حالية تم استردادها من واجهة برمجة التطبيقات، بافتراض توفّر resource_name وcustomer_id صالحَين. باستخدام هذه الاستراتيجية، تشارك updated_campaign جميع الحقول التي تم استردادها في initial_campaign (بما في ذلك resource_name)، ويُعلم قناع الحقل الذي تم إنشاؤه واجهة برمجة التطبيقات بأنّ الحقل 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. لمزيد من التفاصيل، اطّلِع على ضبط عناصر الرسائل الفارغة كحقول.