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

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

FieldMaskUtil

हमारा सुझाव है कि फ़ील्ड मास्क जनरेट करने के लिए, पहले से मौजूद फ़ील्ड मास्क की सुविधा का इस्तेमाल करें. इससे बहुत सारी खास जानकारी छिप जाती है. साथ ही, फ़ील्ड में किए गए बदलावों की निगरानी करके, फ़ील्ड मास्क अपने-आप जनरेट किए जा सकते हैं.

किसी कैंपेन को अपडेट करने के लिए, फ़ील्ड मास्क जनरेट करने का तरीका यहां बताया गया है:

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

कोड सबसे पहले एक खाली कैंपेन ऑब्जेक्ट बनाता है, फिर अपडेट किए जा रहे कैंपेन के एपीआई को जानकारी देने के लिए अपना संसाधन नाम सेट करता है.

इस उदाहरण में, अपडेट को शामिल करने वाला ब्लॉक शुरू करने के लिए, कैंपेन में client.field_mask.with तरीके का इस्तेमाल किया जाता है. इस ब्लॉक के आखिर में, यूटिलिटी ब्लॉक के बाद कैंपेन की मौजूदा स्थिति की तुलना, ब्लॉक से पहले कैंपेन की शुरुआती स्थिति से करती है और अपने-आप एक फ़ील्ड मास्क बनाती है, जिसमें बदले गए फ़ील्ड शामिल होते हैं. उस फ़ील्ड मास्क को बदलाव कॉल के लिए बनाते समय, नीचे बताए गए तरीके से लागू किया जा सकता है:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

इस तरीके का सुझाव तब दिया जाता है, जब कोई मुश्किल काम किया जा रहा हो और आपको हर चरण पर बेहतर कंट्रोल चाहिए. हालांकि, ज़्यादातर मामलों में ज़्यादा आसान Ruby लाइब्रेरी सुविधा का इस्तेमाल किया जा सकता है:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

यह तरीका अपने-आप एक नया खाली कैंपेन रिसॉर्स बनाता है. साथ ही, ब्लॉक में किए गए बदलावों के आधार पर फ़ील्ड मास्क बनाता है, अपडेट करने की कार्रवाई बनाता है, और पहले से भरे update और update_mask की मदद से, आखिरी कार्रवाई को दिखाता है. कैंपेन की शुरुआती स्थिति जानने के लिए, किसी कैंपेन को campaign तरीके में भी पास किया जा सकता है. यह पैटर्न, अपडेट की कार्रवाई को सपोर्ट करने वाले सभी संसाधनों के लिए काम करता है.

मैन्युअल तरीके से मास्क बनाना

लाइब्रेरी सुविधाओं का इस्तेमाल किए बिना, शुरुआत से फ़ील्ड मास्क बनाने के लिए, सबसे पहले Google::Protobuf::FieldMask बनाना होगा. इसके बाद, उन सभी फ़ील्ड के नामों से एक कैटगरी बनानी होगी जिनमें आपको बदलाव करना है. इसके बाद, अरे को फ़ील्ड मास्क के path फ़ील्ड में असाइन करें.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

मैसेज के फ़ील्ड और उनके सबफ़ील्ड अपडेट किए जा रहे हैं

MESSAGE फ़ील्ड में सबफ़ील्ड हो सकते हैं (जैसे कि MaximizeConversions, जिसमें तीन हैं: target_cpa_micros, cpc_bid_ceiling_micros, और cpc_bid_floor_micros) या इनमें कोई भी नहीं हो सकता (जैसे कि ManualCpm).

बिना तय सबफ़ील्ड वाले मैसेज फ़ील्ड

ऐसे MESSAGE फ़ील्ड को अपडेट करते समय जिसे किसी भी सबफ़ील्ड के साथ तय नहीं किया गया है, फ़ील्ड मास्क जनरेट करने के लिएFieldMaskUtil का इस्तेमाल करें. इसके बारे में पहले बताया गया है.

