فهرست کردن فایل‌ها با Cloud Storage در پلاتفرم‌های Apple

این صفحه نحوه استفاده از Cloud Storage for Firebase SDK را برای فهرست کردن محتویات سطل Cloud Storage شما شرح می‌دهد. کیت توسعه نرم‌افزار هم موارد و هم پیشوندهای اشیاء را تحت مرجع Cloud Storage فعلی برمی‌گرداند.

پروژه‌هایی که از فهرست API استفاده می‌کنند به 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() فایل را به‌عنوان یک مورد برمی‌گرداند.

کیت توسعه نرم‌افزار Cloud Storage for Firebase مسیرهای شیء را که حاوی دو / متوالی هستند یا به /. ختم می‌شوند برنمی‌گرداند. برای مثال، دسته‌ای را درنظر بگیرید که دارای اشیاء زیر است:

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

عملیات فهرست روی موارد موجود در این دسته نتایج زیر را ارائه می‌دهد:

  • عملیات فهرست در ریشه، ارجاع‌ها به correctPrefix، wrongPrefix، و lonelyItem را به‌صورت prefixes برمی‌گرداند.
  • عملیات فهرست در correctPrefix/، مرجع‌های correctPrefix/happyItem را به‌عنوان items برمی‌گرداند.
  • عملیات فهرست در wrongPrefix/ هیچ مرجعی را برنمی‌گرداند زیرا wrongPrefix//sadItem حاوی دو / متوالی است.
  • عملیات فهرست در 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.
  }
}];

صفحه‌بندی نتایج فهرست

list(withMaxResults:completion:) API برای تعداد نتایجی که برمی‌گرداند محدودیت اعمال می‌کند. 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];
  }
}

مدیریت کردن خطا

اگر «قوانین امنیتی» خود را به نسخه ۲ ارتقا نداده باشید، روش‌های موجود در میانای برنامه‌سازی کاربردی فهرست با شکست مواجه خواهند شد. اگر این خطا را می‌بینید، «قوانین امنیتی» خود را ارتقا دهید:

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

خطاهای احتمالی دیگر ممکن است نشان دهد که کاربر اجازه‌های لازم را ندارد. برای اطلاعات بیشتر درباره خطاها، رسیدگی به خطاها را ببینید.