إدراج الملفات باستخدام Cloud Storage على الويب

تتيح لك خدمة Cloud Storage for Firebase إدراج محتويات حاوية Cloud Storage. تعرض حِزم SDK كلاً من العناصر وبادئات الكائنات ضِمن مرجع Cloud Storage الحالي.Cloud Storage

تتطلب المشاريع التي تستخدم List API الإصدار 2 من قواعد أمان Cloud Storage for Firebase. إذا كان لديك مشروع حالي على Firebase، اتّبِع الخطوات الواردة في دليل قواعد الأمان.

تستخدِم list() واجهة برمجة التطبيقات Google Cloud Storage List API. في Cloud Storage for Firebase، نستخدم / كمحدِّد، ما يسمح لنا بـ محاكاة دلالات نظام الملفات. للسماح بالتنقّل بكفاءة في الحاويات الكبيرة ذات التسلسل الهرمي Cloud Storage، تعرض List API البادئات والعناصر بشكل منفصل. على سبيل المثال، إذا حمّلت ملفًا واحدًا /images/uid/file1،

• ستعرض الدالة root.child('images').listAll() السلسلة /images/uid كبادئة.
• root.child('images/uid').listAll() ستعرض الملف كعنصر.

لا تعرض حزمة تطوير البرامج (SDK) الخاصة بـ Cloud Storage for Firebase مسارات الكائنات التي تحتوي على شرطتَين مائلتَين متتاليتَين ( /) أو تنتهي بـ /.. على سبيل المثال، لنفترض أنّ لديك حاوية تحتوي على الكائنات التالية:

• correctPrefix/happyItem
• wrongPrefix//sadItem
• lonelyItem/

ستؤدي عمليات القائمة على العناصر في هذه الحاوية إلى النتائج التالية:

• تعرض عملية القائمة في الجذر مراجع correctPrefix وwrongPrefix وlonelyItem على أنّها prefixes.
• تعرض عملية القائمة في correctPrefix/ مراجع correctPrefix/happyItem على أنّها items.
• لا تعرض عملية القائمة في wrongPrefix/ أي مراجع لأنّ wrongPrefix//sadItem تحتوي على شرطتَين مائلتَين متتاليتَين./
• لا تعرض عملية القائمة في lonelyItem/ أي مراجع لأنّ الكائن lonelyItem/ ينتهي بـ /.

إدراج جميع الملفات

يمكنك استخدام listAll لجلب جميع نتائج دليل معيّن. من الأفضل استخدام هذه الطريقة مع الأدلة الصغيرة لأنّه يتم تخزين جميع النتائج مؤقتًا في الذاكرة. قد لا تعرض العملية أيضًا لقطة متّسقة إذا تمت إضافة كائنات أو إزالتها أثناء العملية.

بالنسبة إلى القوائم الكبيرة، استخدِم طريقة list() المقسَّمة إلى صفحات لأنّ listAll() تخزّن جميع النتائج مؤقتًا في الذاكرة.

يوضّح المثال التالي طريقة listAll.

import { getStorage, ref, listAll } from "firebase/storage";

const storage = getStorage();

// Create a reference under which you want to list
const listRef = ref(storage, 'files/uid');

// Find all the prefixes and items.
listAll(listRef)
  .then((res) => {
    res.prefixes.forEach((folderRef) => {
      // All the prefixes under listRef.
      // You may call listAll() recursively on them.
    });
    res.items.forEach((itemRef) => {
      // All the items under listRef.
    });
  }).catch((error) => {
    // Uh-oh, an error occurred!
  });
storage_list_all.js

// Create a reference under which you want to list
var listRef = storageRef.child('files/uid');

// Find all the prefixes and items.
listRef.listAll()
  .then((res) => {
    res.prefixes.forEach((folderRef) => {
      // All the prefixes under listRef.
      // You may call listAll() recursively on them.
    });
    res.items.forEach((itemRef) => {
      // All the items under listRef.
    });
  }).catch((error) => {
    // Uh-oh, an error occurred!
  });
list-files.js

تقسيم نتائج القائمة إلى صفحات

تفرض واجهة برمجة التطبيقات list() حدًا على عدد النتائج التي تعرضها. توفّر list() مشاهدة صفحة على الويب متّسقة وتعرض pageToken يسمح بالتحكّم في وقت جلب نتائج إضافية.

يُشفّر pageToken المسار والإصدار الخاصَين بالعنصر الأخير الذي تم عرضه في النتيجة السابقة. في طلب لاحق باستخدام pageToken، يتم عرض العناصر التي تأتي بعد pageToken.

يوضّح المثال التالي كيفية تقسيم نتيجة إلى صفحات باستخدام async/await.

import { getStorage, ref, list } from "firebase/storage";

async function pageTokenExample(){
  // Create a reference under which you want to list
  const storage = getStorage();
  const listRef = ref(storage, 'files/uid');

  // Fetch the first page of 100.
  const firstPage = await list(listRef, { maxResults: 100 });

  // Use the result.
  // processItems(firstPage.items)
  // processPrefixes(firstPage.prefixes)

  // Fetch the second page if there are more elements.
  if (firstPage.nextPageToken) {
    const secondPage = await list(listRef, {
      maxResults: 100,
      pageToken: firstPage.nextPageToken,
    });
    // processItems(secondPage.items)
    // processPrefixes(secondPage.prefixes)
  }
}
storage_list_paginate.js

async function pageTokenExample(){
  // Create a reference under which you want to list
  var listRef = storageRef.child('files/uid');

  // Fetch the first page of 100.
  var firstPage = await listRef.list({ maxResults: 100});

  // Use the result.
  // processItems(firstPage.items)
  // processPrefixes(firstPage.prefixes)

  // Fetch the second page if there are more elements.
  if (firstPage.nextPageToken) {
    var secondPage = await listRef.list({
      maxResults: 100,
      pageToken: firstPage.nextPageToken,
    });
    // processItems(secondPage.items)
    // processPrefixes(secondPage.prefixes)
  }
}
list-files.js

التعامل مع الأخطاء

تعرض الدالتان list() وlistAll() وعدًا مرفوضًا إذا لم تكن قد رقّيت قواعد الأمان إلى الإصدار 2. رقِّ قواعد الأمان إذا ظهر لك هذا الخطأ:

Listing objects in a bucket is disallowed for rules_version = "1".
Please update storage security rules to rules_version = "2" to use list.

قد تشير الأخطاء المحتمَلة الأخرى إلى أنّ المستخدم ليس لديه الإذن المناسب. يمكنك الاطّلاع على مزيد من المعلومات حول الأخطاء في مقالة التعامل مع الأخطاء.