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

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 फ़ील्ड को अपडेट करना है जिसे सब-फ़ील्ड के तौर पर तय किया गया है और उस मैसेज पर किसी भी सब-फ़ील्ड को साफ़ तौर पर सेट नहीं किया गया है, तो आपको FieldMask में हर उस बदले जा सकने वाले MESSAGE सब-फ़ील्ड को मैन्युअल तरीके से जोड़ना होगा. यह उसी तरह है जैसे पहले उदाहरण में, फ़ील्ड मास्क को शुरू से बनाया गया था.

एक सामान्य उदाहरण, बिडिंग की नई रणनीति में किसी भी फ़ील्ड को सेट किए बिना, कैंपेन की बिडिंग की रणनीति को अपडेट करना है. नीचे दिए गए उदाहरण में, बिडिंग की रणनीति पर कोई भी सब-फ़ील्ड सेट किए बिना, 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 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 फ़ील्ड को खाली करने के लिए बिडिंग की रणनीति को अपडेट नहीं करता.

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