=================== Bucket Operations =================== PUT Bucket ---------- Creates a new bucket. To create a bucket, you must have a user ID and a valid AWS Access Key ID to authenticate requests. You may not create buckets as an anonymous user. .. note:: We do not support request entities for ``PUT /{bucket}`` in this release. Constraints ~~~~~~~~~~~ In general, bucket names should follow domain name constraints. - Bucket names must be unique. - Bucket names must begin and end with a lowercase letter. - Bucket names may contain a dash (-). Syntax ~~~~~~ :: PUT /{bucket} HTTP/1.1 Host: cname.domain.com x-amz-acl: public-read-write Authorization: AWS {access-key}:{hash-of-header-and-secret} Parameters ~~~~~~~~~~ +---------------+----------------------+-----------------------------------------------------------------------------+------------+ | Name | Description | Valid Values | Required | +===============+======================+=============================================================================+============+ | ``x-amz-acl`` | Canned ACLs. | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read`` | No | +---------------+----------------------+-----------------------------------------------------------------------------+------------+ HTTP Response ~~~~~~~~~~~~~ If the bucket name is unique, within constraints and unused, the operation will succeed. If a bucket with the same name already exists and the user is the bucket owner, the operation will succeed. If the bucket name is already in use, the operation will fail. +---------------+-----------------------+----------------------------------------------------------+ | HTTP Status | Status Code | Description | +===============+=======================+==========================================================+ | ``409`` | BucketAlreadyExists | Bucket already exists under different user's ownership. | +---------------+-----------------------+----------------------------------------------------------+ DELETE Bucket ------------- Deletes a bucket. You can reuse bucket names following a successful bucket removal. Syntax ~~~~~~ :: DELETE /{bucket} HTTP/1.1 Host: cname.domain.com Authorization: AWS {access-key}:{hash-of-header-and-secret} HTTP Response ~~~~~~~~~~~~~ +---------------+---------------+------------------+ | HTTP Status | Status Code | Description | +===============+===============+==================+ | ``204`` | No Content | Bucket removed. | +---------------+---------------+------------------+ GET Bucket ---------- Returns a list of bucket objects. Syntax ~~~~~~ :: GET /{bucket}?max-keys=25 HTTP/1.1 Host: cname.domain.com Parameters ~~~~~~~~~~ +-----------------+-----------+-----------------------------------------------------------------------+ | Name | Type | Description | +=================+===========+=======================================================================+ | ``prefix`` | String | Only returns objects that contain the specified prefix. | +-----------------+-----------+-----------------------------------------------------------------------+ | ``delimiter`` | String | The delimiter between the prefix and the rest of the object name. | +-----------------+-----------+-----------------------------------------------------------------------+ | ``marker`` | String | A beginning index for the list of objects returned. | +-----------------+-----------+-----------------------------------------------------------------------+ | ``max-keys`` | Integer | The maximum number of keys to return. Default is 1000. | +-----------------+-----------+-----------------------------------------------------------------------+ HTTP Response ~~~~~~~~~~~~~ +---------------+---------------+--------------------+ | HTTP Status | Status Code | Description | +===============+===============+====================+ | ``200`` | OK | Buckets retrieved | +---------------+---------------+--------------------+ Bucket Response Entities ~~~~~~~~~~~~~~~~~~~~~~~~ ``GET /{bucket}`` returns a container for buckets with the following fields. +------------------------+-----------+----------------------------------------------------------------------------------+ | Name | Type | Description | +========================+===========+==================================================================================+ | ``ListBucketResult`` | Entity | The container for the list of objects. | +------------------------+-----------+----------------------------------------------------------------------------------+ | ``Name`` | String | The name of the bucket whose contents will be returned. | +------------------------+-----------+----------------------------------------------------------------------------------+ | ``Prefix`` | String | A prefix for the object keys. | +------------------------+-----------+----------------------------------------------------------------------------------+ | ``Marker`` | String | A beginning index for the list of objects returned. | +------------------------+-----------+----------------------------------------------------------------------------------+ | ``MaxKeys`` | Integer | The maximum number of keys returned. | +------------------------+-----------+----------------------------------------------------------------------------------+ | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | +------------------------+-----------+----------------------------------------------------------------------------------+ | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's contents were returned. | +------------------------+-----------+----------------------------------------------------------------------------------+ | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | +------------------------+-----------+----------------------------------------------------------------------------------+ Object Response Entities ~~~~~~~~~~~~~~~~~~~~~~~~ The ``ListBucketResult`` contains objects, where each object is within a ``Contents`` container. +------------------------+-----------+------------------------------------------+ | Name | Type | Description | +========================+===========+==========================================+ | ``Contents`` | Object | A container for the object. | +------------------------+-----------+------------------------------------------+ | ``Key`` | String | The object's key. | +------------------------+-----------+------------------------------------------+ | ``LastModified`` | Date | The object's last-modified date/time. | +------------------------+-----------+------------------------------------------+ | ``ETag`` | String | An MD-5 hash of the object. (entity tag) | +------------------------+-----------+------------------------------------------+ | ``Size`` | Integer | The object's size. | +------------------------+-----------+------------------------------------------+ | ``StorageClass`` | String | Should always return ``STANDARD``. | +------------------------+-----------+------------------------------------------+ Get Bucket Location ------------------- Retrieves the bucket's region. The user needs to be the bucket owner to call this. A bucket can be constrained to a region by providing ``LocationConstraint`` during a PUT request. Syntax ~~~~~~ Add the ``location`` subresource to bucket resource as shown below :: GET /{bucket}?location HTTP/1.1 Host: cname.domain.com Authorization: AWS {access-key}:{hash-of-header-and-secret} Response Entities ~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------+-----------+------------------------------------------+ | Name | Type | Description | +========================+===========+==========================================+ | ``LocationConstraint`` | String | The region where bucket resides, empty | | | | string for defult region | +------------------------+-----------+------------------------------------------+ Get Bucket ACL -------------- Retrieves the bucket access control list. The user needs to be the bucket owner or to have been granted ``READ_ACP`` permission on the bucket. Syntax ~~~~~~ Add the ``acl`` subresource to the bucket request as shown below. :: GET /{bucket}?acl HTTP/1.1 Host: cname.domain.com Authorization: AWS {access-key}:{hash-of-header-and-secret} Response Entities ~~~~~~~~~~~~~~~~~ +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | Name | Type | Description | +===========================+=============+==============================================================================================+ | ``AccessControlPolicy`` | Container | A container for the response. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``AccessControlList`` | Container | A container for the ACL information. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``ID`` | String | The bucket owner's ID. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``DisplayName`` | String | The bucket owner's display name. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ PUT Bucket ACL -------------- Sets an access control to an existing bucket. The user needs to be the bucket owner or to have been granted ``WRITE_ACP`` permission on the bucket. Syntax ~~~~~~ Add the ``acl`` subresource to the bucket request as shown below. :: PUT /{bucket}?acl HTTP/1.1 Request Entities ~~~~~~~~~~~~~~~~ +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | Name | Type | Description | +===========================+=============+==============================================================================================+ | ``AccessControlPolicy`` | Container | A container for the request. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``AccessControlList`` | Container | A container for the ACL information. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Owner`` | Container | A container for the bucket owner's ``ID`` and ``DisplayName``. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``ID`` | String | The bucket owner's ID. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``DisplayName`` | String | The bucket owner's display name. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Grant`` | Container | A container for ``Grantee`` and ``Permission``. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Grantee`` | Container | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ | ``Permission`` | String | The permission given to the ``Grantee`` bucket. | +---------------------------+-------------+----------------------------------------------------------------------------------------------+ List Bucket Multipart Uploads ----------------------------- ``GET /?uploads`` returns a list of the current in-progress multipart uploads--i.e., the application initiates a multipart upload, but the service hasn't completed all the uploads yet. Syntax ~~~~~~ :: GET /{bucket}?uploads HTTP/1.1 Parameters ~~~~~~~~~~ You may specify parameters for ``GET /{bucket}?uploads``, but none of them are required. +------------------------+-----------+--------------------------------------------------------------------------------------+ | Name | Type | Description | +========================+===========+======================================================================================+ | ``prefix`` | String | Returns in-progress uploads whose keys contains the specified prefix. | +------------------------+-----------+--------------------------------------------------------------------------------------+ | ``delimiter`` | String | The delimiter between the prefix and the rest of the object name. | +------------------------+-----------+--------------------------------------------------------------------------------------+ | ``key-marker`` | String | The beginning marker for the list of uploads. | +------------------------+-----------+--------------------------------------------------------------------------------------+ | ``max-keys`` | Integer | The maximum number of in-progress uploads. The default is 1000. | +------------------------+-----------+--------------------------------------------------------------------------------------+ | ``max-uploads`` | Integer | The maximum number of multipart uploads. The range from 1-1000. The default is 1000. | +------------------------+-----------+--------------------------------------------------------------------------------------+ | ``upload-id-marker`` | String | Ignored if ``key-marker`` isn't specified. Specifies the ``ID`` of first | | | | upload to list in lexicographical order at or following the ``ID``. | +------------------------+-----------+--------------------------------------------------------------------------------------+ Response Entities ~~~~~~~~~~~~~~~~~ +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | Name | Type | Description | +=========================================+=============+==========================================================================================================+ | ``ListMultipartUploadsResult`` | Container | A container for the results. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``ListMultipartUploadsResult.Prefix`` | String | The prefix specified by the ``prefix`` request parameter (if any). | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``Bucket`` | String | The bucket that will receive the bucket contents. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``KeyMarker`` | String | The key marker specified by the ``key-marker`` request parameter (if any). | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``UploadIdMarker`` | String | The marker specified by the ``upload-id-marker`` request parameter (if any). | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``NextKeyMarker`` | String | The key marker to use in a subsequent request if ``IsTruncated`` is ``true``. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``NextUploadIdMarker`` | String | The upload ID marker to use in a subsequent request if ``IsTruncated`` is ``true``. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``MaxUploads`` | Integer | The max uploads specified by the ``max-uploads`` request parameter. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``Delimiter`` | String | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``IsTruncated`` | Boolean | If ``true``, only a subset of the bucket's upload contents were returned. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``Upload`` | Container | A container for ``Key``, ``UploadId``, ``InitiatorOwner``, ``StorageClass``, and ``Initiated`` elements. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``Key`` | String | The key of the object once the multipart upload is complete. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``UploadId`` | String | The ``ID`` that identifies the multipart upload. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``Initiator`` | Container | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``DisplayName`` | String | The initiator's display name. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``ID`` | String | The initiator's ID. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``Owner`` | Container | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``StorageClass`` | String | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY`` | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``Initiated`` | Date | The date and time the user initiated the upload. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``CommonPrefixes`` | Container | If multiple objects contain the same prefix, they will appear in this list. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+ | ``CommonPrefixes.Prefix`` | String | The substring of the key after the prefix as defined by the ``prefix`` request parameter. | +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+