Связаться с намиПодключиться

Object Storage API, REST: Bucket methods

Статья создана
Обновлена 12 марта 2024 г.

A set of methods for managing buckets.

JSON Representation

{
  "id": "string",
  "name": "string",
  "folderId": "string",
  "anonymousAccessFlags": {
    "read": true,
    "list": true,
    "configRead": true
  },
  "defaultStorageClass": "string",
  "versioning": "string",
  "maxSize": "string",
  "policy": "object",
  "acl": {
    "grants": [
      {
        "permission": "string",
        "grantType": "string",
        "granteeId": "string"
      }
    ]
  },
  "createdAt": "string",
  "cors": [
    {
      "id": "string",
      "allowedMethods": [
        "string"
      ],
      "allowedHeaders": [
        "string"
      ],
      "allowedOrigins": [
        "string"
      ],
      "exposeHeaders": [
        "string"
      ],
      "maxAgeSeconds": "integer"
    }
  ],
  "websiteSettings": {
    "index": "string",
    "error": "string",
    "redirectAllRequests": {
      "protocol": "string",
      "hostname": "string"
    },
    "routingRules": [
      {
        "condition": {
          "httpErrorCodeReturnedEquals": "string",
          "keyPrefixEquals": "string"
        },
        "redirect": {
          "hostname": "string",
          "httpRedirectCode": "string",
          "protocol": "string",
          "replaceKeyPrefixWith": "string",
          "replaceKeyWith": "string"
        }
      }
    ]
  },
  "lifecycleRules": [
    {
      "id": "string",
      "enabled": true,
      "filter": {
        "prefix": "string",
        "objectSizeGreaterThan": "integer",
        "objectSizeLessThan": "integer",
        "tag": {
          "key": "string",
          "value": "string"
        },
        "andOperator": {
          "prefix": "string",
          "objectSizeGreaterThan": "integer",
          "objectSizeLessThan": "integer",
          "tag": [
            {
              "key": "string",
              "value": "string"
            }
          ]
        }
      },
      "expiration": {
        "date": "string",
        "days": "integer",
        "expiredObjectDeleteMarker": true
      },
      "transitions": [
        {
          "date": "string",
          "days": "integer",
          "storageClass": "string"
        }
      ],
      "abortIncompleteMultipartUpload": {
        "daysAfterExpiration": "integer"
      },
      "noncurrentExpiration": {
        "noncurrentDays": "integer"
      },
      "noncurrentTransitions": [
        {
          "noncurrentDays": "integer",
          "storageClass": "string"
        }
      ],
      "noncurrentDeleteMarkers": {
        "noncurrentDays": "integer"
      }
    }
  ],
  "tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "objectLock": {
    "status": "string",
    "defaultRetention": {
      "mode": "string",

      // `objectLock.defaultRetention` includes only one of the fields `days`, `years`
      "days": "string",
      "years": "string",
      // end of the list of possible fields`objectLock.defaultRetention`

    }
  },
  "encryption": {
    "rules": [
      {
        "kmsMasterKeyId": "string",
        "sseAlgorithm": "string"
      }
    ]
  }
}
Field Description
id string

ID of the bucket. Always equal to name, which has priority.
name string

Name of the bucket.

The name is unique within the platform. For naming limitations and rules, see documentation.
folderId string

ID of the folder that the bucket belongs to.
anonymousAccessFlags object

Flags for configuring public (anonymous) access to the bucket's content and settings. For details, see documentation.
anonymousAccessFlags.
read		 boolean (boolean)

Specifies whether public (anonymous) access to read objects in the bucket is enabled.
anonymousAccessFlags.
list		 boolean (boolean)

Specifies whether public (anonymous) access to the list of objects in the bucket is enabled.
anonymousAccessFlags.
configRead		 boolean (boolean)

Specifies whether public (anonymous) access to read CORS, static website hosting, and object lifecycles settings of the bucket is enabled.
defaultStorageClass string

Default storage class for objects in the bucket. Supported classes are standard storage (STANDARD), cold storage (COLD, STANDARD_IA, NEARLINE all synonyms), and ice storage (ICE and GLACIER are synonyms). For details, see documentation.
versioning string

