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

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

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

Kotlin+KTX

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>