Object Storage API, gRPC: BucketService.Get

Статья создана

Yandex Cloud

Обновлена 17 декабря 2024 г.

gRPC request
GetBucketRequest
Bucket
AnonymousAccessFlags
ACL
Grant
CorsRule
WebsiteSettings
Scheme
RoutingRule
Condition
Redirect
LifecycleRule
RuleFilter
Tag
And
Expiration
Transition
AfterDays
NoncurrentExpiration
NoncurrentTransition
NoncurrentDeleteMarkers
ObjectLock
DefaultRetention
Encryption
EncryptionRule
BucketAllowedPrivateEndpoints

Returns the specified bucket.

To get the list of all available buckets, make a List request.

gRPC request

rpc Get (GetBucketRequest) returns (Bucket)

GetBucketRequest

{
  "name": "string",
  "view": "View"
}

Field

Description

name

string

Required field. Name of the bucket to return.

To get the bucket name, make a BucketService.List request.

view

enum View

Scope of information about the bucket to return.

Access to scopes is managed via Identity and Access Management roles,
bucket ACL and policies.

VIEW_UNSPECIFIED
VIEW_BASIC: Returns basic information about a bucket.

The following fields will not be returned: Bucket.acl, Bucket.cors, Bucket.website_settings,
Bucket.lifecycle_rules, Bucket.tags.
VIEW_ACL: Returns basic information and access control list (ACL) for the bucket.

The following fields will not be returned: Bucket.cors, Bucket.website_settings, Bucket.lifecycle_rules,
Bucket.tags.
VIEW_FULL: Returns full information about a bucket.

Bucket

{
  "id": "string",
  "name": "string",
  "folder_id": "string",
  "anonymous_access_flags": {
    "read": "google.protobuf.BoolValue",
    "list": "google.protobuf.BoolValue",
    "config_read": "google.protobuf.BoolValue"
  },
  "default_storage_class": "string",
  "versioning": "Versioning",
  "max_size": "int64",
  "policy": "google.protobuf.Struct",
  "acl": {
    "grants": [
      {
        "permission": "Permission",
        "grant_type": "GrantType",
        "grantee_id": "string"
      }
    ]
  },
  "created_at": "google.protobuf.Timestamp",
  "cors": [
    {
      "id": "string",
      "allowed_methods": [
        "Method"
      ],
      "allowed_headers": [
        "string"
      ],
      "allowed_origins": [
        "string"
      ],
      "expose_headers": [
        "string"
      ],
      "max_age_seconds": "google.protobuf.Int64Value"
    }
  ],
  "website_settings": {
    "index": "string",
    "error": "string",
    "redirect_all_requests": {
      "protocol": "Protocol",
      "hostname": "string"
    },
    "routing_rules": [
      {
        "condition": {
          "http_error_code_returned_equals": "string",
          "key_prefix_equals": "string"
        },
        "redirect": {
          "hostname": "string",
          "http_redirect_code": "string",
          "protocol": "Protocol",
          "replace_key_prefix_with": "string",
          "replace_key_with": "string"
        }
      }
    ]
  },
  "lifecycle_rules": [
    {
      "id": "google.protobuf.StringValue",
      "enabled": "bool",
      "filter": {
        "prefix": "string",
        "object_size_greater_than": "google.protobuf.Int64Value",
        "object_size_less_than": "google.protobuf.Int64Value",
        "tag": {
          "key": "string",
          "value": "string"
        },
        "and_operator": {
          "prefix": "string",
          "object_size_greater_than": "google.protobuf.Int64Value",
          "object_size_less_than": "google.protobuf.Int64Value",
          "tag": [
            {
              "key": "string",
              "value": "string"
            }
          ]
        }
      },
      "expiration": {
        "date": "google.protobuf.Timestamp",
        "days": "google.protobuf.Int64Value",
        "expired_object_delete_marker": "google.protobuf.BoolValue"
      },
      "transitions": [
        {
          "date": "google.protobuf.Timestamp",
          "days": "google.protobuf.Int64Value",
          "storage_class": "string"
        }
      ],
      "abort_incomplete_multipart_upload": {
        "days_after_expiration": "google.protobuf.Int64Value"
      },
      "noncurrent_expiration": {
        "noncurrent_days": "google.protobuf.Int64Value"
      },
      "noncurrent_transitions": [
        {
          "noncurrent_days": "google.protobuf.Int64Value",
          "storage_class": "string"
        }
      ],
      "noncurrent_delete_markers": {
        "noncurrent_days": "google.protobuf.Int64Value"
      }
    }
  ],
  "tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "object_lock": {
    "status": "ObjectLockStatus",
    "default_retention": {
      "mode": "Mode",
      // Includes only one of the fields `days`, `years`
      "days": "int64",
      "years": "int64"
      // end of the list of possible fields
    }
  },
  "encryption": {
    "rules": [
      {
        "kms_master_key_id": "string",
        "sse_algorithm": "string"
      }
    ]
  },
  "allowed_private_endpoints": {
    "enabled": "bool",
    "private_endpoints": [
      "string"
    ]
  }
}

A bucket resource.
For details about the concept, see documentation.

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.
folder_id	string ID of the folder that the bucket belongs to.
anonymous_access_flags	AnonymousAccessFlags Flags for configuring public (anonymous) access to the bucket's content and settings. For details, see documentation.
default_storage_class	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	enum Versioning Bucket versioning status. For details, see documentation. `VERSIONING_UNSPECIFIED` `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 BucketService.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 BucketService.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 BucketService.Update request.
max_size	int64 Maximum size of the bucket, in bytes. For details, see documentation.
policy	google.protobuf.Struct Bucket policies that set permissions for actions with the bucket, its objects, and groups of objects. For details, see documentation.
acl	ACL Access control list (ACL) of the bucket. For details, see documentation.
created_at	google.protobuf.Timestamp Creation timestamp.
cors[]	CorsRule List of rules for cross-domain requests to objects in the bucket (cross-origin resource sharing, CORS). For details, see documentation.
website_settings	WebsiteSettings Configuration for hosting a static website in the bucket. For details, see documentation.
lifecycle_rules[]	LifecycleRule List of object lifecycle rules for the bucket. For details, see documentation.
tags[]	Tag List of tags for the bucket. For details, see documentation.
object_lock	ObjectLock Configuration for object lock on the bucket. For details about the concept, see documentation.
encryption	Encryption Configuration for bucket's encryption For details, see documentation
allowed_private_endpoints	BucketAllowedPrivateEndpoints Bucket allowed private endpoints.

AnonymousAccessFlags

Field	Description
read	google.protobuf.BoolValue Specifies whether public (anonymous) access to read objects in the bucket is enabled.
list	google.protobuf.BoolValue Specifies whether public (anonymous) access to the list of objects in the bucket is enabled.
config_read	google.protobuf.BoolValue Specifies whether public (anonymous) access to read CORS, static website hosting, and object lifecycles settings of the bucket is enabled.

ACL

Field

Description

grants[]

Grant

List of permissions granted and the grantees.

Grant

A grant resource, used to specify the permission granted and the grantee.

Field	Description
permission	enum Permission Required field. Permission granted by the grant. `PERMISSION_UNSPECIFIED` `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.
grant_type	enum GrantType Required field. The grantee type for the grant. `GRANT_TYPE_UNSPECIFIED` `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.grantee_id` 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).
grantee_id	string ID of the account who is a grantee. Required when the `grant_type` is `GRANT_TYPE_ACCOUNT`.

CorsRule

A CORS rule resource.
For details about the concept, see documentation.

Field	Description
id	string ID of the CORS rule.
allowed_methods[]	enum Method 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. `METHOD_UNSPECIFIED` `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.
allowed_headers[]	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.
allowed_origins[]	string 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`.
expose_headers[]	string List of headers contained in responses to CORS requests that can be accessed by applications.
max_age_seconds	google.protobuf.Int64Value 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

Field	Description
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 `redirect_all_requests` 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.
error	string Key of the error page object that is returned when an error occurs.
redirect_all_requests	Scheme Configuration for redirecting all requests sent to the website. Either `redirect_all_requests` or `index` must be specified in order for the bucket to host a static website. If `redirect_all_requests` is specified, it must be the only field in Bucket.website_settings.
routing_rules[]	RoutingRule List of redirect rules.

Scheme

A configuration resource for redirecting all requests sent to the website.

Field

Description

protocol

enum Protocol

Scheme of the redirect URI.

PROTOCOL_UNSPECIFIED
PROTOCOL_HTTP: http scheme.
PROTOCOL_HTTPS: https scheme.

hostname

string

Hostname of the redirect URI.

RoutingRule

List of redirect rules.

Field

Description

condition

Condition

Redirect condition.

redirect

Redirect

Redirect instructions.

Condition

Field

Description

http_error_code_returned_equals

string

HTTP status code (number only) that must match for the redirect to apply.

key_prefix_equals

string

Prefix of the object key from which requests are redirected.

Redirect

Field	Description
hostname	string Hostname of the redirect URI.
http_redirect_code	string HTTP status code of the redirect response. Default value: `"301"`.
protocol	enum Protocol Scheme of the redirect URI. `PROTOCOL_UNSPECIFIED` `PROTOCOL_HTTP`: `http` scheme. `PROTOCOL_HTTPS`: `https` scheme.
replace_key_prefix_with	string Substitution for the prefix of the object key specified in Condition.key_prefix_equals. At most one of `replace_key_prefix_with` and `replace_key_with` can be specified.
replace_key_with	string New object key. At most one of `replace_key_with` and `replace_key_prefix_with` can be specified.

LifecycleRule

An object lifecycle rule resource for the bucket.
For details about the concept, see documentation.

Field	Description
id	google.protobuf.StringValue ID of the rule. Provided by the client or generated at creation time.
enabled	bool Indicates whether the rule is in effect.
filter	RuleFilter Filter that identifies the objects to which the rule applies. If not specified, the rule applies to all objects in the bucket.
expiration	Expiration 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.
transitions[]	Transition 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.
abort_incomplete_multipart_upload	AfterDays Configuration for aborting incomplete multipart uploads.
noncurrent_expiration	NoncurrentExpiration 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.
noncurrent_transitions[]	NoncurrentTransition 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.
noncurrent_delete_markers	NoncurrentDeleteMarkers 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.

RuleFilter

Field	Description
prefix	string Key prefix that the object must have in order for the rule to apply.
object_size_greater_than	google.protobuf.Int64Value Size that the object must be greater.
object_size_less_than	google.protobuf.Int64Value Size that the object must be less t.
tag	Tag Tags that the object's tag set must have for the rule to apply.
and_operator	And Apply a logical AND to all of the predicates configured inside the And operator.

Tag

Field

Description

key

string

Key of the bucket tag.

value

string

Value of the bucket tag.

And

Field	Description
prefix	string
object_size_greater_than	google.protobuf.Int64Value
object_size_less_than	google.protobuf.Int64Value
tag[]	Tag

Expiration

Field	Description
date	google.protobuf.Timestamp 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 `expired_object_delete_marker` fields can be specified.
days	google.protobuf.Int64Value 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 `expired_object_delete_marker` fields can be specified.
expired_object_delete_marker	google.protobuf.BoolValue 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 `expired_object_delete_marker`, `date`, and `days` fields can be specified.

Transition

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.

Field	Description
date	google.protobuf.Timestamp 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.
days	google.protobuf.Int64Value 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.
storage_class	string Required field. 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.

AfterDays

Field

Description

days_after_expiration

google.protobuf.Int64Value

Time period, in number of days from the start of the multipart upload, after which the incomplete upload is
aborted.

NoncurrentExpiration

Field

Description

noncurrent_days

google.protobuf.Int64Value

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

NoncurrentTransition

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.

Field

Description

noncurrent_days

google.protobuf.Int64Value

Time period, in number of days since the version of an object was classified as non-current, after which the
version is transitioned.

storage_class

string

Required field. 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.

NoncurrentDeleteMarkers

Field

Description

noncurrent_days

google.protobuf.Int64Value

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

ObjectLock

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

Field

Description

status

enum ObjectLockStatus

OBJECT_LOCK_STATUS_UNSPECIFIED
OBJECT_LOCK_STATUS_DISABLED
OBJECT_LOCK_STATUS_ENABLED

default_retention

DefaultRetention

DefaultRetention

Default lock configuration for added objects

Field	Description
mode	enum Mode `MODE_UNSPECIFIED` `MODE_GOVERNANCE` `MODE_COMPLIANCE`
days	int64 Number of days for locking Includes only one of the fields `days`, `years`.
years	int64 Number of years for locking Includes only one of the fields `days`, `years`.

Encryption

Field	Description
rules[]	EncryptionRule

EncryptionRule

Field	Description
kms_master_key_id	string
sse_algorithm	string

BucketAllowedPrivateEndpoints

Field

Description

enabled

bool

if true, private endpoints white list check is enabled
even if private_endpoints list is empty

private_endpoints[]

string

white list of private endpoints bucket accessible from

Object Storage API, gRPC: BucketService.Get

gRPC requestgRPC request

GetBucketRequestGetBucketRequest

BucketBucket

AnonymousAccessFlagsAnonymousAccessFlags

ACLACL

GrantGrant

CorsRuleCorsRule

WebsiteSettingsWebsiteSettings

SchemeScheme

RoutingRuleRoutingRule

ConditionCondition

RedirectRedirect

LifecycleRuleLifecycleRule

RuleFilterRuleFilter

TagTag

AndAnd

ExpirationExpiration

TransitionTransition

AfterDaysAfterDays

NoncurrentExpirationNoncurrentExpiration

NoncurrentTransitionNoncurrentTransition

NoncurrentDeleteMarkersNoncurrentDeleteMarkers

ObjectLockObjectLock

DefaultRetentionDefaultRetention

EncryptionEncryption

EncryptionRuleEncryptionRule

BucketAllowedPrivateEndpointsBucketAllowedPrivateEndpoints

Была ли статья полезна?

gRPC request

GetBucketRequest

Bucket

AnonymousAccessFlags

ACL

Grant

CorsRule

WebsiteSettings

Scheme

RoutingRule

Condition

Redirect

LifecycleRule

RuleFilter

Tag

And

Expiration

Transition

AfterDays

NoncurrentExpiration

NoncurrentTransition

NoncurrentDeleteMarkers

ObjectLock

DefaultRetention

Encryption

EncryptionRule

BucketAllowedPrivateEndpoints