diff --git a/google/cloud/functions/v1/BUILD.bazel b/google/cloud/functions/v1/BUILD.bazel index 7ffcb70c1..1a4f03517 100644 --- a/google/cloud/functions/v1/BUILD.bazel +++ b/google/cloud/functions/v1/BUILD.bazel @@ -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", diff --git a/google/cloud/functions/v1/cloudfunctions_v1.yaml b/google/cloud/functions/v1/cloudfunctions_v1.yaml index 77f854f63..7dc248d79 100644 --- a/google/cloud/functions/v1/cloudfunctions_v1.yaml +++ b/google/cloud/functions/v1/cloudfunctions_v1.yaml @@ -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 diff --git a/google/cloud/functions/v1/functions.proto b/google/cloud/functions/v1/functions.proto index 4b01c5b4f..340338e5b 100644 --- a/google/cloud/functions/v1/functions.proto +++ b/google/cloud/functions/v1/functions.proto @@ -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 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. diff --git a/google/cloud/functions/v1/operations.proto b/google/cloud/functions/v1/operations.proto index 880774c96..1a9ba1889 100644 --- a/google/cloud/functions/v1/operations.proto +++ b/google/cloud/functions/v1/operations.proto @@ -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.