getObjectAnnotation method

Future<GetObjectAnnotationOutput> getObjectAnnotation({
  1. required String annotationName,
  2. required String bucket,
  3. required String key,
  4. ChecksumMode? checksumMode,
  5. String? expectedBucketOwner,
  6. RequestPayer? requestPayer,
  7. String? versionId,
})

Retrieves an annotation from an Amazon S3 object. To use this operation, you must have the s3:GetObjectAnnotation permission.

If checksum mode is enabled via the x-amz-checksum-mode header, Amazon S3 returns the stored checksum in the response headers for client-side validation. The following operations are related to GetObjectAnnotation:

May throw NoSuchAnnotation. May throw NoSuchBucket. May throw NoSuchKey.

Parameter annotationName : The name of the annotation to retrieve.

Length Constraints: Minimum length of 1. Maximum length of 512 bytes.

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

Parameter key : The object key.

Parameter checksumMode : Set to ENABLED to validate the checksum of the annotation payload on retrieval.

Parameter expectedBucketOwner : The account ID of the expected bucket owner. If the bucket is owned by a different account, the request fails with an HTTP 403 (Access Denied) error.

Parameter versionId : The version ID of the object.

Implementation

Future<GetObjectAnnotationOutput> getObjectAnnotation({
  required String annotationName,
  required String bucket,
  required String key,
  ChecksumMode? checksumMode,
  String? expectedBucketOwner,
  RequestPayer? requestPayer,
  String? versionId,
}) async {
  final headers = <String, String>{
    if (checksumMode != null) 'x-amz-checksum-mode': checksumMode.value,
    if (expectedBucketOwner != null)
      'x-amz-expected-bucket-owner': expectedBucketOwner.toString(),
    if (requestPayer != null) 'x-amz-request-payer': requestPayer.value,
  };
  final $query = <String, List<String>>{
    'annotationName': [annotationName],
    if (versionId != null) 'versionId': [versionId],
  };
  final $result = await _protocol.sendRaw(
    method: 'GET',
    requestUri:
        '/${key.split('/').map(Uri.encodeComponent).join('/')}?annotation&x-id=GetObjectAnnotation',
    queryParams: $query,
    headers: headers,
    endpoint: _resolveEndpoint(
      bucket: bucket,
      key: key,
    ),
    exceptionFnMap: _exceptionFns,
  );
  return GetObjectAnnotationOutput(
    annotationPayload: await $result.stream.toBytes(),
    checksumCRC32:
        _s.extractHeaderStringValue($result.headers, 'x-amz-checksum-crc32'),
    checksumCRC32C:
        _s.extractHeaderStringValue($result.headers, 'x-amz-checksum-crc32c'),
    checksumCRC64NVME: _s.extractHeaderStringValue(
        $result.headers, 'x-amz-checksum-crc64nvme'),
    checksumMD5:
        _s.extractHeaderStringValue($result.headers, 'x-amz-checksum-md5'),
    checksumSHA1:
        _s.extractHeaderStringValue($result.headers, 'x-amz-checksum-sha1'),
    checksumSHA256:
        _s.extractHeaderStringValue($result.headers, 'x-amz-checksum-sha256'),
    checksumSHA512:
        _s.extractHeaderStringValue($result.headers, 'x-amz-checksum-sha512'),
    checksumType: _s
        .extractHeaderStringValue($result.headers, 'x-amz-checksum-type')
        ?.let(ChecksumType.fromString),
    checksumXXHASH128: _s.extractHeaderStringValue(
        $result.headers, 'x-amz-checksum-xxhash128'),
    checksumXXHASH3: _s.extractHeaderStringValue(
        $result.headers, 'x-amz-checksum-xxhash3'),
    checksumXXHASH64: _s.extractHeaderStringValue(
        $result.headers, 'x-amz-checksum-xxhash64'),
    contentLength:
        _s.extractHeaderIntValue($result.headers, 'Content-Length'),
    eTag: _s.extractHeaderStringValue($result.headers, 'ETag'),
    lastModified:
        _s.extractHeaderDateTimeValue($result.headers, 'Last-Modified'),
    objectVersionId: _s.extractHeaderStringValue(
        $result.headers, 'x-amz-object-version-id'),
    replicationStatus: _s
        .extractHeaderStringValue($result.headers, 'x-amz-replication-status')
        ?.let(ReplicationStatus.fromString),
    requestCharged: _s
        .extractHeaderStringValue($result.headers, 'x-amz-request-charged')
        ?.let(RequestCharged.fromString),
    serverSideEncryption: _s
        .extractHeaderStringValue(
            $result.headers, 'x-amz-server-side-encryption')
        ?.let(ServerSideEncryption.fromString),
  );
}