diff --git a/google/longrunning/artman_longrunning.yaml b/google/longrunning/artman_longrunning.yaml index ddda18b0..1b93f451 100644 --- a/google/longrunning/artman_longrunning.yaml +++ b/google/longrunning/artman_longrunning.yaml @@ -8,6 +8,7 @@ common: - . proto_deps: - name: google-common-protos + proto_package: google.longrunning artifacts: - name: java_gapic type: GAPIC_ONLY diff --git a/google/longrunning/longrunning.yaml b/google/longrunning/longrunning.yaml index ff8fccf0..ffb6bf3b 100644 --- a/google/longrunning/longrunning.yaml +++ b/google/longrunning/longrunning.yaml @@ -4,10 +4,10 @@ name: longrunning.googleapis.com title: Long Running Operations API apis: - - name: google.longrunning.Operations +- name: google.longrunning.Operations types: - - name: google.longrunning.OperationInfo +- name: google.longrunning.OperationInfo documentation: overview: |- @@ -20,11 +20,11 @@ documentation: ## What are Long Running Operations? A Long Running Operation (LRO) is a way of representing an action that may - take a significant amount of time to complete. For example, an API call that - starts exporting a large amount of data could take quite a while to complete - and is therefore best represented as an LRO. A common rule of thumb is to - think of LROs as "API promises" that represent the result of some on-going - action. + take a significant amount of time to complete. For example, an API call + that starts exporting a large amount of data could take quite a while to + complete and is therefore best represented as an LRO. A common rule of + thumb is to think of LROs as "API promises" that represent the result of + some on-going action. ## Using LROs @@ -32,31 +32,33 @@ documentation: should return a long running operation instead of a direct response. This means that even if there are situations where the response could be immediate, the API should still return an LRO -- it just may be already - marked as completed. For example, if a data export operation is called on an - empty resource, the operation itself may be possible to execute immediately, - and would result in an already completed LRO. + marked as completed. + For example, if a data export operation is called on an empty resource, + the operation itself may be possible to execute immediately, and would + result in an already completed LRO. - Additionally, the operation should be managed using the LRO interface, which - allows clients to poll the operation for status updates or cancel it + Additionally, the operation should be managed using the LRO interface, + which allows clients to poll the operation for status updates or cancel it entirely. Finally, an LRO represents an action and as a result, the operation is not created directly. Instead, the operation comes into existence as a side-effect of the action it represents. For example, an RPC called - `ExportData` would create and return an LRO. This means that there should - never be an RPC called `CreateOperation`. + `ExportData` would + create and return an LRO. This means that there should never be an RPC + called `CreateOperation`. This also means that any permissions on the operation would be based on action it represents. Any immediate side effects of starting the operation - must be visible in the service as soon as the LRO is returned. For example, - if an LRO is returned when creating a resource, that resource should be - visible in the API immediately, but be in a non-final state until the LRO is - completed. + must be visible in the service as soon as the LRO is returned. For + example, if an LRO is returned when creating a resource, that resource + should be visible in the API immediately, but be in a non-final state + until the LRO is completed. ## LROs versus Jobs - A job is a common design pattern often used in data processing that tends to - be used to represent some contained piece of work that would be stored, + A job is a common design pattern often used in data processing that tends + to be used to represent some contained piece of work that would be stored, re-run, and modified over time. Jobs also typically interact with multiple resources and are created, deleted, and updated directly as independent resources. @@ -67,6 +69,6 @@ documentation: In general, if an action may take a while but it represents a single piece of work, it's best to represent the response as an LRO. If the action is - something more complex (for example, it involves lots of resources and can't - be created as a byproduct of a single action), it may make more sense to - represent it as a job. + something more complex (for example, it involves lots of resources and + can't be created as a byproduct of a single action), it may make more + sense to represent it as a job. diff --git a/google/longrunning/operations.proto b/google/longrunning/operations.proto index 90778e03..a9e0a443 100644 --- a/google/longrunning/operations.proto +++ b/google/longrunning/operations.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// Copyright 2016-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. @@ -11,13 +11,13 @@ // 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. -// syntax = "proto3"; package google.longrunning; import "google/api/annotations.proto"; +import "google/api/client.proto"; import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/empty.proto"; @@ -66,6 +66,7 @@ service Operations { option (google.api.http) = { get: "/v1/{name=operations}" }; + option (google.api.method_signature) = "name,filter"; } // Gets the latest state of a long-running operation. Clients can use this @@ -75,6 +76,7 @@ service Operations { option (google.api.http) = { get: "/v1/{name=operations/**}" }; + option (google.api.method_signature) = "name"; } // Deletes a long-running operation. This method indicates that the client is @@ -85,6 +87,7 @@ service Operations { option (google.api.http) = { delete: "/v1/{name=operations/**}" }; + option (google.api.method_signature) = "name"; } // Starts asynchronous cancellation on a long-running operation. The server @@ -102,6 +105,7 @@ service Operations { post: "/v1/{name=operations/**}:cancel" body: "*" }; + option (google.api.method_signature) = "name"; } // Waits for the specified long-running operation until it is done or reaches @@ -122,7 +126,7 @@ service Operations { message Operation { // The server-assigned name, which is only unique within the same service that // originally returns it. If you use the default HTTP mapping, the - // `name` should have the format of `operations/some/unique/name`. + // `name` should be a resource name ending with `operations/{unique_id}`. string name = 1; // Service-specific metadata associated with the operation. It typically