Skip to content

Commit

Permalink
feat(Swift): Adding SubpathStrategy documentation for Storage.List
Browse files Browse the repository at this point in the history
  • Loading branch information
@sebaland
sebaland committed Jul 17, 2024
1 parent 91dacfa commit 04b03ff
Show file tree
Hide file tree
Showing 2 changed files with 293 additions and 36 deletions.
194 changes: 167 additions & 27 deletions src/fragments/lib/storage/ios/list.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
You can list all of the objects uploaded under a given prefix by setting the `pageSize`. If the `pageSize` is set lower than the total file size available, A single `Storage.list` call only returns a subset of all the files. To list all the files with multiple calls, the user can use the `nextToken` from the previous call response.
You can list files without having to download all the files. You can do this by using the list API from the Amplify Library for Storage.

#### With StoragePath
## With StoragePath

The following example lists all objects inside the `public/photos/` path:
<BlockSwitcher>

<Block name="Async/Await">

```swift
let options = StorageListRequest.Options(pageSize: 1000)
let listResult = try await Amplify.Storage.list(
path: .fromString("public/example/path"),
options: options
path: .fromString("public/photos/")
)
listResult.items.forEach { item in
print("Path: \(item.path)")
Expand All @@ -22,18 +22,15 @@ listResult.items.forEach { item in

```swift
let sink = Amplify.Publisher.create {
let options = StorageListRequest.Options(pageSize: 1000)
try await Amplify.Storage.list(
path: .fromString("public/example/path"),
options: options
path: .fromString("public/photos/")
)
}.sink {
if case let .failure(error) = $0 {
print("Failed: \(error)")
}
}
receiveValue: { listResult in
print("Completed")
listResult.items.forEach { item in
print("Path: \(item.path)")
}
Expand All @@ -44,14 +41,135 @@ receiveValue: { listResult in

</BlockSwitcher>

#### With Key (Deprecated)
<Callout>
Note the trailing slash `/` in the given path.

If you had used `public/photos` as path, it would also match against files like `public/photos01.jpg`.
</Callout>

### Exclude results from nested subpaths

By default, the `list` API will return all objects contained within the given path, including objects inside nested subpaths.

For example, the previous `public/photos/` path would include these objects:

```bash
Path: public/photos/photo1.jpg
Path: public/photos/vacation/photo1.jpg
Path: public/photos/thumbnails/photo1.jpg
```

In order to exclude objects within the `vacation` and `thumbnails` subpaths, you can set the `subpathStrategy` option to `.exclude`:

<BlockSwitcher>

<Block name="Async/Await">

```swift
let listResult = try await Amplify.Storage.list(
path: .fromString("public/photos/"),
options: .init(
subpathStrategy: .exclude
)
)
listResult.items.forEach { item in
print("Path: \(item.path)")
}
listResult.excludedSubpaths.forEach { subpath in
print("Subpath: \(subpath)")
}
```

</Block>

<Block name="Combine">

```swift
let sink = Amplify.Publisher.create {
try await Amplify.Storage.list(
path: .fromString("public/photos/"),
options: .init(
subpathStrategy: .exclude
)
)
}.sink {
if case let .failure(error) = $0 {
print("Failed: \(error)")
}
}
receiveValue: { listResult in
listResult.items.forEach { item in
print("Path: \(item.path)")
}
listResult.excludedSubpaths.forEach { subpath in
print("Subpath: \(subpath)")
}
}
```

</Block>

</BlockSwitcher>

The response will only include objects within the `public/photos/` path and will also provide a list of the excluded subpaths:

```bash
Path: public/photos/photo01.jpg
Subpath: public/photos/vacation/
Subpath: public/photos/thumbnails/
```

The default delimiter character is `"/"`, but this can be changed by supplying a custom delimiter:

<BlockSwitcher>

<Block name="Async/Await">

```swift
let listResult = try await Amplify.Storage.list(
path: .fromString("public/photos-"),
options: .init(
subpathStrategy: .exclude(delimitedBy: "-")
)
)
```

</Block>

<Block name="Combine">

```swift
let sink = Amplify.Publisher.create {
try await Amplify.Storage.list(
path: .fromString("public/photos-"),
options: .init(
subpathStrategy: .exclude(delimitedBy: "-")
)
)
}.sink {
if case let .failure(error) = $0 {
print("Failed: \(error)")
}
}
receiveValue: { listResult in
// ...
}
```

</Block>

</BlockSwitcher>


## With Key (Deprecated)
The following example lists all public files:

<BlockSwitcher>

<Block name="Async/Await">

```swift
let options = StorageListRequest.Options(pageSize: 1000)
let listResult = try await Amplify.Storage.list(options: options)
let listResult = try await Amplify.Storage.list()
listResult.items.forEach { item in
print("Key: \(item.key)")
}
Expand All @@ -63,8 +181,7 @@ listResult.items.forEach { item in

```swift
let sink = Amplify.Publisher.create {
let options = StorageListRequest.Options(pageSize: 1000)
try await Amplify.Storage.list(options: options)
try await Amplify.Storage.list()
}.sink {
if case let .failure(error) = $0 {
print("Failed: \(error)")
Expand All @@ -89,10 +206,14 @@ You can also list private or protected files by passing options. For example, to
<Block name="Async/Await">

```swift
let options = StorageListRequest.Options(accessLevel: .protected, targetIdentityId: "otherUserID", pageSize: 1000)
let listResult = try await Amplify.Storage.list(options: options)
let listResult = try await Amplify.Storage.list(
options: .init(
accessLevel: .protected,
targetIdentityId: "otherUserID"
)
)
listResult.items.forEach { item in
print("Path: \(item.path)")
print("Key: \(item.key)")
}
```

Expand All @@ -102,17 +223,21 @@ listResult.items.forEach { item in

```swift
let sink = Amplify.Publisher.create {
let options = StorageListRequest.Options(accessLevel: .protected, targetIdentityId: "otherUserID", pageSize: 1000)
try await Amplify.Storage.list(options: options)
let options = StorageListRequest.Options)
try await Amplify.Storage.list(
options: .init(
accessLevel: .protected,
targetIdentityId: "otherUserID"
)
)
}.sink {
if case let .failure(error) = $0 {
print("Failed: \(error)")
}
}
receiveValue: { listResult in
print("Completed")
listResult.items.forEach { item in
print("Path: \(item.path)")
print("Key: \(item.path)")
}
}
```
Expand All @@ -128,8 +253,11 @@ If you like limit the response to keys that begin with the specified path provid
<Block name="Async/Await">

```swift
let options = StorageListRequest.Options(path: "path")
let listResult = try await Amplify.Storage.list(options: options)
let listResult = try await Amplify.Storage.list(
options: .init(
path: "path"
)
)
listResult.items.forEach { item in
print("Key: \(item.key)")
}
Expand All @@ -141,15 +269,17 @@ listResult.items.forEach { item in

```swift
let sink = Amplify.Publisher.create {
let options = StorageListRequest.Options(path: "path")
try await Amplify.Storage.list(options: options)
try await Amplify.Storage.list(
options: .init(
path: "path"
)
)
}.sink {
if case let .failure(error) = $0 {
print("Failed: \(error)")
}
}
receiveValue: { listResult in
print("Completed")
listResult.items.forEach { item in
print("Key: \(item.key)")
}
Expand All @@ -158,4 +288,14 @@ receiveValue: { listResult in

</Block>

</BlockSwitcher>
</BlockSwitcher>

## More `list` options

| Option | Type | Description |
| --- | --- | --- |
| pageSize | UInt | Number between 1 and 1,000 that indicates the limit of how many entries to fetch when retrieving file lists from the server |
| nextToken | String | String indicating the page offset at which to resume a listing. |


If the `pageSize` is set lower than the total file size available, a single `list` call only returns a subset of all the files. To list all the files with multiple calls, the user can use the `nextToken` value from the previous response.
Loading

0 comments on commit 04b03ff

Please sign in to comment.