API ত্রুটিগুলি বুঝুন

এই নির্দেশিকাটি ব্যাখ্যা করে যে গুগল অ্যাডস এপিআই কীভাবে ত্রুটিগুলি পরিচালনা করে এবং জানায়। এপিআই ত্রুটিগুলির গঠন এবং অর্থ বোঝা শক্তিশালী অ্যাপ্লিকেশন তৈরির জন্য অত্যন্ত গুরুত্বপূর্ণ, যা ভুল ইনপুট থেকে শুরু করে পরিষেবার সাময়িক অনুপলব্ধতার মতো সমস্যাগুলি সুন্দরভাবে সামলাতে পারে।

গুগল অ্যাডস এপিআই স্ট্যান্ডার্ড গুগল এপিআই এরর মডেল অনুসরণ করে, যা জিআরপিসি স্ট্যাটাস কোডের উপর ভিত্তি করে তৈরি। প্রতিটি এপিআই রেসপন্স, যার ফলে কোনো এরর হয়, তাতে একটি Status অবজেক্ট থাকে, যাতে নিম্নলিখিত বিষয়গুলো অন্তর্ভুক্ত থাকে:

• একটি সাংখ্যিক ত্রুটি কোড।
• একটি ত্রুটি বার্তা।
• ঐচ্ছিক, অতিরিক্ত ত্রুটির বিবরণ।

ক্যানোনিকাল ত্রুটি কোড

গুগল অ্যাডস এপিআই, gRPC এবং HTTP দ্বারা সংজ্ঞায়িত কিছু প্রমিত ত্রুটি কোড ব্যবহার করে। এই কোডগুলো ত্রুটির ধরন সম্পর্কে একটি প্রাথমিক ধারণা দেয়। সমস্যার মূল প্রকৃতি বোঝার জন্য আপনার সর্বদা প্রথমে এই সাংখ্যিক কোডটি পরীক্ষা করা উচিত।

গুগল অ্যাডস এপিআই ব্যবহার করার সময় আপনি সাধারণত যে কোডগুলোর সম্মুখীন হতে পারেন, নিচের সারণিতে সেগুলোর একটি সংক্ষিপ্ত বিবরণ দেওয়া হলো:

এই কোডগুলো সম্পর্কে আরও বিস্তারিত জানতে, এপিআই ডিজাইন গাইড - এরর কোডসমূহ দেখুন।

ত্রুটির বিবরণ বুঝুন

শীর্ষ-স্তরের কোডের বাইরে, গুগল অ্যাডস এপিআই ' Status অবজেক্টের ' details ফিল্ডের মধ্যে আরও সুনির্দিষ্ট ত্রুটির তথ্য প্রদান করে। এই ফিল্ডটিতে প্রায়শই একটি GoogleAdsFailure প্রোটো থাকে, যার মধ্যে স্বতন্ত্র GoogleAdsError অবজেক্টগুলোর একটি তালিকা অন্তর্ভুক্ত থাকে।

প্রতিটি GoogleAdsFailure অবজেক্টে রয়েছে:

• errors : GoogleAdsError অবজেক্টগুলোর একটি তালিকা, যার প্রতিটিতে সংঘটিত একটি নির্দিষ্ট ত্রুটির বিবরণ রয়েছে।
• request_id : অনুরোধটির একটি অনন্য আইডি, যা ডিবাগিং এবং সহায়তার জন্য উপযোগী।

প্রতিটি GoogleAdsError অবজেক্ট নিম্নলিখিত বিষয়গুলো প্রদান করে:

• errorCode : একটি আরও সুনির্দিষ্ট, গুগল অ্যাডস এপিআই-নির্দিষ্ট ত্রুটি কোড , যেমন AuthenticationError.NOT_ADS_USER ।
• message : নির্দিষ্ট ত্রুটিটির একটি পাঠযোগ্য বিবরণ।
• trigger : যে মানটির কারণে ত্রুটিটি ঘটেছে, যদি প্রযোজ্য হয়।
• location : অনুরোধের কোথায় ত্রুটিটি ঘটেছে তা বর্ণনা করে, যার মধ্যে ফিল্ড পাথও অন্তর্ভুক্ত থাকে।
• details : ত্রুটির অতিরিক্ত বিবরণ, যেমন অপ্রকাশিত ত্রুটির কারণসমূহ।

ত্রুটির বিবরণের উদাহরণ

যখন আপনি কোনো ত্রুটি পাবেন, তখন আপনার ক্লায়েন্ট লাইব্রেরি আপনাকে এই বিবরণগুলো দেখার সুযোগ দেবে। উদাহরণস্বরূপ, একটি INVALID_ARGUMENT (কোড ৩)-এর ক্ষেত্রে GoogleAdsFailure বিবরণগুলো এইরকম হতে পারে:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

