फ़ील्ड मास्क का इस्तेमाल करके अपडेट करना

Google Ads API में, फ़ील्ड मास्क का इस्तेमाल करके अपडेट किए जाते हैं. फ़ील्ड मास्क में वे सभी फ़ील्ड शामिल होते हैं जिन्हें आपको अपडेट करना है. साथ ही, इसमें वे फ़ील्ड भी शामिल होते हैं जिन्हें फ़ील्ड मास्क में शामिल नहीं किया गया है. ऐसे फ़ील्ड को नज़रअंदाज़ कर दिया जाता है, भले ही उन्हें सर्वर पर भेजा गया हो.

फ़ील्ड मास्क हेल्पर

फ़ील्ड मास्क जनरेट करने का सुझाव दिया गया तरीका यह है कि google.api_core पैकेज में शामिल field_mask हेल्पर फ़ंक्शन का इस्तेमाल किया जाए. यह दो प्रोटोबफ़ ऑब्जेक्ट स्वीकार करता है और फ़ील्ड मास्क ऑब्जेक्ट दिखाता है. इसमें paths लिस्ट होती है. इस लिस्ट में वे सभी फ़ील्ड होते हैं जो दोनों ऑब्जेक्ट में अलग-अलग होते हैं.

अगर None को पहले पैरामीटर के तौर पर पास किया जाता है, तो फ़ील्ड मास्क की सूची में, दूसरे प्रोटोबफ़ ऑब्जेक्ट के वे सभी फ़ील्ड शामिल होते हैं जिनकी वैल्यू डिफ़ॉल्ट वैल्यू पर सेट नहीं होती.

फ़ील्ड मास्क ऑब्जेक्ट बनाने के बाद, उसे उस ऑपरेशन ऑब्जेक्ट पर कॉपी किया जाना चाहिए जिसे सर्वर को भेजा जाएगा.

किसी नए लोकल ऑब्जेक्ट से अपडेट करना

इस उदाहरण में, एक खाली CampaignOperation ऑब्जेक्ट बनाया गया है. साथ ही, इसके update फ़ील्ड से एक खाली Campaign ऑब्जेक्ट वापस पाया गया है. इसके बाद, उस कैंपेन ऑब्जेक्ट में बदलाव करें और 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 में जोड़ें. ज़्यादा जानकारी के लिए, खाली मैसेज ऑब्जेक्ट को फ़ील्ड के तौर पर सेट करना लेख पढ़ें.