معالجة الأخطاء في 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>.