codekingpro/portable-devtools

1// Copyright 2021 Google LLC.2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//     http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.14 15// This file contains custom annotations that are used by GAPIC generators to16// handle Long Running Operation methods (LRO) that are NOT compliant with17// https://google.aip.dev/151. These annotations are public for technical18// reasons only. Please DO NOT USE them in your protos.19syntax = "proto3";20 21package google.cloud;22 23import "google/protobuf/descriptor.proto";24 25option go_package = "google.golang.org/genproto/googleapis/cloud/extendedops;extendedops";26option java_multiple_files = true;27option java_outer_classname = "ExtendedOperationsProto";28option java_package = "com.google.cloud";29option objc_class_prefix = "GAPI";30 31// FieldOptions to match corresponding fields in the initial request,32// polling request and operation response messages.33//34// Example:35//36// In an API-specific operation message:37//38//     message MyOperation {39//       string http_error_message = 1 [(operation_field) = ERROR_MESSAGE];40//       int32 http_error_status_code = 2 [(operation_field) = ERROR_CODE];41//       string id = 3 [(operation_field) = NAME];42//       Status status = 4 [(operation_field) = STATUS];43//     }44//45// In a polling request message (the one which is used to poll for an LRO46// status):47//48//     message MyPollingRequest {49//       string operation = 1 [(operation_response_field) = "id"];50//       string project = 2;51//       string region = 3;52//     }53//54// In an initial request message (the one which starts an LRO):55//56//    message MyInitialRequest {57//      string my_project = 2 [(operation_request_field) = "project"];58//      string my_region = 3 [(operation_request_field) = "region"];59//    }60//61extend google.protobuf.FieldOptions {62  // A field annotation that maps fields in an API-specific Operation object to63  // their standard counterparts in google.longrunning.Operation. See64  // OperationResponseMapping enum definition.65  OperationResponseMapping operation_field = 1149;66 67  // A field annotation that maps fields in the initial request message68  // (the one which started the LRO) to their counterparts in the polling69  // request message. For non-standard LRO, the polling response may be missing70  // some of the information needed to make a subsequent polling request. The71  // missing information (for example, project or region ID) is contained in the72  // fields of the initial request message that this annotation must be applied73  // to. The string value of the annotation corresponds to the name of the74  // counterpart field in the polling request message that the annotated field's75  // value will be copied to.76  string operation_request_field = 1150;77 78  // A field annotation that maps fields in the polling request message to their79  // counterparts in the initial and/or polling response message. The initial80  // and the polling methods return an API-specific Operation object. Some of81  // the fields from that response object must be reused in the subsequent82  // request (like operation name/ID) to fully identify the polled operation.83  // This annotation must be applied to the fields in the polling request84  // message, the string value of the annotation must correspond to the name of85  // the counterpart field in the Operation response object whose value will be86  // copied to the annotated field.87  string operation_response_field = 1151;88}89 90// MethodOptions to identify the actual service and method used for operation91// status polling.92//93// Example:94//95// In a method, which starts an LRO:96//97//     service MyService {98//       rpc Foo(MyInitialRequest) returns (MyOperation) {99//         option (operation_service) = "MyPollingService";100//       }101//     }102//103// In a polling method:104//105//     service MyPollingService {106//       rpc Get(MyPollingRequest) returns (MyOperation) {107//         option (operation_polling_method) = true;108//       }109//     }110extend google.protobuf.MethodOptions {111  // A method annotation that maps an LRO method (the one which starts an LRO)112  // to the service, which will be used to poll for the operation status. The113  // annotation must be applied to the method which starts an LRO, the string114  // value of the annotation must correspond to the name of the service used to115  // poll for the operation status.116  string operation_service = 1249;117 118  // A method annotation that marks methods that can be used for polling119  // operation status (e.g. the MyPollingService.Get(MyPollingRequest) method).120  bool operation_polling_method = 1250;121}122 123// An enum to be used to mark the essential (for polling) fields in an124// API-specific Operation object. A custom Operation object may contain many125// different fields, but only few of them are essential to conduct a successful126// polling process.127enum OperationResponseMapping {128  // Do not use.129  UNDEFINED = 0;130 131  // A field in an API-specific (custom) Operation object which carries the same132  // meaning as google.longrunning.Operation.name.133  NAME = 1;134 135  // A field in an API-specific (custom) Operation object which carries the same136  // meaning as google.longrunning.Operation.done. If the annotated field is of137  // an enum type, `annotated_field_name == EnumType.DONE` semantics should be138  // equivalent to `Operation.done == true`. If the annotated field is of type139  // boolean, then it should follow the same semantics as Operation.done.140  // Otherwise, a non-empty value should be treated as `Operation.done == true`.141  STATUS = 2;142 143  // A field in an API-specific (custom) Operation object which carries the same144  // meaning as google.longrunning.Operation.error.code.145  ERROR_CODE = 3;146 147  // A field in an API-specific (custom) Operation object which carries the same148  // meaning as google.longrunning.Operation.error.message.149  ERROR_MESSAGE = 4;150}