Uploading an Object to a Bucket

You can upload a local object to a bucket to store it and create a backup in the Cloud, and possibly share it with other users.

As the storage capacity is only restricted by the storage platform itself, objects are not limited in size. You can upload an object whose size is from 1 byte to 5 GiB in a single command. However, it is recommended to upload objects of 100 MiB or more in several smaller parts in order to upload them faster. For more information, see Creating a Multipart Upload.
You can upload objects in your buckets or in a bucket another user shared with you. Other users can also upload objects in your bucket if you granted them the appropriate permissions. For more information, see Access Control List (ACL) Reference.

We recommend not exceeding 300 uploads per second in a single bucket.

You cannot change the key of an object once it is uploaded in the bucket. If you upload an object with the same key as another object already contained in the bucket, this object you upload replaces the former object. If bucket versioning is enabled, the former object is conserved as a previous version. For more information, see Enabling or Disabling Bucket Versioning.

By default, the objects you upload are private. However, you can share the objects that you uploaded in your bucket with other users setting an Access Control List (ACL). For more information, see Access Control List (ACL) Reference.

This action also returns an ETag element that you need to create a multipart-upload. For more information, see Creating a Multipart Upload.

Ensure not to set public read permissions for your sensitive data.

Uploading an Object to a Bucket Using AWS CLI (s3api)

Before you begin: Install and configure AWS CLI. For more information, see Installing and Configuring AWS CLI.

To upload a local object to a bucket, use the put-object command following this syntax:

Request sample

$ aws s3api put-object \
    --profile YOUR_PROFILE \
    --bucket BUCKET \
    --key OBJECT \
    --body usr/bin/YOUR_OBJECT \
    --acl private \
    --grant-full-control "id=USER_ID, id=USER_ID" \
    --grant-read "id=USER_ID, id=USER_ID" \
    --grant-read-acp "id=USER_ID, id=USER_ID" \
    --grant-write-acp "id=USER_ID, id=USER_ID" \
    --cache-control "no-cache" \
    --content-disposition "inline" \
    --content-encoding "gzip" \
    --content-language "en" \
    --content-type image/png \
    --content-length 42 \
    --expires "2024-03-01T00:00:00Z" \
    --metadata "{\"key1\": \"value1\", \"key2\": \"value2\"}" \
    --metadata-directive "COPY" \
    --website-redirect "/new-page.html" \
    --endpoint https://oos.eu-west-2.outscale.com

This command contains the following options that you need to specify:

(optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.
bucket: The bucket in which you want to upload the object.

key: The name you want to give to your object in the bucket.

You can use the same prefix in the keys of several objects in the following format: prefix/key1, prefix/key2, and so on.

This creates a virtual architecture in your bucket and enables you to retrieve your objects faster when listing them. For more information, see Listing the Objects of a Bucket.

body: The path to the object on your machine.

(optional) acl: The permissions you grant for your bucket (private | public-read | public-read-write | authenticated-read).

If you do not specify a permission for your bucket upon creation, it will automatically be set to private.
When specifying new permissions, all the previous permissions are replaced. Therefore, you need to specify both the existing permissions that you want to keep and the new permissions that you want to give in a single command.

For more information about existing permissions, see Getting Information About a Bucket ACL and Getting Information About an Object ACL.

(optional) grant-full-control: One or more IDs of users to whom you grant the full-control permission.
(optional) grant-read: One or more IDs of users to whom you grant the read permission.
(optional) grant-read-acp: One or more IDs of users to whom you grant the read-acp permission.
(optional) grant-write: One or more IDs of users to whom you grant the write permission.

(optional) grant-write-acp: One or more IDs of users to whom you grant the write-acp permission.

You need to specify S3 user IDs. You can retrieve S3 user IDs via the Listing Your Buckets and Listing the Objects of a Bucket methods.
You can also specify user email addresses using the emailaddress=name@domain.com format.

(optional) cache-control: How you want the object to be handled in terms of caching (max-age | max-stale | min-fresh | no-cache | no-store | no-transform | only-if-cached | stale-if-error).
(optional) content-disposition: How you want the object to be displayed when accessed via a browser ("inline" | "attachment" | "attachment; filename="<NAME_OF_DOWNLOADED_FILE>"").
- inline: When possible, prompts the browser to display the content within the browser window itself. This is useful for images, PDFs, and other media types that browsers can easily render.
- attachment: Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally.
- "attachment; filename="<NAME_OF_DOWNLOADED_FILE>"": Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally with the specified filename.
(optional) content-encoding: The encoding format of the object (gzip | compress | deflate | identity | br).
(optional) content-language: The language the content of the object is in, in language code (ISO 639 format).

(optional) content-type: The MIME (Multipurpose Internet Mail Extensions) type of the object.

An inaccurately set or absent content-type option can cause objects to be misinterpreted or mishandled by browsers. As a result, you may encounter difficulties accessing or viewing your objects using your preferred browser.

(optional) content-length: If the size cannot be defined automatically, the size of the object, in bytes.
(optional) expires: The date and time, in UTC format, at which you consider the object can no longer be cached, and is considered stale.
(optional) metadata: A map of additional metadata entries you can freely specify.
- key: The name of the metadata.
- value: The value of the metadata.
(optional) metadata-directive: Whether you want the metadata to be copied from the source objects or replaced with the metadata provided in the request (COPY or REPLACE).
(optional) website-redirect: If you configured the bucket as a website, redirects requests for this object to another object in the same bucket or to an external URL.
endpoint: The endpoint corresponding to the Region you want to send the request to. For more information, see Installing and Configuring AWS CLI.

The put-object command returns the following element:

Expiration: If a lifecycle rule has been applied to the object, returns details on its configuration. For more information, see Managing the Lifecycle of Your Buckets.
- expiry-date: The date and time at which the object is set to expire.
- rule-id: The name given to the lifecycle rule.
ETag: The ETag of your object, that you need to use the multipart upload commands. For more information, see Creating a Multipart Upload.
VersionId: If bucket versioning was enabled, the version ID of the object.

Result sample

{
    "Expiration": "expiry-date=\"Fri, 12 Jan 2024 09:30:08 GMT\", rule-id=\"id\"",
    "ETag": "\"fae0000b0d0000fababdd00e0a000000\"",
    "VersionId": "aJfWzV80O5rN00001000001I4j3QKItW"
}

The object is uploaded to the bucket.

Uploading an Object to a Bucket Using AWS CLI (s3)

Before you begin: Install and configure AWS CLI. For more information, see Installing and Configuring AWS CLI.

To upload a local object to a bucket, use the cp command following this syntax:

Request sample

$ aws s3 cp LOCAL_PATH/OBJECT_TO_UPLOAD s3://BUCKET/ \
   --profile YOUR_PROFILE \
   --debug \
   --dryrun \
   --acl private \
   --grant-full-control "id=USER_ID, id=USER_ID" \
   --grant-read "id=USER_ID, id=USER_ID" \
   --grant-read-acp "id=USER_ID, id=USER_ID" \
   --grant-write "id=USER_ID, id=USER_ID" \
   --cache-control "no-cache" \
   --content-disposition "inline" \
   --content-encoding "gzip" \
   --content-language "en" \
   --content-type image/png \
   --expires "2024-03-01T00:00:00Z" \
   --metadata "{\"key1\": \"value1\", \"key2\": \"value2"}\" \
   --copy-props none \
   --expected-size 1234 \
   --website-redirect "/new-page.html" \
   --endpoint https://oos.eu-west-2.outscale.com

