مدیریت پاسخ‌های خطا

این راهنما نحوه مدیریت خطاهایی که توسط API فروشنده (Merchant API) برگردانده می‌شوند را توضیح می‌دهد. درک ساختار پاسخ خطا و پایداری آن برای ایجاد یکپارچه‌سازی‌های قوی که می‌توانند به طور خودکار از خرابی‌ها بازیابی شوند یا بازخورد معناداری به کاربران ارائه دهند، بسیار مهم است.

نمای کلی

وقتی درخواست یک Merchant API با شکست مواجه می‌شود، API یک کد وضعیت HTTP استاندارد ( 4xx یا 5xx ) و یک بدنه پاسخ JSON حاوی جزئیات مربوط به خطا را برمی‌گرداند. Merchant API از استاندارد AIP-193 برای جزئیات خطا پیروی می‌کند و اطلاعات قابل خواندن توسط ماشین را ارائه می‌دهد که به برنامه شما اجازه می‌دهد سناریوهای خطای خاص را به صورت برنامه‌نویسی مدیریت کند.

ساختار پاسخ خطا

پاسخ خطا یک شیء JSON است که شامل فیلدهای استانداردی مانند code ، message و status است. نکته مهم این است که شامل یک آرایه details نیز می‌شود. برای مدیریت خطاها به صورت برنامه‌نویسی، باید به دنبال شیء در details باشید که @type به type.googleapis.com/google.rpc.ErrorInfo باشد.

این شیء ErrorInfo داده‌های پایدار و ساختاریافته‌ای در مورد خطا ارائه می‌دهد:

  • دامنه : گروه‌بندی منطقی خطا، معمولاً merchantapi.googleapis.com .
  • فراداده : نقشه‌ای از مقادیر پویای مربوط به خطا. این شامل موارد زیر است:
    • دلیل : یک شناسه‌ی مشخص و پایدار برای خطای دقیق (مثلاً INVALID_NAME_PART_NOT_NUMBER ، PERMISSION_DENIED_ACCOUNTS ). این فیلد همیشه وجود دارد. از این فیلد برای مدیریت دقیق خطا در منطق برنامه‌ی خود استفاده کنید.
    • HELP_CENTER_LINK : توضیحات و دستورالعمل‌های بیشتری برای رفع مشکل ارائه می‌دهد. این فیلد برای همه خطاها موجود نیست، اما ما قصد داریم به مرور زمان پوشش آن را برای خطاهایی که ممکن است به توضیحات بیشتری نیاز داشته باشند، گسترش دهیم.
    • سایر فیلدهای پویا : کلیدهای دیگری که زمینه را فراهم می‌کنند، مانند نام فیلد نامعتبر ( FIELD_LOCATION ) یا مقداری که باعث خطا شده است ( FIELD_VALUE ).

نمونه پاسخ‌های خطا

JSON زیر ساختار خطای API فروشنده را نشان می‌دهد که در آن نام منبع نادرست نوشته شده است.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

در اینجا مثالی از خطای احراز هویت آورده شده است:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

پایداری میدان‌های خطا

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

  • میدان‌های پایدار:

  • details.metadata.REASON : شناسه‌ی خطای خاص. شما باید برای منطق جریان کنترل برنامه‌ی خود به این فیلد تکیه کنید.

    • کلیدهای details.metadata : کلیدهای درون نقشه‌ی فراداده (مثلاً FIELD_LOCATION ، ACCOUNT_IDS ) پایدار هستند.
    • code : کد وضعیت HTTP سطح بالا (مثلاً 400 ، 401 ، 503 ) پایدار است.

  • فیلدهای ناپایدار:

    • message : پیام خطای قابل خواندن توسط انسان پایدار نیست . این پیام فقط برای اشکال‌زدایی توسعه‌دهندگان در نظر گرفته شده است. کدی ننویسید که محتوای متنی فیلد message را تجزیه یا به آن متکی باشد ، زیرا ممکن است بدون اطلاع قبلی برای بهبود وضوح یا اضافه کردن زمینه تغییر کند.
    • مقادیر details.metadata : در حالی که کلیدها پایدار هستند، مقادیر کلیدهای اطلاعاتی ممکن است تغییر کنند. برای مثال، اگر یک کلید HELP_CENTER_LINK ارائه شود، URL خاصی که به آن اشاره می‌کند ممکن است بدون اطلاع قبلی به یک صفحه مستندات جدیدتر به‌روزرسانی شود. با این حال، همانطور که قبلاً ذکر شد، مقدار details.metadata.REASON پایدار است.

بهترین شیوه‌ها

برای اطمینان از اینکه ادغام شما خطاها را به خوبی مدیریت می‌کند، از این بهترین شیوه‌ها پیروی کنید.

برای منطق details.metadata.REASON استفاده کنید

همیشه از REASON خاص درون نقشه metadata برای تعیین علت خطا استفاده کنید. فقط به کد وضعیت HTTP تکیه نکنید، زیرا ممکن است چندین خطا کد وضعیت یکسانی داشته باشند.

پیام خطا را تجزیه و تحلیل نکنید

همانطور که در بخش پایداری اشاره شد، فیلد message برای استفاده انسانی است. اگر به اطلاعات پویا نیاز دارید (مانند اینکه کدام فیلد نامعتبر بوده است)، آن را با استفاده از کلیدهای پایداری مانند FIELD_LOCATION و VARIABLE_NAME از نقشه metadata استخراج کنید.

پیاده سازی پسروی نمایی

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

  • quota/request_rate_too_high : این خطا نشان می‌دهد که شما از سهمیه دقیقه‌ای خود برای گروه سهمیه خاص فراتر رفته‌اید. نرخ درخواست خود را کاهش دهید.
  • internal_error : این خطاها معمولاً گذرا هستند. با backoff نمایی دوباره امتحان کنید. توجه: اگر internal_error پس از چندین تلاش مجدد با backoff همچنان پابرجا بود، به نحوه تماس با پشتیبانی API فروشنده مراجعه کنید.

نحوه تماس با پشتیبانی API فروشگاه

اگر نیاز دارید در مورد یک خطای خاص با پشتیبانی Merchant API تماس بگیرید، اطلاعات زیر را در درخواست خود ارائه دهید:

  1. پاسخ خطای دقیق دریافتی
  2. نام متد API
  3. بار درخواست
  4. مهرهای زمانی یا محدوده زمانی که در طی آن متد فراخوانی شده و خطاها دریافت شده‌اند