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

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

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

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

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

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

এই কোডগুলি সম্পর্কে আরও তথ্যের জন্য, API ডিজাইন গাইড - ত্রুটি কোডগুলি দেখুন।

ত্রুটিগুলি পরিচালনা করুন

কোনও অনুরোধ ব্যর্থ হলে এই পদক্ষেপগুলি অনুসরণ করুন:

  1. ত্রুটির ধরণ খুঁজে পেতে ত্রুটি কোডটি পরীক্ষা করুন।

    • যদি আপনি gRPC ব্যবহার করেন, তাহলে ত্রুটি কোডটি Status এর code ক্ষেত্রে থাকে। যদি আপনি একটি ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন , তাহলে এটি একটি নির্দিষ্ট ধরণের ব্যতিক্রম ছুঁড়ে দিতে পারে যা ত্রুটি কোডের সাথে সঙ্গতিপূর্ণ। উদাহরণস্বরূপ, জাভার ক্লায়েন্ট লাইব্রেরি একটি com.google.api.gax.rpc.InvalidArgumentException ছুঁড়ে দেয় যদি ত্রুটি কোডটি INVALID_ARGUMENT হয়।
    • যদি আপনি REST ব্যবহার করেন, তাহলে ত্রুটি কোডটি error.status এ ত্রুটি প্রতিক্রিয়াতে থাকবে এবং সংশ্লিষ্ট HTTP স্থিতিটি error.code এ থাকবে।
  2. ত্রুটি কোডের জন্য স্ট্যান্ডার্ড ডিটেইল পেলোড পরীক্ষা করুন। স্ট্যান্ডার্ড ডিটেইল পেলোড হল গুগল এপিআই থেকে আসা ত্রুটির জন্য বার্তাগুলির একটি সেট । এগুলি আপনাকে একটি কাঠামোগত এবং সামঞ্জস্যপূর্ণ উপায়ে ত্রুটির বিবরণ দেয়। ডেটা ম্যানেজার এপিআই থেকে প্রতিটি ত্রুটিতে একাধিক স্ট্যান্ডার্ড ডিটেইল পেলোড বার্তা থাকতে পারে। ডেটা ম্যানেজার এপিআই ক্লায়েন্ট লাইব্রেরিতে একটি ত্রুটি থেকে স্ট্যান্ডার্ড ডিটেইল পেলোড পেতে সহায়ক পদ্ধতি রয়েছে

    ত্রুটি কোড যাই হোক না কেন, আমরা আপনাকে ErrorInfo , RequestInfo , Help , এবং LocalizedMessage পেলোডগুলি পরীক্ষা করে লগ করার পরামর্শ দিচ্ছি।

    • ErrorInfo এমন তথ্য আছে যা অন্যান্য পেলোডে নাও থাকতে পারে।
    • RequestInfo রিকোয়েস্ট আইডি আছে, যা আপনার যদি সাপোর্টের সাথে যোগাযোগ করার প্রয়োজন হয় তাহলে সহায়ক।
    • Help এবং LocalizedMessage লিঙ্ক এবং অন্যান্য বিবরণ রয়েছে যা আপনাকে ত্রুটিটি সমাধানে সহায়তা করবে।

    এছাড়াও, BadRequest , QuotaFailure , এবং RetryInfo পেলোডগুলি নির্দিষ্ট ত্রুটি কোডগুলির জন্য কার্যকর:

    • যদি স্ট্যাটাস কোডটি INVALID_ARGUMENT হয়, তাহলে কোন ক্ষেত্রগুলি ত্রুটির কারণ হয়েছে সে সম্পর্কে তথ্যের জন্য BadRequest পেলোডটি পরীক্ষা করুন।
    • যদি স্ট্যাটাস কোডটি RESOURCE_EXHAUSTED হয়, তাহলে কোটা তথ্য এবং পুনরায় চেষ্টা বিলম্বের সুপারিশের জন্য QuotaFailure এবং RetryInfo পেলোডগুলি পরীক্ষা করুন।

স্ট্যান্ডার্ড ডিটেইল পেলোড

ডেটা ম্যানেজার API-এর জন্য সবচেয়ে সাধারণ স্ট্যান্ডার্ড ডিটেইল পেলোডগুলি হল:

BadRequest

