feat: added helper methods for long running operations, IAM, and locations

docs: clarified that vpcConnector shortname is only returned if the connector is in the same project as the function
docs: applied general style guide updates to descriptions

PiperOrigin-RevId: 530688922
pull/803/head
Google APIs 2 years ago committed by Copybara-Service
parent c515b17e3c
commit a540c8aef8
  1. 8
      google/cloud/functions/v1/BUILD.bazel
  2. 3
      google/cloud/functions/v1/cloudfunctions_v1.yaml
  3. 205
      google/cloud/functions/v1/functions.proto
  4. 2
      google/cloud/functions/v1/operations.proto

@ -45,6 +45,8 @@ proto_library_with_info(
deps = [
":functions_proto",
"//google/cloud:common_resources_proto",
"//google/cloud/location:location_proto",
"//google/iam/v1:iam_policy_proto",
],
)
@ -79,13 +81,15 @@ java_gapic_library(
rest_numeric_enums = True,
service_yaml = "cloudfunctions_v1.yaml",
test_deps = [
":functions_java_grpc",
"//google/cloud/location:location_java_grpc",
"//google/iam/v1:iam_java_grpc",
":functions_java_grpc",
],
transport = "grpc+rest",
deps = [
":functions_java_proto",
"//google/api:api_java_proto",
"//google/cloud/location:location_java_proto",
"//google/iam/v1:iam_java_proto",
],
)
@ -147,6 +151,7 @@ go_gapic_library(
transport = "grpc+rest",
deps = [
":functions_go_proto",
"//google/cloud/location:location_go_proto",
"//google/iam/v1:iam_go_proto",
"//google/longrunning:longrunning_go_proto",
"@com_google_cloud_go_longrunning//:go_default_library",
@ -241,6 +246,7 @@ php_gapic_library(
name = "functions_php_gapic",
srcs = [":functions_proto_with_info"],
grpc_service_config = "functions_grpc_service_config.json",
migration_mode = "PRE_MIGRATION_SURFACE_ONLY",
rest_numeric_enums = True,
service_yaml = "cloudfunctions_v1.yaml",
transport = "grpc+rest",

@ -5,6 +5,9 @@ title: Cloud Functions API
apis:
- name: google.cloud.functions.v1.CloudFunctionsService
- name: google.cloud.location.Locations
- name: google.iam.v1.IAMPolicy
- name: google.longrunning.Operations
types:
- name: google.cloud.functions.v1.OperationMetadataV1

@ -1,4 +1,4 @@
// Copyright 2022 Google LLC
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@ -20,10 +20,12 @@ import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/functions/v1/operations.proto";
import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
@ -44,7 +46,8 @@ option (google.api.resource_definition) = {
// A service that application uses to manipulate triggers and functions.
service CloudFunctionsService {
option (google.api.default_host) = "cloudfunctions.googleapis.com";
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
option (google.api.oauth_scopes) =
"https://www.googleapis.com/auth/cloud-platform";
// Returns a list of functions that belong to the requested project.
rpc ListFunctions(ListFunctionsRequest) returns (ListFunctionsResponse) {
@ -62,9 +65,10 @@ service CloudFunctionsService {
}
// Creates a new function. If a function with the given name already exists in
// the specified project, the long running operation will return
// the specified project, the long running operation returns an
// `ALREADY_EXISTS` error.
rpc CreateFunction(CreateFunctionRequest) returns (google.longrunning.Operation) {
rpc CreateFunction(CreateFunctionRequest)
returns (google.longrunning.Operation) {
option (google.api.http) = {
post: "/v1/{location=projects/*/locations/*}/functions"
body: "function"
@ -77,7 +81,8 @@ service CloudFunctionsService {
}
// Updates existing function.
rpc UpdateFunction(UpdateFunctionRequest) returns (google.longrunning.Operation) {
rpc UpdateFunction(UpdateFunctionRequest)
returns (google.longrunning.Operation) {
option (google.api.http) = {
patch: "/v1/{function.name=projects/*/locations/*/functions/*}"
body: "function"
@ -90,9 +95,10 @@ service CloudFunctionsService {
}
// 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
// given function is used by some trigger, the trigger is updated to
// remove this function.
rpc DeleteFunction(DeleteFunctionRequest) returns (google.longrunning.Operation) {
rpc DeleteFunction(DeleteFunctionRequest)
returns (google.longrunning.Operation) {
option (google.api.http) = {
delete: "/v1/{name=projects/*/locations/*/functions/*}"
};
@ -132,15 +138,16 @@ service CloudFunctionsService {
// attached, the identity from the credentials would be used, but that
// identity does not have permissions to upload files to the URL.
//
// When making a HTTP PUT request, these two headers need to be specified:
// When making an HTTP PUT request, these two headers must be specified:
//
// * `content-type: application/zip`
// * `x-goog-content-length-range: 0,104857600`
//
// And this header SHOULD NOT be specified:
// And this header must NOT be specified:
//
// * `Authorization: Bearer YOUR_TOKEN`
rpc GenerateUploadUrl(GenerateUploadUrlRequest) returns (GenerateUploadUrlResponse) {
rpc GenerateUploadUrl(GenerateUploadUrlRequest)
returns (GenerateUploadUrlResponse) {
option (google.api.http) = {
post: "/v1/{parent=projects/*/locations/*}/functions:generateUploadUrl"
body: "*"
@ -148,11 +155,12 @@ service CloudFunctionsService {
}
// Returns a signed URL for downloading deployed function source code.
// The URL is only valid for a limited period and should be used within
// The URL is only valid for a limited period and must be used within
// minutes after generation.
// For more information about the signed URL usage see:
// For more information about the signed URL usage, see:
// https://cloud.google.com/storage/docs/access-control/signed-urls
rpc GenerateDownloadUrl(GenerateDownloadUrlRequest) returns (GenerateDownloadUrlResponse) {
rpc GenerateDownloadUrl(GenerateDownloadUrlRequest)
returns (GenerateDownloadUrlResponse) {
option (google.api.http) = {
post: "/v1/{name=projects/*/locations/*/functions/*}:generateDownloadUrl"
body: "*"
@ -161,7 +169,8 @@ service CloudFunctionsService {
// Sets the IAM access control policy on the specified function.
// Replaces any existing policy.
rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) {
rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest)
returns (google.iam.v1.Policy) {
option (google.api.http) = {
post: "/v1/{resource=projects/*/locations/*/functions/*}:setIamPolicy"
body: "*"
@ -171,7 +180,8 @@ service CloudFunctionsService {
// Gets the IAM access control policy for a function.
// Returns an empty policy if the function exists and does not have a policy
// set.
rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) {
rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest)
returns (google.iam.v1.Policy) {
option (google.api.http) = {
get: "/v1/{resource=projects/*/locations/*/functions/*}:getIamPolicy"
};
@ -179,9 +189,10 @@ service CloudFunctionsService {
// Tests the specified permissions against the IAM access control policy
// for a function.
// If the function does not exist, this will return an empty set of
// If the function does not exist, this returns an empty set of
// permissions, not a NOT_FOUND error.
rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) {
rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest)
returns (google.iam.v1.TestIamPermissionsResponse) {
option (google.api.http) = {
post: "/v1/{resource=projects/*/locations/*/functions/*}:testIamPermissions"
body: "*"
@ -190,7 +201,7 @@ service CloudFunctionsService {
}
// Describes a Cloud Function that contains user computation executed in
// response to an event. It encapsulate function and triggers configurations.
// response to an event. It encapsulates function and triggers configurations.
message CloudFunction {
option (google.api.resource) = {
type: "cloudfunctions.googleapis.com/CloudFunction"
@ -199,17 +210,18 @@ message CloudFunction {
// Available egress settings.
//
// This controls what traffic is diverted through the VPC Access Connector
// resource. By default PRIVATE_RANGES_ONLY will be used.
// This controls what traffic is diverted through the Serverless VPC Access
// connector resource. By default, PRIVATE_RANGES_ONLY is used.
enum VpcConnectorEgressSettings {
// Unspecified.
VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED = 0;
// Use the VPC Access Connector only for private IP space from RFC1918.
// Use the Serverless VPC Access connector only for private IP space from
// RFC1918.
PRIVATE_RANGES_ONLY = 1;
// Force the use of VPC Access Connector for all egress traffic from the
// function.
// Force the use of Serverless VPC Access connector for all egress traffic
// from the function.
ALL_TRAFFIC = 2;
}
@ -217,7 +229,7 @@ message CloudFunction {
//
// This controls what traffic can reach the function.
//
// If unspecified, ALLOW_ALL will be used.
// If unspecified, ALLOW_ALL is used.
enum IngressSettings {
// Unspecified.
INGRESS_SETTINGS_UNSPECIFIED = 0;
@ -237,15 +249,15 @@ message CloudFunction {
// Unspecified.
DOCKER_REGISTRY_UNSPECIFIED = 0;
// Docker images will be stored in multi-regional Container Registry
// Docker images are stored in multi-regional Container Registry
// repositories named `gcf`.
CONTAINER_REGISTRY = 1;
// Docker images will be stored in regional Artifact Registry repositories.
// By default, GCF will create and use repositories named `gcf-artifacts`
// in every region in which a function is deployed. But the repository to
// use can also be specified by the user using the `docker_repository`
// field.
// Docker images are stored in regional Artifact Registry repositories.
// By default, Cloud Functions creates and uses repositories named
// `gcf-artifacts` in every region in which a function is deployed. But the
// repository to use can also be specified by the user by using the
// `docker_repository` field.
ARTIFACT_REGISTRY = 2;
}
@ -267,7 +279,7 @@ message CloudFunction {
// The source repository where a function is hosted.
SourceRepository source_repository = 4;
// The Google Cloud Storage signed URL used for source uploading, generated
// The Google Cloud Storage-signed URL used for source uploading, generated
// by calling [google.cloud.functions.v1.GenerateUploadUrl].
//
// The signature is validated on write methods (Create, Update)
@ -288,12 +300,12 @@ message CloudFunction {
// Output only. Status of the function deployment.
CloudFunctionStatus status = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
// 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`.
// The name of the function (as defined in source code) that is executed.
// Defaults to the resource name suffix, if not specified. For
// backward compatibility, if function with given name is not found, the
// system tries to use the function named "function".
// For Node.js, this is the name of a function exported by the module
// as specified in `source_location`.
string entry_point = 8;
// The runtime in which to run the function. Required when deploying a new
@ -317,10 +329,11 @@ message CloudFunction {
string service_account_email = 11;
// Output only. The last update timestamp of a Cloud Function.
google.protobuf.Timestamp update_time = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
google.protobuf.Timestamp update_time = 12
[(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. The version identifier of the Cloud Function. Each deployment attempt
// results in a new version of a function being created.
// Output only. The version identifier of the Cloud Function. Each deployment
// attempt results in a new version of a function being created.
int64 version_id = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
// Labels associated with this Cloud Function.
@ -332,11 +345,11 @@ message CloudFunction {
// Build environment variables that shall be available during build time.
map<string, string> build_environment_variables = 28;
// The VPC Network that this cloud function can connect to. It can be
// either the fully-qualified URI, or the short name of the network resource.
// If the short network name is used, the network must belong to the same
// project. Otherwise, it must belong to a project within the same
// organization. The format of this field is either
// The Serverless VPC Access connector that this cloud function can connect
// to. It can be either the fully qualified URI, or the short name of the
// connector resource. If the connector name is used, the connector must
// belong to the same project as the function. Otherwise, it must belong to a
// project within the same organization. The format of this field is either
// `projects/{project}/global/networks/{network}` or `{network}`, where
// `{project}` is a project id where the network is defined, and `{network}`
// is the short name of the network.
@ -348,13 +361,13 @@ message CloudFunction {
// more information on connecting Cloud projects.
string network = 18;
// The limit on the maximum number of function instances that may coexist at a
// The limit on the maximum number of function instances that can coexist at a
// given time.
//
// In some cases, such as rapid traffic surges, Cloud Functions may, for a
// short period of time, create more instances than the specified max
// In some cases, such as rapid traffic surges, Cloud Functions can for a
// short period of time create more instances than the specified max
// instances limit. If your function cannot tolerate this temporary behavior,
// you may want to factor in a safety margin and set a lower max instances
// you might want to factor in a safety margin and set a lower max instances
// value than your function can tolerate.
//
// See the [Max
@ -362,12 +375,12 @@ message CloudFunction {
// more details.
int32 max_instances = 20;
// A lower bound for the number function instances that may coexist at a
// A lower bound for the number function instances that can coexist at a
// given time.
int32 min_instances = 32;
// The VPC Network Connector that this cloud function can connect to. It can
// be either the fully-qualified URI, or the short name of the network
// be either the fully qualified URI, or the short name of the network
// connector resource. The format of this field is
// `projects/*/locations/*/connectors/*`
//
@ -416,8 +429,8 @@ message CloudFunction {
// function resources in internal projects that are not accessible by the
// end user.
string kms_key_name = 25 [(google.api.resource_reference) = {
type: "cloudkms.googleapis.com/CryptoKey"
}];
type: "cloudkms.googleapis.com/CryptoKey"
}];
// Name of the Cloud Build Custom Worker Pool that should be used to build the
// function. The format of this field is
@ -447,8 +460,8 @@ message CloudFunction {
// Secret volumes configuration.
repeated SecretVolume secret_volumes = 30;
// Input only. An identifier for Firebase function sources. Disclaimer: This field is only
// supported for Firebase function deployments.
// Input only. An identifier for Firebase function sources. Disclaimer: This
// field is only supported for Firebase function deployments.
string source_token = 31 [(google.api.field_behavior) = INPUT_ONLY];
// User managed repository created in Artifact Registry optionally with a
@ -456,7 +469,7 @@ message CloudFunction {
// Artifact Registry. If unspecified and the deployment is eligible to use
// Artifact Registry, GCF will create and use a repository named
// 'gcf-artifacts' for every deployed region. This is the repository to which
// the function docker image will be pushed after it is built by Cloud Build.
// the function docker image is pushed after it is built by Cloud Build.
//
// It must match the pattern
// `projects/{project}/locations/{location}/repositories/{repository}`.
@ -465,12 +478,12 @@ message CloudFunction {
// Cross-location repositories are not supported.
// Repository format must be 'DOCKER'.
string docker_repository = 34 [(google.api.resource_reference) = {
type: "artifactregistry.googleapis.com/Repository"
}];
type: "artifactregistry.googleapis.com/Repository"
}];
// Docker Registry to use for this deployment.
//
// If `docker_repository` field is specified, this field will be automatically
// If `docker_repository` field is specified, this field is automatically
// set as `ARTIFACT_REGISTRY`.
// If unspecified, it currently defaults to `CONTAINER_REGISTRY`.
// This field may be overridden by the backend for eligible deployments.
@ -492,7 +505,7 @@ message SourceRepository {
// To refer to a specific fixed alias (tag):
// `https://source.developers.google.com/projects/*/repos/*/fixed-aliases/*/paths/*`
//
// You may omit `paths/*` if you want to use the main directory.
// You can omit `paths/*` if you want to use the main directory.
string url = 1;
// Output only. The URL pointing to the hosted repository where the function
@ -503,11 +516,11 @@ message SourceRepository {
// Describes HttpsTrigger, could be used to connect web hooks to function.
message HttpsTrigger {
// Available security level settings.
// Available security-level settings.
//
// This controls the methods to enforce security (HTTPS) on a URL.
//
// If unspecified, SECURE_OPTIONAL will be used.
// If unspecified, SECURE_OPTIONAL is used.
enum SecurityLevel {
// Unspecified.
SECURITY_LEVEL_UNSPECIFIED = 0;
@ -523,14 +536,14 @@ message HttpsTrigger {
SECURE_OPTIONAL = 2;
}
// Output only. The deployed url for the function.
// Output only. The deployed URL for the function.
string url = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
// The security level for the function.
SecurityLevel security_level = 2;
}
// Describes EventTrigger, used to request events be sent from another
// Describes EventTrigger, used to request that events be sent from another
// service.
message EventTrigger {
// Required. The type of event to observe. For example:
@ -546,7 +559,7 @@ message EventTrigger {
// example, the Google Cloud Storage API includes the type `object`.
// 3. action: The action that generates the event. For example, action for
// a Google Cloud Storage Object is 'change'.
// These parts are lower case.
// These parts are lowercase.
string event_type = 1;
// Required. The resource(s) from which to observe events, for example,
@ -564,7 +577,7 @@ message EventTrigger {
// that matches Google Cloud Pub/Sub topics.
//
// Additionally, some services may support short names when creating an
// `EventTrigger`. These will always be returned in the normalized "long"
// `EventTrigger`. These are always returned in the normalized "long"
// format.
//
// See each *service's* documentation for supported formats.
@ -582,20 +595,18 @@ message EventTrigger {
}
// Describes the policy in case of function's execution failure.
// If empty, then defaults to ignoring failures (i.e. not retrying them).
// If empty, then defaults to ignoring failures (i.e., not retrying them).
message FailurePolicy {
// Describes the retry policy in case of function's execution failure.
// A function execution will be retried on any failure.
// A failed execution will be retried up to 7 days with an exponential backoff
// A function execution is retried on any failure.
// A failed execution is retried up to 7 days with an exponential backoff
// (capped at 10 seconds).
// Retried execution is charged as any other execution.
message Retry {
}
message Retry {}
// Defines the action taken in case of a function execution failure.
oneof action {
// If specified, then the function will be retried in case of a failure.
// If specified, the function is retried in case of a failure.
Retry retry = 1;
}
}
@ -623,19 +634,19 @@ enum CloudFunctionStatus {
}
// Configuration for a secret environment variable. It has the information
// necessary to fetch the secret value from secret manager and expose it as an
// necessary to fetch the secret value from Secret Manager and expose it as an
// environment variable.
message SecretEnvVar {
// Name of the environment variable.
string key = 1;
// Project identifier (preferrably project number but can also be the project
// ID) of the project that contains the secret. If not set, it will be
// populated with the function's project assuming that the secret exists in
// the same project as of the function.
// ID) of the project that contains the secret. If not set, it is
// populated with the function's project, assuming that the secret exists in
// the same project as the function.
string project_id = 2;
// Name of the secret in secret manager (not the full resource name).
// Name of the secret in Secret Manager (not the full resource name).
string secret = 3;
// Version of the secret (version number or the string 'latest'). It is
@ -645,28 +656,28 @@ message SecretEnvVar {
}
// Configuration for a secret volume. It has the information necessary to fetch
// the secret value from secret manager and make it available as files mounted
// the secret value from Secret Manager and make it available as files mounted
// at the requested paths within the application container. Secret value is not
// a part of the configuration. Every filesystem read operation performs a
// lookup in secret manager to retrieve the secret value.
// a part of the configuration. Every file system read operation performs a
// lookup in Secret Manager to retrieve the secret value.
message SecretVolume {
// Configuration for a single version.
message SecretVersion {
// Version of the secret (version number or the string 'latest'). It is
// preferrable to use `latest` version with secret volumes as secret value
// preferable to use `latest` version with secret volumes as secret value
// changes are reflected immediately.
string version = 1;
// Relative path of the file under the mount path where the secret value for
// this version will be fetched and made available. For example, setting the
// mount_path as '/etc/secrets' and path as `/secret_foo` would mount the
// this version is fetched and made available. For example, setting the
// mount_path as '/etc/secrets' and path as `/secret_foo` mounts the
// secret value file at `/etc/secrets/secret_foo`.
string path = 2;
}
// The path within the container to mount the secret volume. For example,
// setting the mount_path as `/etc/secrets` would mount the secret value files
// under the `/etc/secrets` directory. This directory will also be completely
// setting the mount_path as `/etc/secrets` mounts the secret value files
// under the `/etc/secrets` directory. This directory is also completely
// shadowed and unavailable to mount any other secrets.
//
// Recommended mount paths: /etc/secrets
@ -674,24 +685,24 @@ message SecretVolume {
string mount_path = 1;
// Project identifier (preferrably project number but can also be the project
// ID) of the project that contains the secret. If not set, it will be
// populated with the function's project assuming that the secret exists in
// the same project as of the function.
// ID) of the project that contains the secret. If not set, it is
// populated with the function's project, assuming that the secret exists in
// the same project as the function.
string project_id = 2;
// Name of the secret in secret manager (not the full resource name).
// Name of the secret in Secret Manager (not the full resource name).
string secret = 3;
// List of secret versions to mount for this secret. If empty, the `latest`
// version of the secret will be made available in a file named after the
// version of the secret is made available in a file named after the
// secret under the mount point.
repeated SecretVersion versions = 4;
}
// Request for the `CreateFunction` method.
message CreateFunctionRequest {
// Required. The project and location in which the function should be created, specified
// in the format `projects/*/locations/*`
// Required. The project and location in which the function should be created,
// specified in the format `projects/*/locations/*`
string location = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
@ -732,8 +743,8 @@ message ListFunctionsRequest {
// location(s) are unreachable, the response will contain functions from all
// reachable locations along with the names of any unreachable locations.
string parent = 1 [(google.api.resource_reference) = {
type: "locations.googleapis.com/Location"
}];
type: "locations.googleapis.com/Location"
}];
// Maximum number of functions to return per call.
int32 page_size = 2;
@ -824,8 +835,8 @@ message GenerateUploadUrlRequest {
// delegate access to the Google Storage service account in the internal
// project.
string kms_key_name = 2 [(google.api.resource_reference) = {
type: "cloudkms.googleapis.com/CryptoKey"
}];
type: "cloudkms.googleapis.com/CryptoKey"
}];
}
// Response of `GenerateSourceUploadUrl` method.

@ -1,4 +1,4 @@
// Copyright 2022 Google LLC
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.

Loading…
Cancel
Save