path: root/third_party/googleapis/google/cloud/functions/v1beta2/functions.proto

// Copyright 2017 Google Inc.
//
// 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.functions.v1beta2;

import "google/api/annotations.proto";
import "google/api/auth.proto";
import "google/cloud/functions/v1beta2/operations.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option go_package = "google.golang.org/genproto/googleapis/cloud/functions/v1beta2;functions";
option java_multiple_files = true;
option java_outer_classname = "FunctionsProto";
option java_package = "com.google.cloud.functions.v1beta2";
option objc_class_prefix = "GCF";


// A service that application uses to manipulate triggers and functions.
service CloudFunctionsService {
  // Returns a list of functions that belong to the requested project.
  rpc ListFunctions(ListFunctionsRequest) returns (ListFunctionsResponse) {
    option (google.api.http) = { get: "/v1beta2/{location=projects/*/locations/*}/functions" };
  }

  // Returns a function with the given name from the requested project.
  rpc GetFunction(GetFunctionRequest) returns (CloudFunction) {
    option (google.api.http) = { get: "/v1beta2/{name=projects/*/locations/*/functions/*}" };
  }

  // Creates a new function. If a function with the given name already exists in
  // the specified project, the long running operation will return
  // `ALREADY_EXISTS` error.
  rpc CreateFunction(CreateFunctionRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = { post: "/v1beta2/{location=projects/*/locations/*}/functions" body: "function" };
  }

  // Updates existing function.
  rpc UpdateFunction(UpdateFunctionRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = { put: "/v1beta2/{name=projects/*/locations/*/functions/*}" body: "function" };
  }

  // Deletes a function with the given name from the specified project. If the
  // given function is used by some trigger, the trigger will be updated to
  // remove this function.
  rpc DeleteFunction(DeleteFunctionRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = { delete: "/v1beta2/{name=projects/*/locations/*/functions/*}" };
  }

  // Invokes synchronously deployed function. To be used for testing, very
  // limited traffic allowed.
  rpc CallFunction(CallFunctionRequest) returns (CallFunctionResponse) {
    option (google.api.http) = { post: "/v1beta2/{name=projects/*/locations/*/functions/*}:call" body: "*" };
  }
}

// Describes a Cloud Function that contains user computation executed in
// response to an event. It encapsulate function and triggers configurations.
message CloudFunction {
  // A user-defined name of the function. Function names must be unique
  // globally and match pattern `projects/*/locations/*/functions/*`
  string name = 1;

  // The location of the function source code.
  oneof source_code {
    // The URL, starting with gs://, pointing to the zip archive which contains
    // the function.
    string source_archive_url = 14;

    // The hosted repository where the function is defined.
    SourceRepository source_repository = 3;
  }

  // An event that triggers the function.
  oneof trigger {
    // An HTTPS endpoint type of source that can be triggered via URL.
    HTTPSTrigger https_trigger = 6;

    // A source that fires events in response to a condition in another service.
    EventTrigger event_trigger = 12;
  }

  // Output only. Status of the function deployment.
  CloudFunctionStatus status = 7;

  // Output only. Name of the most recent operation modifying the function. If
  // the function status is `DEPLOYING` or `DELETING`, then it points to the
  // active operation.
  string latest_operation = 8;

  // The name of the function (as defined in source code) that will be
  // executed. Defaults to the resource name suffix, if not specified. For
  // backward compatibility, if function with given name is not found, then the
  // system will try to use function named "function".
  // For Node.js this is name of a function exported by the module specified
  // in `source_location`.
  string entry_point = 9;

  // The function execution timeout. Execution is considered failed and
  // can be terminated if the function is not completed at the end of the
  // timeout period. Defaults to 60 seconds.
  google.protobuf.Duration timeout = 10;

  // The amount of memory in MB available for a function.
  // Defaults to 256MB.
  int32 available_memory_mb = 11;

  // Output only. The service account of the function.
  string service_account = 13;

  // Output only. The last update timestamp of a Cloud Function.
  google.protobuf.Timestamp update_time = 15;
}

// Describes HTTPSTrigger, could be used to connect web hooks to function.
message HTTPSTrigger {
  // Output only. The deployed url for the function.
  string url = 1;
}

