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

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

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

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

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

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

جدول زیر رایج‌ترین کدهایی را که ممکن است هنگام استفاده از Google Ads API با آن‌ها مواجه شوید خلاصه می‌کند:

کد gRPC	کد HTTP	نام شمارشی	شرح	راهنمایی
0	۲۰۰	OK	خطایی وجود ندارد؛ نشان‌دهنده موفقیت است.	موجود نیست
1	499	CANCELLED	عملیات لغو شد، معمولاً توسط کارخواه.	معمولاً به این معنی است که کارخواه دیگر منتظر نمانده است. زمان‌های اتمام سمت کارخواه را بررسی کنید.
2	۵۰۰	UNKNOWN	خطای ناشناخته‌ای روی داد. ممکن است جزئیات بیشتر در پیام خطا یا جزئیات باشد.	به‌عنوان خطای سرور درنظر گرفته شود. اغلب می‌توان با عقب‌نشینی دوباره امتحان کرد.
3	۴۰۰	INVALID_ARGUMENT	کارخواه متغیر مستقل نامعتبری را مشخص کرده است. این نشان‌دهنده مشکلی است که مانع از پردازش درخواست توسط میانای برنامه‌سازی کاربردی می‌شود، مانند نام منبع نادرست یا مقدار نامعتبر.	خطای کارخواه: پارامترهای درخواستتان را بازبینی کنید و مطمئن شوید که الزامات میانای برنامه‌سازی کاربردی را برآورده می‌کنند. جزئیات خطا معمولاً اطلاعاتی درباره اینکه کدام متغیر مستقل نامعتبر بوده و چرا نامعتبر بوده است ارائه می‌دهد—از این جزئیات برای رفع مشکل درخواست استفاده کنید. بدون اصلاح درخواست، دوباره امتحان نکنید.
4	504	DEADLINE_EXCEEDED	مهلت تعیین‌شده پیش‌از تکمیل عملیات منقضی شد.	خطای سرور: اغلب گذرا است. با عقب‌گرد نمایی دوباره امتحان کنید.
5	404	NOT_FOUND	برخی‌از نهادهای درخواستی، مانند پویش یا گروه آگهی، پیدا نشد.	خطای کارخواه: وجود و شناسه منابعی را که می‌خواهید به آن‌ها دسترسی داشته باشید تأیید کنید. بدون تصحیح دوباره امتحان نکنید.
6	409	ALREADY_EXISTS	موجودیتی که کارخواه تلاش کرد ایجاد کند ازقبل وجود دارد.	خطای کارخواه: از ایجاد منابع تکراری خودداری کنید. پیش‌از تلاش برای ایجاد منبع، بررسی کنید که آیا منبع وجود دارد یا نه.
7	403	PERMISSION_DENIED	فراخواننده اجازه اجرای عملیات مشخص‌شده را ندارد.	خطای کارخواه: اصالت‌سنجی، مجوز، و نقش‌های کاربر را برای حساب Google Ads بررسی کنید. بدون حل کردن مشکل اجازه‌ها، دوباره امتحان نکنید.
8	429	RESOURCE_EXHAUSTED	یا منبعی تمام شده است (برای مثال، از سهمیه‌تان فراتر رفته‌اید)، یا سیستم دچار بار اضافی شده است.	خطای کارخواه/سرور: معمولاً باید منتظر بمانید. عقب‌گرد نمایی را اجرا کنید و احتمالاً نرخ درخواست را کاهش دهید. محدودیت‌ها و سهمیه‌های میانای برنامه‌سازی کاربردی را ببینید.
9	۴۰۰	FAILED_PRECONDITION	عملیات رد شد زیرا سیستم در وضعیت لازم برای اجرای عملیات نیست. برای مثال، فیلد الزامی وجود ندارد.	خطای کارخواه: درخواست معتبر است، اما وضعیت اشتباه است. جزئیات خطا را مرور کنید تا دلیل عدم موفقیت پیش‌شرط را متوجه شوید. بدون اصلاح وضعیت، دوباره امتحان نکنید.
10	409	ABORTED	عملیات لغو شد، معمولاً به‌دلیل مشکل همزمانی مانند تداخل تراکنش.	خطای سرور: اغلب امتحان مجدد با کمی تأخیر ایمن است.
11	۴۰۰	OUT_OF_RANGE	عملیات پس‌از گستره معتبر انجام شد.	خطای کارخواه: محدوده یا نمایه را تصحیح کنید.
12	501	UNIMPLEMENTED	این عملیات توسط API اجرا نشده است یا پشتیبانی نمی‌شود.	خطای کارخواه: نسخه API و ویژگی‌های دردسترس را بررسی کنید. دوباره امتحان نکنید.
13	۵۰۰	INTERNAL	یک خطای داخلی رخ داد. این یک خطای کلی برای مشکلات سمت سرور است.	خطای سرور: معمولاً می‌توان با عقب‌نشینی نمایی دوباره امتحان کرد. اگر مشکل برطرف نشد، مشکل را گزارش کنید.
14	۵۰۳	UNAVAILABLE	این سرویس موقتاً دردسترس نیست. این وضعیت به‌احتمال زیاد گذرا است.	خطای سرور: اکیداً توصیه می‌شود با عقب‌نشینی نمایی دوباره امتحان کنید.
15	۵۰۰	DATA_LOSS	ازدست رفتن یا خراب شدن غیرقابل‌بازیابی داده‌ها.	خطای سرور: نادر. نشان‌دهنده مشکلی جدی است. دوباره امتحان نکنید. اگر مشکل برطرف نشد، مشکل را گزارش کنید.
16	401	UNAUTHENTICATED	درخواست اعتبارنامه اصالت‌سنجی معتبری ندارد.	خطای مشتری: نشان‌های اصالت‌سنجی و اطلاعات اعتباری‌تان را درستی‌سنجی کنید. بدون رفع مشکل اصالت‌سنجی، دوباره امتحان نکنید.

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

