معالجة الأخطاء في Cloud Storage على Android

في بعض الأحيان، لا تسير الأمور كما هو مخطّط لها ويحدث خطأ.

عند الشك، تحقَّق من الخطأ الذي تم إرجاعه واطّلِع على ما تقوله رسالة الخطأ. يعرض الرمز التالي عملية تنفيذ معالج أخطاء مخصّص يفحص رمز الخطأ ورسالة الخطأ التي تعرضها Cloud Storage. يمكن إضافة معالجات الأخطاء هذه إلى عناصر مختلفة مستخدَمة في واجهة برمجة التطبيقات Cloud Storage (على سبيل المثال، UploadTask وFileDownloadTask).

Kotlin

internal inner class MyFailureListener : OnFailureListener {
    override fun onFailure(exception: Exception) {
        val errorCode = (exception as StorageException).errorCode
        val errorMessage = exception.message
        // test the errorCode and errorMessage, and handle accordingly
    }
}
StorageActivity.kt

Java

class MyFailureListener implements OnFailureListener {
    @Override
    public void onFailure(@NonNull Exception exception) {
        int errorCode = ((StorageException) exception).getErrorCode();
        String errorMessage = exception.getMessage();
        // test the errorCode and errorMessage, and handle accordingly
    }
}
StorageActivity.java

إذا راجعت رسالة الخطأ وتأكّدت من توفّر Cloud Storage Security Rules التي تسمح لك بتنفيذ الإجراء، ولكنك لا تزال تواجه صعوبة في حلّ الخطأ، يُرجى الانتقال إلى صفحة الدعم وإعلامنا بكيفية مساعدتك.

التعامل مع رسائل الخطأ

هناك عدة أسباب قد تؤدي إلى حدوث أخطاء، بما في ذلك عدم توفّر الملف أو عدم توفّر إذن للمستخدم بالوصول إلى الملف المطلوب أو إلغاء المستخدم لعملية تحميل الملف.

لتشخيص المشكلة ومعالجة الخطأ بشكل صحيح، إليك قائمة كاملة بجميع الأخطاء التي سيبلغ عنها برنامجنا وكيفية حدوثها. يتم تحديد رموز الخطأ في هذا الجدول في الفئة StorageException كثوابت عددية صحيحة.

الرمز السبب
ERROR_UNKNOWN حدث خطأ غير معروف.
ERROR_OBJECT_NOT_FOUND لا يتوفّر أي عنصر في المرجع المحدّد.
ERROR_BUCKET_NOT_FOUND لم يتم إعداد أي حزمة لـ Cloud Storage
ERROR_PROJECT_NOT_FOUND لم يتم إعداد أي مشروع للنطاق Cloud Storage
ERROR_QUOTA_EXCEEDED تم تجاوز الحصة المخصّصة لحزمة Cloud Storage. إذا كنت تستخدم خطة أسعار Spark، ننصحك بالترقية إلى خطة أسعار Blaze بنظام الدفع حسب الاستخدام. إذا كنت مشتركًا في خطة أسعار Blaze، يُرجى التواصل مع فريق دعم Firebase.

ملاحظة مهمة: اعتبارًا من 1 أكتوبر 2025، يجب الاشتراك في خطة أسعار Blaze لاستخدام Cloud Storage، حتى الحِزم التلقائية.
ERROR_NOT_AUTHENTICATED لم تتم مصادقة المستخدم، يُرجى المصادقة والمحاولة مرة أخرى.
ERROR_NOT_AUTHORIZED لا يُسمح للمستخدم بتنفيذ الإجراء المطلوب، لذا يُرجى التحقّق من القواعد للتأكّد من صحتها.
ERROR_RETRY_LIMIT_EXCEEDED تم تجاوز الحدّ الأقصى للوقت المسموح به لإجراء عملية (تحميل أو تنزيل أو حذف أو غير ذلك). يُرجى إعادة المحاولة.
ERROR_INVALID_CHECKSUM لا يتطابق الملف على الجهاز مع المجموع الاختباري للملف الذي تلقّاه الخادم. يُرجى محاولة التحميل مرة أخرى.
ERROR_CANCELED ألغى المستخدِم العملية.

بالإضافة إلى ذلك، ستؤدي محاولة الاتصال بـ getReferenceFromUrl() باستخدام عنوان URL غير صالح إلى ظهور الخطأ IllegalArgumentException. يجب أن تكون وسيطة الطريقة المذكورة أعلاه بالتنسيق gs://bucket/object أو https://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=<TOKEN>