तय किए गए सबफ़ील्ड वाले मैसेज फ़ील्ड

मैसेज में किसी भी सबफ़ील्ड को साफ़ तौर पर सेट किए बिना, सबफ़ील्ड के साथ तय किए गए MESSAGE फ़ील्ड को अपडेट करते समय, आपको म्यूटेबल MESSAGE सबफ़ील्ड को FieldMask में मैन्युअल तरीके से जोड़ना होगा. यह ठीक वैसा ही है जैसा शुरुआती उदाहरण में दिखाया गया था.

इसका एक सामान्य उदाहरण है, बोली लगाने की नई रणनीति के लिए किसी भी फ़ील्ड को सेट किए बिना कैंपेन की बोली लगाने की रणनीति को अपडेट करना. यहां दिए गए उदाहरण में, बिडिंग की रणनीति के किसी भी सबफ़ील्ड को सेट किए बिना, MaximizeConversions बिडिंग की रणनीति का इस्तेमाल करने के लिए, कैंपेन को अपडेट करने का तरीका बताया गया है.

इस उदाहरण के लिए, फ़ील्ड MaskUtil में पहले से मौजूद तुलना का इस्तेमाल करने से, तय किया गया लक्ष्य हासिल नहीं होता.

यह कोड एक फ़ील्ड मास्क जनरेट करता है, जिसमें maximize_conversions शामिल है. हालांकि, Google Ads API इस तरह के व्यवहार की अनुमति नहीं देता, ताकि फ़ील्ड को गलती से मिटाया जा सके और FieldMaskError.FIELD_HAS_SUBFIELDS गड़बड़ी दिख सके.

चेतावनी: यह कोड गड़बड़ी पैदा करता है.

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

इस कोड में बताया गया है कि किसी भी सबफ़ील्ड को सेट किए बिना, MaximizeConversions बिडिंग की रणनीति का इस्तेमाल करने के लिए, कैंपेन को सही तरीके से कैसे अपडेट किया जाए.

सफल: नीचे दिया गया कोड, कैंपेन की बिडिंग की रणनीति को अपडेट करता है.

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

फ़ील्ड खाली करना

कुछ फ़ील्ड को साफ़ तौर पर मिटाया जा सकता है. पिछले उदाहरण की तरह ही, आपको इन फ़ील्ड को साफ़ तौर पर फ़ील्ड मास्क में जोड़ना होगा. उदाहरण के लिए, मान लें कि आपके पास एक ऐसा कैंपेन है जिसमें MaximizeConversions बिडिंग की रणनीति का इस्तेमाल किया गया है और target_cpa_micros फ़ील्ड को 0 से ज़्यादा वैल्यू के साथ सेट किया गया है.

नीचे दिया गया कोड चलता है. हालांकि, maximize_conversions.target_cpa_micros को फ़ील्ड मास्क में नहीं जोड़ा जाएगा और इसलिए target_cpa_micros फ़ील्ड में कोई बदलाव नहीं किया जाएगा:

चेतावनी: इस कोड का इस्तेमाल करने पर कोई गड़बड़ी हो सकती है.

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

इस कोड में, बिडिंग की MaximizeConversions रणनीति के तहत, target_cpa_micros फ़ील्ड को सही तरीके से खाली करने का तरीका बताया गया है.

हो गया: यह कोड, target_cpa_micros को मिटा देता है.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

ध्यान रखें कि "गलत" कोड, Google Ads API protocol buffers में optional के तौर पर बताए गए फ़ील्ड के लिए सही तरीके से काम करता है. हालांकि, target_cpa_micros कोई optional फ़ील्ड नहीं है, इसलिए "गलत" कोड target_cpa फ़ील्ड को हटाने के लिए, बिडिंग की रणनीति को अपडेट नहीं करता.

अहम जानकारी: अगर आपको किसी फ़ील्ड को खाली करना है, तो सबसे सुरक्षित तरीका यह है कि उस फ़ील्ड को फ़ील्ड मास्क में साफ़ तौर पर जोड़ें.