درک جزئیات خطا

فراتر از کد سطح بالا، Google Ads API اطلاعات خطای خاص‌تری را در فیلد details از شیء Status ارائه می‌دهد. این فیلد اغلب حاوی یک GoogleAdsFailure proto است که شامل فهرستی از اشیاء GoogleAdsError تکی است.

هر شیء GoogleAdsFailure شامل موارد زیر است:

• errors: فهرستی از اشیاء GoogleAdsError، که هرکدام جزئیات خطای خاصی را که رخ داده است نشان می‌دهد.
• ‫request_id: شناسه یکتا برای درخواست، مفید برای اهداف اشکال‌زدایی و پشتیبانی.

هر شیء GoogleAdsError موارد زیر را ارائه می‌دهد:

• error_code: خطای ErrorCode جزئی‌تر و مختص Google Ads API (خطاهای رایج)، مانند AuthenticationError.NOT_ADS_USER.
• message: شرحی قابل‌خواندن برای انسان از خطای خاص.
• trigger: Value که باعث بروز خطا شده است (درصورت وجود).
• location: یک ErrorLocation که توضیح می‌دهد خطا در کجای درخواست رخ داده است، ازجمله مسیرهای فیلد.
• details: ErrorDetails اضافی، مثل دلایل خطای لغو انتشار.

نمونه‌ای از جزئیات خطا

وقتی خطایی دریافت می‌کنید، کتابخانه مشتری به شما اجازه می‌دهد به این جزئیات دسترسی پیدا کنید. برای مثال، INVALID_ARGUMENT (کد ۳) ممکن است جزئیات GoogleAdsFailure مانند این داشته باشد:

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

در این مثال، باوجود INVALID_ARGUMENT سطح بالا، جزئیات GoogleAdsFailure به شما می‌گوید که فیلدهای name و description باعث بروز مشکل شده‌اند و دلیل آن چیست (به‌ترتیب REQUIRED و TOO_SHORT).

مکان‌یابی جزئیات خطا

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

فراخوانی‌های استاندارد و جاری‌سازی میانای برنامه‌سازی کاربردی

