import { EndpointParameterInstructions } from "@aws-sdk/middleware-endpoint"; import { Command as $Command } from "@aws-sdk/smithy-client"; import { Handler, HttpHandlerOptions as __HttpHandlerOptions, MetadataBearer as __MetadataBearer, MiddlewareStack, WithSdkStreamMixin as __WithSdkStreamMixin } from "@aws-sdk/types"; import { GetObjectOutput, GetObjectRequest } from "../models/models_0"; import { S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../S3Client"; /** * @public */ export { __MetadataBearer, $Command }; /** * @public * * The input for {@link GetObjectCommand}. */ export interface GetObjectCommandInput extends GetObjectRequest { } /** * @public * * The output of {@link GetObjectCommand}. */ export interface GetObjectCommandOutput extends __WithSdkStreamMixin, __MetadataBearer { } /** * @public *

Retrieves objects from Amazon S3. To use GET, you must have READ * access to the object. If you grant READ access to the anonymous user, you can * return the object without using an authorization header.

*

An Amazon S3 bucket has no directory hierarchy such as you would find in a typical computer * file system. You can, however, create a logical hierarchy by using object key names that * imply a folder structure. For example, instead of naming an object sample.jpg, * you can name it photos/2006/February/sample.jpg.

*

To get an object from such a logical hierarchy, specify the full key name for the object * in the GET operation. For a virtual hosted-style request example, if you have * the object photos/2006/February/sample.jpg, specify the resource as * /photos/2006/February/sample.jpg. For a path-style request example, if you * have the object photos/2006/February/sample.jpg in the bucket named * examplebucket, specify the resource as * /examplebucket/photos/2006/February/sample.jpg. For more information about * request types, see HTTP Host * Header Bucket Specification.

*

For more information about returning the ACL of an object, see GetObjectAcl.

*

If the object you are retrieving is stored in the S3 Glacier Flexible Retrieval or * S3 Glacier Deep Archive storage class, or S3 Intelligent-Tiering Archive or * S3 Intelligent-Tiering Deep Archive tiers, before you can retrieve the object you must first restore a * copy using RestoreObject. Otherwise, this action returns an * InvalidObjectState error. For information about restoring archived objects, * see Restoring * Archived Objects.

*

Encryption request headers, like x-amz-server-side-encryption, should not * be sent for GET requests if your object uses server-side encryption with Key Management Service (KMS) * keys (SSE-KMS), dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), or * server-side encryption with Amazon S3 managed encryption keys (SSE-S3). If your object does use * these types of keys, you’ll get an HTTP 400 Bad Request error.

*

If you encrypt an object by using server-side encryption with customer-provided * encryption keys (SSE-C) when you store the object in Amazon S3, then when you GET the object, * you must use the following headers:

* *

For more information about SSE-C, see Server-Side Encryption * (Using Customer-Provided Encryption Keys).

*

Assuming you have the relevant permission to read object tags, the response also returns * the x-amz-tagging-count header that provides the count of number of tags * associated with the object. You can use GetObjectTagging to retrieve * the tag set associated with an object.

*
*
Permissions
*
*

You need the relevant read object (or version) permission for this operation. For more * information, see Specifying Permissions in a * Policy. If the object that you request doesn’t exist, the error that Amazon S3 returns depends * on whether you also have the s3:ListBucket permission.

*

If you have the s3:ListBucket permission on the bucket, Amazon S3 * returns an HTTP status code 404 (Not Found) error.

*

If you don’t have the s3:ListBucket permission, Amazon S3 returns an * HTTP status code 403 ("access denied") error.

*
*
Versioning
*
*

By default, the GET action returns the current version of an object. To return a * different version, use the versionId subresource.

* *
    *
  • *

    If you supply a versionId, you need the * s3:GetObjectVersion permission to access a specific version of an * object. If you request a specific version, you do not need to have the * s3:GetObject permission. If you request the current version * without a specific version ID, only s3:GetObject permission is * required. s3:GetObjectVersion permission won't be required.

    *
    • *
  • *

    If the current version of the object is a delete marker, Amazon S3 behaves as if the * object was deleted and includes x-amz-delete-marker: true in the * response.

    *
    • *
