آشنایی با خطاهای میانای برنامه‌سازی کاربردی

این راهنما توضیح می‌دهد که «میانای برنامه‌سازی کاربردی مدیر داده» چگونه خطاها را مدیریت و اعلام می‌کند. درک ساختار و معنای خطاهای API برای ساختن برنامه‌های قدرتمندی که می‌توانند به‌خوبی از عهده مشکلات برآیند، از ورودی نامعتبر گرفته تا عدم دسترسی موقت به سرویس، بسیار مهم است.

«میانای برنامه‌سازی کاربردی مدیر داده» از مدل خطای استاندارد Google API پیروی می‌کند که براساس کدهای وضعیت gRPC است. هر پاسخ API که منجر به خطا می‌شود شامل یک شیء Status با موارد زیر است:

• کد خطای عددی.
• پیام خطا.
• اختیاری، جزئیات تکمیلی خطا.

کدهای خطای متعارف

Data Manager API از مجموعه‌ای از کدهای خطای متعارف تعریف‌شده توسط gRPC و HTTP استفاده می‌کند. این کدها نشانگر سطح بالایی از نوع خطا هستند. همیشه باید ابتدا این کد را بررسی کنید تا ماهیت اساسی مشکل را درک کنید.

برای جزئیات بیشتر درباره این کدها، راهنمای طراحی میانای برنامه‌سازی کاربردی - کدهای خطا را ببینید.

مدل شکست سریع

«میانای برنامه‌سازی کاربردی مدیر داده» از مدل «سریع شکست‌خورده» استفاده می‌کند. اگر درخواستی حاوی خطاهای ساختاری باشد یا اگر هریک از سوابق برای فیلد الزامی معتبر نباشد، کل درخواست ناموفق خواهد بود و میانای برنامه‌سازی کاربردی هیچ‌یک از داده‌های آن درخواست را پردازش نخواهد کرد.

نکته کلیدی: مدل «شکست سریع» مجموعه محدودی از بررسی‌های اعتبارسنجی را برای شناسایی مشکلات اساسی که به‌طور کامل از پردازش بیشتر داده‌ها جلوگیری می‌کنند، انجام می‌دهد. عدم موفقیت در اعتبارسنجی فیلدهای اختیاری باعث عدم موفقیت درخواست نمی‌شود. «میانای برنامه‌سازی کاربردی مدیر داده» همچنین اعتبارسنجی‌های پیچیده‌تری را به‌صورت ناهم‌زمان درطول پردازش انجام می‌دهد و هرگونه هشدار یا خطا را در تشخیص خرابی گزارش می‌کند.

مقایسه با مدل خرابی جزئی

مدل سریع‌شکست با مدل شکست جزئی در برخی دیگر از میاناهای برنامه‌سازی کاربردی Google، مانند میانای برنامه‌سازی کاربردی Google Ads و میانای برنامه‌سازی کاربردی Campaign Manager 360، متفاوت است. در مدل خرابی جزئی، درخواست حتی اگر برخی‌از سوابق خطا داشته باشند موفقیت‌آمیز است و پاسخ حاوی جزئیات خطای سوابق ناموفق است.

اگرچه خرابی جزئی می‌تواند راحت باشد، اما خطرات قابل‌توجهی دارد زیرا مدل خرابی جزئی به‌طور پیش‌فعال به شما درباره خطاها هشدار نمی‌دهد—شما باید به‌طور صریح خطاها را در هر پاسخ بررسی کنید. این می‌تواند مشکلات مهم را پنهان کند زیرا درخواست حتی اگر «میانای برنامه‌سازی کاربردی» بسیاری یا حتی همه گزارش‌های درخواست را رد کند، موفقیت‌آمیز خواهد بود. اگر بخش قابل‌توجهی از گزارش‌های موجود در یک درخواست خطا داشته باشد اما پاسخ را بررسی نکنید، ممکن است اصلاً متوجه مشکلات گسترده داده‌هایتان نشوید و این مشکلات را فقط چند روز یا چند هفته بعد، وقتی نتایج تجمعی با انتظاراتتان مطابقت ندارد، کشف کنید.