وقتی فراخوانی میانای برنامه‌سازی کاربردی بدون استفاده از شکست جزئی ناموفق باشد، ازجمله فراخوانی‌های جاری‌سازی، شیء GoogleAdsFailure به‌عنوان بخشی از فراداده‌های انتهایی در سرایندهای پاسخ gRPC برگردانده می‌شود. اگر از REST برای تماس‌های استاندارد استفاده می‌کنید، GoogleAdsFailure در پاسخ HTTP برگردانده می‌شود. کتابخانه‌های کارخواه معمولاً این را به‌عنوان استثنایی با مشخصه GoogleAdsFailure نمایش می‌دهند.

ناموفق ناقص

اگر از شکست جزئی استفاده می‌کنید، خطاهای مربوط به عملیات ناموفق در فیلد partial_failure_error پاسخ برگردانده می‌شوند، نه در سرایندهای پاسخ. در این مورد، GoogleAdsFailure در شیء google.rpc.Status در پاسخ جاسازی شده است.

مشاغل دسته‌ای

برای پردازش دسته‌ای، خطاهای مربوط به عملیات‌های تکی را می‌توان با فراخوانی BatchJobService.ListBatchJobResults پس‌از تکمیل کار پیدا کرد. هر نتیجه عملیات شامل فیلد status خواهد بود که اگر عملیات ناموفق باشد، جزئیات خطا را دربردارد.

شناسه درخواست

request-id رشته‌ای یکتا است که درخواست میانای برنامه‌سازی کاربردی شما را شناسایی می‌کند و برای عیب‌یابی ضروری است.

می‌توانید request-id را در جاهای مختلفی پیدا کنید:

• GoogleAdsFailure: اگر فراخوانی میانای برنامه‌سازی کاربردی ناموفق باشد و GoogleAdsFailure برگردانده شود، حاوی request_id خواهد بود.
• فراداده‌های دنباله‌دار: برای درخواست‌های موفق و ناموفق، request-id در فراداده‌های دنباله‌دار پاسخ gRPC دردسترس است.
• سرایندهای پاسخ: برای درخواست‌های موفق و ناموفق، request-id در سرایندهای پاسخ gRPC و HTTP نیز دردسترس است، به‌استثنای درخواست‌های جاری‌سازی موفق.
• SearchGoogleAdsStreamResponse: برای درخواست‌های جاری‌سازی، هر پیام SearchGoogleAdsStreamResponse حاوی یک فیلد request_id است.

هنگام ثبت خطاها یا تماس با پشتیبانی، حتماً request-id را اضافه کنید تا به تشخیص مشکلات کمک کند.

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

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

1. بررسی جزئیات خطا: همیشه فیلد details شیء Status را تجزیه کنید، به‌ویژه به‌دنبال GoogleAdsFailure بگردید. error_code، message، و location دانه‌ای در GoogleAdsError کاربردی‌ترین اطلاعات را برای اشکال‌زدایی و بازخورد کاربر ارائه می‌دهند.

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

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

3. پیاده‌سازی استراتژی تکرار:

   • زمان امتحان مجدد: فقط برای خطاهای گذرا در سرور، مانند UNAVAILABLE، DEADLINE_EXCEEDED، INTERNAL، UNKNOWN، و ABORTED، دوباره امتحان کنید.
   • عقب‌گرد نمایی: از الگوریتم عقب‌گرد نمایی برای انتظار در دوره‌های افزایشی بین تلاش‌های مجدد استفاده کنید. این کار کمک می‌کند تا از تحت فشار قرار گرفتن سرویسی که درحال‌حاضر تحت فشار است جلوگیری شود. برای مثال، ۱ ثانیه، سپس ۲ ثانیه، سپس ۴ ثانیه صبر کنید، و این کار را تا رسیدن به حداکثر تعداد تلاش مجدد یا کل زمان انتظار ادامه دهید.
   • لرزش: مقدار تصادفی کوچکی از «لرزش» را به تأخیرهای عقب‌نشینی اضافه کنید تا از مشکل «گله رعدآسا» که در آن بسیاری از مشتریان به‌طور هم‌زمان دوباره امتحان می‌کنند، جلوگیری شود.

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

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

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