এই নির্দেশিকায় সকল এপিআই কলের সাধারণ কাঠামো বর্ণনা করা হয়েছে।
আপনি যদি এপিআই-এর সাথে ইন্টারঅ্যাক্ট করার জন্য কোনো ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন, তাহলে আপনার অন্তর্নিহিত রিকোয়েস্টের বিস্তারিত জানার প্রয়োজন হবে না। তবে, টেস্টিং এবং ডিবাগিংয়ের সময় এপিআই কলের গঠন সম্পর্কে কিছু জ্ঞান কাজে আসতে পারে।
গুগল অ্যাডস এপিআই হলো একটি gRPC এপিআই , যার REST বাইন্ডিং রয়েছে। এর মানে হলো, এই এপিআই-তে কল করার দুটি উপায় আছে।
পছন্দের :
অনুরোধের মূল অংশটিকে একটি প্রোটোকল বাফার হিসেবে তৈরি করুন।
HTTP/2 ব্যবহার করে এটি সার্ভারে পাঠান।
প্রতিক্রিয়াটিকে একটি প্রোটোকল বাফারে ডিসিরিয়ালাইজ করুন।
ফলাফলগুলো ব্যাখ্যা করুন।
আমাদের বেশিরভাগ ডকুমেন্টেশনে gRPC ব্যবহারের বর্ণনা দেওয়া হয়েছে।
ঐচ্ছিক :
অনুরোধের মূল অংশটি একটি JSON অবজেক্ট হিসেবে তৈরি করুন।
HTTP 1.1 ব্যবহার করে এটি সার্ভারে পাঠান।
প্রতিক্রিয়াটিকে একটি JSON অবজেক্ট হিসাবে ডিসিরিয়ালাইজ করুন।
ফলাফলগুলো ব্যাখ্যা করুন।
REST ব্যবহারের বিষয়ে আরও তথ্যের জন্য REST ইন্টারফেস গাইডটি দেখুন।
সম্পদের নাম
এপিআই-এর বেশিরভাগ অবজেক্ট তাদের রিসোর্স নেম স্ট্রিং দ্বারা চিহ্নিত করা হয়। REST ইন্টারফেস ব্যবহার করার সময় এই স্ট্রিংগুলো ইউআরএল (URL) হিসেবেও কাজ করে। এদের গঠন সম্পর্কে জানতে REST ইন্টারফেসের রিসোর্স নেম অংশটি দেখুন।
যৌগিক আইডি
যদি কোনো অবজেক্টের আইডি বিশ্বব্যাপী অনন্য না হয়, তবে তার প্যারেন্ট আইডির শুরুতে একটি টিল্ড (~) চিহ্ন যুক্ত করে সেই অবজেক্টটির জন্য একটি যৌগিক আইডি তৈরি করা হয়।
উদাহরণস্বরূপ, যেহেতু একটি অ্যাড গ্রুপের অ্যাড আইডি বিশ্বব্যাপী অনন্য নয়, তাই একটি অনন্য যৌগিক আইডি তৈরি করার জন্য আমরা এর শুরুতে এর প্যারেন্ট অবজেক্ট (অ্যাড গ্রুপ) আইডি যুক্ত করি:
-
123+~এরAdGroupId+45678এরAdGroupAdId=123~45678এর সম্মিলিত বিজ্ঞাপন গ্রুপের বিজ্ঞাপন আইডি।
অনুরোধ হেডার
এগুলো হলো HTTP হেডার (বা grpc মেটাডেটা ) যা অনুরোধের বডির সাথে থাকে:
অনুমোদন
আপনাকে অবশ্যই Authorization: Bearer YOUR_ACCESS_TOKEN ফর্ম্যাটে একটি OAuth2 অ্যাক্সেস টোকেন অন্তর্ভুক্ত করতে হবে, যা ক্লায়েন্টের পক্ষ থেকে কাজ করা একজন ম্যানেজার অ্যাকাউন্ট, অথবা সরাসরি নিজের অ্যাকাউন্ট পরিচালনা করা একজন বিজ্ঞাপনদাতাকে শনাক্ত করে। অ্যাক্সেস টোকেন পুনরুদ্ধার করার নির্দেশাবলী OAuth2 গাইডে পাওয়া যাবে। একটি অ্যাক্সেস টোকেন পাওয়ার পর এক ঘণ্টার জন্য বৈধ থাকে; মেয়াদ শেষ হয়ে গেলে, একটি নতুন টোকেন পেতে অ্যাক্সেস টোকেনটি রিফ্রেশ করুন। মনে রাখবেন যে আমাদের ক্লায়েন্ট লাইব্রেরিগুলি মেয়াদোত্তীর্ণ টোকেনগুলি স্বয়ংক্রিয়ভাবে রিফ্রেশ করে।
যদি আপনি অনুমোদন সংক্রান্ত ত্রুটির সম্মুখীন হন, তবে নিশ্চিত করুন যে আপনি সঠিক ক্রেডেনশিয়াল ব্যবহার করছেন এবং আপনার পর্যাপ্ত অনুমতি রয়েছে। একটি USER_PERMISSION_DENIED ত্রুটি নির্দেশ করে যে, প্রমাণীকৃত ব্যবহারকারীর অনুরোধে উল্লেখিত গ্রাহক অ্যাকাউন্টে অ্যাক্সেস নাও থাকতে পারে। অনুমতি ব্যবস্থাপনার বিশদ বিবরণের জন্য Google Ads Access Levels দেখুন।
ডেভেলপার-টোকেন
ডেভেলপার টোকেন হলো একটি ২২-ক্যারেক্টারের স্ট্রিং যা একজন গুগল অ্যাডস এপিআই ডেভেলপারকে অনন্যভাবে শনাক্ত করে। একটি উদাহরণ ডেভেলপার টোকেন স্ট্রিং হলো ABcdeFGH93KL-NOPQ_STUv । ডেভেলপার টোকেনটি developer-token : ABcdeFGH93KL-NOPQ_STUv এই ফর্মে অন্তর্ভুক্ত করতে হবে।
লগইন-গ্রাহক-আইডি
এটি অনুরোধে ব্যবহারের জন্য অনুমোদিত গ্রাহকের কাস্টমার আইডি, হাইফেন ( - ) ছাড়া। যদি গ্রাহক অ্যাকাউন্টে আপনার অ্যাক্সেস কোনো ম্যানেজার অ্যাকাউন্টের মাধ্যমে হয়, তাহলে এই হেডারটি আবশ্যক এবং এটি অবশ্যই ম্যানেজার অ্যাকাউন্টের কাস্টমার আইডিতে সেট করতে হবে। ম্যানেজার অ্যাকাউন্টের মাধ্যমে প্রমাণীকরণের সময় আপনি যদি login-customer-id অন্তর্ভুক্ত করতে ব্যর্থ হন, তাহলে এর ফলে একটি AuthorizationError.USER_PERMISSION_DENIED ত্রুটি দেখা দেয়। এই ধরনের ত্রুটি সম্পর্কে আরও তথ্যের জন্য সাধারণ ত্রুটিসমূহ (Common Errors) পর্যালোচনা করুন।
https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate
login-customer-id সেট করা, সাইন ইন করার পর গুগল অ্যাডস UI-তে একটি অ্যাকাউন্ট বেছে নেওয়া অথবা উপরের ডানদিকে আপনার প্রোফাইল ছবিতে ক্লিক করার সমতুল্য। আপনি যদি এই হেডারটি অন্তর্ভুক্ত না করেন, তবে এটি ডিফল্টরূপে অপারেটিং কাস্টমার হিসেবে সেট হয়ে যায়।
লিঙ্ক করা গ্রাহক আইডি
লিঙ্ক করা গুগল অ্যাডস অ্যাকাউন্টের ওপর কাজ করার সময় পার্টনাররা (যেমন থার্ড-পার্টি অ্যাপ অ্যানালিটিক্স প্রোভাইডার বা ডেটা পার্টনার) এই হেডারটি ব্যবহার করে থাকে। এই হেডারে অবশ্যই সেই গুগল অ্যাডস অ্যাকাউন্টের কাস্টমার আইডি উল্লেখ করতে হবে, যেটিতে প্রোডাক্ট লিঙ্কটি রয়েছে।
এমন একটি পরিস্থিতি বিবেচনা করুন যেখানে কোনো অংশীদারকে একটি পণ্যের লিঙ্কের উপর ভিত্তি করে গুগল অ্যাডস অ্যাকাউন্টে এপিআই (API) কল করতে হবে।
- বিজ্ঞাপনদাতা : এপিআই কলের মাধ্যমে যে গুগল অ্যাডস অ্যাকাউন্টটি পরিচালনা বা আপডেট করা হচ্ছে। বিজ্ঞাপনদাতা অ্যাকাউন্টের আইডি অনুরোধে উল্লেখ করা থাকে। REST-এ, এটি হলো
customerIdপাথ প্যারামিটার (উদাহরণস্বরূপ,customers/1111111111/...), এবং gRPC-তে, এটি হলো অনুরোধেরcustomer_idফিল্ড। - অংশীদার : অংশীদার অ্যাকাউন্ট (উদাহরণস্বরূপ, একজন তৃতীয় পক্ষের অ্যাপ অ্যানালিটিক্স প্রদানকারী বা ডেটা অংশীদার)।
- লিঙ্ক করা অ্যাকাউন্ট : যে গুগল অ্যাডস অ্যাকাউন্টের পার্টনারের সাথে একটি প্রতিষ্ঠিত প্রোডাক্ট লিঙ্ক রয়েছে, যা পার্টনারকে অ্যাডভার্টাইজারে অ্যাক্সেস প্রদান করে।
যে ব্যবহারকারীর পার্টনার-এ অ্যাক্সেস আছে, তিনি অ্যাডভার্টাইজার-এর এনটিটিগুলোর ওপর কাজ করার জন্য এপিআই কল করেন (উদাহরণস্বরূপ, কনভার্সন আপলোড করতে বা ব্যবহারকারীর তালিকা পরিচালনা করতে)। লিঙ্ক করা অ্যাকাউন্টটি স্বয়ং অ্যাডভার্টাইজার অথবা অ্যাডভার্টাইজার-এর কোনো ম্যানেজার অ্যাকাউন্ট হতে পারে।
অনুরোধ হেডারগুলি নিম্নলিখিতভাবে সেট করতে হবে:
-
Authorization: পার্টনার-এ প্রবেশাধিকার আছে এমন একজন ব্যবহারকারীর জন্য একটি OAuth2 টোকেন। -
developer-token: এপিআই অ্যাপ্লিকেশনের জন্য ডেভেলপার টোকেন, যা সাধারণত পার্টনারের সাথে যুক্ত থাকে। -
login-customer-id: পার্টনারের কাস্টমার আইডি। প্রমাণীকৃত ব্যবহারকারীর এই অ্যাকাউন্টে অ্যাক্সেস থাকতে হবে। -
linked-customer-id: লিঙ্ক করা অ্যাকাউন্টের কাস্টমার আইডি। এই হেডারটি নির্দেশ করে যে, এই অনুরোধের অনুমোদনটি পার্টনারের সাথে লিঙ্ক করা অ্যাকাউন্টের প্রোডাক্ট লিঙ্কের উপর নির্ভরশীল।
দুটি সংযোগের পরিস্থিতি রয়েছে:
- যদি বিজ্ঞাপনদাতার পার্টনারের সাথে সরাসরি প্রোডাক্ট লিঙ্ক থাকে, তাহলে লিঙ্ক করা অ্যাকাউন্টটি হবে বিজ্ঞাপনদাতা, এবং
linked-customer-idঅবশ্যই বিজ্ঞাপনদাতার কাস্টমার আইডিতে সেট করতে হবে। - যদি বিজ্ঞাপনদাতা এমন একটি ম্যানেজার অ্যাকাউন্ট দ্বারা পরিচালিত হয় যার পার্টনারের সাথে একটি প্রোডাক্ট লিঙ্ক রয়েছে, তাহলে লিঙ্ক করা অ্যাকাউন্টটি হবে সেই ম্যানেজার অ্যাকাউন্ট, এবং
linked-customer-idঅবশ্যই ম্যানেজারের গ্রাহক আইডিতে সেট করতে হবে।
উদাহরণ ১: সরাসরি লিঙ্ক
যদি বিজ্ঞাপনদাতা 1111111111 সাথে অংশীদার 2222222222 এর সরাসরি সংযোগ থাকে, এবং এপিআই কলটি customers/1111111111/... লক্ষ্য করে করা হয়:
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111
উদাহরণ ২: ম্যানেজার লিঙ্ক
যদি বিজ্ঞাপনদাতা 1111111111 ব্যবস্থাপক 3333333333 দ্বারা পরিচালিত হয়, ব্যবস্থাপক 3333333333 এর সাথে অংশীদার 2222222222 এর একটি সংযোগ থাকে, এবং এপিআই কলটি customers/1111111111/... লক্ষ্য করে করা হয়:
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333
প্রতিক্রিয়া হেডার
রেসপন্স বডির সাথে নিম্নলিখিত হেডারগুলো (অথবা grpc ট্রেইলিং-মেটাডেটা ) ফেরত দেওয়া হয়। ডিবাগিংয়ের উদ্দেশ্যে এই মানগুলো লগ করার পরামর্শ দেওয়া হচ্ছে।
অনুরোধ-আইডি
request-id হলো একটি স্ট্রিং যা এই রিকোয়েস্টটিকে অনন্যভাবে শনাক্ত করে।