* *

For more information about versioning, see PutBucketVersioning.

*
*
Overriding Response Header Values
*
*

There are times when you want to override certain response header values in a GET * response. For example, you might override the Content-Disposition response * header value in your GET request.

*

You can override values for a set of response headers using the following query * parameters. These response header values are sent only on a successful request, that is, * when status code 200 OK is returned. The set of headers you can override using these * parameters is a subset of the headers that Amazon S3 accepts when you create an object. The * response headers that you can override for the GET response are Content-Type, * Content-Language, Expires, Cache-Control, * Content-Disposition, and Content-Encoding. To override these * header values in the GET response, you use the following request parameters.

* *

You must sign the request, either using an Authorization header or a presigned URL, * when using these parameters. They cannot be used with an unsigned (anonymous) * request.

* *
    *
  • *

    * response-content-type *

    *
    • *
  • *

    * response-content-language *

    *
    • *
  • *

    * response-expires *

    *
    • *
  • *

    * response-cache-control *

    *
    • *
  • *

    * response-content-disposition *

    *
    • *
  • *

    * response-content-encoding *

    *
    • *
*
*
Overriding Response Header Values
*
*

If both of the If-Match and If-Unmodified-Since headers are * present in the request as follows: If-Match condition evaluates to * true, and; If-Unmodified-Since condition evaluates to * false; then, S3 returns 200 OK and the data requested.

*

If both of the If-None-Match and If-Modified-Since headers are * present in the request as follows: If-None-Match condition evaluates to * false, and; If-Modified-Since condition evaluates to * true; then, S3 returns 304 Not Modified response code.

*

For more information about conditional requests, see RFC 7232.

*
*
*

The following operations are related to GetObject:

* * @example * Use a bare-bones client and the command you need to make an API call. * ```javascript * import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"; // ES Modules import * // const { S3Client, GetObjectCommand } = require("@aws-sdk/client-s3"); // CommonJS import * const client = new S3Client(config); * const input = { // GetObjectRequest * Bucket: "STRING_VALUE", // required * IfMatch: "STRING_VALUE", * IfModifiedSince: new Date("TIMESTAMP"), * IfNoneMatch: "STRING_VALUE", * IfUnmodifiedSince: new Date("TIMESTAMP"), * Key: "STRING_VALUE", // required * Range: "STRING_VALUE", * ResponseCacheControl: "STRING_VALUE", * ResponseContentDisposition: "STRING_VALUE", * ResponseContentEncoding: "STRING_VALUE", * ResponseContentLanguage: "STRING_VALUE", * ResponseContentType: "STRING_VALUE", * ResponseExpires: new Date("TIMESTAMP"), * VersionId: "STRING_VALUE", * SSECustomerAlgorithm: "STRING_VALUE", * SSECustomerKey: "STRING_VALUE", * SSECustomerKeyMD5: "STRING_VALUE", * RequestPayer: "requester", * PartNumber: Number("int"), * ExpectedBucketOwner: "STRING_VALUE", * ChecksumMode: "ENABLED", * }; * const command = new GetObjectCommand(input); * const response = await client.send(command); * // { // GetObjectOutput * // Body: "STREAMING_BLOB_VALUE", * // DeleteMarker: true || false, * // AcceptRanges: "STRING_VALUE", * // Expiration: "STRING_VALUE", * // Restore: "STRING_VALUE", * // LastModified: new Date("TIMESTAMP"), * // ContentLength: Number("long"), * // ETag: "STRING_VALUE", * // ChecksumCRC32: "STRING_VALUE", * // ChecksumCRC32C: "STRING_VALUE", * // ChecksumSHA1: "STRING_VALUE", * // ChecksumSHA256: "STRING_VALUE", * // MissingMeta: Number("int"), * // VersionId: "STRING_VALUE", * // CacheControl: "STRING_VALUE", * // ContentDisposition: "STRING_VALUE", * // ContentEncoding: "STRING_VALUE", * // ContentLanguage: "STRING_VALUE", * // ContentRange: "STRING_VALUE", * // ContentType: "STRING_VALUE", * // Expires: new Date("TIMESTAMP"), * // WebsiteRedirectLocation: "STRING_VALUE", * // ServerSideEncryption: "AES256" || "aws:kms" || "aws:kms:dsse", * // Metadata: { // Metadata * // "": "STRING_VALUE", * // }, * // SSECustomerAlgorithm: "STRING_VALUE", * // SSECustomerKeyMD5: "STRING_VALUE", * // SSEKMSKeyId: "STRING_VALUE", * // BucketKeyEnabled: true || false, * // StorageClass: "STANDARD" || "REDUCED_REDUNDANCY" || "STANDARD_IA" || "ONEZONE_IA" || "INTELLIGENT_TIERING" || "GLACIER" || "DEEP_ARCHIVE" || "OUTPOSTS" || "GLACIER_IR" || "SNOW", * // RequestCharged: "requester", * // ReplicationStatus: "COMPLETE" || "PENDING" || "FAILED" || "REPLICA", * // PartsCount: Number("int"), * // TagCount: Number("int"), * // ObjectLockMode: "GOVERNANCE" || "COMPLIANCE", * // ObjectLockRetainUntilDate: new Date("TIMESTAMP"), * // ObjectLockLegalHoldStatus: "ON" || "OFF", * // }; * * ``` * * @param GetObjectCommandInput - {@link GetObjectCommandInput} * @returns {@link GetObjectCommandOutput} * @see {@link GetObjectCommandInput} for command's `input` shape. * @see {@link GetObjectCommandOutput} for command's `response` shape. * @see {@link S3ClientResolvedConfig | config} for S3Client's `config` shape. * * @throws {@link InvalidObjectState} (client fault) *

