You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/pages/[platform]/build-a-backend/storage/list-files/index.mdx
+87-24Lines changed: 87 additions & 24 deletions
Original file line number
Diff line number
Diff line change
@@ -29,22 +29,18 @@ export function getStaticProps(context) {
29
29
};
30
30
}
31
31
32
-
You can list files without having to download all the files. You can do this by using the listFile API from the Amplify Library for Storage. You can also get properties individually for a file using the getProperties API.
32
+
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. You can also get properties individually for a file using the getProperties API.
Note the trailing slash `/` - if you had requested `list({ path : 'photos' })` it would also match against files like `photos123.jpg` alongside `photos/123.jpg`.
@@ -63,9 +59,18 @@ The format of the response will look similar to the below example:
63
59
// ...
64
60
],
65
61
}
66
-
```
67
-
{/* in other files we're referring to paths instead of folders, can we be consistent on terminology? */}
68
-
Manually created folders will show up as files with a `size` of 0, but you can also match keys against a regex like `file.key.match(/\.[0-9a-z]+$/i)` to distinguish files from folders. Since "folders" are a virtual concept in Amazon S3, any file may declare any depth of folder just by having a `/` in its name. If you need to list all the folders, you'll have to parse them accordingly to get an authoritative list of files and folders:
62
+
````
63
+
64
+
{/* in other files we're referring to paths instead of folders, can we be consistent on terminology? */} Manually created folders will show up as files with a `size`of0, but you can also match keys against a regex like `file.key.match(/\.[0-9a-z]+$/i)` to distinguish files from folders. Since"folders" are a virtual concept in Amazon S3, any file may declare any depth of folder just by having a `/`in its name.
65
+
66
+
To access the contents and subpaths of a "folder", you have two options:
67
+
68
+
1. Request the entire path and parse the contents.
69
+
2. Use the subpathStrategy option to retrieve only the files within the specified path (i.e. exclude files under subpaths).
70
+
71
+
### Get all nested files within a path
72
+
73
+
This retrieves all files and folders under a given path. You may need to parse the result to get only the files within the specified path.
69
74
70
75
```js
71
76
function processStorageList(response) {
@@ -109,10 +114,66 @@ function processStorageList(response) {
109
114
110
115
This places each item's data inside a special `__data` key.
111
116
117
+
### Excluding subpaths
118
+
119
+
In addition to using the `list` API to get all the contents of a path, you can also use it to get only the files within a path while excluding files under subpaths.
120
+
121
+
For example, given the following keys in your `path` you may want to return only the jpg object, and not the "vacation" subpath and its contents:
122
+
123
+
```
124
+
photos/photo1.jpg
125
+
photos/vacation/
126
+
```
127
+
128
+
This can be accomplished with the `subpathStrategy` option:
129
+
130
+
```ts title="src/main.ts"
131
+
import { list } from "aws-amplify/storage";
132
+
const result = await list({
133
+
path: "photos/",
134
+
options:{
135
+
subpathStrategy: { strategy:'exclude' }
136
+
}
137
+
});
138
+
```
139
+
140
+
The response will include only the objects within the `photos/` path and will also communicate any excluded subpaths:
141
+
142
+
```js
143
+
{
144
+
excludedSubpaths: [
145
+
'photos/vacation/'
146
+
],
147
+
items: [
148
+
{
149
+
path: "photos/photo1.jpg",
150
+
eTag: "30074401292215403a42b0739f3b5262",
151
+
lastModified: "Thu Oct 08 2020 23:59:31 GMT+0800 (Singapore Standard Time)",
152
+
size: 138256
153
+
},
154
+
]
155
+
}
156
+
```
157
+
158
+
The default delimiter character is '/', but this can be changed by supplying a custom delimiter:
159
+
160
+
```ts title="src/main.ts"
161
+
const result = await list({
162
+
// Path uses '-' character to organize files rather than '/'
163
+
path: 'photos-',
164
+
options: {
165
+
subpathStrategy: {
166
+
strategy: 'exclude',
167
+
delimiter: '-'
168
+
}
169
+
}
170
+
});
171
+
```
172
+
112
173
### More `list` options
113
174
114
-
Option | Type | Description |
115
-
| -- | -- |----------- |
175
+
| Option | Type | Description |
176
+
| --- | --- | --- |
116
177
| listAll | boolean | Set to true to list all files within the specified `path` |
117
178
| pageSize | number | Sets the maximum number of files to be return. The range is 0 - 1000 |
118
179
| nextToken | string | Indicates whether the list is being continued on this bucket with a token |
@@ -242,7 +303,7 @@ You can list all of the objects uploaded under a given path by setting the `page
242
303
```swift
243
304
let options = StorageListRequest.Options(pageSize: 1000)
244
305
let listResult = try await Amplify.Storage.list(
245
-
path: .fromString("public/example/path"),
306
+
path: .fromString("public/example/path"),
246
307
options: options
247
308
)
248
309
listResult.items.forEach { item in
@@ -258,7 +319,7 @@ listResult.items.forEach { item in
258
319
let sink = Amplify.Publisher.create {
259
320
let options = StorageListRequest.Options(pageSize: 1000)
260
321
try await Amplify.Storage.list(
261
-
path: .fromString("public/example/path"),
322
+
path: .fromString("public/example/path"),
262
323
options: options
263
324
)
264
325
}.sink {
@@ -280,18 +341,19 @@ receiveValue: { listResult in
280
341
281
342
### More `list` options
282
343
283
-
Option | Type | Description |
284
-
| -- | -- |----------- |
344
+
| Option | Type | Description |
345
+
| --- | --- | --- |
285
346
| 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 |
286
347
| nextToken | String | String indicating the page offset at which to resume a listing. |
287
-
348
+
288
349
</InlineFilter>
289
350
290
351
<InlineFilter filters={["flutter"]}>
291
352
292
353
This will list all files located under path `album` that:
293
-
* have `private` access level
294
-
* are in the root of `album/` (the result doesn't include files under any sub path)
354
+
355
+
- have `private` access level
356
+
- are in the root of `album/` (the result doesn't include files under any sub path)
0 commit comments