This command contains the following options that you need to specify:

s3://BUCKET/OBJECT_TO_UPLOAD: The path to the object you want to upload in the bucket.
(optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.
(optional) debug: When included, returns the detailed log of the operation. This is useful to analyze and troubleshoot issues you may be encountering.
(optional) dryrun: Provides an overview of the operations performed by the command without actually running it. This is used as a safety measure to review the impact of a command before executing it.

(optional) acl: The permissions you grant for your bucket (private | public-read | public-read-write | authenticated-read).

If you do not specify a permission for your bucket upon creation, it will automatically be set to private.
When specifying new permissions, all the previous permissions are replaced. Therefore, you need to specify both the existing permissions that you want to keep and the new permissions that you want to give in a single command.

For more information about existing permissions, see Getting Information About a Bucket ACL and Getting Information About an Object ACL.

(optional) grant-full-control: One or more IDs of users to whom you grant the full-control permission.
(optional) grant-read: One or more IDs of users to whom you grant the read permission.
(optional) grant-read-acp: One or more IDs of users to whom you grant the read-acp permission.
(optional) grant-write: One or more IDs of users to whom you grant the write permission.

(optional) grant-write-acp: One or more IDs of users to whom you grant the write-acp permission.

You need to specify S3 user IDs. You can retrieve S3 user IDs via the Listing Your Buckets and Listing the Objects of a Bucket methods.
You can also specify user email addresses using the emailaddress=name@domain.com format.

(optional) cache-control: How you want the object to be handled in terms of caching (max-age | max-stale | min-fresh | no-cache | no-store | no-transform | only-if-cached | stale-if-error).
(optional) content-disposition: How you want the object to be displayed when accessed via a browser ("inline" | "attachment" | "attachment; filename="<NAME_OF_DOWNLOADED_FILE>"").
- inline: When possible, prompts the browser to display the content within the browser window itself. This is useful for images, PDFs, and other media types that browsers can easily render.
- attachment: Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally.
- "attachment; filename="<NAME_OF_DOWNLOADED_FILE>"": Regardless of file type, prompts the browser to download the content instead of displaying it inline. The file is thus saved locally with the specified filename.
(optional) content-encoding: The encoding format of the object (gzip | compress | deflate | identity | br).
(optional) content-language: The language the content of the object is in, in language code (ISO 639 format).

(optional) content-type: The MIME (Multipurpose Internet Mail Extensions) type of the object.

(optional) expires: The date and time, in UTC format, at which you consider the object can no longer be cached, and is considered stale.
(optional) metadata: A map of additional metadata entries you can freely specify.
- key: The name of the metadata.
- value: The value of the metadata.
(optional) expected-size: If the object is larger than 50GB, specifies the expected size of the upload, in bytes. This is useful if you want to confirm the integrity or the expected size of the file being downloaded. For more information, see Tutorial: Using Multipart Upload With AWS CLI (s3).
(optional) website-redirect: If you configured the bucket as a website, redirects requests for this object to another object in the same bucket or to an external URL.
endpoint: The endpoint corresponding to the Region you want to send the request to. For more information, see Installing and Configuring AWS CLI.

Your object is uploaded to the bucket.

Uploading an Object to a Bucket Using s3cmd

You can manage your object storage resources using s3cmd commands. For more information, see s3cmd.

Related Pages

AWS™ and Amazon Web Services™ are trademarks of Amazon Technologies, Inc or its affiliates in the United States and/or other countries.