Bucket versioning status. For details, see documentation.

  • VERSIONING_DISABLED: The bucket is unversioned, i.e. versioning has never been enabled for the bucket, including at its creation. Objects that are stored in the bucket have a version ID of null.

    To enable versioning, change status to VERSIONING_ENABLED via a update request. Note that this action is irreversible, and a bucket with versioning enabled can never return to VERSIONING_DISABLED state.

  • VERSIONING_ENABLED: Bucket versioning is enabled, i.e. all new objects are versioned and given a unique version ID, and objects that already existed at the time versioning was enabled will be versioned and given a unique version ID when modified by future requests.

    To suspend versioning, change status to VERSIONING_SUSPENDED via a update request. You cannot disable versioning altogether for a bucket that already had it enabled; objects that had version IDs will keep them.

  • VERSIONING_SUSPENDED: Bucket versioning is suspended, i.e. new objects are not versioned, but objects that already existed at the time versioning was suspended are still versioned and keep their version IDs.

    To resume versioning, change status to VERSIONING_ENABLED via a update request.
maxSize string (int64)

Maximum size of the bucket, in bytes. For details, see documentation.
policy object

Bucket policies that set permissions for actions with the bucket, its objects, and groups of objects. For details, see documentation.
acl object

Access control list (ACL) of the bucket. For details, see documentation.
acl.
grants[]		 object

List of permissions granted and the grantees.
acl.
grants[].
permission		 string

Required. Permission granted by the grant.

  • PERMISSION_FULL_CONTROL: Allows grantee the PERMISSION_WRITE, PERMISSION_WRITE_ACP, PERMISSION_READ, and PERMISSION_READ_ACP on the bucket.

    Maps to x-amz-grant-full-control header for bucketPutAcl method of Amazon S3-compatible HTTP API.

  • PERMISSION_WRITE: Allows grantee to create new objects in the bucket. For the bucket and object owners of existing objects, also allows deletions and overwrites of those objects.

    Maps to x-amz-grant-write header for bucketPutAcl method of Amazon S3-compatible HTTP API.

  • PERMISSION_WRITE_ACP: Allows grantee to write the ACL for the bucket.

    Maps to x-amz-grant-write-acp header for bucketPutAcl method of Amazon S3-compatible HTTP API.

  • PERMISSION_READ: Allows grantee to list the objects in the bucket.

    Maps to x-amz-grant-read header for bucketPutAcl method of Amazon S3-compatible HTTP API.

  • PERMISSION_READ_ACP: Allows grantee to read the bucket ACL

    Maps to x-amz-grant-read-acp header for bucketPutAcl method of Amazon S3-compatible HTTP API.
acl.
grants[].
grantType		 string

Required. The grantee type for the grant.

  • GRANT_TYPE_ACCOUNT: A grantee is an account on the platform.

    For this grantee type, you need to specify the user ID in Bucket.acl.grants.granteeId field. To get user ID, see instruction.

    Maps to using id="*" value for x-amz-grant-* header (bucketPutAcl method of Amazon S3-compatible HTTP API).

  • GRANT_TYPE_ALL_AUTHENTICATED_USERS: Grantees are all authenticated users, both from your clouds and other users' clouds. Access permission to this group allows any account on the platform to access the resource via a signed (authenticated) request.

    Maps to using uri="http://acs.amazonaws.com/groups/global/AuthenticatedUsers" value for x-amz-grant-* header (bucketPutAcl method of Amazon S3-compatible HTTP API).

  • GRANT_TYPE_ALL_USERS: Grantees are all internet users. Access permission to this group allows anyone in the world access to the resource via signed (authenticated) or unsigned (anonymous) requests.

    Maps to using uri="http://acs.amazonaws.com/groups/global/AllUsers" value for x-amz-grant-* header (bucketPutAcl method of Amazon S3-compatible HTTP API).
acl.
grants[].
granteeId		 string

ID of the account who is a grantee. Required when the grantType is GRANT_TYPE_ACCOUNT.
createdAt string (date-time)

Creation timestamp.

String in RFC3339 text format. The range of possible values is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
cors[] object