INVALID_ARGUMENT (HTTP স্ট্যাটাস কোড 400 ) ব্যবহার করে কোনও অনুরোধ ব্যর্থ হলে BadRequest পেলোড পরীক্ষা করুন।

একটি BadRequest বার্তা দেখায় যে অনুরোধটিতে খারাপ মান সহ ফিল্ড রয়েছে, অথবা একটি প্রয়োজনীয় ফিল্ডের জন্য একটি মান অনুপস্থিত। কোন ফিল্ডগুলিতে ত্রুটি রয়েছে তা খুঁজে পেতে BadRequestfield_violations তালিকাটি পরীক্ষা করুন। প্রতিটি field_violations এন্ট্রিতে ত্রুটিটি ঠিক করতে সাহায্য করার জন্য তথ্য রয়েছে:

field

ক্যামেল কেস পাথ সিনট্যাক্স ব্যবহার করে অনুরোধে ক্ষেত্রের অবস্থান।

যদি একটি পাথ একটি তালিকার একটি আইটেমকে নির্দেশ করে (একটি repeated ক্ষেত্র), তাহলে এর সূচী তালিকার নামের পরে বর্গাকার বন্ধনীতে ( [...] ) দেখানো হবে।

উদাহরণস্বরূপ, destinations[0].operating_account.account_id হল destinations তালিকার প্রথম আইটেমের operating_account এর account_id

description

মানটি কেন ত্রুটির কারণ হয়েছে তার একটি ব্যাখ্যা।

reason

ErrorReason enum, যেমন INVALID_HEX_ENCODING অথবা INVALID_CURRENCY_CODE

BadRequest এর উদাহরণ

এখানে একটি BadRequest বার্তা সহ একটি INVALID_ARGUMENT ত্রুটির নমুনা প্রতিক্রিয়া দেওয়া হল। field_violations দেখায় যে ত্রুটিটি একটি accountId যা কোনও সংখ্যা নয়। destinations[0].login_account.account_id field মান দেখায় যে ক্ষেত্র লঙ্ঘন সহ accountId টি destinations তালিকার প্রথম আইটেমের login_account এ রয়েছে।

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "destinations[0].login_account.account_id",
            "description": "String is not a valid number.",
            "reason": "INVALID_NUMBER_FORMAT"
          }
        ]
      }
    ]
  }
}

