diff --git a/google/cloud/bigquery/reservation/v1/reservation.proto b/google/cloud/bigquery/reservation/v1/reservation.proto index caa296bc..e3c24d42 100644 --- a/google/cloud/bigquery/reservation/v1/reservation.proto +++ b/google/cloud/bigquery/reservation/v1/reservation.proto @@ -38,13 +38,13 @@ option java_package = "com.google.cloud.bigquery.reservation.v1"; // parallelism. In a scan of a multi-partitioned table, a single slot operates // on a single partition of the table. A reservation resource exists as a child // resource of the admin project and location, e.g.: -// projects/myproject/locations/US/reservations/reservationName. +// `projects/myproject/locations/US/reservations/reservationName`. // // A capacity commitment is a way to purchase compute capacity for BigQuery jobs // (in the form of slots) with some committed period of usage. A capacity // commitment resource exists as a child resource of the admin project and // location, e.g.: -// projects/myproject/locations/US/capacityCommitments/id. +// `projects/myproject/locations/US/capacityCommitments/id`. service ReservationService { option (google.api.default_host) = "bigqueryreservation.googleapis.com"; option (google.api.oauth_scopes) = @@ -61,7 +61,8 @@ service ReservationService { } // Lists all the reservations for the project in the specified location. - rpc ListReservations(ListReservationsRequest) returns (ListReservationsResponse) { + rpc ListReservations(ListReservationsRequest) + returns (ListReservationsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/locations/*}/reservations" }; @@ -79,7 +80,8 @@ service ReservationService { // Deletes a reservation. // Returns `google.rpc.Code.FAILED_PRECONDITION` when reservation has // assignments. - rpc DeleteReservation(DeleteReservationRequest) returns (google.protobuf.Empty) { + rpc DeleteReservation(DeleteReservationRequest) + returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{name=projects/*/locations/*/reservations/*}" }; @@ -96,7 +98,8 @@ service ReservationService { } // Creates a new capacity commitment resource. - rpc CreateCapacityCommitment(CreateCapacityCommitmentRequest) returns (CapacityCommitment) { + rpc CreateCapacityCommitment(CreateCapacityCommitmentRequest) + returns (CapacityCommitment) { option (google.api.http) = { post: "/v1/{parent=projects/*/locations/*}/capacityCommitments" body: "capacity_commitment" @@ -105,7 +108,8 @@ service ReservationService { } // Lists all the capacity commitments for the admin project. - rpc ListCapacityCommitments(ListCapacityCommitmentsRequest) returns (ListCapacityCommitmentsResponse) { + rpc ListCapacityCommitments(ListCapacityCommitmentsRequest) + returns (ListCapacityCommitmentsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/locations/*}/capacityCommitments" }; @@ -113,7 +117,8 @@ service ReservationService { } // Returns information about the capacity commitment. - rpc GetCapacityCommitment(GetCapacityCommitmentRequest) returns (CapacityCommitment) { + rpc GetCapacityCommitment(GetCapacityCommitmentRequest) + returns (CapacityCommitment) { option (google.api.http) = { get: "/v1/{name=projects/*/locations/*/capacityCommitments/*}" }; @@ -123,7 +128,8 @@ service ReservationService { // Deletes a capacity commitment. Attempting to delete capacity commitment // before its commitment_end_time will fail with the error code // `google.rpc.Code.FAILED_PRECONDITION`. - rpc DeleteCapacityCommitment(DeleteCapacityCommitmentRequest) returns (google.protobuf.Empty) { + rpc DeleteCapacityCommitment(DeleteCapacityCommitmentRequest) + returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{name=projects/*/locations/*/capacityCommitments/*}" }; @@ -132,11 +138,13 @@ service ReservationService { // Updates an existing capacity commitment. // - // Only plan and renewal_plan fields can be updated. + // Only `plan` and `renewal_plan` fields can be updated. + // // Plan can only be changed to a plan of a longer commitment period. // Attempting to change to a plan with shorter commitment period will fail // with the error code `google.rpc.Code.FAILED_PRECONDITION`. - rpc UpdateCapacityCommitment(UpdateCapacityCommitmentRequest) returns (CapacityCommitment) { + rpc UpdateCapacityCommitment(UpdateCapacityCommitmentRequest) + returns (CapacityCommitment) { option (google.api.http) = { patch: "/v1/{capacity_commitment.name=projects/*/locations/*/capacityCommitments/*}" body: "capacity_commitment" @@ -145,11 +153,15 @@ service ReservationService { } // Splits capacity commitment to two commitments of the same plan and - // commitment_end_time. A common use case to do that is to perform a downgrade - // e.g., in order to downgrade from 10000 slots to 8000, one might split 10000 - // capacity commitment to 2000 and 8000, change the plan of the first one to - // flex and then delete it. - rpc SplitCapacityCommitment(SplitCapacityCommitmentRequest) returns (SplitCapacityCommitmentResponse) { + // `commitment_end_time`. + // + // A common use case is to enable downgrading commitments. + // + // For example, in order to downgrade from 10000 slots to 8000, you might + // split a 10000 capacity commitment into commitments of 2000 and 8000. Then, + // you would change the plan of the first one to `FLEX` and then delete it. + rpc SplitCapacityCommitment(SplitCapacityCommitmentRequest) + returns (SplitCapacityCommitmentResponse) { option (google.api.http) = { post: "/v1/{name=projects/*/locations/*/capacityCommitments/*}:split" body: "*" @@ -157,11 +169,15 @@ service ReservationService { option (google.api.method_signature) = "name,slot_count"; } - // Merges capacity commitments of the same plan into one. Resulting capacity - // commitment has the longer commitment_end_time out of the two. Attempting to - // merge capacity commitments of different plan will fail with the error code - // `google.rpc.Code.FAILED_PRECONDITION`. - rpc MergeCapacityCommitments(MergeCapacityCommitmentsRequest) returns (CapacityCommitment) { + // Merges capacity commitments of the same plan into a single commitment. + // + // The resulting capacity commitment has the greater commitment_end_time + // out of the to-be-merged capacity commitments. + // + // Attempting to merge capacity commitments of different plan will fail + // with the error code `google.rpc.Code.FAILED_PRECONDITION`. + rpc MergeCapacityCommitments(MergeCapacityCommitmentsRequest) + returns (CapacityCommitment) { option (google.api.http) = { post: "/v1/{parent=projects/*/locations/*}/capacityCommitments:merge" body: "*" @@ -169,21 +185,34 @@ service ReservationService { option (google.api.method_signature) = "parent,capacity_commitment_ids"; } - // Creates an object which allows the given project to submit jobs - // of a certain type using slots from the specified reservation. Currently a + // Creates an assignment object which allows the given project to submit jobs + // of a certain type using slots from the specified reservation. + // + // Currently a // resource (project, folder, organization) can only have one assignment per - // {job_type, location}, and that reservation will be used for all jobs of the - // matching type. Within the organization, different assignments can be - // created on projects, folders or organization level. During query execution, + // each (job_type, location) combination, and that reservation will be used + // for all jobs of the matching type. + // + // Different assignments can be created on different levels of the + // projects, folders or organization hierarchy. During query execution, // the assignment is looked up at the project, folder and organization levels - // in that order. The first assignment found is applied to the query. When - // creating assignments, it does not matter if other assignments exist at - // higher levels. E.g: organizationA contains project1, project2. Assignments - // for organizationA, project1 and project2 could all be created, mapping to - // the same or different reservations. + // in that order. The first assignment found is applied to the query. + // + // When creating assignments, it does not matter if other assignments exist at + // higher levels. + // + // Example: + // + // * The organization `organizationA` contains two projects, `project1` + // and `project2`. + // * Assignments for all three entities (`organizationA`, `project1`, and + // `project2`) could all be created and mapped to the same or different + // reservations. + // // 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. + // // Returns `google.rpc.Code.INVALID_ARGUMENT` when location of the assignment // does not match location of the reservation. rpc CreateAssignment(CreateAssignmentRequest) returns (Assignment) { @@ -195,18 +224,28 @@ service ReservationService { } // Lists assignments. - // Only explicitly created assignments will be returned. E.g: - // organizationA contains project1 and project2. Reservation res1 exists. - // CreateAssignment was invoked previously and following assignments were - // created explicitly: - // - // - // Then this API will just return the above two assignments for reservation - // res1, and no expansion/merge will happen. Wildcard "-" can be used for + // + // Only explicitly created assignments will be returned. + // + // Example: + // + // * Organization `organizationA` contains two projects, `project1` and + // `project2`. + // * Reservation `res1` exists and was created previously. + // * CreateAssignment was used previously to define the following + // associations between entities and reservations: `` + // and `` + // + // In this example, ListAssignments will just return the above two assignments + // for reservation `res1`, and no expansion/merge will happen. + // + // The wildcard "-" can be used for // reservations in the request. In that case all assignments belongs to the - // specified project and location will be listed. Note - // "-" cannot be used for projects nor locations. - rpc ListAssignments(ListAssignmentsRequest) returns (ListAssignmentsResponse) { + // specified project and location will be listed. + // + // **Note** "-" cannot be used for projects nor locations. + rpc ListAssignments(ListAssignmentsRequest) + returns (ListAssignmentsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/locations/*/reservations/*}/assignments" }; @@ -214,16 +253,22 @@ service ReservationService { } // Deletes a assignment. No expansion will happen. - // E.g: - // organizationA contains project1 and project2. Reservation res1 exists. - // CreateAssignment was invoked previously and following assignments were - // created explicitly: - // - // - // Then deletion of won't affect . After - // deletion of , queries from project1 will still use - // res1, while queries from project2 will use on-demand mode. - rpc DeleteAssignment(DeleteAssignmentRequest) returns (google.protobuf.Empty) { + // + // Example: + // + // * Organization `organizationA` contains two projects, `project1` and + // `project2`. + // * Reservation `res1` exists and was created previously. + // * CreateAssignment was used previously to define the following + // associations between entities and reservations: `` + // and `` + // + // In this example, deletion of the `` assignment won't + // affect the other assignment ``. After said deletion, + // queries from `project1` will still use `res1` while queries from + // `project2` will switch to use on-demand mode. + rpc DeleteAssignment(DeleteAssignmentRequest) + returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{name=projects/*/locations/*/reservations/*/assignments/*}" }; @@ -232,33 +277,40 @@ service ReservationService { // 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. - // Same logic applies if the request is about a folder. + // + // 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/*. - // Note "-" cannot be used for projects + // + // 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/*`. + // + // **Note** "-" cannot be used for projects // nor locations. - rpc SearchAssignments(SearchAssignmentsRequest) returns (SearchAssignmentsResponse) { + rpc SearchAssignments(SearchAssignmentsRequest) + returns (SearchAssignmentsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/locations/*}:searchAssignments" }; option (google.api.method_signature) = "parent,query"; } - // Moves a assignment under a new reservation. Customers can do this by - // deleting the existing assignment followed by creating another assignment - // under the new reservation, but this method provides a transactional way to - // do so, to make sure the assignee always has an associated reservation. - // Without the method customers might see some queries run on-demand which - // might be unexpected. + // Moves an assignment under a new reservation. + // + // This differs from removing an existing assignment and recreating a new one + // by providing a transactional change that ensures an assignee always has an + // associated reservation. rpc MoveAssignment(MoveAssignmentRequest) returns (Assignment) { option (google.api.http) = { post: "/v1/{name=projects/*/locations/*/reservations/*/assignments/*}:move" @@ -276,8 +328,10 @@ service ReservationService { } // Updates a BI reservation. - // Only fields specified in the field_mask are updated. - // Singleton BI reservation always exists with default size 0. + // + // Only fields specified in the `field_mask` are updated. + // + // A singleton BI reservation always exists with default size 0. // In order to reserve BI capacity it needs to be updated to an amount // greater than 0. In order to release BI capacity reservation size // must be set to 0. @@ -298,13 +352,15 @@ message Reservation { }; // The resource name of the reservation, e.g., - // "projects/*/locations/*/reservations/team1-prod". + // `projects/*/locations/*/reservations/team1-prod`. string name = 1; // Minimum slots available to this reservation. A slot is a unit of // computational power in BigQuery, and serves as the unit of parallelism. + // // Queries using this reservation might use more slots during runtime if // ignore_idle_slots is set to false. + // // If the new reservation's slot capacity exceed the parent's slot capacity or // if total slot capacity of the new reservation and its siblings exceeds the // parent's slot capacity, the request will fail with @@ -320,8 +376,10 @@ message Reservation { // Capacity commitment is a way to purchase compute capacity for BigQuery jobs // (in the form of slots) with some committed period of usage. Annual // commitments renew by default. Commitments can be removed after their -// commitment end time passes. In order to remove annual commitment, its plan -// needs to be changed to monthly or flex first. +// commitment end time passes. +// +// In order to remove annual commitment, its plan needs to be changed +// to monthly or flex first. // // A capacity commitment resource exists as a child resource of the admin // project. @@ -343,6 +401,12 @@ message CapacityCommitment { // any time. FLEX = 3; + // Trial commitments have a committed period of 182 days after becoming + // ACTIVE. After that, they are converted to a new commitment based on the + // `renewal_plan`. Default `renewal_plan` for Trial commitment is Flex so + // that it can be deleted right after committed period ends. + TRIAL = 5; + // Monthly commitments have a committed period of 30 days after becoming // ACTIVE. After that, they are not in a committed period anymore and can be // removed any time. @@ -373,7 +437,7 @@ message CapacityCommitment { } // Output only. The resource name of the capacity commitment, e.g., - // projects/myproject/locations/US/capacityCommitments/123 + // `projects/myproject/locations/US/capacityCommitments/123` string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; // Number of slots in this commitment. @@ -385,23 +449,26 @@ message CapacityCommitment { // Output only. State of the commitment. State state = 4 [(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]; + // 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]; // Output only. For FAILED commitment plan, provides the reason of failure. - google.rpc.Status failure_status = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.rpc.Status failure_status = 7 + [(google.api.field_behavior) = OUTPUT_ONLY]; // The plan this capacity commitment is converted to after commitment_end_time // passes. Once the plan is changed, committed period is extended according to - // commitment plan. Only applicable for ANNUAL commitments. + // commitment plan. Only applicable for ANNUAL and TRIAL commitments. CommitmentPlan renewal_plan = 8; } -// The request for [ReservationService.CreateReservation][google.cloud.bigquery.reservation.v1.ReservationService.CreateReservation]. +// The request for +// [ReservationService.CreateReservation][google.cloud.bigquery.reservation.v1.ReservationService.CreateReservation]. message CreateReservationRequest { // Required. Project, location. E.g., - // projects/myproject/locations/US + // `projects/myproject/locations/US` string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -413,11 +480,12 @@ message CreateReservationRequest { // characters or dash. Max length is 64 characters. string reservation_id = 2; - // Content of the new reservation to create. + // Definition of the new reservation to create. Reservation reservation = 3; } -// The request for [ReservationService.ListReservations][google.cloud.bigquery.reservation.v1.ReservationService.ListReservations]. +// The request for +// [ReservationService.ListReservations][google.cloud.bigquery.reservation.v1.ReservationService.ListReservations]. message ListReservationsRequest { // Required. The parent resource name containing project and location, e.g.: // "projects/myproject/locations/US" @@ -428,14 +496,15 @@ message ListReservationsRequest { } ]; - // The maximum number of items to return. + // The maximum number of items to return per page. int32 page_size = 2; // The next_page_token value returned from a previous List request, if any. string page_token = 3; } -// The response for [ReservationService.ListReservations][google.cloud.bigquery.reservation.v1.ReservationService.ListReservations]. +// The response for +// [ReservationService.ListReservations][google.cloud.bigquery.reservation.v1.ReservationService.ListReservations]. message ListReservationsResponse { // List of reservations visible to the user. repeated Reservation reservations = 1; @@ -445,10 +514,11 @@ message ListReservationsResponse { string next_page_token = 2; } -// The request for [ReservationService.GetReservation][google.cloud.bigquery.reservation.v1.ReservationService.GetReservation]. +// The request for +// [ReservationService.GetReservation][google.cloud.bigquery.reservation.v1.ReservationService.GetReservation]. message GetReservationRequest { // Required. Resource name of the reservation to retrieve. E.g., - // projects/myproject/locations/US/reservations/team1-prod + // `projects/myproject/locations/US/reservations/team1-prod` string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -457,10 +527,11 @@ message GetReservationRequest { ]; } -// The request for [ReservationService.DeleteReservation][google.cloud.bigquery.reservation.v1.ReservationService.DeleteReservation]. +// The request for +// [ReservationService.DeleteReservation][google.cloud.bigquery.reservation.v1.ReservationService.DeleteReservation]. message DeleteReservationRequest { // Required. Resource name of the reservation to retrieve. E.g., - // projects/myproject/locations/US/reservations/team1-prod + // `projects/myproject/locations/US/reservations/team1-prod` string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -469,7 +540,8 @@ message DeleteReservationRequest { ]; } -// The request for [ReservationService.UpdateReservation][google.cloud.bigquery.reservation.v1.ReservationService.UpdateReservation]. +// The request for +// [ReservationService.UpdateReservation][google.cloud.bigquery.reservation.v1.ReservationService.UpdateReservation]. message UpdateReservationRequest { // Content of the reservation to update. Reservation reservation = 1; @@ -478,7 +550,8 @@ message UpdateReservationRequest { google.protobuf.FieldMask update_mask = 2; } -// The request for [ReservationService.CreateCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.CreateCapacityCommitment]. +// The request for +// [ReservationService.CreateCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.CreateCapacityCommitment]. message CreateCapacityCommitmentRequest { // Required. Resource name of the parent reservation. E.g., // projects/myproject/locations/US @@ -497,7 +570,8 @@ message CreateCapacityCommitmentRequest { bool enforce_single_admin_project_per_org = 4; } -// The request for [ReservationService.ListCapacityCommitments][google.cloud.bigquery.reservation.v1.ReservationService.ListCapacityCommitments]. +// The request for +// [ReservationService.ListCapacityCommitments][google.cloud.bigquery.reservation.v1.ReservationService.ListCapacityCommitments]. message ListCapacityCommitmentsRequest { // Required. Resource name of the parent reservation. E.g., // projects/myproject/locations/US @@ -515,7 +589,8 @@ message ListCapacityCommitmentsRequest { string page_token = 3; } -// The response for [ReservationService.ListCapacityCommitments][google.cloud.bigquery.reservation.v1.ReservationService.ListCapacityCommitments]. +// The response for +// [ReservationService.ListCapacityCommitments][google.cloud.bigquery.reservation.v1.ReservationService.ListCapacityCommitments]. message ListCapacityCommitmentsResponse { // List of capacity commitments visible to the user. repeated CapacityCommitment capacity_commitments = 1; @@ -525,7 +600,8 @@ message ListCapacityCommitmentsResponse { string next_page_token = 2; } -// The request for [ReservationService.GetCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.GetCapacityCommitment]. +// The request for +// [ReservationService.GetCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.GetCapacityCommitment]. message GetCapacityCommitmentRequest { // Required. Resource name of the capacity commitment to retrieve. E.g., // projects/myproject/locations/US/capacityCommitments/123 @@ -537,7 +613,8 @@ message GetCapacityCommitmentRequest { ]; } -// The request for [ReservationService.DeleteCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.DeleteCapacityCommitment]. +// The request for +// [ReservationService.DeleteCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.DeleteCapacityCommitment]. message DeleteCapacityCommitmentRequest { // Required. Resource name of the capacity commitment to delete. E.g., // projects/myproject/locations/US/capacityCommitments/123 @@ -549,7 +626,8 @@ message DeleteCapacityCommitmentRequest { ]; } -// The request for [ReservationService.UpdateCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.UpdateCapacityCommitment]. +// The request for +// [ReservationService.UpdateCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.UpdateCapacityCommitment]. message UpdateCapacityCommitmentRequest { // Content of the capacity commitment to update. CapacityCommitment capacity_commitment = 1; @@ -558,7 +636,8 @@ message UpdateCapacityCommitmentRequest { google.protobuf.FieldMask update_mask = 2; } -// The request for [ReservationService.SplitCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.SplitCapacityCommitment]. +// The request for +// [ReservationService.SplitCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.SplitCapacityCommitment]. message SplitCapacityCommitmentRequest { // Required. The resource name e.g.,: // projects/myproject/locations/US/capacityCommitments/123 @@ -573,7 +652,8 @@ message SplitCapacityCommitmentRequest { int64 slot_count = 2; } -// The response for [ReservationService.SplitCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.SplitCapacityCommitment]. +// The response for +// [ReservationService.SplitCapacityCommitment][google.cloud.bigquery.reservation.v1.ReservationService.SplitCapacityCommitment]. message SplitCapacityCommitmentResponse { // First capacity commitment, result of a split. CapacityCommitment first = 1; @@ -582,13 +662,14 @@ message SplitCapacityCommitmentResponse { CapacityCommitment second = 2; } -// The request for [ReservationService.MergeCapacityCommitments][google.cloud.bigquery.reservation.v1.ReservationService.MergeCapacityCommitments]. +// The request for +// [ReservationService.MergeCapacityCommitments][google.cloud.bigquery.reservation.v1.ReservationService.MergeCapacityCommitments]. message MergeCapacityCommitmentsRequest { // Parent resource that identifies admin project and location e.g., // projects/myproject/locations/us string parent = 1 [(google.api.resource_reference) = { - child_type: "bigqueryreservation.googleapis.com/CapacityCommitment" - }]; + child_type: "bigqueryreservation.googleapis.com/CapacityCommitment" + }]; // Ids of capacity commitments to merge. // These capacity commitments must exist under admin project and location @@ -633,11 +714,11 @@ message Assignment { } // Output only. Name of the resource. E.g.: - // projects/myproject/locations/US/reservations/team1-prod/assignments/123. + // `projects/myproject/locations/US/reservations/team1-prod/assignments/123`. string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; // The resource which will use the reservation. E.g. - // projects/myproject, folders/123, organizations/456. + // `projects/myproject`, `folders/123`, or `organizations/456`. string assignee = 4; // Which type of jobs will use the reservation. @@ -647,12 +728,13 @@ message Assignment { State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; } -// The request for [ReservationService.CreateAssignment][google.cloud.bigquery.reservation.v1.ReservationService.CreateAssignment]. +// The request for +// [ReservationService.CreateAssignment][google.cloud.bigquery.reservation.v1.ReservationService.CreateAssignment]. // Note: "bigquery.reservationAssignments.create" permission is required on the // related assignee. message CreateAssignmentRequest { // Required. The parent resource name of the assignment - // E.g.: projects/myproject/locations/US/reservations/team1-prod + // E.g. `projects/myproject/locations/US/reservations/team1-prod` string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -664,12 +746,16 @@ message CreateAssignmentRequest { Assignment assignment = 2; } -// The request for [ReservationService.ListAssignments][google.cloud.bigquery.reservation.v1.ReservationService.ListAssignments]. +// The request for +// [ReservationService.ListAssignments][google.cloud.bigquery.reservation.v1.ReservationService.ListAssignments]. message ListAssignmentsRequest { // Required. The parent resource name e.g.: - // projects/myproject/locations/US/reservations/team1-prod + // + // `projects/myproject/locations/US/reservations/team1-prod` + // // Or: - // projects/myproject/locations/US/reservations/- + // + // `projects/myproject/locations/US/reservations/-` string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -677,14 +763,15 @@ message ListAssignmentsRequest { } ]; - // The maximum number of items to return. + // The maximum number of items to return per page. int32 page_size = 2; // The next_page_token value returned from a previous List request, if any. string page_token = 3; } -// The response for [ReservationService.ListAssignments][google.cloud.bigquery.reservation.v1.ReservationService.ListAssignments]. +// The response for +// [ReservationService.ListAssignments][google.cloud.bigquery.reservation.v1.ReservationService.ListAssignments]. message ListAssignmentsResponse { // List of assignments visible to the user. repeated Assignment assignments = 1; @@ -694,12 +781,13 @@ message ListAssignmentsResponse { string next_page_token = 2; } -// The request for [ReservationService.DeleteAssignment][google.cloud.bigquery.reservation.v1.ReservationService.DeleteAssignment]. +// The request for +// [ReservationService.DeleteAssignment][google.cloud.bigquery.reservation.v1.ReservationService.DeleteAssignment]. // Note: "bigquery.reservationAssignments.delete" permission is required on the // related assignee. message DeleteAssignmentRequest { - // Required. Name of the resource, e.g.: - // projects/myproject/locations/US/reservations/team1-prod/assignments/123 + // Required. Name of the resource, e.g. + // `projects/myproject/locations/US/reservations/team1-prod/assignments/123` string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -713,8 +801,8 @@ message DeleteAssignmentRequest { // Note: "bigquery.reservationAssignments.search" permission is required on the // related assignee. message SearchAssignmentsRequest { - // Required. The resource name of the admin project(containing project and location), - // e.g.: + // Required. The resource name of the admin project(containing project and + // location), e.g.: // "projects/myproject/locations/US". string parent = 1 [ (google.api.field_behavior) = REQUIRED, @@ -724,19 +812,23 @@ message SearchAssignmentsRequest { ]; // Please specify resource name as assignee in the query. - // e.g., "assignee=projects/myproject" - // "assignee=folders/123" - // "assignee=organizations/456" + // + // Examples: + // + // * `assignee=projects/myproject` + // * `assignee=folders/123` + // * `assignee=organizations/456` string query = 2; - // The maximum number of items to return. + // 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]. +// The response for +// [ReservationService.SearchAssignments][google.cloud.bigquery.reservation.v1.ReservationService.SearchAssignments]. message SearchAssignmentsResponse { // List of assignments visible to the user. repeated Assignment assignments = 1; @@ -748,14 +840,17 @@ message SearchAssignmentsResponse { // The request for // [ReservationService.MoveAssignment][google.cloud.bigquery.reservation.v1.ReservationService.MoveAssignment]. -// Note: "bigquery.reservationAssignments.create" permission is required on the -// destination_id. Note: "bigquery.reservationAssignments.create" and -// "bigquery.reservationAssignments.delete" permission is required on the +// +// **Note**: "bigquery.reservationAssignments.create" permission is required on +// the destination_id. +// +// **Note**: "bigquery.reservationAssignments.create" and +// "bigquery.reservationAssignments.delete" permission are required on the // related assignee. message MoveAssignmentRequest { // Required. The resource name of the assignment, - // e.g.: - // projects/myproject/locations/US/reservations/team1-prod/assignments/123 + // e.g. + // `projects/myproject/locations/US/reservations/team1-prod/assignments/123` string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -764,7 +859,7 @@ message MoveAssignmentRequest { ]; // The new reservation ID, e.g.: - // projects/myotherproject/locations/US/reservations/team2-prod + // `projects/myotherproject/locations/US/reservations/team2-prod` string destination_id = 3; } @@ -781,7 +876,8 @@ message BiReservation { string name = 1; // Output only. The last update timestamp of a reservation. - google.protobuf.Timestamp update_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp update_time = 3 + [(google.api.field_behavior) = OUTPUT_ONLY]; // Size of a reservation, in bytes. int64 size = 4;