مدل سریع-شکست با هشدار دادن فوری درباره مشکلات داده‌ها یا یکپارچه‌سازی، از این مشکلات جلوگیری می‌کند تا بتوانید اقدام مناسب را انجام دهید.

بررسی خطاهای سریع با validateOnly

بیشتر درخواست‌های انتقال و برداشتن محتوا از فیلد validateOnly پشتیبانی می‌کنند. وقتی validateOnly را روی true تنظیم می‌کنید، Data Manager API همان بررسی‌های اعتبارسنجی پایه را که برای درخواست عادی انجام می‌دهد اجرا می‌کند، اما هیچ داده‌ای را انتقال یا حذف نمی‌کند.

• اگر درخواست خطا داشته باشد، با همان پاسخ خطایی که از درخواست معمولی دریافت می‌کنید، ناموفق خواهد بود.
• اگر درخواست از اعتبارسنجی عبور کند، موفقیت‌آمیز خواهد بود. پاسخ شامل هرگونه fieldWarnings برای فیلدهای اختیاری است، درست مانند یک درخواست معمولی.

از validateOnly برای موارد زیر استفاده کنید:

• ادغام جدید یا به‌روزشده را بدون تأثیر گذاشتن روی داده‌های زنده آزمایش کنید.
• پیش‌از ارسال مجدد درخواست، تأیید کنید که اصلاح خطا را برطرف می‌کند.

توجه: درخواست فقط اعتبارسنجی موفق تأیید می‌کند که درخواست از بررسی‌های اعتبارسنجی اولیه عبور کرده است. به شما نمی‌گوید که آیا درطول پردازش ناهمزمان خطایی رخ خواهد داد یا نه. این خطاها پس‌از انتقال داده‌ها در تشخیص خرابی گزارش می‌شوند. نمی‌توانید تشخیص خرابی را برای درخواستی که validateOnly آن روی true تنظیم شده است بازیابی کنید.

مدیریت خطاها

وقتی درخواستی ناموفق است، این مراحل را دنبال کنید:

1. برای یافتن نوع خطا، کد خطا را بررسی کنید.

   • اگر از gRPC استفاده می‌کنید، کد خطا در فیلد code از Status قرار دارد. اگر از کتابخانه مشتری استفاده می‌کنید، ممکن است نوع خاصی از استثنا را که با کد خطا مطابقت دارد ایجاد کند. برای مثال، کتابخانه مشتری برای Java درصورت com.google.api.gax.rpc.InvalidArgumentException بودن کد خطا، INVALID_ARGUMENT را پرتاب می‌کند.
   • اگر از REST استفاده می‌کنید، کد خطا در پاسخ خطا در error.status است، و وضعیت HTTP مربوطه در error.code است.
   مهم: Data Manager API از مدل سریع شکست استفاده می‌کند. اگر درخواستی ناموفق باشد، هیچ‌یک از داده‌ها پردازش نمی‌شود. خطا را برطرف کنید و کل درخواست را دوباره ارسال کنید.