এখানে একটি INVALID_ARGUMENT ত্রুটির আরেকটি নমুনা প্রতিক্রিয়া দেওয়া হল যেখানে একটি BadRequest বার্তা রয়েছে। এই ক্ষেত্রে, field_violations তালিকা দুটি ত্রুটি দেখায়:

  1. প্রথম event একটি মান আছে যা ইভেন্টের দ্বিতীয় ব্যবহারকারী শনাক্তকারীতে হেক্স-এনকোড করা নেই।

  2. দ্বিতীয় event একটি মান আছে যা ইভেন্টের তৃতীয় ব্যবহারকারী শনাক্তকারীতে হেক্স-এনকোড করা নেই।

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers[1]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          },
          {
            "field": "events.events[1].user_data.user_identifiers[2]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

QuotaFailure এবং RetryInfo

RESOURCE_EXHAUSTED (HTTP স্ট্যাটাস কোড 429 ) ব্যবহার করে কোনও অনুরোধ ব্যর্থ হলে QuotaFailure এবং RetryInfo পেলোডগুলি পরীক্ষা করুন।

একটি QuotaFailure বার্তা ইঙ্গিত দেয় যে হয় একটি রিসোর্স শেষ হয়ে গেছে (উদাহরণস্বরূপ, আপনি আপনার কোটা অতিক্রম করেছেন), অথবা একটি সিস্টেম ওভারলোডেড। কোন কোটা অতিক্রম করা হয়েছে তা নির্ধারণ করতে violations তালিকাটি পরীক্ষা করুন।

ত্রুটিটিতে একটি RetryInfo বার্তাও থাকতে পারে, যা অনুরোধটি পুনরায় চেষ্টা করার জন্য একটি প্রস্তাবিত retry_delay নির্দেশ করে।

RequestInfo

যখনই কোনও অনুরোধ ব্যর্থ হয় তখন RequestInfo পেলোডটি পরীক্ষা করুন। একটি RequestInfo request_id থাকে যা আপনার API অনুরোধকে অনন্যভাবে সনাক্ত করে।

{
  "@type": "type.googleapis.com/google.rpc.RequestInfo",
  "requestId": "t-4490c640-dc5d-4c28-91c1-04a1cae0f49f"
}

ত্রুটি লগ করার সময় বা সহায়তার সাথে যোগাযোগ করার সময়, সমস্যা নির্ণয়ে সহায়তা করার জন্য অনুরোধ আইডি অন্তর্ভুক্ত করতে ভুলবেন না।

ErrorInfo

অন্যান্য স্ট্যান্ডার্ড ডিটেইল পেলোডে ক্যাপচার নাও হতে পারে এমন অতিরিক্ত তথ্য পুনরুদ্ধারের জন্য ErrorInfo বার্তাটি পরীক্ষা করুন। ErrorInfo পেলোডে ত্রুটি সম্পর্কে তথ্য সহ একটি metadata মানচিত্র রয়েছে।

উদাহরণস্বরূপ, Google ক্লাউড প্রজেক্টের জন্য যেখানে ডেটা ম্যানেজার API সক্রিয় নেই, সেখানে শংসাপত্র ব্যবহার করার কারণে PERMISSION_DENIED ব্যর্থতার জন্য ErrorInfo এখানে দেওয়া হল। ErrorInfo ত্রুটি সম্পর্কে অতিরিক্ত তথ্য প্রদান করে, যেমন:

  • metadata.consumer এর অধীনে অনুরোধের সাথে সম্পর্কিত প্রকল্প।
  • পরিষেবার নাম, metadata.serviceTitle এর অধীনে।
  • metadata.activationUrl এর অধীনে, যে URLটিতে পরিষেবাটি সক্রিয় করা যেতে পারে।
{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_DISABLED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "service": "datamanager.googleapis.com",
          "containerInfo": "PROJECT_NUMBER",
          "serviceTitle": "Data Manager API",
          "activationUrl": "https://console.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

Help এবং LocalizedMessage

ডকুমেন্টেশন এবং স্থানীয়কৃত ত্রুটি বার্তাগুলির লিঙ্ক পেতে Help এবং LocalizedMessage বার্তা পেলোডগুলি পরীক্ষা করুন যা আপনাকে ত্রুটিটি বুঝতে এবং ঠিক করতে সহায়তা করবে।

উদাহরণস্বরূপ, একটি Google ক্লাউড প্রকল্পের জন্য যেখানে ডেটা ম্যানেজার API সক্ষম করা নেই, সেখানে শংসাপত্র ব্যবহার করার কারণে PERMISSION_DENIED ব্যর্থতার জন্য এখানে Help এবং LocalizedMessage দেওয়া হল। Help পেলোডটি সেই URL দেখায় যেখানে পরিষেবাটি সক্ষম করা যেতে পারে এবং LocalizedMessage এ ত্রুটির বিবরণ রয়েছে।

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry."
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [
          {
            "description": "Google developers console API activation",
            "url": "https://console.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
          }
        ]
      },
      ...
    ]
  }
}

অ্যাক্সেস ত্রুটির বিবরণ

যদি আপনি ক্লায়েন্ট লাইব্রেরিগুলির একটি ব্যবহার করেন, তাহলে স্ট্যান্ডার্ড ডিটেইল পেলোড পেতে সহায়ক পদ্ধতিগুলি ব্যবহার করুন।

.নেট

try {
    // Send API request
}
catch (Grpc.Core.RpcException rpcException)
{
    Console.WriteLine($"Exception encountered: {rpcException.Message}");
    var statusDetails =
        Google.Api.Gax.Grpc.RpcExceptionExtensions.GetAllStatusDetails(
            rpcException
        );
    foreach (var detail in statusDetails)
    {
        if (detail is Google.Rpc.BadRequest)
        {
            Google.Rpc.BadRequest badRequest = (Google.Rpc.BadRequest)detail;
            foreach (
                BadRequest.Types.FieldViolation? fieldViolation in badRequest.FieldViolations
            )
            {
                // Access attributes such as fieldViolation!.Reason and fieldViolation!.Field
            }
        }
        else if (detail is Google.Rpc.RequestInfo)
        {
            Google.Rpc.RequestInfo requestInfo = (Google.Rpc.RequestInfo)detail;
            string requestId = requestInfo.RequestId;
            // Log the requestId...
        }
        else if (detail is Google.Rpc.QuotaFailure)
        {
            Google.Rpc.QuotaFailure quotaFailure = (Google.Rpc.QuotaFailure)detail;
            foreach (
                Google.Rpc.QuotaFailure.Types.Violation violation in quotaFailure.Violations
            )
            {
                // Access attributes such as violation.Subject and violation.QuotaId
            }
        }
        else
        {
            // ...
        }
    }
}

