1 // Copyright 2019 Google LLC.
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 at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // 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 and
13 // limitations under the License.
18 package google.longrunning;
20 import "google/api/annotations.proto";
21 import "google/protobuf/any.proto";
22 import "google/protobuf/duration.proto";
23 import "google/protobuf/empty.proto";
24 import "google/rpc/status.proto";
25 import "google/protobuf/descriptor.proto";
27 option cc_enable_arenas = true;
28 option csharp_namespace = "Google.LongRunning";
29 option go_package = "google.golang.org/genproto/googleapis/longrunning;longrunning";
30 option java_multiple_files = true;
31 option java_outer_classname = "OperationsProto";
32 option java_package = "com.google.longrunning";
33 option php_namespace = "Google\\LongRunning";
35 extend google.protobuf.MethodOptions {
36 // Additional information regarding long-running operations.
37 // In particular, this specifies the types that are returned from
38 // long-running operations.
40 // Required for methods that return `google.longrunning.Operation`; invalid
42 google.longrunning.OperationInfo operation_info = 1049;
45 // Manages long-running operations with an API service.
47 // When an API method normally takes long time to complete, it can be designed
48 // to return [Operation][google.longrunning.Operation] to the client, and the client can use this
49 // interface to receive the real response asynchronously by polling the
50 // operation resource, or pass the operation resource to another API (such as
51 // Google Cloud Pub/Sub API) to receive the response. Any API service that
52 // returns long-running operations should implement the `Operations` interface
53 // so developers can have a consistent client experience.
55 // Lists operations that match the specified filter in the request. If the
56 // server doesn't support this method, it returns `UNIMPLEMENTED`.
58 // NOTE: the `name` binding allows API services to override the binding
59 // to use different resource name schemes, such as `users/*/operations`. To
60 // override the binding, API services can add a binding such as
61 // `"/v1/{name=users/*}/operations"` to their service configuration.
62 // For backwards compatibility, the default name includes the operations
63 // collection id, however overriding users must ensure the name binding
64 // is the parent resource, without the operations collection id.
65 rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse) {
66 option (google.api.http) = {
67 get: "/v1/{name=operations}"
71 // Gets the latest state of a long-running operation. Clients can use this
72 // method to poll the operation result at intervals as recommended by the API
74 rpc GetOperation(GetOperationRequest) returns (Operation) {
75 option (google.api.http) = {
76 get: "/v1/{name=operations/**}"
80 // Deletes a long-running operation. This method indicates that the client is
81 // no longer interested in the operation result. It does not cancel the
82 // operation. If the server doesn't support this method, it returns
83 // `google.rpc.Code.UNIMPLEMENTED`.
84 rpc DeleteOperation(DeleteOperationRequest) returns (google.protobuf.Empty) {
85 option (google.api.http) = {
86 delete: "/v1/{name=operations/**}"
90 // Starts asynchronous cancellation on a long-running operation. The server
91 // makes a best effort to cancel the operation, but success is not
92 // guaranteed. If the server doesn't support this method, it returns
93 // `google.rpc.Code.UNIMPLEMENTED`. Clients can use
94 // [Operations.GetOperation][google.longrunning.Operations.GetOperation] or
95 // other methods to check whether the cancellation succeeded or whether the
96 // operation completed despite cancellation. On successful cancellation,
97 // the operation is not deleted; instead, it becomes an operation with
98 // an [Operation.error][google.longrunning.Operation.error] value with a [google.rpc.Status.code][google.rpc.Status.code] of 1,
99 // corresponding to `Code.CANCELLED`.
100 rpc CancelOperation(CancelOperationRequest) returns (google.protobuf.Empty) {
101 option (google.api.http) = {
102 post: "/v1/{name=operations/**}:cancel"
107 // Waits for the specified long-running operation until it is done or reaches
108 // at most a specified timeout, returning the latest state. If the operation
109 // is already done, the latest state is immediately returned. If the timeout
110 // specified is greater than the default HTTP/RPC timeout, the HTTP/RPC
111 // timeout is used. If the server does not support this method, it returns
112 // `google.rpc.Code.UNIMPLEMENTED`.
113 // Note that this method is on a best-effort basis. It may return the latest
114 // state before the specified timeout (including immediately), meaning even an
115 // immediate response is no guarantee that the operation is done.
116 rpc WaitOperation(WaitOperationRequest) returns (Operation) {
120 // This resource represents a long-running operation that is the result of a
123 // The server-assigned name, which is only unique within the same service that
124 // originally returns it. If you use the default HTTP mapping, the
125 // `name` should have the format of `operations/some/unique/name`.
128 // Service-specific metadata associated with the operation. It typically
129 // contains progress information and common metadata such as create time.
130 // Some services might not provide such metadata. Any method that returns a
131 // long-running operation should document the metadata type, if any.
132 google.protobuf.Any metadata = 2;
134 // If the value is `false`, it means the operation is still in progress.
135 // If `true`, the operation is completed, and either `error` or `response` is
139 // The operation result, which can be either an `error` or a valid `response`.
140 // If `done` == `false`, neither `error` nor `response` is set.
141 // If `done` == `true`, exactly one of `error` or `response` is set.
143 // The error result of the operation in case of failure or cancellation.
144 google.rpc.Status error = 4;
146 // The normal response of the operation in case of success. If the original
147 // method returns no data on success, such as `Delete`, the response is
148 // `google.protobuf.Empty`. If the original method is standard
149 // `Get`/`Create`/`Update`, the response should be the resource. For other
150 // methods, the response should have the type `XxxResponse`, where `Xxx`
151 // is the original method name. For example, if the original method name
152 // is `TakeSnapshot()`, the inferred response type is
153 // `TakeSnapshotResponse`.
154 google.protobuf.Any response = 5;
158 // The request message for [Operations.GetOperation][google.longrunning.Operations.GetOperation].
159 message GetOperationRequest {
160 // The name of the operation resource.
164 // The request message for [Operations.ListOperations][google.longrunning.Operations.ListOperations].
165 message ListOperationsRequest {
166 // The name of the operation's parent resource.
169 // The standard list filter.
172 // The standard list page size.
175 // The standard list page token.
176 string page_token = 3;
179 // The response message for [Operations.ListOperations][google.longrunning.Operations.ListOperations].
180 message ListOperationsResponse {
181 // A list of operations that matches the specified filter in the request.
182 repeated Operation operations = 1;
184 // The standard List next-page token.
185 string next_page_token = 2;
188 // The request message for [Operations.CancelOperation][google.longrunning.Operations.CancelOperation].
189 message CancelOperationRequest {
190 // The name of the operation resource to be cancelled.
194 // The request message for [Operations.DeleteOperation][google.longrunning.Operations.DeleteOperation].
195 message DeleteOperationRequest {
196 // The name of the operation resource to be deleted.
200 // The request message for [Operations.WaitOperation][google.longrunning.Operations.WaitOperation].
201 message WaitOperationRequest {
202 // The name of the operation resource to wait on.
205 // The maximum duration to wait before timing out. If left blank, the wait
206 // will be at most the time permitted by the underlying HTTP/RPC protocol.
207 // If RPC context deadline is also specified, the shorter one will be used.
208 google.protobuf.Duration timeout = 2;
211 // A message representing the message types used by a long-running operation.
215 // rpc LongRunningRecognize(LongRunningRecognizeRequest)
216 // returns (google.longrunning.Operation) {
217 // option (google.longrunning.operation_info) = {
218 // response_type: "LongRunningRecognizeResponse"
219 // metadata_type: "LongRunningRecognizeMetadata"
222 message OperationInfo {
223 // Required. The message name of the primary return type for this
224 // long-running operation.
225 // This type will be used to deserialize the LRO's response.
227 // If the response is in a different package from the rpc, a fully-qualified
228 // message name must be used (e.g. `google.protobuf.Struct`).
230 // Note: Altering this value constitutes a breaking change.
231 string response_type = 1;
233 // Required. The message name of the metadata type for this long-running
236 // If the response is in a different package from the rpc, a fully-qualified
237 // message name must be used (e.g. `google.protobuf.Struct`).
239 // Note: Altering this value constitutes a breaking change.
240 string metadata_type = 2;