feat: add extended_operations.proto (#77)

* feat: add extended_operations.proto * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot 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 · Dec 7, 2021 · bc85849 · bc85849
1 parent 1ae0bbc
commit bc85849
Show file tree

Hide file tree

Showing 2 changed files with 381 additions and 0 deletions.
diff --git a/google/cloud/extended_operations.proto b/google/cloud/extended_operations.proto
@@ -0,0 +1,150 @@
+// 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.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// This file contains custom annotations that are used by GAPIC generators to
+// handle Long Running Operation methods (LRO) that are NOT compliant with
+// https://google.aip.dev/151. These annotations are public for technical
+// reasons only. Please DO NOT USE them in your protos.
+syntax = "proto3";
+
+package google.cloud;
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/cloud/extendedops;extendedops";
+option java_multiple_files = true;
+option java_outer_classname = "ExtendedOperationsProto";
+option java_package = "com.google.cloud";
+option objc_class_prefix = "GAPI";
+
+// FieldOptions to match corresponding fields in the initial request,
+// polling request and operation response messages.
+//
+// Example:
+//
+// In an API-specific operation message:
+//
+//     message MyOperation {
+//       string http_error_message = 1 [(operation_field) = ERROR_MESSAGE];
+//       int32 http_error_status_code = 2 [(operation_field) = ERROR_CODE];
+//       string id = 3 [(operation_field) = NAME];
+//       Status status = 4 [(operation_field) = STATUS];
+//     }
+//
+// In a polling request message (the one which is used to poll for an LRO
+// status):
+//
+//     message MyPollingRequest {
+//       string operation = 1 [(operation_response_field) = "id"];
+//       string project = 2;
+//       string region = 3;
+//     }
+//
+// In an initial request message (the one which starts an LRO):
+//
+//    message MyInitialRequest {
+//      string my_project = 2 [(operation_request_field) = "project"];
+//      string my_region = 3 [(operation_request_field) = "region"];
+//    }
+//
+extend google.protobuf.FieldOptions {
+  // A field annotation that maps fields in an API-specific Operation object to
+  // their standard counterparts in google.longrunning.Operation. See
+  // OperationResponseMapping enum definition.
+  OperationResponseMapping operation_field = 1149;
+
+  // A field annotation that maps fields in the initial request message
+  // (the one which started the LRO) to their counterparts in the polling
+  // request message. For non-standard LRO, the polling response may be missing
+  // some of the information needed to make a subsequent polling request. The
+  // missing information (for example, project or region ID) is contained in the
+  // fields of the initial request message that this annotation must be applied
+  // to. The string value of the annotation corresponds to the name of the
+  // counterpart field in the polling request message that the annotated field's
+  // value will be copied to.
+  string operation_request_field = 1150;
+
+  // A field annotation that maps fields in the polling request message to their
+  // counterparts in the initial and/or polling response message. The initial
+  // and the polling methods return an API-specific Operation object. Some of
+  // the fields from that response object must be reused in the subsequent
+  // request (like operation name/ID) to fully identify the polled operation.
+  // This annotation must be applied to the fields in the polling request
+  // message, the string value of the annotation must correspond to the name of
+  // the counterpart field in the Operation response object whose value will be
+  // copied to the annotated field.
+  string operation_response_field = 1151;
+}
+
+// MethodOptions to identify the actual service and method used for operation
+// status polling.
+//
+// Example:
+//
+// In a method, which starts an LRO:
+//
+//     service MyService {
+//       rpc Foo(MyInitialRequest) returns (MyOperation) {
+//         option (operation_service) = "MyPollingService";
+//       }
+//     }
+//
+// In a polling method:
+//
+//     service MyPollingService {
+//       rpc Get(MyPollingRequest) returns (MyOperation) {
+//         option (operation_polling_method) = true;
+//       }
+//     }
+extend google.protobuf.MethodOptions {
+  // A method annotation that maps an LRO method (the one which starts an LRO)
+  // to the service, which will be used to poll for the operation status. The
+  // annotation must be applied to the method which starts an LRO, the string
+  // value of the annotation must correspond to the name of the service used to
+  // poll for the operation status.
+  string operation_service = 1249;
+
+  // A method annotation that marks methods that can be used for polling
+  // operation status (e.g. the MyPollingService.Get(MyPollingRequest) method).
+  bool operation_polling_method = 1250;
+}
+
+// An enum to be used to mark the essential (for polling) fields in an
+// API-specific Operation object. A custom Operation object may contain many
+// different fields, but only few of them are essential to conduct a successful
+// polling process.
+enum OperationResponseMapping {
+  // Do not use.
+  UNDEFINED = 0;
+
+  // A field in an API-specific (custom) Operation object which carries the same
+  // meaning as google.longrunning.Operation.name.
+  NAME = 1;
+
+  // A field in an API-specific (custom) Operation object which carries the same
+  // meaning as google.longrunning.Operation.done. If the annotated field is of
+  // an enum type, `annotated_field_name == EnumType.DONE` semantics should be
+  // equivalent to `Operation.done == true`. If the annotated field is of type
+  // boolean, then it should follow the same semantics as Operation.done.
+  // Otherwise, a non-empty value should be treated as `Operation.done == true`.
+  STATUS = 2;
+
+  // A field in an API-specific (custom) Operation object which carries the same
+  // meaning as google.longrunning.Operation.error.code.
+  ERROR_CODE = 3;
+
+  // A field in an API-specific (custom) Operation object which carries the same
+  // meaning as google.longrunning.Operation.error.message.
+  ERROR_MESSAGE = 4;
+}
diff --git a/google/cloud/extended_operations_pb2.py b/google/cloud/extended_operations_pb2.py
@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: google/cloud/extended_operations.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from google.protobuf import reflection as _reflection
+from google.protobuf import symbol_database as _symbol_database
+
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import descriptor_pb2 as google_dot_protobuf_dot_descriptor__pb2
+
+
+DESCRIPTOR = _descriptor.FileDescriptor(
+    name="google/cloud/extended_operations.proto",
+    package="google.cloud",
+    syntax="proto3",
+    serialized_options=b"\n\020com.google.cloudB\027ExtendedOperationsProtoP\001ZCgoogle.golang.org/genproto/googleapis/cloud/extendedops;extendedops\242\002\004GAPI",
+    create_key=_descriptor._internal_create_key,
+    serialized_pb=b"\n&google/cloud/extended_operations.proto\x12\x0cgoogle.cloud\x1a google/protobuf/descriptor.proto*b\n\x18OperationResponseMapping\x12\r\n\tUNDEFINED\x10\x00\x12\x08\n\x04NAME\x10\x01\x12\n\n\x06STATUS\x10\x02\x12\x0e\n\nERROR_CODE\x10\x03\x12\x11\n\rERROR_MESSAGE\x10\x04:_\n\x0foperation_field\x12\x1d.google.protobuf.FieldOptions\x18\xfd\x08 \x01(\x0e\x32&.google.cloud.OperationResponseMapping:?\n\x17operation_request_field\x12\x1d.google.protobuf.FieldOptions\x18\xfe\x08 \x01(\t:@\n\x18operation_response_field\x12\x1d.google.protobuf.FieldOptions\x18\xff\x08 \x01(\t::\n\x11operation_service\x12\x1e.google.protobuf.MethodOptions\x18\xe1\t \x01(\t:A\n\x18operation_polling_method\x12\x1e.google.protobuf.MethodOptions\x18\xe2\t \x01(\x08\x42y\n\x10\x63om.google.cloudB\x17\x45xtendedOperationsProtoP\x01ZCgoogle.golang.org/genproto/googleapis/cloud/extendedops;extendedops\xa2\x02\x04GAPIb\x06proto3",
+    dependencies=[google_dot_protobuf_dot_descriptor__pb2.DESCRIPTOR],
+)
+
+_OPERATIONRESPONSEMAPPING = _descriptor.EnumDescriptor(
+    name="OperationResponseMapping",
+    full_name="google.cloud.OperationResponseMapping",
+    filename=None,
+    file=DESCRIPTOR,
+    create_key=_descriptor._internal_create_key,
+    values=[
+        _descriptor.EnumValueDescriptor(
+            name="UNDEFINED",
+            index=0,
+            number=0,
+            serialized_options=None,
+            type=None,
+            create_key=_descriptor._internal_create_key,
+        ),
+        _descriptor.EnumValueDescriptor(
+            name="NAME",
+            index=1,
+            number=1,
+            serialized_options=None,
+            type=None,
+            create_key=_descriptor._internal_create_key,
+        ),
+        _descriptor.EnumValueDescriptor(
+            name="STATUS",
+            index=2,
+            number=2,
+            serialized_options=None,
+            type=None,
+            create_key=_descriptor._internal_create_key,
+        ),
+        _descriptor.EnumValueDescriptor(
+            name="ERROR_CODE",
+            index=3,
+            number=3,
+            serialized_options=None,
+            type=None,
+            create_key=_descriptor._internal_create_key,
+        ),
+        _descriptor.EnumValueDescriptor(
+            name="ERROR_MESSAGE",
+            index=4,
+            number=4,
+            serialized_options=None,
+            type=None,
+            create_key=_descriptor._internal_create_key,
+        ),
+    ],
+    containing_type=None,
+    serialized_options=None,
+    serialized_start=90,
+    serialized_end=188,
+)
+_sym_db.RegisterEnumDescriptor(_OPERATIONRESPONSEMAPPING)
+
+OperationResponseMapping = enum_type_wrapper.EnumTypeWrapper(_OPERATIONRESPONSEMAPPING)
+UNDEFINED = 0
+NAME = 1
+STATUS = 2
+ERROR_CODE = 3
+ERROR_MESSAGE = 4
+
+OPERATION_FIELD_FIELD_NUMBER = 1149
+operation_field = _descriptor.FieldDescriptor(
+    name="operation_field",
+    full_name="google.cloud.operation_field",
+    index=0,
+    number=1149,
+    type=14,
+    cpp_type=8,
+    label=1,
+    has_default_value=False,
+    default_value=0,
+    message_type=None,
+    enum_type=None,
+    containing_type=None,
+    is_extension=True,
+    extension_scope=None,
+    serialized_options=None,
+    file=DESCRIPTOR,
+    create_key=_descriptor._internal_create_key,
+)
+OPERATION_REQUEST_FIELD_FIELD_NUMBER = 1150
+operation_request_field = _descriptor.FieldDescriptor(
+    name="operation_request_field",
+    full_name="google.cloud.operation_request_field",
+    index=1,
+    number=1150,
+    type=9,
+    cpp_type=9,
+    label=1,
+    has_default_value=False,
+    default_value=b"".decode("utf-8"),
+    message_type=None,
+    enum_type=None,
+    containing_type=None,
+    is_extension=True,
+    extension_scope=None,
+    serialized_options=None,
+    file=DESCRIPTOR,
+    create_key=_descriptor._internal_create_key,
+)
+OPERATION_RESPONSE_FIELD_FIELD_NUMBER = 1151
+operation_response_field = _descriptor.FieldDescriptor(
+    name="operation_response_field",
+    full_name="google.cloud.operation_response_field",
+    index=2,
+    number=1151,
+    type=9,
+    cpp_type=9,
+    label=1,
+    has_default_value=False,
+    default_value=b"".decode("utf-8"),
+    message_type=None,
+    enum_type=None,
+    containing_type=None,
+    is_extension=True,
+    extension_scope=None,
+    serialized_options=None,
+    file=DESCRIPTOR,
+    create_key=_descriptor._internal_create_key,
+)
+OPERATION_SERVICE_FIELD_NUMBER = 1249
+operation_service = _descriptor.FieldDescriptor(
+    name="operation_service",
+    full_name="google.cloud.operation_service",
+    index=3,
+    number=1249,
+    type=9,
+    cpp_type=9,
+    label=1,
+    has_default_value=False,
+    default_value=b"".decode("utf-8"),
+    message_type=None,
+    enum_type=None,
+    containing_type=None,
+    is_extension=True,
+    extension_scope=None,
+    serialized_options=None,
+    file=DESCRIPTOR,
+    create_key=_descriptor._internal_create_key,
+)
+OPERATION_POLLING_METHOD_FIELD_NUMBER = 1250
+operation_polling_method = _descriptor.FieldDescriptor(
+    name="operation_polling_method",
+    full_name="google.cloud.operation_polling_method",
+    index=4,
+    number=1250,
+    type=8,
+    cpp_type=7,
+    label=1,
+    has_default_value=False,
+    default_value=False,
+    message_type=None,
+    enum_type=None,
+    containing_type=None,
+    is_extension=True,
+    extension_scope=None,
+    serialized_options=None,
+    file=DESCRIPTOR,
+    create_key=_descriptor._internal_create_key,
+)
+
+DESCRIPTOR.enum_types_by_name["OperationResponseMapping"] = _OPERATIONRESPONSEMAPPING
+DESCRIPTOR.extensions_by_name["operation_field"] = operation_field
+DESCRIPTOR.extensions_by_name["operation_request_field"] = operation_request_field
+DESCRIPTOR.extensions_by_name["operation_response_field"] = operation_response_field
+DESCRIPTOR.extensions_by_name["operation_service"] = operation_service
+DESCRIPTOR.extensions_by_name["operation_polling_method"] = operation_polling_method
+_sym_db.RegisterFileDescriptor(DESCRIPTOR)
+
+operation_field.enum_type = _OPERATIONRESPONSEMAPPING
+google_dot_protobuf_dot_descriptor__pb2.FieldOptions.RegisterExtension(operation_field)
+google_dot_protobuf_dot_descriptor__pb2.FieldOptions.RegisterExtension(
+    operation_request_field
+)
+google_dot_protobuf_dot_descriptor__pb2.FieldOptions.RegisterExtension(
+    operation_response_field
+)
+google_dot_protobuf_dot_descriptor__pb2.MethodOptions.RegisterExtension(
+    operation_service
+)
+google_dot_protobuf_dot_descriptor__pb2.MethodOptions.RegisterExtension(
+    operation_polling_method
+)
+
+DESCRIPTOR._options = None
+# @@protoc_insertion_point(module_scope)