|
| 1 | +// Copyright (c) 2015, Google Inc. |
| 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 at |
| 6 | +// |
| 7 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +// |
| 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. |
| 14 | + |
| 15 | +syntax = "proto3"; |
| 16 | + |
| 17 | +package google.longrunning; |
| 18 | + |
| 19 | +import "google/api/annotations.proto"; |
| 20 | +import "google/protobuf/any.proto"; |
| 21 | +import "google/protobuf/empty.proto"; |
| 22 | +import "google/rpc/status.proto"; |
| 23 | + |
| 24 | +option java_multiple_files = true; |
| 25 | +option java_outer_classname = "OperationsProto"; |
| 26 | +option java_package = "com.google.longrunning"; |
| 27 | + |
| 28 | + |
| 29 | +// Manages long-running operations with an API service. |
| 30 | +// |
| 31 | +// When an API method normally takes long time to complete, it can be designed |
| 32 | +// to return [Operation][google.longrunning.Operation] to the client, and the client can use this |
| 33 | +// interface to receive the real response asynchronously by polling the |
| 34 | +// operation resource, or using `google.watcher.v1.Watcher` interface to watch |
| 35 | +// the response, or pass the operation resource to another API (such as Google |
| 36 | +// Cloud Pub/Sub API) to receive the response. Any API service that returns |
| 37 | +// long-running operations should implement the `Operations` interface so |
| 38 | +// developers can have a consistent client experience. |
| 39 | +service Operations { |
| 40 | + // Gets the latest state of a long-running operation. Clients may use this |
| 41 | + // method to poll the operation result at intervals as recommended by the API |
| 42 | + // service. |
| 43 | + rpc GetOperation(GetOperationRequest) returns (Operation) { |
| 44 | + option (google.api.http) = { get: "/v1/{name=operations/**}" }; |
| 45 | + } |
| 46 | + |
| 47 | + // Lists operations that match the specified filter in the request. If the |
| 48 | + // server doesn't support this method, it returns |
| 49 | + // `google.rpc.Code.UNIMPLEMENTED`. |
| 50 | + rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse) { |
| 51 | + option (google.api.http) = { get: "/v1/{name=operations}" }; |
| 52 | + } |
| 53 | + |
| 54 | + // Starts asynchronous cancellation on a long-running operation. The server |
| 55 | + // makes a best effort to cancel the operation, but success is not |
| 56 | + // guaranteed. If the server doesn't support this method, it returns |
| 57 | + // `google.rpc.Code.UNIMPLEMENTED`. Clients may use |
| 58 | + // [Operations.GetOperation] or other methods to check whether the |
| 59 | + // cancellation succeeded or the operation completed despite cancellation. |
| 60 | + rpc CancelOperation(CancelOperationRequest) returns (google.protobuf.Empty) { |
| 61 | + option (google.api.http) = { post: "/v1/{name=operations/**}:cancel" body: "*" }; |
| 62 | + } |
| 63 | + |
| 64 | + // Deletes a long-running operation. It indicates the client is no longer |
| 65 | + // interested in the operation result. It does not cancel the operation. |
| 66 | + rpc DeleteOperation(DeleteOperationRequest) returns (google.protobuf.Empty) { |
| 67 | + option (google.api.http) = { delete: "/v1/{name=operations/**}" }; |
| 68 | + } |
| 69 | +} |
| 70 | + |
| 71 | +// This resource represents a long-running operation that is the result of a |
| 72 | +// network API call. |
| 73 | +message Operation { |
| 74 | + // The name of the operation resource, which is only unique within the same |
| 75 | + // service that originally returns it. |
| 76 | + string name = 1; |
| 77 | + |
| 78 | + // Some service-specific metadata associated with the operation. It typically |
| 79 | + // contains progress information and common metadata such as create time. |
| 80 | + // Some services may not provide such metadata. Any method that returns a |
| 81 | + // long-running operation should document the metadata type, if any. |
| 82 | + google.protobuf.Any metadata = 2; |
| 83 | + |
| 84 | + // If the value is false, it means the operation is still in progress. |
| 85 | + // If true, the operation is completed and the `result` is available. |
| 86 | + bool done = 3; |
| 87 | + |
| 88 | + oneof result { |
| 89 | + // The error result of the operation in case of failure. |
| 90 | + google.rpc.Status error = 4; |
| 91 | + |
| 92 | + // The normal response of the operation in case of success. If the original |
| 93 | + // method returns no data on success, such as `Delete`, the response will be |
| 94 | + // `google.protobuf.Empty`. If the original method is standard |
| 95 | + // `Get`/`Create`/`Update`, the response should be the resource. For other |
| 96 | + // methods, the response should have the type `XxxResponse`, where `Xxx` |
| 97 | + // is the original method name. For example, if the original method name |
| 98 | + // is `TakeSnapshot()`, the inferred response type will be |
| 99 | + // `TakeSnapshotResponse`. |
| 100 | + google.protobuf.Any response = 5; |
| 101 | + } |
| 102 | +} |
| 103 | + |
| 104 | +// The request message for [Operations.GetOperation][google.longrunning.Operations.GetOperation]. |
| 105 | +message GetOperationRequest { |
| 106 | + // The name of the operation resource. |
| 107 | + string name = 1; |
| 108 | +} |
| 109 | + |
| 110 | +// The request message for [Operations.ListOperations][google.longrunning.Operations.ListOperations]. |
| 111 | +message ListOperationsRequest { |
| 112 | + // The name of the operation collection. |
| 113 | + string name = 4; |
| 114 | + |
| 115 | + // The standard List filter. |
| 116 | + string filter = 1; |
| 117 | + |
| 118 | + // The standard List page size. |
| 119 | + int32 page_size = 2; |
| 120 | + |
| 121 | + // The standard List page token. |
| 122 | + string page_token = 3; |
| 123 | +} |
| 124 | + |
| 125 | +// The response message for [Operations.ListOperations][google.longrunning.Operations.ListOperations]. |
| 126 | +message ListOperationsResponse { |
| 127 | + // A list of operations that match the specified filter in the request. |
| 128 | + repeated Operation operations = 1; |
| 129 | + |
| 130 | + // The standard List next-page token. |
| 131 | + string next_page_token = 2; |
| 132 | +} |
| 133 | + |
| 134 | +// The request message for [Operations.CancelOperation][google.longrunning.Operations.CancelOperation]. |
| 135 | +message CancelOperationRequest { |
| 136 | + // The name of the operation resource to be cancelled. |
| 137 | + string name = 1; |
| 138 | +} |
| 139 | + |
| 140 | +// The request message for [Operations.DeleteOperation][google.longrunning.Operations.DeleteOperation]. |
| 141 | +message DeleteOperationRequest { |
| 142 | + // The name of the operation resource to be deleted. |
| 143 | + string name = 1; |
| 144 | +} |
0 commit comments