API কলের গঠন

এই গাইডে সব API কলের সাধারণ স্ট্রাকচার বর্ণনা করা হয়েছে।

API-এর সাথে ইন্টার‍্যাক্ট করার জন্য আপনি ক্লায়েন্ট লাইব্রেরি ব্যবহার করলে, আপনাকে অন্তর্নিহিত অনুরোধের বিবরণ জানতে হবে না। তবে, টেস্টিং ও ডিবাগিং করার সময় API কলের স্ট্রাকচার সম্পর্কে কিছু জ্ঞান কাজে লাগতে পারে।

Google Ads API হল REST বাইন্ডিং সহ gRPC API। এর অর্থ হল, API-তে কল করার দুটি উপায় আছে।

পছন্দের:

  1. প্রোটোকল বাফার হিসেবে অনুরোধের বডি তৈরি করুন।
  2. HTTP/2 ব্যবহার করে সার্ভারে পাঠান।
  3. প্রোটোকল বাফারে উত্তরের ডিসিরিয়ালাইজ করা।
  4. ফলাফল বিশ্লেষণ করুন।

আমাদের বেশিরভাগ ডকুমেন্টেশনে gRPC ব্যবহার করা সম্পর্কে বর্ণনা করা হয়েছে।

ঐচ্ছিক:

  1. JSON অবজেক্ট হিসেবে অনুরোধের বডি তৈরি করুন।
  2. HTTP 1.1 ব্যবহার করে এটি সার্ভারে পাঠান।
  3. JSON অবজেক্ট হিসেবে উত্তরটি ডিসিরিয়ালাইজ করুন।
  4. ফলাফল বিশ্লেষণ করুন।

REST ব্যবহার করা সম্পর্কে আরও তথ্যের জন্য REST ইন্টারফেস গাইড দেখুন।

রিসোর্স শনাক্তকারী

Google Ads API-তে অবজেক্টগুলি স্ট্রাকচার্ড রিসোর্স নাম এবং কম্পোজিট আইডেন্টিফায়ার ব্যবহার করে অ্যাড্রেস করা হয়।

রিসোর্সের নাম

API-তে বেশিরভাগ অবজেক্ট তাদের রিসোর্স নামের স্ট্রিং দ্বারা শনাক্ত করা হয়। এছাড়াও, REST ইন্টারফেস ব্যবহার করার সময় এই স্ট্রিংগুলি URL হিসেবে কাজ করে। REST ইন্টারফেস দেখুন রিসোর্সের নাম তাদের গঠনের জন্য।

কম্পোজিট আইডি

কোনও অবজেক্টের আইডি বিশ্বজুড়ে অনন্য না হলে, সেই অবজেক্টের জন্য একটি কম্পোজিট আইডি তৈরি করা হয়। এর জন্য, অবজেক্টের প্যারেন্ট আইডি এবং একটি টিল্ড (~) আগে যোগ করা হয়।

যেমন, AdGroupAd-এর রিসোর্স নামের প্যাটার্ন হল customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}। কারণ এর কম্পোজিট আইডেন্টিফায়ার মূল বিজ্ঞাপন গ্রুপ আইডি (ad_group.id) এবং অন্তর্নিহিত বিজ্ঞাপন আইডি (ad_group_ad.ad.id) একত্রিত করে, আমরা বিজ্ঞাপন আইডির আগে বিজ্ঞাপন গ্রুপ আইডি যোগ করি:

  • 123-এর AdGroupId + ~ + 45678-এর AdId = কম্পোজিট বিজ্ঞাপন গ্রুপ 123~45678-এর বিজ্ঞাপন আইডি।

রিকোয়েস্ট হেডার

এগুলি হল HTTP হেডার (বা gRPC মেটাডেটা) যা অনুরোধের বডির সাথে থাকে:

অনুমোদন

আপনাকে অবশ্যই Authorization: Bearer YOUR_ACCESS_TOKEN-এর ফর্ম্যাটে একটি OAuth 2.0 অ্যাক্সেস টোকেন অন্তর্ভুক্ত করতে হবে যা কোনও ক্লায়েন্টের পক্ষে কাজ করা ম্যানেজার অ্যাকাউন্ট বা সরাসরি নিজের অ্যাকাউন্ট ম্যানেজ করা কোনও বিজ্ঞাপনদাতাকে শনাক্ত করে। অ্যাক্সেস টোকেন পুনরুদ্ধার করার নির্দেশাবলী OAuth2 নির্দেশিকা-তে পাওয়া যাবে। অ্যাক্সেস টোকেন পাওয়ার পরে এক ঘণ্টা পর্যন্ত বৈধ থাকে; মেয়াদ শেষ হয়ে গেলে, নতুন অ্যাক্সেস টোকেন পেতে এটি রিফ্রেশ করুন। মনে রাখবেন, আমাদের ক্লায়েন্ট লাইব্রেরি মেয়াদ শেষ হয়ে যাওয়া টোকেন অটোমেটিক রিফ্রেশ করে।

