انواع خطا

ما خطاها را به دسته‌های کلی زیر طبقه‌بندی کرده‌ایم:

  • احراز هویت
  • خطاهایی که می‌توان دوباره امتحان کرد
  • اعتبارسنجی
  • مرتبط با همگام‌سازی

اگرچه این دسته‌ها شامل تمام خطاهای ممکن نمی‌شوند و برخی ممکن است در بیش از یک دسته قرار گیرند، با این وجود می‌توانند به عنوان نقطه شروعی برای ساختاردهی مدیریت خطا در برنامه شما باشند. برای جزئیات بیشتر در مورد خطاهای خاص، به منابع زیر مراجعه کنید:

  • خطاهای رایج جزئیات بیشتری در مورد یک خطای خاص ارائه می‌دهند.
  • google.rpc.Status جزئیاتی در مورد مدل خطای منطقی مورد استفاده توسط API ارائه می‌دهد.
  • کدهای خطای متعارف، فهرستی از کدهای خطای متعارف تعریف‌شده توسط gRPC و HTTP در چارچوب API تبلیغات گوگل ارائه می‌دهد و توضیحی در مورد آنها ارائه می‌دهد.

خطاهای احراز هویت

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

رایج‌ترین دلیل بروز خطای احراز هویت ناشی از عواملی خارج از کنترل شما این است که کاربر احراز هویت شده، مجوزی را که به برنامه شما برای اقدام از طرف خود داده است، لغو کرده است. به عنوان مثال، اگر برنامه شما حساب‌های Google Ads جداگانه‌ای را برای کلاینت‌های مستقل مدیریت می‌کند و هنگام مدیریت حساب هر کلاینت، به طور جداگانه برای هر کلاینت احراز هویت می‌شود، یک کلاینت می‌تواند دسترسی برنامه شما را در هر زمانی لغو کند. بسته به زمان لغو دسترسی شما، API ممکن است مستقیماً خطای AuthenticationError.OAUTH_TOKEN_REVOKED را برگرداند، یا اشیاء اعتبارنامه داخلی در کتابخانه‌های کلاینت ممکن است یک استثنای token revoked ایجاد کنند. در هر دو حالت، اگر برنامه شما رابط کاربری برای کلاینت‌های شما دارد، می‌تواند از آنها بخواهد که جریان OAuth2 را مجدداً راه‌اندازی کنند تا مجوز برنامه شما برای اقدام از طرف آنها دوباره برقرار شود.

به طور مشابه، اگر پروژه Google Cloud شما فقط سطح دسترسی Test داشته باشد و سعی کند درخواست‌هایی را علیه یک حساب کاربری در حال تولید (غیر آزمایشی) ارسال کند، API یک AuthorizationError برمی‌گرداند که مقدار enum آن به نسخه API بستگی دارد:

خطاهایی که می‌توان دوباره امتحان کرد

برخی خطاها، مانند TRANSIENT_ERROR یا INTERNAL_ERROR ، می‌توانند نشان‌دهنده‌ی یک مشکل موقت باشند که ممکن است با تلاش مجدد برای ارسال درخواست پس از یک مکث کوتاه، برطرف شود.

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

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

هنگام تلاش مجدد برای درخواست‌ها، از یک سیاست بازگشت نمایی با لرزش تصادفی استفاده کنید. به عنوان مثال، اگر ابتدا ۵ ثانیه قبل از اولین تلاش مجدد مکث می‌کنید، می‌توانید ۱۰ ثانیه پس از تلاش دوم و ۲۰ ثانیه پس از تلاش سوم مکث کنید و یک تأخیر تصادفی کوچک به هر بازه اضافه کنید تا از افزایش ناگهانی تلاش مجدد همگام‌سازی شده جلوگیری شود. بازگشت نمایی به شما کمک می‌کند تا مطمئن شوید که API را بیش از حد تهاجمی فراخوانی نمی‌کنید. اگر خطایی پس از تلاش‌های مکرر ادامه داشت، request-id را از پاسخ برای عیب‌یابی ثبت کنید.

خطاهای اعتبارسنجی

خطاهای اعتبارسنجی نشان می‌دهند که ورودی یک عملیات قابل قبول نبوده است. نمونه‌هایی از آن عبارتند از PolicyViolationError ، DateError ، DateRangeError ، StringLengthError و UrlFieldError .

خطاهای اعتبارسنجی اغلب در درخواست‌های آغاز شده توسط کاربر رخ می‌دهند، جایی که کاربر ورودی نامعتبر وارد کرده است. در این موارد، شما باید بر اساس خطای API خاصی که دریافت کرده‌اید، یک پیام خطای مناسب به کاربر ارائه دهید. همچنین می‌توانید قبل از برقراری تماس API، ورودی کاربر را برای اشتباهات رایج اعتبارسنجی کنید، که باعث می‌شود برنامه شما پاسخگوتر و استفاده از API شما کارآمدتر شود. برای درخواست‌های backend، برنامه شما می‌تواند عملیات ناموفق را به صف بررسی توسط اپراتور انسانی اضافه کند.

بسیاری از برنامه‌های گوگل ادز یک پایگاه داده محلی برای ذخیره اشیاء گوگل ادز خود دارند. یکی از چالش‌های این رویکرد این است که پایگاه داده محلی ممکن است با اشیاء واقعی در گوگل ادز هماهنگ نباشد. به عنوان مثال، یک کاربر ممکن است یک گروه تبلیغاتی را مستقیماً در گوگل ادز حذف کند، اما برنامه و پایگاه داده محلی از این تغییر بی‌اطلاع باشند و همچنان به صدور فراخوانی‌های API ادامه دهند، گویی گروه تبلیغاتی وجود داشته است. این مشکلات همگام‌سازی می‌توانند به صورت خطاهای مختلفی مانند DUPLICATE_CAMPAIGN_NAME ، DUPLICATE_ADGROUP_NAME ، AD_NOT_UNDER_ADGROUP ، CANNOT_OPERATE_ON_REMOVED_ADGROUPAD و بسیاری دیگر ظاهر شوند.

برای درخواست‌های آغاز شده توسط کاربر، یک استراتژی این است که کاربر را از مشکل احتمالی همگام‌سازی مطلع کنید، بلافاصله کاری را اجرا کنید که کلاس مربوطه از اشیاء Google Ads را بازیابی کرده و پایگاه داده محلی را به‌روزرسانی کند، سپس از کاربر بخواهید رابط کاربری را به‌روزرسانی کند.

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

بعدی
خطاهای API را درک کنید