// 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.
syntax = "proto3";
package google.cloud.workflows.executions.v1;
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/timestamp.proto";
option go_package = "google.golang.org/genproto/googleapis/cloud/workflows/executions/v1;executions";
option java_multiple_files = true;
option java_outer_classname = "ExecutionsProto";
option java_package = "com.google.cloud.workflows.executions.v1";
option (google.api.resource_definition) = {
type: "workflows.googleapis.com/Workflow"
pattern: "projects/{project}/locations/{location}/workflows/{workflow}"
};
// Executions is used to start and manage running instances of
// [Workflows][google.cloud.workflows.v1.Workflow] called executions.
service Executions {
option (google.api.default_host) = "workflowexecutions.googleapis.com";
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
// Returns a list of executions which belong to the workflow with
// the given name. The method returns executions of all workflow
// revisions. Returned executions are ordered by their start time (newest
// first).
rpc ListExecutions(ListExecutionsRequest) returns (ListExecutionsResponse) {
option (google.api.http) = {
get: "/v1/{parent=projects/*/locations/*/workflows/*}/executions"
};
option (google.api.method_signature) = "parent";
}
// Creates a new execution using the latest revision of the given workflow.
rpc CreateExecution(CreateExecutionRequest) returns (Execution) {
option (google.api.http) = {
post: "/v1/{parent=projects/*/locations/*/workflows/*}/executions"
body: "execution"
};
option (google.api.method_signature) = "parent,execution";
}
// Returns an execution of the given name.
rpc GetExecution(GetExecutionRequest) returns (Execution) {
option (google.api.http) = {
get: "/v1/{name=projects/*/locations/*/workflows/*/executions/*}"
};
option (google.api.method_signature) = "name";
}
// Cancels an execution of the given name.
rpc CancelExecution(CancelExecutionRequest) returns (Execution) {
option (google.api.http) = {
post: "/v1/{name=projects/*/locations/*/workflows/*/executions/*}:cancel"
body: "*"
};
option (google.api.method_signature) = "name";
}
}
// A running instance of a
// [Workflow](/workflows/docs/reference/rest/v1/projects.locations.workflows).
message Execution {
option (google.api.resource) = {
type: "workflowexecutions.googleapis.com/Execution"
pattern: "projects/{project}/locations/{location}/workflows/{workflow}/executions/{execution}"
};
// A single stack element (frame) where an error occurred.
message StackTraceElement {
// Position contains source position information about the stack trace
// element such as line number, column number and length of the code block
// in bytes.
message Position {
// The source code line number the current instruction was generated from.
int64 line = 1;
// The source code column position (of the line) the current instruction
// was generated from.
int64 column = 2;
// The number of bytes of source code making up this stack trace element.
int64 length = 3;
}
// The step the error occurred at.
string step = 1;
// The routine where the error occurred.
string routine = 2;
// The source position information of the stack trace element.
Position position = 3;
}
// A collection of stack elements (frames) where an error occurred.
message StackTrace {
// An array of stack elements.
repeated StackTraceElement elements = 1;
}
// Error describes why the execution was abnormally terminated.
message Error {
// Error message and data returned represented as a JSON string.
string payload = 1;
// Human-readable stack trace string.
string context = 2;
// Stack trace with detailed information of where error was generated.
StackTrace stack_trace = 3;
}
// Describes the current state of the execution. More states might be added
// in the future.
enum State {
// Invalid state.
STATE_UNSPECIFIED = 0;
// The execution is in progress.
ACTIVE = 1;
// The execution finished successfully.
SUCCEEDED = 2;
// The execution failed with an error.
FAILED = 3;
// The execution was stopped intentionally.
CANCELLED = 4;
}
// Describes the level of platform logging to apply to calls and call
// responses during workflow executions.
enum CallLogLevel {
// No call logging specified.
CALL_LOG_LEVEL_UNSPECIFIED = 0;
// Log all call steps within workflows, all call returns, and all exceptions
// raised.
LOG_ALL_CALLS = 1;
// Log only exceptions that are raised from call steps within workflows.
LOG_ERRORS_ONLY = 2;
}
// Output only. The resource name of the execution.
// Format:
// projects/{project}/locations/{location}/workflows/{workflow}/executions/{execution}
string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. Marks the beginning of execution.
google.protobuf.Timestamp start_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. Marks the end of execution, successful or not.
google.protobuf.Timestamp end_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. Current state of the execution.
State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
// Input parameters of the execution represented as a JSON string.
// The size limit is 32KB.
//
// *Note*: If you are using the REST API directly to run your workflow, you
// must escape any JSON string value of `argument`. Example:
// `'{"argument":"{\"firstName\":\"FIRST\",\"lastName\":\"LAST\"}"}'`
string argument = 5;
// Output only. Output of the execution represented as a JSON string. The
// value can only be present if the execution's state is `SUCCEEDED`.
string result = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. The error which caused the execution to finish prematurely.
// The value is only present if the execution's state is `FAILED`
// or `CANCELLED`.
Error error = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. Revision of the workflow this execution is using.
string workflow_revision_id = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
// The call logging level associated to this execution.
CallLogLevel call_log_level = 9;
}
// Request for the
// [ListExecutions][]
// method.
message ListExecutionsRequest {
// Required. Name of the workflow for which the executions should be listed.
// Format: projects/{project}/locations/{location}/workflows/{workflow}
string parent = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "workflows.googleapis.com/Workflow"
}
];
// Maximum number of executions to return per call.
// Max supported value depends on the selected Execution view: it's 10000 for
// BASIC and 100 for FULL. The default value used if the field is not
// specified is 100, regardless of the selected view. Values greater than
// the max value will be coerced down to it.
int32 page_size = 2;
// A page token, received from a previous `ListExecutions` call.
// Provide this to retrieve the subsequent page.
//
// When paginating, all other parameters provided to `ListExecutions` must
// match the call that provided the page token.
string page_token = 3;
// Optional. A view defining which fields should be filled in the returned executions.
// The API will default to the BASIC view.
ExecutionView view = 4 [(google.api.field_behavior) = OPTIONAL];
}
// Response for the
// [ListExecutions][google.cloud.workflows.executions.v1.Executions.ListExecutions]
// method.
message ListExecutionsResponse {
// The executions which match the request.
repeated Execution executions = 1;
// A token, which can be sent as `page_token` to retrieve the next page.
// If this field is omitted, there are no subsequent pages.
string next_page_token = 2;
}
// Request for the
// [CreateExecution][google.cloud.workflows.executions.v1.Executions.CreateExecution]
// method.
message CreateExecutionRequest {
// Required. Name of the workflow for which an execution should be created.
// Format: projects/{project}/locations/{location}/workflows/{workflow}
// The latest revision of the workflow will be used.
string parent = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "workflows.googleapis.com/Workflow"
}
];
// Required. Execution to be created.
Execution execution = 2 [(google.api.field_behavior) = REQUIRED];
}
// Request for the
// [GetExecution][google.cloud.workflows.executions.v1.Executions.GetExecution]
// method.
message GetExecutionRequest {
// Required. Name of the execution to be retrieved.
// Format:
// projects/{project}/locations/{location}/workflows/{workflow}/executions/{execution}
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "workflowexecutions.googleapis.com/Execution"
}
];
// Optional. A view defining which fields should be filled in the returned execution.
// The API will default to the FULL view.
ExecutionView view = 2 [(google.api.field_behavior) = OPTIONAL];
}
// Request for the
// [CancelExecution][google.cloud.workflows.executions.v1.Executions.CancelExecution]
// method.
message CancelExecutionRequest {
// Required. Name of the execution to be cancelled.
// Format:
// projects/{project}/locations/{location}/workflows/{workflow}/executions/{execution}
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "workflowexecutions.googleapis.com/Execution"
}
];
}
// Defines possible views for execution resource.
enum ExecutionView {
// The default / unset value.
EXECUTION_VIEW_UNSPECIFIED = 0;
// Includes only basic metadata about the execution.
// Following fields are returned: name, start_time, end_time, state
// and workflow_revision_id.
BASIC = 1;
// Includes all data.
FULL = 2;
}