2. بار استاندارد جزئیات را برای کد خطا بررسی کنید. باربرهای جزئیات استاندارد مجموعه‌ای از پیام‌های مربوط به خطاهای میاناهای برنامه‌سازی کاربردی Google هستند. این کدها جزئیات خطا را به‌شیوه‌ای ساختارمند و یکپارچه به شما ارائه می‌دهند. هر خطا از «میانای برنامه‌سازی کاربردی مدیر داده» ممکن است چند پیام بار استاندارد جزئیات داشته باشد. کتابخانه‌های کارخواه «میانای برنامه‌سازی کاربردی مدیر داده‌ها» روش‌های کمکی برای دریافت محموله‌های جزئیات استاندارد از خطا دارند.

   صرف‌نظر از کد خطا، توصیه می‌کنیم که ErrorInfo، RequestInfo، Help، و LocalizedMessage بارها را بررسی و ثبت کنید.

   • ‫ErrorInfo اطلاعاتی دارد که ممکن است در محموله‌های دیگر نباشد.
   • RequestInfo شناسه درخواست را دارد که درصورت نیاز به تماس با پشتیبانی مفید است.
   • ‫Help و LocalizedMessage حاوی پیوندها و جزئیات دیگری است که به شما کمک می‌کند خطا را برطرف کنید.

   علاوه‌براین، محتوای BadRequest برای خطاهای INVALID_ARGUMENT مفید است زیرا اطلاعاتی درباره فیلدهایی که باعث خطا شده‌اند ارائه می‌دهد.

هشدارهای انتقال داده

«میانای برنامه‌سازی کاربردی مدیر داده» تا حد امکان درخواست انتقال داده را می‌پذیرد. اگر داده‌هایی را که لازم نیست اضافه کنید، خطاهای اعتبارسنجی برای آن فیلدها باعث نمی‌شود درخواست ناموفق باشد. برای مثال، اگر شناسه محصول فروشنده برای یکی از محصولات سبد خرید وجود نداشته باشد، «میانای برنامه‌سازی کاربردی» بقیه درخواست را پردازش می‌کند و هشدار برمی‌گرداند.

پاسخ موفقیت‌آمیز انتقال داده (کد وضعیت HTTP 200) شامل این هشدارها در فهرست fieldWarnings است. هر ورودی یک شیء FieldWarning با فیلدهای زیر است:

field

مکان فیلد در درخواست، در نحو مسیر نگارش ماری.

اگر مسیری به موردی در فهرست (فیلد repeated) اشاره کند، نمایه‌اش در قلاب‌های مربع ([...]) پس‌از نام فهرست نشان داده می‌شود.

برای مثال، events.events[0].cart_data.items[0].merchant_product_id هشداری مرتبط با اولین مورد در داده‌های سبد خرید اولین رویداد در درخواست را شناسایی می‌کند.

description

توضیحی درباره اینکه چرا مقدار ارائه‌شده باعث ایجاد هشدار شده است.

reason

مقدار شمارشی WarningReason که نوع هشدار را مشخص می‌کند.

مهم: هشدارهای انتقال داده باعث ناموفق شدن درخواست نمی‌شوند. باید پاسخ fieldWarnings را بررسی کنید تا متوجه شوید همه داده‌هایی که ارسال کرده‌اید پذیرفته شده است یا نه.

مثال با FieldWarning

در اینجا نمونه‌ای از پاسخ برای درخواست موفق انتقال داده آورده شده است که به‌دلیل اینکه شناسه محصول فروشنده برای یکی از موارد سبد خرید وجود ندارد، حاوی هشدار است.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a",
  "fieldWarnings": [
    {
      "field": "events.events[0].cart_data.items[0].merchant_product_id",
      "description": "The merchant product ID is missing in the cart item.",
      "reason": "WARNING_REASON_CART_DATA_ITEM_MERCHANT_PRODUCT_ID_MISSING"
    }
  ]
}

پیکربندی‌های جزئیات استاندارد

رایج‌ترین محموله‌های جزئیات استاندارد برای Data Manager API عبارت‌اند از:

• BadRequest
• RequestInfo
• ErrorInfo
• Help و LocalizedMessage

BadRequest

وقتی درخواستی با INVALID_ARGUMENT (کد وضعیت HTTP 400) ناموفق بود، وجود بار BadRequest را بررسی کنید.