List of rules for cross-domain requests to objects in the bucket (cross-origin resource sharing, CORS). For details, see documentation.
cors[].
id		 string

ID of the CORS rule.
cors[].
allowedMethods[]		 string

Required. List of HTTP methods allowed by the CORS rule.

When a client sends a CORS-preflight options request with the Access-Control-Request-Method header (see S3-compatible API reference), the specified method is checked against the list of the allowed methods. If there is a match, all the allowed methods are listed in the Access-Control-Allow-Methods header of the response.

Must contain at least one element.

  • METHOD_GET: HTTP GET method.
  • METHOD_HEAD: HTTP HEAD method.
  • METHOD_POST: HTTP POST method.
  • METHOD_PUT: HTTP PUT method.
  • METHOD_DELETE: HTTP DELETE method.
cors[].
allowedHeaders[]		 string

List of HTTP headers allowed by the CORS rule.

When a client sends a CORS-preflight options request with the Access-Control-Request-Headers header (see S3-compatible API reference), the specified headers are checked against the list of the allowed headers. If there is a match, the specified headers that are allowed are listed in the Access-Control-Allow-Headers header of the response.

Each string in the list can contain at most one * wildcard character that matches 0 or more characters. For example, x-amz-* value will allow all Amazon S3-compatible headers.
cors[].
allowedOrigins[]		 string

Required. List of request origins allowed by the CORS rule.

Each string in the list can contain at most one * wildcard character that matches 0 or more characters. For example, http://*.example.com value will allow requests originating from all subdomains of example.com.

Must contain at least one element.
cors[].
exposeHeaders[]		 string

List of headers contained in responses to CORS requests that can be accessed by applications.
cors[].
maxAgeSeconds		 integer (int64)

Time in seconds that a client can cache the response to a CORS-preflight request as identified by the object requested, the HTTP method, and the origin.
websiteSettings object

Configuration for hosting a static website in the bucket. For details, see documentation.
websiteSettings.
index		 string

Key of the index page object that is returned when a response is made to the root of the website.

Either index or redirectAllRequests must be specified in order for the bucket to host a static website.

If specified, the index page object must be located in the root of the bucket.
websiteSettings.
error		 string

Key of the error page object that is returned when an error occurs.
websiteSettings.
redirectAllRequests		 object

Configuration for redirecting all requests sent to the website.

Either redirectAllRequests or index must be specified in order for the bucket to host a static website. If redirectAllRequests is specified, it must be the only field in Bucket.websiteSettings.

A configuration resource for redirecting all requests sent to the website.
websiteSettings.
redirectAllRequests.
protocol		 string

Scheme of the redirect URI.

  • PROTOCOL_HTTP: http scheme.
  • PROTOCOL_HTTPS: https scheme.
websiteSettings.
redirectAllRequests.
hostname		 string

Hostname of the redirect URI.
websiteSettings.
routingRules[]		 object

List of redirect rules.
websiteSettings.
routingRules[].
condition		 object

Redirect condition.
websiteSettings.
routingRules[].
condition.
httpErrorCodeReturnedEquals		 string

HTTP status code (number only) that must match for the redirect to apply.
websiteSettings.
routingRules[].
condition.
keyPrefixEquals		 string

Prefix of the object key from which requests are redirected.
websiteSettings.
routingRules[].
redirect		 object

Redirect instructions.
websiteSettings.
routingRules[].
redirect.
hostname		 string

Hostname of the redirect URI.
websiteSettings.
routingRules[].
redirect.
httpRedirectCode		 string

HTTP status code of the redirect response.

Default value: "301".

Value must match the regular expression 3(0[1-9]|[1-9][0-9]).
websiteSettings.
routingRules[].
redirect.
protocol		 string

Scheme of the redirect URI.

  • PROTOCOL_HTTP: http scheme.
  • PROTOCOL_HTTPS: https scheme.
websiteSettings.
routingRules[].
redirect.
replaceKeyPrefixWith		 string

Substitution for the prefix of the object key specified in keyPrefixEquals.