Object is archived and inaccessible until restored.

* * @throws {@link NoSuchKey} (client fault) *

The specified key does not exist.

* * @throws {@link S3ServiceException} *

Base exception class for all service exceptions from S3 service.

* * @example To retrieve a byte range of an object * ```javascript * // The following example retrieves an object for an S3 bucket. The request specifies the range header to retrieve a specific byte range. * const input = { * "Bucket": "examplebucket", * "Key": "SampleFile.txt", * "Range": "bytes=0-9" * }; * const command = new GetObjectCommand(input); * const response = await client.send(command); * /* response == * { * "AcceptRanges": "bytes", * "ContentLength": "10", * "ContentRange": "bytes 0-9/43", * "ContentType": "text/plain", * "ETag": "\"0d94420ffd0bc68cd3d152506b97a9cc\"", * "LastModified": "Thu, 09 Oct 2014 22:57:28 GMT", * "Metadata": {}, * "VersionId": "null" * } * *\/ * // example id: to-retrieve-a-byte-range-of-an-object--1481832674603 * ``` * * @example To retrieve an object * ```javascript * // The following example retrieves an object for an S3 bucket. * const input = { * "Bucket": "examplebucket", * "Key": "HappyFace.jpg" * }; * const command = new GetObjectCommand(input); * const response = await client.send(command); * /* response == * { * "AcceptRanges": "bytes", * "ContentLength": "3191", * "ContentType": "image/jpeg", * "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"", * "LastModified": "Thu, 15 Dec 2016 01:19:41 GMT", * "Metadata": {}, * "TagCount": 2, * "VersionId": "null" * } * *\/ * // example id: to-retrieve-an-object-1481827837012 * ``` * */ export declare class GetObjectCommand extends $Command { readonly input: GetObjectCommandInput; static getEndpointParameterInstructions(): EndpointParameterInstructions; /** * @public */ constructor(input: GetObjectCommandInput); /** * @internal */ resolveMiddleware(clientStack: MiddlewareStack, configuration: S3ClientResolvedConfig, options?: __HttpHandlerOptions): Handler; /** * @internal */ private serialize; /** * @internal */ private deserialize; }