پیام BadRequest نشان می‌دهد که درخواست دارای فیلدهایی با مقادیر بد بوده است، یا مقدار فیلد الزامی را نداشته است. برای پیدا کردن فیلدهایی که خطا دارند، فهرست field_violations را در BadRequest بررسی کنید. هر ورودی field_violations اطلاعاتی دارد که به شما کمک می‌کند خطا را برطرف کنید:

field

مکان فیلد در درخواست، در نحو مسیر نگارش ماری.

اگر مسیری به موردی در فهرست (فیلد repeated) اشاره کند، نمایه‌اش در قلاب‌های مربع ([...]) پس‌از نام فهرست نشان داده می‌شود.

برای مثال، destinations[0].operating_account.account_id account_id در operating_account اولین مورد در فهرست destinations است.

description

توضیحی درباره اینکه چرا مقدار باعث بروز خطا شده است.

reason

عدد ثابت ErrorReason، مثل INVALID_HEX_ENCODING یا INVALID_CURRENCY_CODE.

مثال‌های BadRequest

در اینجا نمونه‌ای از پاسخ برای خطای INVALID_ARGUMENT با پیام BadRequest ارائه شده است. ‫field_violations نشان می‌دهد که خطا accountId است و عدد نیست. مقدار field destinations[0].login_account.account_id نشان می‌دهد accountId با نقض فیلد در login_account اولین مورد در فهرست destinations است.

{
  "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"
          }
        ]
      }
    ]
  }
}

RequestInfo

هرگاه درخواستی ناموفق بود، بار RequestInfo را بررسی کنید. RequestInfo شامل request_id است که درخواست API شما را به‌طور یکتا شناسایی می‌کند.

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

هنگام ثبت خطاها یا تماس با پشتیبانی، حتماً شناسه درخواست را ذکر کنید تا در تشخیص مشکلات کمک کند.

ErrorInfo

برای بازیابی اطلاعات تکمیلی که ممکن است در دیگر محموله‌های جزئیات استاندارد ثبت نشده باشد، پیام ErrorInfo را بررسی کنید. ErrorInfo بار حاوی نقشه metadata با اطلاعات مربوط به خطا است.

برای مثال، در اینجا ErrorInfo برای خطای PERMISSION_DENIED ناشی از استفاده از اطلاعات اعتباری برای پروژه Google Cloud که Data Manager API در آن فعال نیست آورده شده است. ‫ErrorInfo اطلاعات بیشتری درباره خطا ارائه می‌دهد، ازجمله:

• پروژه مرتبط با درخواست، در metadata.consumer.
• نام سرویس، تحت metadata.serviceTitle.
• نشانی وبی که در آن سرویس را می‌توان در metadata.activationUrl فعال کرد.

{
  "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.cloud.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.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

خطاهای سهمیه و حد نرخ

وقتی درخواستی از حد پروژه فراتر می‌رود، API RESOURCE_EXHAUSTED خطایی (کد وضعیت HTTP 429) برمی‌گرداند. بار ErrorInfo جزئیاتی درباره اینکه کدام حد در نقشه metadata آن فراتر رفته است ارائه می‌دهد:

consumer

پروژه Google Cloud مرتبط با درخواست، با قالب projects/PROJECT_NUMBER.

quota_limit

نام حد سهمیه‌ای که از آن فراتر رفته‌اید، برای مثال IngestionMutateRequestsPerMinutePerProject یا IngestionMutateRequestsPerDayPerProject. می‌توانید از این مقدار برای تعیین اینکه آیا برنامه از حد مجاز در هر دقیقه یا حد مجاز روزانه فراتر رفته است یا نه استفاده کنید. برای فهرست کامل نام‌های محدودیت، محدودیت‌های پروژه را ببینید.

quota_location

مکان اعمال سهمیه. برای Data Manager API، این مقدار همیشه global است.

quota_metric

سنجه مرتبط با محدودیت، مثل datamanager.googleapis.com/ingestion_mutate_requests.

service

نام سرویس، datamanager.googleapis.com.

در اینجا نمونه‌ای از پاسخ خطای RESOURCE_EXHAUSTED زمانی که درخواست از حد مجاز در دقیقه برای درخواست‌های تغییر داده‌های ورودی فراتر می‌رود آورده شده است:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Ingestion mutate requests' and limit 'Ingestion mutate requests per minute' of service 'datamanager.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RATE_LIMIT_EXCEEDED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "quota_limit": "IngestionMutateRequestsPerMinutePerProject",
          "quota_location": "global",
          "quota_metric": "datamanager.googleapis.com/ingestion_mutate_requests",
          "service": "datamanager.googleapis.com"
        }
      }
    ]
  }
}

