feat: Deprecated SearchAssignments in favor of SearchAllAssignments

Google APIs · copybara-github · commit 2c7f233a072c · 2021-08-31T18:33:09.000-07:00
feat: Reservation objects now contain a creation time and an update time
feat: Added commitment_start_time to capacity commitments
feat: Force deleting capacity commitments is allowed while reservations with active assignments exist
feat: ML_EXTERNAL job type is supported
feat: Optional id can be passed into CreateCapacityCommitment and CreateAssignment
docs: Clarified docs for None assignments
fix!: Fixed pattern for BiReservation object
BREAKING_CHANGE: Changed from `bireservation` to `biReservation`

PiperOrigin-RevId: 394129271
diff --git a/google/cloud/bigquery/reservation/v1/BUILD.bazel b/google/cloud/bigquery/reservation/v1/BUILD.bazel
@@ -1,4 +1,13 @@
 # This file was automatically generated by BuildFileGenerator
+# https://github.com/googleapis/rules_gapic/tree/master/bazel
+
+# Most of the manual changes to this file will be overwritten.
+# It's **only** allowed to change the following rule attribute values:
+# - names of *_gapic_assembly_* rules
+# - certain parameters of *_gapic_library rules, including but not limited to:
+#    * extra_protoc_parameters
+#    * extra_protoc_file_parameters
+# The complete list of preserved parameters can be found in the source code.
 
 # This is an API workspace, having public visibility by default makes perfect sense.
 package(default_visibility = ["//visibility:public"])
