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

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

בפרויקטים שמשתמשים ב-List API נדרשת גרסה 2 של Cloud Storage for FirebaseRules. אם יש לכם פרויקט 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() תחזיר את הקובץ כפריט.

‫Cloud Storage for Firebase SDK לא מחזיר נתיבי אובייקטים שמכילים שני תווי / עוקבים או מסתיימים בתו /.. לדוגמה, נניח שיש לכם קטגוריה עם האובייקטים הבאים:

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

פעולות הרשימה על פריטים בדלי הזה יניבו את התוצאות הבאות:

• פעולת הרשימה ברמת הבסיס מחזירה את ההפניות אל correctPrefix,‏ wrongPrefix ו-lonelyItem בתור prefixes.
• פעולת הרשימה ב-correctPrefix/ מחזירה את ההפניות אל correctPrefix/happyItem בתור items.
• פעולת הרשימה ב-wrongPrefix/ לא מחזירה הפניות כי wrongPrefix//sadItem מכיל שני /s רצופים.
• פעולת הרשימה ב-lonelyItem/ לא מחזירה הפניות כי האובייקט lonelyItem/ מסתיים ב-/.

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

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

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

בדוגמה הבאה מוצגת הפקודה listAll(completion:).

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 {
  // ...
}
ViewController.swift

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.
  }
}];
ViewController.m

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

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

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

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

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)
  }
}
ViewController.swift

- (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];
  }
}
ViewController.m

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

שיטות ב-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.

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