Ad Manager SOAP API থেকে মাইগ্রেট করুন

অ্যাড ম্যানেজার SOAP API হলো আপনার অ্যাড ম্যানেজার ডেটা পড়া ও লেখা এবং রিপোর্ট চালানোর জন্য ব্যবহৃত একটি লিগ্যাসি API। আপনি যদি মাইগ্রেট করতে পারেন, তবে আমরা অ্যাড ম্যানেজার API (বিটা) ব্যবহার করার পরামর্শ দিই। তবে, অ্যাড ম্যানেজার SOAP API-এর সংস্করণগুলো তাদের স্বাভাবিক জীবনচক্র পর্যন্ত সমর্থিত থাকে। আরও তথ্যের জন্য, অ্যাড ম্যানেজার SOAP API ডেপ্রিকেশন শিডিউল দেখুন।

নিম্নলিখিত নির্দেশিকায় অ্যাড ম্যানেজার SOAP API এবং অ্যাড ম্যানেজার API (বিটা)-এর মধ্যেকার পার্থক্যগুলো তুলে ধরা হয়েছে।

শিখুন

স্ট্যান্ডার্ড অ্যাড ম্যানেজার SOAP API সার্ভিস মেথডগুলোর সমতুল্য ধারণা অ্যাড ম্যানেজার API-তে রয়েছে। অ্যাড ম্যানেজার API-তে একক এনটিটি পড়ার জন্যও মেথড রয়েছে। নিচের সারণিতে Order মেথডগুলোর একটি উদাহরণ ম্যাপিং দেখানো হলো:

SOAP পদ্ধতি REST পদ্ধতি
getOrdersByStatement networks.orders.get
networks.orders.list

প্রমাণীকরণ করুন

অ্যাড ম্যানেজার এপিআই (বিটা)-এর সাথে প্রমাণীকরণের জন্য, আপনি আপনার বিদ্যমান অ্যাড ম্যানেজার SOAP এপিআই ক্রেডেনশিয়াল ব্যবহার করতে পারেন অথবা নতুন ক্রেডেনশিয়াল তৈরি করতে পারেন। উভয় ক্ষেত্রেই, আপনাকে প্রথমে আপনার গুগল ক্লাউড প্রজেক্টে অ্যাড ম্যানেজার এপিআই সক্রিয় করতে হবে। আরও বিস্তারিত জানতে, প্রমাণীকরণ (Authentication) দেখুন।

আপনি যদি কোনো ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন, তাহলে আপনার সার্ভিস অ্যাকাউন্ট কী ফাইলের পাথে GOOGLE_APPLICATION_CREDENTIALS এনভায়রনমেন্ট ভেরিয়েবলটি সেট করে অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়ালস সেট আপ করুন। আরও বিস্তারিত জানতে, ‘অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়ালস কীভাবে কাজ করে’ দেখুন।

আপনি যদি ইনস্টল করা অ্যাপ্লিকেশনের ক্রেডেনশিয়াল ব্যবহার করেন, তাহলে নিম্নলিখিত ফরম্যাটে একটি JSON ফাইল তৈরি করুন এবং এনভায়রনমেন্ট ভেরিয়েবলটিকে তার পাথে সেট করুন:

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

নিম্নলিখিত মানগুলি প্রতিস্থাপন করুন:

  • CLIENT_ID : আপনার নতুন বা বিদ্যমান ক্লায়েন্ট আইডি।
  • CLIENT_SECRET : আপনার নতুন বা বিদ্যমান ক্লায়েন্টের গোপনীয় তথ্য।

  • REFRESH_TOKEN : আপনার নতুন বা বিদ্যমান রিফ্রেশ টোকেন।

লিনাক্স বা ম্যাকওএস 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

উইন্ডোজ 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

ফিল্টারের পার্থক্য বুঝুন

অ্যাড ম্যানেজার এপিআই (বিটা)-এর কোয়েরি ল্যাঙ্গুয়েজ পাবলিশার কোয়েরি ল্যাঙ্গুয়েজ (পি কিউ এল)-এর সকল বৈশিষ্ট্য সমর্থন করে, কিন্তু এর সিনট্যাক্সে উল্লেখযোগ্য পার্থক্য রয়েছে।

