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

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

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

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

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

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

campaign_resource_name = client.path.campaign(customer_id, campaign_id)

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

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

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

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

mask = Google::Protobuf::FieldMask.new
mask.paths = ['status', 'name']

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

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

ऐसे मैसेज फ़ील्ड जिनके लिए कोई सबफ़ील्ड तय नहीं किया गया है

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

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

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

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

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

नीचे दिया गया कोड, एक फ़ील्ड मास्क जनरेट करता है. इसमें 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 results 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]
)

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask starts empty. You can modify
# other fields in this block, except the message field intended to have a
# blank subfield.
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 से ज़्यादा वैल्यू के साथ सेट किया गया है.

proto3 में, ज़रूरी स्केलर फ़ील्ड को उसकी डिफ़ॉल्ट वैल्यू (0) पर सेट करने और नए मैसेज इंस्टेंस पर उसे सेट न करने में कोई अंतर नहीं होता. इस वजह से, FieldMaskUtil, maximize_conversions.target_cpa_micros के बजाय फ़ील्ड मास्क में maximize_conversions जोड़ता है. इससे FieldMaskError.FIELD_HAS_SUBFIELDS गड़बड़ी होती है.

# 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 includes 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it results 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 fails because the field mask is invalid.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

# Create a campaign including the maximize conversions fields right away, since
# they are manually added 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 can add a block here with
# other changes that are automatically 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 succeeds because the correct field mask is specified.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

ध्यान दें कि अपने-आप तुलना करने का तरीका, Google Ads API के प्रोटोकॉल बफ़र में optional के तौर पर तय किए गए फ़ील्ड के लिए सही तरीके से काम करता है. ऐसा इसलिए है, क्योंकि target_cpa_micros, MaximizeConversions पर मौजूद optional फ़ील्ड नहीं है. इसलिए, इसे हटाने के लिए, update_mask.paths में पाथ को साफ़ तौर पर जोड़ना ज़रूरी है.