Cloud Storage allows you to list the contents of your Storage Bucket. The SDKs return both the items and the prefixes of objects under the current Storage reference.
Projects that use the list API require Firebase Storage Rules Version 2. If you have an existing Firebase Project, please follow the steps in the Security Rules Guide.
The list API uses Google Cloud Storage’s
List API.
In Firebase Storage, we use /
as a delimiter, which allows us to emulate file
system semantics. To allow for efficient traversal of large, hierarchical
Storage Buckets, the List API returns prefixes and items separately.
For example, if you upload one file /images/uid/file1
,
root.child('images').listAll()
will return/images/uid
as a prefix.root.child('images/uid').listAll()
will return the file as an item.
The Firebase Storage SDK does not return object paths that contain two
consecutive /
s or end with a /.
. For example, if a bucket has the
following objects:
correctPrefix/happyItem
wrongPrefix//sadItem
lonelyItem/
List operations on items in this bucket will give the following results:
- The list operation at the root returns the references to
correctPrefix
,wrongPrefix
andlonelyItem
asprefixes
. - The list operation at the
correctPrefix/
returns the references tocorrectPrefix/happyItem
asitems
. - The list operation at the
wrongPrefix/
doesn't return any references becausewrongPrefix//sadItem
contains two consecutive/
s. - The list operation at the
lonelyItem/
doesn't return any references because the objectlonelyItem/
ends with/
.
List all files
You can use listAll(completion:)
to fetch all results for a directory.
This is best used for small directories as all results are buffered in memory.
The operation also may not return a consistent snapshot if objects are added or
removed during the process.
For a large list, use the paginated list(withMaxResults:completion:)
method as
listAll(completion:)
buffers all results in memory.
The following example demonstrates listAll(completion:)
.
Swift
let storageReference = storage.reference().child("files/uid") storageReference.listAll { (result, error) in if let error = error { // ... } 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. } }
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. } }];
Paginate list results
The list(withMaxResults:completion:)
API places a limit on the number of
results it returns. list(withMaxResults:completion)
provides a consistent
pageview and exposes a pageToken that allows control over when to fetch
additional results.
The pageToken encodes the path and version of the last item returned in the previous result. In a subsequent request using the pageToken, items that come after the pageToken are shown.
The following example demonstrates paginating a result:
Swift
func listAllPaginated(pageToken: String? = nil) { let storage = Storage.storage() let storageReference = storage.reference().child("files/uid") let pageHandler: (StorageListResult, Error?) -> Void = { (result, error) in if let error = error { // ... } let prefixes = result.prefixes let items = result.items // ... // Process next page if let token = result.pageToken { self.listAllPaginated(pageToken: token) } } if let pageToken = pageToken { storageReference.list(withMaxResults: 100, pageToken: pageToken, completion: pageHandler) } else { storageReference.list(withMaxResults: 100, completion: pageHandler) } }
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]; } }
Handle errors
Methods in the list API will fail if you haven't upgraded your Security Rules to version 2. Upgrade your Security Rules if you see this error:
Listing objects in a bucket is disallowed for rules_version = "1".
Please update storage security rules to rules_version = "2" to use list.
Other possible errors may indicate the user does not have the right permissions. More information on errors can be found in Handle Errors.