@@ -60,12 +69,15 @@ java_grpc_library(
 java_gapic_library(
     name = "reservation_java_gapic",
     srcs = [":reservation_proto_with_info"],
+    gapic_yaml = None,
     grpc_service_config = "bigqueryreservation_grpc_service_config.json",
+    service_yaml = "bigqueryreservation_v1.yaml",
     test_deps = [
         ":reservation_java_grpc",
     ],
     deps = [
         ":reservation_java_proto",
+        "//google/api:api_java_proto",
     ],
 )
 
@@ -115,6 +127,7 @@ go_gapic_library(
     srcs = [":reservation_proto_with_info"],
     grpc_service_config = "bigqueryreservation_grpc_service_config.json",
     importpath = "cloud.google.com/go/bigquery/reservation/apiv1;reservation",
+    metadata = True,
     service_yaml = "bigqueryreservation_v1.yaml",
     deps = [
         ":reservation_go_proto",
@@ -133,6 +146,7 @@ go_gapic_assembly_pkg(
     name = "gapi-cloud-bigquery-reservation-v1-go",
     deps = [
         ":reservation_go_gapic",
+        ":reservation_go_gapic_srcjar-metadata.srcjar",
         ":reservation_go_gapic_srcjar-test.srcjar",
         ":reservation_go_proto",
     ],
@@ -152,8 +166,8 @@ py_gapic_library(
     srcs = [":reservation_proto"],
     grpc_service_config = "bigqueryreservation_grpc_service_config.json",
     opt_args = [
-        "python-gapic-namespace=google.cloud",
         "python-gapic-name=bigquery_reservation",
+        "python-gapic-namespace=google.cloud",
     ],
 )
 
@@ -191,6 +205,7 @@ php_gapic_library(
     name = "reservation_php_gapic",
     srcs = [":reservation_proto_with_info"],
     grpc_service_config = "bigqueryreservation_grpc_service_config.json",
+    service_yaml = "bigqueryreservation_v1.yaml",
     deps = [
         ":reservation_php_grpc",
         ":reservation_php_proto",
@@ -261,11 +276,11 @@ ruby_cloud_gapic_library(
     name = "reservation_ruby_gapic",
     srcs = [":reservation_proto_with_info"],
     extra_protoc_parameters = [
-        "ruby-cloud-gem-name=google-cloud-bigquery-reservation-v1",
-        "ruby-cloud-env-prefix=BIGQUERY_RESERVATION",
-        "ruby-cloud-product-url=https://cloud.google.com/bigquery/docs/reference/reservations",
         "ruby-cloud-api-id=bigqueryreservation.googleapis.com",
         "ruby-cloud-api-shortname=bigqueryreservation",
+        "ruby-cloud-env-prefix=BIGQUERY_RESERVATION",
+        "ruby-cloud-gem-name=google-cloud-bigquery-reservation-v1",
+        "ruby-cloud-product-url=https://cloud.google.com/bigquery/docs/reference/reservations",
     ],
     grpc_service_config = "bigqueryreservation_grpc_service_config.json",
     ruby_cloud_description = "The BigQuery Reservation API provides the mechanisms by which enterprise users can provision and manage dedicated resources such as slots and BigQuery BI Engine memory allocations.",
diff --git a/google/cloud/bigquery/reservation/v1/bigqueryreservation_grpc_service_config.json b/google/cloud/bigquery/reservation/v1/bigqueryreservation_grpc_service_config.json
@@ -39,7 +39,7 @@
           "method": "UpdateBiReservation"
         }
       ],
-      "timeout": "60s"
+      "timeout": "300s"
     },
     {
       "name": [
diff --git a/google/cloud/bigquery/reservation/v1/bigqueryreservation_v1.yaml b/google/cloud/bigquery/reservation/v1/bigqueryreservation_v1.yaml
@@ -13,8 +13,10 @@ backend:
   rules:
   - selector: 'google.cloud.bigquery.reservation.v1.ReservationService.*'
     deadline: 30.0
-  - selector: 'google.longrunning.Operations.*'
-    deadline: 30.0
+  - selector: google.cloud.bigquery.reservation.v1.ReservationService.CreateCapacityCommitment
+    deadline: 300.0
+  - selector: google.cloud.bigquery.reservation.v1.ReservationService.DeleteCapacityCommitment
+    deadline: 300.0
 
 authentication:
   rules:
@@ -23,8 +25,3 @@ authentication:
       canonical_scopes: |-
         https://www.googleapis.com/auth/bigquery,
         https://www.googleapis.com/auth/cloud-platform
-  - selector: 'google.longrunning.Operations.*'
-    oauth:
-      canonical_scopes: |-
-        https://www.googleapis.com/auth/bigquery,
-        https://www.googleapis.com/auth/cloud-platform
diff --git a/google/cloud/bigquery/reservation/v1/reservation.proto b/google/cloud/bigquery/reservation/v1/reservation.proto
@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -202,6 +202,11 @@ service ReservationService {
   //   `project2`) could all be created and mapped to the same or different
   //   reservations.
   //
+  // "None" assignments represent an absence of the assignment. Projects
+  // assigned to None use on-demand pricing. To create a "None" assignment, use
+  // "none" as a reservation_id in the parent. Example parent:
+  // `projects/myproject/locations/US/reservations/none`.
+  //
   // Returns `google.rpc.Code.PERMISSION_DENIED` if user does not have
   // 'bigquery.admin' permissions on the project using the reservation
   // and the project that owns this reservation.
@@ -266,7 +271,7 @@ service ReservationService {
     option (google.api.method_signature) = "name";
   }
 
-  // Looks up assignments for a specified resource for a particular region.
+  // Deprecated: Looks up assignments for a specified resource for a particular region.
   // If the request is about a project:
   //
   // 1. Assignments created on the project will be returned if they exist.
@@ -290,12 +295,40 @@ service ReservationService {
   // **Note** "-" cannot be used for projects
   // nor locations.
   rpc SearchAssignments(SearchAssignmentsRequest) returns (SearchAssignmentsResponse) {
+    option deprecated = true;
     option (google.api.http) = {
       get: "/v1/{parent=projects/*/locations/*}:searchAssignments"
     };
     option (google.api.method_signature) = "parent,query";
   }
 
+  // Looks up assignments for a specified resource for a particular region.
+  // If the request is about a project:
+  //
+  // 1. Assignments created on the project will be returned if they exist.
+  // 2. Otherwise assignments created on the closest ancestor will be
+  //    returned.
+  // 3. Assignments for different JobTypes will all be returned.
+  //
+  // The same logic applies if the request is about a folder.
+  //
+  // If the request is about an organization, then assignments created on the
+  // organization will be returned (organization doesn't have ancestors).
+  //
+  // Comparing to ListAssignments, there are some behavior
+  // differences:
+  //
+  // 1. permission on the assignee will be verified in this API.
+  // 2. Hierarchy lookup (project->folder->organization) happens in this API.
+  // 3. Parent here is `projects/*/locations/*`, instead of
+  //    `projects/*/locations/*reservations/*`.
+  rpc SearchAllAssignments(SearchAllAssignmentsRequest) returns (SearchAllAssignmentsResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=projects/*/locations/*}:searchAllAssignments"
+    };
+    option (google.api.method_signature) = "parent,query";
+  }
+
   // Moves an assignment under a new reservation.
   //
   // This differs from removing an existing assignment and recreating a new one
@@ -357,10 +390,17 @@ message Reservation {
   // `google.rpc.Code.RESOURCE_EXHAUSTED`.
   int64 slot_capacity = 2;
 
-  // If false, any query using this reservation will use idle slots from other
-  // reservations within the same admin project. If true, a query using this
-  // reservation will execute with the slot capacity specified above at most.
+  // If false, any query or pipeline job using this reservation will use idle
+  // slots from other reservations within the same admin project. If true, a
+  // query or pipeline job using this reservation will execute with the slot
+  // capacity specified in the slot_capacity field at most.
   bool ignore_idle_slots = 4;
+
+  // Output only. Creation time of the reservation.
+  google.protobuf.Timestamp creation_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Last update time of the reservation.
+  google.protobuf.Timestamp update_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Capacity commitment is a way to purchase compute capacity for BigQuery jobs
@@ -439,6 +479,10 @@ message CapacityCommitment {
   // Output only. State of the commitment.
   State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 
+  // Output only. The start of the current commitment period. It is applicable only for
+  // ACTIVE capacity commitments.
+  google.protobuf.Timestamp commitment_start_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Output only. The end of the current commitment period. It is applicable only for ACTIVE
   // capacity commitments.
   google.protobuf.Timestamp commitment_end_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -549,6 +593,13 @@ message CreateCapacityCommitmentRequest {
   // If true, fail the request if another project in the organization has a
   // capacity commitment.
   bool enforce_single_admin_project_per_org = 4;
+
+  // The optional capacity commitment ID. Capacity commitment name will be
+  // generated automatically if this field is empty.
+  // This field must only contain lower case alphanumeric characters or dash.
+  // Max length is 64 characters.
+  // NOTE: this ID won't be kept if the capacity commitment is split or merged.
+  string capacity_commitment_id = 5;
 }
 
 // The request for [ReservationService.ListCapacityCommitments][google.cloud.bigquery.reservation.v1.ReservationService.ListCapacityCommitments].
@@ -601,6 +652,11 @@ message DeleteCapacityCommitmentRequest {
       type: "bigqueryreservation.googleapis.com/CapacityCommitment"
     }
   ];
+
+  // Can be used to force delete commitments even if assignments exist. Deleting
+  // commitments with assignments may cause queries to fail if they no longer
+  // have access to slots.
+  bool force = 3;
 }
 
 // The request for [ReservationService.UpdateCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.UpdateCapacityCommitment].
@@ -671,6 +727,10 @@ message Assignment {
 
     // Query jobs from the project will use the reservation.
     QUERY = 2;
+
+    // BigQuery ML jobs that use services external to BigQuery for model
+    // training. These jobs will not utilize idle slots from other reservations.
+    ML_EXTERNAL = 3;
   }
 
   // Assignment will remain in PENDING state if no active capacity commitment is
@@ -718,6 +778,12 @@ message CreateAssignmentRequest {
 
   // Assignment resource to create.
   Assignment assignment = 2;
+
+  // The optional assignment ID. Assignment name will be generated automatically
+  // if this field is empty.
+  // This field must only contain lower case alphanumeric characters or dash.
+  // Max length is 64 characters.
+  string assignment_id = 4;
 }
 
 // The request for [ReservationService.ListAssignments][google.cloud.bigquery.reservation.v1.ReservationService.ListAssignments].
@@ -798,6 +864,37 @@ message SearchAssignmentsRequest {
   string page_token = 4;
 }
 
+// The request for
+// [ReservationService.SearchAllAssignments][google.cloud.bigquery.reservation.v1.ReservationService.SearchAllAssignments].
+// Note: "bigquery.reservationAssignments.search" permission is required on the
+// related assignee.
+message SearchAllAssignmentsRequest {
+  // Required. The resource name with location (project name could be the wildcard '-'),
+  // e.g.:
+  //   `projects/-/locations/US`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "locations.googleapis.com/Location"
+    }
+  ];
+
+  // Please specify resource name as assignee in the query.
+  //
+  // Examples:
+  //
+  // * `assignee=projects/myproject`
+  // * `assignee=folders/123`
+  // * `assignee=organizations/456`
+  string query = 2;
+
+  // The maximum number of items to return per page.
+  int32 page_size = 3;
+
+  // The next_page_token value returned from a previous List request, if any.
+  string page_token = 4;
+}
+
 // The response for [ReservationService.SearchAssignments][google.cloud.bigquery.reservation.v1.ReservationService.SearchAssignments].
 message SearchAssignmentsResponse {
   // List of assignments visible to the user.
@@ -808,6 +905,16 @@ message SearchAssignmentsResponse {
   string next_page_token = 2;
 }
 
+// The response for [ReservationService.SearchAllAssignments][google.cloud.bigquery.reservation.v1.ReservationService.SearchAllAssignments].
+message SearchAllAssignmentsResponse {
+  // List of assignments visible to the user.
+  repeated Assignment assignments = 1;
+
+  // Token to retrieve the next page of results, or empty if there are no
+  // more results in the list.
+  string next_page_token = 2;
+}
+
 // The request for
 // [ReservationService.MoveAssignment][google.cloud.bigquery.reservation.v1.ReservationService.MoveAssignment].
 //
@@ -839,12 +946,12 @@ message MoveAssignmentRequest {
 message BiReservation {
   option (google.api.resource) = {
     type: "bigqueryreservation.googleapis.com/BiReservation"
-    pattern: "projects/{project}/locations/{location}/bireservation"
+    pattern: "projects/{project}/locations/{location}/biReservation"
   };
 
   // The resource name of the singleton BI reservation.
   // Reservation names have the form
-  // `projects/{project_id}/locations/{location_id}/bireservation`.
+  // `projects/{project_id}/locations/{location_id}/biReservation`.
   string name = 1;
 
   // Output only. The last update timestamp of a reservation.
@@ -857,7 +964,7 @@ message BiReservation {
 // A request to get a singleton BI reservation.
 message GetBiReservationRequest {
   // Required. Name of the requested reservation, for example:
-  // `projects/{project_id}/locations/{location_id}/bireservation`
+  // `projects/{project_id}/locations/{location_id}/biReservation`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {

Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@`
`39`	`39`	`"method": "UpdateBiReservation"`
`40`	`40`	`}`
`41`	`41`	`],`
`42`		`- "timeout": "60s"`
	`42`	`+ "timeout": "300s"`
`43`	`43`	`},`
`44`	`44`	`{`
`45`	`45`	`"name": [`