At most one of replaceKeyPrefixWith and replaceKeyWith can be specified.
websiteSettings.
routingRules[].
redirect.
replaceKeyWith		 string

New object key.

At most one of replaceKeyWith and replaceKeyPrefixWith can be specified.
lifecycleRules[] object

List of object lifecycle rules for the bucket. For details, see documentation.
lifecycleRules[].
id		 string

ID of the rule. Provided by the client or generated at creation time.
lifecycleRules[].
enabled		 boolean (boolean)

Indicates whether the rule is in effect.
lifecycleRules[].
filter		 object

Filter that identifies the objects to which the rule applies.

If not specified, the rule applies to all objects in the bucket.
lifecycleRules[].
filter.
prefix		 string

Key prefix that the object must have in order for the rule to apply.
lifecycleRules[].
filter.
objectSizeGreaterThan		 integer (int64)

Size that the object must be greater.
lifecycleRules[].
filter.
objectSizeLessThan		 integer (int64)

Size that the object must be less t.
lifecycleRules[].
filter.
tag		 object

Tags that the object's tag set must have for the rule to apply.
lifecycleRules[].
filter.
tag.
key		 string

Key of the bucket tag.
lifecycleRules[].
filter.
tag.
value		 string

Value of the bucket tag.
lifecycleRules[].
filter.
andOperator		 object

Apply a logical AND to all of the predicates configured inside the And operator.
lifecycleRules[].
filter.
andOperator.
prefix		 string
lifecycleRules[].
filter.
andOperator.
objectSizeGreaterThan		 integer (int64)
lifecycleRules[].
filter.
andOperator.
objectSizeLessThan		 integer (int64)
lifecycleRules[].
filter.
andOperator.
tag[]		 object
lifecycleRules[].
filter.
andOperator.
tag[].
key		 string

Key of the bucket tag.
lifecycleRules[].
filter.
andOperator.
tag[].
value		 string

Value of the bucket tag.
lifecycleRules[].
expiration		 object

Expiration rule.

The expiration of an object is described as follows.

For the unversioned bucket (Bucket.versioning is VERSIONING_DISABLED), the object is deleted and cannot be recovered.

For the bucket with versioning enabled (Bucket.versioning is VERSIONING_ENABLED), the current version of the object (if it exists and is not a delete marker) is retained as a non-current version, and a delete marker becomes the current version of the object.

For the bucket with versioning suspended (Bucket.versioning is VERSIONING_SUSPENDED), the current version of the object is retained as a non-current version if it is not a delete marker, or is removed otherwise, and a delete marker becomes the current version of the object.
lifecycleRules[].
expiration.
date		 string (date-time)

Specific date of object expiration.

The rule continues to apply even after the date has passed, i.e. any new objects created in the bucket expire immediately.

Exactly one of date, days, and expiredObjectDeleteMarker fields can be specified.

String in RFC3339 text format. The range of possible values is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
lifecycleRules[].
expiration.
days		 integer (int64)

Time period, in number of days from the creation or modification of the object, after which an object expires.

Exactly one of days, date, and expiredObjectDeleteMarker fields can be specified.
lifecycleRules[].
expiration.
expiredObjectDeleteMarker		 boolean (boolean)

Indicates whether a delete marker of an object with no non-current versions (referred to as an expired object delete marker) is removed at the object's expiration.

Exactly one of expiredObjectDeleteMarker, date, and days fields can be specified.
lifecycleRules[].
transitions[]		 object

List of transition rules.

The transition of an object is described as follows.

For the unversioned bucket (Bucket.versioning is VERSIONING_DISABLED), the object is transitioned to the specified storage class.

For the bucket with versioning enabled (Bucket.versioning is VERSIONING_ENABLED) or suspended (VERSIONING_SUSPENDED), the current version of the object is transitioned to the specified storage class.
lifecycleRules[].
transitions[].
date		 string (date-time)

Specific date of object transition.

The rule continues to apply even after the date has passed, i.e. any new objects created in the bucket are transitioned immediately.

At most one of date and days fields can be specified.

String in RFC3339 text format. The range of possible values is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
lifecycleRules[].
transitions[].
days		 integer (int64)

