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

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 गड़बड़ी दिखाता है.

// 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 को उम्मीद के मुताबिक साफ़ नहीं किया जाएगा:

// 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 फ़ील्ड को सही तरीके से हटाने का तरीका बताया गया है.

// 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();