Order অবজেক্ট তালিকাভুক্ত করার এই উদাহরণটি প্রধান পরিবর্তনগুলো তুলে ধরে, যেমন বাইন্ড ভেরিয়েবল ও কেস সেনসিটিভ অপারেটর অপসারণ, এবং ORDER BY ও LIMIT ক্লজকে পৃথক ফিল্ড দ্বারা প্রতিস্থাপন:

বিজ্ঞাপন ব্যবস্থাপক SOAP API 

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

বিজ্ঞাপন ব্যবস্থাপক এপিআই (বিটা)

JSON ফরম্যাট

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

URL এনকোড করা

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

অ্যাড ম্যানেজার এপিআই (বিটা) সমস্ত পিকিউএল (PQL) সক্ষমতা সমর্থন করে, তবে অ্যাড ম্যানেজার সোপ এপিআই (SOAP API) থেকে এর সিনট্যাক্সে নিম্নলিখিত পার্থক্য রয়েছে:

  • অ্যাড ম্যানেজার এপিআই (বিটা)-তে AND এবং OR অপারেটরগুলো কেস-সেনসিটিভ । ছোট হাতের ' and ' or কে সাধারণ আক্ষরিক সার্চ স্ট্রিং হিসেবে গণ্য করা হয়, যা অ্যাড ম্যানেজার এপিআই (বিটা)-এর একটি ফিচার এবং এর মাধ্যমে বিভিন্ন ফিল্ডের মধ্যে সার্চ করা যায়।

    বড় হাতের অক্ষর ব্যবহার করুন

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    ছোট হাতের অক্ষরকে আক্ষরিক হিসাবে গণ্য করা হয়

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false

  • * অক্ষরটি স্ট্রিং মেলানোর জন্য একটি ওয়াইল্ডকার্ড। অ্যাড ম্যানেজার এপিআই (বিটা) like অপারেটরটি সমর্থন করে না।

    বিজ্ঞাপন ব্যবস্থাপক SOAP API PQL

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    বিজ্ঞাপন ব্যবস্থাপক এপিআই (বিটা) 

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • তুলনা অপারেটরের বাম দিকে ফিল্ডের নাম অবশ্যই থাকতে হবে:

    বৈধ ফিল্টার 

    updateTime > "2024-01-01T00:00:00Z"

    অবৈধ ফিল্টার 

    "2024-01-01T00:00:00Z" < updateTime

  • অ্যাড ম্যানেজার এপিআই (বিটা) বাইন্ড ভ্যারিয়েবল সমর্থন করে না। সমস্ত ভ্যালু অবশ্যই ইনলাইন করতে হবে।

  • যেসব স্ট্রিং লিটারেলের মধ্যে স্পেস থাকে, সেগুলোকে অবশ্যই ডাবল কোটেশনের মধ্যে রাখতে হবে, যেমন, "Foo bar" । স্ট্রিং লিটারেলকে সিঙ্গেল কোটেশন দিয়ে মোড়ানো যায় না।

অর্ডার বাই ক্লজগুলো সরিয়ে ফেলুন

Specifying a sorting order is optional in the Ad Manager API (Beta). If you want to specify a sorting order for your result set, remove the PQL ORDER BY clause and set the orderBy field instead: 

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

অফসেট থেকে পেজিনেশন টোকেনে স্থানান্তরিত করুন

অ্যাড ম্যানেজার এপিআই (বিটা) বড় আকারের ফলাফল সেটের মধ্যে পেজিং করার জন্য LIMIT এবং OFFSET ক্লজের পরিবর্তে পেজিনেশন টোকেন ব্যবহার করে।

অ্যাড ম্যানেজার এপিআই (বিটা) পেজ সাইজ নিয়ন্ত্রণ করতে একটি pageSize প্যারামিটার ব্যবহার করে। অ্যাড ম্যানেজার SOAP এপিআই-এর LIMIT ক্লজের মতো নয়, পেজ সাইজ উল্লেখ না করলে সম্পূর্ণ রেজাল্ট সেট ফেরত আসে না । এর পরিবর্তে, list মেথডটি ডিফল্ট হিসেবে 50 পেজ সাইজ ব্যবহার করে। নিচের উদাহরণটিতে pageSize এবং pageToken URL প্যারামিটার হিসেবে সেট করা হয়েছে: 

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