‫Help و LocalizedMessage

برای دریافت پیوند به اسناد و پیام‌های خطای بومی‌سازی‌شده که به شما کمک می‌کند خطا را درک و رفع کنید، باربرهای Help و LocalizedMessage را بررسی کنید.

برای مثال، در اینجا Help و LocalizedMessage برای PERMISSION_DENIED خطایی که در اثر استفاده از اعتبارنامه برای پروژه Google Cloud ایجاد شده است که در آن Data Manager API فعال نیست، نشان داده شده است. بار Help نشانی وبی را نشان می‌دهد که در آن سرویس می‌تواند فعال شود، و 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.cloud.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.cloud.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 API Console API activation",
            "url": "https://console.cloud.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.ErrorInfo)
        {
            Google.Rpc.ErrorInfo errorInfo = (Google.Rpc.ErrorInfo)detail;
            // Log the errorInfo.Reason and errorInfo.Metadata...

            // If handling a rate limit error, check the exceeded quota limit:
            if (errorInfo.Reason == "RATE_LIMIT_EXCEEDED" &&
                errorInfo.Metadata.TryGetValue("quota_limit", out string quotaLimit))
            {
                // Inspect quotaLimit to determine whether it is a per-minute
                // or daily limit (for example,
                // IngestionMutateRequestsPerMinutePerProject).
            }

            // Log the details in the 'Metadata' map...
            foreach (
                KeyValuePair<String, String> metadataEntry in errorInfo.Metadata
            )
            {
                // Log the metadataEntry.Key and metadataEntry.Value...
            }
        }
        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.ApiException apiException) {
  // Fallback exception handler for other types of ApiException.

  // Gets the standard ErrorInfo payload from the exception.
  ErrorInfo errorInfo = apiException.getErrorDetails().getErrorInfo();
  // Log the 'reason' and 'domain'...

  // If handling a rate limit error, check the exceeded quota limit:
  if (errorInfo != null && "RATE_LIMIT_EXCEEDED".equals(errorInfo.getReason())) {
    String quotaLimit = errorInfo.getMetadataMap().get("quota_limit");
    // Inspect quotaLimit to determine whether it is a per-minute
    // or daily limit (for example,
    // IngestionMutateRequestsPerMinutePerProject).
  }

  // Log the details in the 'metadata' map...
  for (Entry<String, String> metadataEntry : errorInfo.getMetadataMap().entrySet()) {
    // Log the metadataEntry key and value...
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = apiException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

روال‌های مطلوب برای مدیریت خطا

برای ساختن برنامه‌های انعطاف‌پذیر، روال‌های مطلوب زیر را پیاده‌سازی کنید.

پیش‌از ارسال، درستی‌سنجی کنید

وقتی یک یکپارچه‌سازی می‌سازید یا تغییر می‌دهید، درخواست‌هایی با validateOnly تنظیم‌شده روی true ارسال کنید تا خطاهای سریع-شکست را قبل‌از انتقال داده‌ها دریافت کنید.

بررسی جزئیات خطا

همیشه به‌دنبال یکی از پیام‌های استاندارد جزئیات بار مانند BadRequest باشید. هر محتوای جزئیات استاندارد حاوی اطلاعاتی است که به شما کمک می‌کند علت خطا را درک کنید.

تمایز بین خطاهای کارخواه و سرور

تعیین کنید که آیا خطا ناشی از مشکل در پیاده‌سازی شما (کارخواه) است یا مشکل در «میانای برنامه‌سازی کاربردی» (سرور).

• خطاهای کارخواه: کدهایی مثل INVALID_ARGUMENT، NOT_FOUND، PERMISSION_DENIED، FAILED_PRECONDITION، UNAUTHENTICATED. این موارد نیازمند تغییر در درخواست یا وضعیت/اطلاعات اعتباری برنامه شما است. بدون رسیدگی به مشکل، درخواست را دوباره امتحان نکنید.
• خطاهای سرور: کدهایی مثل UNAVAILABLE، INTERNAL، DEADLINE_EXCEEDED، UNKNOWN. این خطاها نشان‌دهنده مشکل موقتی در سرویس API است.

پیاده‌سازی استراتژی تلاش مجدد

تعیین کنید که آیا خطا می‌تواند دوباره امتحان شود یا نه، و از استراتژی تلاش مجدد استفاده کنید.

• فقط برای خطاهای سرور گذرا (مثل UNAVAILABLE، DEADLINE_EXCEEDED، INTERNAL، UNKNOWN، و ABORTED) و محدودیت‌های نرخ در دقیقه (RESOURCE_EXHAUSTED با RATE_LIMIT_EXCEEDED) دوباره امتحان کنید.

• برای حد نرخ، quota_limit را در ErrorInfo بازرسی کنید:

  • اگر حد مجاز در دقیقه است (مثلاً IngestionMutateRequestsPerMinutePerProject)، درخواست‌ها را موقتاً متوقف کنید و بااستفاده از پس‌گیری نمایی با لرزش دوباره امتحان کنید.

  • اگر حد روزانه است (مثل IngestionMutateRequestsPerDayPerProject)، بلافاصله دوباره امتحان نکنید. پردازش را تا زمانی که سهمیه روزانه در نیمه‌شب به وقت اقیانوس آرام بازنشانی شود متوقف کنید.

• از الگوریتم عقب‌گرد نمایی برای انتظار کشیدن برای دوره‌های افزایش بین تلاش‌های مجدد استفاده کنید. این کار به جلوگیری از فشار بیش‌ازحد بر سرویس‌هایی که ازقبل تحت فشار هستند کمک می‌کند. برای مثال، ۱ ثانیه، سپس ۲ ثانیه، سپس ۴ ثانیه صبر کنید و این روند را تا حداکثر تعداد تلاش مجدد یا کل زمان انتظار ادامه دهید.

• مقدار کمی «لرزش» تصادفی به تأخیرهای بازگشت اضافه کنید تا از مشکل «گله پرخروش» که در آن بسیاری از مشتریان به‌طور هم‌زمان دوباره تلاش می‌کنند جلوگیری شود.

گزارش کامل

پاسخ خطای کامل، ازجمله همه محموله‌های جزئیات استاندارد، به‌ویژه شناسه درخواست را ثبت کنید. این اطلاعات برای اشکال‌زدایی و گزارش مشکلات به پشتیبانی Google درصورت نیاز ضروری است.

ارائه بازخورد کاربر

براساس کدها و پیام‌های موجود در بار داده‌های جزئیات استاندارد، بازخوردی واضح و مفید به کاربران برنامه‌تان ارائه دهید. برای مثال، به‌جای اینکه فقط بگویید «خطایی روی داد»، می‌توانید بگویید «شناسه تراکنش وجود نداشت» یا «شناسه حساب مقصد پیدا نشد».

با پیروی از این دستورالعمل‌ها، می‌توانید خطاهای برگشتی از «میانای برنامه‌سازی کاربردی مدیر داده» را به‌طور مؤثر تشخیص دهید و مدیریت کنید، که منجر به برنامه‌های پایدارتر و کاربرپسندتر می‌شود.