মিউটেট

গুগল অ্যাডস স্ক্রিপ্টগুলো গুগল অ্যাডস এপিআই- তে উপলব্ধ জেনেরিক মিউটেট সমর্থন করে। GoogleAdsService.mutate থেকে যে সমস্ত অপারেশন করা যায়, তার বেশিরভাগই গুগল অ্যাডস স্ক্রিপ্টেও করা সম্ভব, যার মধ্যে ক্যাম্পেইন তৈরি এবং পরিচালনাও অন্তর্ভুক্ত।

যেহেতু এই ফিচারটি গুগল অ্যাডস এপিআই-এর একটি বিশাল অংশে অ্যাক্সেস দেয়, তাই এটি ব্যবহার করার জন্য গুগল অ্যাডস এপিআই-এর প্রচলিত নিয়মকানুন সম্পর্কে প্রাথমিক ধারণা থাকা জরুরি। ডেভেলপার টোকেন এবং অথরাইজেশনের মতো অনেক বিষয় এড়িয়ে যাওয়া যায়, কারণ সেগুলো গুগল অ্যাডস স্ক্রিপ্ট আপনার জন্য পরিচালনা করে থাকে, কিন্তু আপনাকে একটি বৈধ মিউটেট রিকোয়েস্ট তৈরি করতেই হবে।

এই নির্দেশিকাটি নিয়ে এগিয়ে যাওয়ার আগে গুগল অ্যাডস এপিআই রেস্ট ইন্টারফেসের উপর কিছু প্রাথমিক রিসোর্স নিচে দেওয়া হলো, যেগুলোর সাথে আপনার পরিচিত থাকা উচিত:

• REST ইন্টারফেস ডিজাইন
• সম্পদের নাম
• JSON ম্যাপিং
• মিউটেট

মৌলিক উদাহরণ

কার্যকারিতাটি দেখানোর জন্য, এই সাধারণ উদাহরণটি বিবেচনা করুন যা একটি ক্যাম্পেইন বাজেট তৈরি করে:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

AdsApp.mutate কল করলে একটি JSON অবজেক্ট গৃহীত হয়, যা একটিমাত্র MutateOperation উপস্থাপন করে। এই অবজেক্টের মধ্যে, আপনি কোন ধরনের অপারেশন করছেন তা নির্দিষ্ট করে দেন—এই ক্ষেত্রে, একটি campaignBudgetOperation । এরপর আপনি create , remove , অথবা update এবং updateMask উভয়ই নির্দিষ্ট করেন। create এবং update ভেতরের নির্দিষ্ট ফিল্ডগুলো নির্ভর করে আপনি কোন ধরনের রিসোর্সের উপর কাজ করছেন তার উপর।

একটি অপারেশন তৈরি করুন

একটি বৈধ অপারেশন তৈরি করার জন্য আপনি কয়েকটি কৌশল ব্যবহার করতে পারেন। ক্যাম্পেইন বাজেটের উদাহরণটি ধরে রাখলে, আপনি ক্যাম্পেইন বাজেটের REST রেফারেন্স ডকুমেন্টেশন দেখে এর সমস্ত বৈধ ফিল্ডের একটি তালিকা পেতে পারেন এবং তারপর উপযুক্ত ফিল্ডগুলো পূরণ করতে পারেন, অথবা একটি উপযুক্ত অবজেক্ট তৈরি করার জন্য আপনার স্ক্রিপ্টে কাস্টম জাভাস্ক্রিপ্ট কোড লিখতে পারেন।

বিকল্পভাবে, আপনি ক্যাম্পেইন বাজেটের জন্য "Try this" ফিচারটি ব্যবহার করে ডাইনামিকভাবে একটি অপারেশন তৈরি করার চেষ্টা করতে পারেন, যা আপনাকে আপনার পছন্দের ফিল্ডগুলো বেছে নিয়ে ডাইনামিকভাবে একটি রিকোয়েস্ট বডি তৈরি করার সুযোগ দেয়। এরপর আপনি তৈরি হওয়া ফলাফল থেকে অপারেশনের বিষয়বস্তু বের করে নিতে পারেন এবং অপারেশনের ধরন নির্দিষ্ট করার পর তা আপনার mutate কলে যোগ করতে পারেন।

অপারেশনের প্রকারভেদ

তৈরি করুন

আপনার অপারেশনে create নির্দিষ্ট করুন এবং যে রিসোর্সটি তৈরি করতে চান তার একটি অবজেক্ট রিপ্রেজেন্টেশন পাস করুন।

create অপারেশনের একটি উদাহরণের জন্য পূর্বে প্রদত্ত কোড স্নিপেটটি দেখুন।

অপসারণ করুন

আপনার অপারেশনে remove নির্দিষ্ট করুন এবং যে রিসোর্সটি সরাতে চান তার রিসোর্স নামটি পাস করুন, উদাহরণস্বরূপ:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

যদি আপনি কোনো এনটিটির রিসোর্স নেম না জানেন, তাহলে একটি Adsapp.search রিকোয়েস্ট ব্যবহার করে তা ফেচ করতে পারেন।

আপডেট

