הצגה של רשימת קבצים באמצעות Cloud Storage בפלטפורמות של Apple

‫Cloud Storage for Firebase מאפשרת לכם להציג את תוכן הקטגוריה Cloud Storage. ערכות ה-SDK מחזירות גם את הפריטים וגם את הקידומות של האובייקטים בהפניה הנוכחית Cloud Storage.

פרויקטים שמשתמשים ב-list API דורשים כללים בגרסה 2 של Cloud Storage for Firebase. אם יש לכם פרויקט Firebase, תוכלו לפעול לפי השלבים שמפורטים במדריך לכללי אבטחה.

‫list() משתמש ב-Google Cloud Storage List API. ב-Cloud Storage for Firebase, אנחנו משתמשים ב-/ כתו מפריד, שמאפשר לנו לדמות סמנטיקה של מערכת קבצים. כדי לאפשר מעבר יעיל בין דליים גדולים והיררכיים של Cloud Storage, ה-API של List מחזיר קידומות ופריטים בנפרד. לדוגמה, אם מעלים קובץ אחד /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 מכיל שני מופעים עוקבים של /.
  • הפעולה list ב-lonelyItem/ לא מחזירה הפניות כי האובייקט lonelyItem/ מסתיים ב-/.

רשימה של כל הקבצים

אפשר להשתמש ב-listAll(completion:) כדי לאחזר את כל התוצאות של ספרייה. השיטה הזו מתאימה במיוחד לספריות קטנות, כי כל התוצאות נשמרות בזיכרון. בנוסף, יכול להיות שהפעולה לא תחזיר תמונת מצב עקבית אם אובייקטים יתווספו או יוסרו במהלך התהליך.

אם הרשימה גדולה, כדאי להשתמש בשיטה list(withMaxResults:completion:) עם חלוקה לדפים, כי listAll(completion:) מאגדת את כל התוצאות בזיכרון.

בדוגמה הבאה אפשר לראות איך משתמשים ב-listAll(completion:).

Swift

let storageReference = storage.reference().child("files/uid")
do {
  let result = try await storageReference.listAll()
  for prefix in result.prefixes {
    // The prefixes under storageReference.
    // You may call listAll(completion:) recursively on them.
  }
  for item in result.items {
    // The items under storageReference.
  }
} catch {
  // ...
}

Objective-C

FIRStorageReference *storageReference = [storage reference];
[storageReference listAllWithCompletion:^(FIRStorageListResult *result, NSError *error) {
  if (error != nil) {
    // ...
  }

  for (FIRStorageReference *prefix in result.prefixes) {
    // All the prefixes under storageReference.
    // You may call listAllWithCompletion: recursively on them.
  }
  for (FIRStorageReference *item in result.items) {
    // All items under storageReference.
  }
}];

חלוקת תוצאות הרשימה לדפים

ב-API של list(withMaxResults:completion:) יש מגבלה על מספר התוצאות שמוחזרות. list(withMaxResults:completion) מספקת תצוגת דף עקבית וחושפת pageToken שמאפשרת שליטה במועד האחזור של תוצאות נוספות.

הפרמטר pageToken מקודד את הנתיב והגרסה של הפריט האחרון שהוחזר בתוצאה הקודמת. בבקשה הבאה, באמצעות pageToken, מוצגים פריטים שמופיעים אחרי pageToken.

בדוגמה הבאה מוצג אופן חלוקת התוצאה לדפים:

Swift

func listAllPaginated(pageToken: String? = nil) async throws {
  let storage = Storage.storage()
  let storageReference = storage.reference().child("files/uid")

  let listResult: StorageListResult
  if let pageToken = pageToken {
    listResult = try await storageReference.list(maxResults: 100, pageToken: pageToken)
  } else {
    listResult = try await storageReference.list(maxResults: 100)
  }
  let prefixes = listResult.prefixes
  let items = listResult.items
  // Handle list result
  // ...

  // Process next page
  if let token = listResult.pageToken {
    try await listAllPaginated(pageToken: token)
  }
}

Objective-C

- (void)paginateFilesAtReference:(FIRStorageReference *)reference
                       pageToken:(nullable NSString *)pageToken {
  void (^pageHandler)(FIRStorageListResult *_Nonnull, NSError *_Nullable) =
      ^(FIRStorageListResult *result, NSError *error) {
        if (error != nil) {
          // ...
        }
        NSArray *prefixes = result.prefixes;
        NSArray *items = result.items;

        // ...

        // Process next page
        if (result.pageToken != nil) {
          [self paginateFilesAtReference:reference pageToken:result.pageToken];
        }
  };

  if (pageToken != nil) {
    [reference listWithMaxResults:100 pageToken:pageToken completion:pageHandler];
  } else {
    [reference listWithMaxResults:100 completion:pageHandler];
  }
}

טיפול בשגיאות

שיטות ב-API של רשימת הכללים ייכשלו אם לא שדרגתם את כללי האבטחה לגרסה 2. אם מופיעה השגיאה הבאה, צריך לשדרג את כללי האבטחה:

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

שגיאות אפשריות אחרות עשויות להצביע על כך שאין למשתמש את ההרשאות הנכונות. מידע נוסף על שגיאות זמין במאמר טיפול בשגיאות.