মাঠের মুখোশ

গুগল অ্যাডস এপিআই-তে, একটি ফিল্ড মাস্ক ব্যবহার করে আপডেট করা হয়। ফিল্ড মাস্ক ( google.protobuf.FieldMask )-এ snake_case এ থাকা সেইসব ফিল্ড পাথের একটি তালিকা থাকে, যেগুলো আপনি আপডেটের মাধ্যমে পরিবর্তন করতে চান। ফিল্ড মাস্কে নেই এমন কোনো নির্দিষ্ট ফিল্ড সার্ভারে পাঠানো হলেও তা উপেক্ষা করা হয়।

ফিল্ডমাস্ক ইউটিলিটি

জাভা ক্লায়েন্ট লাইব্রেরিতে ফিল্ড মাস্ক তৈরি করার প্রস্তাবিত উপায় হলো বিল্ট-ইন 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 field 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 এ স্পষ্টভাবে সেই ফিল্ডের পাথটি যোগ করুন এবং রিসোর্স অবজেক্টে ফিল্ডটিকে অনির্ধারিত রাখুন।