// Describes EventTrigger, used to request events be sent from another
// service.
message EventTrigger {
  // `event_type` names contain the service that is sending an event and the
  // kind of event that was fired. Must be of the form
  // `providers/*/eventTypes/*` e.g. Directly handle a Message published to
  // Google Cloud Pub/Sub `providers/cloud.pubsub/eventTypes/topic.publish`
  //
  //      Handle an object changing in Google Cloud Storage
  //      `providers/cloud.storage/eventTypes/object.change`
  //
  //      Handle a write to the Firebase Realtime Database
  //      `providers/firebase.database/eventTypes/data.write`
  string event_type = 1;

  // Which instance of the source's service should send events. E.g. for Pub/Sub
  // this would be a Pub/Sub topic at `projects/*/topics/*`. For Google Cloud
  // Storage this would be a bucket at `projects/*/buckets/*`. For any source
  // that only supports one instance per-project, this should be the name of the
  // project (`projects/*`)
  string resource = 2;
}

// Describes the location of the function source in a remote repository.
message SourceRepository {
  // URL to the hosted repository where the function is defined. Only paths in
  // https://source.developers.google.com domain are supported. The path should
  // contain the name of the repository.
  string repository_url = 1;

  // The path within the repository where the function is defined. The path
  // should point to the directory where Cloud Functions files are located. Use
  // "/" if the function is defined directly in the root directory of a
  // repository.
  string source_path = 2;

  // The version of a function. Defaults to the latest version of the master
  // branch.
  oneof version {
    // The name of the branch from which the function should be fetched.
    string branch = 3;

    // The name of the tag that captures the state of the repository from
    // which the function should be fetched.
    string tag = 4;

    // The id of the revision that captures the state of the repository from
    // which the function should be fetched.
    string revision = 5;
  }

  // Output only. The id of the revision that was resolved at the moment of
  // function creation or update. For example when a user deployed from a
  // branch, it will be the revision id of the latest change on this branch at
  // that time. If user deployed from revision then this value will be always
  // equal to the revision specified by the user.
  string deployed_revision = 6;
}

// Request for the `CreateFunction` method.
message CreateFunctionRequest {
  // The project and location in which the function should be created, specified
  // in the format `projects/*/locations/*`
  string location = 1;

  // Function to be created.
  CloudFunction function = 2;
}

// Request for the `UpdateFunction` method.
message UpdateFunctionRequest {
  // The name of the function to be updated.
  string name = 1;

  // New version of the function.
  CloudFunction function = 2;
}

// Request for the `GetFunction` method.
message GetFunctionRequest {
  // The name of the function which details should be obtained.
  string name = 1;
}

// Request for the `ListFunctions` method.
message ListFunctionsRequest {
  // The project and location from which the function should be listed,
  // specified in the format `projects/*/locations/*`
  // If you want to list functions in all locations, use "-" in place of a
  // location.
  string location = 1;

  // Maximum number of functions to return per call.
  int32 page_size = 2;

  // The value returned by the last
  // `ListFunctionsResponse`; indicates that
  // this is a continuation of a prior `ListFunctions` call, and that the
  // system should return the next page of data.
  string page_token = 3;
}

// Response for the `ListFunctions` method.
message ListFunctionsResponse {
  // The functions that match the request.
  repeated CloudFunction functions = 1;

  // If not empty, indicates that there may be more functions that match
  // the request; this value should be passed in a new
  // [google.cloud.functions.v1beta2.ListFunctionsRequest][]
  // to get more functions.
  string next_page_token = 2;
}

// Request for the `DeleteFunction` method.
message DeleteFunctionRequest {
  // The name of the function which should be deleted.
  string name = 1;
}

// Request for the `CallFunction` method.
message CallFunctionRequest {
  // The name of the function to be called.
  string name = 1;

  // Input to be passed to the function.
  string data = 2;
}

// Response of `CallFunction` method.
message CallFunctionResponse {
  // Execution id of function invocation.
  string execution_id = 1;

  // Result populated for successful execution of synchronous function. Will
  // not be populated if function does not return a result through context.
  string result = 2;

  // Either system or user-function generated error. Set if execution
  // was not successful.
  string error = 3;
}

// Describes the current stage of a deployment.
enum CloudFunctionStatus {
  // Status not specified.
  STATUS_UNSPECIFIED = 0;

  // Successfully deployed.
  READY = 1;

  // Not deployed correctly - behavior is undefined. The item should be updated
  // or deleted to move it out of this state.
  FAILED = 2;

  // Creation or update in progress.
  DEPLOYING = 3;

  // Deletion in progress.
  DELETING = 4;
}