আপনার অপারেশনে update নির্দিষ্ট করুন এবং নির্দিষ্ট রিসোর্স নামটি সহ একটি অবজেক্ট পাস করুন, যাতে সিস্টেম নির্ধারণ করতে পারে যে আপনি কোন অবজেক্টটি আপডেট করতে চান। এছাড়াও, যে ফিল্ডগুলোর মান আপনি আপডেট করতে চান, সেগুলো পূরণ করুন এবং একটি updateMask নির্দিষ্ট করুন, যা নির্দেশ করবে যে এই অনুরোধে আপনি ঠিক কোন ফিল্ডগুলো পরিবর্তন করতে চান। আপডেট মাস্কে রিসোর্স নামটি অন্তর্ভুক্ত করবেন না।

update অপারেশনের একটি উদাহরণ:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

ফলাফল পরিচালনা করুন

অপারেশনের ধরন নির্বিশেষে, রিটার্ন ভ্যালুটি হলো একটি MutateResult । মিউটেট করার পর রিসোর্সটির বর্তমান অবস্থা জানতে এবং অপারেশনটি সফল হয়েছে কিনা বা কোনো ত্রুটি ঘটেছে কিনা তা পরীক্ষা করতে, আপনি রিটার্ন করা রিসোর্স নামটি ব্যবহার করতে পারেন।

ফলাফল যাচাই করা এবং লগ-এ কিছু তথ্য প্রিন্ট করার একটি সাধারণ কার্যপ্রবাহের উদাহরণ নিচে দেওয়া হলো:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

একাধিক অপারেশন

Google Ads স্ক্রিপ্ট AdsApp.mutateAll মেথড ব্যবহার করে একটিমাত্র রিকোয়েস্টে একাধিক অপারেশন পরিবর্তন করাও সমর্থন করে। আপনি একটিমাত্র রিকোয়েস্টে একে অপরের উপর নির্ভরশীল এনটিটি, যেমন একটি সম্পূর্ণ ক্যাম্পেইন হায়ারার্কি, পরিবর্তন করতে পারেন। আপনি চাইলে অপারেশনের সম্পূর্ণ সেটটিকে অ্যাটমিক করতে পারেন, ফলে কোনো একটি ব্যর্থ হলে কোনোটিই সম্পাদিত হবে না।

রিটার্ন ভ্যালুটি হলো MutateResult অবজেক্টের একটি অ্যারে, যেখানে আপনার দেওয়া প্রতিটি অপারেশনের জন্য একটি করে অবজেক্ট থাকে এবং সেগুলো প্রাথমিক অপারেশনগুলোর ক্রমেই সাজানো থাকে।

এই ফিচারটি গুগল অ্যাডস এপিআই (Google Ads API) ফিচারের মতোই কাজ করে, তাই টেম্প আইডি (temp ID) এবং অন্যান্য বিবেচ্য বিষয়গুলির সম্পূর্ণ ব্যাখ্যার জন্য গুগল অ্যাডস এপিআই বেস্ট প্র্যাকটিসেস গাইড (Google Ads API best practices guide) দেখুন; লক্ষ্য করুন যে গাইডটিতে ফিল্ডের নাম বোঝাতে snake_case ব্যবহার করা হয়েছে, যেখানে গুগল অ্যাডস স্ক্রিপ্টস ডকুমেন্টেশনে lowerCamelCase ব্যবহার করা হয়েছে। গুগল অ্যাডস স্ক্রিপ্টসে এই উভয় কেসই গৃহীত হয়, তাই আপনি সরাসরি সেই গাইড থেকে কোড কপি করতে পারেন।

একটি অনুরোধে একাধিক অপারেশন সম্পন্ন করতে, আপনার সমস্ত অপারেশন একটি অ্যারেতে সংগ্রহ করুন এবং তারপরে AdsApp.mutateAll কল করুন। mutateAll কলটি প্রথম আর্গুমেন্ট হিসেবে অপারেশনের অ্যারে এবং ঐচ্ছিক দ্বিতীয় আর্গুমেন্ট হিসেবে অপশন গ্রহণ করে, যার মধ্যে রয়েছে:

• apiVersion : স্ক্রিপ্টের ডিফল্ট সংস্করণ ছাড়া অন্য কোনো সংস্করণ ব্যবহার করতে চাইলে, আপনি V24 মতো একটি কাস্টম এপিআই সংস্করণ নির্দিষ্ট করতে পারেন। আপনি সেই সময়ে সর্বজনীনভাবে উপলব্ধ যেকোনো সংস্করণ ব্যবহার করতে পারেন।
• partialFailure : এই ফিল্ডটির ডিফল্ট মান হলো true । যদি এটি true সেট করা হয়, তাহলে বৈধ অপারেশনগুলো সম্পন্ন করা হয় এবং ব্যর্থ অপারেশনগুলো এরর রিটার্ন করে। যদি এটি false সেট করা হয়, তাহলে কোনো অপারেশন ব্যর্থ হলে কোনো অপারেশনই সম্পন্ন করা হয় না, যার ফলে এই অপারেশন সেটটি কার্যকরভাবে অ্যাটমিক হয়ে যায়।

এখানে একাধিক অপারেশনের একটি উদাহরণ দেওয়া হলো, যা একটি অ্যাটমিক রিকোয়েস্টের মাধ্যমে ক্যাম্পেইন বাজেট, ক্যাম্পেইন এবং অ্যাড গ্রুপ তৈরি করে।

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});