এই গাইডে সব API কলের সাধারণ স্ট্রাকচার বর্ণনা করা হয়েছে।
API-এর সাথে ইন্টার্যাক্ট করার জন্য আপনি কোনও ক্লায়েন্ট লাইব্রেরি ব্যবহার করলে, আপনাকে অন্তর্নিহিত অনুরোধের বিবরণ জানতে হবে না। তবে, API কল স্ট্রাকচার সম্পর্কে কিছু জ্ঞান থাকলে টেস্ট ও ডিবাগ করার সময় সুবিধা হতে পারে।
Google Ads API হল REST বাইন্ডিং সহ gRPC API। এর অর্থ হল API-তে কল করার দুটি উপায় আছে।
পছন্দের:
- প্রোটোকল বাফার হিসেবে অনুরোধের বডি তৈরি করুন।
- HTTP/2 ব্যবহার করে সার্ভারে পাঠান।
- প্রোটোকল বাফারে উত্তর ডিসিরিয়ালাইজ করুন।
- ফলাফল বিশ্লেষণ করুন।
আমাদের বেশিরভাগ ডকুমেন্টেশনে gRPC ব্যবহার করা সম্পর্কে বর্ণনা করা হয়েছে।
ঐচ্ছিক:
- JSON অবজেক্ট হিসেবে অনুরোধের বডি তৈরি করুন।
- HTTP 1.1 ব্যবহার করে এটি সার্ভারে পাঠান।
- JSON অবজেক্ট হিসেবে উত্তরটি ডিসিরিয়ালাইজ করুন।
- ফলাফল বিশ্লেষণ করুন।
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 অনুরোধের সমস্যা সমাধানে সহায়তা করার জন্য সহায়তা টিমের সাথে যোগাযোগ করার সময় এই
মানটি প্রদান করুন।