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

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 तरीके का इस्तेमाल किया गया है, ताकि अपडेट शामिल करने वाले ब्लॉक को शुरू किया जा सके. इस ब्लॉक के आखिर में, यूटिलिटी ब्लॉक के बाद कैंपेन की मौजूदा स्थिति की तुलना, ब्लॉक से पहले कैंपेन की शुरुआती स्थिति से करती है. साथ ही, बदले गए फ़ील्ड की गिनती करने वाली फ़ील्ड मास्क अपने-आप जनरेट करती है. mutate कॉल के लिए फ़ील्ड मास्क बनाते समय, उसे इस तरह ऑपरेशन में शामिल किया जा सकता है:

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 में पाथ को साफ़ तौर पर जोड़ना ज़रूरी है.