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

‫Cloud Storage for Firebase به شما امکان می‌دهد محتوای Cloud Storage سبد را فهرست کنید. «کیت‌های توسعه نرم‌افزار» هم موارد و هم پیشوندهای اشیاء را تحت مرجع Cloud Storage کنونی برمی‌گردانند.

پروژه‌هایی که از فهرست میانای برنامه‌سازی کاربردی استفاده می‌کنند به Cloud Storage for Firebase نسخه ۲ «قوانین» نیاز دارند. اگر پروژه Firebase موجودی دارید، مراحل موجود در راهنمای قوانین امنیتی را دنبال کنید.

‫list() از Google Cloud Storage میانای برنامه‌سازی کاربردی فهرست استفاده می‌کند. در Cloud Storage for Firebase، از / به‌عنوان جداکننده استفاده می‌کنیم که به ما امکان می‌دهد معناشناسی سیستم فایل را شبیه‌سازی کنیم. برای پیمایش کارآمد دسته‌های بزرگ و سلسله‌مراتبی Cloud Storage، «میانای برنامه‌سازی کاربردی فهرست» پیشوندها و موارد را به‌صورت جداگانه برمی‌گرداند. برای مثال، اگر یک فایل /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.

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