docs: [storage] update storage control documentation and add PHP for …

…publishing (#5264) * docs: update storage control documentation and add PHP for publishing PiperOrigin-RevId: 626165497 Source-Link: googleapis/googleapis@1125069 Source-Link: googleapis/googleapis-gen@a09be5f Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLXN0b3JhZ2UtY29udHJvbC8uT3dsQm90LnlhbWwiLCJoIjoiYTA5YmU1Zjc3YjBkOGMyOGRhMjkyMWZjZTcyZjBlMWMwNmU3MjViNCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
googleapis · Apr 23, 2024 · 9458fef · 9458fef
1 parent 467f31b
commit 9458fef
Show file tree

Hide file tree

Showing 6 changed files with 77 additions and 43 deletions.
diff --git a/packages/google-storage-control/protos/google/storage/control/v2/storage_control.proto b/packages/google-storage-control/protos/google/storage/control/v2/storage_control.proto
@@ -47,15 +47,19 @@ service StorageControl {
       "https://www.googleapis.com/auth/devstorage.read_only,"
       "https://www.googleapis.com/auth/devstorage.read_write";
 
-  // Creates a new folder.
+  // Creates a new folder. This operation is only applicable to a hierarchical
+  // namespace enabled bucket.
+  // Hierarchical namespace buckets are in allowlist preview.
   rpc CreateFolder(CreateFolderRequest) returns (Folder) {
     option (google.api.routing) = {
       routing_parameters { field: "parent" path_template: "{bucket=**}" }
     };
     option (google.api.method_signature) = "parent,folder,folder_id";
   }
 
-  // Permanently deletes an empty folder.
+  // Permanently deletes an empty folder. This operation is only applicable to a
+  // hierarchical namespace enabled bucket.
+  // Hierarchical namespace buckets are in allowlist preview.
   rpc DeleteFolder(DeleteFolderRequest) returns (google.protobuf.Empty) {
     option (google.api.routing) = {
       routing_parameters {
@@ -66,7 +70,9 @@ service StorageControl {
     option (google.api.method_signature) = "name";
   }
 
-  // Returns metadata for the specified folder.
+  // Returns metadata for the specified folder. This operation is only
+  // applicable to a hierarchical namespace enabled bucket.
+  // Hierarchical namespace buckets are in allowlist preview.
   rpc GetFolder(GetFolderRequest) returns (Folder) {
     option (google.api.routing) = {
       routing_parameters {
@@ -77,17 +83,21 @@ service StorageControl {
     option (google.api.method_signature) = "name";
   }
 
-  // Retrieves a list of folders for a given bucket.
+  // Retrieves a list of folders. This operation is only applicable to a
+  // hierarchical namespace enabled bucket.
+  // Hierarchical namespace buckets are in allowlist preview.
   rpc ListFolders(ListFoldersRequest) returns (ListFoldersResponse) {
     option (google.api.routing) = {
       routing_parameters { field: "parent" path_template: "{bucket=**}" }
     };
     option (google.api.method_signature) = "parent";
   }
 
-  // Renames a source folder to a destination folder. During a rename, the
+  // Renames a source folder to a destination folder. This operation is only
+  // applicable to a hierarchical namespace enabled bucket. During a rename, the
   // source and destination folders are locked until the long running operation
   // completes.
+  // Hierarchical namespace buckets are in allowlist preview.
   rpc RenameFolder(RenameFolderRequest) returns (google.longrunning.Operation) {
     option (google.api.routing) = {
       routing_parameters {
@@ -161,7 +171,9 @@ message PendingRenameInfo {
   string operation = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
-// A folder.
+// A folder resource. This resource can only exist in a hierarchical namespace
+// enabled bucket.
+// Hierarchical namespace buckets are in allowlist preview.
 message Folder {
   option (google.api.resource) = {
     type: "storage.googleapis.com/Folder"
@@ -195,7 +207,9 @@ message Folder {
       [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
-// Request message for GetFolder.
+// Request message for GetFolder. This operation is only applicable to a
+// hierarchical namespace enabled bucket.
+// Hierarchical namespace buckets are in allowlist preview.
 message GetFolderRequest {
   // Required. Name of the folder.
   // Format: `projects/{project}/buckets/{bucket}/folders/{folder}`
@@ -220,9 +234,12 @@ message GetFolderRequest {
   ];
 }
 
-// Request message for CreateFolder.
+// Request message for CreateFolder. This operation is only applicable to a
+// hierarchical namespace enabled bucket.
+// Hierarchical namespace buckets are in allowlist preview.
 message CreateFolderRequest {
-  // Required. Name of the bucket in which the folder will reside.
+  // Required. Name of the bucket in which the folder will reside. The bucket
+  // must be a hierarchical namespace enabled bucket.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -248,15 +265,16 @@ message CreateFolderRequest {
   bool recursive = 4 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. A unique identifier for this request. UUID is the recommended
-  // format, but other formats are still accepted. This request is only
-  // idempotent if a `request_id` is provided.
+  // format, but other formats are still accepted.
   string request_id = 5 [
     (google.api.field_info).format = UUID4,
     (google.api.field_behavior) = OPTIONAL
   ];
 }
 
-// Request message for DeleteFolder.
+// Request message for DeleteFolder. This operation is only applicable to a
+// hierarchical namespace enabled bucket.
+// Hierarchical namespace buckets are in allowlist preview.
 message DeleteFolderRequest {
   // Required. Name of the folder.
   // Format: `projects/{project}/buckets/{bucket}/folders/{folder}`
@@ -274,17 +292,19 @@ message DeleteFolderRequest {
   optional int64 if_metageneration_not_match = 4;
 
   // Optional. A unique identifier for this request. UUID is the recommended
-  // format, but other formats are still accepted. This request is only
-  // idempotent if a `request_id` is provided.
+  // format, but other formats are still accepted.
   string request_id = 5 [
     (google.api.field_info).format = UUID4,
     (google.api.field_behavior) = OPTIONAL
   ];
 }
 
-// Request message for ListFolders.
+// Request message for ListFolders. This operation is only applicable to a
+// hierarchical namespace enabled bucket.
+// Hierarchical namespace buckets are in allowlist preview.
 message ListFoldersRequest {
-  // Required. Name of the bucket in which to look for folders.
+  // Required. Name of the bucket in which to look for folders. The bucket must
+  // be a hierarchical namespace enabled bucket.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -339,7 +359,9 @@ message ListFoldersResponse {
   string next_page_token = 2;
 }
 
-// Request message for RenameFolder.
+// Request message for RenameFolder. This operation is only applicable to a
+// hierarchical namespace enabled bucket.
+// Hierarchical namespace buckets are in allowlist preview.
 message RenameFolderRequest {
   // Required. Name of the source folder being renamed.
   // Format: `projects/{project}/buckets/{bucket}/folders/{folder}`

diff --git a/...ogle-storage-control/samples/generated/v2/snippet_metadata_google.storage.control.v2.json b/...ogle-storage-control/samples/generated/v2/snippet_metadata_google.storage.control.v2.json
@@ -15,7 +15,7 @@
             "regionTag": "storage_v2_generated_StorageControl_CreateFolder_async",
             "title": "StorageControl createFolder Sample",
             "origin": "API_DEFINITION",
-            "description": " Creates a new folder.",
+            "description": " Creates a new folder. This operation is only applicable to a hierarchical namespace enabled bucket. Hierarchical namespace buckets are in allowlist preview.",
             "canonical": true,
             "file": "storage_control.create_folder.js",
             "language": "JAVASCRIPT",
@@ -71,14 +71,14 @@
             "regionTag": "storage_v2_generated_StorageControl_DeleteFolder_async",
             "title": "StorageControl deleteFolder Sample",
             "origin": "API_DEFINITION",
-            "description": " Permanently deletes an empty folder.",
+            "description": " Permanently deletes an empty folder. This operation is only applicable to a hierarchical namespace enabled bucket. Hierarchical namespace buckets are in allowlist preview.",
             "canonical": true,
             "file": "storage_control.delete_folder.js",
             "language": "JAVASCRIPT",
             "segments": [
                 {
                     "start": 25,
-                    "end": 70,
+                    "end": 69,
                     "type": "FULL"
                 }
             ],
@@ -123,7 +123,7 @@
             "regionTag": "storage_v2_generated_StorageControl_GetFolder_async",
             "title": "StorageControl getFolder Sample",
             "origin": "API_DEFINITION",
-            "description": " Returns metadata for the specified folder.",
+            "description": " Returns metadata for the specified folder. This operation is only applicable to a hierarchical namespace enabled bucket. Hierarchical namespace buckets are in allowlist preview.",
             "canonical": true,
             "file": "storage_control.get_folder.js",
             "language": "JAVASCRIPT",
@@ -175,14 +175,14 @@
             "regionTag": "storage_v2_generated_StorageControl_ListFolders_async",
             "title": "StorageControl listFolders Sample",
             "origin": "API_DEFINITION",
-            "description": " Retrieves a list of folders for a given bucket.",
+            "description": " Retrieves a list of folders. This operation is only applicable to a hierarchical namespace enabled bucket. Hierarchical namespace buckets are in allowlist preview.",
             "canonical": true,
             "file": "storage_control.list_folders.js",
             "language": "JAVASCRIPT",
             "segments": [
                 {
                     "start": 25,
-                    "end": 95,
+                    "end": 96,
                     "type": "FULL"
                 }
             ],
@@ -243,7 +243,7 @@
             "regionTag": "storage_v2_generated_StorageControl_RenameFolder_async",
             "title": "StorageControl renameFolder Sample",
             "origin": "API_DEFINITION",
-            "description": " Renames a source folder to a destination folder. During a rename, the source and destination folders are locked until the long running operation completes.",
+            "description": " Renames a source folder to a destination folder. This operation is only applicable to a hierarchical namespace enabled bucket. During a rename, the source and destination folders are locked until the long running operation completes. Hierarchical namespace buckets are in allowlist preview.",
             "canonical": true,
             "file": "storage_control.rename_folder.js",
             "language": "JAVASCRIPT",

diff --git a/packages/google-storage-control/samples/generated/v2/storage_control.create_folder.js b/packages/google-storage-control/samples/generated/v2/storage_control.create_folder.js
@@ -29,7 +29,8 @@ function main(parent, folder, folderId) {
    * TODO(developer): Uncomment these variables before running the sample.
    */
   /**
-   *  Required. Name of the bucket in which the folder will reside.
+   *  Required. Name of the bucket in which the folder will reside. The bucket
+   *  must be a hierarchical namespace enabled bucket.
    */
   // const parent = 'abc123'
   /**
@@ -54,8 +55,7 @@ function main(parent, folder, folderId) {
   // const recursive = true
   /**
    *  Optional. A unique identifier for this request. UUID is the recommended
-   *  format, but other formats are still accepted. This request is only
-   *  idempotent if a `request_id` is provided.
+   *  format, but other formats are still accepted.
    */
   // const requestId = 'abc123'
 

diff --git a/packages/google-storage-control/samples/generated/v2/storage_control.delete_folder.js b/packages/google-storage-control/samples/generated/v2/storage_control.delete_folder.js
@@ -45,8 +45,7 @@ function main(name) {
   // const ifMetagenerationNotMatch = 1234
   /**
    *  Optional. A unique identifier for this request. UUID is the recommended
-   *  format, but other formats are still accepted. This request is only
-   *  idempotent if a `request_id` is provided.
+   *  format, but other formats are still accepted.
    */
   // const requestId = 'abc123'
 

diff --git a/packages/google-storage-control/samples/generated/v2/storage_control.list_folders.js b/packages/google-storage-control/samples/generated/v2/storage_control.list_folders.js
@@ -29,7 +29,8 @@ function main(parent) {
    * TODO(developer): Uncomment these variables before running the sample.
    */
   /**
-   *  Required. Name of the bucket in which to look for folders.
+   *  Required. Name of the bucket in which to look for folders. The bucket must
+   *  be a hierarchical namespace enabled bucket.
    */
   // const parent = 'abc123'
   /**

diff --git a/packages/google-storage-control/src/v2/storage_control_client.ts b/packages/google-storage-control/src/v2/storage_control_client.ts
@@ -449,12 +449,15 @@ export class StorageControlClient {
   // -- Service calls --
   // -------------------
   /**
-   * Creates a new folder.
+   * Creates a new folder. This operation is only applicable to a hierarchical
+   * namespace enabled bucket.
+   * Hierarchical namespace buckets are in allowlist preview.
    *
    * @param {Object} request
    *   The request object that will be sent.
    * @param {string} request.parent
-   *   Required. Name of the bucket in which the folder will reside.
+   *   Required. Name of the bucket in which the folder will reside. The bucket
+   *   must be a hierarchical namespace enabled bucket.
    * @param {google.storage.control.v2.Folder} request.folder
    *   Required. Properties of the new folder being created.
    *   The bucket and name of the folder are specified in the parent and folder_id
@@ -471,8 +474,7 @@ export class StorageControlClient {
    *   ancestor folders will be created atomically.
    * @param {string} [request.requestId]
    *   Optional. A unique identifier for this request. UUID is the recommended
-   *   format, but other formats are still accepted. This request is only
-   *   idempotent if a `request_id` is provided.
+   *   format, but other formats are still accepted.
    * @param {object} [options]
    *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
    * @returns {Promise} - The promise which resolves to an array.
@@ -563,7 +565,9 @@ export class StorageControlClient {
     return this.innerApiCalls.createFolder(request, options, callback);
   }
   /**
-   * Permanently deletes an empty folder.
+   * Permanently deletes an empty folder. This operation is only applicable to a
+   * hierarchical namespace enabled bucket.
+   * Hierarchical namespace buckets are in allowlist preview.
    *
    * @param {Object} request
    *   The request object that will be sent.
@@ -578,8 +582,7 @@ export class StorageControlClient {
    *   current metageneration does not match the given value.
    * @param {string} [request.requestId]
    *   Optional. A unique identifier for this request. UUID is the recommended
-   *   format, but other formats are still accepted. This request is only
-   *   idempotent if a `request_id` is provided.
+   *   format, but other formats are still accepted.
    * @param {object} [options]
    *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
    * @returns {Promise} - The promise which resolves to an array.
@@ -672,7 +675,9 @@ export class StorageControlClient {
     return this.innerApiCalls.deleteFolder(request, options, callback);
   }
   /**
-   * Returns metadata for the specified folder.
+   * Returns metadata for the specified folder. This operation is only
+   * applicable to a hierarchical namespace enabled bucket.
+   * Hierarchical namespace buckets are in allowlist preview.
    *
    * @param {Object} request
    *   The request object that will be sent.
@@ -1238,9 +1243,11 @@ export class StorageControlClient {
   }
 
   /**
-   * Renames a source folder to a destination folder. During a rename, the
+   * Renames a source folder to a destination folder. This operation is only
+   * applicable to a hierarchical namespace enabled bucket. During a rename, the
    * source and destination folders are locked until the long running operation
    * completes.
+   * Hierarchical namespace buckets are in allowlist preview.
    *
    * @param {Object} request
    *   The request object that will be sent.
@@ -1403,12 +1410,15 @@ export class StorageControlClient {
     >;
   }
   /**
-   * Retrieves a list of folders for a given bucket.
+   * Retrieves a list of folders. This operation is only applicable to a
+   * hierarchical namespace enabled bucket.
+   * Hierarchical namespace buckets are in allowlist preview.
    *
    * @param {Object} request
    *   The request object that will be sent.
    * @param {string} request.parent
-   *   Required. Name of the bucket in which to look for folders.
+   *   Required. Name of the bucket in which to look for folders. The bucket must
+   *   be a hierarchical namespace enabled bucket.
    * @param {number} [request.pageSize]
    *   Optional. Maximum number of folders to return in a single response. The
    *   service will use this parameter or 1,000 items, whichever is smaller.
@@ -1530,7 +1540,8 @@ export class StorageControlClient {
    * @param {Object} request
    *   The request object that will be sent.
    * @param {string} request.parent
-   *   Required. Name of the bucket in which to look for folders.
+   *   Required. Name of the bucket in which to look for folders. The bucket must
+   *   be a hierarchical namespace enabled bucket.
    * @param {number} [request.pageSize]
    *   Optional. Maximum number of folders to return in a single response. The
    *   service will use this parameter or 1,000 items, whichever is smaller.
@@ -1606,7 +1617,8 @@ export class StorageControlClient {
    * @param {Object} request
    *   The request object that will be sent.
    * @param {string} request.parent
-   *   Required. Name of the bucket in which to look for folders.
+   *   Required. Name of the bucket in which to look for folders. The bucket must
+   *   be a hierarchical namespace enabled bucket.
    * @param {number} [request.pageSize]
    *   Optional. Maximum number of folders to return in a single response. The
    *   service will use this parameter or 1,000 items, whichever is smaller.