অনুমোদন সংক্রান্ত কোনও সমস্যা হলে, আপনি সঠিক ক্রেডেনশিয়াল ব্যবহার করছেন কিনা এবং আপনার কাছে পর্যাপ্ত অনুমতি আছে কিনা তা নিশ্চিত করুন। USER_PERMISSION_DENIED সমস্যার অর্থ হল অনুরোধে উল্লেখ করা গ্রাহক অ্যাকাউন্টে যাচাই করা ব্যবহারকারীর অ্যাক্সেস নাও থাকতে পারে। আপনার Google Cloud প্রোজেক্ট যদি শুধুমাত্র Test অ্যাক্সেসের জন্য অনুমোদিত হয় এবং আপনি প্রোডাকশন অ্যাকাউন্টকে টার্গেট করে অনুরোধ পাঠান, তাহলে API v25 এবং তার পরের ভার্সনে AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION রিটার্ন করে (অথবা v24 এবং তার আগের ভার্সনে AuthorizationError.ACTION_NOT_PERMITTED)। অনুমতি ম্যানেজ করার ব্যাপারে বিস্তারিত জানতে Google Ads অ্যাক্সেস লেভেল দেখুন।

login-customer-id

অনুরোধে ব্যবহার করার জন্য এটি হল অনুমোদিত গ্রাহকের কাস্টমার আইডি, হাইফেন (-) ছাড়া। ম্যানেজার অ্যাকাউন্টের মাধ্যমে গ্রাহক অ্যাকাউন্টে অ্যাক্সেস পেলে, এই হেডার প্রয়োজনীয় এবং ম্যানেজার অ্যাকাউন্টের কাস্টমার আইডিতে সেট করতে হবে। ম্যানেজার অ্যাকাউন্টের মাধ্যমে যাচাই করার সময় login-customer-id অন্তর্ভুক্ত করতে না পারলে, AuthorizationError.USER_PERMISSION_DENIED সমস্যা হয়। এই ধরনের সমস্যা সম্পর্কে আরও জানতে, সাধারণ সমস্যা পর্যালোচনা করুন। অ্যাকাউন্ট অ্যাক্সেস সংক্রান্ত সমস্যার সমাধান কীভাবে করা হয়, সেই বিষয়ে বিস্তারিত জানতে, OAuth অ্যাক্সেস মডেল গাইড দেখুন।

https://googleads.googleapis.com/v26/customers/1234567890/campaignBudgets:mutate

login-customer-id সেট করা মানে সাইন-ইন করার পরে বা উপরে ডানদিকে আপনার প্রোফাইল ছবিতে ক্লিক করার পরে Google Ads UI-তে একটি অ্যাকাউন্ট বেছে নেওয়া। আপনি এই হেডার অন্তর্ভুক্ত না করলে, এটি ডিফল্ট হিসেবে অপারেটিং কাস্টমার-এ সেট হয়ে যায়।

linked-customer-id

লিঙ্ক করা Google Ads অ্যাকাউন্টে অ্যাকশন নেওয়ার সময় পার্টনারদের (যেমন, থার্ড-পার্টি অ্যাপ অ্যানালিটিক্স প্রোভাইডার বা ডেটা পার্টনার) এই হেডার প্রয়োজন হয় এবং তারা এটি ব্যবহার করে। এই হেডারকে অবশ্যই সেই Google Ads অ্যাকাউন্টের গ্রাহক আইডি উল্লেখ করতে হবে যেটিতে প্রোডাক্ট লিঙ্ক আছে।

এমন একটি পরিস্থিতির কথা বিবেচনা করুন যেখানে কোনও পার্টনারকে প্রোডাক্ট লিঙ্কের উপর ভিত্তি করে Google Ads অ্যাকাউন্টে API কল করতে হবে।

  • বিজ্ঞাপনদাতা: API কলের মাধ্যমে ম্যানেজ বা আপডেট করা Google Ads অ্যাকাউন্ট। অনুরোধে বিজ্ঞাপনদাতার অ্যাকাউন্টের আইডি উল্লেখ করা আছে। REST-এ, এটি হল customerId পাথ প্যারামিটার (যেমন, customers/1111111111/...) এবং gRPC-তে, এটি হল অনুরোধের customer_id ফিল্ড।
  • পার্টনার: পার্টনার অ্যাকাউন্ট (যেমন, থার্ড-পার্টি অ্যাপ অ্যানালিটিক্স প্রদানকারী বা ডেটা পার্টনার)।
  • লিঙ্ক করা অ্যাকাউন্ট: পার্টনারের সাথে প্রতিষ্ঠিত প্রোডাক্ট লিঙ্ক আছে এমন Google Ads অ্যাকাউন্ট, যা পার্টনারকে বিজ্ঞাপনদাতার অ্যাক্সেস দেয়।

