listObjects method
ListObjects:
May throw NoSuchBucket.
Parameter bucket :
The name of the bucket containing the objects.
Directory buckets - When you use this operation with a directory
bucket, you must use virtual-hosted-style requests in the format
Bucket-name.s3express-zone-id.region-code.amazonaws.com.
Path-style requests are not supported. Directory bucket names must be
unique in the chosen Zone (Availability Zone or Local Zone). Bucket names
must follow the format
bucket-base-name--zone-id--x-s3 (for example,
amzn-s3-demo-bucket--usw2-az1--x-s3). For information
about bucket naming restrictions, see Directory
bucket naming rules in the Amazon S3 User Guide.
Access points - When you use this action with an access point for
general purpose buckets, you must provide the alias of the access point in
place of the bucket name or specify the access point ARN. When you use
this action with an access point for directory buckets, you must provide
the access point name in place of the bucket name. When using the access
point ARN, you must direct requests to the access point hostname. The
access point hostname takes the form
AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com.
When using this action with an access point through the Amazon Web
Services SDKs, you provide the access point ARN in place of the bucket
name. For more information about access point ARNs, see Using
access points in the Amazon S3 User Guide.
S3 on Outposts - When you use this action with S3 on Outposts, you
must direct requests to the S3 on Outposts hostname. The S3 on Outposts
hostname takes the form
AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com.
When you use this action with S3 on Outposts, the destination bucket must
be the Outposts access point ARN or the access point alias. For more
information about S3 on Outposts, see What
is S3 on Outposts? in the Amazon S3 User Guide.
Parameter delimiter :
A delimiter is a character that you use to group keys.
CommonPrefixes is filtered out from results if it is not
lexicographically greater than the key-marker.
Parameter expectedBucketOwner :
The account ID of the expected bucket owner. If the account ID that you
provide does not match the actual owner of the bucket, the request fails
with the HTTP status code 403 Forbidden (access denied).
Parameter marker :
Marker is where you want Amazon S3 to start listing from. Amazon S3 starts
listing after this specified key. Marker can be any key in the bucket.
Parameter maxKeys :
Sets the maximum number of keys returned in the response. By default, the
action returns up to 1,000 key names. The response might contain fewer
keys but will never contain more.
Parameter optionalObjectAttributes :
Specifies the optional fields that you want returned in the response.
Fields that you do not specify are not returned.
Parameter prefix :
Limits the response to keys that begin with the specified prefix.
Parameter requestPayer :
Confirms that the requester knows that she or he will be charged for the
list objects request. Bucket owners need not specify this parameter in
their requests.
Implementation
Future<ListObjectsOutput> listObjects({
required String bucket,
String? delimiter,
EncodingType? encodingType,
String? expectedBucketOwner,
String? marker,
int? maxKeys,
List<OptionalObjectAttributes>? optionalObjectAttributes,
String? prefix,
RequestPayer? requestPayer,
}) async {
final headers = <String, String>{
if (expectedBucketOwner != null)
'x-amz-expected-bucket-owner': expectedBucketOwner.toString(),
if (optionalObjectAttributes != null)
'x-amz-optional-object-attributes':
optionalObjectAttributes.map((e) => e.value).join(', '),
if (requestPayer != null) 'x-amz-request-payer': requestPayer.value,
};
final $query = <String, List<String>>{
if (delimiter != null) 'delimiter': [delimiter],
if (encodingType != null) 'encoding-type': [encodingType.value],
if (marker != null) 'marker': [marker],
if (maxKeys != null) 'max-keys': [maxKeys.toString()],
if (prefix != null) 'prefix': [prefix],
};
final $result = await _protocol.sendRaw(
method: 'GET',
requestUri: '/${Uri.encodeComponent(bucket)}',
queryParams: $query,
headers: headers,
exceptionFnMap: _exceptionFns,
);
final $elem = await _s.xmlFromResponse($result);
return ListObjectsOutput(
commonPrefixes: $elem
.findElements('CommonPrefixes')
.map(CommonPrefix.fromXml)
.toList(),
contents: $elem.findElements('Contents').map(Object.fromXml).toList(),
delimiter: _s.extractXmlStringValue($elem, 'Delimiter'),
encodingType: _s
.extractXmlStringValue($elem, 'EncodingType')
?.let(EncodingType.fromString),
isTruncated: _s.extractXmlBoolValue($elem, 'IsTruncated'),
marker: _s.extractXmlStringValue($elem, 'Marker'),
maxKeys: _s.extractXmlIntValue($elem, 'MaxKeys'),
name: _s.extractXmlStringValue($elem, 'Name'),
nextMarker: _s.extractXmlStringValue($elem, 'NextMarker'),
prefix: _s.extractXmlStringValue($elem, 'Prefix'),
requestCharged: _s
.extractHeaderStringValue($result.headers, 'x-amz-request-charged')
?.let(RequestCharged.fromString),
);
}