API কল স্ট্রাকচার

এই নির্দেশিকায় সকল এপিআই কলের সাধারণ কাঠামো বর্ণনা করা হয়েছে।

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

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

পছন্দের :

1. অনুরোধের মূল অংশটিকে একটি প্রোটোকল বাফার হিসেবে তৈরি করুন।

2. HTTP/2 ব্যবহার করে এটি সার্ভারে পাঠান।

3. প্রতিক্রিয়াটিকে একটি প্রোটোকল বাফারে ডিসিরিয়ালাইজ করুন।

4. ফলাফলগুলো ব্যাখ্যা করুন।

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

ঐচ্ছিক :

1. অনুরোধের মূল অংশটি একটি JSON অবজেক্ট হিসেবে তৈরি করুন।

2. HTTP 1.1 ব্যবহার করে এটি সার্ভারে পাঠান।

3. প্রতিক্রিয়াটিকে একটি JSON অবজেক্ট হিসাবে ডিসিরিয়ালাইজ করুন।

4. ফলাফলগুলো ব্যাখ্যা করুন।

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-তে একটি অ্যাকাউন্ট বেছে নেওয়া অথবা উপরের ডানদিকে আপনার প্রোফাইল ছবিতে ক্লিক করার সমতুল্য। আপনি যদি এই হেডারটি অন্তর্ভুক্ত না করেন, তবে এটি ডিফল্টরূপে অপারেটিং কাস্টমার হিসেবে সেট হয়ে যায়।

লিঙ্ক করা গ্রাহক আইডি

এই হেডারটি শুধুমাত্র তৃতীয় পক্ষের অ্যাপ অ্যানালিটিক্স প্রদানকারীরা একটি লিঙ্ক করা Google Ads অ্যাকাউন্টে কনভার্সন আপলোড করার সময় ব্যবহার করে।

এমন একটি পরিস্থিতি বিবেচনা করুন যেখানে অ্যাকাউন্ট A এর ব্যবহারকারীরা একটি ThirdPartyAppAnalyticsLink এর মাধ্যমে অ্যাকাউন্ট B কে তার এনটিটিগুলোতে রিড এবং এডিট অ্যাক্সেস প্রদান করে। একবার লিঙ্ক করা হয়ে গেলে, অ্যাকাউন্ট B এর একজন ব্যবহারকারী লিঙ্কের মাধ্যমে প্রদত্ত অনুমতি সাপেক্ষে অ্যাকাউন্ট A বিরুদ্ধে API কল করতে পারে। এই ক্ষেত্রে, অ্যাকাউন্ট A তে API-কল করার অনুমতি অন্যান্য API কলে ব্যবহৃত ম্যানেজার-অ্যাকাউন্ট সম্পর্কের পরিবর্তে, অ্যাকাউন্ট B এর সাথে থাকা থার্ড-পার্টি লিঙ্কের মাধ্যমে নির্ধারিত হয়।

তৃতীয় পক্ষের অ্যাপ অ্যানালিটিক্স প্রদানকারী নিম্নরূপে একটি এপিআই কল করে:

• linked-customer-id : তৃতীয় পক্ষের অ্যাপ অ্যানালিটিক্স অ্যাকাউন্ট যা ডেটা আপলোড করে (অ্যাকাউন্ট B )।
• customer-id : যে গুগল অ্যাডস অ্যাকাউন্টে ডেটা আপলোড করা হয় (অ্যাকাউন্ট A )।
• login-customer-id এবং Authorization header: অ্যাকাউন্ট B তে অ্যাক্সেস আছে এমন একজন ব্যবহারকারীকে শনাক্ত করার জন্য বিভিন্ন মানের সমন্বয়।

প্রতিক্রিয়া হেডার

রেসপন্স বডির সাথে নিম্নলিখিত হেডারগুলো (অথবা grpc ট্রেইলিং-মেটাডেটা ) ফেরত দেওয়া হয়। ডিবাগিংয়ের উদ্দেশ্যে এই মানগুলো লগ করার পরামর্শ দেওয়া হচ্ছে।

অনুরোধ-আইডি

request-id হলো একটি স্ট্রিং যা এই রিকোয়েস্টটিকে অনন্যভাবে শনাক্ত করে।