এই উদাহরণে, শীর্ষ-স্তরের INVALID_ARGUMENT থাকা সত্ত্বেও, GoogleAdsFailure বিবরণ আপনাকে বলে দেয় যে name এবং description ফিল্ডগুলোই সমস্যাটির কারণ ছিল এবং কেন (যথাক্রমে REQUIRED এবং TOO_SHORT )।

ত্রুটির বিবরণ খুঁজুন

আপনি স্ট্যান্ডার্ড এপিআই কল, আংশিক ব্যর্থতা, নাকি স্ট্রিমিং ব্যবহার করছেন, তার ওপর নির্ভর করে আপনি ত্রুটির বিবরণ কীভাবে অ্যাক্সেস করবেন।

স্ট্যান্ডার্ড এবং স্ট্রিমিং এপিআই কল

যখন পার্শিয়াল ফেইলর ব্যবহার না করে কোনো এপিআই কল ব্যর্থ হয় ( স্ট্রিমিং কল সহ), তখন gRPC রেসপন্স হেডারের শেষের মেটাডেটার অংশ হিসেবে GoogleAdsFailure অবজেক্টটি ফেরত আসে। আপনি যদি স্ট্যান্ডার্ড কলের জন্য REST ব্যবহার করেন, তাহলে GoogleAdsFailure এইচটিটিপি রেসপন্সে ফেরত আসে। ক্লায়েন্ট লাইব্রেরিগুলো সাধারণত এটিকে একটি GoogleAdsFailure অ্যাট্রিবিউটসহ এক্সেপশন হিসেবে দেখায়।

আংশিক ব্যর্থতা

আপনি যদি পার্শিয়াল ফেইলিওর ব্যবহার করেন, তাহলে ব্যর্থ অপারেশনের ত্রুটিগুলো রেসপন্স হেডারে নয়, বরং রেসপন্সের partial_failure_error ফিল্ডে ফেরত দেওয়া হয়। এক্ষেত্রে, রেসপন্সের মধ্যে একটি google.rpc.Status অবজেক্টের ভেতরে GoogleAdsFailure টি এমবেড করা থাকে।

ব্যাচ জব

ব্যাচ প্রসেসিংয়ের ক্ষেত্রে, কাজটি সম্পন্ন হওয়ার পর ব্যাচ জবের ফলাফল পুনরুদ্ধার করে প্রতিটি অপারেশনের ত্রুটি খুঁজে পাওয়া যায়। যদি অপারেশনটি ব্যর্থ হয়, তবে প্রতিটি অপারেশনের ফলাফলে একটি status ফিল্ড থাকবে, যেখানে ত্রুটির বিবরণ দেওয়া থাকবে।

অনুরোধ আইডি

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

আপনি request-id একাধিক জায়গায় খুঁজে পেতে পারেন:

• GoogleAdsFailure : যদি কোনো API কল ব্যর্থ হয় এবং GoogleAdsFailure রিটার্ন করা হয়, তাহলে তাতে একটি request_id থাকবে।
• ট্রেইলিং মেটাডেটা : সফল এবং ব্যর্থ উভয় অনুরোধের ক্ষেত্রেই, gRPC প্রতিক্রিয়ার ট্রেইলিং মেটাডেটাতে request-id পাওয়া যায়।
• রেসপন্স হেডার : সফল স্ট্রিমিং রিকোয়েস্ট ব্যতীত, সফল এবং ব্যর্থ উভয় রিকোয়েস্টের ক্ষেত্রেই gRPC এবং HTTP রেসপন্স হেডারে request-id পাওয়া যায়।
• SearchGoogleAdsStreamResponse : স্ট্রিমিং অনুরোধের ক্ষেত্রে, প্রতিটি SearchGoogleAdsStreamResponse মেসেজে একটি request_id ফিল্ড থাকে।

ত্রুটি নথিভুক্ত করার সময় বা সাপোর্টের সাথে যোগাযোগ করার সময়, সমস্যা নির্ণয়ে সহায়তার জন্য অবশ্যই request-id উল্লেখ করুন।

ত্রুটি ব্যবস্থাপনার সর্বোত্তম অনুশীলন

স্থিতিস্থাপক অ্যাপ্লিকেশন তৈরি করতে, নিম্নলিখিত সর্বোত্তম অনুশীলনগুলি প্রয়োগ করুন:

1. ত্রুটির বিবরণ পরীক্ষা করুন: সর্বদা Status অবজেক্টের details ফিল্ডটি পার্স করুন, বিশেষ করে GoogleAdsFailure এর সন্ধান করুন। GoogleAdsError মধ্যে থাকা errorCode , message , এবং location এর মতো সুনির্দিষ্ট তথ্য ডিবাগিং এবং ব্যবহারকারীকে প্রতিক্রিয়া জানানোর জন্য সবচেয়ে কার্যকরী তথ্য প্রদান করে।

2. ক্লায়েন্ট এবং সার্ভার ত্রুটির মধ্যে পার্থক্য করুন:

   • ক্লায়েন্ট ত্রুটি: INVALID_ARGUMENT , NOT_FOUND , PERMISSION_DENIED , FAILED_PRECONDITION , UNAUTHENTICATED মতো কোড। এগুলোর জন্য অনুরোধে অথবা আপনার অ্যাপ্লিকেশনের অবস্থা/ক্রেডেনশিয়ালে পরিবর্তন প্রয়োজন। সমস্যাটির সমাধান না করে অনুরোধটি পুনরায় চেষ্টা করবেন না।
   • সার্ভার ত্রুটি: UNAVAILABLE , INTERNAL , DEADLINE_EXCEEDED , UNKNOWN মতো কোড। এগুলো এপিআই (API) পরিষেবাতে একটি অস্থায়ী সমস্যার ইঙ্গিত দেয়।

3. পুনরায় চেষ্টা করার কৌশল প্রয়োগ করুন:

   • কখন পুনরায় চেষ্টা করবেন: শুধুমাত্র ক্ষণস্থায়ী সার্ভার ত্রুটির ক্ষেত্রে পুনরায় চেষ্টা করুন, যেমন— UNAVAILABLE , DEADLINE_EXCEEDED , INTERNAL , UNKNOWN , এবং ABORTED ।
   • এক্সপোনেনশিয়াল ব্যাকঅফ: পুনরায় চেষ্টার মধ্যবর্তী সময় বাড়ানোর জন্য একটি এক্সপোনেনশিয়াল ব্যাকঅফ অ্যালগরিদম ব্যবহার করুন। এটি আগে থেকেই চাপের মধ্যে থাকা একটি সার্ভিসকে অতিরিক্ত ভারাক্রান্ত হওয়া থেকে বাঁচাতে সাহায্য করে। উদাহরণস্বরূপ, প্রথমে ১ সেকেন্ড, তারপর ২ সেকেন্ড, তারপর ৪ সেকেন্ড অপেক্ষা করুন এবং এভাবে সর্বোচ্চ সংখ্যক পুনরায় চেষ্টা বা মোট অপেক্ষার সময় পর্যন্ত তা চালিয়ে যান।
   • জিটার: ব্যাকঅফ ডিলে-তে অল্প পরিমাণে এলোমেলো 'জিটার' যোগ করুন, যাতে 'থান্ডারিং হার্ড' সমস্যাটি প্রতিরোধ করা যায়, যেখানে অনেক ক্লায়েন্ট একই সাথে পুনরায় চেষ্টা করে।

4. পুঙ্খানুপুঙ্খভাবে লগ করুন: সম্পূর্ণ ত্রুটির প্রতিক্রিয়াটি লগ করুন, যার মধ্যে সমস্ত বিবরণ, বিশেষ করে অনুরোধ আইডি অন্তর্ভুক্ত থাকবে। এই তথ্য ডিবাগিংয়ের জন্য এবং প্রয়োজনে গুগল সাপোর্টে সমস্যা জানানোর জন্য অপরিহার্য।

5. ব্যবহারকারীকে মতামত দিন: নির্দিষ্ট GoogleAdsError কোড এবং বার্তার উপর ভিত্তি করে আপনার অ্যাপ্লিকেশনের ব্যবহারকারীদের স্পষ্ট এবং সহায়ক মতামত দিন। উদাহরণস্বরূপ, শুধু "একটি ত্রুটি ঘটেছে" বলার পরিবর্তে, আপনি বলতে পারেন "ক্যাম্পেইনের নাম আবশ্যক" অথবা "প্রদত্ত অ্যাড গ্রুপ আইডিটি খুঁজে পাওয়া যায়নি।"

এই নির্দেশিকাগুলো অনুসরণ করে, আপনি গুগল অ্যাডস এপিআই থেকে আসা ত্রুটিগুলো কার্যকরভাবে নির্ণয় ও সমাধান করতে পারবেন, যার ফলে আরও স্থিতিশীল এবং ব্যবহারকারী-বান্ধব অ্যাপ্লিকেশন তৈরি হবে।