docs: update storage control documentation and add PHP for publishing

Google APIs · copybara-github · commit 11250694018f · 2024-04-18T15:21:30.000-07:00
PiperOrigin-RevId: 626165497
diff --git a/google/storage/control/v2/storage_control.proto b/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/google/storage/control/v2/storage_v2.yaml b/google/storage/control/v2/storage_v2.yaml
@@ -1,7 +1,7 @@
 type: google.api.Service
 config_version: 3
 name: storage.googleapis.com
-title: Cloud Storage API
+title: Storage Control API
 
 apis:
 - name: google.longrunning.Operations
@@ -12,7 +12,14 @@ types:
 - name: google.storage.control.v2.RenameFolderMetadata
 
 documentation:
-  summary: 'Lets you store and retrieve potentially-large, immutable data objects.'
+  summary: |-
+    The Storage Control API lets you perform metadata-specific, control plane,
+    and long-running operations.
+
+    The Storage Control API creates one space to perform metadata-specific,
+    control plane, and long-running operations apart from the Storage API.
+    Separating these operations from the Storage API improves API
+    standardization and lets you run faster releases.
   overview: |-
     The Google Cloud Storage API allows applications to read and write data
     through the abstractions of buckets and objects, which are similar to
@@ -77,7 +84,7 @@ publishing:
   doc_tag_prefix: storage
   organization: CLOUD
   library_settings:
-  - version: google.cloud.storage.control.v2
+  - version: google.storage.control.v2
     launch_stage: ALPHA
     java_settings:
       common:
@@ -87,6 +94,10 @@ publishing:
       common:
         destinations:
         - PACKAGE_MANAGER
+    php_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
     python_settings:
       common:
         destinations:
