घर में मास्क लगाने की सेवा

Google Ads API में, फ़ील्ड मास्क का इस्तेमाल करके अपडेट किए जाते हैं. फ़ील्ड मास्क (google.protobuf.FieldMask) में, snake_case में मौजूद फ़ील्ड पाथ की सूची होती है. इस सूची में मौजूद फ़ील्ड पाथ को अपडेट करके बदला जा सकता है. फ़ील्ड मास्क में शामिल नहीं किए गए किसी भी फ़ील्ड को अनदेखा कर दिया जाता है. भले ही, उसे सर्वर पर भेजा गया हो.

FieldMasks यूटिलिटी

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

यहां कैंपेन अपडेट करने का एक उदाहरण दिया गया है:

// Creates a Campaign object with the proper resource name and any other
// changes.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.allSetFieldsOf utility to derive the update mask. This mask tells
// the Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

इसके बाद, उदाहरण के तौर पर कैंपेन में FieldMasks.allSetFieldsOf() को कॉल किया जाता है, ताकि सेट किए गए सभी फ़ील्ड की गिनती करने वाला फ़ील्ड मास्क अपने-आप जनरेट हो सके. वापस किए गए मास्क को सीधे अपडेट कॉल में पास किया जा सकता है.

अगर आपको किसी मौजूदा ऑब्जेक्ट के साथ काम करना है और कुछ फ़ील्ड अपडेट करने हैं, तो FieldMasks.compare() का इस्तेमाल इस तरह करें:

// Assumes existingCampaign was retrieved from a previous API call.

// Creates a new campaign based on the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
    existingCampaign.toBuilder()
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.compare utility to derive the update mask. This mask tells the
// Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaignToUpdate)
        .setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

शुरुआत से फ़ील्ड मास्क बनाने के लिए, FieldMask बिल्डर बनाएं और हर उस फ़ील्ड का snake_case नाम जोड़ें जिसमें आपको बदलाव करना है:

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

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

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

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

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

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

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

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

इस मामले में, FieldMasks के allSetFieldsOf() और compare() तरीकों का इस्तेमाल करने से, तय किया गया लक्ष्य हासिल नहीं होता.

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

चेतावनी: इस कोड से FieldMaskError.FIELD_HAS_SUBFIELDS गड़बड़ी होती है.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(MaximizeConversions.newBuilder().build())
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the update
// mask. The field mask includes 'maximize_conversions', which produces a
// FieldMaskError.FIELD_HAS_SUBFIELDS error.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that results in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields with
// subfields cannot be included directly in a field mask.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

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

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Creates a field mask from the campaign and adds the mutable subfield
// ('maximize_conversions.target_cpa_micros') on the MaximizeConversions
// bidding strategy to the field mask. Because this subfield is included in the
// field mask while excluded from the campaign object, the Google Ads API
// switches the campaign's bidding strategy oneof to MaximizeConversions with
// target_cpa_micros unset.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

फ़ील्ड में मौजूद कॉन्टेंट मिटाना

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

नीचे दिया गया कोड चलता है, लेकिन maximize_conversions.target_cpa_micros को उम्मीद के मुताबिक नहीं हटाया जाएगा:

चेतावनी: यह कोड, MaximizeConversions बिडिंग की रणनीति पर target_cpa_micros को नहीं हटाता.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0L.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpaMicros(0L).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the
// update mask.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that does not clear the field
// cleanly.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

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

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Constructs a field mask from the campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

अहम जानकारी: अगर आपको किसी फ़ील्ड को हटाना है, तो FieldMask में उस फ़ील्ड का पाथ जोड़ें. साथ ही, रिसॉर्स ऑब्जेक्ट पर फ़ील्ड को सेट न करें.