অ্যাড ম্যানেজার SOAP API-এর বিপরীতে, অ্যাড ম্যানেজার API (বিটা) অতিরিক্ত পৃষ্ঠা থাকা সত্ত্বেও অনুরোধ করা পৃষ্ঠার আকারের চেয়ে কম ফলাফল ফেরত দিতে পারে। অতিরিক্ত ফলাফল আছে কিনা তা জানতে nextPageToken ফিল্ডটি ব্যবহার করুন।

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

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50

অভিবাসন প্রতিবেদন

SOAP API শুধুমাত্র অপ্রচলিত Reports টুলের রিপোর্টগুলো পড়তে ও চালাতে পারে। অপরদিকে, REST API শুধুমাত্র ইন্টারেক্টিভ রিপোর্টগুলো পড়তে, লিখতে এবং চালাতে পারে।

রিপোর্টিং টুল এবং এপিআইগুলোর একটি ভিন্ন আইডি স্পেস রয়েছে। SOAP এপিআই-এর একটি SavedQuery এর আইডি REST এপিআই-তে ব্যবহার করা যায় না।

আপনি যদি SavedQuery ব্যবহার করেন, তাহলে UI-তে রিপোর্টটিকে একটি ইন্টারেক্টিভ রিপোর্টে মাইগ্রেট করতে পারেন এবং দুটি ID স্পেসের মধ্যে একটি ম্যাপিং তৈরি করতে পারেন। রিপোর্ট মাইগ্রেট করার বিষয়ে আরও তথ্যের জন্য, “রিপোর্টগুলিকে ইন্টারেক্টিভ রিপোর্টে মাইগ্রেট করুন” দেখুন।

এপিআই পার্থক্যগুলো বুঝুন

SOAP API এবং REST API যেভাবে রিপোর্ট ডেফিনিশন ও ফলাফল পরিচালনা করে, তার মধ্যে কিছু পার্থক্য রয়েছে:

  • যখন কোনো রিপোর্টে শুধুমাত্র NAME চাওয়া হতো, তখন SOAP API স্বয়ংক্রিয়ভাবে ফলাফলে একটি সংশ্লিষ্ট ID ডাইমেনশন যোগ করে দিত। REST API-তে, ফলাফলে অন্তর্ভুক্ত হওয়ার জন্য আপনাকে অবশ্যই ReportDefinition এ ID ডাইমেনশনটি স্পষ্টভাবে যোগ করতে হবে।

  • SOAP API-তে মেট্রিক্সের জন্য কোনো সুস্পষ্ট টাইপ ছিল না। REST API একটি ডেটা টাইপ সংজ্ঞায়িত করে, যা Dimension enum ভ্যালুতে নথিভুক্ত থাকে। মনে রাখবেন যে ENUM ডাইমেনশনগুলো হলো ওপেন enum । ফলাফল পার্স করার সময় আপনাকে নতুন এবং অজানা enum ভ্যালুগুলো পরিচালনা করতে হবে।

  • SOAP API-তে Dimensions এবং DimensionAttributes আলাদা করা ছিল। REST API-তে একটি সমন্বিত Dimension enum আছে, যার মধ্যে উভয়ই অন্তর্ভুক্ত।

  • SOAP API-তে ডাইমেনশনের সংখ্যার কোনো সীমা ছিল না। ইন্টারেক্টিভ রিপোর্টের UI এবং API উভয় ক্ষেত্রেই ডাইমেনশনের সীমা ১০টি। যে ডাইমেনশনগুলো একই ID স্পেস দ্বারা বিভক্ত হয়, সেগুলোকে একটি একক ডাইমেনশন হিসেবে গণনা করা হয়। উদাহরণস্বরূপ, সীমা গণনা করার সময় ORDER_NAME , ORDER_ID , এবং ORDER_START_DATE অন্তর্ভুক্ত করলে তা শুধুমাত্র ১টি ডাইমেনশন হিসেবেই গণ্য হয়।