পার্টনার অ্যাকাউন্টে অ্যাক্সেস আছে এমন একজন ব্যবহারকারী বিজ্ঞাপনদাতা অ্যাকাউন্টে এন্টিটির উপর কাজ করার জন্য API কল করেন (যেমন, কনভার্সন আপলোড করা বা ব্যবহারকারীর তালিকা ম্যানেজ করা)। লিঙ্ক করা অ্যাকাউন্টটি বিজ্ঞাপনদাতা অ্যাকাউন্ট নিজে বা বিজ্ঞাপনদাতা অ্যাকাউন্টের ম্যানেজার অ্যাকাউন্ট হতে পারে।

অনুরোধের হেডার অবশ্যই নিম্নলিখিতভাবে সেট করতে হবে:

  • Authorization: পার্টনারের অ্যাক্সেস আছে এমন কোনও ব্যবহারকারীর জন্য OAuth 2.0 অ্যাক্সেস টোকেন।
  • login-customer-id: পার্টনার অ্যাকাউন্টের কাস্টমার আইডি। যাচাই করা ব্যবহারকারীর এই অ্যাকাউন্টে অ্যাক্সেস থাকতে হবে।
  • linked-customer-id: লিঙ্ক করা অ্যাকাউন্টের গ্রাহক আইডি। এই হেডার থেকে বোঝা যায় যে এই অনুরোধের অনুমোদনের জন্য পার্টনারের সাথে লিঙ্ক করা অ্যাকাউন্টের প্রোডাক্ট লিঙ্কের উপর নির্ভর করতে হবে।

লিঙ্ক করার দুটি পরিস্থিতি আছে:

  • বিজ্ঞাপনদাতার অ্যাকাউন্টের সাথে পার্টনার অ্যাকাউন্টের সরাসরি প্রোডাক্ট লিঙ্ক থাকলে, লিঙ্ক করা অ্যাকাউন্ট হল বিজ্ঞাপনদাতার অ্যাকাউন্ট এবং linked-customer-id অবশ্যই বিজ্ঞাপনদাতার অ্যাকাউন্টের গ্রাহক আইডি হিসেবে সেট করতে হবে।
  • বিজ্ঞাপনদাতার অ্যাকাউন্ট যদি এমন কোনও ম্যানেজার অ্যাকাউন্ট দ্বারা ম্যানেজ করা হয় যার সাথে পার্টনার অ্যাকাউন্টের প্রোডাক্ট লিঙ্ক আছে, তাহলে লিঙ্ক করা অ্যাকাউন্ট হল ম্যানেজার অ্যাকাউন্ট এবং linked-customer-id অবশ্যই ম্যানেজারের কাস্টমার আইডি হিসেবে সেট করতে হবে।

উদাহরণ ১: ডাইরেক্ট লিঙ্ক

বিজ্ঞাপনদাতার অ্যাকাউন্ট 1111111111-এর সাথে পার্টনার অ্যাকাউন্ট 2222222222-এর সরাসরি লিঙ্ক থাকলে এবং API কল customers/1111111111/...-কে টার্গেট করলে:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

উদাহরণ ২: ম্যানেজার লিঙ্ক

বিজ্ঞাপনদাতার অ্যাকাউন্ট 1111111111 যদি ম্যানেজার অ্যাকাউন্ট 3333333333 দ্বারা ম্যানেজ করা হয়, ম্যানেজার অ্যাকাউন্টের 3333333333 সাথে পার্টনার অ্যাকাউন্টের 2222222222 লিঙ্ক থাকে এবং API কল customers/1111111111/...-কে টার্গেট করে:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

রেসপন্স হেডার

উত্তরের বডির সাথে নিম্নলিখিত হেডার (বা gRPC ট্রেলিং-মেটাডেটা) ফেরত দেওয়া হয়। আমরা সাজেস্ট করি যে আপনি ডিবাগিংয়ের উদ্দেশ্যে এইসব ভ্যালু লগ করুন।

request-id

request-id হল একটি স্ট্রিং যা এই অনুরোধকে অনন্যভাবে শনাক্ত করে। API অনুরোধ ব্যর্থ হলে বা অপ্রত্যাশিত হলে, সমস্যার সমাধান করতে সহায়তা টিমের সাথে যোগাযোগ করার সময় এই মানটি প্রদান করুন।

পূর্ববর্তী
রিসোর্স মেটাডেটা