Skip to main content

GetObject

Retrieves an object from Astran S3.

In the GetObject request, specify the full key name for the object.

Permissions​

ActionDescriptionResource
GetObjectGrants permission to retrieve an object from a bucketobject
GetObjectVersionGrants permission to retrieve a specific version of an object from a bucketobject
caution

Having the GetObject permission does not grant you GetObjectVersion permission, and vice versa. Each permission is independent of the other.

The following operations are related to GetObject:

Request Syntax​

            GET /Bucket/Key+?response-cache-control=ResponseCacheControl&versionId=VersionId HTTP/1.1
            Host: <partition>.s3.astran.io
            Range: Range

URI Request Parameters​

The request uses the following URI parameters.

Bucket

The bucket name containing the object.

Required: Yes

Key

Key of the object to get.

Length Constraints: Minimum length of 1.

Required: Yes

Range

Downloads the specified byte range of an object. For more information about the HTTP Range header, see https://www.rfc-editor.org/rfc/rfc9110.html#name-range.

note

Astran S3 doesn't support retrieving multiple ranges of data per GET request.

response-cache-control

Sets the Cache-Control header of the response.

versionId

Version ID used to reference a specific version of the object. By default, GetObject returns the current version of the object. To return a different version, use the versionId subresource.

For more information about versioning, see PutBucketVersioning.

Request Body​

The request does not have a request body.

Response Syntax​

            HTTP/1.1 200
            x-amz-delete-marker: DeleteMarker
            accept-ranges: AcceptRanges
            Last-Modified: LastModified
            Content-Length: ContentLength
            ETag: ETag
            x-amz-version-id: VersionId
            Cache-Control: CacheControl
            Content-Range: ContentRange
            x-amz-date: 20240925T090917Z

            Body

Response Elements​

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

accept-ranges

Indicates that a range of bytes was specified in the request.

Cache-Control

Specifies caching behavior along the request/reply chain.

Content-Length

Size of the body in bytes.

Content-Range

The portion of the object returned in the response.

ETag

An entity tag (ETag) is an opaque identifier assigned by a web server to a specific version of a resource found at a URL.

Last-Modified

Date and time when the object was last modified.

The following data is returned in binary format by the service.

x-amz-delete-marker

Indicates whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.

note
  • If the current version of the object is a delete marker, Astran S3 behaves as if the object was deleted and includes x-amz-delete-marker: true in the response.
  • If the specified version in the request is a delete marker, the response returns a 405 Method Not Allowed error and the Last-Modified: timestamp response header.

x-amz-version-id

Version ID of the object.

Body

Errors​

NoSuchKey

The specified key does not exist.

HTTP Status Code: 404

Examples​

Sample Request for general purpose buckets​

The following request returns the object my-image.jpg.

            GET /bucket/my-image.jpg HTTP/1.1
            Host: <partition>.s3.astran.io
            Date: Mon, 25 Sep 2024 09:09:17 GMT
            Authorization: authorization string

Sample Response for general purpose buckets​

This example illustrates one usage of GetObject.


            HTTP/1.1 200 OK
            x-request-id: 318BC8BC148832E5
            x-amz-date: 20240925T090917Z
            Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
            ETag: "fba9dede5f27731c9771645a39863328"
            Content-Length: 434234

           [434234 bytes of object data]

Sample Request for general purpose buckets: Parameters altering response header values​

The following request specifies all the query string parameters in a GET request overriding the response header values.

            GET /bucket/Junk3.txt?response-cache-control=No-cache HTTP/1.1
            Date: Mon, 25 Sep 2024 09:09:17 GMT
            Accept: */*
            Authorization: AWS AKIAIOSFODNN7EXAMPLE:aaStE6nKnw8ihhiIdReoXYlMamW=

Sample Response for general purpose buckets: With overridden response header values​

The following request specifies all the query string parameters in a GET request overriding the response header values.

            HTTP/1.1 200 OK
            x-request-id: 881B1CBD9DF17WA1
            Date: Mon, 25 Sep 2024 09:09:17 GMT
            Cache-Control: No-cache
            Last-Modified: Fri, 17 Dec 2010 18:10:41 GMT
            ETag: "0332bee1a7bf845f176c5c0d1ae7cf07"
            Accept-Ranges: bytes
            Content-Length: 22

            [object data not shown]

Sample Request for general purpose buckets: Range header​

The following request specifies the HTTP Range header to retrieve the first 10 bytes of an object. For more information about the HTTP Range header, see https://www.rfc-editor.org/rfc/rfc9110.html#name-range.

note

Astran S3 doesn't support retrieving multiple ranges of data per GET request.

            GET /bucket/example-object HTTP/1.1
            Host: <partition>.s3.astran.io
            Date: Mon, 25 Sep 2024 09:09:17 GMT
            Range: bytes=0-9
            Authorization: AWS AKIAIOSFODNN7EXAMPLE:Yxg83MZaEgh3OZ3l0rLo5RTX11o=
            Sample Response with Specified Range of the Object Bytes

Sample Response for general purpose buckets​

In the following sample response, note that the header values are set to the values specified in the true request.

            HTTP/1.1 206 Partial Content
            x-request-id: 47622117804B3E11
            x-amz-date: 20240925T090917Z
            Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
            ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
            Accept-Ranges: bytes
            Content-Range: bytes 0-9/443
            Content-Length: 10

           [10 bytes of object data]

Sample Response for general purpose buckets: If the Latest Object Is a Delete Marker​

Notice that the delete marker returns a 404 Not Found error.

            HTTP/1.1 404 Not Found
            Content-Length: 191
            Content-Type: application/xml; charset=UTF-8
            x-amz-date: 20240925T090917Z
            Vary: Origin
            x-amz-version-id: some_version_id
            x-amz-delete-marker: true

            <?xml version="1.0" encoding="UTF-8"?>
            <Error>
                <Code>NoSuchKey</Code>
                <Message>object not found</Message>
                <Resource></Resource>
                <RequestId>38c0bc82-483a-4cca-b4c1-3aad095732be</RequestId>
            </Error>

Sample Request for general purpose buckets: Getting a specified version of an object​

The following request returns the specified version of an object.

            GET /bucket/myObject?versionId=some_version_id HTTP/1.1
            Host: <partition>.s3.astran.io
            Authorization: authorization string
            Date: Mon, 25 Sep 2024 09:09:17 GMT

Sample Response for general purpose buckets: GET a versioned object​

This example illustrates one usage of GetObject.

            HTTP/1.1 200 OK
            Content-Length:1024 
            Accept-Ranges: bytes
            Content-Type: binary/octet-stream
            x-amz-date: 20240925T090917Z
            Last-Modified: Wed, 25 Sep 2024 09:09:17 GMT
            Vary: Origin
            x-amz-version-id: some_version_id

            [1024 bytes of object data]

See Also​

For more information about using this API in one of the language-specific AWS SDKs, see the following: