Skip to content

Commit 617ec74

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
docs: Clarifications about behavior of DeleteObject RPC
docs: Clarifications about format of GetServiceAccountRequest, CreateHmacKeyRequest, DeleteHmacKeyRequest, GetHmacKeyRequest, ListHmacKeysRequest, ObjectChecksums, HmacKeyMetadata, Bucket field used in CreateBucket request docs: Corrected child_type annotations for ListBucketsRequest docs: Updated resource_reference for DeleteObjectRequest, ReadObjectRequest, GetObjectRequest, ListObjectsRequest, Bucket feat: Changed ChecksummedData definition to use annotation ctype=CORD feat!: Removed Bucket.retention_period, now that we've migrated to retention_duration PiperOrigin-RevId: 519863335
1 parent d5a51f6 commit 617ec74

1 file changed

Lines changed: 54 additions & 45 deletions

File tree

‎google/storage/v2/storage.proto‎

Lines changed: 54 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2022 Google LLC
1+
// Copyright 2023 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -225,8 +225,12 @@ service Storage {
225225
};
226226
}
227227

228-
// Deletes an object and its metadata. Deletions are permanent if versioning
229-
// is not enabled for the bucket, or if the `generation` parameter is used.
228+
// Deletes an object and its metadata.
229+
//
230+
// Deletions are normally permanent when versioning is disabled or whenever
231+
// the generation parameter is used. However, if soft delete is enabled for
232+
// the bucket, deleted objects can be restored using RestoreObject until the
233+
// soft delete retention period has passed.
230234
rpc DeleteObject(DeleteObjectRequest) returns (google.protobuf.Empty) {
231235
option (google.api.routing) = {
232236
routing_parameters { field: "bucket" path_template: "{bucket=**}" }
@@ -482,14 +486,17 @@ message CreateBucketRequest {
482486
string parent = 1 [
483487
(google.api.field_behavior) = REQUIRED,
484488
(google.api.resource_reference) = {
485-
type: "cloudresourcemanager.googleapis.com/Project"
489+
child_type: "storage.googleapis.com/Bucket"
486490
}
487491
];
488492

489493
// Properties of the new bucket being inserted.
490-
// The project and name of the bucket are specified in the parent and
491-
// bucket_id fields, respectively. Populating those fields in `bucket` will
492-
// result in an error.
494+
// The name of the bucket is specified in the `bucket_id` field. Populating
495+
// `bucket.name` field will result in an error.
496+
// The project of the bucket must be specified in the `bucket.project` field.
497+
// This field must be in `projects/{projectIdentifier}` format,
498+
// {projectIdentifier} can be the project ID or project number. The `parent`
499+
// field must be either empty or `projects/_`.
493500
Bucket bucket = 2;
494501

495502
// Required. The ID to use for this bucket, which will become the final
@@ -514,7 +521,7 @@ message ListBucketsRequest {
514521
string parent = 1 [
515522
(google.api.field_behavior) = REQUIRED,
516523
(google.api.resource_reference) = {
517-
type: "cloudresourcemanager.googleapis.com/Project"
524+
child_type: "storage.googleapis.com/Bucket"
518525
}
519526
];
520527

@@ -593,8 +600,6 @@ message UpdateBucketRequest {
593600
// may accidentally reset the new field's value.
594601
//
595602
// Not specifying any fields is an error.
596-
// Not specifying a field while setting that field to a non-default value is
597-
// an error.
598603
google.protobuf.FieldMask update_mask = 6
599604
[(google.api.field_behavior) = REQUIRED];
600605
}
@@ -617,7 +622,9 @@ message GetNotificationConfigRequest {
617622
// `projects/{project}/buckets/{bucket}/notificationConfigs/{notificationConfig}`
618623
string name = 1 [
619624
(google.api.field_behavior) = REQUIRED,
620-
(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }
625+
(google.api.resource_reference) = {
626+
type: "storage.googleapis.com/NotificationConfig"
627+
}
621628
];
622629
}
623630

@@ -627,7 +634,7 @@ message CreateNotificationConfigRequest {
627634
string parent = 1 [
628635
(google.api.field_behavior) = REQUIRED,
629636
(google.api.resource_reference) = {
630-
child_type: "storage.googleapis.com/Bucket"
637+
child_type: "storage.googleapis.com/NotificationConfig"
631638
}
632639
];
633640

@@ -642,7 +649,7 @@ message ListNotificationConfigsRequest {
642649
string parent = 1 [
643650
(google.api.field_behavior) = REQUIRED,
644651
(google.api.resource_reference) = {
645-
child_type: "storage.googleapis.com/Bucket"
652+
child_type: "storage.googleapis.com/NotificationConfig"
646653
}
647654
];
648655

@@ -732,7 +739,10 @@ message ComposeObjectRequest {
732739
// `bucket` and `object` **must** be set.
733740
message DeleteObjectRequest {
734741
// Required. Name of the bucket in which the object resides.
735-
string bucket = 1 [(google.api.field_behavior) = REQUIRED];
742+
string bucket = 1 [
743+
(google.api.field_behavior) = REQUIRED,
744+
(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }
745+
];
736746

737747
// Required. The name of the finalized object to delete.
738748
// Note: If you want to delete an unfinalized resumable upload please use
@@ -781,7 +791,10 @@ message CancelResumableWriteResponse {}
781791
// Request message for ReadObject.
782792
message ReadObjectRequest {
783793
// Required. The name of the bucket containing the object to read.
784-
string bucket = 1 [(google.api.field_behavior) = REQUIRED];
794+
string bucket = 1 [
795+
(google.api.field_behavior) = REQUIRED,
796+
(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }
797+
];
785798

786799
// Required. The name of the object to read.
787800
string object = 2 [(google.api.field_behavior) = REQUIRED];
@@ -843,7 +856,10 @@ message ReadObjectRequest {
843856
// Request message for GetObject.
844857
message GetObjectRequest {
845858
// Required. Name of the bucket in which the object resides.
846-
string bucket = 1 [(google.api.field_behavior) = REQUIRED];
859+
string bucket = 1 [
860+
(google.api.field_behavior) = REQUIRED,
861+
(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }
862+
];
847863

848864
// Required. Name of the object.
849865
string object = 2 [(google.api.field_behavior) = REQUIRED];
@@ -887,7 +903,7 @@ message ReadObjectResponse {
887903
// empty for any given `ReadResponse`. This enables the service to inform the
888904
// client that the request is still live while it is running an operation to
889905
// generate more data.
890-
ChecksummedData checksummed_data = 1;
906+
ChecksummedData checksummed_data = 1 [ctype = CORD];
891907

892908
// The checksums of the complete object. The client should compute one of
893909
// these checksums over the downloaded object and compare it against the value
@@ -1017,9 +1033,7 @@ message ListObjectsRequest {
10171033
// Required. Name of the bucket in which to look for objects.
10181034
string parent = 1 [
10191035
(google.api.field_behavior) = REQUIRED,
1020-
(google.api.resource_reference) = {
1021-
child_type: "storage.googleapis.com/Bucket"
1022-
}
1036+
(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }
10231037
];
10241038

10251039
// Maximum number of `items` plus `prefixes` to return
@@ -1147,7 +1161,10 @@ message RewriteObjectRequest {
11471161
Object destination = 1;
11481162

11491163
// Required. Name of the bucket in which to find the source object.
1150-
string source_bucket = 2 [(google.api.field_behavior) = REQUIRED];
1164+
string source_bucket = 2 [
1165+
(google.api.field_behavior) = REQUIRED,
1166+
(google.api.resource_reference) = { type: "storage.googleapis.com/Bucket" }
1167+
];
11511168

11521169
// Required. Name of the source object.
11531170
string source_object = 3 [(google.api.field_behavior) = REQUIRED];
@@ -1323,8 +1340,6 @@ message UpdateObjectRequest {
13231340
// may accidentally reset the new field's value.
13241341
//
13251342
// Not specifying any fields is an error.
1326-
// Not specifying a field while setting that field to a non-default value is
1327-
// an error.
13281343
google.protobuf.FieldMask update_mask = 7
13291344
[(google.api.field_behavior) = REQUIRED];
13301345

@@ -1334,8 +1349,8 @@ message UpdateObjectRequest {
13341349

13351350
// Request message for GetServiceAccount.
13361351
message GetServiceAccountRequest {
1337-
// Required. Project ID, in the format of "projects/<projectIdentifier>".
1338-
// <projectIdentifier> can be the project ID or project number.
1352+
// Required. Project ID, in the format of "projects/{projectIdentifier}".
1353+
// {projectIdentifier} can be the project ID or project number.
13391354
string project = 1 [
13401355
(google.api.field_behavior) = REQUIRED,
13411356
(google.api.resource_reference) = {
@@ -1347,7 +1362,7 @@ message GetServiceAccountRequest {
13471362
// Request message for CreateHmacKey.
13481363
message CreateHmacKeyRequest {
13491364
// Required. The project that the HMAC-owning service account lives in, in the
1350-
// format of "projects/<projectIdentifier>". <projectIdentifier> can be the
1365+
// format of "projects/{projectIdentifier}". {projectIdentifier} can be the
13511366
// project ID or project number.
13521367
string project = 1 [
13531368
(google.api.field_behavior) = REQUIRED,
@@ -1376,8 +1391,8 @@ message DeleteHmacKeyRequest {
13761391
string access_id = 1 [(google.api.field_behavior) = REQUIRED];
13771392

13781393
// Required. The project that owns the HMAC key, in the format of
1379-
// "projects/<projectIdentifier>".
1380-
// <projectIdentifier> can be the project ID or project number.
1394+
// "projects/{projectIdentifier}".
1395+
// {projectIdentifier} can be the project ID or project number.
13811396
string project = 2 [
13821397
(google.api.field_behavior) = REQUIRED,
13831398
(google.api.resource_reference) = {
@@ -1392,8 +1407,8 @@ message GetHmacKeyRequest {
13921407
string access_id = 1 [(google.api.field_behavior) = REQUIRED];
13931408

13941409
// Required. The project the HMAC key lies in, in the format of
1395-
// "projects/<projectIdentifier>".
1396-
// <projectIdentifier> can be the project ID or project number.
1410+
// "projects/{projectIdentifier}".
1411+
// {projectIdentifier} can be the project ID or project number.
13971412
string project = 2 [
13981413
(google.api.field_behavior) = REQUIRED,
13991414
(google.api.resource_reference) = {
@@ -1405,8 +1420,8 @@ message GetHmacKeyRequest {
14051420
// Request to fetch a list of HMAC keys under a given project.
14061421
message ListHmacKeysRequest {
14071422
// Required. The project to list HMAC keys for, in the format of
1408-
// "projects/<projectIdentifier>".
1409-
// <projectIdentifier> can be the project ID or project number.
1423+
// "projects/{projectIdentifier}".
1424+
// {projectIdentifier} can be the project ID or project number.
14101425
string project = 1 [
14111426
(google.api.field_behavior) = REQUIRED,
14121427
(google.api.resource_reference) = {
@@ -1729,12 +1744,6 @@ message Bucket {
17291744
// Once locked, an object retention policy cannot be modified.
17301745
bool is_locked = 2;
17311746

1732-
// The duration in seconds that objects need to be retained. Retention
1733-
// duration must be greater than zero and less than 100 years. Note that
1734-
// enforcement of retention periods less than a day is not guaranteed. Such
1735-
// periods should only be used for testing purposes.
1736-
optional int64 retention_period = 3;
1737-
17381747
// The duration that objects need to be retained. Retention duration must be
17391748
// greater than zero and less than 100 years. Note that enforcement of
17401749
// retention periods less than a day is not guaranteed. Such periods should
@@ -1804,8 +1813,8 @@ message Bucket {
18041813
string etag = 29;
18051814

18061815
// Immutable. The project which owns this bucket, in the format of
1807-
// "projects/<projectIdentifier>".
1808-
// <projectIdentifier> can be the project ID or project number.
1816+
// "projects/{projectIdentifier}".
1817+
// {projectIdentifier} can be the project ID or project number.
18091818
string project = 3 [
18101819
(google.api.field_behavior) = IMMUTABLE,
18111820
(google.api.resource_reference) = {
@@ -2009,7 +2018,7 @@ message ChecksummedData {
20092018
message ObjectChecksums {
20102019
// CRC32C digest of the object data. Computed by the Cloud Storage service for
20112020
// all written objects.
2012-
// If set in an WriteObjectRequest, service will validate that the stored
2021+
// If set in a WriteObjectRequest, service will validate that the stored
20132022
// object matches this checksum.
20142023
optional fixed32 crc32c = 1;
20152024

@@ -2026,16 +2035,16 @@ message ObjectChecksums {
20262035
// Hmac Key Metadata, which includes all information other than the secret.
20272036
message HmacKeyMetadata {
20282037
// Immutable. Resource name ID of the key in the format
2029-
// <projectIdentifier>/<accessId>.
2030-
// <projectIdentifier> can be the project ID or project number.
2038+
// {projectIdentifier}/{accessId}.
2039+
// {projectIdentifier} can be the project ID or project number.
20312040
string id = 1 [(google.api.field_behavior) = IMMUTABLE];
20322041

20332042
// Immutable. Globally unique id for keys.
20342043
string access_id = 2 [(google.api.field_behavior) = IMMUTABLE];
20352044

20362045
// Immutable. Identifies the project that owns the service account of the
2037-
// specified HMAC key, in the format "projects/<projectIdentifier>".
2038-
// <projectIdentifier> can be the project ID or project number.
2046+
// specified HMAC key, in the format "projects/{projectIdentifier}".
2047+
// {projectIdentifier} can be the project ID or project number.
20392048
string project = 3 [
20402049
(google.api.field_behavior) = IMMUTABLE,
20412050
(google.api.resource_reference) = {

0 commit comments

Comments
 (0)