Time period, in number of days from the creation or modification of the object, after which an object is transitioned.

At most one of days and date fields can be specified.
lifecycleRules[].
transitions[].
storageClass		 string

Required. Storage class to which an object is transitioned from standard storage.

The only supported class is cold storage (COLD, STANDARD_IA, NEARLINE all synonyms). Transitions from cold to standard storage and transitions to or from ice storage are not allowed.
lifecycleRules[].
abortIncompleteMultipartUpload		 object

Configuration for aborting incomplete multipart uploads.
lifecycleRules[].
abortIncompleteMultipartUpload.
daysAfterExpiration		 integer (int64)

Time period, in number of days from the start of the multipart upload, after which the incomplete upload is aborted.
lifecycleRules[].
noncurrentExpiration		 object

Expiration rule for non-current versions of objects in a bucket with versioning enabled (Bucket.versioning is VERSIONING_ENABLED) or suspended (VERSIONING_SUSPENDED).

At expiration, the non-current version of the object is deleted and cannot be recovered.
lifecycleRules[].
noncurrentExpiration.
noncurrentDays		 integer (int64)

Time period, in number of days since the version of an object was classified as non-current, after which the version expires.
lifecycleRules[].
noncurrentTransitions[]		 object

List of transition rules for non-current versions of objects in a bucket with versioning enabled (Bucket.versioning is VERSIONING_ENABLED) or suspended (VERSIONING_SUSPENDED).

At transition, the non-current version of the object is transitioned to the specified storage class.
lifecycleRules[].
noncurrentTransitions[].
noncurrentDays		 integer (int64)

Time period, in number of days since the version of an object was classified as non-current, after which the version is transitioned.
lifecycleRules[].
noncurrentTransitions[].
storageClass		 string

Required. Storage class to which a non-current version of an object is transitioned from standard storage.

The only supported class is cold storage (COLD, STANDARD_IA, NEARLINE all synonyms). Transitions from cold to standard storage and transitions to or from ice storage are not allowed.
lifecycleRules[].
noncurrentDeleteMarkers		 object

Expiration rule for non-current delete markers of an objects in a bucket with versioning enabled (Bucket.versioning is VERSIONING_ENABLED) or suspended (VERSIONING_SUSPENDED). Works in the same way as noncurrent_expiration rule, but only for delete markers.

At expiration, the non-current delete marker of the object is deleted and cannot be recovered.
lifecycleRules[].
noncurrentDeleteMarkers.
noncurrentDays		 integer (int64)

Time period, in number of days since the version of a delete marker was classified as non-current, after which the delete marker expires.
tags[] object

List of tags for the bucket. For details, see documentation.
tags[].
key		 string

Key of the bucket tag.
tags[].
value		 string

Value of the bucket tag.
objectLock object

Configuration for object lock on the bucket. For details about the concept, see documentation.

A resource for Object Lock configuration of a bucket. For details about the concept, see documentation.
objectLock.
status		 string

Activity status of the object lock settings on the bucket
objectLock.
defaultRetention		 object

Default lock configuration for added objects
objectLock.
defaultRetention.
mode		 string

Lock type
objectLock.
defaultRetention.
days		 string (int64)
objectLock.defaultRetention includes only one of the fields days, years

Number of days for locking
objectLock.
defaultRetention.
years		 string (int64)
objectLock.defaultRetention includes only one of the fields days, years

Number of years for locking
encryption object

Configuration for bucket's encryption For detauls, see documentation
encryption.
rules[]		 object
encryption.
rules[].
kmsMasterKeyId		 string
encryption.
rules[].
sseAlgorithm		 string

Methods

Method Description
create Creates a bucket in the specified folder.
delete Deletes the specified bucket.
deleteHTTPSConfig Deletes the HTTPS configuration for the specified bucket.
get Returns the specified bucket.
getHTTPSConfig Returns the HTTPS configuration for the specified bucket.
getStats Returns the statistics for the specified bucket.
list Retrieves the list of buckets in the specified folder.
setHTTPSConfig Updates the HTTPS configuration for the specified bucket.
update Updates the specified bucket.
Предыдущая
Overview
Следующая
create