জাভা

try {
  // Send API request
} catch (com.google.api.gax.rpc.InvalidArgumentException invalidArgumentException) {
  // Gets the standard BadRequest payload from the exception.
  BadRequest badRequest = invalidArgumentException.getErrorDetails().getBadRequest();
  for (int i = 0; i < badRequest.getFieldViolationsCount(); i++) {
    FieldViolation fieldViolation = badRequest.getFieldViolations(i);
    // Access attributes such as fieldViolation.getField() and fieldViolation.getReason()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
} catch (com.google.api.gax.rpc.QuotaFailureException quotaFailureException) {
  // Gets the standard QuotaFailure payload from the exception.
  QuotaFailure quotaFailure = quotaFailureException.getErrorDetails().getQuotaFailure();
  for (int i = 0; i < quotaFailure.getViolationsCount(); i++) {
    QuotaFailure.Violation violation = quotaFailure.getViolations(i);
    // Access attributes such as violation.getSubject() and violation.getQuotaId()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = quotaFailureException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
} catch (com.google.api.gax.rpc.ApiException apiException) {
  // Fallback exception handler for other types of ApiException.
  ...
}

ত্রুটি পরিচালনার জন্য সেরা অনুশীলন

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

ত্রুটির বিবরণ পরীক্ষা করুন
সর্বদা BadRequest এর মতো স্ট্যান্ডার্ড ডিটেইল পেলোডগুলির মধ্যে একটি খুঁজুন। প্রতিটি স্ট্যান্ডার্ড ডিটেইল পেলোডে এমন তথ্য থাকে যা আপনাকে ত্রুটির কারণ বুঝতে সাহায্য করবে।
ক্লায়েন্ট এবং সার্ভার ত্রুটির মধ্যে পার্থক্য করুন

ত্রুটিটি আপনার বাস্তবায়নের (ক্লায়েন্টের) কোনও সমস্যার কারণে হয়েছে নাকি API (সার্ভারের) কোনও সমস্যার কারণে হয়েছে তা নির্ধারণ করুন।

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

ত্রুটিটি পুনরায় চেষ্টা করা যেতে পারে কিনা তা নির্ধারণ করুন এবং পুনরায় চেষ্টা করার কৌশল ব্যবহার করুন।

  • শুধুমাত্র UNAVAILABLE , DEADLINE_EXCEEDED , INTERNAL , UNKNOWN , এবং ABORTED এর মতো ক্ষণস্থায়ী সার্ভার ত্রুটির জন্য পুনরায় চেষ্টা করুন।
  • পুনরায় চেষ্টার মধ্যে ক্রমবর্ধমান সময়কালের জন্য অপেক্ষা করার জন্য একটি সূচকীয় ব্যাকঅফ অ্যালগরিদম ব্যবহার করুন। এটি ইতিমধ্যেই চাপযুক্ত পরিষেবাকে অতিরিক্ত চাপ এড়াতে সাহায্য করে। উদাহরণস্বরূপ, 1 সেকেন্ড, তারপর 2 সেকেন্ড, তারপর 4 সেকেন্ড অপেক্ষা করুন, সর্বোচ্চ সংখ্যক পুনরায় চেষ্টা বা মোট অপেক্ষার সময় পর্যন্ত।
  • "বজ্রপাতের দল" সমস্যা প্রতিরোধ করার জন্য ব্যাকঅফ বিলম্বের সাথে অল্প পরিমাণে "জিটার" যোগ করুন যেখানে অনেক ক্লায়েন্ট একই সাথে পুনরায় চেষ্টা করে।
পুঙ্খানুপুঙ্খভাবে লগ ইন করুন

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

ব্যবহারকারীর মতামত প্রদান করুন

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

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