listObjectAnnotations method

Future<ListObjectAnnotationsOutput> listObjectAnnotations({
  1. required String bucket,
  2. required String key,
  3. String? annotationPrefix,
  4. String? continuationToken,
  5. String? expectedBucketOwner,
  6. int? maxAnnotationResults,
  7. RequestPayer? requestPayer,
  8. String? versionId,
})

Lists the annotations attached to an Amazon S3 object. Results are paginated, with a maximum of 1,000 annotations per object. Use the AnnotationPrefix parameter to filter the results by name prefix.

To use this operation, you must have the s3:ListObjectAnnotations permission. The following operations are related to ListObjectAnnotations:

May throw InvalidPrefix. May throw NoSuchBucket. May throw NoSuchKey.

Parameter bucket : The name of the bucket that contains the object.

Parameter key : The object key.

Parameter annotationPrefix : Filter results to annotations whose name begins with the specified prefix.

Parameter continuationToken : Continuation token returned by a previous request to retrieve the next page.

Parameter expectedBucketOwner : The account ID of the expected bucket owner.

Parameter maxAnnotationResults : The maximum number of annotations to return in the response. Maximum is 1,000.

Parameter versionId : The version ID of the object.

Implementation

Future<ListObjectAnnotationsOutput> listObjectAnnotations({
  required String bucket,
  required String key,
  String? annotationPrefix,
  String? continuationToken,
  String? expectedBucketOwner,
  int? maxAnnotationResults,
  RequestPayer? requestPayer,
  String? versionId,
}) async {
  _s.validateNumRange(
    'maxAnnotationResults',
    maxAnnotationResults,
    1,
    1000,
  );
  final headers = <String, String>{
    if (expectedBucketOwner != null)
      'x-amz-expected-bucket-owner': expectedBucketOwner.toString(),
    if (requestPayer != null) 'x-amz-request-payer': requestPayer.value,
  };
  final $query = <String, List<String>>{
    if (annotationPrefix != null) 'annotation-prefix': [annotationPrefix],
    if (continuationToken != null) 'continuation-token': [continuationToken],
    if (maxAnnotationResults != null)
      'max-annotation-results': [maxAnnotationResults.toString()],
    if (versionId != null) 'versionId': [versionId],
  };
  final $result = await _protocol.sendRaw(
    method: 'GET',
    requestUri:
        '/${key.split('/').map(Uri.encodeComponent).join('/')}?annotation&x-id=ListObjectAnnotations',
    queryParams: $query,
    headers: headers,
    endpoint: _resolveEndpoint(
      bucket: bucket,
    ),
    exceptionFnMap: _exceptionFns,
  );
  final $elem = await _s.xmlFromResponse($result);
  return ListObjectAnnotationsOutput(
    annotationCount: _s.extractXmlIntValue($elem, 'AnnotationCount'),
    annotationPrefix: _s.extractXmlStringValue($elem, 'AnnotationPrefix'),
    annotations: _s.extractXmlChild($elem, 'Annotations')?.let(($elem) =>
        $elem
            .findElements('AnnotationEntry')
            .map(AnnotationEntry.fromXml)
            .toList()),
    bucket: _s.extractXmlStringValue($elem, 'Bucket'),
    continuationToken: _s.extractXmlStringValue($elem, 'ContinuationToken'),
    key: _s.extractXmlStringValue($elem, 'Key'),
    maxAnnotationResults:
        _s.extractXmlIntValue($elem, 'MaxAnnotationResults'),
    nextContinuationToken:
        _s.extractXmlStringValue($elem, 'NextContinuationToken'),
    objectVersionId: _s.extractHeaderStringValue(
        $result.headers, 'x-amz-object-version-id'),
    requestCharged: _s
        .extractHeaderStringValue($result.headers, 'x-amz-request-charged')
        ?.let(RequestCharged.fromString),
  );
}