diff options
Diffstat (limited to 'google/cloud')
418 files changed, 89628 insertions, 0 deletions
diff --git a/google/cloud/asset/BUILD.bazel b/google/cloud/asset/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/asset/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/asset/artman_cloudasset_v1.yaml b/google/cloud/asset/artman_cloudasset_v1.yaml new file mode 100644 index 000000000..53429a5d8 --- /dev/null +++ b/google/cloud/asset/artman_cloudasset_v1.yaml @@ -0,0 +1,35 @@ +common: + # Keep the api_name asset, otherwise Java code gen will be broken. + api_name: asset + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: asset_v1.yaml + gapic_yaml: v1/cloudasset_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/asset/artman_cloudasset_v1beta1.yaml b/google/cloud/asset/artman_cloudasset_v1beta1.yaml new file mode 100644 index 000000000..c3278c500 --- /dev/null +++ b/google/cloud/asset/artman_cloudasset_v1beta1.yaml @@ -0,0 +1,35 @@ +common: + # Keep the api_name asset, otherwise Java code gen will be broken. + api_name: asset + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: asset_v1beta1.yaml + gapic_yaml: v1beta1/cloudasset_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/asset/asset_v1.yaml b/google/cloud/asset/asset_v1.yaml new file mode 100644 index 000000000..71c62ee8d --- /dev/null +++ b/google/cloud/asset/asset_v1.yaml @@ -0,0 +1,50 @@ +type: google.api.Service +config_version: 3 +name: cloudasset.googleapis.com +title: Cloud Asset API + +apis: +- name: google.cloud.asset.v1.AssetService + +documentation: + summary: The cloud asset API manages the history and inventory of cloud resources. + overview: |- + # Cloud Asset API + + The Cloud Asset API keeps a history of Google Cloud Platform (GCP) asset + metadata, and allows GCP users to download a dump of all asset metadata for + the resource types listed below within an organization or a project at a + given timestamp. + + Read more documents here: + https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview + +backend: + rules: + - selector: google.longrunning.Operations.GetOperation + deadline: 60.0 + - selector: google.cloud.asset.v1.AssetService.ExportAssets + deadline: 600.0 + - selector: google.cloud.asset.v1.AssetService.BatchGetAssetsHistory + deadline: 600.0 + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1beta1/{name=projects/*/operations/*/**}' + additional_bindings: + - get: '/v1beta1/{name=folders/*/operations/*/**}' + + - get: '/v1beta1/{name=organizations/*/operations/*/**}' + + - get: '/v1p1alpha1/{name=*/*/operations/*/**}' + + - get: '/v1/{name=*/*/operations/*/**}' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/asset/asset_v1beta1.yaml b/google/cloud/asset/asset_v1beta1.yaml new file mode 100644 index 000000000..d1edc78b9 --- /dev/null +++ b/google/cloud/asset/asset_v1beta1.yaml @@ -0,0 +1,56 @@ +type: google.api.Service +config_version: 3 +name: cloudasset.googleapis.com +title: Cloud Asset API + +apis: +- name: google.cloud.asset.v1beta1.AssetService + +documentation: + summary: The cloud asset API manages the history and inventory of cloud resources. + overview: |- + # Cloud Asset API + + The Cloud Asset API keeps a history of Google Cloud Platform (GCP) asset + metadata, and allows GCP users to download a dump of all asset metadata for + the resource types listed below within an organization or a project at a + given timestamp. + + Read more documents here: + https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview + +backend: + rules: + - selector: google.longrunning.Operations.GetOperation + deadline: 60.0 + - selector: google.cloud.asset.v1beta1.AssetService.ExportAssets + deadline: 600.0 + - selector: google.cloud.asset.v1beta1.AssetService.BatchGetAssetsHistory + deadline: 600.0 + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1alpha1/{name=projects/*/operations/*/*}' + additional_bindings: + - get: '/v1alpha1/{name=organizations/*/operations/*/*}' + + - get: '/v1alpha2/{name=projects/*/operations/*/*}' + + - get: '/v1alpha2/{name=organizations/*/operations/*/*}' + + - get: '/v1beta1/{name=projects/*/operations/*/*}' + + - get: '/v1beta1/{name=folders/*/operations/*/*}' + + - get: '/v1beta1/{name=organizations/*/operations/*/*}' + + - get: '/v1/{name=*/*/operations/*/*}' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/asset/v1/asset_service.proto b/google/cloud/asset/v1/asset_service.proto new file mode 100644 index 000000000..0dfc2898b --- /dev/null +++ b/google/cloud/asset/v1/asset_service.proto @@ -0,0 +1,171 @@ +// Copyright 2019 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.asset.v1; + +import "google/api/annotations.proto"; +import "google/cloud/asset/v1/assets.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Asset.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/asset/v1;asset"; +option java_multiple_files = true; +option java_outer_classname = "AssetServiceProto"; +option java_package = "com.google.cloud.asset.v1"; +option php_namespace = "Google\\Cloud\\Asset\\V1"; + + +// Asset service definition. +service AssetService { + // Exports assets with time and resource types to a given Cloud Storage + // location. The output format is newline-delimited JSON. + // This API implements the [google.longrunning.Operation][google.longrunning.Operation] API allowing you + // to keep track of the export. + rpc ExportAssets(ExportAssetsRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=*/*}:exportAssets" + body: "*" + }; + } + + // Batch gets the update history of assets that overlap a time window. + // For RESOURCE content, this API outputs history with asset in both + // non-delete or deleted status. + // For IAM_POLICY content, this API outputs history when the asset and its + // attached IAM POLICY both exist. This can create gaps in the output history. + // If a specified asset does not exist, this API returns an INVALID_ARGUMENT + // error. + rpc BatchGetAssetsHistory(BatchGetAssetsHistoryRequest) returns (BatchGetAssetsHistoryResponse) { + option (google.api.http) = { + get: "/v1/{parent=*/*}:batchGetAssetsHistory" + }; + } +} + +// Export asset request. +message ExportAssetsRequest { + // Required. The relative name of the root asset. This can only be an + // organization number (such as "organizations/123"), a project ID (such as + // "projects/my-project-id"), or a project number (such as "projects/12345"), + // or a folder number (such as "folders/123"). + string parent = 1; + + // Timestamp to take an asset snapshot. This can only be set to a timestamp + // between 2018-10-02 UTC (inclusive) and the current time. If not specified, + // the current time will be used. Due to delays in resource data collection + // and indexing, there is a volatile window during which running the same + // query may get different results. + google.protobuf.Timestamp read_time = 2; + + // A list of asset types of which to take a snapshot for. For example: + // "compute.googleapis.com/Disk". If specified, only matching assets will be returned. + // See [Introduction to Cloud Asset + // Inventory](https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview) + // for all supported asset types. + repeated string asset_types = 3; + + // Asset content type. If not specified, no content but the asset name will be + // returned. + ContentType content_type = 4; + + // Required. Output configuration indicating where the results will be output + // to. All results will be in newline delimited JSON format. + OutputConfig output_config = 5; +} + +// The export asset response. This message is returned by the +// [google.longrunning.Operations.GetOperation][google.longrunning.Operations.GetOperation] method in the returned +// [google.longrunning.Operation.response][google.longrunning.Operation.response] field. +message ExportAssetsResponse { + // Time the snapshot was taken. + google.protobuf.Timestamp read_time = 1; + + // Output configuration indicating where the results were output to. + // All results are in JSON format. + OutputConfig output_config = 2; +} + +// Batch get assets history request. +message BatchGetAssetsHistoryRequest { + // Required. The relative name of the root asset. It can only be an + // organization number (such as "organizations/123"), a project ID (such as + // "projects/my-project-id")", or a project number (such as "projects/12345"). + string parent = 1; + + // A list of the full names of the assets. For example: + // `//compute.googleapis.com/projects/my_project_123/zones/zone1/instances/instance1`. + // See [Resource + // Names](https://cloud.google.com/apis/design/resource_names#full_resource_name) + // and [Resource Name Format](https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/resource-name-format) + // for more info. + // + // The request becomes a no-op if the asset name list is empty, and the max + // size of the asset name list is 100 in one request. + repeated string asset_names = 2; + + // Required. The content type. + ContentType content_type = 3; + + // Optional. The time window for the asset history. Both start_time and + // end_time are optional and if set, it must be after 2018-10-02 UTC. If + // end_time is not set, it is default to current timestamp. If start_time is + // not set, the snapshot of the assets at end_time will be returned. The + // returned results contain all temporal assets whose time window overlap with + // read_time_window. + TimeWindow read_time_window = 4; +} + +// Batch get assets history response. +message BatchGetAssetsHistoryResponse { + // A list of assets with valid time windows. + repeated TemporalAsset assets = 1; +} + +// Output configuration for export assets destination. +message OutputConfig { + // Asset export destination. + oneof destination { + // Destination on Cloud Storage. + GcsDestination gcs_destination = 1; + } +} + +// A Cloud Storage location. +message GcsDestination { + // Required. + oneof object_uri { + // The uri of the Cloud Storage object. It's the same uri that is used by + // gsutil. For example: "gs://bucket_name/object_name". See [Viewing and + // Editing Object + // Metadata](https://cloud.google.com/storage/docs/viewing-editing-metadata) + // for more information. + string uri = 1; + } +} + +// Asset content type. +enum ContentType { + // Unspecified content type. + CONTENT_TYPE_UNSPECIFIED = 0; + + // Resource metadata. + RESOURCE = 1; + + // The actual IAM policy set on a resource. + IAM_POLICY = 2; +} diff --git a/google/cloud/asset/v1/assets.proto b/google/cloud/asset/v1/assets.proto new file mode 100644 index 000000000..f6a8108c0 --- /dev/null +++ b/google/cloud/asset/v1/assets.proto @@ -0,0 +1,118 @@ +// Copyright 2019 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.asset.v1; + +import "google/api/annotations.proto"; +import "google/iam/v1/policy.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Asset.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/asset/v1;asset"; +option java_multiple_files = true; +option java_outer_classname = "AssetProto"; +option java_package = "com.google.cloud.asset.v1"; +option php_namespace = "Google\\Cloud\\Asset\\V1"; + + +// Temporal asset. In addition to the asset, the temporal asset includes the +// status of the asset and valid from and to time of it. +message TemporalAsset { + // The time window when the asset data and state was observed. + TimeWindow window = 1; + + // If the asset is deleted or not. + bool deleted = 2; + + // Asset. + Asset asset = 3; +} + +// A time window of (start_time, end_time]. +message TimeWindow { + // Start time of the time window (exclusive). + google.protobuf.Timestamp start_time = 1; + + // End time of the time window (inclusive). + // Current timestamp if not specified. + google.protobuf.Timestamp end_time = 2; +} + +// Cloud asset. This includes all Google Cloud Platform resources, +// Cloud IAM policies, and other non-GCP assets. +message Asset { + // The full name of the asset. For example: + // `//compute.googleapis.com/projects/my_project_123/zones/zone1/instances/instance1`. + // See [Resource + // Names](https://cloud.google.com/apis/design/resource_names#full_resource_name) + // for more information. + string name = 1; + + // Type of the asset. Example: "compute.googleapis.com/Disk". + string asset_type = 2; + + // Representation of the resource. + Resource resource = 3; + + // Representation of the actual Cloud IAM policy set on a cloud resource. For + // each resource, there must be at most one Cloud IAM policy set on it. + google.iam.v1.Policy iam_policy = 4; +} + +// Representation of a cloud resource. +message Resource { + // The API version. Example: "v1". + string version = 1; + + // The URL of the discovery document containing the resource's JSON schema. + // For example: + // `"https://www.googleapis.com/discovery/v1/apis/compute/v1/rest"`. + // It will be left unspecified for resources without a discovery-based API, + // such as Cloud Bigtable. + string discovery_document_uri = 2; + + // The JSON schema name listed in the discovery document. + // Example: "Project". It will be left unspecified for resources (such as + // Cloud Bigtable) without a discovery-based API. + string discovery_name = 3; + + // The REST URL for accessing the resource. An HTTP GET operation using this + // URL returns the resource itself. + // Example: + // `https://cloudresourcemanager.googleapis.com/v1/projects/my-project-123`. + // It will be left unspecified for resources without a REST API. + string resource_url = 4; + + // The full name of the immediate parent of this resource. See + // [Resource + // Names](https://cloud.google.com/apis/design/resource_names#full_resource_name) + // for more information. + // + // For GCP assets, it is the parent resource defined in the [Cloud IAM policy + // hierarchy](https://cloud.google.com/iam/docs/overview#policy_hierarchy). + // For example: + // `"//cloudresourcemanager.googleapis.com/projects/my_project_123"`. + // + // For third-party assets, it is up to the users to define. + string parent = 5; + + // The content of the resource, in which some sensitive fields are scrubbed + // away and may not be present. + google.protobuf.Struct data = 6; +} diff --git a/google/cloud/asset/v1/cloudasset_gapic.yaml b/google/cloud/asset/v1/cloudasset_gapic.yaml new file mode 100644 index 000000000..9d60f1042 --- /dev/null +++ b/google/cloud/asset/v1/cloudasset_gapic.yaml @@ -0,0 +1,142 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.asset.v1 + python: + package_name: google.cloud.asset_v1.gapic + go: + package_name: cloud.google.com/go/asset/apiv1 + csharp: + package_name: Google.Cloud.Asset.V1 + ruby: + package_name: Google::Cloud::Asset::V1 + php: + package_name: Google\Cloud\Asset\V1 + nodejs: + package_name: asset.v1 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.asset.v1.AssetService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ExportAssets + required_fields: + - parent + - output_config + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + long_running: + return_type: google.cloud.asset.v1.ExportAssetsResponse + metadata_type: google.cloud.asset.v1.ExportAssetsRequest + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 600000 + - name: BatchGetAssetsHistory + required_fields: + - parent + - content_type + - read_time_window + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + timeout_millis: 600000 +resource_name_generation: +- message_name: ExportAssetsRequest + field_entity_map: + parent: project +- message_name: BatchGetAssetsHistoryRequest + field_entity_map: + parent: project diff --git a/google/cloud/asset/v1beta1/BUILD.bazel b/google/cloud/asset/v1beta1/BUILD.bazel new file mode 100644 index 000000000..c78dc9961 --- /dev/null +++ b/google/cloud/asset/v1beta1/BUILD.bazel @@ -0,0 +1,142 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "asset_proto", + srcs = [ + "asset_service.proto", + "assets.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/iam/v1:policy_proto", + "//google/longrunning:operations_proto", + "@com_google_protobuf//:any_proto", + "@com_google_protobuf//:struct_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "asset_proto_with_info", + deps = [":asset_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") +load("@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", "java_gapic_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", + "@com_google_api_grpc_proto_google_iam_v1//jar", +] + +java_proto_library( + name = "asset_java_proto", + deps = [":asset_proto"], +) + +java_grpc_library( + name = "asset_java_grpc", + srcs = [":asset_proto"], + deps = [":asset_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_gapic_library( + name = "asset_java_gapic", + src = ":asset_proto_with_info", + gapic_yaml = "cloudasset_gapic.yaml", + service_yaml = "//google/cloud/asset:asset_v1beta1.yaml", + test_deps = [":asset_java_grpc"], + deps = [":asset_java_proto"] + _JAVA_GRPC_DEPS, +) + +# TODO: configure flattened methods in AssetServiceClient so +# com.google.cloud.asset.v1beta1.AssetServiceClientTest has actual methods to test (now it is empty, +# and Bazel does not allow to run empty test classes (test classes without test methods)). +# +#[java_test( +# name = test_name, +# test_class = test_name, +# runtime_deps = [ +# ":asset_java_gapic_test", +# ], +#) for test_name in [ +# "com.google.cloud.asset.v1beta1.AssetServiceClientTest", +#]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-asset-v1beta1-java", + client_deps = [":asset_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":asset_java_gapic_test"], + grpc_deps = [":asset_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":asset_java_proto", + ":asset_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "asset_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/asset/v1beta1", + protos = [":asset_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/iam/v1:iam_go_proto", + "//google/longrunning:longrunning_go_proto", + ], +) + +go_gapic_library( + name = "asset_go_gapic", + src = ":asset_proto_with_info", + gapic_yaml = "cloudasset_gapic.yaml", + importpath = "cloud.google.com/go/asset/apiv1beta1", + service_yaml = "//google/cloud/asset:asset_v1beta1.yaml", + deps = [ + ":asset_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "asset_go_gapic_test", + srcs = [":asset_go_gapic_srcjar_test"], + embed = [":asset_go_gapic"], + importpath = "cloud.google.com/go/asset/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-asset-v1beta1-go", + deps = [ + ":asset_go_gapic", + ":asset_go_gapic_srcjar-smoke-test.srcjar", + ":asset_go_gapic_srcjar-test.srcjar", + ":asset_go_proto", + ], +) diff --git a/google/cloud/asset/v1beta1/asset_service.proto b/google/cloud/asset/v1beta1/asset_service.proto new file mode 100644 index 000000000..8e2d1b0a3 --- /dev/null +++ b/google/cloud/asset/v1beta1/asset_service.proto @@ -0,0 +1,182 @@ +// Copyright 2018 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.asset.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/asset/v1beta1/assets.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Asset.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/asset/v1beta1;asset"; +option java_multiple_files = true; +option java_outer_classname = "AssetServiceProto"; +option java_package = "com.google.cloud.asset.v1beta1"; +option php_namespace = "Google\\Cloud\\Asset\\V1beta1"; + +// Asset service definition. +service AssetService { + // Exports assets with time and resource types to a given Cloud Storage + // location. The output format is newline-delimited JSON. + // This API implements the + // [google.longrunning.Operation][google.longrunning.Operation] API allowing + // you to keep track of the export. + rpc ExportAssets(ExportAssetsRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*}:exportAssets" + body: "*" + additional_bindings { + post: "/v1beta1/{parent=folders/*}:exportAssets" + body: "*" + } + additional_bindings { + post: "/v1beta1/{parent=organizations/*}:exportAssets" + body: "*" + } + }; + } + + // Batch gets the update history of assets that overlap a time window. + // For RESOURCE content, this API outputs history with asset in both + // non-delete or deleted status. + // For IAM_POLICY content, this API outputs history when the asset and its + // attached IAM POLICY both exist. This can create gaps in the output history. + rpc BatchGetAssetsHistory(BatchGetAssetsHistoryRequest) + returns (BatchGetAssetsHistoryResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*}:batchGetAssetsHistory" + additional_bindings { + get: "/v1beta1/{parent=organizations/*}:batchGetAssetsHistory" + } + }; + } +} + +// Export asset request. +message ExportAssetsRequest { + // Required. The relative name of the root asset. This can only be an + // organization number (such as "organizations/123"), a project ID (such as + // "projects/my-project-id"), a project number (such as "projects/12345"), or + // a folder number (such as "folders/123"). + string parent = 1; + + // Timestamp to take an asset snapshot. This can only be set to a timestamp + // between 2018-10-02 UTC (inclusive) and the current time. If not specified, + // the current time will be used. Due to delays in resource data collection + // and indexing, there is a volatile window during which running the same + // query may get different results. + google.protobuf.Timestamp read_time = 2; + + // A list of asset types of which to take a snapshot for. For example: + // "google.compute.Disk". If specified, only matching assets will be returned. + // See [Introduction to Cloud Asset + // Inventory](https://cloud.google.com/resource-manager/docs/cloud-asset-inventory/overview) + // for all supported asset types. + repeated string asset_types = 3; + + // Asset content type. If not specified, no content but the asset name will be + // returned. + ContentType content_type = 4; + + // Required. Output configuration indicating where the results will be output + // to. All results will be in newline delimited JSON format. + OutputConfig output_config = 5; +} + +// The export asset response. This message is returned by the +// [google.longrunning.Operations.GetOperation][google.longrunning.Operations.GetOperation] +// method in the returned +// [google.longrunning.Operation.response][google.longrunning.Operation.response] +// field. +message ExportAssetsResponse { + // Time the snapshot was taken. + google.protobuf.Timestamp read_time = 1; + + // Output configuration indicating where the results were output to. + // All results are in JSON format. + OutputConfig output_config = 2; +} + +// Batch get assets history request. +message BatchGetAssetsHistoryRequest { + // Required. The relative name of the root asset. It can only be an + // organization number (such as "organizations/123"), a project ID (such as + // "projects/my-project-id")", or a project number (such as "projects/12345"). + string parent = 1; + + // A list of the full names of the assets. For example: + // `//compute.googleapis.com/projects/my_project_123/zones/zone1/instances/instance1`. + // See [Resource + // Names](https://cloud.google.com/apis/design/resource_names#full_resource_name) + // for more info. + // + // The request becomes a no-op if the asset name list is empty, and the max + // size of the asset name list is 100 in one request. + repeated string asset_names = 2; + + // Required. The content type. + ContentType content_type = 3; + + // Optional. The time window for the asset history. Both start_time and + // end_time are optional and if set, it must be after 2018-10-02 UTC. If + // end_time is not set, it is default to current timestamp. If start_time is + // not set, the snapshot of the assets at end_time will be returned. The + // returned results contain all temporal assets whose time window overlap with + // read_time_window. + TimeWindow read_time_window = 4; +} + +// Batch get assets history response. +message BatchGetAssetsHistoryResponse { + // A list of assets with valid time windows. + repeated TemporalAsset assets = 1; +} + +// Output configuration for export assets destination. +message OutputConfig { + // Asset export destination. + oneof destination { + // Destination on Cloud Storage. + GcsDestination gcs_destination = 1; + } +} + +// A Cloud Storage location. +message GcsDestination { + // Required. + oneof object_uri { + // The uri of the Cloud Storage object. It's the same uri that is used by + // gsutil. For example: "gs://bucket_name/object_name". See [Viewing and + // Editing Object + // Metadata](https://cloud.google.com/storage/docs/viewing-editing-metadata) + // for more information. + string uri = 1; + } +} + +// Asset content type. +enum ContentType { + // Unspecified content type. + CONTENT_TYPE_UNSPECIFIED = 0; + + // Resource metadata. + RESOURCE = 1; + + // The actual IAM policy set on a resource. + IAM_POLICY = 2; +} diff --git a/google/cloud/asset/v1beta1/assets.proto b/google/cloud/asset/v1beta1/assets.proto new file mode 100644 index 000000000..84db977b9 --- /dev/null +++ b/google/cloud/asset/v1beta1/assets.proto @@ -0,0 +1,117 @@ +// Copyright 2018 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.asset.v1beta1; + +import "google/api/annotations.proto"; +import "google/iam/v1/policy.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Asset.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/asset/v1beta1;asset"; +option java_multiple_files = true; +option java_outer_classname = "AssetProto"; +option java_package = "com.google.cloud.asset.v1beta1"; +option php_namespace = "Google\\Cloud\\Asset\\V1beta1"; + +// Temporal asset. In addition to the asset, the temporal asset includes the +// status of the asset and valid from and to time of it. +message TemporalAsset { + // The time window when the asset data and state was observed. + TimeWindow window = 1; + + // If the asset is deleted or not. + bool deleted = 2; + + // Asset. + Asset asset = 3; +} + +// A time window of (start_time, end_time]. +message TimeWindow { + // Start time of the time window (exclusive). + google.protobuf.Timestamp start_time = 1; + + // End time of the time window (inclusive). + // Current timestamp if not specified. + google.protobuf.Timestamp end_time = 2; +} + +// Cloud asset. This includes all Google Cloud Platform resources, +// Cloud IAM policies, and other non-GCP assets. +message Asset { + // The full name of the asset. For example: + // `//compute.googleapis.com/projects/my_project_123/zones/zone1/instances/instance1`. + // See [Resource + // Names](https://cloud.google.com/apis/design/resource_names#full_resource_name) + // for more information. + string name = 1; + + // Type of the asset. Example: "google.compute.Disk". + string asset_type = 2; + + // Representation of the resource. + Resource resource = 3; + + // Representation of the actual Cloud IAM policy set on a cloud resource. For + // each resource, there must be at most one Cloud IAM policy set on it. + google.iam.v1.Policy iam_policy = 4; +} + +// Representation of a cloud resource. +message Resource { + // The API version. Example: "v1". + string version = 1; + + // The URL of the discovery document containing the resource's JSON schema. + // For example: + // `"https://www.googleapis.com/discovery/v1/apis/compute/v1/rest"`. + // It will be left unspecified for resources without a discovery-based API, + // such as Cloud Bigtable. + string discovery_document_uri = 2; + + // The JSON schema name listed in the discovery document. + // Example: "Project". It will be left unspecified for resources (such as + // Cloud Bigtable) without a discovery-based API. + string discovery_name = 3; + + // The REST URL for accessing the resource. An HTTP GET operation using this + // URL returns the resource itself. + // Example: + // `https://cloudresourcemanager.googleapis.com/v1/projects/my-project-123`. + // It will be left unspecified for resources without a REST API. + string resource_url = 4; + + // The full name of the immediate parent of this resource. See + // [Resource + // Names](https://cloud.google.com/apis/design/resource_names#full_resource_name) + // for more information. + // + // For GCP assets, it is the parent resource defined in the [Cloud IAM policy + // hierarchy](https://cloud.google.com/iam/docs/overview#policy_hierarchy). + // For example: + // `"//cloudresourcemanager.googleapis.com/projects/my_project_123"`. + // + // For third-party assets, it is up to the users to define. + string parent = 5; + + // The content of the resource, in which some sensitive fields are scrubbed + // away and may not be present. + google.protobuf.Struct data = 6; +} diff --git a/google/cloud/asset/v1beta1/cloudasset_gapic.yaml b/google/cloud/asset/v1beta1/cloudasset_gapic.yaml new file mode 100644 index 000000000..d88a59238 --- /dev/null +++ b/google/cloud/asset/v1beta1/cloudasset_gapic.yaml @@ -0,0 +1,146 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.asset.v1beta1 + python: + package_name: google.cloud.asset_v1beta1.gapic + go: + package_name: cloud.google.com/go/asset/apiv1beta1 + csharp: + package_name: Google.Cloud.Asset.V1Beta1 + ruby: + package_name: Google::Cloud::Asset::V1beta1 + php: + package_name: Google\Cloud\Asset\V1beta1 + nodejs: + package_name: asset.v1beta1 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.asset.v1beta1.AssetService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ExportAssets + required_fields: + - parent + - output_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + resource_name_treatment: STATIC_TYPES + long_running: + return_type: google.cloud.asset.v1beta1.ExportAssetsResponse + metadata_type: google.cloud.asset.v1beta1.ExportAssetsRequest + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 600000 + - name: BatchGetAssetsHistory + required_fields: + - parent + - content_type + - read_time_window + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 600000 +resource_name_generation: +- message_name: ExportAssetsRequest + field_entity_map: + parent: project +- message_name: BatchGetAssetsHistoryRequest + field_entity_map: + parent: project diff --git a/google/cloud/audit/audit_log.proto b/google/cloud/audit/audit_log.proto new file mode 100644 index 000000000..d76d2865c --- /dev/null +++ b/google/cloud/audit/audit_log.proto @@ -0,0 +1,128 @@ +// Copyright 2016 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.audit; + +import "google/api/annotations.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/struct.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/audit;audit"; +option java_multiple_files = true; +option java_outer_classname = "AuditLogProto"; +option java_package = "com.google.cloud.audit"; + +// Common audit log format for Google Cloud Platform API operations. +message AuditLog { + // The name of the API service performing the operation. For example, + // `"datastore.googleapis.com"`. + string service_name = 7; + + // The name of the service method or operation. + // For API calls, this should be the name of the API method. + // For example, + // + // "google.datastore.v1.Datastore.RunQuery" + // "google.logging.v1.LoggingService.DeleteLog" + string method_name = 8; + + // The resource or collection that is the target of the operation. + // The name is a scheme-less URI, not including the API service name. + // For example: + // + // "shelves/SHELF_ID/books" + // "shelves/SHELF_ID/books/BOOK_ID" + string resource_name = 11; + + // The number of items returned from a List or Query API method, + // if applicable. + int64 num_response_items = 12; + + // The status of the overall operation. + google.rpc.Status status = 2; + + // Authentication information. + AuthenticationInfo authentication_info = 3; + + // Authorization information. If there are multiple + // resources or permissions involved, then there is + // one AuthorizationInfo element for each {resource, permission} tuple. + repeated AuthorizationInfo authorization_info = 9; + + // Metadata about the operation. + RequestMetadata request_metadata = 4; + + // The operation request. This may not include all request parameters, + // such as those that are too large, privacy-sensitive, or duplicated + // elsewhere in the log record. + // It should never include user-generated data, such as file contents. + // When the JSON object represented here has a proto equivalent, the proto + // name will be indicated in the `@type` property. + google.protobuf.Struct request = 16; + + // The operation response. This may not include all response elements, + // such as those that are too large, privacy-sensitive, or duplicated + // elsewhere in the log record. + // It should never include user-generated data, such as file contents. + // When the JSON object represented here has a proto equivalent, the proto + // name will be indicated in the `@type` property. + google.protobuf.Struct response = 17; + + // Other service-specific data about the request, response, and other + // activities. + google.protobuf.Any service_data = 15; +} + +// Authentication information for the operation. +message AuthenticationInfo { + // The email address of the authenticated user making the request. + string principal_email = 1; +} + +// Authorization information for the operation. +message AuthorizationInfo { + // The resource being accessed, as a REST-style string. For example: + // + // bigquery.googlapis.com/projects/PROJECTID/datasets/DATASETID + string resource = 1; + + // The required IAM permission. + string permission = 2; + + // Whether or not authorization for `resource` and `permission` + // was granted. + bool granted = 3; +} + +// Metadata about the request. +message RequestMetadata { + // The IP address of the caller. + string caller_ip = 1; + + // The user agent of the caller. + // This information is not authenticated and should be treated accordingly. + // For example: + // + // + `google-api-python-client/1.4.0`: + // The request was made by the Google API client for Python. + // + `Cloud SDK Command Line Tool apitools-client/1.0 gcloud/0.9.62`: + // The request was made by the Google Cloud SDK CLI (gcloud). + // + `AppEngine-Google; (+http://code.google.com/appengine; appid: + // s~my-project`: + // The request was made from the `my-project` App Engine app. + string caller_supplied_user_agent = 2; +} diff --git a/google/cloud/automl/BUILD.bazel b/google/cloud/automl/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/automl/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/automl/artman_automl_v1beta1.yaml b/google/cloud/automl/artman_automl_v1beta1.yaml new file mode 100644 index 000000000..a98243bd6 --- /dev/null +++ b/google/cloud/automl/artman_automl_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: automl + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: automl_v1beta1.yaml + gapic_yaml: v1beta1/automl_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/automl/automl_v1beta1.yaml b/google/cloud/automl/automl_v1beta1.yaml new file mode 100644 index 000000000..ce17fb353 --- /dev/null +++ b/google/cloud/automl/automl_v1beta1.yaml @@ -0,0 +1,129 @@ +type: google.api.Service +config_version: 3 +name: automl.googleapis.com +title: Cloud AutoML API + +apis: +- name: google.cloud.automl.v1beta1.AutoMl +- name: google.cloud.automl.v1beta1.PredictionService + +types: +- name: google.cloud.automl.v1beta1.OperationMetadata +- name: google.cloud.automl.v1beta1.BatchPredictResult + +documentation: + summary: |- + Train high-quality custom machine learning models with minimum effort and + machine learning expertise. + overview: |- + Cloud AutoML is a suite of machine learning products that enables developers + with limited machine learning expertise to train high-quality models + specific to their business needs, by leveraging Google’s state-of-the-art + transfer learning, and Neural Architecture Search technology. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 50.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 5.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 5.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.PredictionService.Predict + deadline: 60.0 + - selector: google.cloud.automl.v1beta1.PredictionService.BatchPredict + deadline: 20.0 + - selector: google.cloud.automl.v1beta1.AutoMl.CreateDataset + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.GetDataset + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ListDatasets + deadline: 50.0 + - selector: google.cloud.automl.v1beta1.AutoMl.UpdateDataset + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.DeleteDataset + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ImportData + deadline: 20.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ExportData + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.GetAnnotationSpec + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.GetTableSpec + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ListTableSpecs + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.UpdateTableSpec + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.GetColumnSpec + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ListColumnSpecs + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.UpdateColumnSpec + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.CreateModel + deadline: 20.0 + - selector: google.cloud.automl.v1beta1.AutoMl.GetModel + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ListModels + deadline: 50.0 + - selector: google.cloud.automl.v1beta1.AutoMl.DeleteModel + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.DeployModel + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.UndeployModel + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ExportModel + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ExportEvaluatedExamples + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.GetModelEvaluation + deadline: 5.0 + - selector: google.cloud.automl.v1beta1.AutoMl.ListModelEvaluations + deadline: 50.0 + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + deadline: 5.0 + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + deadline: 5.0 + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + deadline: 5.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1beta1/{name=projects/*/locations/*}/operations' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1beta1/{name=projects/*/locations/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1beta1/{name=projects/*/locations/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1beta1/{name=projects/*/locations/*/operations/*}:cancel' + body: '*' + + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + post: '/v1beta1/{resource=projects/*/locations/*/datasets/*}:setIamPolicy' + body: '*' + additional_bindings: + - post: '/v1beta1/{resource=projects/*/locations/*/models/*}:setIamPolicy' + body: '*' + + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + get: '/v1beta1/{resource=projects/*/locations/*/datasets/*}:getIamPolicy' + additional_bindings: + - get: '/v1beta1/{resource=projects/*/locations/*/models/*}:getIamPolicy' + + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + post: '/v1beta1/{resource=projects/*/locations/*/**}:testIamPermissions' + body: '*' + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/automl/v1beta1/BUILD.bazel b/google/cloud/automl/v1beta1/BUILD.bazel new file mode 100644 index 000000000..ad36e9ab6 --- /dev/null +++ b/google/cloud/automl/v1beta1/BUILD.bazel @@ -0,0 +1,162 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "automl_proto", + srcs = [ + "annotation_payload.proto", + "classification.proto", + "data_items.proto", + "dataset.proto", + "image.proto", + "io.proto", + "model.proto", + "model_evaluation.proto", + "operations.proto", + "prediction_service.proto", + "service.proto", + "text.proto", + "translation.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "automl_proto_with_info", + deps = [":automl_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "automl_java_proto", + deps = [":automl_proto"], +) + +java_grpc_library( + name = "automl_java_grpc", + srcs = [":automl_proto"], + deps = [":automl_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "automl_resource_name_java_proto", + gapic_yaml = "automl_gapic.yaml", + deps = [":automl_proto"], +) + +java_gapic_library( + name = "automl_java_gapic", + src = ":automl_proto_with_info", + gapic_yaml = "automl_gapic.yaml", + service_yaml = "//google/cloud/automl:automl_v1beta1.yaml", + test_deps = [":automl_java_grpc"], + deps = [ + ":automl_java_proto", + ":automl_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":automl_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.automl.v1beta1.AutoMlClientTest", + "com.google.cloud.automl.v1beta1.PredictionServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-automl-v1beta1-java", + client_deps = [":automl_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":automl_java_gapic_test"], + grpc_deps = [":automl_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":automl_java_proto", + ":automl_proto", + ":automl_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "automl_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1", + protos = [":automl_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "automl_go_gapic", + src = ":automl_proto_with_info", + gapic_yaml = "automl_gapic.yaml", + importpath = "cloud.google.com/go/cloud/automl/apiv1beta1", + service_yaml = "//google/cloud/automl:automl_v1beta1.yaml", + deps = [ + ":automl_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "automl_go_gapic_test", + srcs = [":automl_go_gapic_srcjar_test"], + embed = [":automl_go_gapic"], + importpath = "cloud.google.com/go/cloud/automl/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-automl-v1beta1-go", + deps = [ + ":automl_go_gapic", + ":automl_go_gapic_srcjar-smoke-test.srcjar", + ":automl_go_gapic_srcjar-test.srcjar", + ":automl_go_proto", + ], +) diff --git a/google/cloud/automl/v1beta1/annotation_payload.proto b/google/cloud/automl/v1beta1/annotation_payload.proto new file mode 100644 index 000000000..6a06308e3 --- /dev/null +++ b/google/cloud/automl/v1beta1/annotation_payload.proto @@ -0,0 +1,74 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/classification.proto"; +import "google/cloud/automl/v1beta1/detection.proto"; +import "google/cloud/automl/v1beta1/tables.proto"; +import "google/cloud/automl/v1beta1/text_extraction.proto"; +import "google/cloud/automl/v1beta1/text_sentiment.proto"; +import "google/cloud/automl/v1beta1/translation.proto"; +import "google/protobuf/any.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Contains annotation information that is relevant to AutoML. +message AnnotationPayload { + // Output only . Additional information about the annotation + // specific to the AutoML domain. + oneof detail { + // Annotation details for translation. + TranslationAnnotation translation = 2; + + // Annotation details for content or image classification. + ClassificationAnnotation classification = 3; + + // Annotation details for image object detection. + ImageObjectDetectionAnnotation image_object_detection = 4; + + // Annotation details for video classification. + // Returned for Video Classification predictions. + VideoClassificationAnnotation video_classification = 9; + + // Annotation details for text extraction. + TextExtractionAnnotation text_extraction = 6; + + // Annotation details for text sentiment. + TextSentimentAnnotation text_sentiment = 7; + + // Annotation details for Tables. + TablesAnnotation tables = 10; + } + + // Output only . The resource ID of the annotation spec that + // this annotation pertains to. The annotation spec comes from either an + // ancestor dataset, or the dataset that was used to train the model in use. + string annotation_spec_id = 1; + + // Output only. The value of [AnnotationSpec.display_name][google.cloud.automl.v1beta1.AnnotationSpec.display_name] when the model + // was trained. Because this field returns a value at model training time, + // for different models trained using the same dataset, the returned value + // could be different as model owner could update the display_name between + // any two model training. + string display_name = 5; +} diff --git a/google/cloud/automl/v1beta1/automl_gapic.yaml b/google/cloud/automl/v1beta1/automl_gapic.yaml new file mode 100644 index 000000000..ba3e9edf2 --- /dev/null +++ b/google/cloud/automl/v1beta1/automl_gapic.yaml @@ -0,0 +1,730 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.automl.v1beta1 + python: + package_name: google.cloud.automl_v1beta1.gapic + go: + package_name: cloud.google.com/go/cloud/automl/apiv1beta1 + csharp: + package_name: Google.Cloud.Automl.V1Beta1 + ruby: + package_name: Google::Cloud::Automl::V1Beta1 + php: + package_name: Google\Cloud\AutoMl\V1beta1 + nodejs: + package_name: automl.v1beta1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.automl.v1beta1.PredictionService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location}/models/{model} + entity_name: model + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: Predict + flattening: + groups: + - parameters: + - name + - payload + - params + required_fields: + - name + - payload + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: model + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: BatchPredict + required_fields: + - name + - input_config + - output_config + flattening: + groups: + - parameters: + - name + - input_config + - output_config + - params + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: model + long_running: + return_type: google.cloud.automl.v1beta1.BatchPredictResult + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 20000 + # The fully qualified name of the API interface. +- name: google.cloud.automl.v1beta1.AutoMl + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/datasets/{dataset} + entity_name: dataset + - name_pattern: projects/{project}/locations/{location}/models/{model} + entity_name: model + - name_pattern: projects/{project}/locations/{location}/models/{model}/modelEvaluations/{model_evaluation} + entity_name: model_evaluation + - name_pattern: projects/{project}/locations/{location}/datasets/{dataset}/annotationSpecs/{annotation_spec} + entity_name: annotation_spec + - name_pattern: projects/{project}/locations/{location}/datasets/{dataset}/tableSpecs/{table_spec} + entity_name: table_spec + - name_pattern: projects/{project}/locations/{location}/datasets/{dataset}/tableSpecs/{table_spec}/columnSpecs/{column_spec} + entity_name: column_spec + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateDataset + flattening: + groups: + - parameters: + - parent + - dataset + required_fields: + - parent + - dataset + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + - name: UpdateDataset + flattening: + groups: + - parameters: + - dataset + required_fields: + - dataset + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + dataset.name: dataset + timeout_millis: 5000 + - name: GetDataset + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: dataset + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + - name: ListDatasets + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: datasets + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + - name: DeleteDataset + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: dataset + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + - name: ImportData + flattening: + groups: + - parameters: + - name + - input_config + required_fields: + - name + - input_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: dataset + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + - name: ExportData + flattening: + groups: + - parameters: + - name + - output_config + required_fields: + - name + - output_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: dataset + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + - name: CreateModel + flattening: + groups: + - parameters: + - parent + - model + required_fields: + - parent + - model + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + long_running: + return_type: google.cloud.automl.v1beta1.Model + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + - name: GetModel + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: model + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + - name: ListModels + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: model + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + - name: DeleteModel + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: model + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + - name: DeployModel + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: model + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + - name: UndeployModel + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: model + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + - name: GetModelEvaluation + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: model_evaluation + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + - name: ExportModel + required_fields: + - name + - output_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: model + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 5000 + - name: ExportEvaluatedExamples + required_fields: + - name + - output_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: model + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.automl.v1beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 5000 + - name: ListModelEvaluations + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: model_evaluation + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: model + resource_name_treatment: STATIC_TYPES + timeout_millis: 5000 + - name: GetAnnotationSpec + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: annotation_spec + timeout_millis: 5000 + - name: GetTableSpec + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: table_spec + timeout_millis: 5000 + - name: ListTableSpecs + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: table_specs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: dataset + timeout_millis: 5000 + - name: UpdateTableSpec + flattening: + groups: + - parameters: + - table_spec + required_fields: + - table_spec + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + table_spec.name: table_spec + timeout_millis: 5000 + - name: GetColumnSpec + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: column_spec + timeout_millis: 5000 + - name: ListColumnSpecs + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: column_specs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: table_spec + timeout_millis: 5000 + - name: UpdateColumnSpec + flattening: + groups: + - parameters: + - column_spec + required_fields: + - column_spec + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + column_spec.name: column_spec + timeout_millis: 5000 +resource_name_generation: +- message_name: CreateDatasetRequest + field_entity_map: + parent: location +- message_name: UpdateDatasetRequest + field_entity_map: + dataset.name: dataset +- message_name: GetDatasetRequest + field_entity_map: + name: dataset +- message_name: ListDatasetsRequest + field_entity_map: + parent: location +- message_name: DeleteDatasetRequest + field_entity_map: + name: dataset +- message_name: ImportDataRequest + field_entity_map: + name: dataset +- message_name: ExportDataRequest + field_entity_map: + name: dataset +- message_name: CreateModelRequest + field_entity_map: + parent: location +- message_name: GetModelRequest + field_entity_map: + name: model +- message_name: ListModelsRequest + field_entity_map: + parent: location +- message_name: DeleteModelRequest + field_entity_map: + name: model +- message_name: DeployModelRequest + field_entity_map: + name: model +- message_name: UndeployModelRequest + field_entity_map: + name: model +- message_name: ExportModelRequest + field_entity_map: + name: model +- message_name: ExportEvaluatedExamplesRequest + field_entity_map: + name: model +- message_name: GetModelEvaluationRequest + field_entity_map: + name: model_evaluation +- message_name: ListModelEvaluationsRequest + field_entity_map: + parent: model +- message_name: PredictRequest + field_entity_map: + name: model +- message_name: BatchPredictRequest + field_entity_map: + name: model +- message_name: GetAnnotationSpecRequest + field_entity_map: + name: annotation_spec +- message_name: GetTableSpecRequest + field_entity_map: + name: table_spec +- message_name: ListTableSpecsRequest + field_entity_map: + parent: dataset +- message_name: UpdateTableSpecRequest + field_entity_map: + table_spec.name: table_spec +- message_name: GetColumnSpecRequest + field_entity_map: + name: column_spec +- message_name: ListColumnSpecsRequest + field_entity_map: + parent: table_spec +- message_name: UpdateColumnSpecRequest + field_entity_map: + column_spec.name: column_spec diff --git a/google/cloud/automl/v1beta1/classification.proto b/google/cloud/automl/v1beta1/classification.proto new file mode 100644 index 000000000..6f95e89e1 --- /dev/null +++ b/google/cloud/automl/v1beta1/classification.proto @@ -0,0 +1,202 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/temporal.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_outer_classname = "ClassificationProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Contains annotation details specific to classification. +message ClassificationAnnotation { + // Output only. A confidence estimate between 0.0 and 1.0. A higher value + // means greater confidence that the annotation is positive. If a user + // approves an annotation as negative or positive, the score value remains + // unchanged. If a user creates an annotation, the score is 0 for negative or + // 1 for positive. + float score = 1; +} + +// Contains annotation details specific to video classification. +message VideoClassificationAnnotation { + // Output only. Expresses the type of video classification. Possible values: + // + // * `segment` - Classification done on a specified by user + // time segment of a video. AnnotationSpec is answered to be present + // in that time segment, if it is present in any part of it. The video + // ML model evaluations are done only for this type of classification. + // + // * `shot`- Shot-level classification. + // AutoML Video Intelligence determines the boundaries + // for each camera shot in the entire segment of the video that user + // specified in the request configuration. AutoML Video Intelligence + // then returns labels and their confidence scores for each detected + // shot, along with the start and end time of the shot. + // WARNING: Model evaluation is not done for this classification type, + // the quality of it depends on training data, but there are no + // metrics provided to describe that quality. + // + // * `1s_interval` - AutoML Video Intelligence returns labels and their + // confidence scores for each second of the entire segment of the video + // that user specified in the request configuration. + // WARNING: Model evaluation is not done for this classification type, + // the quality of it depends on training data, but there are no + // metrics provided to describe that quality. + string type = 1; + + // Output only . The classification details of this annotation. + ClassificationAnnotation classification_annotation = 2; + + // Output only . The time segment of the video to which the + // annotation applies. + TimeSegment time_segment = 3; +} + +// Model evaluation metrics for classification problems. +// Note: For Video Classification this metrics only describe quality of the +// Video Classification predictions of "segment_classification" type. +message ClassificationEvaluationMetrics { + // Metrics for a single confidence threshold. + message ConfidenceMetricsEntry { + // Output only. Metrics are computed with an assumption that the model + // never returns predictions with score lower than this value. + float confidence_threshold = 1; + + // Output only. Metrics are computed with an assumption that the model + // always returns at most this many predictions (ordered by their score, + // descendingly), but they all still need to meet the confidence_threshold. + int32 position_threshold = 14; + + // Output only. Recall (True Positive Rate) for the given confidence + // threshold. + float recall = 2; + + // Output only. Precision for the given confidence threshold. + float precision = 3; + + // Output only. False Positive Rate for the given confidence threshold. + float false_positive_rate = 8; + + // Output only. The harmonic mean of recall and precision. + float f1_score = 4; + + // Output only. The Recall (True Positive Rate) when only considering the + // label that has the highest prediction score and not below the confidence + // threshold for each example. + float recall_at1 = 5; + + // Output only. The precision when only considering the label that has the + // highest prediction score and not below the confidence threshold for each + // example. + float precision_at1 = 6; + + // Output only. The False Positive Rate when only considering the label that + // has the highest prediction score and not below the confidence threshold + // for each example. + float false_positive_rate_at1 = 9; + + // Output only. The harmonic mean of [recall_at1][google.cloud.automl.v1beta1.ClassificationEvaluationMetrics.ConfidenceMetricsEntry.recall_at1] and [precision_at1][google.cloud.automl.v1beta1.ClassificationEvaluationMetrics.ConfidenceMetricsEntry.precision_at1]. + float f1_score_at1 = 7; + + // Output only. The number of model created labels that match a ground truth + // label. + int64 true_positive_count = 10; + + // Output only. The number of model created labels that do not match a + // ground truth label. + int64 false_positive_count = 11; + + // Output only. The number of ground truth labels that are not matched + // by a model created label. + int64 false_negative_count = 12; + + // Output only. The number of labels that were not created by the model, + // but if they would, they would not match a ground truth label. + int64 true_negative_count = 13; + } + + // Confusion matrix of the model running the classification. + message ConfusionMatrix { + // Output only. A row in the confusion matrix. + message Row { + // Output only. Value of the specific cell in the confusion matrix. + // The number of values each row has (i.e. the length of the row) is equal + // to the length of the annotation_spec_id field. + repeated int32 example_count = 1; + } + + // Output only. IDs of the annotation specs used in the confusion matrix. + repeated string annotation_spec_id = 1; + + // Output only. Rows in the confusion matrix. The number of rows is equal to + // the size of `annotation_spec_id`. + // `row[i].value[j]` is the number of examples that have ground truth of the + // `annotation_spec_id[i]` and are predicted as `annotation_spec_id[j]` by + // the model being evaluated. + repeated Row row = 2; + } + + // Output only. The Area Under Precision-Recall Curve metric. Micro-averaged + // for the overall evaluation. + float au_prc = 1; + + // Output only. The Area Under Precision-Recall Curve metric based on priors. + // Micro-averaged for the overall evaluation. + // Deprecated. + float base_au_prc = 2 [deprecated = true]; + + // Output only. The Area Under Receiver Operating Characteristic curve metric. + // Micro-averaged for the overall evaluation. + float au_roc = 6; + + // Output only. The Log Loss metric. + float log_loss = 7; + + // Output only. Metrics for each confidence_threshold in + // 0.00,0.05,0.10,...,0.95,0.96,0.97,0.98,0.99 and + // position_threshold = INT32_MAX_VALUE. + // Precision-recall curve is derived from them. + // The above metrics may also be supplied for additional values of + // position_threshold. + repeated ConfidenceMetricsEntry confidence_metrics_entry = 3; + + // Output only. Confusion matrix of the evaluation. + // Only set for MULTICLASS classification problems where number + // of labels is no more than 10. + // Only set for model level evaluation, not for evaluation per label. + ConfusionMatrix confusion_matrix = 4; + + // Output only. The annotation spec ids used for this evaluation. + repeated string annotation_spec_id = 5; +} + +// Type of the classification problem. +enum ClassificationType { + // Should not be used, an un-set enum has this value by default. + CLASSIFICATION_TYPE_UNSPECIFIED = 0; + + // At most one label is allowed per example. + MULTICLASS = 1; + + // Multiple labels are allowed for one example. + MULTILABEL = 2; +} diff --git a/google/cloud/automl/v1beta1/column_spec.proto b/google/cloud/automl/v1beta1/column_spec.proto new file mode 100644 index 000000000..9e977cf5e --- /dev/null +++ b/google/cloud/automl/v1beta1/column_spec.proto @@ -0,0 +1,78 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/data_stats.proto"; +import "google/cloud/automl/v1beta1/data_types.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A representation of a column in a relational table. When listing them, column specs are returned in the same order in which they were +// given on import . +// Used by: +// * Tables +message ColumnSpec { + // Identifies the table's column, and its correlation with the column this + // ColumnSpec describes. + message CorrelatedColumn { + // The column_spec_id of the correlated column, which belongs to the same + // table as the in-context column. + string column_spec_id = 1; + + // Correlation between this and the in-context column. + CorrelationStats correlation_stats = 2; + } + + // Output only. The resource name of the column specs. + // Form: + // + // `projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/tableSpecs/{table_spec_id}/columnSpecs/{column_spec_id}` + string name = 1; + + // The data type of elements stored in the column. + DataType data_type = 2; + + // Output only. The name of the column to show in the interface. The name can + // be up to 100 characters long and can consist only of ASCII Latin letters + // A-Z and a-z, ASCII digits 0-9, underscores(_), and forward slashes(/), and + // must start with a letter or a digit. + string display_name = 3; + + // Output only. Stats of the series of values in the column. + // This field may be stale, see the ancestor's + // Dataset.tables_dataset_metadata.stats_update_time field + // for the timestamp at which these stats were last updated. + DataStats data_stats = 4; + + // Output only. Top 10 most correlated with this column columns of the table, + // ordered by + // [cramers_v][google.cloud.automl.v1beta1.CorrelationStats.cramers_v] metric. + // This field may be stale, see the ancestor's + // Dataset.tables_dataset_metadata.stats_update_time field + // for the timestamp at which these stats were last updated. + repeated CorrelatedColumn top_correlated_columns = 5; + + // Used to perform consistent read-modify-write updates. If not set, a blind + // "overwrite" update happens. + string etag = 6; +} diff --git a/google/cloud/automl/v1beta1/data_items.proto b/google/cloud/automl/v1beta1/data_items.proto new file mode 100644 index 000000000..f596cda27 --- /dev/null +++ b/google/cloud/automl/v1beta1/data_items.proto @@ -0,0 +1,109 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/io.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A representation of an image. +// Only images up to 30MB in size are supported. +message Image { + // Input only. The data representing the image. + // For Predict calls [image_bytes][] must be set, as other options are not + // currently supported by prediction API. You can read the contents of an + // uploaded image by using the [content_uri][] field. + oneof data { + // Image content represented as a stream of bytes. + // Note: As with all `bytes` fields, protobuffers use a pure binary + // representation, whereas JSON representations use base64. + bytes image_bytes = 1; + + // An input config specifying the content of the image. + InputConfig input_config = 6; + } + + // Output only. HTTP URI to the thumbnail image. + string thumbnail_uri = 4; +} + +// A representation of a text snippet. +message TextSnippet { + // Required. The content of the text snippet as a string. Up to 250000 + // characters long. + string content = 1; + + // The format of the source text. Currently the only two allowed values are + // "text/html" and "text/plain". If left blank the format is automatically + // determined from the type of the uploaded content. + string mime_type = 2; + + // Output only. HTTP URI where you can download the content. + string content_uri = 4; +} + +// A structured text document e.g. a PDF. +message Document { + // An input config specifying the content of the document. + DocumentInputConfig input_config = 1; +} + +// A representation of a row in a relational table. +message Row { + // The resource IDs of the column specs describing the columns of the row. + // If set must contain, but possibly in a different order, all input feature + // + // [column_spec_ids][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] + // of the Model this row is being passed to. + // Note: The below `values` field must match order of this field, if this + // field is set. + repeated string column_spec_ids = 2; + + // Required. The values of the row cells, given in the same order as the + // column_spec_ids, or, if not set, then in the same order as input feature + // + // [column_specs][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] + // of the Model this row is being passed to. + repeated google.protobuf.Value values = 3; +} + +// Example data used for training or prediction. +message ExamplePayload { + // Required. Input only. The example data. + oneof payload { + // Example image. + Image image = 1; + + // Example text. + TextSnippet text_snippet = 2; + + // Example document. + Document document = 4; + + // Example relational table row. + Row row = 3; + } +} diff --git a/google/cloud/automl/v1beta1/data_stats.proto b/google/cloud/automl/v1beta1/data_stats.proto new file mode 100644 index 000000000..c6557bb37 --- /dev/null +++ b/google/cloud/automl/v1beta1/data_stats.proto @@ -0,0 +1,164 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// The data statistics of a series of values that share the same DataType. +message DataStats { + // The data statistics specific to a DataType. + oneof stats { + // The statistics for FLOAT64 DataType. + Float64Stats float64_stats = 3; + + // The statistics for STRING DataType. + StringStats string_stats = 4; + + // The statistics for TIMESTAMP DataType. + TimestampStats timestamp_stats = 5; + + // The statistics for ARRAY DataType. + ArrayStats array_stats = 6; + + // The statistics for STRUCT DataType. + StructStats struct_stats = 7; + + // The statistics for CATEGORY DataType. + CategoryStats category_stats = 8; + } + + // The number of distinct values. + int64 distinct_value_count = 1; + + // The number of values that are null. + int64 null_value_count = 2; +} + +// The data statistics of a series of FLOAT64 values. +message Float64Stats { + // A bucket of a histogram. + message HistogramBucket { + // The minimum value of the bucket, inclusive. + double min = 1; + + // The maximum value of the bucket, exclusive unless max = `"Infinity"`, in + // which case it's inclusive. + double max = 2; + + // The number of data values that are in the bucket, i.e. are between + // min and max values. + int64 count = 3; + } + + // The mean of the series. + double mean = 1; + + // The standard deviation of the series. + double standard_deviation = 2; + + // Ordered from 0 to k k-quantile values of the data series of n values. + // The value at index i is, approximately, the i*n/k-th smallest value in the + // series; for i = 0 and i = k these are, respectively, the min and max + // values. + repeated double quantiles = 3; + + // Histogram buckets of the data series. Sorted by the min value of the + // bucket, ascendingly, and the number of the buckets is dynamically + // generated. The buckets are non-overlapping and completely cover whole + // FLOAT64 range with min of first bucket being `"-Infinity"`, and max of + // the last one being `"Infinity"`. + repeated HistogramBucket histogram_buckets = 4; +} + +// The data statistics of a series of STRING values. +message StringStats { + // The statistics of a unigram. + message UnigramStats { + // The unigram. + string value = 1; + + // The number of occurrences of this unigram in the series. + int64 count = 2; + } + + // The statistics of the top 20 unigrams, ordered by + // [count][google.cloud.automl.v1beta1.StringStats.UnigramStats.count]. + repeated UnigramStats top_unigram_stats = 1; +} + +// The data statistics of a series of TIMESTAMP values. +message TimestampStats { + // Stats split by a defined in context granularity. + message GranularStats { + // A map from granularity key to example count for that key. + // E.g. for hour_of_day `13` means 1pm, or for month_of_year `5` means May). + map<int32, int64> buckets = 1; + } + + // The string key is the pre-defined granularity. Currently supported: + // hour_of_day, day_of_week, month_of_year. + // Granularities finer that the granularity of timestamp data are not + // populated (e.g. if timestamps are at day granularity, then hour_of_day + // is not populated). + map<string, GranularStats> granular_stats = 1; +} + +// The data statistics of a series of ARRAY values. +message ArrayStats { + // Stats of all the values of all arrays, as if they were a single long + // series of data. The type depends on the element type of the array. + DataStats member_stats = 2; +} + +// The data statistics of a series of STRUCT values. +message StructStats { + // Map from a field name of the struct to data stats aggregated over series + // of all data in that field across all the structs. + map<string, DataStats> field_stats = 1; +} + +// The data statistics of a series of CATEGORY values. +message CategoryStats { + // The statistics of a single CATEGORY value. + message SingleCategoryStats { + // The CATEGORY value. + string value = 1; + + // The number of occurrences of this value in the series. + int64 count = 2; + } + + // The statistics of the top 20 CATEGORY values, ordered by + // + // [count][google.cloud.automl.v1beta1.CategoryStats.SingleCategoryStats.count]. + repeated SingleCategoryStats top_category_stats = 1; +} + +// A correlation statistics between two series of DataType values. The series +// may have differing DataType-s, but within a single series the DataType must +// be the same. +message CorrelationStats { + // The correlation value using the Cramer's V measure. + double cramers_v = 1; +} diff --git a/google/cloud/automl/v1beta1/data_types.proto b/google/cloud/automl/v1beta1/data_types.proto new file mode 100644 index 000000000..19ab5a553 --- /dev/null +++ b/google/cloud/automl/v1beta1/data_types.proto @@ -0,0 +1,116 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/io.proto"; +import "google/cloud/automl/v1beta1/text_extraction.proto"; +import "google/protobuf/any.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Indicated the type of data that can be stored in a structured data entity +// (e.g. a table). +message DataType { + // Details of DataType-s that need additional specification. + oneof details { + // If [type_code][google.cloud.automl.v1beta1.DataType.type_code] == [ARRAY][google.cloud.automl.v1beta1.TypeCode.ARRAY], + // then `list_element_type` is the type of the elements. + DataType list_element_type = 2; + + // If [type_code][google.cloud.automl.v1beta1.DataType.type_code] == [STRUCT][google.cloud.automl.v1beta1.TypeCode.STRUCT], then `struct_type` + // provides type information for the struct's fields. + StructType struct_type = 3; + + // If [type_code][google.cloud.automl.v1beta1.DataType.type_code] == [TIMESTAMP][google.cloud.automl.v1beta1.TypeCode.TIMESTAMP] + // then `time_format` provides the format in which that time field is + // expressed. The time_format must either be one of: + // * `UNIX_SECONDS` + // * `UNIX_MILLISECONDS` + // * `UNIX_MICROSECONDS` + // * `UNIX_NANOSECONDS` + // (for respectively number of seconds, milliseconds, microseconds and + // nanoseconds since start of the Unix epoch); + // or be written in `strftime` syntax. If time_format is not set, then the + // default format as described on the type_code is used. + string time_format = 5; + } + + // Required. The [TypeCode][google.cloud.automl.v1beta1.TypeCode] for this type. + TypeCode type_code = 1; + + // If true, this DataType can also be `null`. + bool nullable = 4; +} + +// `StructType` defines the DataType-s of a [STRUCT][google.cloud.automl.v1beta1.TypeCode.STRUCT] type. +message StructType { + // Unordered map of struct field names to their data types. + // Fields cannot be added or removed via Update. Their names and + // data types are still mutable. + map<string, DataType> fields = 1; +} + +// `TypeCode` is used as a part of +// [DataType][google.cloud.automl.v1beta1.DataType]. +// +// Each legal value of a DataType can be encoded to or decoded from a JSON +// value, using the encodings listed below, and definitions of which can be +// found at +// +// https: +// //developers.google.com/protocol-buffers +// // /docs/reference/google.protobuf#value. +enum TypeCode { + // Not specified. Should not be used. + TYPE_CODE_UNSPECIFIED = 0; + + // Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or + // `"-Infinity"`. + FLOAT64 = 3; + + // Must be between 0AD and 9999AD. Encoded as `string` according to + // [time_format][google.cloud.automl.v1beta1.DataType.time_format], or, if + // that format is not set, then in RFC 3339 `date-time` format, where + // `time-offset` = `"Z"` (e.g. 1985-04-12T23:20:50.52Z). + TIMESTAMP = 4; + + // Encoded as `string`. + STRING = 6; + + // Encoded as `list`, where the list elements are represented according to + // + // [list_element_type][google.cloud.automl.v1beta1.DataType.list_element_type]. + ARRAY = 8; + + // Encoded as `struct`, where field values are represented according to + // [struct_type][google.cloud.automl.v1beta1.DataType.struct_type]. + STRUCT = 9; + + // Values of this type are not further understood by AutoML, + // e.g. AutoML is unable to tell the order of values (as it could with + // FLOAT64), or is unable to say if one value contains another (as it + // could with STRING). + // Encoded as `string` (bytes should be base64-encoded, as described in RFC + // 4648, section 4). + CATEGORY = 10; +} diff --git a/google/cloud/automl/v1beta1/dataset.proto b/google/cloud/automl/v1beta1/dataset.proto new file mode 100644 index 000000000..42fc45360 --- /dev/null +++ b/google/cloud/automl/v1beta1/dataset.proto @@ -0,0 +1,110 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/annotation_payload.proto"; +import "google/cloud/automl/v1beta1/data_items.proto"; +import "google/cloud/automl/v1beta1/image.proto"; +import "google/cloud/automl/v1beta1/tables.proto"; +import "google/cloud/automl/v1beta1/text.proto"; +import "google/cloud/automl/v1beta1/translation.proto"; +import "google/cloud/automl/v1beta1/video.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A workspace for solving a single, particular machine learning (ML) problem. +// A workspace contains examples that may be annotated. +message Dataset { + // Required. + // The dataset metadata that is specific to the problem type. + oneof dataset_metadata { + // Metadata for a dataset used for translation. + TranslationDatasetMetadata translation_dataset_metadata = 23; + + // Metadata for a dataset used for image classification. + ImageClassificationDatasetMetadata image_classification_dataset_metadata = 24; + + // Metadata for a dataset used for text classification. + TextClassificationDatasetMetadata text_classification_dataset_metadata = 25; + + // Metadata for a dataset used for image object detection. + ImageObjectDetectionDatasetMetadata image_object_detection_dataset_metadata = 26; + + // Metadata for a dataset used for video classification. + VideoClassificationDatasetMetadata video_classification_dataset_metadata = 31; + + // Metadata for a dataset used for text extraction. + TextExtractionDatasetMetadata text_extraction_dataset_metadata = 28; + + // Metadata for a dataset used for text sentiment. + TextSentimentDatasetMetadata text_sentiment_dataset_metadata = 30; + + // Metadata for a dataset used for Tables. + TablesDatasetMetadata tables_dataset_metadata = 33; + } + + // Output only. The resource name of the dataset. + // Form: `projects/{project_id}/locations/{location_id}/datasets/{dataset_id}` + string name = 1; + + // Required. The name of the dataset to show in the interface. The name can be + // up to 32 characters long and can consist only of ASCII Latin letters A-Z + // and a-z, underscores + // (_), and ASCII digits 0-9. + string display_name = 2; + + // User-provided description of the dataset. The description can be up to + // 25000 characters long. + string description = 3; + + // Output only. The number of examples in the dataset. + int32 example_count = 21; + + // Output only. Timestamp when this dataset was created. + google.protobuf.Timestamp create_time = 14; + + // Used to perform consistent read-modify-write updates. If not set, a blind + // "overwrite" update happens. + string etag = 17; +} + +// A definition of an annotation. +message AnnotationSpec { + // Output only. Resource name of the annotation spec. + // Form: + // + // 'projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/annotationSpecs/{annotation_spec_id}' + string name = 1; + + // Required. + // The name of the annotation spec to show in the interface. The name can be + // up to 32 characters long and can consist only of ASCII Latin letters A-Z + // and a-z, underscores + // (_), and ASCII digits 0-9. + string display_name = 2; + + // Output only. The number of examples in the parent dataset + // labeled by the annotation spec. + int32 example_count = 9; +} diff --git a/google/cloud/automl/v1beta1/detection.proto b/google/cloud/automl/v1beta1/detection.proto new file mode 100644 index 000000000..face89c21 --- /dev/null +++ b/google/cloud/automl/v1beta1/detection.proto @@ -0,0 +1,89 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/geometry.proto"; +import "google/protobuf/duration.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Annotation details for image object detection. +message ImageObjectDetectionAnnotation { + // Output only. + // The rectangle representing the object location. + BoundingPoly bounding_box = 1; + + // Output only. + // The confidence that this annotation is positive for the parent example, + // value in [0, 1], higher means higher positivity confidence. + float score = 2; +} + +// Bounding box matching model metrics for a single intersection-over-union +// threshold and multiple label match confidence thresholds. +message BoundingBoxMetricsEntry { + // Metrics for a single confidence threshold. + message ConfidenceMetricsEntry { + // Output only. The confidence threshold value used to compute the metrics. + float confidence_threshold = 1; + + // Output only. Recall under the given confidence threshold. + float recall = 2; + + // Output only. Precision under the given confidence threshold. + float precision = 3; + + // Output only. The harmonic mean of recall and precision. + float f1_score = 4; + } + + // Output only. The intersection-over-union threshold value used to compute + // this metrics entry. + float iou_threshold = 1; + + // Output only. The mean average precision, most often close to au_prc. + float mean_average_precision = 2; + + // Output only. Metrics for each label-match confidence_threshold from + // 0.05,0.10,...,0.95,0.96,0.97,0.98,0.99. Precision-recall curve is + // derived from them. + repeated ConfidenceMetricsEntry confidence_metrics_entries = 3; +} + +// Model evaluation metrics for image object detection problems. +// Evaluates prediction quality of labeled bounding boxes. +message ImageObjectDetectionEvaluationMetrics { + // Output only. The total number of bounding boxes (i.e. summed over all + // images) the ground truth used to create this evaluation had. + int32 evaluated_bounding_box_count = 1; + + // Output only. The bounding boxes match metrics for each + // Intersection-over-union threshold 0.05,0.10,...,0.95,0.96,0.97,0.98,0.99 + // and each label confidence threshold 0.05,0.10,...,0.95,0.96,0.97,0.98,0.99 + // pair. + repeated BoundingBoxMetricsEntry bounding_box_metrics_entries = 2; + + // Output only. The single metric for bounding boxes evaluation: + // the mean_average_precision averaged over all bounding_box_metrics_entries. + float bounding_box_mean_average_precision = 3; +} diff --git a/google/cloud/automl/v1beta1/geometry.proto b/google/cloud/automl/v1beta1/geometry.proto new file mode 100644 index 000000000..07f4e36f7 --- /dev/null +++ b/google/cloud/automl/v1beta1/geometry.proto @@ -0,0 +1,47 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A vertex represents a 2D point in the image. +// The normalized vertex coordinates are between 0 to 1 fractions relative to +// the original plane (image, video). E.g. if the plane (e.g. whole image) would +// have size 10 x 20 then a point with normalized coordinates (0.1, 0.3) would +// be at the position (1, 6) on that plane. +message NormalizedVertex { + // Required. Horizontal coordinate. + float x = 1; + + // Required. Vertical coordinate. + float y = 2; +} + +// A bounding polygon of a detected object on a plane. +// On output both vertices and normalized_vertices are provided. +// The polygon is formed by connecting vertices in the order they are listed. +message BoundingPoly { + // Output only . The bounding polygon normalized vertices. + repeated NormalizedVertex normalized_vertices = 2; +} diff --git a/google/cloud/automl/v1beta1/image.proto b/google/cloud/automl/v1beta1/image.proto new file mode 100644 index 000000000..116904712 --- /dev/null +++ b/google/cloud/automl/v1beta1/image.proto @@ -0,0 +1,131 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/classification.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "ImageProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Dataset metadata that is specific to image classification. +message ImageClassificationDatasetMetadata { + // Required. Type of the classification problem. + ClassificationType classification_type = 1; +} + +// Dataset metadata specific to image object detection. +message ImageObjectDetectionDatasetMetadata { + +} + +// Model metadata for image classification. +message ImageClassificationModelMetadata { + // Optional. The ID of the `base` model. If it is specified, the new model + // will be created based on the `base` model. Otherwise, the new model will be + // created from scratch. The `base` model must be in the same + // `project` and `location` as the new model to create, and have the same + // `model_type`. + string base_model_id = 1; + + // Required. The train budget of creating this model, expressed in hours. The + // actual `train_cost` will be equal or less than this value. + int64 train_budget = 2; + + // Output only. The actual train cost of creating this model, expressed in + // hours. If this model is created from a `base` model, the train cost used + // to create the `base` model are not included. + int64 train_cost = 3; + + // Output only. The reason that this create model operation stopped, + // e.g. `BUDGET_REACHED`, `MODEL_CONVERGED`. + string stop_reason = 5; + + // Optional. Type of the model. The available values are: + // * `cloud` - Model to be used via prediction calls to AutoML API. + // This is the default value. + // * `mobile-low-latency-1` - A model that, in addition to providing + // prediction via AutoML API, can also be exported (see + // [AutoMl.ExportModel][google.cloud.automl.v1beta1.AutoMl.ExportModel]) and used on a mobile or edge device + // with TensorFlow afterwards. Expected to have low latency, but + // may have lower prediction quality than other models. + // * `mobile-versatile-1` - A model that, in addition to providing + // prediction via AutoML API, can also be exported (see + // [AutoMl.ExportModel][google.cloud.automl.v1beta1.AutoMl.ExportModel]) and used on a mobile or edge device + // with TensorFlow afterwards. + // * `mobile-high-accuracy-1` - A model that, in addition to providing + // prediction via AutoML API, can also be exported (see + // [AutoMl.ExportModel][google.cloud.automl.v1beta1.AutoMl.ExportModel]) and used on a mobile or edge device + // with TensorFlow afterwards. Expected to have a higher + // latency, but should also have a higher prediction quality + // than other models. + // * `mobile-core-ml-low-latency-1` - A model that, in addition to providing + // prediction via AutoML API, can also be exported (see + // [AutoMl.ExportModel][google.cloud.automl.v1beta1.AutoMl.ExportModel]) and used on a mobile device with Core + // ML afterwards. Expected to have low latency, but may have + // lower prediction quality than other models. + // * `mobile-core-ml-versatile-1` - A model that, in addition to providing + // prediction via AutoML API, can also be exported (see + // [AutoMl.ExportModel][google.cloud.automl.v1beta1.AutoMl.ExportModel]) and used on a mobile device with Core + // ML afterwards. + // * `mobile-core-ml-high-accuracy-1` - A model that, in addition to + // providing prediction via AutoML API, can also be exported + // (see [AutoMl.ExportModel][google.cloud.automl.v1beta1.AutoMl.ExportModel]) and used on a mobile device with + // Core ML afterwards. Expected to have a higher latency, but + // should also have a higher prediction quality than other + // models. + string model_type = 7; +} + +// Model metadata specific to image object detection. +message ImageObjectDetectionModelMetadata { + // Optional. Type of the model. The available values are: + // * `cloud-high-accuracy-1` - (default) A model to be used via prediction + // calls to AutoML API. Expected to have a higher latency, but + // should also have a higher prediction quality than other + // models. + // * `cloud-low-latency-1` - A model to be used via prediction + // calls to AutoML API. Expected to have low latency, but may + // have lower prediction quality than other models. + string model_type = 1; + + // Output only. The number of nodes this model is deployed on. A node is an + // abstraction of a machine resource, which can handle online prediction QPS + // as given in the qps_per_node field. + int64 node_count = 3; + + // Output only. An approximate number of online prediction QPS that can + // be supported by this model per each node on which it is deployed. + double node_qps = 4; +} + +// Model deployment metadata specific to Image Object Detection. +message ImageObjectDetectionModelDeploymentMetadata { + // Input only. The number of nodes to deploy the model on. A node is an + // abstraction of a machine resource, which can handle online prediction QPS + // as given in the model's + // + // [qps_per_node][google.cloud.automl.v1beta1.ImageObjectDetectionModelMetadata.qps_per_node]. + // Must be between 1 and 100, inclusive on both ends. + int64 node_count = 1; +} diff --git a/google/cloud/automl/v1beta1/io.proto b/google/cloud/automl/v1beta1/io.proto new file mode 100644 index 000000000..08c5f5885 --- /dev/null +++ b/google/cloud/automl/v1beta1/io.proto @@ -0,0 +1,811 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Input configuration for ImportData Action. +// +// The format of input depends on dataset_metadata the Dataset into which +// the import is happening has. As input source the +// [gcs_source][google.cloud.automl.v1beta1.InputConfig.gcs_source] +// is expected, unless specified otherwise. If a file with identical content +// (even if it had different GCS_FILE_PATH) is mentioned multiple times , then +// its label, bounding boxes etc. are appended. The same file should be always +// provided with the same ML_USE and GCS_FILE_PATH, if it is not then +// these values are nondeterministically selected from the given ones. +// +// The formats are represented in EBNF with commas being literal and with +// non-terminal symbols defined near the end of this comment. The formats are: +// +// * For Image Object Detection: +// CSV file(s) with each line in format: +// ML_USE,GCS_FILE_PATH,LABEL,BOUNDING_BOX +// GCS_FILE_PATH leads to image of up to 30MB in size. Supported +// extensions: .JPEG, .GIF, .PNG. +// Each image is assumed to be exhaustively labeled. The +// minimum allowed BOUNDING_BOX edge length is 0.01, and no more than +// 500 BOUNDING_BOX-es per image are allowed. +// Three sample rows: +// TRAIN,gs://folder/image1.png,car,0.1,0.1,,,0.3,0.3,, +// TRAIN,gs://folder/image1.png,bike,.7,.6,,,.8,.9,, +// TEST,gs://folder/im2.png,car,0.1,0.1,0.2,0.1,0.2,0.3,0.1,0.3 +// +// +// * For Video Classification: +// CSV file(s) with each line in format: +// ML_USE,GCS_FILE_PATH +// where ML_USE VALIDATE value should not be used. The GCS_FILE_PATH +// should lead to another .csv file which describes examples that have +// given ML_USE, using the following row format: +// GCS_FILE_PATH,LABEL,TIME_SEGMENT_START,TIME_SEGMENT_END +// Here GCS_FILE_PATH leads to a video of up to 50GB in size and up +// to 3h duration. Supported extensions: .MOV, .MPEG4, .MP4, .AVI. +// TIME_SEGMENT_START and TIME_SEGMENT_END must be within the +// length of the video, and end has to be after the start. Any segment +// of a video which has one or more labels on it, is considered a +// hard negative for all other labels. Any segment with no labels on +// it is considered to be unknown. +// Sample top level CSV file: +// TRAIN,gs://folder/train_videos.csv +// TEST,gs://folder/test_videos.csv +// UNASSIGNED,gs://folder/other_videos.csv +// Three sample rows of a CSV file for a particular ML_USE: +// gs://folder/video1.avi,car,120,180.000021 +// gs://folder/video1.avi,bike,150,180.000021 +// gs://folder/vid2.avi,car,0,60.5 +// * For Text Extraction: +// CSV file(s) with each line in format: +// ML_USE,GCS_FILE_PATH +// GCS_FILE_PATH leads to a .JSONL (i.e. JSON Lines) file which either +// imports text in-line or as documents. +// The in-line .JSONL file contains, per line, a proto that wraps a +// TextSnippet proto (in json representation) followed by one or +// more AnnotationPayload protos (called annotations), which have +// display_name and text_extraction detail populated. +// Given text is expected to be annotated exhaustively, e.g. if you +// look for animals and text contains "dolphin" that is not labeled, +// then "dolphin" will be assumed to not be an animal. +// Any given text snippet content must have 30,000 characters or +// less, and also be UTF-8 NFC encoded (ASCII already is). +// The document .JSONL file contains, per line, a proto that wraps a +// Document proto with input_config set. Only PDF documents are +// supported now, and each document may be up to 2MB large. +// Currently annotations on documents cannot be specified at import. +// Any given .JSONL file must be 100MB or smaller. +// Three sample CSV rows: +// TRAIN,gs://folder/file1.jsonl +// VALIDATE,gs://folder/file2.jsonl +// TEST,gs://folder/file3.jsonl +// Sample in-line JSON Lines file (presented here with artificial line +// breaks, but the only actual line break is denoted by \n).: +// { +// "text_snippet": { +// "content": "dog car cat" +// }, +// "annotations": [ +// { +// "display_name": "animal", +// "text_extraction": { +// "text_segment": {"start_offset": 0, "end_offset": 2} +// } +// }, +// { +// "display_name": "vehicle", +// "text_extraction": { +// "text_segment": {"start_offset": 4, "end_offset": 6} +// } +// }, +// { +// "display_name": "animal", +// "text_extraction": { +// "text_segment": {"start_offset": 8, "end_offset": 10} +// } +// } +// ] +// }\n +// { +// "text_snippet": { +// "content": "This dog is good." +// }, +// "annotations": [ +// { +// "display_name": "animal", +// "text_extraction": { +// "text_segment": {"start_offset": 5, "end_offset": 7} +// } +// } +// ] +// } +// Sample document JSON Lines file (presented here with artificial line +// breaks, but the only actual line break is denoted by \n).: +// { +// "document": { +// "input_config": { +// "gcs_source": { "input_uris": [ "gs://folder/document1.pdf" ] +// } +// } +// } +// }\n +// { +// "document": { +// "input_config": { +// "gcs_source": { "input_uris": [ "gs://folder/document2.pdf" ] +// } +// } +// } +// } +// * For Tables: +// Either +// [gcs_source][google.cloud.automl.v1beta1.InputConfig.gcs_source] or +// +// [bigquery_source][google.cloud.automl.v1beta1.InputConfig.bigquery_source] +// can be used. All inputs will be concatenated into a single +// +// [primary_table][google.cloud.automl.v1beta1.TablesDatasetMetadata.primary_table_name] +// For gcs_source: +// CSV file(s), where first file must have a header containing unique +// column names, other files may have such header line too, and all +// other lines contain values for the header columns. Each line must +// have 1,000,000 or fewer characters. +// First three sample rows of a CSV file: +// "Id","First Name","Last Name","Dob","Addresses" +// +// "1","John","Doe","1968-01-22","[{"status":"current","address":"123_First_Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456_Main_Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]" +// +// "2","Jane","Doe","1980-10-16","[{"status":"current","address":"789_Any_Avenue","city":"Albany","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321_Main_Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]} +// For bigquery_source: +// An URI of a BigQuery table. +// An imported table must have between 2 and 1,000 columns, inclusive, +// and between 1,000 and 10,000,000 rows, inclusive. +// +// * For Text Sentiment: +// CSV file(s) with each line in format: +// ML_USE,TEXT_SNIPPET,SENTIMENT +// TEXT_SNIPPET must have up to 500 characters. +// Three sample rows: +// TRAIN,"@freewrytin God is way too good for Claritin",2 +// TRAIN,"I need Claritin so bad",3 +// TEST,"Thank god for Claritin.",4 +// +// Definitions: +// ML_USE = "TRAIN" | "VALIDATE" | "TEST" | "UNASSIGNED" +// Describes how the given example (file) should be used for model +// training. "UNASSIGNED" can be used when user has no preference. +// GCS_FILE_PATH = A path to file on GCS, e.g. "gs://folder/image1.png". +// LABEL = A display name of an object on an image, video etc., e.g. "dog". +// Must be up to 32 characters long and can consist only of ASCII +// Latin letters A-Z and a-z, underscores(_), and ASCII digits 0-9. +// For each label an AnnotationSpec is created which display_name +// becomes the label; AnnotationSpecs are given back in predictions. +// INSTANCE_ID = A positive integer that identifies a specific instance of a +// labeled entity on an example. Used e.g. to track two cars on +// a video while being able to tell apart which one is which. +// BOUNDING_BOX = VERTEX,VERTEX,VERTEX,VERTEX | VERTEX,,,VERTEX,, +// A rectangle parallel to the frame of the example (image, +// video). If 4 vertices are given they are connected by edges +// in the order provided, if 2 are given they are recognized +// as diagonally opposite vertices of the rectangle. +// VERTEX = COORDINATE,COORDINATE +// First coordinate is horizontal (x), the second is vertical (y). +// COORDINATE = A float in 0 to 1 range, relative to total length of +// image or video in given dimension. For fractions the +// leading non-decimal 0 can be omitted (i.e. 0.3 = .3). +// Point 0,0 is in top left. +// TIME_SEGMENT_START = TIME_OFFSET +// Expresses a beginning, inclusive, of a time segment +// within an example that has a time dimension +// (e.g. video). +// TIME_SEGMENT_END = TIME_OFFSET +// Expresses an end, exclusive, of a time segment within +// an example that has a time dimension (e.g. video). +// TIME_OFFSET = A number of seconds as measured from the start of an +// example (e.g. video). Fractions are allowed, up to a +// microsecond precision. "inf" is allowed, and it means the end +// of the example. +// TEXT_SNIPPET = A content of a text snippet, UTF-8 encoded. +// SENTIMENT = An integer between 0 and +// Dataset.text_sentiment_dataset_metadata.sentiment_max +// (inclusive). Describes the ordinal of the sentiment - higher +// value means a more positive sentiment. All the values are +// completely relative, i.e. neither 0 needs to mean a negative or +// neutral sentiment nor sentiment_max needs to mean a positive one +// - it is just required that 0 is the least positive sentiment +// in the data, and sentiment_max is the most positive one. +// The SENTIMENT shouldn't be confused with "score" or "magnitude" +// from the previous Natural Language Sentiment Analysis API. +// All SENTIMENT values between 0 and sentiment_max must be +// represented in the imported data. On prediction the same 0 to +// sentiment_max range will be used. The difference between +// neighboring sentiment values needs not to be uniform, e.g. 1 and +// 2 may be similar whereas the difference between 2 and 3 may be +// huge. +// +// Errors: +// If any of the provided CSV files can't be parsed or if more than certain +// percent of CSV rows cannot be processed then the operation fails and +// nothing is imported. Regardless of overall success or failure the per-row +// failures, up to a certain count cap, will be listed in +// Operation.metadata.partial_failures. +// +message InputConfig { + // Required. The source of the input. + oneof source { + // The Google Cloud Storage location for the input content. + GcsSource gcs_source = 1; + + // The BigQuery location for the input content. + BigQuerySource bigquery_source = 3; + } + + // Additional domain-specific parameters describing the semantic of the + // imported data, any string must be up to 25000 + // characters long. + // + // * For Tables: + // `schema_inference_version` - (integer) Required. The version of the + // algorithm that should be used for the initial inference of the + // schema (columns' DataTypes) of the table the data is being imported + // into. Allowed values: "1". + map<string, string> params = 2; +} + +// Input configuration for BatchPredict Action. +// +// The format of input depends on the ML problem of the model used for +// prediction. As input source the +// [gcs_source][google.cloud.automl.v1beta1.InputConfig.gcs_source] +// is expected, unless specified otherwise. +// +// The formats are represented in EBNF with commas being literal and with +// non-terminal symbols defined near the end of this comment. The formats are: +// +// * For Video Classification: +// CSV file(s) with each line in format: +// GCS_FILE_PATH,TIME_SEGMENT_START,TIME_SEGMENT_END +// GCS_FILE_PATH leads to video of up to 50GB in size and up to 3h +// duration. Supported extensions: .MOV, .MPEG4, .MP4, .AVI. +// TIME_SEGMENT_START and TIME_SEGMENT_END must be within the +// length of the video, and end has to be after the start. +// Three sample rows: +// gs://folder/video1.mp4,10,40 +// gs://folder/video1.mp4,20,60 +// gs://folder/vid2.mov,0,inf +// +// * For Text Extraction +// .JSONL (i.e. JSON Lines) file(s) which either provide text in-line or +// as documents (for a single BatchPredict call only one of the these +// formats may be used). +// The in-line .JSONL file(s) contain per line a proto that +// wraps a temporary user-assigned TextSnippet ID (string up to 2000 +// characters long) called "id" followed by a TextSnippet proto (in +// json representation). Any given text snippet content must have +// 30,000 characters or less, and also be UTF-8 NFC encoded (ASCII +// already is). The IDs provided should be unique. +// The document .JSONL file(s) contain, per line, a proto that wraps a +// Document proto with input_config set. Only PDF documents are +// supported now, and each document must be up to 2MB large. +// Any given .JSONL file must be 100MB or smaller, and no more than 20 +// files may be given. +// Sample in-line JSON Lines file (presented here with artificial line +// breaks, but the only actual line break is denoted by \n): +// { +// "id": "my_first_id", +// "text_snippet": { "content": "dog car cat"} +// }\n +// { +// "id": "2", +// "text_snippet": { +// "content": "An elaborate content", +// "mime_type": "text/plain" +// } +// } +// Sample document JSON Lines file (presented here with artificial line +// breaks, but the only actual line break is denoted by \n).: +// { +// "document": { +// "input_config": { +// "gcs_source": { "input_uris": [ "gs://folder/document1.pdf" ] +// } +// } +// } +// }\n +// { +// "document": { +// "input_config": { +// "gcs_source": { "input_uris": [ "gs://folder/document2.pdf" ] +// } +// } +// } +// } +// +// * For Tables: +// Either +// [gcs_source][google.cloud.automl.v1beta1.InputConfig.gcs_source] or +// +// [bigquery_source][google.cloud.automl.v1beta1.InputConfig.bigquery_source]. +// For gcs_source: +// CSV file(s), where first file must have a header containing +// column names, other files may have such header line too, and all +// other lines contain values for the header columns. The column +// names must be exactly same (order may differ) as the model's +// +// [input_feature_column_specs'][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] +// [display_names][google.cloud.automl.v1beta1.display_name], with +// values compatible with these column specs data types. +// Prediction on all the rows, i.e. the CSV lines, will be +// attempted. +// Each line must have 1,000,000 or fewer characters. +// First three sample rows of a CSV file: +// "First Name","Last Name","Dob","Addresses" +// +// "John","Doe","1968-01-22","[{"status":"current","address":"123_First_Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456_Main_Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]" +// +// "Jane","Doe","1980-10-16","[{"status":"current","address":"789_Any_Avenue","city":"Albany","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321_Main_Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]} +// For bigquery_source: +// An URI of a BigQuery table. The table's columns must be exactly +// same (order may differ) as all model's +// +// [input_feature_column_specs'][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] +// [display_names][google.cloud.automl.v1beta1.display_name], with +// data compatible with these colum specs data types. +// Prediction on all the rows of the table will be attempted. +// +// Definitions: +// GCS_FILE_PATH = A path to file on GCS, e.g. "gs://folder/video.avi". +// TIME_SEGMENT_START = TIME_OFFSET +// Expresses a beginning, inclusive, of a time segment +// within an +// example that has a time dimension (e.g. video). +// TIME_SEGMENT_END = TIME_OFFSET +// Expresses an end, exclusive, of a time segment within +// an example that has a time dimension (e.g. video). +// TIME_OFFSET = A number of seconds as measured from the start of an +// example (e.g. video). Fractions are allowed, up to a +// microsecond precision. "inf" is allowed and it means the end +// of the example. +// +// Errors: +// If any of the provided CSV files can't be parsed or if more than certain +// percent of CSV rows cannot be processed then the operation fails and +// prediction does not happen. Regardless of overall success or failure the +// per-row failures, up to a certain count cap, will be listed in +// Operation.metadata.partial_failures. +// +message BatchPredictInputConfig { + // Required. The source of the input. + oneof source { + // The Google Cloud Storage location for the input content. + GcsSource gcs_source = 1; + + // The BigQuery location for the input content. + BigQuerySource bigquery_source = 2; + } +} + +// Input configuration of a [Document][google.cloud.automl.v1beta1.Document]. +message DocumentInputConfig { + // The Google Cloud Storage location of the document file. Only a single path + // should be given. + // Max supported size: 512MB. + // Supported extensions: .PDF. + GcsSource gcs_source = 1; +} + +// Output configuration for ExportData. +// +// As destination the +// [gcs_destination][google.cloud.automl.v1beta1.OutputConfig.gcs_destination] +// must be set unless specified otherwise for a domain. +// Only ground truth annotations are exported (not approved annotations are +// not exported). +// +// The outputs correspond to how the data was imported, and may be used as +// input to import data. The output formats are represented as EBNF with literal +// commas and same non-terminal symbols definitions are these in import data's +// [InputConfig][google.cloud.automl.v1beta1.InputConfig]: +// +// * For Image Object Detection: +// CSV file(s) `image_object_detection_1.csv`, +// `image_object_detection_2.csv`,...,`image_object_detection_N.csv` +// with each line in format: +// ML_USE,GCS_FILE_PATH,LABEL,BOUNDING_BOX +// where GCS_FILE_PATHs point at the original, source locations of the +// imported images. +// +// * For Video Classification: +// CSV file `video_classification.csv`, with each line in format: +// ML_USE,GCS_FILE_PATH +// (may have muliple lines per a single ML_USE). +// Each GCS_FILE_PATH leads to another .csv file which +// describes examples that have given ML_USE, using the following +// row format: +// GCS_FILE_PATH,LABEL,TIME_SEGMENT_START,TIME_SEGMENT_END +// Here GCS_FILE_PATHs point at the original, source locations of the +// imported videos. +// * For Text Extraction: +// CSV file `text_extraction.csv`, with each line in format: +// ML_USE,GCS_FILE_PATH +// GCS_FILE_PATH leads to a .JSONL (i.e. JSON Lines) file which +// contains, per line, a proto that wraps a TextSnippet proto (in json +// representation) followed by AnnotationPayload protos (called +// annotations). If initially documents had been imported, corresponding +// OCR-ed representation is returned. +// +// * For Tables: +// Output depends on whether the dataset was imported from GCS or +// BigQuery. +// GCS case: +// +// [gcs_destination][google.cloud.automl.v1beta1.OutputConfig.gcs_destination] +// must be set. Exported are CSV file(s) `tables_1.csv`, +// `tables_2.csv`,...,`tables_N.csv` with each having as header line +// the table's column names, and all other lines contain values for +// the header columns. +// BigQuery case: +// +// [bigquery_destination][google.cloud.automl.v1beta1.OutputConfig.bigquery_destination] +// pointing to a BigQuery project must be set. In the given project a +// new dataset will be created with name +// +// `export_data_<automl-dataset-display-name>_<timestamp-of-export-call>` +// where <automl-dataset-display-name> will be made +// BigQuery-dataset-name compatible (e.g. most special characters will +// become underscores), and timestamp will be in +// YYYY_MM_DDThh_mm_ss_sssZ "based on ISO-8601" format. In that +// dataset a new table called `primary_table` will be created, and +// filled with precisely the same data as this obtained on import. +message OutputConfig { + // Required. The destination of the output. + oneof destination { + // The Google Cloud Storage location where the output is to be written to. + // For Image Object Detection, Text Extraction, Video Classification and + // Tables, in the given directory a new directory will be created with name: + // export_data-<dataset-display-name>-<timestamp-of-export-call> + // where timestamp is in YYYY-MM-DDThh:mm:ss.sssZ ISO-8601 format. All + // export output will be written into that directory. + GcsDestination gcs_destination = 1; + + // The BigQuery location where the output is to be written to. + BigQueryDestination bigquery_destination = 2; + } +} + +// Output configuration for BatchPredict Action. +// +// As destination the +// +// [gcs_destination][google.cloud.automl.v1beta1.BatchPredictOutputConfig.gcs_destination] +// must be set unless specified otherwise for a domain. If gcs_destination is +// set then in the given directory a new directory will be created. Its name +// will be +// "prediction-<model-display-name>-<timestamp-of-prediction-call>", +// where timestamp is in YYYY-MM-DDThh:mm:ss.sssZ ISO-8601 format. The contents +// of it depend on the ML problem the predictions are made for. +// +// * For Video Classification: +// In the created directory a video_classification.csv file, and a .JSON +// file per each video classification requested in the input (i.e. each +// line in given CSV(s)), will be created. +// +// The format of video_classification.csv is: +// +// GCS_FILE_PATH,TIME_SEGMENT_START,TIME_SEGMENT_END,JSON_FILE_NAME,STATUS +// where: +// GCS_FILE_PATH,TIME_SEGMENT_START,TIME_SEGMENT_END = matches 1 to 1 +// the prediction input lines (i.e. video_classification.csv has +// precisely the same number of lines as the prediction input had.) +// JSON_FILE_NAME = Name of .JSON file in the output directory, which +// contains prediction responses for the video time segment. +// STATUS = "OK" if prediction completed successfully, or an error +// code and,or message otherwise. If STATUS is not "OK" then the +// .JSON file for that line may not exist or be empty. +// +// Each .JSON file, assuming STATUS is "OK", will contain a list of +// AnnotationPayload protos in JSON format, which are the predictions +// for the video time segment the file is assigned to in the +// video_classification.csv. All AnnotationPayload protos will have +// video_classification field set, and will be sorted by +// video_classification.type field (note that the returned types are +// governed by `classifaction_types` parameter in +// [PredictService.BatchPredictRequest.params][]). +// * For Text Extraction: +// In the created directory files `text_extraction_1.jsonl`, +// `text_extraction_2.jsonl`,...,`text_extraction_N.jsonl` +// will be created, where N may be 1, and depends on the +// total number of inputs and annotations found. +// The contents of these .JSONL file(s) depend on whether the input +// used inline text, or documents. +// If input was inline, then each .JSONL file will contain, per line, +// a JSON representation of a proto that wraps given in request text +// snippet's "id" : "<id_value>" followed by a list of zero or more +// AnnotationPayload protos (called annotations), which have +// text_extraction detail populated. A single text snippet will be +// listed only once with all its annotations, and its annotations will +// never be split across files. +// If input used documents, then each .JSONL file will contain, per +// line, a JSON representation of a proto that wraps given in request +// document proto, followed by its OCR-ed representation in the form +// of a text snippet, finally followed by a list of zero or more +// AnnotationPayload protos (called annotations), which have +// text_extraction detail populated and refer, via their indices, to +// the OCR-ed text snippet. A single document (and its text snippet) +// will be listed only once with all its annotations, and its +// annotations will never be split across files. +// If prediction for any text snippet failed (partially or completely), +// then additional `errors_1.jsonl`, `errors_2.jsonl`,..., +// `errors_N.jsonl` files will be created (N depends on total number of +// failed predictions). These files will have a JSON representation of a +// proto that wraps either the "id" : "<id_value>" (in case of inline) +// or the document proto (in case of document) but here followed by +// exactly one +// +// [`google.rpc.Status`](https: +// //github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) +// containing only `code` and `message`. +// +// * For Tables: +// Output depends on whether +// +// [gcs_destination][google.cloud.automl.v1beta1.BatchPredictOutputConfig.gcs_destination] +// or +// +// [bigquery_destination][google.cloud.automl.v1beta1.BatchPredictOutputConfig.bigquery_destination] +// is set (either is allowed). +// GCS case: +// In the created directory files `tables_1.csv`, `tables_2.csv`,..., +// `tables_N.csv` will be created, where N may be 1, and depends on +// the total number of the successfully predicted rows. +// For the classification models: +// Each .csv file will contain a header, listing all model's +// +// [input_feature_column_specs'][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] +// +// [display_names][google.cloud.automl.v1beta1.ColumnSpec.display_name] +// followed by M target column names in the format of +// +// "<[target_column_specs][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec] +// +// [display_name][google.cloud.automl.v1beta1.ColumnSpec.display_name]>_<target +// value>_score" where M is the number of distinct target values, +// i.e. number of distinct values in the target column of the table +// used to train the model. Subsequent lines will contain the +// respective values of successfully predicted rows, with the last, +// i.e. the target, columns having the corresponding prediction +// [scores][google.cloud.automl.v1beta1.TablesAnnotation.score]. +// For the regression models: +// Each .csv file will contain a header, listing all model's +// +// [input_feature_column_specs][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] +// [display_names][google.cloud.automl.v1beta1.display_name] +// followed by the target column with name equal to +// +// [target_column_specs'][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec] +// +// [display_name][google.cloud.automl.v1beta1.ColumnSpec.display_name]. +// Subsequent lines will contain the respective values of +// successfully predicted rows, with the last, i.e. the target, +// column having the predicted target value. +// If prediction for any rows failed, then an additional +// `errors_1.csv`, `errors_2.csv`,..., `errors_N.csv` will be created +// (N depends on total number of failed rows). These files will have +// analogous format as `tables_*.csv`, but always with a single target +// column having +// +// [`google.rpc.Status`](https: +// //github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) +// represented as a JSON string, and containing only `code` and +// `message`. +// BigQuery case: +// +// [bigquery_destination][google.cloud.automl.v1beta1.OutputConfig.bigquery_destination] +// pointing to a BigQuery project must be set. In the given project a +// new dataset will be created with name +// `prediction_<model-display-name>_<timestamp-of-prediction-call>` +// where <model-display-name> will be made +// BigQuery-dataset-name compatible (e.g. most special characters will +// become underscores), and timestamp will be in +// YYYY_MM_DDThh_mm_ss_sssZ "based on ISO-8601" format. In the dataset +// two tables will be created, `predictions`, and `errors`. +// The `predictions` table's column names will be the +// +// [input_feature_column_specs'][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] +// +// [display_names][google.cloud.automl.v1beta1.ColumnSpec.display_name] +// followed by model's +// +// [target_column_specs'][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec] +// +// [display_name][google.cloud.automl.v1beta1.ColumnSpec.display_name]. +// The input feature columns will contain the respective values of +// successfully predicted rows, with the target column having an +// ARRAY of +// +// [AnnotationPayloads][google.cloud.automl.v1beta1.AnnotationPayload], +// represented as STRUCT-s, containing +// [TablesAnnotation][google.cloud.automl.v1beta1.TablesAnnotation]. +// The `errors` table contains rows for which the prediction has +// failed, it has analogous input feature and target columns, but +// here the target column as a value has +// +// [`google.rpc.Status`](https: +// //github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) +// represented as a STRUCT, and containing only `code` and `message`. +message BatchPredictOutputConfig { + // Required. The destination of the output. + oneof destination { + // The Google Cloud Storage location of the directory where the output is to + // be written to. + GcsDestination gcs_destination = 1; + + // The BigQuery location where the output is to be written to. + BigQueryDestination bigquery_destination = 2; + } +} + +// Output configuration for ModelExport Action. +message ModelExportOutputConfig { + // Required. The destination of the output. + oneof destination { + // The Google Cloud Storage location where the model is to be written to. + // This location may only be set for the following model formats: + // "tflite", "edgetpu_tflite", "core_ml", "docker". + // + // Under the directory given as the destination a new one with name + // "model-export-<model-display-name>-<timestamp-of-export-call>", + // where timestamp is in YYYY-MM-DDThh:mm:ss.sssZ ISO-8601 format, + // will be created. Inside the model and any of its supporting files + // will be written. + GcsDestination gcs_destination = 1; + + // The GCR location where model image is to be pushed to. This location + // may only be set for the following model formats: + // "docker". + // + // The model image will be created under the given URI. + GcrDestination gcr_destination = 3; + } + + // The format in which the model must be exported. The available, and default, + // formats depend on the problem and model type (if given problem and type + // combination doesn't have a format listed, it means its models are not + // exportable): + // + // * For Image Classification mobile-low-latency-1, mobile-versatile-1, + // mobile-high-accuracy-1: + // "tflite" (default), "edgetpu_tflite", "tf_saved_model", "docker". + // + // * For Image Classification mobile-core-ml-low-latency-1, + // mobile-core-ml-versatile-1, mobile-core-ml-high-accuracy-1: + // "core_ml" (default). + // Formats description: + // + // * tflite - Used for Android mobile devices. + // * edgetpu_tflite - Used for [Edge TPU](https://cloud.google.com/edge-tpu/) + // devices. + // * tf_saved_model - A tensorflow model in SavedModel format. + // * docker - Used for Docker containers. Use the params field to customize + // the container. The container is verified to work correctly on + // ubuntu 16.04 operating system. + // * core_ml - Used for iOS mobile devices. + string model_format = 4; + + // Additional model-type and format specific parameters describing the + // requirements for the to be exported model files, any string must be up to + // 25000 characters long. + // + // * For `docker` format: + // `cpu_architecture` - (string) "x86_64" (default). + // `gpu_architecture` - (string) "none" (default), "nvidia". + map<string, string> params = 2; +} + +// Output configuration for ExportEvaluatedExamples Action. Note that this call +// is available only for 30 days since the moment the model was evaluated. +// The output depends on the domain, as follows (note that only examples from +// the TEST set are exported): +// +// * For Tables: +// +// [bigquery_destination][google.cloud.automl.v1beta1.OutputConfig.bigquery_destination] +// pointing to a BigQuery project must be set. In the given project a +// new dataset will be created with name +// +// `export_evaluated_examples_<model-display-name>_<timestamp-of-export-call>` +// where <model-display-name> will be made BigQuery-dataset-name +// compatible (e.g. most special characters will become underscores), +// and timestamp will be in YYYY_MM_DDThh_mm_ss_sssZ "based on ISO-8601" +// format. In the dataset an `evaluated_examples` table will be +// created. It will have all the same columns as the +// [primary +// +// table][google.cloud.automl.v1beta1.TablesDatasetMetadata.primary_table_spec_id] +// of the +// [dataset][google.cloud.automl.v1beta1.Model.dataset_id] from which +// the model was created, as they were at the moment of model's +// evaluation (this includes the target column with its ground +// truth), followed by a column called "predicted_<target_column>". That +// last column will contain the model's prediction result for each +// respective row, given as ARRAY of +// [AnnotationPayloads][google.cloud.automl.v1beta1.AnnotationPayload], +// represented as STRUCT-s, containing +// [TablesAnnotation][google.cloud.automl.v1beta1.TablesAnnotation]. +message ExportEvaluatedExamplesOutputConfig { + // Required. The destination of the output. + oneof destination { + // The BigQuery location where the output is to be written to. + BigQueryDestination bigquery_destination = 2; + } +} + +// The Google Cloud Storage location for the input content. +message GcsSource { + // Required. Google Cloud Storage URIs to input files, up to 2000 characters + // long. Accepted forms: + // * Full object path, e.g. gs://bucket/directory/object.csv + repeated string input_uris = 1; +} + +// The BigQuery location for the input content. +message BigQuerySource { + // Required. BigQuery URI to a table, up to 2000 characters long. + // Accepted forms: + // * BigQuery path e.g. bq://projectId.bqDatasetId.bqTableId + string input_uri = 1; +} + +// The Google Cloud Storage location where the output is to be written to. +message GcsDestination { + // Required. Google Cloud Storage URI to output directory, up to 2000 + // characters long. + // Accepted forms: + // * Prefix path: gs://bucket/directory + // The requesting user must have write permission to the bucket. + // The directory is created if it doesn't exist. + string output_uri_prefix = 1; +} + +// The BigQuery location for the output content. +message BigQueryDestination { + // Required. BigQuery URI to a project, up to 2000 characters long. + // Accepted forms: + // * BigQuery path e.g. bq://projectId + string output_uri = 1; +} + +// The GCR location where the image must be pushed to. +message GcrDestination { + // Required. Google Contained Registry URI of the new image, up to 2000 + // characters long. See + // + // https: + // //cloud.google.com/container-registry/do + // // cs/pushing-and-pulling#pushing_an_image_to_a_registry + // Accepted forms: + // * [HOSTNAME]/[PROJECT-ID]/[IMAGE] + // * [HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG] + // + // The requesting user must have permission to push images the project. + string output_uri = 1; +} diff --git a/google/cloud/automl/v1beta1/model.proto b/google/cloud/automl/v1beta1/model.proto new file mode 100644 index 000000000..42254c36f --- /dev/null +++ b/google/cloud/automl/v1beta1/model.proto @@ -0,0 +1,104 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/image.proto"; +import "google/cloud/automl/v1beta1/tables.proto"; +import "google/cloud/automl/v1beta1/text.proto"; +import "google/cloud/automl/v1beta1/translation.proto"; +import "google/cloud/automl/v1beta1/video.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// API proto representing a trained machine learning model. +message Model { + // Deployment state of the model. + enum DeploymentState { + // Should not be used, an un-set enum has this value by default. + DEPLOYMENT_STATE_UNSPECIFIED = 0; + + // Model is deployed. + DEPLOYED = 1; + + // Model is not deployed. + UNDEPLOYED = 2; + } + + // Required. + // The model metadata that is specific to the problem type. + // Must match the metadata type of the dataset used to train the model. + oneof model_metadata { + // Metadata for translation models. + TranslationModelMetadata translation_model_metadata = 15; + + // Metadata for image classification models. + ImageClassificationModelMetadata image_classification_model_metadata = 13; + + // Metadata for text classification models. + TextClassificationModelMetadata text_classification_model_metadata = 14; + + // Metadata for image object detection models. + ImageObjectDetectionModelMetadata image_object_detection_model_metadata = 20; + + // Metadata for video classification models. + VideoClassificationModelMetadata video_classification_model_metadata = 23; + + // Metadata for text extraction models. + TextExtractionModelMetadata text_extraction_model_metadata = 19; + + // Metadata for Tables models. + TablesModelMetadata tables_model_metadata = 24; + + // Metadata for text sentiment models. + TextSentimentModelMetadata text_sentiment_model_metadata = 22; + } + + // Output only. + // Resource name of the model. + // Format: `projects/{project_id}/locations/{location_id}/models/{model_id}` + string name = 1; + + // Required. The name of the model to show in the interface. The name can be + // up to 32 characters long and can consist only of ASCII Latin letters A-Z + // and a-z, underscores + // (_), and ASCII digits 0-9. It must start with a letter. + string display_name = 2; + + // Required. + // The resource ID of the dataset used to create the model. The dataset must + // come from the same ancestor project and location. + string dataset_id = 3; + + // Output only. + // Timestamp when this model was created. + google.protobuf.Timestamp create_time = 7; + + // Output only. + // Timestamp when this model was last updated. + google.protobuf.Timestamp update_time = 11; + + // Output only. Deployment state of the model. A model can only serve + // prediction requests after it gets deployed. + DeploymentState deployment_state = 8; +} diff --git a/google/cloud/automl/v1beta1/model_evaluation.proto b/google/cloud/automl/v1beta1/model_evaluation.proto new file mode 100644 index 000000000..1074d25be --- /dev/null +++ b/google/cloud/automl/v1beta1/model_evaluation.proto @@ -0,0 +1,105 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/classification.proto"; +import "google/cloud/automl/v1beta1/detection.proto"; +import "google/cloud/automl/v1beta1/regression.proto"; +import "google/cloud/automl/v1beta1/tables.proto"; +import "google/cloud/automl/v1beta1/text_extraction.proto"; +import "google/cloud/automl/v1beta1/text_sentiment.proto"; +import "google/cloud/automl/v1beta1/translation.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Evaluation results of a model. +message ModelEvaluation { + // Output only. Problem type specific evaluation metrics. + oneof metrics { + // Model evaluation metrics for image, text, video and tables + // classification. + // Tables problem is considered a classification when the target column + // has either CATEGORY or ARRAY(CATEGORY) DataType. + ClassificationEvaluationMetrics classification_evaluation_metrics = 8; + + // Model evaluation metrics for Tables regression. + // Tables problem is considered a regression when the target column + // has FLOAT64 DataType. + RegressionEvaluationMetrics regression_evaluation_metrics = 24; + + // Model evaluation metrics for translation. + TranslationEvaluationMetrics translation_evaluation_metrics = 9; + + // Model evaluation metrics for image object detection. + ImageObjectDetectionEvaluationMetrics image_object_detection_evaluation_metrics = 12; + + // Evaluation metrics for text sentiment models. + TextSentimentEvaluationMetrics text_sentiment_evaluation_metrics = 11; + + // Evaluation metrics for text extraction models. + TextExtractionEvaluationMetrics text_extraction_evaluation_metrics = 13; + } + + // Output only. + // Resource name of the model evaluation. + // Format: + // + // `projects/{project_id}/locations/{location_id}/models/{model_id}/modelEvaluations/{model_evaluation_id}` + string name = 1; + + // Output only. + // The ID of the annotation spec that the model evaluation applies to. The + // The ID is empty for the overall model evaluation. + // For Tables classification these are the distinct values of the target + // column at the moment of the evaluation; for this problem annotation specs + // in the dataset do not exist. + // NOTE: Currently there is no way to obtain the display_name of the + // annotation spec from its ID. To see the display_names, review the model + // evaluations in the UI. + string annotation_spec_id = 2; + + // Output only. The value of [AnnotationSpec.display_name][google.cloud.automl.v1beta1.AnnotationSpec.display_name] when the model + // was trained. Because this field returns a value at model training time, + // for different models trained using the same dataset, the returned value + // could be different as model owner could update the display_name between + // any two model training. + // The display_name is empty for the overall model evaluation. + string display_name = 15; + + // Output only. + // Timestamp when this model evaluation was created. + google.protobuf.Timestamp create_time = 5; + + // Output only. + // The number of examples used for model evaluation, i.e. for + // which ground truth from time of model creation is compared against the + // predicted annotations created by the model. + // For overall ModelEvaluation (i.e. with annotation_spec_id not set) this is + // the total number of all examples used for evaluation. + // Otherwise, this is the count of examples that according to the ground + // truth were annotated by the + // + // [annotation_spec_id][google.cloud.automl.v1beta1.ModelEvaluation.annotation_spec_id]. + int32 evaluated_example_count = 6; +} diff --git a/google/cloud/automl/v1beta1/operations.proto b/google/cloud/automl/v1beta1/operations.proto new file mode 100644 index 000000000..f075336be --- /dev/null +++ b/google/cloud/automl/v1beta1/operations.proto @@ -0,0 +1,190 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/io.proto"; +import "google/cloud/automl/v1beta1/model.proto"; +import "google/cloud/automl/v1beta1/model_evaluation.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Metadata used across all long running operations returned by AutoML API. +message OperationMetadata { + // Ouptut only. Details of specific operation. Even if this field is empty, + // the presence allows to distinguish different types of operations. + oneof details { + // Details of a Delete operation. + DeleteOperationMetadata delete_details = 8; + + // Details of a DeployModel operation. + DeployModelOperationMetadata deploy_model_details = 24; + + // Details of an UndeployModel operation. + UndeployModelOperationMetadata undeploy_model_details = 25; + + // Details of CreateModel operation. + CreateModelOperationMetadata create_model_details = 10; + + // Details of ImportData operation. + ImportDataOperationMetadata import_data_details = 15; + + // Details of BatchPredict operation. + BatchPredictOperationMetadata batch_predict_details = 16; + + // Details of ExportData operation. + ExportDataOperationMetadata export_data_details = 21; + + // Details of ExportModel operation. + ExportModelOperationMetadata export_model_details = 22; + + // Details of ExportEvaluatedExamples operation. + ExportEvaluatedExamplesOperationMetadata export_evaluated_examples_details = 26; + } + + // Output only. Progress of operation. Range: [0, 100]. + // Not used currently. + int32 progress_percent = 13; + + // Output only. Partial failures encountered. + // E.g. single files that couldn't be read. + // This field should never exceed 20 entries. + // Status details field will contain standard GCP error details. + repeated google.rpc.Status partial_failures = 2; + + // Output only. Time when the operation was created. + google.protobuf.Timestamp create_time = 3; + + // Output only. Time when the operation was updated for the last time. + google.protobuf.Timestamp update_time = 4; +} + +// Details of operations that perform deletes of any entities. +message DeleteOperationMetadata { + +} + +// Details of DeployModel operation. +message DeployModelOperationMetadata { + +} + +// Details of UndeployModel operation. +message UndeployModelOperationMetadata { + +} + +// Details of CreateModel operation. +message CreateModelOperationMetadata { + +} + +// Details of ImportData operation. +message ImportDataOperationMetadata { + +} + +// Details of ExportData operation. +message ExportDataOperationMetadata { + // Further describes this export data's output. + // Supplements + // [OutputConfig][google.cloud.automl.v1beta1.OutputConfig]. + message ExportDataOutputInfo { + // The output location to which the exported data is written. + oneof output_location { + // The full path of the Google Cloud Storage directory created, into which + // the exported data is written. + string gcs_output_directory = 1; + + // The path of the BigQuery dataset created, in bq://projectId.bqDatasetId + // format, into which the exported data is written. + string bigquery_output_dataset = 2; + } + } + + // Output only. Information further describing this export data's output. + ExportDataOutputInfo output_info = 1; +} + +// Details of BatchPredict operation. +message BatchPredictOperationMetadata { + // Further describes this batch predict's output. + // Supplements + // + // [BatchPredictionOutputConfig][google.cloud.automl.v1beta1.BatchPredictionOutputConfig]. + message BatchPredictOutputInfo { + // The output location into which prediction output is written. + oneof output_location { + // The full path of the Google Cloud Storage directory created, into which + // the prediction output is written. + string gcs_output_directory = 1; + + // The path of the BigQuery dataset created, in bq://projectId.bqDatasetId + // format, into which the prediction output is written. + string bigquery_output_dataset = 2; + } + } + + // Output only. The input config that was given upon starting this + // batch predict operation. + BatchPredictInputConfig input_config = 1; + + // Output only. Information further describing this batch predict's output. + BatchPredictOutputInfo output_info = 2; +} + +// Details of ExportModel operation. +message ExportModelOperationMetadata { + // Further describes the output of model export. + // Supplements + // + // [ModelExportOutputConfig][google.cloud.automl.v1beta1.ModelExportOutputConfig]. + message ExportModelOutputInfo { + // The full path of the Google Cloud Storage directory created, into which + // the model will be exported. + string gcs_output_directory = 1; + } + + // Output only. Information further describing the output of this model + // export. + ExportModelOutputInfo output_info = 2; +} + +// Details of EvaluatedExamples operation. +message ExportEvaluatedExamplesOperationMetadata { + // Further describes the output of the evaluated examples export. + // Supplements + // + // [ExportEvaluatedExamplesOutputConfig][google.cloud.automl.v1beta1.ExportEvaluatedExamplesOutputConfig]. + message ExportEvaluatedExamplesOutputInfo { + // The path of the BigQuery dataset created, in bq://projectId.bqDatasetId + // format, into which the output of export evaluated examples is written. + string bigquery_output_dataset = 2; + } + + // Output only. Information further describing the output of this evaluated + // examples export. + ExportEvaluatedExamplesOutputInfo output_info = 2; +} diff --git a/google/cloud/automl/v1beta1/prediction_service.proto b/google/cloud/automl/v1beta1/prediction_service.proto new file mode 100644 index 000000000..e63fe920f --- /dev/null +++ b/google/cloud/automl/v1beta1/prediction_service.proto @@ -0,0 +1,179 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/annotation_payload.proto"; +import "google/cloud/automl/v1beta1/data_items.proto"; +import "google/cloud/automl/v1beta1/io.proto"; +import "google/cloud/automl/v1beta1/operations.proto"; +import "google/longrunning/operations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "PredictionServiceProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// AutoML Prediction API. +// +// On any input that is documented to expect a string parameter in +// snake_case or kebab-case, either of those cases is accepted. +service PredictionService { + // Perform an online prediction. The prediction result will be directly + // returned in the response. + // Available for following ML problems, and their expected request payloads: + // * Image Classification - Image in .JPEG, .GIF or .PNG format, image_bytes + // up to 30MB. + // * Image Object Detection - Image in .JPEG, .GIF or .PNG format, image_bytes + // up to 30MB. + // * Text Classification - TextSnippet, content up to 10,000 characters, + // UTF-8 encoded. + // * Text Extraction - TextSnippet, content up to 30,000 characters, + // UTF-8 NFC encoded. * Translation - TextSnippet, content up to 25,000 characters, UTF-8 + // encoded. + // * Tables - Row, with column values matching the columns of the model, + // up to 5MB. + // * Text Sentiment - TextSnippet, content up 500 characters, UTF-8 encoded. + rpc Predict(PredictRequest) returns (PredictResponse) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/models/*}:predict" + body: "*" + }; + } + + // Perform a batch prediction. Unlike the online [Predict][google.cloud.automl.v1beta1.PredictionService.Predict], batch + // prediction result won't be immediately available in the response. Instead, + // a long running operation object is returned. User can poll the operation + // result via [GetOperation][google.longrunning.Operations.GetOperation] + // method. Once the operation is done, [BatchPredictResult][google.cloud.automl.v1beta1.BatchPredictResult] is returned in + // the [response][google.longrunning.Operation.response] field. + // Available for following ML problems: + // * Video Classification + // * Text Extraction + // * Tables + rpc BatchPredict(BatchPredictRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/models/*}:batchPredict" + body: "*" + }; + } +} + +// Request message for [PredictionService.Predict][google.cloud.automl.v1beta1.PredictionService.Predict]. +message PredictRequest { + // Name of the model requested to serve the prediction. + string name = 1; + + // Required. + // Payload to perform a prediction on. The payload must match the + // problem type that the model was trained to solve. + ExamplePayload payload = 2; + + // Additional domain-specific parameters, any string must be up to 25000 + // characters long. + // + // * For Image Classification: + // + // `score_threshold` - (float) A value from 0.0 to 1.0. When the model + // makes predictions for an image, it will only produce results that have + // at least this confidence score. The default is 0.5. + // + // * For Image Object Detection: + // `score_threshold` - (float) When Model detects objects on the image, + // it will only produce bounding boxes which have at least this + // confidence score. Value in 0 to 1 range, default is 0.5. + // `max_bounding_box_count` - (int64) No more than this number of bounding + // boxes will be returned in the response. Default is 100, the + // requested value may be limited by server. + map<string, string> params = 3; +} + +// Response message for [PredictionService.Predict][google.cloud.automl.v1beta1.PredictionService.Predict]. +message PredictResponse { + // Prediction result. + // Translation and Text Sentiment will return precisely one payload. + repeated AnnotationPayload payload = 1; + + // Additional domain-specific prediction response metadata. + // + // * For Image Object Detection: + // `max_bounding_box_count` - (int64) At most that many bounding boxes per + // image could have been returned. + // + // * For Text Sentiment: + // `sentiment_score` - (float, deprecated) A value between -1 and 1, + // -1 maps to least positive sentiment, while 1 maps to the most positive + // one and the higher the score, the more positive the sentiment in the + // document is. Yet these values are relative to the training data, so + // e.g. if all data was positive then -1 will be also positive (though + // the least). + // The sentiment_score shouldn't be confused with "score" or "magnitude" + // from the previous Natural Language Sentiment Analysis API. + map<string, string> metadata = 2; +} + +// Request message for [PredictionService.BatchPredict][google.cloud.automl.v1beta1.PredictionService.BatchPredict]. +message BatchPredictRequest { + // Name of the model requested to serve the batch prediction. + string name = 1; + + // Required. The input configuration for batch prediction. + BatchPredictInputConfig input_config = 3; + + // Required. The Configuration specifying where output predictions should + // be written. + BatchPredictOutputConfig output_config = 4; + + // Additional domain-specific parameters for the predictions, any string must + // be up to 25000 characters long. + // + // * For Video Classification : + // `score_threshold` - (float) A value from 0.0 to 1.0. When the model + // makes predictions for a video, it will only produce results that + // have at least this confidence score. The default is 0.5. + // `segment_classification` - (boolean) Set to true to request + // segment-level classification. AutoML Video Intelligence returns + // labels and their confidence scores for the entire segment of the + // video that user specified in the request configuration. + // The default is "true". + // `shot_classification` - (boolean) Set to true to request shot-level + // classification. AutoML Video Intelligence determines the boundaries + // for each camera shot in the entire segment of the video that user + // specified in the request configuration. AutoML Video Intelligence + // then returns labels and their confidence scores for each detected + // shot, along with the start and end time of the shot. + // WARNING: Model evaluation is not done for this classification type, + // the quality of it depends on training data, but there are no metrics + // provided to describe that quality. The default is "false". + // `1s_interval_classification` - (boolean) Set to true to request + // classification for a video at one-second intervals. AutoML Video + // Intelligence returns labels and their confidence scores for each + // second of the entire segment of the video that user specified in the + // request configuration. + // WARNING: Model evaluation is not done for this classification + // type, the quality of it depends on training data, but there are no + // metrics provided to describe that quality. The default is + // "false". + map<string, string> params = 5; +} + +// Batch predict result. +message BatchPredictResult { +} diff --git a/google/cloud/automl/v1beta1/ranges.proto b/google/cloud/automl/v1beta1/ranges.proto new file mode 100644 index 000000000..01602218f --- /dev/null +++ b/google/cloud/automl/v1beta1/ranges.proto @@ -0,0 +1,36 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "RangesProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A range between two double numbers. +message DoubleRange { + // Start of the range, inclusive. + double start = 1; + + // End of the range, exclusive. + double end = 2; +} diff --git a/google/cloud/automl/v1beta1/regression.proto b/google/cloud/automl/v1beta1/regression.proto new file mode 100644 index 000000000..a215c9b98 --- /dev/null +++ b/google/cloud/automl/v1beta1/regression.proto @@ -0,0 +1,42 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_outer_classname = "RegressionProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Metrics for regression problems. +message RegressionEvaluationMetrics { + // Output only. Root Mean Squared Error (RMSE). + float root_mean_squared_error = 1; + + // Output only. Mean Absolute Error (MAE). + float mean_absolute_error = 2; + + // Output only. Mean absolute percentage error. Only set if all ground truth + // values are are positive. + float mean_absolute_percentage_error = 3; + + // Output only. R squared. + float r_squared = 4; +} diff --git a/google/cloud/automl/v1beta1/service.proto b/google/cloud/automl/v1beta1/service.proto new file mode 100644 index 000000000..e0bf47fad --- /dev/null +++ b/google/cloud/automl/v1beta1/service.proto @@ -0,0 +1,640 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/annotation_payload.proto"; +import "google/cloud/automl/v1beta1/column_spec.proto"; +import "google/cloud/automl/v1beta1/dataset.proto"; +import "google/cloud/automl/v1beta1/image.proto"; +import "google/cloud/automl/v1beta1/io.proto"; +import "google/cloud/automl/v1beta1/model.proto"; +import "google/cloud/automl/v1beta1/model_evaluation.proto"; +import "google/cloud/automl/v1beta1/operations.proto"; +import "google/cloud/automl/v1beta1/table_spec.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "AutoMlProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// AutoML Server API. +// +// The resource names are assigned by the server. +// The server never reuses names that it has created after the resources with +// those names are deleted. +// +// An ID of a resource is the last element of the item's resource name. For +// `projects/{project_id}/locations/{location_id}/datasets/{dataset_id}`, then +// the id for the item is `{dataset_id}`. +// +// Currently the only supported `location_id` is "us-central1". +// +// On any input that is documented to expect a string parameter in +// snake_case or kebab-case, either of those cases is accepted. +service AutoMl { + // Creates a dataset. + rpc CreateDataset(CreateDatasetRequest) returns (Dataset) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/locations/*}/datasets" + body: "dataset" + }; + } + + // Gets a dataset. + rpc GetDataset(GetDatasetRequest) returns (Dataset) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/datasets/*}" + }; + } + + // Lists datasets in a project. + rpc ListDatasets(ListDatasetsRequest) returns (ListDatasetsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*}/datasets" + }; + } + + // Updates a dataset. + rpc UpdateDataset(UpdateDatasetRequest) returns (Dataset) { + option (google.api.http) = { + patch: "/v1beta1/{dataset.name=projects/*/locations/*/datasets/*}" + body: "dataset" + }; + } + + // Deletes a dataset and all of its contents. + // Returns empty response in the + // [response][google.longrunning.Operation.response] field when it completes, + // and `delete_details` in the + // [metadata][google.longrunning.Operation.metadata] field. + rpc DeleteDataset(DeleteDatasetRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/locations/*/datasets/*}" + }; + } + + // Imports data into a dataset. For Tables this method can only be called on an empty Dataset. + // + // For Tables: + // * A + // [schema_inference_version][google.cloud.automl.v1beta1.InputConfig.params] + // parameter must be explicitly set. + // Returns an empty response in the + // [response][google.longrunning.Operation.response] field when it completes. + rpc ImportData(ImportDataRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/datasets/*}:importData" + body: "*" + }; + } + + // Exports dataset's data to the provided output location. + // Returns an empty response in the + // [response][google.longrunning.Operation.response] field when it completes. + rpc ExportData(ExportDataRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/datasets/*}:exportData" + body: "*" + }; + } + + // Gets an annotation spec. + rpc GetAnnotationSpec(GetAnnotationSpecRequest) returns (AnnotationSpec) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/datasets/*/annotationSpecs/*}" + }; + } + + // Gets a table spec. + rpc GetTableSpec(GetTableSpecRequest) returns (TableSpec) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/datasets/*/tableSpecs/*}" + }; + } + + // Lists table specs in a dataset. + rpc ListTableSpecs(ListTableSpecsRequest) returns (ListTableSpecsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*/datasets/*}/tableSpecs" + }; + } + + // Updates a table spec. + rpc UpdateTableSpec(UpdateTableSpecRequest) returns (TableSpec) { + option (google.api.http) = { + patch: "/v1beta1/{table_spec.name=projects/*/locations/*/datasets/*/tableSpecs/*}" + body: "table_spec" + }; + } + + // Gets a column spec. + rpc GetColumnSpec(GetColumnSpecRequest) returns (ColumnSpec) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/datasets/*/tableSpecs/*/columnSpecs/*}" + }; + } + + // Lists column specs in a table spec. + rpc ListColumnSpecs(ListColumnSpecsRequest) returns (ListColumnSpecsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*/datasets/*/tableSpecs/*}/columnSpecs" + }; + } + + // Updates a column spec. + rpc UpdateColumnSpec(UpdateColumnSpecRequest) returns (ColumnSpec) { + option (google.api.http) = { + patch: "/v1beta1/{column_spec.name=projects/*/locations/*/datasets/*/tableSpecs/*/columnSpecs/*}" + body: "column_spec" + }; + } + + // Creates a model. + // Returns a Model in the [response][google.longrunning.Operation.response] + // field when it completes. + // When you create a model, several model evaluations are created for it: + // a global evaluation, and one evaluation for each annotation spec. + rpc CreateModel(CreateModelRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/locations/*}/models" + body: "model" + }; + } + + // Gets a model. + rpc GetModel(GetModelRequest) returns (Model) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/models/*}" + }; + } + + // Lists models. + rpc ListModels(ListModelsRequest) returns (ListModelsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*}/models" + }; + } + + // Deletes a model. + // Returns `google.protobuf.Empty` in the + // [response][google.longrunning.Operation.response] field when it completes, + // and `delete_details` in the + // [metadata][google.longrunning.Operation.metadata] field. + rpc DeleteModel(DeleteModelRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/locations/*/models/*}" + }; + } + + // Deploys a model. If a model is already deployed, deploying it with the + // same parameters has no effect. Deploying with different parametrs + // (as e.g. changing + // + // [node_number][google.cloud.automl.v1beta1.ImageObjectDetectionModelDeploymentMetadata.node_number] + // ) will update the deployment without pausing the model's availability. + // + // Only applicable for Text Classification, Image Object Detection and Tables; + // all other domains manage deployment automatically. + // + // Returns an empty response in the + // [response][google.longrunning.Operation.response] field when it completes. + rpc DeployModel(DeployModelRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/models/*}:deploy" + body: "*" + }; + } + + // Undeploys a model. If the model is not deployed this method has no effect. + // + // Only applicable for Text Classification, Image Object Detection and Tables; + // all other domains manage deployment automatically. + // + // Returns an empty response in the + // [response][google.longrunning.Operation.response] field when it completes. + rpc UndeployModel(UndeployModelRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/models/*}:undeploy" + body: "*" + }; + } + + // Exports a trained, "export-able", model to a user specified Google Cloud + // Storage location. A model is considered export-able if and only if it has + // an export format defined for it in + // + // [ModelExportOutputConfig][google.cloud.automl.v1beta1.ModelExportOutputConfig]. + // + // Returns an empty response in the + // [response][google.longrunning.Operation.response] field when it completes. + rpc ExportModel(ExportModelRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/models/*}:export" + body: "*" + }; + } + + // Exports examples on which the model was evaluated (i.e. which were in the + // TEST set of the dataset the model was created from), together with their + // ground truth annotations and the annotations created (predicted) by the + // model. + // The examples, ground truth and predictions are exported in the state + // they were at the moment the model was evaluated. + // + // This export is available only for 30 days since the model evaluation is + // created. + // + // Currently only available for Tables. + // + // Returns an empty response in the + // [response][google.longrunning.Operation.response] field when it completes. + rpc ExportEvaluatedExamples(ExportEvaluatedExamplesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/models/*}:exportEvaluatedExamples" + body: "*" + }; + } + + // Gets a model evaluation. + rpc GetModelEvaluation(GetModelEvaluationRequest) returns (ModelEvaluation) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/models/*/modelEvaluations/*}" + }; + } + + // Lists model evaluations. + rpc ListModelEvaluations(ListModelEvaluationsRequest) returns (ListModelEvaluationsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*/models/*}/modelEvaluations" + }; + } +} + +// Request message for [AutoMl.CreateDataset][google.cloud.automl.v1beta1.AutoMl.CreateDataset]. +message CreateDatasetRequest { + // The resource name of the project to create the dataset for. + string parent = 1; + + // The dataset to create. + Dataset dataset = 2; +} + +// Request message for [AutoMl.GetDataset][google.cloud.automl.v1beta1.AutoMl.GetDataset]. +message GetDatasetRequest { + // The resource name of the dataset to retrieve. + string name = 1; +} + +// Request message for [AutoMl.ListDatasets][google.cloud.automl.v1beta1.AutoMl.ListDatasets]. +message ListDatasetsRequest { + // The resource name of the project from which to list datasets. + string parent = 1; + + // An expression for filtering the results of the request. + // + // * `dataset_metadata` - for existence of the case (e.g. + // image_classification_dataset_metadata:*). Some examples of using the filter are: + // + // * `translation_dataset_metadata:*` --> The dataset has + // translation_dataset_metadata. + string filter = 3; + + // Requested page size. Server may return fewer results than requested. + // If unspecified, server will pick a default size. + int32 page_size = 4; + + // A token identifying a page of results for the server to return + // Typically obtained via + // [ListDatasetsResponse.next_page_token][google.cloud.automl.v1beta1.ListDatasetsResponse.next_page_token] of the previous + // [AutoMl.ListDatasets][google.cloud.automl.v1beta1.AutoMl.ListDatasets] call. + string page_token = 6; +} + +// Response message for [AutoMl.ListDatasets][google.cloud.automl.v1beta1.AutoMl.ListDatasets]. +message ListDatasetsResponse { + // The datasets read. + repeated Dataset datasets = 1; + + // A token to retrieve next page of results. + // Pass to [ListDatasetsRequest.page_token][google.cloud.automl.v1beta1.ListDatasetsRequest.page_token] to obtain that page. + string next_page_token = 2; +} + +// Request message for [AutoMl.UpdateDataset][google.cloud.automl.v1beta1.AutoMl.UpdateDataset] +message UpdateDatasetRequest { + // The dataset which replaces the resource on the server. + Dataset dataset = 1; + + // The update mask applies to the resource. For the `FieldMask` definition, + // see + // + // https: + // //developers.google.com/protocol-buffers + // // /docs/reference/google.protobuf#fieldmask + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for [AutoMl.DeleteDataset][google.cloud.automl.v1beta1.AutoMl.DeleteDataset]. +message DeleteDatasetRequest { + // The resource name of the dataset to delete. + string name = 1; +} + +// Request message for [AutoMl.ImportData][google.cloud.automl.v1beta1.AutoMl.ImportData]. +message ImportDataRequest { + // Required. Dataset name. Dataset must already exist. All imported + // annotations and examples will be added. + string name = 1; + + // Required. The desired input location and its domain specific semantics, + // if any. + InputConfig input_config = 3; +} + +// Request message for [AutoMl.ExportData][google.cloud.automl.v1beta1.AutoMl.ExportData]. +message ExportDataRequest { + // Required. The resource name of the dataset. + string name = 1; + + // Required. The desired output location. + OutputConfig output_config = 3; +} + +// Request message for [AutoMl.GetAnnotationSpec][google.cloud.automl.v1beta1.AutoMl.GetAnnotationSpec]. +message GetAnnotationSpecRequest { + // The resource name of the annotation spec to retrieve. + string name = 1; +} + +// Request message for [AutoMl.GetTableSpec][google.cloud.automl.v1beta1.AutoMl.GetTableSpec]. +message GetTableSpecRequest { + // The resource name of the table spec to retrieve. + string name = 1; + + // Mask specifying which fields to read. + google.protobuf.FieldMask field_mask = 2; +} + +// Request message for [AutoMl.ListTableSpecs][google.cloud.automl.v1beta1.AutoMl.ListTableSpecs]. +message ListTableSpecsRequest { + // The resource name of the dataset to list table specs from. + string parent = 1; + + // Mask specifying which fields to read. + google.protobuf.FieldMask field_mask = 2; + + // Filter expression, see go/filtering. + string filter = 3; + + // Requested page size. The server can return fewer results than requested. + // If unspecified, the server will pick a default size. + int32 page_size = 4; + + // A token identifying a page of results for the server to return. + // Typically obtained from the + // [ListTableSpecsResponse.next_page_token][google.cloud.automl.v1beta1.ListTableSpecsResponse.next_page_token] field of the previous + // [AutoMl.ListTableSpecs][google.cloud.automl.v1beta1.AutoMl.ListTableSpecs] call. + string page_token = 6; +} + +// Response message for [AutoMl.ListTableSpecs][google.cloud.automl.v1beta1.AutoMl.ListTableSpecs]. +message ListTableSpecsResponse { + // The table specs read. + repeated TableSpec table_specs = 1; + + // A token to retrieve next page of results. + // Pass to [ListTableSpecsRequest.page_token][google.cloud.automl.v1beta1.ListTableSpecsRequest.page_token] to obtain that page. + string next_page_token = 2; +} + +// Request message for [AutoMl.UpdateTableSpec][google.cloud.automl.v1beta1.AutoMl.UpdateTableSpec] +message UpdateTableSpecRequest { + // The table spec which replaces the resource on the server. + TableSpec table_spec = 1; + + // The update mask applies to the resource. For the `FieldMask` definition, + // see + // + // https: + // //developers.google.com/protocol-buffers + // // /docs/reference/google.protobuf#fieldmask + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for [AutoMl.GetColumnSpec][google.cloud.automl.v1beta1.AutoMl.GetColumnSpec]. +message GetColumnSpecRequest { + // The resource name of the column spec to retrieve. + string name = 1; + + // Mask specifying which fields to read. + google.protobuf.FieldMask field_mask = 2; +} + +// Request message for [AutoMl.ListColumnSpecs][google.cloud.automl.v1beta1.AutoMl.ListColumnSpecs]. +message ListColumnSpecsRequest { + // The resource name of the table spec to list column specs from. + string parent = 1; + + // Mask specifying which fields to read. + google.protobuf.FieldMask field_mask = 2; + + // Filter expression, see go/filtering. + string filter = 3; + + // Requested page size. The server can return fewer results than requested. + // If unspecified, the server will pick a default size. + int32 page_size = 4; + + // A token identifying a page of results for the server to return. + // Typically obtained from the + // [ListColumnSpecsResponse.next_page_token][google.cloud.automl.v1beta1.ListColumnSpecsResponse.next_page_token] field of the previous + // [AutoMl.ListColumnSpecs][google.cloud.automl.v1beta1.AutoMl.ListColumnSpecs] call. + string page_token = 6; +} + +// Response message for [AutoMl.ListColumnSpecs][google.cloud.automl.v1beta1.AutoMl.ListColumnSpecs]. +message ListColumnSpecsResponse { + // The column specs read. + repeated ColumnSpec column_specs = 1; + + // A token to retrieve next page of results. + // Pass to [ListColumnSpecsRequest.page_token][google.cloud.automl.v1beta1.ListColumnSpecsRequest.page_token] to obtain that page. + string next_page_token = 2; +} + +// Request message for [AutoMl.UpdateColumnSpec][google.cloud.automl.v1beta1.AutoMl.UpdateColumnSpec] +message UpdateColumnSpecRequest { + // The column spec which replaces the resource on the server. + ColumnSpec column_spec = 1; + + // The update mask applies to the resource. For the `FieldMask` definition, + // see + // + // https: + // //developers.google.com/protocol-buffers + // // /docs/reference/google.protobuf#fieldmask + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for [AutoMl.CreateModel][google.cloud.automl.v1beta1.AutoMl.CreateModel]. +message CreateModelRequest { + // Resource name of the parent project where the model is being created. + string parent = 1; + + // The model to create. + Model model = 4; +} + +// Request message for [AutoMl.GetModel][google.cloud.automl.v1beta1.AutoMl.GetModel]. +message GetModelRequest { + // Resource name of the model. + string name = 1; +} + +// Request message for [AutoMl.ListModels][google.cloud.automl.v1beta1.AutoMl.ListModels]. +message ListModelsRequest { + // Resource name of the project, from which to list the models. + string parent = 1; + + // An expression for filtering the results of the request. + // + // * `model_metadata` - for existence of the case (e.g. + // video_classification_model_metadata:*). + // * `dataset_id` - for = or !=. Some examples of using the filter are: + // + // * `image_classification_model_metadata:*` --> The model has + // image_classification_model_metadata. + // * `dataset_id=5` --> The model was created from a dataset with ID 5. + string filter = 3; + + // Requested page size. + int32 page_size = 4; + + // A token identifying a page of results for the server to return + // Typically obtained via + // [ListModelsResponse.next_page_token][google.cloud.automl.v1beta1.ListModelsResponse.next_page_token] of the previous + // [AutoMl.ListModels][google.cloud.automl.v1beta1.AutoMl.ListModels] call. + string page_token = 6; +} + +// Response message for [AutoMl.ListModels][google.cloud.automl.v1beta1.AutoMl.ListModels]. +message ListModelsResponse { + // List of models in the requested page. + repeated Model model = 1; + + // A token to retrieve next page of results. + // Pass to [ListModelsRequest.page_token][google.cloud.automl.v1beta1.ListModelsRequest.page_token] to obtain that page. + string next_page_token = 2; +} + +// Request message for [AutoMl.DeleteModel][google.cloud.automl.v1beta1.AutoMl.DeleteModel]. +message DeleteModelRequest { + // Resource name of the model being deleted. + string name = 1; +} + +// Request message for [AutoMl.DeployModel][google.cloud.automl.v1beta1.AutoMl.DeployModel]. +message DeployModelRequest { + // The per-domain specific deployment parameters. + oneof model_deployment_metadata { + // Model deployment metadata specific to Image Object Detection. + ImageObjectDetectionModelDeploymentMetadata image_object_detection_model_deployment_metadata = 2; + } + + // Resource name of the model to deploy. + string name = 1; +} + +// Request message for [AutoMl.UndeployModel][google.cloud.automl.v1beta1.AutoMl.UndeployModel]. +message UndeployModelRequest { + // Resource name of the model to undeploy. + string name = 1; +} + +// Request message for [AutoMl.ExportModel][google.cloud.automl.v1beta1.AutoMl.ExportModel]. +// Models need to be enabled for exporting, otherwise an error code will be +// returned. +message ExportModelRequest { + // Required. The resource name of the model to export. + string name = 1; + + // Required. The desired output location and configuration. + ModelExportOutputConfig output_config = 3; +} + +// Request message for [AutoMl.ExportEvaluatedExamples][google.cloud.automl.v1beta1.AutoMl.ExportEvaluatedExamples]. +message ExportEvaluatedExamplesRequest { + // Required. The resource name of the model whose evaluated examples are to + // be exported. + string name = 1; + + // Required. The desired output location and configuration. + ExportEvaluatedExamplesOutputConfig output_config = 3; +} + +// Request message for [AutoMl.GetModelEvaluation][google.cloud.automl.v1beta1.AutoMl.GetModelEvaluation]. +message GetModelEvaluationRequest { + // Resource name for the model evaluation. + string name = 1; +} + +// Request message for [AutoMl.ListModelEvaluations][google.cloud.automl.v1beta1.AutoMl.ListModelEvaluations]. +message ListModelEvaluationsRequest { + // Resource name of the model to list the model evaluations for. + // If modelId is set as "-", this will list model evaluations from across all + // models of the parent location. + string parent = 1; + + // An expression for filtering the results of the request. + // + // * `annotation_spec_id` - for =, != or existence. See example below for + // the last. + // + // Some examples of using the filter are: + // + // * `annotation_spec_id!=4` --> The model evaluation was done for + // annotation spec with ID different than 4. + // * `NOT annotation_spec_id:*` --> The model evaluation was done for + // aggregate of all annotation specs. + string filter = 3; + + // Requested page size. + int32 page_size = 4; + + // A token identifying a page of results for the server to return. + // Typically obtained via + // [ListModelEvaluationsResponse.next_page_token][google.cloud.automl.v1beta1.ListModelEvaluationsResponse.next_page_token] of the previous + // [AutoMl.ListModelEvaluations][google.cloud.automl.v1beta1.AutoMl.ListModelEvaluations] call. + string page_token = 6; +} + +// Response message for [AutoMl.ListModelEvaluations][google.cloud.automl.v1beta1.AutoMl.ListModelEvaluations]. +message ListModelEvaluationsResponse { + // List of model evaluations in the requested page. + repeated ModelEvaluation model_evaluation = 1; + + // A token to retrieve next page of results. + // Pass to the [ListModelEvaluationsRequest.page_token][google.cloud.automl.v1beta1.ListModelEvaluationsRequest.page_token] field of a new + // [AutoMl.ListModelEvaluations][google.cloud.automl.v1beta1.AutoMl.ListModelEvaluations] request to obtain that page. + string next_page_token = 2; +} diff --git a/google/cloud/automl/v1beta1/table_spec.proto b/google/cloud/automl/v1beta1/table_spec.proto new file mode 100644 index 000000000..f0d079776 --- /dev/null +++ b/google/cloud/automl/v1beta1/table_spec.proto @@ -0,0 +1,69 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/io.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A specification of a relational table. +// The table's schema is represented via its child column specs. It is +// pre-populated as part of ImportData by schema inference algorithm, the +// version of which is a required parameter of ImportData InputConfig. +// Note: While working with a table, at times the schema may be +// inconsistent with the data in the table (e.g. string in a FLOAT64 column). +// The consistency validation is done upon creation of a model. +// Used by: +// * Tables +message TableSpec { + // Output only. The resource name of the table spec. + // Form: + // + // `projects/{project_id}/locations/{location_id}/datasets/{dataset_id}/tableSpecs/{table_spec_id}` + string name = 1; + + // column_spec_id of the time column. Only used if the parent dataset's + // ml_use_column_spec_id is not set. Used to split rows into TRAIN, VALIDATE + // and TEST sets such that oldest rows go to TRAIN set, newest to TEST, and + // those in between to VALIDATE. + // Required type: TIMESTAMP. + // If both this column and ml_use_column are not set, then ML use of all rows + // will be assigned by AutoML. NOTE: Updates of this field will instantly + // affect any other users concurrently working with the dataset. + string time_column_spec_id = 2; + + // Output only. The number of rows (i.e. examples) in the table. + int64 row_count = 3; + + // Output only. The number of columns of the table. That is, the number of + // child ColumnSpec-s. + int64 column_count = 7; + + // Output only. Input configs via which data currently residing in the table + // had been imported. + repeated InputConfig input_configs = 5; + + // Used to perform consistent read-modify-write updates. If not set, a blind + // "overwrite" update happens. + string etag = 6; +} diff --git a/google/cloud/automl/v1beta1/tables.proto b/google/cloud/automl/v1beta1/tables.proto new file mode 100644 index 000000000..2a5181812 --- /dev/null +++ b/google/cloud/automl/v1beta1/tables.proto @@ -0,0 +1,251 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/column_spec.proto"; +import "google/cloud/automl/v1beta1/data_stats.proto"; +import "google/cloud/automl/v1beta1/ranges.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Metadata for a dataset used for AutoML Tables. +message TablesDatasetMetadata { + // Output only. The table_spec_id of the primary table of this dataset. + string primary_table_spec_id = 1; + + // column_spec_id of the primary table's column that should be used as the + // training & prediction target. + // This column must be non-nullable and have one of following data types + // (otherwise model creation will error): + // * CATEGORY + // * ARRAY(CATEGORY) + // * FLOAT64 + // Furthermore, if the type is CATEGORY or ARRAY(CATEGORY), then only up to + // 40 unique values may exist in that column across all rows, but for + // ARRAY(CATEGORY) unique values are counted as elements of the ARRAY (i.e. + // following 3 ARRAY-s: [A, B], [A], [B] are counted as having 2 unique + // values). + // + // NOTE: Updates of this field will instantly affect any other users + // concurrently working with the dataset. + string target_column_spec_id = 2; + + // column_spec_id of the primary table's column that should be used as the + // weight column, i.e. the higher the value the more important the row will be + // during model training. + // Required type: FLOAT64. + // Allowed values: 0 to 10000, inclusive on both ends; 0 means the row is + // ignored for training. + // If not set all rows are assumed to have equal weight of 1. + // NOTE: Updates of this field will instantly affect any other users + // concurrently working with the dataset. + string weight_column_spec_id = 3; + + // column_spec_id of the primary table column which specifies a possible ML + // use of the row, i.e. the column will be used to split the rows into TRAIN, + // VALIDATE and TEST sets. + // Required type: STRING. + // This column, if set, must either have all of `TRAIN`, `VALIDATE`, `TEST` + // among its values, or only have `TEST`, `UNASSIGNED` values. In the latter + // case the rows with `UNASSIGNED` value will be assigned by AutoML. Note + // that if a given ml use distribution makes it impossible to create a "good" + // model, that call will error describing the issue. + // If both this column_spec_id and primary table's time_column_spec_id are not + // set, then all rows are treated as `UNASSIGNED`. + // NOTE: Updates of this field will instantly affect any other users + // concurrently working with the dataset. + string ml_use_column_spec_id = 4; + + // Output only. Correlations between + // + // [target_column][google.cloud.automl.v1beta1.TablesDatasetMetadata.target_column], + // and other columns of the + // + // [primary_table][google.cloud.automl.v1beta1.TablesDatasetMetadata.primary_table_spec_id]. + // Only set if the target column is set. Mapping from other column spec id to + // its CorrelationStats with the target column. + // This field may be stale, see the stats_update_time field for + // for the timestamp at which these stats were last updated. + map<string, CorrelationStats> target_column_correlations = 6; + + // The most recent timestamp when target_column_correlations field and all + // descendant ColumnSpec.data_stats and ColumnSpec.top_correlated_columns + // fields were last (re-)generated. Any changes that happened to the dataset + // afterwards are not reflected in these fields values. The regeneration + // happens in the background on a best effort basis. + google.protobuf.Timestamp stats_update_time = 7; +} + +// Model metadata specific to AutoML Tables. +message TablesModelMetadata { + // Column spec of the dataset's primary table's column the model is + // predicting. Snapshotted when model creation started. + // Only 3 fields are used: + // name - May be set on CreateModel, if it's not then the ColumnSpec + // corresponding to the current target_column_spec_id of the dataset + // the model is trained from is used. + // If neither is set, CreateModel will error. + // display_name - Output only. + // data_type - Output only. + ColumnSpec target_column_spec = 2; + + // Column specs of the dataset's primary table's columns, on which + // the model is trained and which are used as the input for predictions. + // The + // + // [target_column][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec] + // as well as, according to dataset's state upon model creation, + // + // [weight_column][google.cloud.automl.v1beta1.TablesDatasetMetadata.weight_column_spec_id], + // and + // + // [ml_use_column][google.cloud.automl.v1beta1.TablesDatasetMetadata.ml_use_column_spec_id] + // must never be included here. + // Only 3 fields are used: + // name - May be set on CreateModel, if set only the columns specified are + // used, otherwise all primary table's columns (except the ones listed + // above) are used for the training and prediction input. + // display_name - Output only. + // data_type - Output only. + repeated ColumnSpec input_feature_column_specs = 3; + + // Objective function the model is optimizing towards. The training process + // creates a model that maximizes/minimizes the value of the objective + // function over the validation set. + // + // The supported optimization objectives depend on the prediction_type. + // If the field is not set, a default objective function is used. + // + // CLASSIFICATION_BINARY: + // "MAXIMIZE_AU_ROC" (default) - Maximize the area under the receiver + // operating characteristic (ROC) curve. + // "MINIMIZE_LOG_LOSS" - Minimize log loss. + // "MAXIMIZE_AU_PRC" - Maximize the area under the precision-recall curve. + // + // CLASSIFICATION_MULTI_CLASS : + // "MINIMIZE_LOG_LOSS" (default) - Minimize log loss. + // + // CLASSIFICATION_MULTI_LABEL: + // "MINIMIZE_LOG_LOSS" (default) - Minimize log loss. + // + // REGRESSION: + // "MINIMIZE_RMSE" (default) - Minimize root-mean-squared error (RMSE). + // "MINIMIZE_MAE" - Minimize mean-absolute error (MAE). + // "MINIMIZE_RMSLE" - Minimize root-mean-squared log error (RMSLE). + // + // FORECASTING: + // "MINIMIZE_RMSE" (default) - Minimize root-mean-squared error (RMSE). + // "MINIMIZE_MAE" - Minimize mean-absolute error (MAE). + string optimization_objective = 4; + + // Output only. Auxiliary information for each of the + // input_feature_column_specs, with respect to this particular model. + repeated TablesModelColumnInfo tables_model_column_info = 5; + + // The train budget of creating this model, expressed in milli node hours + // i.e. 1,000 value in this field means 1 node hour. + // + // The training cost of the model will not exceed this budget. The final cost + // will be attempted to be close to the budget, though may end up being (even) + // noticeably smaller - at the backend's discretion. This especially may + // happen when further model training ceases to provide any improvements. + // + // If the budget is set to a value known to be insufficient to train a + // model for the given dataset, the training won't be attempted and + // will error. + int64 train_budget_milli_node_hours = 6; + + // Output only. The actual training cost of the model, expressed in milli + // node hours, i.e. 1,000 value in this field means 1 node hour. Guaranteed + // to not exceed the train budget. + int64 train_cost_milli_node_hours = 7; +} + +// Contains annotation details specific to Tables. +message TablesAnnotation { + // Output only. A confidence estimate between 0.0 and 1.0, inclusive. A higher + // value means greater confidence in the returned value. + // For + // + // [target_column_spec][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec] + // of ARRAY(CATEGORY) data type, this is a confidence that one of the values + // in the ARRAY would be the provided value. + // For + // + // [target_column_spec][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec] + // of FLOAT64 data type the score is not populated. + float score = 1; + + // Output only. Only populated when + // + // [target_column_spec][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec] + // has FLOAT64 data type (i.e. for regression predictions). An interval in + // which the exactly correct target value has 95% chance to be in. + DoubleRange prediction_interval = 4; + + // The predicted value of the row's + // + // [target_column][google.cloud.automl.v1beta1.TablesModelMetadata.target_column_spec]. + // The value depends on the column's DataType: + // CATEGORY - the predicted (with the above confidence `score`) CATEGORY + // value. + // FLOAT64 - the predicted (with the above confidence `score`) FLOAT64 value. + // ARRAY(CATEGORY) - CATEGORY value meaning that this value would be in the + // ARRAY in that column (with the above confidence `score`). + google.protobuf.Value value = 2; + + // Output only. Auxiliary information for each of the model's + // + // [input_feature_column_specs'][google.cloud.automl.v1beta1.TablesModelMetadata.input_feature_column_specs] + // with respect to this particular prediction. + repeated TablesModelColumnInfo tables_model_column_info = 3; +} + +// An information specific to given column and Tables Model, in context +// of the Model and the predictions created by it. +message TablesModelColumnInfo { + // Output only. The name of the ColumnSpec describing the column. Not + // populated when this proto is outputted to BigQuery. + string column_spec_name = 1; + + // Output only. The display name of the column (same as the display_name of + // its ColumnSpec). + string column_display_name = 2; + + // Output only. + // + // When given as part of a Model: + // Measurement of how much model predictions correctness on the TEST data + // depend on values in this column. A value between 0 and 1, higher means + // higher influence. These values are normalized - for all input feature + // columns of a given model they add to 1. + // + // When given back by Predict or Batch Predict: + // Measurement of how impactful for the prediction returned for the given row + // the value in this column was. A value between 0 and 1, higher means larger + // impact. These values are normalized - for all input feature columns of a + // single predicted row they add to 1. + float feature_importance = 3; +} diff --git a/google/cloud/automl/v1beta1/temporal.proto b/google/cloud/automl/v1beta1/temporal.proto new file mode 100644 index 000000000..616338ddc --- /dev/null +++ b/google/cloud/automl/v1beta1/temporal.proto @@ -0,0 +1,38 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A time period inside of an example that has a time dimension (e.g. video). +message TimeSegment { + // Start of the time segment (inclusive), represented as the duration since + // the example start. + google.protobuf.Duration start_time_offset = 1; + + // End of the time segment (exclusive), represented as the duration since the + // example start. + google.protobuf.Duration end_time_offset = 2; +} diff --git a/google/cloud/automl/v1beta1/text.proto b/google/cloud/automl/v1beta1/text.proto new file mode 100644 index 000000000..8b4b853c3 --- /dev/null +++ b/google/cloud/automl/v1beta1/text.proto @@ -0,0 +1,67 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/classification.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "TextProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Dataset metadata for classification. +message TextClassificationDatasetMetadata { + // Required. + // Type of the classification problem. + ClassificationType classification_type = 1; +} + +// Model metadata that is specific to text classification. +message TextClassificationModelMetadata { + +} + +// Dataset metadata that is specific to text extraction +message TextExtractionDatasetMetadata { + +} + +// Model metadata that is specific to text extraction. +message TextExtractionModelMetadata { + +} + +// Dataset metadata for text sentiment. +message TextSentimentDatasetMetadata { + // Required. + // A sentiment is expressed as an integer ordinal, where higher value + // means a more positive sentiment. The range of sentiments that will be used + // is between 0 and sentiment_max (inclusive on both ends), and all the values + // in the range must be represented in the dataset before a model can be + // created. + // sentiment_max value must be between 1 and 10 (inclusive). + int32 sentiment_max = 1; +} + +// Model metadata that is specific to text classification. +message TextSentimentModelMetadata { + +} diff --git a/google/cloud/automl/v1beta1/text_extraction.proto b/google/cloud/automl/v1beta1/text_extraction.proto new file mode 100644 index 000000000..4d6a235e6 --- /dev/null +++ b/google/cloud/automl/v1beta1/text_extraction.proto @@ -0,0 +1,64 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/text_segment.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Annotation for identifying spans of text. +message TextExtractionAnnotation { + // Output only. A confidence estimate between 0.0 and 1.0. A higher value + // means greater confidence in correctness of the annotation. + float score = 1; + + // Required. The part of the original text to which this annotation pertains. + TextSegment text_segment = 3; +} + +// Model evaluation metrics for text extraction problems. +message TextExtractionEvaluationMetrics { + // Metrics for a single confidence threshold. + message ConfidenceMetricsEntry { + // Output only. The confidence threshold value used to compute the metrics. + // Only annotations with score of at least this threshold are considered to + // be ones the model would return. + float confidence_threshold = 1; + + // Output only. Recall under the given confidence threshold. + float recall = 3; + + // Output only. Precision under the given confidence threshold. + float precision = 4; + + // Output only. The harmonic mean of recall and precision. + float f1_score = 5; + } + + // Output only. The Area under precision recall curve metric. + float au_prc = 1; + + // Output only. Metrics that have confidence thresholds. + // Precision-recall curve can be derived from it. + repeated ConfidenceMetricsEntry confidence_metrics_entries = 2; +} diff --git a/google/cloud/automl/v1beta1/text_segment.proto b/google/cloud/automl/v1beta1/text_segment.proto new file mode 100644 index 000000000..d170cc33f --- /dev/null +++ b/google/cloud/automl/v1beta1/text_segment.proto @@ -0,0 +1,43 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "TextSegmentProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// A contiguous part of a text (string), assuming it has an UTF-8 NFC encoding. +// . +message TextSegment { + // Output only. The content of the TextSegment. + string content = 3; + + // Required. Zero-based character index of the first character of the text + // segment (counting characters from the beginning of the text). + int64 start_offset = 1; + + // Required. Zero-based character index of the first character past the end of + // the text segment (counting character from the beginning of the text). + // The character at the end_offset is NOT included in the text segment. + int64 end_offset = 2; +} diff --git a/google/cloud/automl/v1beta1/text_sentiment.proto b/google/cloud/automl/v1beta1/text_sentiment.proto new file mode 100644 index 000000000..22c26cf72 --- /dev/null +++ b/google/cloud/automl/v1beta1/text_sentiment.proto @@ -0,0 +1,84 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/classification.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_outer_classname = "TextSentimentProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Contains annotation details specific to text sentiment. +message TextSentimentAnnotation { + // Output only. The sentiment with the semantic, as given to the + // [AutoMl.ImportData][google.cloud.automl.v1beta1.AutoMl.ImportData] when populating the dataset from which the model used + // for the prediction had been trained. + // The sentiment values are between 0 and + // Dataset.text_sentiment_dataset_metadata.sentiment_max (inclusive), + // with higher value meaning more positive sentiment. They are completely + // relative, i.e. 0 means least positive sentiment and sentiment_max means + // the most positive from the sentiments present in the train data. Therefore + // e.g. if train data had only negative sentiment, then sentiment_max, would + // be still negative (although least negative). + // The sentiment shouldn't be confused with "score" or "magnitude" + // from the previous Natural Language Sentiment Analysis API. + int32 sentiment = 1; +} + +// Model evaluation metrics for text sentiment problems. +message TextSentimentEvaluationMetrics { + // Output only. Precision. + float precision = 1; + + // Output only. Recall. + float recall = 2; + + // Output only. The harmonic mean of recall and precision. + float f1_score = 3; + + // Output only. Mean absolute error. Only set for the overall model + // evaluation, not for evaluation of a single annotation spec. + float mean_absolute_error = 4; + + // Output only. Mean squared error. Only set for the overall model + // evaluation, not for evaluation of a single annotation spec. + float mean_squared_error = 5; + + // Output only. Linear weighted kappa. Only set for the overall model + // evaluation, not for evaluation of a single annotation spec. + float linear_kappa = 6; + + // Output only. Quadratic weighted kappa. Only set for the overall model + // evaluation, not for evaluation of a single annotation spec. + float quadratic_kappa = 7; + + // Output only. Confusion matrix of the evaluation. + // Only set for the overall model evaluation, not for evaluation of a single + // annotation spec. + ClassificationEvaluationMetrics.ConfusionMatrix confusion_matrix = 8; + + // Output only. The annotation spec ids used for this evaluation. + // Deprecated, remove after Boq Migration and use then + // TextSentimentModelMetadata.annotation_spec_count for count, and list + // all model evaluations to see the exact annotation_spec_ids that were + // used. + repeated string annotation_spec_id = 9; +} diff --git a/google/cloud/automl/v1beta1/translation.proto b/google/cloud/automl/v1beta1/translation.proto new file mode 100644 index 000000000..92dfab03e --- /dev/null +++ b/google/cloud/automl/v1beta1/translation.proto @@ -0,0 +1,69 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/data_items.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "TranslationProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Dataset metadata that is specific to translation. +message TranslationDatasetMetadata { + // Required. The BCP-47 language code of the source language. + string source_language_code = 1; + + // Required. The BCP-47 language code of the target language. + string target_language_code = 2; +} + +// Evaluation metrics for the dataset. +message TranslationEvaluationMetrics { + // Output only. BLEU score. + double bleu_score = 1; + + // Output only. BLEU score for base model. + double base_bleu_score = 2; +} + +// Model metadata that is specific to translation. +message TranslationModelMetadata { + // The resource name of the model to use as a baseline to train the custom + // model. If unset, we use the default base model provided by Google + // Translate. Format: + // `projects/{project_id}/locations/{location_id}/models/{model_id}` + string base_model = 1; + + // Output only. Inferred from the dataset. + // The source languge (The BCP-47 language code) that is used for training. + string source_language_code = 2; + + // Output only. The target languge (The BCP-47 language code) that is used for + // training. + string target_language_code = 3; +} + +// Annotation details specific to translation. +message TranslationAnnotation { + // Output only . The translated content. + TextSnippet translated_content = 1; +} diff --git a/google/cloud/automl/v1beta1/video.proto b/google/cloud/automl/v1beta1/video.proto new file mode 100644 index 000000000..e4146b713 --- /dev/null +++ b/google/cloud/automl/v1beta1/video.proto @@ -0,0 +1,39 @@ +// Copyright 2018 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.automl.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/automl/v1beta1/classification.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl"; +option java_multiple_files = true; +option java_outer_classname = "VideoProto"; +option java_package = "com.google.cloud.automl.v1beta1"; +option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1"; + + +// Dataset metadata specific to video classification. +// All Video Classification datasets are treated as multi label. +message VideoClassificationDatasetMetadata { + +} + +// Model metadata specific to video classification. +message VideoClassificationModelMetadata { + +} diff --git a/google/cloud/bigquery/artman_bigquery_v2.yaml b/google/cloud/bigquery/artman_bigquery_v2.yaml new file mode 100644 index 000000000..426a197a8 --- /dev/null +++ b/google/cloud/bigquery/artman_bigquery_v2.yaml @@ -0,0 +1,34 @@ +common: + api_name: bigquery + api_version: v2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v2 + service_yaml: bigquery_v2.yaml + gapic_yaml: v2/bigquery_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/bigquery/bigquery_v2.yaml b/google/cloud/bigquery/bigquery_v2.yaml new file mode 100644 index 000000000..f6ffefee7 --- /dev/null +++ b/google/cloud/bigquery/bigquery_v2.yaml @@ -0,0 +1,35 @@ +type: google.api.Service +config_version: 2 +name: bigquery.googleapis.com +title: BigQuery API + +apis: +- name: google.cloud.bigquery.v2.ModelService + +documentation: + summary: 'A data platform for customers to create, manage, share and query data.' + +authentication: + rules: + - selector: google.cloud.bigquery.v2.ModelService.DeleteModel + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/bigquery, + https://www.googleapis.com/auth/cloud-platform + - selector: google.cloud.bigquery.v2.ModelService.GetModel + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/bigquery, + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-platform.read-only + - selector: google.cloud.bigquery.v2.ModelService.ListModels + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/bigquery, + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-platform.read-only + - selector: google.cloud.bigquery.v2.ModelService.PatchModel + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/bigquery, + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/bigquery/datatransfer/BUILD.bazel b/google/cloud/bigquery/datatransfer/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/bigquery/datatransfer/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/bigquery/datatransfer/artman_bigquerydatatransfer.yaml b/google/cloud/bigquery/datatransfer/artman_bigquerydatatransfer.yaml new file mode 100644 index 000000000..6e3950d8c --- /dev/null +++ b/google/cloud/bigquery/datatransfer/artman_bigquerydatatransfer.yaml @@ -0,0 +1,34 @@ +common: + api_name: bigquerydatatransfer + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: datatransfer.yaml + gapic_yaml: v1/bigquerydatatransfer_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/bigquery/datatransfer/datatransfer.yaml b/google/cloud/bigquery/datatransfer/datatransfer.yaml new file mode 100644 index 000000000..9879bbf37 --- /dev/null +++ b/google/cloud/bigquery/datatransfer/datatransfer.yaml @@ -0,0 +1,19 @@ +type: google.api.Service +config_version: 3 +name: bigquerydatatransfer.googleapis.com +title: BigQuery Data Transfer API + +apis: +- name: google.cloud.bigquery.datatransfer.v1.DataTransferService + +documentation: + summary: |- + Transfers data from partner SaaS applications to Google BigQuery on a + scheduled, managed basis. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/bigquery/datatransfer/v1/BUILD.bazel b/google/cloud/bigquery/datatransfer/v1/BUILD.bazel new file mode 100644 index 000000000..d4270c451 --- /dev/null +++ b/google/cloud/bigquery/datatransfer/v1/BUILD.bazel @@ -0,0 +1,150 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "bigquerydatatransfer_proto", + srcs = [ + ":datatransfer.proto", + ":transfer.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:struct_proto", + "@com_google_protobuf//:timestamp_proto", + "@com_google_protobuf//:wrappers_proto", + ], +) + +proto_library_with_info( + name = "bigquerydatatransfer_proto_with_info", + deps = [":bigquerydatatransfer_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "bigquerydatatransfer_java_proto", + deps = [":bigquerydatatransfer_proto"], +) + +java_grpc_library( + name = "bigquerydatatransfer_java_grpc", + srcs = [":bigquerydatatransfer_proto"], + deps = [":bigquerydatatransfer_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "bigquerydatatransfer_resource_name_java_proto", + gapic_yaml = "bigquerydatatransfer_gapic.yaml", + deps = [":bigquerydatatransfer_proto"], +) + +java_gapic_library( + name = "bigquerydatatransfer_java_gapic", + src = ":bigquerydatatransfer_proto_with_info", + gapic_yaml = "bigquerydatatransfer_gapic.yaml", + service_yaml = "//google/cloud/bigquery/datatransfer:datatransfer.yaml", + test_deps = [":bigquerydatatransfer_java_grpc"], + deps = [ + ":bigquerydatatransfer_java_proto", + ":bigquerydatatransfer_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":bigquerydatatransfer_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-bigquerydatatransfer-v1-java", + client_deps = [ + ":bigquerydatatransfer_java_gapic", + ], + client_group = "com.google.cloud", + client_test_deps = [ + ":bigquerydatatransfer_java_gapic_test", + ], + grpc_deps = [":bigquerydatatransfer_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":bigquerydatatransfer_java_proto", + ":bigquerydatatransfer_proto", + ":bigquerydatatransfer_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "bigquerydatatransfer_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/bigquery/datatransfer/v1", + protos = [":bigquerydatatransfer_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "bigquerydatatransfer_go_gapic", + src = ":bigquerydatatransfer_proto_with_info", + gapic_yaml = "bigquerydatatransfer_gapic.yaml", + importpath = "cloud.google.com/go/bigquery/datatransfer/apiv1", + service_yaml = "//google/cloud/bigquery/datatransfer:datatransfer.yaml", + deps = [":bigquerydatatransfer_go_proto"], +) + +go_test( + name = "bigquerydatatransfer_go_gapic_test", + srcs = [":bigquerydatatransfer_go_gapic_srcjar_test"], + embed = [":bigquerydatatransfer_go_gapic"], + importpath = "cloud.google.com/go/bigquery/datatransfer/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-bigquerydatatransfer-v1-go", + deps = [ + ":bigquerydatatransfer_go_gapic", + ":bigquerydatatransfer_go_gapic_srcjar-smoke-test.srcjar", + ":bigquerydatatransfer_go_gapic_srcjar-test.srcjar", + ":bigquerydatatransfer_go_proto", + ], +) diff --git a/google/cloud/bigquery/datatransfer/v1/bigquerydatatransfer_gapic.yaml b/google/cloud/bigquery/datatransfer/v1/bigquerydatatransfer_gapic.yaml new file mode 100644 index 000000000..8339c1988 --- /dev/null +++ b/google/cloud/bigquery/datatransfer/v1/bigquerydatatransfer_gapic.yaml @@ -0,0 +1,421 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.bigquery.datatransfer.v1 + python: + package_name: google.cloud.bigquery_datatransfer_v1.gapic + go: + package_name: cloud.google.com/go/bigquery/datatransfer/apiv1 + csharp: + package_name: Google.Cloud.BigQuery.DataTransfer.V1 + ruby: + package_name: Google::Cloud::Bigquery::DataTransfer::V1 + release_level: BETA + php: + package_name: Google\Cloud\BigQuery\DataTransfer\V1 + nodejs: + package_name: bigquery-data-transfer.v1 + domain_layer_location: google-cloud +collection_oneofs: +- oneof_name: parent_oneof + collection_names: + - project + - location +- oneof_name: data_source_oneof + collection_names: + - project_data_source + - location_data_source +- oneof_name: transfer_config_oneof + collection_names: + - project_transfer_config + - location_transfer_config +- oneof_name: run_oneof + collection_names: + - project_run + - location_run +collections: +- name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName +- name_pattern: projects/{project}/locations/{location} + entity_name: location +- name_pattern: projects/{project}/dataSources/{data_source} + entity_name: project_data_source +- name_pattern: projects/{project}/locations/{location}/dataSources/{data_source} + entity_name: location_data_source +- name_pattern: projects/{project}/transferConfigs/{transfer_config} + entity_name: project_transfer_config +- name_pattern: projects/{project}/locations/{location}/transferConfigs/{transfer_config} + entity_name: location_transfer_config +- name_pattern: projects/{project}/transferConfigs/{transfer_config}/runs/{run} + entity_name: project_run +- name_pattern: projects/{project}/locations/{location}/transferConfigs/{transfer_config}/runs/{run} + entity_name: location_run +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.bigquery.datatransfer.v1.DataTransferService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + # Definition for smoke test. + smoke_test: + method: ListDataSources + init_fields: + - parent%project=$PROJECT_ID + - parent%location="us-central1" + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the + # resource name formats defined in the field_name_patterns + # and response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: GetDataSource + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: data_source_oneof + timeout_millis: 20000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - name + - name: ListDataSources + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: data_sources + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: parent_oneof + timeout_millis: 20000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - parent + - name: CreateTransferConfig + flattening: + groups: + - parameters: + - parent + - transfer_config + required_fields: + - parent + - transfer_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: parent_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - parent + - name: UpdateTransferConfig + flattening: + groups: + - parameters: + - transfer_config + - update_mask + required_fields: + - transfer_config + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + transfer_config.name: transfer_config_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - transfer_config.name + - name: DeleteTransferConfig + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: transfer_config_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - name + - name: GetTransferConfig + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: transfer_config_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - name + - name: ListTransferConfigs + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: transfer_configs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: parent_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - parent + - name: ScheduleTransferRuns + flattening: + groups: + - parameters: + - parent + - start_time + - end_time + required_fields: + - parent + - start_time + - end_time + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: transfer_config_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - parent + - name: GetTransferRun + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: run_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - name + - name: DeleteTransferRun + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: run_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - name + - name: ListTransferRuns + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: transfer_runs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: transfer_config_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - parent + - name: ListTransferLogs + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: transfer_messages + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: run_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - parent + - name: CheckValidCreds + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: data_source_oneof + timeout_millis: 30000 + resource_name_treatment: STATIC_TYPES + header_request_params: + - name +resource_name_generation: +- message_name: GetDataSourceRequest + field_entity_map: + name: data_source_oneof +- message_name: ListDataSourcesRequest + field_entity_map: + parent: parent_oneof +- message_name: CreateTransferConfigRequest + field_entity_map: + parent: parent_oneof +- message_name: GetTransferConfigRequest + field_entity_map: + name: transfer_config_oneof +- message_name: DeleteTransferConfigRequest + field_entity_map: + name: transfer_config_oneof +- message_name: GetTransferRunRequest + field_entity_map: + name: run_oneof +- message_name: DeleteTransferRunRequest + field_entity_map: + name: run_oneof +- message_name: ListTransferConfigsRequest + field_entity_map: + parent: parent_oneof +- message_name: ListTransferRunsRequest + field_entity_map: + parent: transfer_config_oneof +- message_name: ListTransferLogsRequest + field_entity_map: + parent: run_oneof +- message_name: CheckValidCredsRequest + field_entity_map: + name: data_source_oneof +- message_name: ScheduleTransferRunsRequest + field_entity_map: + parent: transfer_config_oneof +- message_name: DataSource + field_entity_map: + name: data_source_oneof +- message_name: TransferConfig + field_entity_map: + name: transfer_config_oneof +- message_name: TransferRun + field_entity_map: + name: run_oneof diff --git a/google/cloud/bigquery/datatransfer/v1/datatransfer.proto b/google/cloud/bigquery/datatransfer/v1/datatransfer.proto new file mode 100644 index 000000000..2f82669ec --- /dev/null +++ b/google/cloud/bigquery/datatransfer/v1/datatransfer.proto @@ -0,0 +1,652 @@ +// Copyright 2018 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.bigquery.datatransfer.v1; + +import "google/api/annotations.proto"; +import "google/cloud/bigquery/datatransfer/v1/transfer.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; + +option csharp_namespace = "Google.Cloud.BigQuery.DataTransfer.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/datatransfer/v1;datatransfer"; +option java_multiple_files = true; +option java_outer_classname = "DataTransferProto"; +option java_package = "com.google.cloud.bigquery.datatransfer.v1"; +option php_namespace = "Google\\Cloud\\BigQuery\\DataTransfer\\V1"; + +// The Google BigQuery Data Transfer Service API enables BigQuery users to +// configure the transfer of their data from other Google Products into +// BigQuery. This service contains methods that are end user exposed. It backs +// up the frontend. +service DataTransferService { + // Retrieves a supported data source and returns its settings, + // which can be used for UI rendering. + rpc GetDataSource(GetDataSourceRequest) returns (DataSource) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/dataSources/*}" + additional_bindings { get: "/v1/{name=projects/*/dataSources/*}" } + }; + } + + // Lists supported data sources and returns their settings, + // which can be used for UI rendering. + rpc ListDataSources(ListDataSourcesRequest) + returns (ListDataSourcesResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/dataSources" + additional_bindings { get: "/v1/{parent=projects/*}/dataSources" } + }; + } + + // Creates a new data transfer configuration. + rpc CreateTransferConfig(CreateTransferConfigRequest) + returns (TransferConfig) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/transferConfigs" + body: "transfer_config" + additional_bindings { + post: "/v1/{parent=projects/*}/transferConfigs" + body: "transfer_config" + } + }; + } + + // Updates a data transfer configuration. + // All fields must be set, even if they are not updated. + rpc UpdateTransferConfig(UpdateTransferConfigRequest) + returns (TransferConfig) { + option (google.api.http) = { + patch: "/v1/{transfer_config.name=projects/*/locations/*/transferConfigs/*}" + body: "transfer_config" + additional_bindings { + patch: "/v1/{transfer_config.name=projects/*/transferConfigs/*}" + body: "transfer_config" + } + }; + } + + // Deletes a data transfer configuration, + // including any associated transfer runs and logs. + rpc DeleteTransferConfig(DeleteTransferConfigRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/transferConfigs/*}" + additional_bindings { delete: "/v1/{name=projects/*/transferConfigs/*}" } + }; + } + + // Returns information about a data transfer config. + rpc GetTransferConfig(GetTransferConfigRequest) returns (TransferConfig) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/transferConfigs/*}" + additional_bindings { get: "/v1/{name=projects/*/transferConfigs/*}" } + }; + } + + // Returns information about all data transfers in the project. + rpc ListTransferConfigs(ListTransferConfigsRequest) + returns (ListTransferConfigsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/transferConfigs" + additional_bindings { get: "/v1/{parent=projects/*}/transferConfigs" } + }; + } + + // Creates transfer runs for a time range [start_time, end_time]. + // For each date - or whatever granularity the data source supports - in the + // range, one transfer run is created. + // Note that runs are created per UTC time in the time range. + rpc ScheduleTransferRuns(ScheduleTransferRunsRequest) + returns (ScheduleTransferRunsResponse) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*/transferConfigs/*}:scheduleRuns" + body: "*" + additional_bindings { + post: "/v1/{parent=projects/*/transferConfigs/*}:scheduleRuns" + body: "*" + } + }; + } + + // Returns information about the particular transfer run. + rpc GetTransferRun(GetTransferRunRequest) returns (TransferRun) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/transferConfigs/*/runs/*}" + additional_bindings { + get: "/v1/{name=projects/*/transferConfigs/*/runs/*}" + } + }; + } + + // Deletes the specified transfer run. + rpc DeleteTransferRun(DeleteTransferRunRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/transferConfigs/*/runs/*}" + additional_bindings { + delete: "/v1/{name=projects/*/transferConfigs/*/runs/*}" + } + }; + } + + // Returns information about running and completed jobs. + rpc ListTransferRuns(ListTransferRunsRequest) + returns (ListTransferRunsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*/transferConfigs/*}/runs" + additional_bindings { + get: "/v1/{parent=projects/*/transferConfigs/*}/runs" + } + }; + } + + // Returns user facing log messages for the data transfer run. + rpc ListTransferLogs(ListTransferLogsRequest) + returns (ListTransferLogsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*/transferConfigs/*/runs/*}/transferLogs" + additional_bindings { + get: "/v1/{parent=projects/*/transferConfigs/*/runs/*}/transferLogs" + } + }; + } + + // Returns true if valid credentials exist for the given data source and + // requesting user. + // Some data sources doesn't support service account, so we need to talk to + // them on behalf of the end user. This API just checks whether we have OAuth + // token for the particular user, which is a pre-requisite before user can + // create a transfer config. + rpc CheckValidCreds(CheckValidCredsRequest) + returns (CheckValidCredsResponse) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/dataSources/*}:checkValidCreds" + body: "*" + additional_bindings { + post: "/v1/{name=projects/*/dataSources/*}:checkValidCreds" + body: "*" + } + }; + } +} + +// Represents a data source parameter with validation rules, so that +// parameters can be rendered in the UI. These parameters are given to us by +// supported data sources, and include all needed information for rendering +// and validation. +// Thus, whoever uses this api can decide to generate either generic ui, +// or custom data source specific forms. +message DataSourceParameter { + // Parameter type. + enum Type { + // Type unspecified. + TYPE_UNSPECIFIED = 0; + + // String parameter. + STRING = 1; + + // Integer parameter (64-bits). + // Will be serialized to json as string. + INTEGER = 2; + + // Double precision floating point parameter. + DOUBLE = 3; + + // Boolean parameter. + BOOLEAN = 4; + + // Record parameter. + RECORD = 5; + + // Page ID for a Google+ Page. + PLUS_PAGE = 6; + } + + // Parameter identifier. + string param_id = 1; + + // Parameter display name in the user interface. + string display_name = 2; + + // Parameter description. + string description = 3; + + // Parameter type. + Type type = 4; + + // Is parameter required. + bool required = 5; + + // Can parameter have multiple values. + bool repeated = 6; + + // Regular expression which can be used for parameter validation. + string validation_regex = 7; + + // All possible values for the parameter. + repeated string allowed_values = 8; + + // For integer and double values specifies minimum allowed value. + google.protobuf.DoubleValue min_value = 9; + + // For integer and double values specifies maxminum allowed value. + google.protobuf.DoubleValue max_value = 10; + + // When parameter is a record, describes child fields. + repeated DataSourceParameter fields = 11; + + // Description of the requirements for this field, in case the user input does + // not fulfill the regex pattern or min/max values. + string validation_description = 12; + + // URL to a help document to further explain the naming requirements. + string validation_help_url = 13; + + // Cannot be changed after initial creation. + bool immutable = 14; + + // If set to true, schema should be taken from the parent with the same + // parameter_id. Only applicable when parameter type is RECORD. + bool recurse = 15; +} + +// Represents data source metadata. Metadata is sufficient to +// render UI and request proper OAuth tokens. +message DataSource { + // The type of authorization needed for this data source. + enum AuthorizationType { + // Type unspecified. + AUTHORIZATION_TYPE_UNSPECIFIED = 0; + + // Use OAuth 2 authorization codes that can be exchanged + // for a refresh token on the backend. + AUTHORIZATION_CODE = 1; + + // Return an authorization code for a given Google+ page that can then be + // exchanged for a refresh token on the backend. + GOOGLE_PLUS_AUTHORIZATION_CODE = 2; + } + + // Represents how the data source supports data auto refresh. + enum DataRefreshType { + // The data source won't support data auto refresh, which is default value. + DATA_REFRESH_TYPE_UNSPECIFIED = 0; + + // The data source supports data auto refresh, and runs will be scheduled + // for the past few days. Does not allow custom values to be set for each + // transfer config. + SLIDING_WINDOW = 1; + + // The data source supports data auto refresh, and runs will be scheduled + // for the past few days. Allows custom values to be set for each transfer + // config. + CUSTOM_SLIDING_WINDOW = 2; + } + + // Output only. Data source resource name. + string name = 1; + + // Data source id. + string data_source_id = 2; + + // User friendly data source name. + string display_name = 3; + + // User friendly data source description string. + string description = 4; + + // Data source client id which should be used to receive refresh token. + // When not supplied, no offline credentials are populated for data transfer. + string client_id = 5; + + // Api auth scopes for which refresh token needs to be obtained. Only valid + // when `client_id` is specified. Ignored otherwise. These are scopes needed + // by a data source to prepare data and ingest them into BigQuery, + // e.g., https://www.googleapis.com/auth/bigquery + repeated string scopes = 6; + + // Deprecated. This field has no effect. + TransferType transfer_type = 7; + + // Indicates whether the data source supports multiple transfers + // to different BigQuery targets. + bool supports_multiple_transfers = 8; + + // The number of seconds to wait for an update from the data source + // before BigQuery marks the transfer as failed. + int32 update_deadline_seconds = 9; + + // Default data transfer schedule. + // Examples of valid schedules include: + // `1st,3rd monday of month 15:30`, + // `every wed,fri of jan,jun 13:15`, and + // `first sunday of quarter 00:00`. + string default_schedule = 10; + + // Specifies whether the data source supports a user defined schedule, or + // operates on the default schedule. + // When set to `true`, user can override default schedule. + bool supports_custom_schedule = 11; + + // Data source parameters. + repeated DataSourceParameter parameters = 12; + + // Url for the help document for this data source. + string help_url = 13; + + // Indicates the type of authorization. + AuthorizationType authorization_type = 14; + + // Specifies whether the data source supports automatic data refresh for the + // past few days, and how it's supported. + // For some data sources, data might not be complete until a few days later, + // so it's useful to refresh data automatically. + DataRefreshType data_refresh_type = 15; + + // Default data refresh window on days. + // Only meaningful when `data_refresh_type` = `SLIDING_WINDOW`. + int32 default_data_refresh_window_days = 16; + + // Disables backfilling and manual run scheduling + // for the data source. + bool manual_runs_disabled = 17; + + // The minimum interval for scheduler to schedule runs. + google.protobuf.Duration minimum_schedule_interval = 18; +} + +// A request to get data source info. +message GetDataSourceRequest { + // The field will contain name of the resource requested, for example: + // `projects/{project_id}/dataSources/{data_source_id}` + string name = 1; +} + +// Request to list supported data sources and their data transfer settings. +message ListDataSourcesRequest { + // The BigQuery project id for which data sources should be returned. + // Must be in the form: `projects/{project_id}` + string parent = 1; + + // Pagination token, which can be used to request a specific page + // of `ListDataSourcesRequest` list results. For multiple-page + // results, `ListDataSourcesResponse` outputs + // a `next_page` token, which can be used as the + // `page_token` value to request the next page of list results. + string page_token = 3; + + // Page size. The default page size is the maximum value of 1000 results. + int32 page_size = 4; +} + +// Returns list of supported data sources and their metadata. +message ListDataSourcesResponse { + // List of supported data sources and their transfer settings. + repeated DataSource data_sources = 1; + + // Output only. The next-pagination token. For multiple-page list results, + // this token can be used as the + // `ListDataSourcesRequest.page_token` + // to request the next page of list results. + string next_page_token = 2; +} + +// A request to create a data transfer configuration. If new credentials are +// needed for this transfer configuration, an authorization code must be +// provided. If an authorization code is provided, the transfer configuration +// will be associated with the user id corresponding to the +// authorization code. Otherwise, the transfer configuration will be associated +// with the calling user. +message CreateTransferConfigRequest { + // The BigQuery project id where the transfer configuration should be created. + // Must be in the format /projects/{project_id}/locations/{location_id} + // If specified location and location of the destination bigquery dataset + // do not match - the request will fail. + string parent = 1; + + // Data transfer configuration to create. + TransferConfig transfer_config = 2; + + // Optional OAuth2 authorization code to use with this transfer configuration. + // This is required if new credentials are needed, as indicated by + // `CheckValidCreds`. + // In order to obtain authorization_code, please make a + // request to + // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?client_id=<datatransferapiclientid>&scope=<data_source_scopes>&redirect_uri=<redirect_uri> + // + // * client_id should be OAuth client_id of BigQuery DTS API for the given + // data source returned by ListDataSources method. + // * data_source_scopes are the scopes returned by ListDataSources method. + // * redirect_uri is an optional parameter. If not specified, then + // authorization code is posted to the opener of authorization flow window. + // Otherwise it will be sent to the redirect uri. A special value of + // urn:ietf:wg:oauth:2.0:oob means that authorization code should be + // returned in the title bar of the browser, with the page text prompting + // the user to copy the code and paste it in the application. + string authorization_code = 3; +} + +// A request to update a transfer configuration. To update the user id of the +// transfer configuration, an authorization code needs to be provided. +message UpdateTransferConfigRequest { + // Data transfer configuration to create. + TransferConfig transfer_config = 1; + + // Optional OAuth2 authorization code to use with this transfer configuration. + // If it is provided, the transfer configuration will be associated with the + // authorizing user. + // In order to obtain authorization_code, please make a + // request to + // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?client_id=<datatransferapiclientid>&scope=<data_source_scopes>&redirect_uri=<redirect_uri> + // + // * client_id should be OAuth client_id of BigQuery DTS API for the given + // data source returned by ListDataSources method. + // * data_source_scopes are the scopes returned by ListDataSources method. + // * redirect_uri is an optional parameter. If not specified, then + // authorization code is posted to the opener of authorization flow window. + // Otherwise it will be sent to the redirect uri. A special value of + // urn:ietf:wg:oauth:2.0:oob means that authorization code should be + // returned in the title bar of the browser, with the page text prompting + // the user to copy the code and paste it in the application. + string authorization_code = 3; + + // Required list of fields to be updated in this request. + google.protobuf.FieldMask update_mask = 4; +} + +// A request to get data transfer information. +message GetTransferConfigRequest { + // The field will contain name of the resource requested, for example: + // `projects/{project_id}/transferConfigs/{config_id}` + string name = 1; +} + +// A request to delete data transfer information. All associated transfer runs +// and log messages will be deleted as well. +message DeleteTransferConfigRequest { + // The field will contain name of the resource requested, for example: + // `projects/{project_id}/transferConfigs/{config_id}` + string name = 1; +} + +// A request to get data transfer run information. +message GetTransferRunRequest { + // The field will contain name of the resource requested, for example: + // `projects/{project_id}/transferConfigs/{config_id}/runs/{run_id}` + string name = 1; +} + +// A request to delete data transfer run information. +message DeleteTransferRunRequest { + // The field will contain name of the resource requested, for example: + // `projects/{project_id}/transferConfigs/{config_id}/runs/{run_id}` + string name = 1; +} + +// A request to list data transfers configured for a BigQuery project. +message ListTransferConfigsRequest { + // The BigQuery project id for which data sources + // should be returned: `projects/{project_id}`. + string parent = 1; + + // When specified, only configurations of requested data sources are returned. + repeated string data_source_ids = 2; + + // Pagination token, which can be used to request a specific page + // of `ListTransfersRequest` list results. For multiple-page + // results, `ListTransfersResponse` outputs + // a `next_page` token, which can be used as the + // `page_token` value to request the next page of list results. + string page_token = 3; + + // Page size. The default page size is the maximum value of 1000 results. + int32 page_size = 4; +} + +// The returned list of pipelines in the project. +message ListTransferConfigsResponse { + // Output only. The stored pipeline transfer configurations. + repeated TransferConfig transfer_configs = 1; + + // Output only. The next-pagination token. For multiple-page list results, + // this token can be used as the + // `ListTransferConfigsRequest.page_token` + // to request the next page of list results. + string next_page_token = 2; +} + +// A request to list data transfer runs. UI can use this method to show/filter +// specific data transfer runs. The data source can use this method to request +// all scheduled transfer runs. +message ListTransferRunsRequest { + // Represents which runs should be pulled. + enum RunAttempt { + // All runs should be returned. + RUN_ATTEMPT_UNSPECIFIED = 0; + + // Only latest run per day should be returned. + LATEST = 1; + } + + // Name of transfer configuration for which transfer runs should be retrieved. + // Format of transfer configuration resource name is: + // `projects/{project_id}/transferConfigs/{config_id}`. + string parent = 1; + + // When specified, only transfer runs with requested states are returned. + repeated TransferState states = 2; + + // Pagination token, which can be used to request a specific page + // of `ListTransferRunsRequest` list results. For multiple-page + // results, `ListTransferRunsResponse` outputs + // a `next_page` token, which can be used as the + // `page_token` value to request the next page of list results. + string page_token = 3; + + // Page size. The default page size is the maximum value of 1000 results. + int32 page_size = 4; + + // Indicates how run attempts are to be pulled. + RunAttempt run_attempt = 5; +} + +// The returned list of pipelines in the project. +message ListTransferRunsResponse { + // Output only. The stored pipeline transfer runs. + repeated TransferRun transfer_runs = 1; + + // Output only. The next-pagination token. For multiple-page list results, + // this token can be used as the + // `ListTransferRunsRequest.page_token` + // to request the next page of list results. + string next_page_token = 2; +} + +// A request to get user facing log messages associated with data transfer run. +message ListTransferLogsRequest { + // Transfer run name in the form: + // `projects/{project_id}/transferConfigs/{config_Id}/runs/{run_id}`. + string parent = 1; + + // Pagination token, which can be used to request a specific page + // of `ListTransferLogsRequest` list results. For multiple-page + // results, `ListTransferLogsResponse` outputs + // a `next_page` token, which can be used as the + // `page_token` value to request the next page of list results. + string page_token = 4; + + // Page size. The default page size is the maximum value of 1000 results. + int32 page_size = 5; + + // Message types to return. If not populated - INFO, WARNING and ERROR + // messages are returned. + repeated TransferMessage.MessageSeverity message_types = 6; +} + +// The returned list transfer run messages. +message ListTransferLogsResponse { + // Output only. The stored pipeline transfer messages. + repeated TransferMessage transfer_messages = 1; + + // Output only. The next-pagination token. For multiple-page list results, + // this token can be used as the + // `GetTransferRunLogRequest.page_token` + // to request the next page of list results. + string next_page_token = 2; +} + +// A request to determine whether the user has valid credentials. This method +// is used to limit the number of OAuth popups in the user interface. The +// user id is inferred from the API call context. +// If the data source has the Google+ authorization type, this method +// returns false, as it cannot be determined whether the credentials are +// already valid merely based on the user id. +message CheckValidCredsRequest { + // The data source in the form: + // `projects/{project_id}/dataSources/{data_source_id}` + string name = 1; +} + +// A response indicating whether the credentials exist and are valid. +message CheckValidCredsResponse { + // If set to `true`, the credentials exist and are valid. + bool has_valid_creds = 1; +} + +// A request to schedule transfer runs for a time range. +message ScheduleTransferRunsRequest { + // Transfer configuration name in the form: + // `projects/{project_id}/transferConfigs/{config_id}`. + string parent = 1; + + // Start time of the range of transfer runs. For example, + // `"2017-05-25T00:00:00+00:00"`. + google.protobuf.Timestamp start_time = 2; + + // End time of the range of transfer runs. For example, + // `"2017-05-30T00:00:00+00:00"`. + google.protobuf.Timestamp end_time = 3; +} + +// A response to schedule transfer runs for a time range. +message ScheduleTransferRunsResponse { + // The transfer runs that were scheduled. + repeated TransferRun runs = 1; +} diff --git a/google/cloud/bigquery/datatransfer/v1/transfer.proto b/google/cloud/bigquery/datatransfer/v1/transfer.proto new file mode 100644 index 000000000..09e3c2ddd --- /dev/null +++ b/google/cloud/bigquery/datatransfer/v1/transfer.proto @@ -0,0 +1,221 @@ +// Copyright 2018 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.bigquery.datatransfer.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.BigQuery.DataTransfer.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/datatransfer/v1;datatransfer"; +option java_multiple_files = true; +option java_outer_classname = "TransferProto"; +option java_package = "com.google.cloud.bigquery.datatransfer.v1"; +option objc_class_prefix = "GCBDT"; +option php_namespace = "Google\\Cloud\\BigQuery\\DataTransfer\\V1"; + +// Represents a data transfer configuration. A transfer configuration +// contains all metadata needed to perform a data transfer. For example, +// `destination_dataset_id` specifies where data should be stored. +// When a new transfer configuration is created, the specified +// `destination_dataset_id` is created when needed and shared with the +// appropriate data source service account. +message TransferConfig { + // The resource name of the transfer config. + // Transfer config names have the form + // `projects/{project_id}/transferConfigs/{config_id}`. + // Where `config_id` is usually a uuid, even though it is not + // guaranteed or required. The name is ignored when creating a transfer + // config. + string name = 1; + + // The BigQuery target dataset id. + string destination_dataset_id = 2; + + // User specified display name for the data transfer. + string display_name = 3; + + // Data source id. Cannot be changed once data transfer is created. + string data_source_id = 5; + + // Data transfer specific parameters. + google.protobuf.Struct params = 9; + + // Data transfer schedule. + // If the data source does not support a custom schedule, this should be + // empty. If it is empty, the default value for the data source will be + // used. + // The specified times are in UTC. + // Examples of valid format: + // `1st,3rd monday of month 15:30`, + // `every wed,fri of jan,jun 13:15`, and + // `first sunday of quarter 00:00`. + // See more explanation about the format here: + // https://cloud.google.com/appengine/docs/flexible/python/scheduling-jobs-with-cron-yaml#the_schedule_format + // NOTE: the granularity should be at least 8 hours, or less frequent. + string schedule = 7; + + // The number of days to look back to automatically refresh the data. + // For example, if `data_refresh_window_days = 10`, then every day + // BigQuery reingests data for [today-10, today-1], rather than ingesting data + // for just [today-1]. + // Only valid if the data source supports the feature. Set the value to 0 + // to use the default value. + int32 data_refresh_window_days = 12; + + // Is this config disabled. When set to true, no runs are scheduled + // for a given transfer. + bool disabled = 13; + + // Output only. Data transfer modification time. Ignored by server on input. + google.protobuf.Timestamp update_time = 4; + + // Output only. Next time when data transfer will run. + google.protobuf.Timestamp next_run_time = 8; + + // Output only. State of the most recently updated transfer run. + TransferState state = 10; + + // Output only. Unique ID of the user on whose behalf transfer is done. + // Applicable only to data sources that do not support service accounts. + // When set to 0, the data source service account credentials are used. + // May be negative. Note, that this identifier is not stable. + // It may change over time even for the same user. + int64 user_id = 11; + + // Output only. Region in which BigQuery dataset is located. + string dataset_region = 14; +} + +// Represents a data transfer run. +message TransferRun { + // The resource name of the transfer run. + // Transfer run names have the form + // `projects/{project_id}/locations/{location}/transferConfigs/{config_id}/runs/{run_id}`. + // The name is ignored when creating a transfer run. + string name = 1; + + // Minimum time after which a transfer run can be started. + google.protobuf.Timestamp schedule_time = 3; + + // For batch transfer runs, specifies the date and time that + // data should be ingested. + google.protobuf.Timestamp run_time = 10; + + // Status of the transfer run. + google.rpc.Status error_status = 21; + + // Output only. Time when transfer run was started. + // Parameter ignored by server for input requests. + google.protobuf.Timestamp start_time = 4; + + // Output only. Time when transfer run ended. + // Parameter ignored by server for input requests. + google.protobuf.Timestamp end_time = 5; + + // Output only. Last time the data transfer run state was updated. + google.protobuf.Timestamp update_time = 6; + + // Output only. Data transfer specific parameters. + google.protobuf.Struct params = 9; + + // Output only. The BigQuery target dataset id. + string destination_dataset_id = 2; + + // Output only. Data source id. + string data_source_id = 7; + + // Data transfer run state. Ignored for input requests. + TransferState state = 8; + + // Output only. Unique ID of the user on whose behalf transfer is done. + // Applicable only to data sources that do not support service accounts. + // When set to 0, the data source service account credentials are used. + // May be negative. Note, that this identifier is not stable. + // It may change over time even for the same user. + int64 user_id = 11; + + // Output only. Describes the schedule of this transfer run if it was + // created as part of a regular schedule. For batch transfer runs that are + // scheduled manually, this is empty. + // NOTE: the system might choose to delay the schedule depending on the + // current load, so `schedule_time` doesn't always matches this. + string schedule = 12; +} + +// Represents a user facing message for a particular data transfer run. +message TransferMessage { + // Represents data transfer user facing message severity. + enum MessageSeverity { + // No severity specified. + MESSAGE_SEVERITY_UNSPECIFIED = 0; + + // Informational message. + INFO = 1; + + // Warning message. + WARNING = 2; + + // Error message. + ERROR = 3; + } + + // Time when message was logged. + google.protobuf.Timestamp message_time = 1; + + // Message severity. + MessageSeverity severity = 2; + + // Message text. + string message_text = 3; +} + +// DEPRECATED. Represents data transfer type. +enum TransferType { + // Invalid or Unknown transfer type placeholder. + TRANSFER_TYPE_UNSPECIFIED = 0; + + // Batch data transfer. + BATCH = 1; + + // Streaming data transfer. Streaming data source currently doesn't + // support multiple transfer configs per project. + STREAMING = 2; +} + +// Represents data transfer run state. +enum TransferState { + // State placeholder. + TRANSFER_STATE_UNSPECIFIED = 0; + + // Data transfer is scheduled and is waiting to be picked up by + // data transfer backend. + PENDING = 2; + + // Data transfer is in progress. + RUNNING = 3; + + // Data transfer completed successsfully. + SUCCEEDED = 4; + + // Data transfer failed. + FAILED = 5; + + // Data transfer is cancelled. + CANCELLED = 6; +} diff --git a/google/cloud/bigquery/logging/v1/audit_data.proto b/google/cloud/bigquery/logging/v1/audit_data.proto new file mode 100644 index 000000000..0031521c9 --- /dev/null +++ b/google/cloud/bigquery/logging/v1/audit_data.proto @@ -0,0 +1,524 @@ +// 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.bigquery.logging.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/logging/v1;logging"; +option java_multiple_files = true; +option java_outer_classname = "AuditDataProto"; +option java_package = "com.google.cloud.bigquery.logging.v1"; + +// BigQuery request and response messages for audit log. +// Note: `Table.schema` has been deprecated in favor of `Table.schemaJson`. +// `Table.schema` may continue to be present in your logs during this +// transition. +message AuditData { + // Request data for each BigQuery method. + oneof request { + // Table insert request. + TableInsertRequest table_insert_request = 1; + + // Table update request. + TableUpdateRequest table_update_request = 16; + + // Dataset list request. + DatasetListRequest dataset_list_request = 2; + + // Dataset insert request. + DatasetInsertRequest dataset_insert_request = 3; + + // Dataset update request. + DatasetUpdateRequest dataset_update_request = 4; + + // Job insert request. + JobInsertRequest job_insert_request = 5; + + // Job query request. + JobQueryRequest job_query_request = 6; + + // Job get query results request. + JobGetQueryResultsRequest job_get_query_results_request = 7; + + // Table data-list request. + TableDataListRequest table_data_list_request = 8; + } + + // Response data for each BigQuery method. + oneof response { + // Table insert response. + TableInsertResponse table_insert_response = 9; + + // Table update response. + TableUpdateResponse table_update_response = 10; + + // Dataset insert response. + DatasetInsertResponse dataset_insert_response = 11; + + // Dataset update response. + DatasetUpdateResponse dataset_update_response = 12; + + // Job insert response. + JobInsertResponse job_insert_response = 18; + + // Job query response. + JobQueryResponse job_query_response = 13; + + // Job get query results response. + JobGetQueryResultsResponse job_get_query_results_response = 14; + + // Deprecated: Job query-done response. Use this information for usage + // analysis. + JobQueryDoneResponse job_query_done_response = 15; + } + + // A job completion event. + JobCompletedEvent job_completed_event = 17; +} + +// Table insert request. +message TableInsertRequest { + // The new table. + Table resource = 1; +} + +// Table update request. +message TableUpdateRequest { + // The table to be updated. + Table resource = 1; +} + +// Table insert response. +message TableInsertResponse { + // Final state of the inserted table. + Table resource = 1; +} + +// Table update response. +message TableUpdateResponse { + // Final state of the updated table. + Table resource = 1; +} + +// Dataset list request. +message DatasetListRequest { + // Whether to list all datasets, including hidden ones. + bool list_all = 1; +} + +// Dataset insert request. +message DatasetInsertRequest { + // The dataset to be inserted. + Dataset resource = 1; +} + +// Dataset insert response. +message DatasetInsertResponse { + // Final state of the inserted dataset. + Dataset resource = 1; +} + +// Dataset update request. +message DatasetUpdateRequest { + // The dataset to be updated. + Dataset resource = 1; +} + +// Dataset update response. +message DatasetUpdateResponse { + // Final state of the updated dataset. + Dataset resource = 1; +} + +// Job insert request. +message JobInsertRequest { + // Job insert request. + Job resource = 1; +} + +// Job insert response. +message JobInsertResponse { + // Job insert response. + Job resource = 1; +} + +// Job query request. +message JobQueryRequest { + // The query. + string query = 1; + + // The maximum number of results. + uint32 max_results = 2; + + // The default dataset for tables that do not have a dataset specified. + DatasetName default_dataset = 3; + + // Project that the query should be charged to. + string project_id = 4; + + // If true, don't actually run the job. Just check that it would run. + bool dry_run = 5; +} + +// Job query response. +message JobQueryResponse { + // The total number of rows in the full query result set. + uint64 total_results = 1; + + // Information about the queried job. + Job job = 2; +} + +// Job getQueryResults request. +message JobGetQueryResultsRequest { + // Maximum number of results to return. + uint32 max_results = 1; + + // Zero-based row number at which to start. + uint64 start_row = 2; +} + +// Job getQueryResults response. +message JobGetQueryResultsResponse { + // Total number of results in query results. + uint64 total_results = 1; + + // The job that was created to run the query. + // It completed if `job.status.state` is `DONE`. + // It failed if `job.status.errorResult` is also present. + Job job = 2; +} + +// Job getQueryDone response. +message JobQueryDoneResponse { + // The job and status information. + // The job completed if `job.status.state` is `DONE`. + Job job = 1; +} + +// Query job completed event. +message JobCompletedEvent { + // Name of the event. + string event_name = 1; + + // Job information. + Job job = 2; +} + +// Table data-list request. +message TableDataListRequest { + // Starting row offset. + uint64 start_row = 1; + + // Maximum number of results to return. + uint32 max_results = 2; +} + +// Describes a BigQuery table. +// See the [Table](/bigquery/docs/reference/v2/tables) API resource +// for more details on individual fields. +// Note: `Table.schema` has been deprecated in favor of `Table.schemaJson`. +// `Table.schema` may continue to be present in your logs during this +// transition. +message Table { + // The name of the table. + TableName table_name = 1; + + // User-provided metadata for the table. + TableInfo info = 2; + + // A JSON representation of the table's schema. + string schema_json = 8; + + // If present, this is a virtual table defined by a SQL query. + TableViewDefinition view = 4; + + // The expiration date for the table, after which the table + // is deleted and the storage reclaimed. + // If not present, the table persists indefinitely. + google.protobuf.Timestamp expire_time = 5; + + // The time the table was created. + google.protobuf.Timestamp create_time = 6; + + // The time the table was last truncated + // by an operation with a `writeDisposition` of `WRITE_TRUNCATE`. + google.protobuf.Timestamp truncate_time = 7; +} + +// User-provided metadata for a table. +message TableInfo { + // A short name for the table, such as`"Analytics Data - Jan 2011"`. + string friendly_name = 1; + + // A long description, perhaps several paragraphs, + // describing the table contents in detail. + string description = 2; +} + +// Describes a virtual table defined by a SQL query. +message TableViewDefinition { + // SQL query defining the view. + string query = 1; +} + +// BigQuery dataset information. +// See the [Dataset](/bigquery/docs/reference/v2/datasets) API resource +// for more details on individual fields. +message Dataset { + // The name of the dataset. + DatasetName dataset_name = 1; + + // User-provided metadata for the dataset. + DatasetInfo info = 2; + + // The time the dataset was created. + google.protobuf.Timestamp create_time = 4; + + // The time the dataset was last modified. + google.protobuf.Timestamp update_time = 5; + + // The access control list for the dataset. + BigQueryAcl acl = 6; + + // If this field is present, each table that does not specify an + // expiration time is assigned an expiration time by adding this + // duration to the table's `createTime`. If this field is empty, + // there is no default table expiration time. + google.protobuf.Duration default_table_expire_duration = 8; +} + +// User-provided metadata for a dataset. +message DatasetInfo { + // A short name for the dataset, such as`"Analytics Data 2011"`. + string friendly_name = 1; + + // A long description, perhaps several paragraphs, + // describing the dataset contents in detail. + string description = 2; +} + +// An access control list. +message BigQueryAcl { + // Access control entry. + message Entry { + // The granted role, which can be `READER`, `WRITER`, or `OWNER`. + string role = 1; + + // Grants access to a group identified by an email address. + string group_email = 2; + + // Grants access to a user identified by an email address. + string user_email = 3; + + // Grants access to all members of a domain. + string domain = 4; + + // Grants access to special groups. Valid groups are `PROJECT_OWNERS`, + // `PROJECT_READERS`, `PROJECT_WRITERS` and `ALL_AUTHENTICATED_USERS`. + string special_group = 5; + + // Grants access to a BigQuery View. + TableName view_name = 6; + } + + // Access control entry list. + repeated Entry entries = 1; +} + +// Describes a job. +message Job { + // Job name. + JobName job_name = 1; + + // Job configuration. + JobConfiguration job_configuration = 2; + + // Job status. + JobStatus job_status = 3; + + // Job statistics. + JobStatistics job_statistics = 4; +} + +// Job configuration information. +// See the [Jobs](/bigquery/docs/reference/v2/jobs) API resource +// for more details on individual fields. +message JobConfiguration { + // Describes a query job, which executes a SQL-like query. + message Query { + // The SQL query to run. + string query = 1; + + // The table where results are written. + TableName destination_table = 2; + + // Describes when a job is allowed to create a table: + // `CREATE_IF_NEEDED`, `CREATE_NEVER`. + string create_disposition = 3; + + // Describes how writes affect existing tables: + // `WRITE_TRUNCATE`, `WRITE_APPEND`, `WRITE_EMPTY`. + string write_disposition = 4; + + // If a table name is specified without a dataset in a query, + // this dataset will be added to table name. + DatasetName default_dataset = 5; + + // Describes data sources outside BigQuery, if needed. + repeated TableDefinition table_definitions = 6; + } + + // Describes a load job, which loads data from an external source via + // the import pipeline. + message Load { + // URIs for the data to be imported. Only Google Cloud Storage URIs are + // supported. + repeated string source_uris = 1; + + // The table schema in JSON format representation of a TableSchema. + string schema_json = 6; + + // The table where the imported data is written. + TableName destination_table = 3; + + // Describes when a job is allowed to create a table: + // `CREATE_IF_NEEDED`, `CREATE_NEVER`. + string create_disposition = 4; + + // Describes how writes affect existing tables: + // `WRITE_TRUNCATE`, `WRITE_APPEND`, `WRITE_EMPTY`. + string write_disposition = 5; + } + + // Describes an extract job, which exports data to an external source + // via the export pipeline. + message Extract { + // Google Cloud Storage URIs where extracted data should be written. + repeated string destination_uris = 1; + + // The source table. + TableName source_table = 2; + } + + // Describes a copy job, which copies an existing table to another table. + message TableCopy { + // Source tables. + repeated TableName source_tables = 1; + + // Destination table. + TableName destination_table = 2; + + // Describes when a job is allowed to create a table: + // `CREATE_IF_NEEDED`, `CREATE_NEVER`. + string create_disposition = 3; + + // Describes how writes affect existing tables: + // `WRITE_TRUNCATE`, `WRITE_APPEND`, `WRITE_EMPTY`. + string write_disposition = 4; + } + + // Job configuration information. + oneof configuration { + // Query job information. + Query query = 5; + + // Load job information. + Load load = 6; + + // Extract job information. + Extract extract = 7; + + // TableCopy job information. + TableCopy table_copy = 8; + } + + // If true, don't actually run the job. Just check that it would run. + bool dry_run = 9; +} + +// Describes an external data source used in a query. +message TableDefinition { + // Name of the table, used in queries. + string name = 1; + + // Google Cloud Storage URIs for the data to be imported. + repeated string source_uris = 2; +} + +// Running state of a job. +message JobStatus { + // State of a job: `PENDING`, `RUNNING`, or `DONE`. + string state = 1; + + // If the job did not complete successfully, this field describes why. + google.rpc.Status error = 2; +} + +// Job statistics that may change after a job starts. +message JobStatistics { + // Time when the job was created. + google.protobuf.Timestamp create_time = 1; + + // Time when the job started. + google.protobuf.Timestamp start_time = 2; + + // Time when the job ended. + google.protobuf.Timestamp end_time = 3; + + // Total bytes processed for a job. + int64 total_processed_bytes = 4; + + // Processed bytes, adjusted by the job's CPU usage. + int64 total_billed_bytes = 5; + + // The tier assigned by CPU-based billing. + int32 billing_tier = 7; +} + +// The fully-qualified name for a dataset. +message DatasetName { + // The project ID. + string project_id = 1; + + // The dataset ID within the project. + string dataset_id = 2; +} + +// The fully-qualified name for a table. +message TableName { + // The project ID. + string project_id = 1; + + // The dataset ID within the project. + string dataset_id = 2; + + // The table ID of the table within the dataset. + string table_id = 3; +} + +// The fully-qualified name for a job. +message JobName { + // The project ID. + string project_id = 1; + + // The job ID within the project. + string job_id = 2; +} diff --git a/google/cloud/bigquery/storage/BUILD.bazel b/google/cloud/bigquery/storage/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/bigquery/storage/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/bigquery/storage/artman_bigquerystorage_v1beta1.yaml b/google/cloud/bigquery/storage/artman_bigquerystorage_v1beta1.yaml new file mode 100644 index 000000000..49e837efd --- /dev/null +++ b/google/cloud/bigquery/storage/artman_bigquerystorage_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: bigquerystorage + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: storage_v1beta1.yaml + gapic_yaml: v1beta1/bigquerystorage_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/bigquery/storage/storage_v1beta1.yaml b/google/cloud/bigquery/storage/storage_v1beta1.yaml new file mode 100644 index 000000000..28ac248ae --- /dev/null +++ b/google/cloud/bigquery/storage/storage_v1beta1.yaml @@ -0,0 +1,15 @@ +type: google.api.Service +config_version: 3 +name: bigquerystorage.googleapis.com +title: BigQuery Storage API + +apis: +- name: google.cloud.bigquery.storage.v1beta1.BigQueryStorage + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/bigquery, + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/bigquery/storage/v1beta1/BUILD.bazel b/google/cloud/bigquery/storage/v1beta1/BUILD.bazel new file mode 100644 index 000000000..6913b83fa --- /dev/null +++ b/google/cloud/bigquery/storage/v1beta1/BUILD.bazel @@ -0,0 +1,141 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "bigquerystorage_proto", + srcs = [ + "avro.proto", + "read_options.proto", + "storage.proto", + "table_reference.proto", + ], + deps = [ + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "bigquerystorage_proto_with_info", + deps = [":bigquerystorage_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "bigquerystorage_java_proto", + deps = [":bigquerystorage_proto"], +) + +java_grpc_library( + name = "bigquerystorage_java_grpc", + srcs = [":bigquerystorage_proto"], + deps = [":bigquerystorage_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "bigquerystorage_resource_name_java_proto", + gapic_yaml = "bigquerystorage_gapic.yaml", + deps = [":bigquerystorage_proto"], +) + +java_gapic_library( + name = "bigquerystorage_java_gapic", + src = ":bigquerystorage_proto_with_info", + gapic_yaml = "bigquerystorage_gapic.yaml", + service_yaml = "//google/cloud/bigquery/storage:storage_v1beta1.yaml", + test_deps = [":bigquerystorage_java_grpc"], + deps = [ + ":bigquerystorage_java_proto", + ":bigquerystorage_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":bigquerystorage_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.bigquery.storage.v1beta1.BaseBigQueryStorageClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-bigquerystorage-v1-java", + client_deps = [":bigquerystorage_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":bigquerystorage_java_gapic_test"], + grpc_deps = [":bigquerystorage_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":bigquerystorage_java_proto", + ":bigquerystorage_proto", + ":bigquerystorage_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "bigquerystorage_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/bigquery/storage/v1beta1", + protos = [":bigquerystorage_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + ], +) + +go_gapic_library( + name = "bigquerystorage_go_gapic", + src = ":bigquerystorage_proto_with_info", + gapic_yaml = "bigquerystorage_gapic.yaml", + importpath = "cloud.google.com/go/bigquery/datatransfer/apiv1", + service_yaml = "//google/cloud/bigquery/storage:storage_v1beta1.yaml", + deps = [":bigquerystorage_go_proto"], +) + +go_test( + name = "bigquerystorage_go_gapic_test", + srcs = [":bigquerystorage_go_gapic_srcjar_test"], + embed = [":bigquerystorage_go_gapic"], + importpath = "cloud.google.com/go/bigquery/storage/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-bigquerystorage-v1-go", + deps = [ + ":bigquerystorage_go_gapic", + ":bigquerystorage_go_gapic_srcjar-smoke-test.srcjar", + ":bigquerystorage_go_gapic_srcjar-test.srcjar", + ":bigquerystorage_go_proto", + ], +) diff --git a/google/cloud/bigquery/storage/v1beta1/avro.proto b/google/cloud/bigquery/storage/v1beta1/avro.proto new file mode 100644 index 000000000..699d70a67 --- /dev/null +++ b/google/cloud/bigquery/storage/v1beta1/avro.proto @@ -0,0 +1,39 @@ +// Copyright 2019 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.bigquery.storage.v1beta1; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/storage/v1beta1;storage"; +option java_outer_classname = "AvroProto"; +option java_package = "com.google.cloud.bigquery.storage.v1beta1"; + + +// Avro schema. +message AvroSchema { + // Json serialized schema, as described at + // https://avro.apache.org/docs/1.8.1/spec.html + string schema = 1; +} + +// Avro rows. +message AvroRows { + // Binary serialized rows in a block. + bytes serialized_binary_rows = 1; + + // The count of rows in the returning block. + int64 row_count = 2; +} diff --git a/google/cloud/bigquery/storage/v1beta1/bigquerystorage_gapic.yaml b/google/cloud/bigquery/storage/v1beta1/bigquerystorage_gapic.yaml new file mode 100644 index 000000000..d4554f321 --- /dev/null +++ b/google/cloud/bigquery/storage/v1beta1/bigquerystorage_gapic.yaml @@ -0,0 +1,188 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.bigquery.storage.v1beta1 + interface_names: + google.cloud.bigquery.storage.v1beta1.BigQueryStorage: BaseBigQueryStorage + python: + package_name: google.cloud.bigquery_storage_v1beta1.gapic + go: + package_name: cloud.google.com/go/bigquery/storage/apiv1beta1 + csharp: + package_name: Google.Cloud.Bigquery.Storage.V1beta1 + ruby: + package_name: Google::Cloud::Bigquery::Storage::V1beta1 + php: + package_name: Google\Cloud\Bigquery\Storage\V1beta1 + nodejs: + package_name: storage.v1beta1 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.bigquery.storage.v1beta1.BigQueryStorage + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # CreateReadSession performs some heavyweight table resolution work before + # returning to the caller, and can have DEADLINE_EXCEEDED issues for large + # (> 10TB) tables with the default retry settings. + - name: create_read_session + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 120000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 120000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateReadSession + flattening: + groups: + - parameters: + - table_reference + - parent + - requested_streams + required_fields: + - table_reference + - parent + retry_codes_name: idempotent + retry_params_name: create_read_session + timeout_millis: 60000 + header_request_params: + - table_reference.project_id + - table_reference.dataset_id + - name: ReadRows + flattening: + groups: + - parameters: + - read_position + required_fields: + - read_position + retry_codes_name: idempotent + retry_params_name: default + # Note this value is currently ignored in (at least) Java code generation. + # See https://github.com/googleapis/google-cloud-java/blob/master/google-cloud-clients/google-cloud-bigquerystorage/src/main/java/com/google/cloud/bigquery/storage/v1beta1/stub/EnhancedBigQueryStorageStubSettings.java + # for the Java-specific manual workaround. + timeout_millis: 86400000 + header_request_params: + - read_position.stream.name + - name: BatchCreateReadSessionStreams + flattening: + groups: + - parameters: + - session + - requested_streams + required_fields: + - session + - requested_streams + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + header_request_params: + - session.name + - name: FinalizeStream + flattening: + groups: + - parameters: + - stream + required_fields: + - stream + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + header_request_params: + - stream.name + - name: SplitReadStream + flattening: + groups: + - parameters: + - original_stream + required_fields: + - original_stream + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + header_request_params: + - original_stream.name diff --git a/google/cloud/bigquery/storage/v1beta1/read_options.proto b/google/cloud/bigquery/storage/v1beta1/read_options.proto new file mode 100644 index 000000000..8a3c66699 --- /dev/null +++ b/google/cloud/bigquery/storage/v1beta1/read_options.proto @@ -0,0 +1,42 @@ +// Copyright 2019 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.bigquery.storage.v1beta1; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/storage/v1beta1;storage"; +option java_package = "com.google.cloud.bigquery.storage.v1beta1"; + + +// Options dictating how we read a table. +message TableReadOptions { + // Optional. Names of the fields in the table that should be read. If empty, + // all fields will be read. If the specified field is a nested field, all the + // sub-fields in the field will be selected. The output field order is + // unrelated to the order of fields in selected_fields. + repeated string selected_fields = 1; + + // Optional. SQL text filtering statement, similar to a WHERE clause in + // a query. Currently, only a single predicate that is a comparison between + // a column and a constant value is supported. Aggregates are not supported. + // + // Examples: "int_field > 5" + // "date_field = CAST('2014-9-27' as DATE)" + // "nullable_field is not NULL" + // "st_equals(geo_field, st_geofromtext("POINT(2, 2)"))" + // "numeric_field BETWEEN 1.0 AND 5.0" + string row_restriction = 2; +} diff --git a/google/cloud/bigquery/storage/v1beta1/storage.proto b/google/cloud/bigquery/storage/v1beta1/storage.proto new file mode 100644 index 000000000..4ea0b1060 --- /dev/null +++ b/google/cloud/bigquery/storage/v1beta1/storage.proto @@ -0,0 +1,292 @@ +// Copyright 2019 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.bigquery.storage.v1beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/bigquery/storage/v1beta1/avro.proto"; +import "google/cloud/bigquery/storage/v1beta1/read_options.proto"; +import "google/cloud/bigquery/storage/v1beta1/table_reference.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/storage/v1beta1;storage"; +option java_package = "com.google.cloud.bigquery.storage.v1beta1"; + + +// BigQuery storage API. +// +// The BigQuery storage API can be used to read data stored in BigQuery. +service BigQueryStorage { + // Creates a new read session. A read session divides the contents of a + // BigQuery table into one or more streams, which can then be used to read + // data from the table. The read session also specifies properties of the + // data to be read, such as a list of columns or a push-down filter describing + // the rows to be returned. + // + // A particular row can be read by at most one stream. When the caller has + // reached the end of each stream in the session, then all the data in the + // table has been read. + // + // Read sessions automatically expire 24 hours after they are created and do + // not require manual clean-up by the caller. + rpc CreateReadSession(CreateReadSessionRequest) returns (ReadSession) { + option (google.api.http) = { + post: "/v1beta1/{table_reference.project_id=projects/*}" + body: "*" + additional_bindings { + post: "/v1beta1/{table_reference.dataset_id=projects/*/datasets/*}" + body: "*" + } + }; + } + + // Reads rows from the table in the format prescribed by the read session. + // Each response contains one or more table rows, up to a maximum of 10 MiB + // per response; read requests which attempt to read individual rows larger + // than this will fail. + // + // Each request also returns a set of stream statistics reflecting the + // estimated total number of rows in the read stream. This number is computed + // based on the total table size and the number of active streams in the read + // session, and may change as other streams continue to read data. + rpc ReadRows(ReadRowsRequest) returns (stream ReadRowsResponse) { + option (google.api.http) = { + get: "/v1beta1/{read_position.stream.name=projects/*/streams/*}" + }; + } + + // Creates additional streams for a ReadSession. This API can be used to + // dynamically adjust the parallelism of a batch processing task upwards by + // adding additional workers. + rpc BatchCreateReadSessionStreams(BatchCreateReadSessionStreamsRequest) returns (BatchCreateReadSessionStreamsResponse) { + option (google.api.http) = { + post: "/v1beta1/{session.name=projects/*/sessions/*}" + body: "*" + }; + } + + // Triggers the graceful termination of a single stream in a ReadSession. This + // API can be used to dynamically adjust the parallelism of a batch processing + // task downwards without losing data. + // + // This API does not delete the stream -- it remains visible in the + // ReadSession, and any data processed by the stream is not released to other + // streams. However, no additional data will be assigned to the stream once + // this call completes. Callers must continue reading data on the stream until + // the end of the stream is reached so that data which has already been + // assigned to the stream will be processed. + // + // This method will return an error if there are no other live streams + // in the Session, or if SplitReadStream() has been called on the given + // Stream. + rpc FinalizeStream(FinalizeStreamRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1beta1/{stream.name=projects/*/streams/*}" + body: "*" + }; + } + + // Splits a given read stream into two Streams. These streams are referred to + // as the primary and the residual of the split. The original stream can still + // be read from in the same manner as before. Both of the returned streams can + // also be read from, and the total rows return by both child streams will be + // the same as the rows read from the original stream. + // + // Moreover, the two child streams will be allocated back to back in the + // original Stream. Concretely, it is guaranteed that for streams Original, + // Primary, and Residual, that Original[0-j] = Primary[0-j] and + // Original[j-n] = Residual[0-m] once the streams have been read to + // completion. + // + // This method is guaranteed to be idempotent. + rpc SplitReadStream(SplitReadStreamRequest) returns (SplitReadStreamResponse) { + option (google.api.http) = { + get: "/v1beta1/{original_stream.name=projects/*/streams/*}" + }; + } +} + +// Information about a single data stream within a read session. +message Stream { + // Name of the stream, in the form + // `projects/{project_id}/locations/{location}/streams/{stream_id}`. + string name = 1; + + // Rows in the stream. + int64 row_count = 2; +} + +// Expresses a point within a given stream using an offset position. +message StreamPosition { + // Identifier for a given Stream. + Stream stream = 1; + + // Position in the stream. + int64 offset = 2; +} + +// Information returned from a `CreateReadSession` request. +message ReadSession { + // Unique identifier for the session, in the form + // `projects/{project_id}/locations/{location}/sessions/{session_id}`. + string name = 1; + + // Time at which the session becomes invalid. After this time, subsequent + // requests to read this Session will return errors. + google.protobuf.Timestamp expire_time = 2; + + // The schema for the read. If read_options.selected_fields is set, the + // schema may be different from the table schema as it will only contain + // the selected fields. + oneof schema { + // Avro schema. + AvroSchema avro_schema = 5; + } + + // Streams associated with this session. + repeated Stream streams = 4; + + // Table that this ReadSession is reading from. + TableReference table_reference = 7; + + // Any modifiers which are applied when reading from the specified table. + TableModifiers table_modifiers = 8; +} + +// Creates a new read session, which may include additional options such as +// requested parallelism, projection filters and constraints. +message CreateReadSessionRequest { + // Required. Reference to the table to read. + TableReference table_reference = 1; + + // Required. String of the form `projects/{project_id}` indicating the + // project this ReadSession is associated with. This is the project that will + // be billed for usage. + string parent = 6; + + // Optional. Any modifiers to the Table (e.g. snapshot timestamp). + TableModifiers table_modifiers = 2; + + // Optional. Initial number of streams. If unset or 0, we will + // provide a value of streams so as to produce reasonable throughput. Must be + // non-negative. The number of streams may be lower than the requested number, + // depending on the amount parallelism that is reasonable for the table and + // the maximum amount of parallelism allowed by the system. + // + // Streams must be read starting from offset 0. + int32 requested_streams = 3; + + // Optional. Read options for this session (e.g. column selection, filters). + TableReadOptions read_options = 4; + + // Data output format. Currently default to Avro. + DataFormat format = 5; +} + +// Data format for input or output data. +enum DataFormat { + // Data format is unspecified. + DATA_FORMAT_UNSPECIFIED = 0; + + // Avro is a standard open source row based file format. + // See https://avro.apache.org/ for more details. + AVRO = 1; +} + +// Requesting row data via `ReadRows` must provide Stream position information. +message ReadRowsRequest { + // Required. Identifier of the position in the stream to start reading from. + // The offset requested must be less than the last row read from ReadRows. + // Requesting a larger offset is undefined. + StreamPosition read_position = 1; +} + +// Progress information for a given Stream. +message StreamStatus { + // Number of estimated rows in the current stream. May change over time as + // different readers in the stream progress at rates which are relatively fast + // or slow. + int64 estimated_row_count = 1; +} + +// Information on if the current connection is being throttled. +message ThrottleStatus { + // How much this connection is being throttled. + // 0 is no throttling, 100 is completely throttled. + int32 throttle_percent = 1; +} + +// Response from calling `ReadRows` may include row data, progress and +// throttling information. +message ReadRowsResponse { + // Row data is returned in format specified during session creation. + oneof rows { + // Serialized row data in AVRO format. + AvroRows avro_rows = 3; + } + + // Estimated stream statistics. + StreamStatus status = 2; + + // Throttling status. If unset, the latest response still describes + // the current throttling status. + ThrottleStatus throttle_status = 5; +} + +// Information needed to request additional streams for an established read +// session. +message BatchCreateReadSessionStreamsRequest { + // Required. Must be a non-expired session obtained from a call to + // CreateReadSession. Only the name field needs to be set. + ReadSession session = 1; + + // Required. Number of new streams requested. Must be positive. + // Number of added streams may be less than this, see CreateReadSessionRequest + // for more information. + int32 requested_streams = 2; +} + +// The response from `BatchCreateReadSessionStreams` returns the stream +// identifiers for the newly created streams. +message BatchCreateReadSessionStreamsResponse { + // Newly added streams. + repeated Stream streams = 1; +} + +// Request information for invoking `FinalizeStream`. +message FinalizeStreamRequest { + // Stream to finalize. + Stream stream = 2; +} + +// Request information for `SplitReadStream`. +message SplitReadStreamRequest { + // Stream to split. + Stream original_stream = 1; +} + +// Response from `SplitReadStream`. +message SplitReadStreamResponse { + // Primary stream. Will contain the beginning portion of + // |original_stream|. + Stream primary_stream = 1; + + // Remainder stream. Will contain the tail of |original_stream|. + Stream remainder_stream = 2; +} diff --git a/google/cloud/bigquery/storage/v1beta1/table_reference.proto b/google/cloud/bigquery/storage/v1beta1/table_reference.proto new file mode 100644 index 000000000..0d513898d --- /dev/null +++ b/google/cloud/bigquery/storage/v1beta1/table_reference.proto @@ -0,0 +1,44 @@ +// Copyright 2019 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.bigquery.storage.v1beta1; + +import "google/api/resource.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/storage/v1beta1;storage"; +option java_outer_classname = "TableReferenceProto"; +option java_package = "com.google.cloud.bigquery.storage.v1beta1"; + + +// Table reference that includes just the 3 strings needed to identify a table. +message TableReference { + // The assigned project ID of the project. + string project_id = 1; + + // The ID of the dataset in the above project. + string dataset_id = 2; + + // The ID of the table in the above dataset. + string table_id = 3; +} + +// All fields in this message optional. +message TableModifiers { + // The snapshot time of the table. If not set, interpreted as now. + google.protobuf.Timestamp snapshot_time = 1; +} diff --git a/google/cloud/bigquery/v2/bigquery_gapic.yaml b/google/cloud/bigquery/v2/bigquery_gapic.yaml new file mode 100644 index 000000000..de614d248 --- /dev/null +++ b/google/cloud/bigquery/v2/bigquery_gapic.yaml @@ -0,0 +1,175 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.bigquery.v2 + python: + package_name: google.cloud.bigquery_v2.gapic + go: + package_name: cloud.google.com/go/bigquery/apiv2 + csharp: + package_name: Google.Cloud.Bigquery.V2 + ruby: + package_name: Google::Cloud::Bigquery::V2 + php: + package_name: Google\Cloud\Bigquery\V2 + nodejs: + package_name: bigquery.v2 +# The configuration for the license header to put on generated files. +license_header: + # The file containing the copyright line(s). + copyright_file: copyright-google.txt + # The file containing the raw license header without any copyright line(s). + license_file: license-header-apache-2.0.txt +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.bigquery.v2.ModelService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: GetModel + flattening: + groups: + - parameters: + - project_id + - dataset_id + - model_id + required_fields: + - project_id + - dataset_id + - model_id + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: ListModels + flattening: + groups: + - parameters: + - project_id + - dataset_id + - max_results + required_fields: + - project_id + - dataset_id + page_streaming: + request: + token_field: page_token + response: + token_field: next_page_token + resources_field: models + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: PatchModel + flattening: + groups: + - parameters: + - project_id + - dataset_id + - model_id + - model + required_fields: + - project_id + - dataset_id + - model_id + - model + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: DeleteModel + flattening: + groups: + - parameters: + - project_id + - dataset_id + - model_id + required_fields: + - project_id + - dataset_id + - model_id + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/bigquery/v2/model.proto b/google/cloud/bigquery/v2/model.proto new file mode 100644 index 000000000..b94cb3f5e --- /dev/null +++ b/google/cloud/bigquery/v2/model.proto @@ -0,0 +1,513 @@ +// Copyright 2019 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.bigquery.v2; + +import "google/cloud/bigquery/v2/model_reference.proto"; +import "google/cloud/bigquery/v2/standard_sql.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/v2;bigquery"; +option java_outer_classname = "ModelProto"; +option java_package = "com.google.cloud.bigquery.v2"; + + +service ModelService { + // Gets the specified model resource by model ID. + rpc GetModel(GetModelRequest) returns (Model) { + } + + // Lists all models in the specified dataset. Requires the READER dataset + // role. + rpc ListModels(ListModelsRequest) returns (ListModelsResponse) { + } + + // Patch specific fields in the specified model. + rpc PatchModel(PatchModelRequest) returns (Model) { + } + + // Deletes the model specified by modelId from the dataset. + rpc DeleteModel(DeleteModelRequest) returns (google.protobuf.Empty) { + } +} + +message Model { + // Evaluation metrics for regression models. + message RegressionMetrics { + // Mean absolute error. + google.protobuf.DoubleValue mean_absolute_error = 1; + + // Mean squared error. + google.protobuf.DoubleValue mean_squared_error = 2; + + // Mean squared log error. + google.protobuf.DoubleValue mean_squared_log_error = 3; + + // Median absolute error. + google.protobuf.DoubleValue median_absolute_error = 4; + + // R^2 score. + google.protobuf.DoubleValue r_squared = 5; + } + + // Aggregate metrics for classification models. For multi-class models, + // the metrics are either macro-averaged: metrics are calculated for each + // label and then an unweighted average is taken of those values or + // micro-averaged: the metric is calculated globally by counting the total + // number of correctly predicted rows. + message AggregateClassificationMetrics { + // Precision is the fraction of actual positive predictions that had + // positive actual labels. For multiclass this is a macro-averaged + // metric treating each class as a binary classifier. + google.protobuf.DoubleValue precision = 1; + + // Recall is the fraction of actual positive labels that were given a + // positive prediction. For multiclass this is a macro-averaged metric. + google.protobuf.DoubleValue recall = 2; + + // Accuracy is the fraction of predictions given the correct label. For + // multiclass this is a micro-averaged metric. + google.protobuf.DoubleValue accuracy = 3; + + // Threshold at which the metrics are computed. For binary + // classification models this is the positive class threshold. + // For multi-class classfication models this is the confidence + // threshold. + google.protobuf.DoubleValue threshold = 4; + + // The F1 score is an average of recall and precision. For multiclass + // this is a macro-averaged metric. + google.protobuf.DoubleValue f1_score = 5; + + // Logarithmic Loss. For multiclass this is a macro-averaged metric. + google.protobuf.DoubleValue log_loss = 6; + + // Area Under a ROC Curve. For multiclass this is a macro-averaged + // metric. + google.protobuf.DoubleValue roc_auc = 7; + } + + // Evaluation metrics for binary classification models. + message BinaryClassificationMetrics { + // Confusion matrix for binary classification models. + message BinaryConfusionMatrix { + // Threshold value used when computing each of the following metric. + google.protobuf.DoubleValue positive_class_threshold = 1; + + // Number of true samples predicted as true. + google.protobuf.Int64Value true_positives = 2; + + // Number of false samples predicted as true. + google.protobuf.Int64Value false_positives = 3; + + // Number of true samples predicted as false. + google.protobuf.Int64Value true_negatives = 4; + + // Number of false samples predicted as false. + google.protobuf.Int64Value false_negatives = 5; + + // Aggregate precision. + google.protobuf.DoubleValue precision = 6; + + // Aggregate recall. + google.protobuf.DoubleValue recall = 7; + } + + // Aggregate classification metrics. + AggregateClassificationMetrics aggregate_classification_metrics = 1; + + // Binary confusion matrix at multiple thresholds. + repeated BinaryConfusionMatrix binary_confusion_matrix_list = 2; + } + + // Evaluation metrics for multi-class classification models. + message MultiClassClassificationMetrics { + // Confusion matrix for multi-class classification models. + message ConfusionMatrix { + // A single entry in the confusion matrix. + message Entry { + // The predicted label. For confidence_threshold > 0, we will + // also add an entry indicating the number of items under the + // confidence threshold. + string predicted_label = 1; + + // Number of items being predicted as this label. + google.protobuf.Int64Value item_count = 2; + } + + // A single row in the confusion matrix. + message Row { + // The original label of this row. + string actual_label = 1; + + // Info describing predicted label distribution. + repeated Entry entries = 2; + } + + // Confidence threshold used when computing the entries of the + // confusion matrix. + google.protobuf.DoubleValue confidence_threshold = 1; + + // One row per actual label. + repeated Row rows = 2; + } + + // Aggregate classification metrics. + AggregateClassificationMetrics aggregate_classification_metrics = 1; + + // Confusion matrix at different thresholds. + repeated ConfusionMatrix confusion_matrix_list = 2; + } + + // Evaluation metrics for clustering models. + message ClusteringMetrics { + // Davies-Bouldin index. + google.protobuf.DoubleValue davies_bouldin_index = 1; + + // Mean of squared distances between each sample to its cluster centroid. + google.protobuf.DoubleValue mean_squared_distance = 2; + } + + // Evaluation metrics of a model. These are either computed on all + // training data or just the eval data based on whether eval data was used + // during training. + message EvaluationMetrics { + oneof metrics { + // Populated for regression models. + RegressionMetrics regression_metrics = 1; + + // Populated for binary classification models. + BinaryClassificationMetrics binary_classification_metrics = 2; + + // Populated for multi-class classification models. + MultiClassClassificationMetrics multi_class_classification_metrics = 3; + + // [Beta] Populated for clustering models. + ClusteringMetrics clustering_metrics = 4; + } + } + + // Information about a single training query run for the model. + message TrainingRun { + message TrainingOptions { + // The maximum number of iterations in training. + int64 max_iterations = 1; + + // Type of loss function used during training run. + LossType loss_type = 2; + + // Learning rate in training. + double learn_rate = 3; + + // L1 regularization coefficient. + google.protobuf.DoubleValue l1_regularization = 4; + + // L2 regularization coefficient. + google.protobuf.DoubleValue l2_regularization = 5; + + // When early_stop is true, stops training when accuracy improvement is + // less than 'min_relative_progress'. + google.protobuf.DoubleValue min_relative_progress = 6; + + // Whether to train a model from the last checkpoint. + google.protobuf.BoolValue warm_start = 7; + + // Whether to stop early when the loss doesn't improve significantly + // any more (compared to min_relative_progress). + google.protobuf.BoolValue early_stop = 8; + + // Name of input label columns in training data. + repeated string input_label_columns = 9; + + // The data split type for training and evaluation, e.g. RANDOM. + DataSplitMethod data_split_method = 10; + + // The fraction of evaluation data over the whole input data. The rest + // of data will be used as training data. The format should be double. + // Accurate to two decimal places. + // Default value is 0.2. + double data_split_eval_fraction = 11; + + // The column to split data with. This column won't be used as a + // feature. + // 1. When data_split_method is CUSTOM, the corresponding column should + // be boolean. The rows with true value tag are eval data, and the false + // are training data. + // 2. When data_split_method is SEQ, the first DATA_SPLIT_EVAL_FRACTION + // rows (from smallest to largest) in the corresponding column are used + // as training data, and the rest are eval data. It respects the order + // in Orderable data types: + // https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#data-type-properties + string data_split_column = 12; + + // The strategy to determine learning rate. + LearnRateStrategy learn_rate_strategy = 13; + + // Specifies the initial learning rate for line search to start at. + double initial_learn_rate = 16; + + // Weights associated with each label class, for rebalancing the + // training data. + map<string, double> label_class_weights = 17; + + // [Beta] Distance type for clustering models. + DistanceType distance_type = 20; + + // [Beta] Number of clusters for clustering models. + int64 num_clusters = 21; + } + + // Information about a single iteration of the training run. + message IterationResult { + // Information about a single cluster for clustering model. + message ClusterInfo { + // Centroid id. + int64 centroid_id = 1; + + // Cluster radius, the average distance from centroid + // to each point assigned to the cluster. + google.protobuf.DoubleValue cluster_radius = 2; + + // Cluster size, the total number of points assigned to the cluster. + google.protobuf.Int64Value cluster_size = 3; + } + + // Index of the iteration, 0 based. + google.protobuf.Int32Value index = 1; + + // Time taken to run the iteration in milliseconds. + google.protobuf.Int64Value duration_ms = 4; + + // Loss computed on the training data at the end of iteration. + google.protobuf.DoubleValue training_loss = 5; + + // Loss computed on the eval data at the end of iteration. + google.protobuf.DoubleValue eval_loss = 6; + + // Learn rate used for this iteration. + double learn_rate = 7; + + // [Beta] Information about top clusters for clustering models. + repeated ClusterInfo cluster_infos = 8; + } + + // Options that were used for this training run, includes + // user specified and default options that were used. + TrainingOptions training_options = 1; + + // The start time of this training run. + google.protobuf.Timestamp start_time = 8; + + // Output of each iteration run, results.size() <= max_iterations. + repeated IterationResult results = 6; + + // The evaluation metrics over training/eval data that were computed at the + // end of training. + EvaluationMetrics evaluation_metrics = 7; + } + + // Indicates the type of the Model. + enum ModelType { + MODEL_TYPE_UNSPECIFIED = 0; + + // Linear regression model. + LINEAR_REGRESSION = 1; + + // Logistic regression model. + LOGISTIC_REGRESSION = 2; + + // [Beta] K-means clustering model. + KMEANS = 3; + } + + // Loss metric to evaluate model training performance. + enum LossType { + LOSS_TYPE_UNSPECIFIED = 0; + + // Mean squared loss, used for linear regression. + MEAN_SQUARED_LOSS = 1; + + // Mean log loss, used for logistic regression. + MEAN_LOG_LOSS = 2; + } + + // Distance metric used to compute the distance between two points. + enum DistanceType { + DISTANCE_TYPE_UNSPECIFIED = 0; + + // Eculidean distance. + EUCLIDEAN = 1; + + // Cosine distance. + COSINE = 2; + } + + // Indicates the method to split input data into multiple tables. + enum DataSplitMethod { + DATA_SPLIT_METHOD_UNSPECIFIED = 0; + + // Splits data randomly. + RANDOM = 1; + + // Splits data with the user provided tags. + CUSTOM = 2; + + // Splits data sequentially. + SEQUENTIAL = 3; + + // Data split will be skipped. + NO_SPLIT = 4; + + // Splits data automatically: Uses NO_SPLIT if the data size is small. + // Otherwise uses RANDOM. + AUTO_SPLIT = 5; + } + + // Indicates the learning rate optimization strategy to use. + enum LearnRateStrategy { + LEARN_RATE_STRATEGY_UNSPECIFIED = 0; + + // Use line search to determine learning rate. + LINE_SEARCH = 1; + + // Use a constant learning rate. + CONSTANT = 2; + } + + // Output only. A hash of this resource. + string etag = 1; + + // Required. Unique identifier for this model. + ModelReference model_reference = 2; + + // Output only. The time when this model was created, in millisecs since the + // epoch. + int64 creation_time = 5; + + // Output only. The time when this model was last modified, in millisecs + // since the epoch. + int64 last_modified_time = 6; + + // [Optional] A user-friendly description of this model. + // @mutable bigquery.models.patch + string description = 12; + + // [Optional] A descriptive name for this model. + // @mutable bigquery.models.patch + string friendly_name = 14; + + // [Optional] The labels associated with this model. You can use these to + // organize and group your models. Label keys and values can be no longer + // than 63 characters, can only contain lowercase letters, numeric + // characters, underscores and dashes. International characters are allowed. + // Label values are optional. Label keys must start with a letter and each + // label in the list must have a different key. + // @mutable bigquery.models.patch + map<string, string> labels = 15; + + // [Optional] The time when this model expires, in milliseconds since the + // epoch. If not present, the model will persist indefinitely. Expired models + // will be deleted and their storage reclaimed. The defaultTableExpirationMs + // property of the encapsulating dataset can be used to set a default + // expirationTime on newly created models. + // @mutable bigquery.models.patch + int64 expiration_time = 16; + + // Output only. The geographic location where the model resides. This value + // is inherited from the dataset. + string location = 13; + + // Output only. Type of the model resource. + ModelType model_type = 7; + + // Output only. Information for all training runs in increasing order of + // start_time. + repeated TrainingRun training_runs = 9; + + // Output only. Input feature columns that were used to train this model. + repeated StandardSqlField feature_columns = 10; + + // Output only. Label columns that were used to train this model. + // The output of the model will have a “predicted_” prefix to these columns. + repeated StandardSqlField label_columns = 11; +} + +message GetModelRequest { + // Project ID of the requested model. + string project_id = 1; + + // Dataset ID of the requested model. + string dataset_id = 2; + + // Model ID of the requested model. + string model_id = 3; +} + +message PatchModelRequest { + // Project ID of the model to patch. + string project_id = 1; + + // Dataset ID of the model to patch. + string dataset_id = 2; + + // Model ID of the model to patch. + string model_id = 3; + + // Patched model. + // Follows patch semantics. Missing fields are not updated. To clear a field, + // explicitly set to default value. + Model model = 4; +} + +message DeleteModelRequest { + // Project ID of the model to delete. + string project_id = 1; + + // Dataset ID of the model to delete. + string dataset_id = 2; + + // Model ID of the model to delete. + string model_id = 3; +} + +message ListModelsRequest { + // Project ID of the models to list. + string project_id = 1; + + // Dataset ID of the models to list. + string dataset_id = 2; + + // The maximum number of results per page. + google.protobuf.UInt32Value max_results = 3; + + // Page token, returned by a previous call to request the next page of + // results + string page_token = 4; +} + +message ListModelsResponse { + // Models in the requested dataset. Only the following fields are populated: + // model_reference, model_type, creation_time, last_modified_time and + // labels. + repeated Model models = 1; + + // A token to request the next page of results. + string next_page_token = 2; +} diff --git a/google/cloud/bigquery/v2/model_reference.proto b/google/cloud/bigquery/v2/model_reference.proto new file mode 100644 index 000000000..8e1e218f9 --- /dev/null +++ b/google/cloud/bigquery/v2/model_reference.proto @@ -0,0 +1,39 @@ +// Copyright 2019 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.bigquery.v2; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/v2;bigquery"; +option java_outer_classname = "ModelReferenceProto"; +option java_package = "com.google.cloud.bigquery.v2"; + + +// Id path of a model. +message ModelReference { + // [Required] The ID of the project containing this model. + string project_id = 1; + + // [Required] The ID of the dataset containing this model. + string dataset_id = 2; + + // [Required] The ID of the model. The ID must contain only + // letters (a-z, A-Z), numbers (0-9), or underscores (_). The maximum + // length is 1,024 characters. + string model_id = 3; +} diff --git a/google/cloud/bigquery/v2/standard_sql.proto b/google/cloud/bigquery/v2/standard_sql.proto new file mode 100644 index 000000000..82d996024 --- /dev/null +++ b/google/cloud/bigquery/v2/standard_sql.proto @@ -0,0 +1,110 @@ +// Copyright 2019 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.bigquery.v2; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/bigquery/v2;bigquery"; +option java_outer_classname = "StandardSqlProto"; +option java_package = "com.google.cloud.bigquery.v2"; + + +// The type of a variable, e.g., a function argument. +// Examples: +// INT64: {type_kind="INT64"} +// ARRAY<STRING>: {type_kind="ARRAY", array_element_type="STRING"} +// STRUCT<x STRING, y ARRAY<DATE>>: +// {type_kind="STRUCT", +// struct_type={fields=[ +// {name="x", type={type_kind="STRING"}}, +// {name="y", type={type_kind="ARRAY", array_element_type="DATE"}} +// ]}} +message StandardSqlDataType { + enum TypeKind { + // Invalid type. + TYPE_KIND_UNSPECIFIED = 0; + + // Encoded as a string in decimal format. + INT64 = 2; + + // Encoded as a boolean "false" or "true". + BOOL = 5; + + // Encoded as a number, or string "NaN", "Infinity" or "-Infinity". + FLOAT64 = 7; + + // Encoded as a string value. + STRING = 8; + + // Encoded as a base64 string per RFC 4648, section 4. + BYTES = 9; + + // Encoded as an RFC 3339 timestamp with mandatory "Z" time zone string: + // 1985-04-12T23:20:50.52Z + TIMESTAMP = 19; + + // Encoded as RFC 3339 full-date format string: 1985-04-12 + DATE = 10; + + // Encoded as RFC 3339 partial-time format string: 23:20:50.52 + TIME = 20; + + // Encoded as RFC 3339 full-date "T" partial-time: 1985-04-12T23:20:50.52 + DATETIME = 21; + + // Encoded as WKT + GEOGRAPHY = 22; + + // Encoded as a decimal string. + NUMERIC = 23; + + // Encoded as a list with types matching Type.array_type. + ARRAY = 16; + + // Encoded as a list with fields of type Type.struct_type[i]. List is used + // because a JSON object cannot have duplicate field names. + STRUCT = 17; + } + + // Required. The top level type of this field. + // Can be any standard SQL data type (e.g., "INT64", "DATE", "ARRAY"). + TypeKind type_kind = 1; + + oneof sub_type { + // The type of the array's elements, if type_kind = "ARRAY". + StandardSqlDataType array_element_type = 2; + + // The fields of this struct, in order, if type_kind = "STRUCT". + StandardSqlStructType struct_type = 3; + } +} + +// A field or a column. +message StandardSqlField { + // Optional. The name of this field. Can be absent for struct fields. + string name = 1; + + // Optional. The type of this parameter. Absent if not explicitly + // specified (e.g., CREATE FUNCTION statement can omit the return type; + // in this case the output parameter does not have this "type" field). + StandardSqlDataType type = 2; +} + +message StandardSqlStructType { + repeated StandardSqlField fields = 1; +} diff --git a/google/cloud/billing/v1/cloud_billing.proto b/google/cloud/billing/v1/cloud_billing.proto new file mode 100644 index 000000000..2985d4515 --- /dev/null +++ b/google/cloud/billing/v1/cloud_billing.proto @@ -0,0 +1,228 @@ +// Copyright 2016 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.billing.v1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/billing/v1;billing"; +option java_multiple_files = true; +option java_outer_classname = "CloudBillingProto"; +option java_package = "com.google.cloud.billing.v1"; + +// Retrieves Google Cloud Console billing accounts and associates them with +// projects. +service CloudBilling { + // Gets information about a billing account. The current authenticated user + // must be an [owner of the billing + // account](https://support.google.com/cloud/answer/4430947). + rpc GetBillingAccount(GetBillingAccountRequest) returns (BillingAccount) { + option (google.api.http) = { + get: "/v1/{name=billingAccounts/*}" + }; + } + + // Lists the billing accounts that the current authenticated user + // [owns](https://support.google.com/cloud/answer/4430947). + rpc ListBillingAccounts(ListBillingAccountsRequest) + returns (ListBillingAccountsResponse) { + option (google.api.http) = { + get: "/v1/billingAccounts" + }; + } + + // Lists the projects associated with a billing account. The current + // authenticated user must be an [owner of the billing + // account](https://support.google.com/cloud/answer/4430947). + rpc ListProjectBillingInfo(ListProjectBillingInfoRequest) + returns (ListProjectBillingInfoResponse) { + option (google.api.http) = { + get: "/v1/{name=billingAccounts/*}/projects" + }; + } + + // Gets the billing information for a project. The current authenticated user + // must have [permission to view the + // project](https://cloud.google.com/docs/permissions-overview#h.bgs0oxofvnoo + // ). + rpc GetProjectBillingInfo(GetProjectBillingInfoRequest) + returns (ProjectBillingInfo) { + option (google.api.http) = { + get: "/v1/{name=projects/*}/billingInfo" + }; + } + + // Sets or updates the billing account associated with a project. You specify + // the new billing account by setting the `billing_account_name` in the + // `ProjectBillingInfo` resource to the resource name of a billing account. + // Associating a project with an open billing account enables billing on the + // project and allows charges for resource usage. If the project already had a + // billing account, this method changes the billing account used for resource + // usage charges. + // + // *Note:* Incurred charges that have not yet been reported in the transaction + // history of the Google Cloud Console may be billed to the new billing + // account, even if the charge occurred before the new billing account was + // assigned to the project. + // + // The current authenticated user must have ownership privileges for both the + // [project](https://cloud.google.com/docs/permissions-overview#h.bgs0oxofvnoo + // ) and the [billing + // account](https://support.google.com/cloud/answer/4430947). + // + // You can disable billing on the project by setting the + // `billing_account_name` field to empty. This action disassociates the + // current billing account from the project. Any billable activity of your + // in-use services will stop, and your application could stop functioning as + // expected. Any unbilled charges to date will be billed to the previously + // associated account. The current authenticated user must be either an owner + // of the project or an owner of the billing account for the project. + // + // Note that associating a project with a *closed* billing account will have + // much the same effect as disabling billing on the project: any paid + // resources used by the project will be shut down. Thus, unless you wish to + // disable billing, you should always call this method with the name of an + // *open* billing account. + rpc UpdateProjectBillingInfo(UpdateProjectBillingInfoRequest) + returns (ProjectBillingInfo) { + option (google.api.http) = { + put: "/v1/{name=projects/*}/billingInfo" + body: "project_billing_info" + }; + } +} + +// A billing account in [Google Cloud +// Console](https://console.cloud.google.com/). You can assign a billing account +// to one or more projects. +message BillingAccount { + // The resource name of the billing account. The resource name has the form + // `billingAccounts/{billing_account_id}`. For example, + // `billingAccounts/012345-567890-ABCDEF` would be the resource name for + // billing account `012345-567890-ABCDEF`. + string name = 1; + + // True if the billing account is open, and will therefore be charged for any + // usage on associated projects. False if the billing account is closed, and + // therefore projects associated with it will be unable to use paid services. + bool open = 2; + + // The display name given to the billing account, such as `My Billing + // Account`. This name is displayed in the Google Cloud Console. + string display_name = 3; +} + +// Encapsulation of billing information for a Cloud Console project. A project +// has at most one associated billing account at a time (but a billing account +// can be assigned to multiple projects). +message ProjectBillingInfo { + // The resource name for the `ProjectBillingInfo`; has the form + // `projects/{project_id}/billingInfo`. For example, the resource name for the + // billing information for project `tokyo-rain-123` would be + // `projects/tokyo-rain-123/billingInfo`. This field is read-only. + string name = 1; + + // The ID of the project that this `ProjectBillingInfo` represents, such as + // `tokyo-rain-123`. This is a convenience field so that you don't need to + // parse the `name` field to obtain a project ID. This field is read-only. + string project_id = 2; + + // The resource name of the billing account associated with the project, if + // any. For example, `billingAccounts/012345-567890-ABCDEF`. + string billing_account_name = 3; + + // True if the project is associated with an open billing account, to which + // usage on the project is charged. False if the project is associated with a + // closed billing account, or no billing account at all, and therefore cannot + // use paid services. This field is read-only. + bool billing_enabled = 4; +} + +// Request message for `GetBillingAccount`. +message GetBillingAccountRequest { + // The resource name of the billing account to retrieve. For example, + // `billingAccounts/012345-567890-ABCDEF`. + string name = 1; +} + +// Request message for `ListBillingAccounts`. +message ListBillingAccountsRequest { + // Requested page size. The maximum page size is 100; this is also the + // default. + int32 page_size = 1; + + // A token identifying a page of results to return. This should be a + // `next_page_token` value returned from a previous `ListBillingAccounts` + // call. If unspecified, the first page of results is returned. + string page_token = 2; +} + +// Response message for `ListBillingAccounts`. +message ListBillingAccountsResponse { + // A list of billing accounts. + repeated BillingAccount billing_accounts = 1; + + // A token to retrieve the next page of results. To retrieve the next page, + // call `ListBillingAccounts` again with the `page_token` field set to this + // value. This field is empty if there are no more results to retrieve. + string next_page_token = 2; +} + +// Request message for `ListProjectBillingInfo`. +message ListProjectBillingInfoRequest { + // The resource name of the billing account associated with the projects that + // you want to list. For example, `billingAccounts/012345-567890-ABCDEF`. + string name = 1; + + // Requested page size. The maximum page size is 100; this is also the + // default. + int32 page_size = 2; + + // A token identifying a page of results to be returned. This should be a + // `next_page_token` value returned from a previous `ListProjectBillingInfo` + // call. If unspecified, the first page of results is returned. + string page_token = 3; +} + +// Request message for `ListProjectBillingInfoResponse`. +message ListProjectBillingInfoResponse { + // A list of `ProjectBillingInfo` resources representing the projects + // associated with the billing account. + repeated ProjectBillingInfo project_billing_info = 1; + + // A token to retrieve the next page of results. To retrieve the next page, + // call `ListProjectBillingInfo` again with the `page_token` field set to this + // value. This field is empty if there are no more results to retrieve. + string next_page_token = 2; +} + +// Request message for `GetProjectBillingInfo`. +message GetProjectBillingInfoRequest { + // The resource name of the project for which billing information is + // retrieved. For example, `projects/tokyo-rain-123`. + string name = 1; +} + +// Request message for `UpdateProjectBillingInfo`. +message UpdateProjectBillingInfoRequest { + // The resource name of the project associated with the billing information + // that you want to update. For example, `projects/tokyo-rain-123`. + string name = 1; + + // The new billing information for the project. Read-only fields are ignored; + // thus, you may leave empty all fields except `billing_account_name`. + ProjectBillingInfo project_billing_info = 2; +} diff --git a/google/cloud/datalabeling/artman_datalabeling_v1beta1.yaml b/google/cloud/datalabeling/artman_datalabeling_v1beta1.yaml new file mode 100644 index 000000000..2d81d3c57 --- /dev/null +++ b/google/cloud/datalabeling/artman_datalabeling_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: datalabeling + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: datalabeling_v1beta1.yaml + gapic_yaml: v1beta1/datalabeling_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/datalabeling/datalabeling_v1beta1.yaml b/google/cloud/datalabeling/datalabeling_v1beta1.yaml new file mode 100644 index 000000000..26d34e06a --- /dev/null +++ b/google/cloud/datalabeling/datalabeling_v1beta1.yaml @@ -0,0 +1,99 @@ +type: google.api.Service +config_version: 3 +name: datalabeling.googleapis.com +title: Data Labeling API + +apis: +- name: google.cloud.datalabeling.v1beta1.DataLabelingService + +documentation: + summary: Public API for Google Cloud AI Data Labeling Service. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 60.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 60.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 60.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 60.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 60.0 + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + deadline: 60.0 + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + deadline: 60.0 + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.CreateDataset + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.GetDataset + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ListDatasets + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.DeleteDataset + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ImportData + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ExportData + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.GetDataItem + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ListDataItems + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.GetAnnotatedDataset + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ListAnnotatedDatasets + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.LabelImage + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.LabelVideo + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.LabelText + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.LabelAudio + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.GetExample + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ListExamples + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.CreateAnnotationSpecSet + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.GetAnnotationSpecSet + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ListAnnotationSpecSets + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.DeleteAnnotationSpecSet + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.CreateInstruction + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.GetInstruction + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.ListInstructions + deadline: 60.0 + - selector: google.cloud.datalabeling.v1beta1.DataLabelingService.DeleteInstruction + deadline: 60.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1beta1/{name=projects/*}/operations' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1beta1/{name=projects/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1beta1/{name=projects/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1beta1/{name=projects/*/operations/*}:cancel' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/datalabeling/v1beta1/annotation.proto b/google/cloud/datalabeling/v1beta1/annotation.proto new file mode 100644 index 000000000..204ad8e3d --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/annotation.proto @@ -0,0 +1,337 @@ +// Copyright 2018 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.datalabeling.v1beta1; + +import "google/cloud/datalabeling/v1beta1/annotation_spec_set.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/datalabeling/v1beta1;datalabeling"; +option java_multiple_files = true; +option java_package = "com.google.cloud.datalabeling.v1beta1"; + + +// Specifies where is the answer from. +enum AnnotationSource { + ANNOTATION_SOURCE_UNSPECIFIED = 0; + + // Answer is provided by a human contributor. + OPERATOR = 3; +} + +enum AnnotationSentiment { + ANNOTATION_SENTIMENT_UNSPECIFIED = 0; + + // This annotation describes negatively about the data. + NEGATIVE = 1; + + // This label describes positively about the data. + POSITIVE = 2; +} + +enum AnnotationType { + ANNOTATION_TYPE_UNSPECIFIED = 0; + + // Classification annotations in an image. + IMAGE_CLASSIFICATION_ANNOTATION = 1; + + // Bounding box annotations in an image. + IMAGE_BOUNDING_BOX_ANNOTATION = 2; + + // Oriented bounding box. The box does not have to be parallel to horizontal + // line. + IMAGE_ORIENTED_BOUNDING_BOX_ANNOTATION = 13; + + // Bounding poly annotations in an image. + IMAGE_BOUNDING_POLY_ANNOTATION = 10; + + // Polyline annotations in an image. + IMAGE_POLYLINE_ANNOTATION = 11; + + // Segmentation annotations in an image. + IMAGE_SEGMENTATION_ANNOTATION = 12; + + // Classification annotations in video shots. + VIDEO_SHOTS_CLASSIFICATION_ANNOTATION = 3; + + // Video object tracking annotation. + VIDEO_OBJECT_TRACKING_ANNOTATION = 4; + + // Video object detection annotation. + VIDEO_OBJECT_DETECTION_ANNOTATION = 5; + + // Video event annotation. + VIDEO_EVENT_ANNOTATION = 6; + + // Speech to text annotation. + AUDIO_TRANSCRIPTION_ANNOTATION = 7; + + // Classification for text. + TEXT_CLASSIFICATION_ANNOTATION = 8; + + // Entity extraction for text. + TEXT_ENTITY_EXTRACTION_ANNOTATION = 9; +} + +// Annotation for Example. Each example may have one or more annotations. For +// example in image classification problem, each image might have one or more +// labels. We call labels binded with this image an Annotation. +message Annotation { + // Output only. Unique name of this annotation, format is: + // + // projects/{project_id}/datasets/{dataset_id}/annotatedDatasets/{annotated_dataset}/examples/{example_id}/annotations/{annotation_id} + string name = 1; + + // Output only. The source of the annotation. + AnnotationSource annotation_source = 2; + + // Output only. This is the actual annotation value, e.g classification, + // bounding box values are stored here. + AnnotationValue annotation_value = 3; + + // Output only. Annotation metadata, including information like votes + // for labels. + AnnotationMetadata annotation_metadata = 4; + + // Output only. Sentiment for this annotation. + AnnotationSentiment annotation_sentiment = 6; +} + +// Annotation value for an example. +message AnnotationValue { + oneof value_type { + // Annotation value for image classification case. + ImageClassificationAnnotation image_classification_annotation = 1; + + // Annotation value for image bounding box, oriented bounding box + // and polygon cases. + ImageBoundingPolyAnnotation image_bounding_poly_annotation = 2; + + // Annotation value for image polyline cases. + // Polyline here is different from BoundingPoly. It is formed by + // line segments connected to each other but not closed form(Bounding Poly). + // The line segments can cross each other. + ImagePolylineAnnotation image_polyline_annotation = 8; + + // Annotation value for image segmentation. + ImageSegmentationAnnotation image_segmentation_annotation = 9; + + // Annotation value for text classification case. + TextClassificationAnnotation text_classification_annotation = 3; + + // Annotation value for video classification case. + VideoClassificationAnnotation video_classification_annotation = 4; + + // Annotation value for video object detection and tracking case. + VideoObjectTrackingAnnotation video_object_tracking_annotation = 5; + + // Annotation value for video event case. + VideoEventAnnotation video_event_annotation = 6; + + // Annotation value for speech audio recognition case. + AudioRecognitionAnnotation audio_recognition_annotation = 7; + } +} + +// Image classification annotation definition. +message ImageClassificationAnnotation { + // Label of image. + AnnotationSpec annotation_spec = 1; +} + +// A vertex represents a 2D point in the image. +// NOTE: the vertex coordinates are in the same scale as the original image. +message Vertex { + // X coordinate. + int32 x = 1; + + // Y coordinate. + int32 y = 2; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// A bounding polygon in the image. +message BoundingPoly { + // The bounding polygon vertices. + repeated Vertex vertices = 1; +} + +// Normalized bounding polygon. +message NormalizedBoundingPoly { + // The bounding polygon normalized vertices. + repeated NormalizedVertex normalized_vertices = 1; +} + +// Image bounding poly annotation. It represents a polygon including +// bounding box in the image. +message ImageBoundingPolyAnnotation { + // The region of the polygon. If it is a bounding box, it is guaranteed to be + // four points. + oneof bounded_area { + BoundingPoly bounding_poly = 2; + + NormalizedBoundingPoly normalized_bounding_poly = 3; + } + + // Label of object in this bounding polygon. + AnnotationSpec annotation_spec = 1; +} + +// A line with multiple line segments. +message Polyline { + // The polyline vertices. + repeated Vertex vertices = 1; +} + +// Normalized polyline. +message NormalizedPolyline { + // The normalized polyline vertices. + repeated NormalizedVertex normalized_vertices = 1; +} + +// A polyline for the image annotation. +message ImagePolylineAnnotation { + oneof poly { + Polyline polyline = 2; + + NormalizedPolyline normalized_polyline = 3; + } + + // Label of this polyline. + AnnotationSpec annotation_spec = 1; +} + +// Image segmentation annotation. +message ImageSegmentationAnnotation { + // The mapping between rgb color and annotation spec. The key is the rgb + // color represented in format of rgb(0, 0, 0). The value is the + // AnnotationSpec. + map<string, AnnotationSpec> annotation_colors = 1; + + // Image format. + string mime_type = 2; + + // A byte string of a full image's color map. + bytes image_bytes = 3; +} + +// Text classification annotation. +message TextClassificationAnnotation { + // Label of the text. + AnnotationSpec annotation_spec = 1; +} + +// A time period inside of an example that has a time dimension (e.g. video). +message TimeSegment { + // Start of the time segment (inclusive), represented as the duration since + // the example start. + google.protobuf.Duration start_time_offset = 1; + + // End of the time segment (exclusive), represented as the duration since the + // example start. + google.protobuf.Duration end_time_offset = 2; +} + +// Video classification annotation. +message VideoClassificationAnnotation { + // The time segment of the video to which the annotation applies. + TimeSegment time_segment = 1; + + // Label of the segment specified by time_segment. + AnnotationSpec annotation_spec = 2; +} + +// Video frame level annotation for object detection and tracking. +message ObjectTrackingFrame { + // The bounding box location of this object track for the frame. + oneof bounded_area { + BoundingPoly bounding_poly = 1; + + NormalizedBoundingPoly normalized_bounding_poly = 2; + } + + // The time offset of this frame relative to the beginning of the video. + google.protobuf.Duration time_offset = 3; +} + +// Video object tracking annotation. +message VideoObjectTrackingAnnotation { + // Label of the object tracked in this annotation. + AnnotationSpec annotation_spec = 1; + + // The time segment of the video to which object tracking applies. + TimeSegment time_segment = 2; + + // The list of frames where this object track appears. + repeated ObjectTrackingFrame object_tracking_frames = 3; +} + +// Video event annotation. +message VideoEventAnnotation { + // Label of the event in this annotation. + AnnotationSpec annotation_spec = 1; + + // The time segment of the video to which the annotation applies. + TimeSegment time_segment = 2; +} + +// Speech audio recognition. +message AudioRecognitionAnnotation { + // Transcript text representing the words spoken. + string transcript = 1; + + // Start position in audio file that the transcription corresponds to. + google.protobuf.Duration start_offset = 2; + + // End position in audio file that the transcription corresponds to. + google.protobuf.Duration end_offset = 3; +} + +// Additional information associated with the annotation. +message AnnotationMetadata { + // Metadata related to human labeling. + OperatorMetadata operator_metadata = 2; +} + +// General information useful for labels coming from contributors. +message OperatorMetadata { + // Confidence score corresponding to a label. For examle, if 3 contributors + // have answered the question and 2 of them agree on the final label, the + // confidence score will be 0.67 (2/3). + float score = 1; + + // The total number of contributors that answer this question. + int32 total_votes = 2; + + // The total number of contributors that choose this label. + int32 label_votes = 3; + + repeated string comments = 4; +} diff --git a/google/cloud/datalabeling/v1beta1/annotation_spec_set.proto b/google/cloud/datalabeling/v1beta1/annotation_spec_set.proto new file mode 100644 index 000000000..20fdec73c --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/annotation_spec_set.proto @@ -0,0 +1,56 @@ +// Copyright 2018 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.datalabeling.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/datalabeling/v1beta1;datalabeling"; +option java_multiple_files = true; +option java_package = "com.google.cloud.datalabeling.v1beta1"; + + +// AnnotationSpecSet is a collection of label definitions. For example, in +// image classification tasks, we define a set of labels, this set is called +// AnnotationSpecSet. AnnotationSpecSet is immutable upon creation. +message AnnotationSpecSet { + // Output only. + // AnnotationSpecSet resource name, format: + // projects/{project_id}/annotationSpecSets/{annotation_spec_set_id} + string name = 1; + + // Required. The display name for AnnotationSpecSet defined by user. + // Maximum of 64 characters. + string display_name = 2; + + // Optional. User-provided description of the annotation specification set. + // The description can be up to 10000 characters long. + string description = 3; + + // Required. The actual spec set defined by the users. + repeated AnnotationSpec annotation_specs = 4; +} + +// Container of information related to one annotation spec. +message AnnotationSpec { + // Required. The display name of the AnnotationSpec. Maximum of 64 characters. + string display_name = 1; + + // Optional. User-provided description of the annotation specification. + // The description can be up to 10000 characters long. + string description = 2; +} diff --git a/google/cloud/datalabeling/v1beta1/data_labeling_service.proto b/google/cloud/datalabeling/v1beta1/data_labeling_service.proto new file mode 100644 index 000000000..22222ab71 --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/data_labeling_service.proto @@ -0,0 +1,728 @@ +// Copyright 2018 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.datalabeling.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/datalabeling/v1beta1/annotation_spec_set.proto"; +import "google/cloud/datalabeling/v1beta1/dataset.proto"; +import "google/cloud/datalabeling/v1beta1/human_annotation_config.proto"; +import "google/cloud/datalabeling/v1beta1/instruction.proto"; +import "google/cloud/datalabeling/v1beta1/operations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/datalabeling/v1beta1;datalabeling"; +option java_multiple_files = true; +option java_package = "com.google.cloud.datalabeling.v1beta1"; + + +service DataLabelingService { + // Creates dataset. If success return a Dataset resource. + rpc CreateDataset(CreateDatasetRequest) returns (Dataset) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*}/datasets" + body: "*" + }; + } + + // Gets dataset by resource name. + rpc GetDataset(GetDatasetRequest) returns (Dataset) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/datasets/*}" + }; + } + + // Lists datasets under a project. Pagination is supported. + rpc ListDatasets(ListDatasetsRequest) returns (ListDatasetsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*}/datasets" + }; + } + + // Deletes a dataset by resource name. + rpc DeleteDataset(DeleteDatasetRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/datasets/*}" + }; + } + + // Imports data into dataset based on source locations defined in request. + // It can be called multiple times for the same dataset. Each dataset can + // only have one long running operation running on it. For example, no + // labeling task (also long running operation) can be started while + // importing is still ongoing. Vice versa. + rpc ImportData(ImportDataRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/datasets/*}:importData" + body: "*" + }; + } + + // Exports data and annotations from dataset. + rpc ExportData(ExportDataRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/datasets/*}:exportData" + body: "*" + }; + } + + // Gets a data item in a dataset by resource name. This API can be + // called after data are imported into dataset. + rpc GetDataItem(GetDataItemRequest) returns (DataItem) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/datasets/*/dataItems/*}" + }; + } + + // Lists data items in a dataset. This API can be called after data + // are imported into dataset. Pagination is supported. + rpc ListDataItems(ListDataItemsRequest) returns (ListDataItemsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/datasets/*}/dataItems" + }; + } + + // Gets an annotated dataset by resource name. + rpc GetAnnotatedDataset(GetAnnotatedDatasetRequest) returns (AnnotatedDataset) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/datasets/*/annotatedDatasets/*}" + }; + } + + // Lists annotated datasets for a dataset. Pagination is supported. + rpc ListAnnotatedDatasets(ListAnnotatedDatasetsRequest) returns (ListAnnotatedDatasetsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/datasets/*}/annotatedDatasets" + }; + } + + // Deletes an annotated dataset by resource name. + rpc DeleteAnnotatedDataset(DeleteAnnotatedDatasetRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/datasets/*/annotatedDatasets/*}" + }; + } + + // Starts a labeling task for image. The type of image labeling task is + // configured by feature in the request. + rpc LabelImage(LabelImageRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/datasets/*}/image:label" + body: "*" + }; + } + + // Starts a labeling task for video. The type of video labeling task is + // configured by feature in the request. + rpc LabelVideo(LabelVideoRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/datasets/*}/video:label" + body: "*" + }; + } + + // Starts a labeling task for text. The type of text labeling task is + // configured by feature in the request. + rpc LabelText(LabelTextRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/datasets/*}/text:label" + body: "*" + }; + } + + // Starts a labeling task for audio. The type of audio labeling task is + // configured by feature in the request. + rpc LabelAudio(LabelAudioRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/datasets/*}/audio:label" + body: "*" + }; + } + + // Gets an example by resource name, including both data and annotation. + rpc GetExample(GetExampleRequest) returns (Example) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/datasets/*/annotatedDatasets/*/examples/*}" + }; + } + + // Lists examples in an annotated dataset. Pagination is supported. + rpc ListExamples(ListExamplesRequest) returns (ListExamplesResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/datasets/*/annotatedDatasets/*}/examples" + }; + } + + // Creates an annotation spec set by providing a set of labels. + rpc CreateAnnotationSpecSet(CreateAnnotationSpecSetRequest) returns (AnnotationSpecSet) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*}/annotationSpecSets" + body: "*" + }; + } + + // Gets an annotation spec set by resource name. + rpc GetAnnotationSpecSet(GetAnnotationSpecSetRequest) returns (AnnotationSpecSet) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/annotationSpecSets/*}" + }; + } + + // Lists annotation spec sets for a project. Pagination is supported. + rpc ListAnnotationSpecSets(ListAnnotationSpecSetsRequest) returns (ListAnnotationSpecSetsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*}/annotationSpecSets" + }; + } + + // Deletes an annotation spec set by resource name. + rpc DeleteAnnotationSpecSet(DeleteAnnotationSpecSetRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/annotationSpecSets/*}" + }; + } + + // Creates an instruction for how data should be labeled. + rpc CreateInstruction(CreateInstructionRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*}/instructions" + body: "*" + }; + } + + // Gets an instruction by resource name. + rpc GetInstruction(GetInstructionRequest) returns (Instruction) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/instructions/*}" + }; + } + + // Lists instructions for a project. Pagination is supported. + rpc ListInstructions(ListInstructionsRequest) returns (ListInstructionsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*}/instructions" + }; + } + + // Deletes an instruction object by resource name. + rpc DeleteInstruction(DeleteInstructionRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/instructions/*}" + }; + } +} + +// Request message for CreateDataset. +message CreateDatasetRequest { + // Required. Dataset resource parent, format: + // projects/{project_id} + string parent = 1; + + // Required. The dataset to be created. + Dataset dataset = 2; +} + +// Request message for GetDataSet. +message GetDatasetRequest { + // Required. Dataset resource name, format: + // projects/{project_id}/datasets/{dataset_id} + string name = 1; +} + +// Request message for ListDataset. +message ListDatasetsRequest { + // Required. Dataset resource parent, format: + // projects/{project_id} + string parent = 1; + + // Optional. Filter on dataset is not supported at this moment. + string filter = 2; + + // Optional. Requested page size. Server may return fewer results than + // requested. Default value is 100. + int32 page_size = 3; + + // Optional. A token identifying a page of results for the server to return. + // Typically obtained by + // [ListDatasetsResponse.next_page_token][google.cloud.datalabeling.v1beta1.ListDatasetsResponse.next_page_token] of the previous + // [DataLabelingService.ListDatasets] call. + // Returns the first page if empty. + string page_token = 4; +} + +// Results of listing datasets within a project. +message ListDatasetsResponse { + // The list of datasets to return. + repeated Dataset datasets = 1; + + // A token to retrieve next page of results. + string next_page_token = 2; +} + +// Request message for DeleteDataset. +message DeleteDatasetRequest { + // Required. Dataset resource name, format: + // projects/{project_id}/datasets/{dataset_id} + string name = 1; +} + +// Request message for ImportData API. +message ImportDataRequest { + // Required. Dataset resource name, format: + // projects/{project_id}/datasets/{dataset_id} + string name = 1; + + // Required. Specify the input source of the data. + InputConfig input_config = 2; +} + +// Request message for ExportData API. +message ExportDataRequest { + // Required. Dataset resource name, format: + // projects/{project_id}/datasets/{dataset_id} + string name = 1; + + // Required. Annotated dataset resource name. DataItem in + // Dataset and their annotations in specified annotated dataset will be + // exported. It's in format of + // projects/{project_id}/datasets/{dataset_id}/annotatedDatasets/ + // {annotated_dataset_id} + string annotated_dataset = 2; + + // Optional. Filter is not supported at this moment. + string filter = 3; + + // Required. Specify the output destination. + OutputConfig output_config = 4; +} + +// Request message for GetDataItem. +message GetDataItemRequest { + // Required. The name of the data item to get, format: + // projects/{project_id}/datasets/{dataset_id}/dataItems/{data_item_id} + string name = 1; +} + +// Request message for ListDataItems. +message ListDataItemsRequest { + // Required. Name of the dataset to list data items, format: + // projects/{project_id}/datasets/{dataset_id} + string parent = 1; + + // Optional. Filter is not supported at this moment. + string filter = 2; + + // Optional. Requested page size. Server may return fewer results than + // requested. Default value is 100. + int32 page_size = 3; + + // Optional. A token identifying a page of results for the server to return. + // Typically obtained by + // [ListDataItemsResponse.next_page_token][google.cloud.datalabeling.v1beta1.ListDataItemsResponse.next_page_token] of the previous + // [DataLabelingService.ListDataItems] call. + // Return first page if empty. + string page_token = 4; +} + +// Results of listing data items in a dataset. +message ListDataItemsResponse { + // The list of data items to return. + repeated DataItem data_items = 1; + + // A token to retrieve next page of results. + string next_page_token = 2; +} + +// Request message for GetAnnotatedDataset. +message GetAnnotatedDatasetRequest { + // Required. Name of the annotated dataset to get, format: + // projects/{project_id}/datasets/{dataset_id}/annotatedDatasets/ + // {annotated_dataset_id} + string name = 1; +} + +// Request message for ListAnnotatedDatasets. +message ListAnnotatedDatasetsRequest { + // Required. Name of the dataset to list annotated datasets, format: + // projects/{project_id}/datasets/{dataset_id} + string parent = 1; + + // Optional. Filter is not supported at this moment. + string filter = 2; + + // Optional. Requested page size. Server may return fewer results than + // requested. Default value is 100. + int32 page_size = 3; + + // Optional. A token identifying a page of results for the server to return. + // Typically obtained by + // [ListAnnotatedDatasetsResponse.next_page_token][google.cloud.datalabeling.v1beta1.ListAnnotatedDatasetsResponse.next_page_token] of the previous + // [DataLabelingService.ListAnnotatedDatasets] call. + // Return first page if empty. + string page_token = 4; +} + +// Request message for DeleteAnnotatedDataset. +message DeleteAnnotatedDatasetRequest { + // Required. Name of the annotated dataset to delete, format: + // projects/{project_id}/datasets/{dataset_id}/annotatedDatasets/ + // {annotated_dataset_id} + string name = 1; +} + +// Results of listing annotated datasets for a dataset. +message ListAnnotatedDatasetsResponse { + // The list of annotated datasets to return. + repeated AnnotatedDataset annotated_datasets = 1; + + // A token to retrieve next page of results. + string next_page_token = 2; +} + +// Request message for starting an image labeling task. +message LabelImageRequest { + // Image labeling task feature. + enum Feature { + FEATURE_UNSPECIFIED = 0; + + // Label whole image with one or more of labels. + CLASSIFICATION = 1; + + // Label image with bounding boxes for labels. + BOUNDING_BOX = 2; + + // Label oriented bounding box. The box does not have to be parallel to + // horizontal line. + ORIENTED_BOUNDING_BOX = 6; + + // Label images with bounding poly. A bounding poly is a plane figure that + // is bounded by a finite chain of straight line segments closing in a loop. + BOUNDING_POLY = 3; + + // Label images with polyline. Polyline is formed by connected line segments + // which are not in closed form. + POLYLINE = 4; + + // Label images with segmentation. Segmentation is different from bounding + // poly since it is more fine-grained, pixel level annotation. + SEGMENTATION = 5; + } + + // Required. Config for labeling tasks. The type of request config must + // match the selected feature. + oneof request_config { + // Configuration for image classification task. + // One of image_classification_config, bounding_poly_config, + // polyline_config and segmentation_config is required. + ImageClassificationConfig image_classification_config = 4; + + // Configuration for bounding box and bounding poly task. + // One of image_classification_config, bounding_poly_config, + // polyline_config and segmentation_config is required. + BoundingPolyConfig bounding_poly_config = 5; + + // Configuration for polyline task. + // One of image_classification_config, bounding_poly_config, + // polyline_config and segmentation_config is required. + PolylineConfig polyline_config = 6; + + // Configuration for segmentation task. + // One of image_classification_config, bounding_poly_config, + // polyline_config and segmentation_config is required. + SegmentationConfig segmentation_config = 7; + } + + // Required. Name of the dataset to request labeling task, format: + // projects/{project_id}/datasets/{dataset_id} + string parent = 1; + + // Required. Basic human annotation config. + HumanAnnotationConfig basic_config = 2; + + // Required. The type of image labeling task. + Feature feature = 3; +} + +// Request message for LabelVideo. +message LabelVideoRequest { + // Video labeling task feature. + enum Feature { + FEATURE_UNSPECIFIED = 0; + + // Label whole video or video segment with one or more labels. + CLASSIFICATION = 1; + + // Label objects with bounding box on image frames extracted from the video. + OBJECT_DETECTION = 2; + + // Label and track objects in video. + OBJECT_TRACKING = 3; + + // Label the range of video for the specified events. + EVENT = 4; + } + + // Required. Config for labeling tasks. The type of request config must + // match the selected feature. + oneof request_config { + // Configuration for video classification task. + // One of video_classification_config, object_detection_config, + // object_tracking_config and event_config is required. + VideoClassificationConfig video_classification_config = 4; + + // Configuration for video object detection task. + // One of video_classification_config, object_detection_config, + // object_tracking_config and event_config is required. + ObjectDetectionConfig object_detection_config = 5; + + // Configuration for video object tracking task. + // One of video_classification_config, object_detection_config, + // object_tracking_config and event_config is required. + ObjectTrackingConfig object_tracking_config = 6; + + // Configuration for video event task. + // One of video_classification_config, object_detection_config, + // object_tracking_config and event_config is required. + EventConfig event_config = 7; + } + + // Required. Name of the dataset to request labeling task, format: + // projects/{project_id}/datasets/{dataset_id} + string parent = 1; + + // Required. Basic human annotation config. + HumanAnnotationConfig basic_config = 2; + + // Required. The type of video labeling task. + Feature feature = 3; +} + +// Request message for LabelText. +message LabelTextRequest { + // Text labeling task feature. + enum Feature { + FEATURE_UNSPECIFIED = 0; + + // Label text content to one of more labels. + TEXT_CLASSIFICATION = 1; + + // Label entities and their span in text. + TEXT_ENTITY_EXTRACTION = 2; + } + + // Required. Config for labeling tasks. The type of request config must + // match the selected feature. + oneof request_config { + // Configuration for text classification task. + // One of text_classification_config and text_entity_extraction_config + // is required. + TextClassificationConfig text_classification_config = 4; + + // Configuration for entity extraction task. + // One of text_classification_config and text_entity_extraction_config + // is required. + TextEntityExtractionConfig text_entity_extraction_config = 5; + } + + // Required. Name of the data set to request labeling task, format: + // projects/{project_id}/datasets/{dataset_id} + string parent = 1; + + // Required. Basic human annotation config. + HumanAnnotationConfig basic_config = 2; + + // Required. The type of text labeling task. + Feature feature = 6; +} + +// Request message for LabelAudio. +message LabelAudioRequest { + // Audio labeling task feature. + enum Feature { + FEATURE_UNSPECIFIED = 0; + + // Transcribe the audios into text. + AUDIO_TRANSCRIPTION = 1; + } + + // Required. Name of the dataset to request labeling task, format: + // projects/{project_id}/datasets/{dataset_id} + string parent = 1; + + // Required. Basic human annotation config. + HumanAnnotationConfig basic_config = 2; + + // Required. The type of audio labeling task. + Feature feature = 3; +} + +// Request message for GetExample +message GetExampleRequest { + // Required. Name of example, format: + // projects/{project_id}/datasets/{dataset_id}/annotatedDatasets/ + // {annotated_dataset_id}/examples/{example_id} + string name = 1; + + // Optional. An expression for filtering Examples. Filter by + // annotation_spec.display_name is supported. Format + // "annotation_spec.display_name = {display_name}" + string filter = 2; +} + +// Request message for ListExamples. +message ListExamplesRequest { + // Required. Example resource parent. + string parent = 1; + + // Optional. An expression for filtering Examples. For annotated datasets that + // have annotation spec set, filter by + // annotation_spec.display_name is supported. Format + // "annotation_spec.display_name = {display_name}" + string filter = 2; + + // Optional. Requested page size. Server may return fewer results than + // requested. Default value is 100. + int32 page_size = 3; + + // Optional. A token identifying a page of results for the server to return. + // Typically obtained by + // [ListExamplesResponse.next_page_token][google.cloud.datalabeling.v1beta1.ListExamplesResponse.next_page_token] of the previous + // [DataLabelingService.ListExamples] call. + // Return first page if empty. + string page_token = 4; +} + +// Results of listing Examples in and annotated dataset. +message ListExamplesResponse { + // The list of examples to return. + repeated Example examples = 1; + + // A token to retrieve next page of results. + string next_page_token = 2; +} + +// Request message for CreateAnnotationSpecSet. +message CreateAnnotationSpecSetRequest { + // Required. AnnotationSpecSet resource parent, format: + // projects/{project_id} + string parent = 1; + + // Required. Annotation spec set to create. Annotation specs must be included. + // Only one annotation spec will be accepted for annotation specs with same + // display_name. + AnnotationSpecSet annotation_spec_set = 2; +} + +// Request message for GetAnnotationSpecSet. +message GetAnnotationSpecSetRequest { + // Required. AnnotationSpecSet resource name, format: + // projects/{project_id}/annotationSpecSets/{annotation_spec_set_id} + string name = 1; +} + +// Request message for ListAnnotationSpecSets. +message ListAnnotationSpecSetsRequest { + // Required. Parent of AnnotationSpecSet resource, format: + // projects/{project_id} + string parent = 1; + + // Optional. Filter is not supported at this moment. + string filter = 2; + + // Optional. Requested page size. Server may return fewer results than + // requested. Default value is 100. + int32 page_size = 3; + + // Optional. A token identifying a page of results for the server to return. + // Typically obtained by + // [ListAnnotationSpecSetsResponse.next_page_token][google.cloud.datalabeling.v1beta1.ListAnnotationSpecSetsResponse.next_page_token] of the previous + // [DataLabelingService.ListAnnotationSpecSets] call. + // Return first page if empty. + string page_token = 4; +} + +// Results of listing annotation spec set under a project. +message ListAnnotationSpecSetsResponse { + // The list of annotation spec sets. + repeated AnnotationSpecSet annotation_spec_sets = 1; + + // A token to retrieve next page of results. + string next_page_token = 2; +} + +// Request message for DeleteAnnotationSpecSet. +message DeleteAnnotationSpecSetRequest { + // Required. AnnotationSpec resource name, format: + // `projects/{project_id}/annotationSpecSets/{annotation_spec_set_id}`. + string name = 1; +} + +// Request message for CreateInstruction. +message CreateInstructionRequest { + // Required. Instruction resource parent, format: + // projects/{project_id} + string parent = 1; + + // Required. Instruction of how to perform the labeling task. + Instruction instruction = 2; +} + +// Request message for GetInstruction. +message GetInstructionRequest { + // Required. Instruction resource name, format: + // projects/{project_id}/instructions/{instruction_id} + string name = 1; +} + +// Request message for DeleteInstruction. +message DeleteInstructionRequest { + // Required. Instruction resource name, format: + // projects/{project_id}/instructions/{instruction_id} + string name = 1; +} + +// Request message for ListInstructions. +message ListInstructionsRequest { + // Required. Instruction resource parent, format: + // projects/{project_id} + string parent = 1; + + // Optional. Filter is not supported at this moment. + string filter = 2; + + // Optional. Requested page size. Server may return fewer results than + // requested. Default value is 100. + int32 page_size = 3; + + // Optional. A token identifying a page of results for the server to return. + // Typically obtained by + // [ListInstructionsResponse.next_page_token][google.cloud.datalabeling.v1beta1.ListInstructionsResponse.next_page_token] of the previous + // [DataLabelingService.ListInstructions] call. + // Return first page if empty. + string page_token = 4; +} + +// Results of listing instructions under a project. +message ListInstructionsResponse { + // The list of Instructions to return. + repeated Instruction instructions = 1; + + // A token to retrieve next page of results. + string next_page_token = 2; +} diff --git a/google/cloud/datalabeling/v1beta1/datalabeling_gapic.yaml b/google/cloud/datalabeling/v1beta1/datalabeling_gapic.yaml new file mode 100644 index 000000000..36197fdd8 --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/datalabeling_gapic.yaml @@ -0,0 +1,540 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.datalabeling.v1beta1 + python: + package_name: google.cloud.datalabeling_v1beta1.gapic + go: + package_name: cloud.google.com/go/datalabeling/apiv1beta1 + csharp: + package_name: Google.Cloud.Datalabeling.V1beta1 + ruby: + package_name: Google::Cloud::Datalabeling::V1beta1 + php: + package_name: Google\Cloud\Datalabeling\V1beta1 + nodejs: + package_name: datalabeling.v1beta1 + domain_layer_location: google-cloud +# The configuration for the license header to put on generated files. +license_header: + # The file containing the raw license header without any copyright line(s). + license_file: license-header-apache-2.0.txt +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.datalabeling.v1beta1.DataLabelingService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + - name_pattern: projects/{project}/annotationSpecSets/{annotation_spec_set} + entity_name: annotation_spec_set + - name_pattern: projects/{project}/datasets/{dataset} + entity_name: dataset + - name_pattern: projects/{project}/datasets/{dataset}/annotatedDatasets/{annotated_dataset} + entity_name: annotated_dataset + - name_pattern: projects/{project}/datasets/{dataset}/annotatedDatasets/{annotated_dataset}/examples/{example} + entity_name: example + - name_pattern: projects/{project}/datasets/{dataset}/dataItems/{data_item} + entity_name: data_item + - name_pattern: projects/{project}/instructions/{instruction} + entity_name: instruction + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 30000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 300000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateDataset + flattening: + groups: + - parameters: + - parent + - dataset + required_fields: + - parent + - dataset + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 30000 + - name: GetDataset + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: dataset + timeout_millis: 30000 + - name: ListDatasets + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: datasets + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 30000 + - name: DeleteDataset + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: dataset + timeout_millis: 30000 + - name: ImportData + flattening: + groups: + - parameters: + - name + - input_config + required_fields: + - name + - input_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: dataset + long_running: + return_type: google.cloud.datalabeling.v1beta1.ImportDataOperationResponse + metadata_type: google.cloud.datalabeling.v1beta1.ImportDataOperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 30000 + - name: ExportData + flattening: + groups: + - parameters: + - name + - annotated_dataset + - filter + - output_config + required_fields: + - name + - annotated_dataset + - output_config + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: dataset + long_running: + return_type: google.cloud.datalabeling.v1beta1.ExportDataOperationResponse + metadata_type: google.cloud.datalabeling.v1beta1.ExportDataOperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 30000 + - name: GetDataItem + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: data_item + timeout_millis: 30000 + - name: ListDataItems + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: data_items + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: dataset + timeout_millis: 30000 + - name: GetAnnotatedDataset + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: annotated_dataset + timeout_millis: 30000 + - name: ListAnnotatedDatasets + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: annotated_datasets + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: dataset + timeout_millis: 30000 + - name: LabelImage + flattening: + groups: + - parameters: + - parent + - basic_config + - feature + required_fields: + - parent + - basic_config + - feature + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: dataset + long_running: + return_type: google.cloud.datalabeling.v1beta1.AnnotatedDataset + metadata_type: google.cloud.datalabeling.v1beta1.LabelOperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 30000 + - name: LabelVideo + flattening: + groups: + - parameters: + - parent + - basic_config + - feature + required_fields: + - parent + - basic_config + - feature + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: dataset + long_running: + return_type: google.cloud.datalabeling.v1beta1.AnnotatedDataset + metadata_type: google.cloud.datalabeling.v1beta1.LabelOperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 30000 + - name: LabelText + flattening: + groups: + - parameters: + - parent + - basic_config + - feature + required_fields: + - parent + - basic_config + - feature + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: dataset + long_running: + return_type: google.cloud.datalabeling.v1beta1.AnnotatedDataset + metadata_type: google.cloud.datalabeling.v1beta1.LabelOperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 30000 + - name: LabelAudio + flattening: + groups: + - parameters: + - parent + - basic_config + - feature + required_fields: + - parent + - basic_config + - feature + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: dataset + long_running: + return_type: google.cloud.datalabeling.v1beta1.AnnotatedDataset + metadata_type: google.cloud.datalabeling.v1beta1.LabelOperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 30000 + - name: GetExample + flattening: + groups: + - parameters: + - name + - filter + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: example + timeout_millis: 30000 + - name: ListExamples + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: examples + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: annotated_dataset + timeout_millis: 30000 + - name: CreateAnnotationSpecSet + flattening: + groups: + - parameters: + - parent + - annotation_spec_set + required_fields: + - parent + - annotation_spec_set + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 30000 + - name: GetAnnotationSpecSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: annotation_spec_set + timeout_millis: 30000 + - name: ListAnnotationSpecSets + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: annotation_spec_sets + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 30000 + - name: DeleteAnnotationSpecSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: annotation_spec_set + timeout_millis: 30000 + - name: CreateInstruction + flattening: + groups: + - parameters: + - parent + - instruction + required_fields: + - parent + - instruction + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + long_running: + return_type: google.cloud.datalabeling.v1beta1.Instruction + metadata_type: google.cloud.datalabeling.v1beta1.CreateInstructionMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 30000 + - name: GetInstruction + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: instruction + timeout_millis: 30000 + - name: ListInstructions + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: instructions + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 30000 + - name: DeleteInstruction + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: instruction + timeout_millis: 30000 diff --git a/google/cloud/datalabeling/v1beta1/dataset.proto b/google/cloud/datalabeling/v1beta1/dataset.proto new file mode 100644 index 000000000..952daf38d --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/dataset.proto @@ -0,0 +1,306 @@ +// Copyright 2018 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.datalabeling.v1beta1; + +import "google/cloud/datalabeling/v1beta1/annotation.proto"; +import "google/cloud/datalabeling/v1beta1/human_annotation_config.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/datalabeling/v1beta1;datalabeling"; +option java_multiple_files = true; +option java_package = "com.google.cloud.datalabeling.v1beta1"; + + +enum DataType { + DATA_TYPE_UNSPECIFIED = 0; + + IMAGE = 1; + + VIDEO = 2; + + TEXT = 4; + + AUDIO = 5; +} + +// Dataset is the resource to hold your data. You can request multiple labeling +// tasks for a dataset while each one will generate an AnnotatedDataset. +message Dataset { + // Output only. + // Dataset resource name, format is: + // projects/{project_id}/datasets/{dataset_id} + string name = 1; + + // Required. The display name of the dataset. Maximum of 64 characters. + string display_name = 2; + + // Optional. User-provided description of the annotation specification set. + // The description can be up to 10000 characters long. + string description = 3; + + // Output only. Time the dataset is created. + google.protobuf.Timestamp create_time = 4; + + // Output only. This is populated with the original input configs + // where ImportData is called. It is available only after the clients + // import data to this dataset. + repeated InputConfig input_configs = 5; +} + +// The configuration of input data, including data type, location, etc. +message InputConfig { + // Required. Where the data is from. + oneof source { + GcsSource gcs_source = 2; + } + + // Required. Data type must be specifed when user tries to import data. + DataType data_type = 1; +} + +// Source of the GCS file to be imported. Only gcs path is allowed in +// input_uri. +message GcsSource { + // Required. The input uri of source file. + string input_uri = 1; + + // Required. The format of the gcs source. Only "text/csv" is supported. + string mime_type = 2; +} + +// The configuration of output data. +message OutputConfig { + // Required. Location to output data to. + oneof destination { + // Output to a GCS file. Should be used for labeling output other than Audio + // transcription. + GcsDestination gcs_destination = 1; + + // Output to a GCS folder. Should be used for Audio transcription + // labeling output. + GcsFolderDestination gcs_folder_destination = 2; + } +} + +// Export destination of the data.Only gcs path is allowed in +// output_uri. +message GcsDestination { + // Required. The output uri of destination file. + string output_uri = 1; + + // Required. The format of the gcs destination. Only "text/csv" and + // "application/json" + // are supported. + string mime_type = 2; +} + +// Export folder destination of the data. +message GcsFolderDestination { + // Required. GCS folder to export data to. + string output_folder_uri = 1; +} + +// DataItem is a piece of data, without annotation. For example, an image. +message DataItem { + // Output only. + oneof payload { + // The image payload, a container of the image bytes/uri. + ImagePayload image_payload = 2; + + // The text payload, a container of text content. + TextPayload text_payload = 3; + + // The video payload, a container of the video uri. + VideoPayload video_payload = 4; + + // The audio payload, a container of the audio uri. + AudioPayload audio_payload = 5; + } + + // Output only. Name of the data item, in format of: + // projects/{project_id}/datasets/{dataset_id}/dataItems/{data_item_id} + string name = 1; +} + +// AnnotatedDataset is a set holding annotations for data in a Dataset. Each +// labeling task will generate an AnnotatedDataset under the Dataset that the +// task is requested for. +message AnnotatedDataset { + // Output only. + // AnnotatedDataset resource name in format of: + // projects/{project_id}/datasets/{dataset_id}/annotatedDatasets/ + // {annotated_dataset_id} + string name = 1; + + // Output only. The display name of the AnnotatedDataset. It is specified in + // HumanAnnotationConfig when user starts a labeling task. Maximum of 64 + // characters. + string display_name = 2; + + // Output only. The description of the AnnotatedDataset. It is specified in + // HumanAnnotationConfig when user starts a labeling task. Maximum of 10000 + // characters. + string description = 9; + + // Output only. Source of the annotation. + AnnotationSource annotation_source = 3; + + // Output only. Type of the annotation. It is specified when starting labeling + // task. + AnnotationType annotation_type = 8; + + // Output only. Number of examples in the annotated dataset. + int64 example_count = 4; + + // Output only. Number of examples that have annotation in the annotated + // dataset. + int64 completed_example_count = 5; + + // Output only. Per label statistics. + LabelStats label_stats = 6; + + // Output only. Time the AnnotatedDataset was created. + google.protobuf.Timestamp create_time = 7; + + // Output only. Additional information about AnnotatedDataset. + AnnotatedDatasetMetadata metadata = 10; +} + +// Metadata on AnnotatedDataset. +message AnnotatedDatasetMetadata { + // HumanAnnotationConfig used when requesting the human labeling task for this + // AnnotatedDataset. + HumanAnnotationConfig human_annotation_config = 1; + + // Specific request configuration used when requesting the labeling task. + oneof annotation_request_config { + // Configuration for image classification task. + ImageClassificationConfig image_classification_config = 2; + // Configuration for image bounding box and bounding poly task. + BoundingPolyConfig bounding_poly_config = 3; + // Configuration for image polyline task. + PolylineConfig polyline_config = 4; + // Configuration for image segmentation task. + SegmentationConfig segmentation_config = 5; + // Configuration for video classification task. + VideoClassificationConfig video_classification_config = 6; + // Configuration for video object detection task. + ObjectDetectionConfig object_detection_config = 7; + // Configuration for video object tracking task. + ObjectTrackingConfig object_tracking_config = 8; + // Configuration for video event labeling task. + EventConfig event_config = 9; + // Configuration for text classification task. + TextClassificationConfig text_classification_config = 10; + // Configuration for text entity extraction task. + TextEntityExtractionConfig text_entity_extraction_config = 11; + } +} + +// Statistics about annotation specs. +message LabelStats { + // Map of each annotation spec's example count. Key is the annotation spec + // name and value is the number of examples for that annotation spec. + map<string, int64> example_count = 1; +} + +// An Example is a piece of data and its annotation. For example, an image with +// label "house". +message Example { + // Output only. The data part of Example. + oneof payload { + // The image payload, a container of the image bytes/uri. + ImagePayload image_payload = 2; + + // The text payload, a container of the text content. + TextPayload text_payload = 6; + + // The video payload, a container of the video uri. + VideoPayload video_payload = 7; + + // The audio payload, a container of the audio uri. + AudioPayload audio_payload = 8; + } + + // Output only. Name of the example, in format of: + // projects/{project_id}/datasets/{dataset_id}/annotatedDatasets/ + // {annotated_dataset_id}/examples/{example_id} + string name = 1; + + // Output only. Annotations for the piece of data in Example. + // One piece of data can have multiple annotations. + repeated Annotation annotations = 5; +} + +// Container of information about an image. +message ImagePayload { + // Image format. + string mime_type = 1; + + // A byte string of a full image. + bytes image_thumbnail = 2; + + // Image uri from the user bucket. + string image_uri = 3; +} + +// Container of information about a piece of text. +message TextPayload { + // Text content. + string text_content = 1; +} + +// Container of information of a video thumbnail. +message VideoThumbnail { + // A byte string of the video frame. + bytes thumbnail = 1; + + // Time offset relative to the beginning of the video, corresponding to the + // video frame where the thumbnail has been extracted from. + google.protobuf.Duration time_offset = 2; +} + +// Container of information of a video. +message VideoPayload { + // Video format. + string mime_type = 1; + + // Video uri from the user bucket. + string video_uri = 2; + + // The list of video thumbnails. + repeated VideoThumbnail video_thumbnails = 3; + + // FPS of the video. + float frame_rate = 4; +} + +// Container of information of an audio. +message AudioPayload { + // Audio uri in user bucket. + string audio_uri = 1; + + // Sample rate in Hertz of the audio data sent in all + // `RecognitionAudio` messages. This field is optional for `FLAC` and `WAV` + // audio files and required for all other audio formats. For details, + // see [AudioEncoding][google.cloud.datalabeling.v1beta1.AudioPayload.AudioEncoding]. + int32 sample_rate_hertz = 3; +} diff --git a/google/cloud/datalabeling/v1beta1/human_annotation_config.proto b/google/cloud/datalabeling/v1beta1/human_annotation_config.proto new file mode 100644 index 000000000..96672aeda --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/human_annotation_config.proto @@ -0,0 +1,208 @@ +// Copyright 2018 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.datalabeling.v1beta1; + +import "google/protobuf/duration.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/datalabeling/v1beta1;datalabeling"; +option java_multiple_files = true; +option java_package = "com.google.cloud.datalabeling.v1beta1"; + + +enum StringAggregationType { + STRING_AGGREGATION_TYPE_UNSPECIFIED = 0; + + // Majority vote to aggregate answers. + MAJORITY_VOTE = 1; + + // Unanimous answers will be adopted. + UNANIMOUS_VOTE = 2; + + // Preserve all answers by crowd compute. + NO_AGGREGATION = 3; +} + +// Configuration for how human labeling task should be done. +message HumanAnnotationConfig { + // Required except for LabelAudio case. Instruction resource name. + string instruction = 1; + + // Required. A human-readable name for AnnotatedDataset defined by + // users. Maximum of 64 characters + // . + string annotated_dataset_display_name = 2; + + // Optional. A human-readable description for AnnotatedDataset. + // The description can be up to 10000 characters long. + string annotated_dataset_description = 3; + + // Optional. A human-readable label used to logically group labeling tasks. + // This string must match the regular expression `[a-zA-Z\\d_-]{0,128}`. + string label_group = 4; + + // Optional. The Language of this question, as a + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). + // Default value is en-US. + // Only need to set this when task is language related. For example, French + // text classification or Chinese audio transcription. + string language_code = 5; + + // Optional. Replication of questions. Each question will be sent to up to + // this number of contributors to label. Aggregated answers will be returned. + // Default is set to 1. + // For image related labeling, valid values are 1, 3, 5. + int32 replica_count = 6; + + // Optional. Maximum duration for contributors to answer a question. Default + // is 1800 seconds. + google.protobuf.Duration question_duration = 7; + + // Optional. If you want your own labeling contributors to manage and work on + // this labeling request, you can set these contributors here. We will give + // them access to the question types in crowdcompute. Note that these + // emails must be registered in crowdcompute worker UI: + // https://crowd-compute.appspot.com/ + repeated string contributor_emails = 9; +} + +// Config for image classification human labeling task. +message ImageClassificationConfig { + // Required. Annotation spec set resource name. + string annotation_spec_set = 1; + + // Optional. If allow_multi_label is true, contributors are able to choose + // multiple labels for one image. + bool allow_multi_label = 2; + + // Optional. The type of how to aggregate answers. + StringAggregationType answer_aggregation_type = 3; +} + +// Config for image bounding poly (and bounding box) human labeling task. +message BoundingPolyConfig { + // Required. Annotation spec set resource name. + string annotation_spec_set = 1; + + // Optional. Instruction message showed on contributors UI. + string instruction_message = 2; +} + +// Config for image polyline human labeling task. +message PolylineConfig { + // Required. Annotation spec set resource name. + string annotation_spec_set = 1; + + // Optional. Instruction message showed on contributors UI. + string instruction_message = 2; +} + +// Config for image segmentation +message SegmentationConfig { + // Required. Annotation spec set resource name. format: + // projects/{project_id}/annotationSpecSets/{annotation_spec_set_id} + string annotation_spec_set = 1; + + // Instruction message showed on labelers UI. + string instruction_message = 2; +} + +// Config for video classification human labeling task. +// Currently two types of video classification are supported: +// 1. Assign labels on the entire video. +// 2. Split the video into multiple video clips based on camera shot, and +// assign labels on each video clip. +message VideoClassificationConfig { + // Annotation spec set with the setting of allowing multi labels or not. + message AnnotationSpecSetConfig { + // Required. Annotation spec set resource name. + string annotation_spec_set = 1; + + // Optional. If allow_multi_label is true, contributors are able to + // choose multiple labels from one annotation spec set. + bool allow_multi_label = 2; + } + + // Required. The list of annotation spec set configs. + // Since watching a video clip takes much longer time than an image, we + // support label with multiple AnnotationSpecSet at the same time. Labels + // in each AnnotationSpecSet will be shown in a group to contributors. + // Contributors can select one or more (depending on whether to allow multi + // label) from each group. + repeated AnnotationSpecSetConfig annotation_spec_set_configs = 1; + + // Optional. Option to apply shot detection on the video. + bool apply_shot_detection = 2; +} + +// Config for video object detection human labeling task. +// Object detection will be conducted on the images extracted from the video, +// and those objects will be labeled with bounding boxes. +// User need to specify the number of images to be extracted per second as the +// extraction frame rate. +message ObjectDetectionConfig { + // Required. Annotation spec set resource name. + string annotation_spec_set = 1; + + // Optional. Instruction message showed on labelers UI. + string instruction_message = 2; + + // Required. Number of frames per second to be extracted from the video. + double extraction_frame_rate = 3; +} + +// Config for video object tracking human labeling task. +message ObjectTrackingConfig { + // Required. Annotation spec set resource name. + string annotation_spec_set = 1; +} + +// Config for video event human labeling task. +message EventConfig { + // Required. The list of annotation spec set resource name. Similar to video + // classification, we support selecting event from multiple AnnotationSpecSet + // at the same time. + repeated string annotation_spec_sets = 1; +} + +// Config for text classification human labeling task. +message TextClassificationConfig { + // Optional. If allow_multi_label is true, contributors are able to choose + // multiple labels for one text segment. + bool allow_multi_label = 1; + + // Required. Annotation spec set resource name. + string annotation_spec_set = 2; + + // Optional. Configs for sentiment selection. + SentimentConfig sentiment_config = 3; +} + +// Config for setting up sentiments. +message SentimentConfig { + // If set to true, contributors will have the option to select sentiment of + // the label they selected, to mark it as negative or positive label. Default + // is false. + bool enable_label_sentiment_selection = 1; +} + +// Config for text entity extraction human labeling task. +message TextEntityExtractionConfig { + // Required. Annotation spec set resource name. + string annotation_spec_set = 1; +} diff --git a/google/cloud/datalabeling/v1beta1/instruction.proto b/google/cloud/datalabeling/v1beta1/instruction.proto new file mode 100644 index 000000000..d1a1e751c --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/instruction.proto @@ -0,0 +1,78 @@ +// Copyright 2018 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.datalabeling.v1beta1; + +import "google/cloud/datalabeling/v1beta1/dataset.proto"; +import "google/protobuf/timestamp.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/datalabeling/v1beta1;datalabeling"; +option java_multiple_files = true; +option java_package = "com.google.cloud.datalabeling.v1beta1"; + + +// Instruction of how to perform the labeling task for human operators. +// Currently two types of instruction are supported - CSV file and PDF. +// One of the two types instruction must be provided. +// CSV file is only supported for image classification task. Instructions for +// other task should be provided as PDF. +// For image classification, CSV and PDF can be provided at the same time. +message Instruction { + // Output only. Instruction resource name, format: + // projects/{project_id}/instructions/{instruction_id} + string name = 1; + + // Required. The display name of the instruction. Maximum of 64 characters. + string display_name = 2; + + // Optional. User-provided description of the instruction. + // The description can be up to 10000 characters long. + string description = 3; + + // Output only. Creation time of instruction. + google.protobuf.Timestamp create_time = 4; + + // Output only. Last update time of instruction. + google.protobuf.Timestamp update_time = 5; + + // Required. The data type of this instruction. + DataType data_type = 6; + + // One of CSV and PDF instruction is required. + // Instruction from a csv file, such as for classification task. + // Csv file should have exact two columns, in the format of: + // The first column is labeled data, such as image reference, text. + // The second column is comma separated labels associated with data. + CsvInstruction csv_instruction = 7; + + // One of CSV and PDF instruction is required. + // Instruction from a PDF doc. The PDF doc should be in GCS bucket. + PdfInstruction pdf_instruction = 9; +} + +// Instruction from a CSV file. +message CsvInstruction { + // CSV file for the instruction. Only gcs path is allowed. + string gcs_file_uri = 1; +} + +// Instruction from a PDF file. +message PdfInstruction { + // PDF file for the instruction. Only gcs path is allowed. + string gcs_file_uri = 1; +} diff --git a/google/cloud/datalabeling/v1beta1/operations.proto b/google/cloud/datalabeling/v1beta1/operations.proto new file mode 100644 index 000000000..71815e531 --- /dev/null +++ b/google/cloud/datalabeling/v1beta1/operations.proto @@ -0,0 +1,206 @@ +// Copyright 2018 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.datalabeling.v1beta1; + +import "google/cloud/datalabeling/v1beta1/dataset.proto"; +import "google/cloud/datalabeling/v1beta1/human_annotation_config.proto"; +import "google/cloud/datalabeling/v1beta1/instruction.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/datalabeling/v1beta1;datalabeling"; +option java_multiple_files = true; +option java_package = "com.google.cloud.datalabeling.v1beta1"; + +// Response used for ImportData longrunning operation. +message ImportDataOperationResponse { + // Ouptut only. The name of imported dataset. + string dataset = 1; + + // Output only. Total number of examples requested to import + int32 total_count = 2; + + // Output only. Number of examples imported successfully. + int32 import_count = 3; +} + +// Response used for ExportDataset longrunning operation. +message ExportDataOperationResponse { + // Ouptut only. The name of dataset. + // "projects/*/datasets/*/Datasets/*" + string dataset = 1; + + // Output only. Total number of examples requested to export + int32 total_count = 2; + + // Output only. Number of examples exported successfully. + int32 export_count = 3; + + // Output only. Statistic infos of labels in the exported dataset. + LabelStats label_stats = 4; + + // Output only. output_config in the ExportData request. + OutputConfig output_config = 5; +} + +// Metadata of an ImportData operation. +message ImportDataOperationMetadata { + // Ouptut only. The name of imported dataset. + // "projects/*/datasets/*" + string dataset = 1; + + // Output only. Partial failures encountered. + // E.g. single files that couldn't be read. + // Status details field will contain standard GCP error details. + repeated google.rpc.Status partial_failures = 2; +} + +// Metadata of an ExportData operation. +message ExportDataOperationMetadata { + // Output only. The name of dataset to be exported. + // "projects/*/datasets/*/Datasets/*" + string dataset = 1; + + // Output only. Partial failures encountered. + // E.g. single files that couldn't be read. + // Status details field will contain standard GCP error details. + repeated google.rpc.Status partial_failures = 2; +} + +// Metadata of a labeling operation, such as LabelImage or LabelVideo. +// Next tag: 16 +message LabelOperationMetadata { + // Output only. Progress of label operation. Range: [0, 100]. + // Currently not supported. + int32 progress_percent = 1; + + // Output only. Partial failures encountered. + // E.g. single files that couldn't be read. + // Status details field will contain standard GCP error details. + repeated google.rpc.Status partial_failures = 2; + + // Ouptut only. Details of specific label operation. + oneof details { + LabelImageClassificationOperationMetadata image_classification_details = 3; + LabelImageBoundingBoxOperationMetadata image_bounding_box_details = 4; + LabelImageBoundingPolyOperationMetadata image_bounding_poly_details = 11; + LabelImageOrientedBoundingBoxOperationMetadata + image_oriented_bounding_box_details = 14; + LabelImagePolylineOperationMetadata image_polyline_details = 12; + LabelImageSegmentationOperationMetadata image_segmentation_details = 15; + LabelVideoClassificationOperationMetadata video_classification_details = 5; + LabelVideoObjectDetectionOperationMetadata video_object_detection_details = + 6; + LabelVideoObjectTrackingOperationMetadata video_object_tracking_details = 7; + LabelVideoEventOperationMetadata video_event_details = 8; + LabelTextClassificationOperationMetadata text_classification_details = 9; + LabelAudioTranscriptionOperationMetadata audio_transcription_details = 10; + LabelTextEntityExtractionOperationMetadata text_entity_extraction_details = + 13; + } +} + +// Metadata of a LabelImageClassification operation. +message LabelImageClassificationOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelImageBoundingBox operation metadata. +message LabelImageBoundingBoxOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelImageOrientedBoundingBox operation metadata. +message LabelImageOrientedBoundingBoxOperationMetadata { + // Basic human annotation config. + HumanAnnotationConfig basic_config = 1; +} + +// Details of LabelImageBoundingPoly operation metadata. +message LabelImageBoundingPolyOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of LabelImagePolyline operation metadata. +message LabelImagePolylineOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelImageSegmentation operation metadata. +message LabelImageSegmentationOperationMetadata { + // Basic human annotation config. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelVideoClassification operation metadata. +message LabelVideoClassificationOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelVideoObjectDetection operation metadata. +message LabelVideoObjectDetectionOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelVideoObjectTracking operation metadata. +message LabelVideoObjectTrackingOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelVideoEvent operation metadata. +message LabelVideoEventOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelTextClassification operation metadata. +message LabelTextClassificationOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +message LabelAudioTranscriptionOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Details of a LabelTextEntityExtraction operation metadata. +message LabelTextEntityExtractionOperationMetadata { + // Basic human annotation config used in labeling request. + HumanAnnotationConfig basic_config = 1; +} + +// Metadata of a CreateInstruction operation. +message CreateInstructionMetadata { + // Output only. The name of the created Instruction. + // projects/{project_id}/instructions/{instruction_id} + string instruction = 1; + + // Output only. Partial failures encountered. + // E.g. single files that couldn't be read. + // Status details field will contain standard GCP error details. + repeated google.rpc.Status partial_failures = 2; +} diff --git a/google/cloud/dataproc/BUILD.bazel b/google/cloud/dataproc/BUILD.bazel new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/google/cloud/dataproc/BUILD.bazel diff --git a/google/cloud/dataproc/artman_dataproc_v1.yaml b/google/cloud/dataproc/artman_dataproc_v1.yaml new file mode 100644 index 000000000..211938f79 --- /dev/null +++ b/google/cloud/dataproc/artman_dataproc_v1.yaml @@ -0,0 +1,34 @@ +common: + api_name: dataproc + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: v1/dataproc.yaml + gapic_yaml: v1/dataproc_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/dataproc/artman_dataproc_v1beta2.yaml b/google/cloud/dataproc/artman_dataproc_v1beta2.yaml new file mode 100644 index 000000000..9917355a7 --- /dev/null +++ b/google/cloud/dataproc/artman_dataproc_v1beta2.yaml @@ -0,0 +1,34 @@ +common: + api_name: dataproc + api_version: v1beta2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta2 + service_yaml: v1beta2/dataproc.yaml + gapic_yaml: v1beta2/dataproc_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/dataproc/dataproc.yaml b/google/cloud/dataproc/dataproc.yaml new file mode 100644 index 000000000..c13e830aa --- /dev/null +++ b/google/cloud/dataproc/dataproc.yaml @@ -0,0 +1,60 @@ +type: google.api.Service +config_version: 2 +name: dataproc.googleapis.com +title: Cloud Dataproc API + +apis: +- name: google.cloud.dataproc.v1beta2.ClusterController +- name: google.cloud.dataproc.v1beta2.JobController +- name: google.cloud.dataproc.v1beta2.WorkflowTemplateService + +types: +- name: google.cloud.dataproc.v1.DiagnoseClusterResults +- name: google.cloud.dataproc.v1.ClusterOperationMetadata +- name: google.cloud.dataproc.v1beta2.DiagnoseClusterResults +- name: google.cloud.dataproc.v1beta2.ClusterOperationMetadata +- name: google.cloud.dataproc.v1beta2.WorkflowMetadata + +documentation: + summary: 'Manages Hadoop-based clusters and jobs on Google Cloud Platform.' + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1/{name=projects/*/regions/*/operations}' + additional_bindings: + - get: '/v1beta2/{name=projects/*/regions/*/operations}' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=projects/*/regions/*/operations/*}' + additional_bindings: + - get: '/v1beta2/{name=projects/*/regions/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/{name=projects/*/regions/*/operations/*}' + additional_bindings: + - delete: '/v1beta2/{name=projects/*/regions/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/{name=projects/*/regions/*/operations/*}:cancel' + additional_bindings: + - post: '/v1beta2/{name=projects/*/regions/*/operations/*}:cancel' + + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + post: '/v1beta2/{resource=projects/*/regions/*/clusters/*}:setIamPolicy' + body: '*' + + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + get: '/v1beta2/{resource=projects/*/regions/*/clusters/*}:getIamPolicy' + + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + post: '/v1beta2/{resource=projects/*/regions/*/clusters/*}:testIamPermissions' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/dataproc/v1/BUILD.bazel b/google/cloud/dataproc/v1/BUILD.bazel new file mode 100644 index 000000000..58359d5d8 --- /dev/null +++ b/google/cloud/dataproc/v1/BUILD.bazel @@ -0,0 +1,153 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "dataproc_proto", + srcs = [ + "clusters.proto", + "jobs.proto", + "operations.proto", + "workflow_templates.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "dataproc_proto_with_info", + deps = [":dataproc_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "dataproc_java_proto", + deps = [":dataproc_proto"], +) + +java_grpc_library( + name = "dataproc_java_grpc", + srcs = [":dataproc_proto"], + deps = [":dataproc_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "dataproc_resource_name_java_proto", + gapic_yaml = "dataproc_gapic.yaml", + deps = [":dataproc_proto"], +) + +java_gapic_library( + name = "dataproc_java_gapic", + src = ":dataproc_proto_with_info", + gapic_yaml = "dataproc_gapic.yaml", + service_yaml = "dataproc.yaml", + test_deps = [":dataproc_java_grpc"], + deps = [ + ":dataproc_java_proto", + ":dataproc_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":dataproc_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.dataproc.v1.ClusterControllerClientTest", + "com.google.cloud.dataproc.v1.JobControllerClientTest", + "com.google.cloud.dataproc.v1.WorkflowTemplateServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-dataproc-v1-java", + client_deps = [":dataproc_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":dataproc_java_gapic_test"], + grpc_deps = [":dataproc_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":dataproc_java_proto", + ":dataproc_proto", + ":dataproc_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "dataproc_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/dataproc/v1", + protos = [":dataproc_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + ], +) + +go_gapic_library( + name = "dataproc_go_gapic", + src = ":dataproc_proto_with_info", + gapic_yaml = "dataproc_gapic.yaml", + importpath = "cloud.google.com/go/dataproc/apiv1", + service_yaml = "dataproc.yaml", + deps = [ + ":dataproc_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "dataproc_go_gapic_test", + srcs = [":dataproc_go_gapic_srcjar_test"], + embed = [":dataproc_go_gapic"], + importpath = "cloud.google.com/go/dataproc/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-dataproc-v1-go", + deps = [ + ":dataproc_go_gapic", + ":dataproc_go_gapic_srcjar-smoke-test.srcjar", + ":dataproc_go_gapic_srcjar-test.srcjar", + ":dataproc_go_proto", + ], +) diff --git a/google/cloud/dataproc/v1/clusters.proto b/google/cloud/dataproc/v1/clusters.proto new file mode 100644 index 000000000..31873aad1 --- /dev/null +++ b/google/cloud/dataproc/v1/clusters.proto @@ -0,0 +1,713 @@ +// Copyright 2018 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.dataproc.v1; + +import "google/api/annotations.proto"; +import "google/cloud/dataproc/v1/operations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "ClustersProto"; +option java_package = "com.google.cloud.dataproc.v1"; + +// The ClusterControllerService provides methods to manage clusters +// of Compute Engine instances. +service ClusterController { + // Creates a cluster in a project. + rpc CreateCluster(CreateClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/projects/{project_id}/regions/{region}/clusters" + body: "cluster" + }; + } + + // Updates a cluster in a project. + rpc UpdateCluster(UpdateClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v1/projects/{project_id}/regions/{region}/clusters/{cluster_name}" + body: "cluster" + }; + } + + // Deletes a cluster in a project. + rpc DeleteCluster(DeleteClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1/projects/{project_id}/regions/{region}/clusters/{cluster_name}" + }; + } + + // Gets the resource representation for a cluster in a project. + rpc GetCluster(GetClusterRequest) returns (Cluster) { + option (google.api.http) = { + get: "/v1/projects/{project_id}/regions/{region}/clusters/{cluster_name}" + }; + } + + // Lists all regions/{region}/clusters in a project. + rpc ListClusters(ListClustersRequest) returns (ListClustersResponse) { + option (google.api.http) = { + get: "/v1/projects/{project_id}/regions/{region}/clusters" + }; + } + + // Gets cluster diagnostic information. + // After the operation completes, the Operation.response field + // contains `DiagnoseClusterOutputLocation`. + rpc DiagnoseCluster(DiagnoseClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/projects/{project_id}/regions/{region}/clusters/{cluster_name}:diagnose" + body: "*" + }; + } +} + +// Describes the identifying information, config, and status of +// a cluster of Compute Engine instances. +message Cluster { + // Required. The Google Cloud Platform project ID that the cluster belongs to. + string project_id = 1; + + // Required. The cluster name. Cluster names within a project must be + // unique. Names of deleted clusters can be reused. + string cluster_name = 2; + + // Required. The cluster config. Note that Cloud Dataproc may set + // default values, and values may change when clusters are updated. + ClusterConfig config = 3; + + // Optional. The labels to associate with this cluster. + // Label **keys** must contain 1 to 63 characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // Label **values** may be empty, but, if present, must contain 1 to 63 + // characters, and must conform to [RFC + // 1035](https://www.ietf.org/rfc/rfc1035.txt). No more than 32 labels can be + // associated with a cluster. + map<string, string> labels = 8; + + // Output only. Cluster status. + ClusterStatus status = 4; + + // Output only. The previous cluster status. + repeated ClusterStatus status_history = 7; + + // Output only. A cluster UUID (Unique Universal Identifier). Cloud Dataproc + // generates this value when it creates the cluster. + string cluster_uuid = 6; + + // Contains cluster daemon metrics such as HDFS and YARN stats. + // + // **Beta Feature**: This report is available for testing purposes only. It + // may be changed before final release. + ClusterMetrics metrics = 9; +} + +// The cluster config. +message ClusterConfig { + // Optional. A Cloud Storage staging bucket used for sharing generated + // SSH keys and config. If you do not specify a staging bucket, Cloud + // Dataproc will determine an appropriate Cloud Storage location (US, + // ASIA, or EU) for your cluster's staging bucket according to the Google + // Compute Engine zone where your cluster is deployed, and then it will create + // and manage this project-level, per-location bucket for you. + string config_bucket = 1; + + // Required. The shared Compute Engine config settings for + // all instances in a cluster. + GceClusterConfig gce_cluster_config = 8; + + // Optional. The Compute Engine config settings for + // the master instance in a cluster. + InstanceGroupConfig master_config = 9; + + // Optional. The Compute Engine config settings for + // worker instances in a cluster. + InstanceGroupConfig worker_config = 10; + + // Optional. The Compute Engine config settings for + // additional worker instances in a cluster. + InstanceGroupConfig secondary_worker_config = 12; + + // Optional. The config settings for software inside the cluster. + SoftwareConfig software_config = 13; + + // Optional. Commands to execute on each node after config is + // completed. By default, executables are run on master and all worker nodes. + // You can test a node's `role` metadata to run an executable on + // a master or worker node, as shown below using `curl` (you can also use + // `wget`): + // + // ROLE=$(curl -H Metadata-Flavor:Google + // http://metadata/computeMetadata/v1/instance/attributes/dataproc-role) + // if [[ "${ROLE}" == 'Master' ]]; then + // ... master specific actions ... + // else + // ... worker specific actions ... + // fi + repeated NodeInitializationAction initialization_actions = 11; + + // Optional. Encryption settings for the cluster. + EncryptionConfig encryption_config = 15; +} + +// Encryption settings for the cluster. +message EncryptionConfig { + // Optional. The Cloud KMS key name to use for PD disk encryption for all + // instances in the cluster. + string gce_pd_kms_key_name = 1; +} + +// Common config settings for resources of Compute Engine cluster +// instances, applicable to all instances in the cluster. +message GceClusterConfig { + // Optional. The zone where the Compute Engine cluster will be located. + // On a create request, it is required in the "global" region. If omitted + // in a non-global Cloud Dataproc region, the service will pick a zone in the + // corresponding Compute Engine region. On a get request, zone will + // always be present. + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/zones/[zone]` + // * `projects/[project_id]/zones/[zone]` + // * `us-central1-f` + string zone_uri = 1; + + // Optional. The Compute Engine network to be used for machine + // communications. Cannot be specified with subnetwork_uri. If neither + // `network_uri` nor `subnetwork_uri` is specified, the "default" network of + // the project is used, if it exists. Cannot be a "Custom Subnet Network" (see + // [Using Subnetworks](/compute/docs/subnetworks) for more information). + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/regions/global/default` + // * `projects/[project_id]/regions/global/default` + // * `default` + string network_uri = 2; + + // Optional. The Compute Engine subnetwork to be used for machine + // communications. Cannot be specified with network_uri. + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/regions/us-east1/sub0` + // * `projects/[project_id]/regions/us-east1/sub0` + // * `sub0` + string subnetwork_uri = 6; + + // Optional. If true, all instances in the cluster will only have internal IP + // addresses. By default, clusters are not restricted to internal IP + // addresses, and will have ephemeral external IP addresses assigned to each + // instance. This `internal_ip_only` restriction can only be enabled for + // subnetwork enabled networks, and all off-cluster dependencies must be + // configured to be accessible without external IP addresses. + bool internal_ip_only = 7; + + // Optional. The service account of the instances. Defaults to the default + // Compute Engine service account. Custom service accounts need + // permissions equivalent to the following IAM roles: + // + // * roles/logging.logWriter + // * roles/storage.objectAdmin + // + // (see + // https://cloud.google.com/compute/docs/access/service-accounts#custom_service_accounts + // for more information). + // Example: `[account_id]@[project_id].iam.gserviceaccount.com` + string service_account = 8; + + // Optional. The URIs of service account scopes to be included in + // Compute Engine instances. The following base set of scopes is always + // included: + // + // * https://www.googleapis.com/auth/cloud.useraccounts.readonly + // * https://www.googleapis.com/auth/devstorage.read_write + // * https://www.googleapis.com/auth/logging.write + // + // If no scopes are specified, the following defaults are also provided: + // + // * https://www.googleapis.com/auth/bigquery + // * https://www.googleapis.com/auth/bigtable.admin.table + // * https://www.googleapis.com/auth/bigtable.data + // * https://www.googleapis.com/auth/devstorage.full_control + repeated string service_account_scopes = 3; + + // The Compute Engine tags to add to all instances (see + // [Tagging instances](/compute/docs/label-or-tag-resources#tags)). + repeated string tags = 4; + + // The Compute Engine metadata entries to add to all instances (see + // [Project and instance + // metadata](https://cloud.google.com/compute/docs/storing-retrieving-metadata#project_and_instance_metadata)). + map<string, string> metadata = 5; +} + +// Optional. The config settings for Compute Engine resources in +// an instance group, such as a master or worker group. +message InstanceGroupConfig { + // Optional. The number of VM instances in the instance group. + // For master instance groups, must be set to 1. + int32 num_instances = 1; + + // Output only. The list of instance names. Cloud Dataproc derives the names + // from `cluster_name`, `num_instances`, and the instance group. + repeated string instance_names = 2; + + // Optional. The Compute Engine image resource used for cluster + // instances. It can be specified or may be inferred from + // `SoftwareConfig.image_version`. + string image_uri = 3; + + // Optional. The Compute Engine machine type used for cluster instances. + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/zones/us-east1-a/machineTypes/n1-standard-2` + // * `projects/[project_id]/zones/us-east1-a/machineTypes/n1-standard-2` + // * `n1-standard-2` + // + // **Auto Zone Exception**: If you are using the Cloud Dataproc + // [Auto Zone + // Placement](/dataproc/docs/concepts/configuring-clusters/auto-zone#using_auto_zone_placement) + // feature, you must use the short name of the machine type + // resource, for example, `n1-standard-2`. + string machine_type_uri = 4; + + // Optional. Disk option config settings. + DiskConfig disk_config = 5; + + // Optional. Specifies that this instance group contains preemptible + // instances. + bool is_preemptible = 6; + + // Output only. The config for Compute Engine Instance Group + // Manager that manages this group. + // This is only used for preemptible instance groups. + ManagedGroupConfig managed_group_config = 7; + + // Optional. The Compute Engine accelerator configuration for these + // instances. + // + // **Beta Feature**: This feature is still under development. It may be + // changed before final release. + repeated AcceleratorConfig accelerators = 8; +} + +// Specifies the resources used to actively manage an instance group. +message ManagedGroupConfig { + // Output only. The name of the Instance Template used for the Managed + // Instance Group. + string instance_template_name = 1; + + // Output only. The name of the Instance Group Manager for this group. + string instance_group_manager_name = 2; +} + +// Specifies the type and number of accelerator cards attached to the instances +// of an instance. See [GPUs on Compute Engine](/compute/docs/gpus/). +message AcceleratorConfig { + // Full URL, partial URI, or short name of the accelerator type resource to + // expose to this instance. See + // [Compute Engine + // AcceleratorTypes](/compute/docs/reference/beta/acceleratorTypes). + // + // Examples: + // + // * `https://www.googleapis.com/compute/beta/projects/[project_id]/zones/us-east1-a/acceleratorTypes/nvidia-tesla-k80` + // * `projects/[project_id]/zones/us-east1-a/acceleratorTypes/nvidia-tesla-k80` + // * `nvidia-tesla-k80` + // + // **Auto Zone Exception**: If you are using the Cloud Dataproc + // [Auto Zone + // Placement](/dataproc/docs/concepts/configuring-clusters/auto-zone#using_auto_zone_placement) + // feature, you must use the short name of the accelerator type + // resource, for example, `nvidia-tesla-k80`. + string accelerator_type_uri = 1; + + // The number of the accelerator cards of this type exposed to this instance. + int32 accelerator_count = 2; +} + +// Specifies the config of disk options for a group of VM instances. +message DiskConfig { + // Optional. Type of the boot disk (default is "pd-standard"). + // Valid values: "pd-ssd" (Persistent Disk Solid State Drive) or + // "pd-standard" (Persistent Disk Hard Disk Drive). + string boot_disk_type = 3; + + // Optional. Size in GB of the boot disk (default is 500GB). + int32 boot_disk_size_gb = 1; + + // Optional. Number of attached SSDs, from 0 to 4 (default is 0). + // If SSDs are not attached, the boot disk is used to store runtime logs and + // [HDFS](https://hadoop.apache.org/docs/r1.2.1/hdfs_user_guide.html) data. + // If one or more SSDs are attached, this runtime bulk + // data is spread across them, and the boot disk contains only basic + // config and installed binaries. + int32 num_local_ssds = 2; +} + +// Specifies an executable to run on a fully configured node and a +// timeout period for executable completion. +message NodeInitializationAction { + // Required. Cloud Storage URI of executable file. + string executable_file = 1; + + // Optional. Amount of time executable has to complete. Default is + // 10 minutes. Cluster creation fails with an explanatory error message (the + // name of the executable that caused the error and the exceeded timeout + // period) if the executable is not completed at end of the timeout period. + google.protobuf.Duration execution_timeout = 2; +} + +// The status of a cluster and its instances. +message ClusterStatus { + // The cluster state. + enum State { + // The cluster state is unknown. + UNKNOWN = 0; + + // The cluster is being created and set up. It is not ready for use. + CREATING = 1; + + // The cluster is currently running and healthy. It is ready for use. + RUNNING = 2; + + // The cluster encountered an error. It is not ready for use. + ERROR = 3; + + // The cluster is being deleted. It cannot be used. + DELETING = 4; + + // The cluster is being updated. It continues to accept and process jobs. + UPDATING = 5; + } + + // The cluster substate. + enum Substate { + // The cluster substate is unknown. + UNSPECIFIED = 0; + + // The cluster is known to be in an unhealthy state + // (for example, critical daemons are not running or HDFS capacity is + // exhausted). + // + // Applies to RUNNING state. + UNHEALTHY = 1; + + // The agent-reported status is out of date (may occur if + // Cloud Dataproc loses communication with Agent). + // + // Applies to RUNNING state. + STALE_STATUS = 2; + } + + // Output only. The cluster's state. + State state = 1; + + // Output only. Optional details of cluster's state. + string detail = 2; + + // Output only. Time when this state was entered. + google.protobuf.Timestamp state_start_time = 3; + + // Output only. Additional state information that includes + // status reported by the agent. + Substate substate = 4; +} + +// Specifies the selection and config of software inside the cluster. +message SoftwareConfig { + // Optional. The version of software inside the cluster. It must be one of the + // supported [Cloud Dataproc + // Versions](/dataproc/docs/concepts/versioning/dataproc-versions#supported_cloud_dataproc_versions), + // such as "1.2" (including a subminor version, such as "1.2.29"), or the + // ["preview" + // version](/dataproc/docs/concepts/versioning/dataproc-versions#other_versions). + // If unspecified, it defaults to the latest version. + string image_version = 1; + + // Optional. The properties to set on daemon config files. + // + // Property keys are specified in `prefix:property` format, such as + // `core:fs.defaultFS`. The following are supported prefixes + // and their mappings: + // + // * capacity-scheduler: `capacity-scheduler.xml` + // * core: `core-site.xml` + // * distcp: `distcp-default.xml` + // * hdfs: `hdfs-site.xml` + // * hive: `hive-site.xml` + // * mapred: `mapred-site.xml` + // * pig: `pig.properties` + // * spark: `spark-defaults.conf` + // * yarn: `yarn-site.xml` + // + // For more information, see + // [Cluster properties](/dataproc/docs/concepts/cluster-properties). + map<string, string> properties = 2; +} + +// Contains cluster daemon metrics, such as HDFS and YARN stats. +// +// **Beta Feature**: This report is available for testing purposes only. It may +// be changed before final release. +message ClusterMetrics { + // The HDFS metrics. + map<string, int64> hdfs_metrics = 1; + + // The YARN metrics. + map<string, int64> yarn_metrics = 2; +} + +// A request to create a cluster. +message CreateClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster to create. + Cluster cluster = 2; + + // Optional. A unique id used to identify the request. If the server + // receives two + // [CreateClusterRequest][google.cloud.dataproc.v1.CreateClusterRequest] + // requests with the same id, then the second request will be ignored and the + // first [google.longrunning.Operation][google.longrunning.Operation] created + // and stored in the backend is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 4; +} + +// A request to update a cluster. +message UpdateClusterRequest { + // Required. The ID of the Google Cloud Platform project the + // cluster belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 5; + + // Required. The cluster name. + string cluster_name = 2; + + // Required. The changes to the cluster. + Cluster cluster = 3; + + // Optional. Timeout for graceful YARN decomissioning. Graceful + // decommissioning allows removing nodes from the cluster without + // interrupting jobs in progress. Timeout specifies how long to wait for jobs + // in progress to finish before forcefully removing nodes (and potentially + // interrupting jobs). Default timeout is 0 (for forceful decommission), and + // the maximum allowed timeout is 1 day. + // + // Only supported on Dataproc image versions 1.2 and higher. + google.protobuf.Duration graceful_decommission_timeout = 6; + + // Required. Specifies the path, relative to `Cluster`, of + // the field to update. For example, to change the number of workers + // in a cluster to 5, the `update_mask` parameter would be + // specified as `config.worker_config.num_instances`, + // and the `PATCH` request body would specify the new value, as follows: + // + // { + // "config":{ + // "workerConfig":{ + // "numInstances":"5" + // } + // } + // } + // Similarly, to change the number of preemptible workers in a cluster to 5, + // the `update_mask` parameter would be + // `config.secondary_worker_config.num_instances`, and the `PATCH` request + // body would be set as follows: + // + // { + // "config":{ + // "secondaryWorkerConfig":{ + // "numInstances":"5" + // } + // } + // } + // <strong>Note:</strong> Currently, only the following fields can be updated: + // + // <table> + // <tbody> + // <tr> + // <td><strong>Mask</strong></td> + // <td><strong>Purpose</strong></td> + // </tr> + // <tr> + // <td><strong><em>labels</em></strong></td> + // <td>Update labels</td> + // </tr> + // <tr> + // <td><strong><em>config.worker_config.num_instances</em></strong></td> + // <td>Resize primary worker group</td> + // </tr> + // <tr> + // <td><strong><em>config.secondary_worker_config.num_instances</em></strong></td> + // <td>Resize secondary worker group</td> + // </tr> + // </tbody> + // </table> + google.protobuf.FieldMask update_mask = 4; + + // Optional. A unique id used to identify the request. If the server + // receives two + // [UpdateClusterRequest][google.cloud.dataproc.v1.UpdateClusterRequest] + // requests with the same id, then the second request will be ignored and the + // first [google.longrunning.Operation][google.longrunning.Operation] created + // and stored in the backend is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 7; +} + +// A request to delete a cluster. +message DeleteClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster name. + string cluster_name = 2; + + // Optional. Specifying the `cluster_uuid` means the RPC should fail + // (with error NOT_FOUND) if cluster with specified UUID does not exist. + string cluster_uuid = 4; + + // Optional. A unique id used to identify the request. If the server + // receives two + // [DeleteClusterRequest][google.cloud.dataproc.v1.DeleteClusterRequest] + // requests with the same id, then the second request will be ignored and the + // first [google.longrunning.Operation][google.longrunning.Operation] created + // and stored in the backend is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 5; +} + +// Request to get the resource representation for a cluster in a project. +message GetClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster name. + string cluster_name = 2; +} + +// A request to list the clusters in a project. +message ListClustersRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 4; + + // Optional. A filter constraining the clusters to list. Filters are + // case-sensitive and have the following syntax: + // + // field = value [AND [field = value]] ... + // + // where **field** is one of `status.state`, `clusterName`, or `labels.[KEY]`, + // and `[KEY]` is a label key. **value** can be `*` to match all values. + // `status.state` can be one of the following: `ACTIVE`, `INACTIVE`, + // `CREATING`, `RUNNING`, `ERROR`, `DELETING`, or `UPDATING`. `ACTIVE` + // contains the `CREATING`, `UPDATING`, and `RUNNING` states. `INACTIVE` + // contains the `DELETING` and `ERROR` states. + // `clusterName` is the name of the cluster provided at creation time. + // Only the logical `AND` operator is supported; space-separated items are + // treated as having an implicit `AND` operator. + // + // Example filter: + // + // status.state = ACTIVE AND clusterName = mycluster + // AND labels.env = staging AND labels.starred = * + string filter = 5; + + // Optional. The standard List page size. + int32 page_size = 2; + + // Optional. The standard List page token. + string page_token = 3; +} + +// The list of all clusters in a project. +message ListClustersResponse { + // Output only. The clusters in the project. + repeated Cluster clusters = 1; + + // Output only. This token is included in the response if there are more + // results to fetch. To fetch additional results, provide this value as the + // `page_token` in a subsequent `ListClustersRequest`. + string next_page_token = 2; +} + +// A request to collect cluster diagnostic information. +message DiagnoseClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster name. + string cluster_name = 2; +} + +// The location of diagnostic output. +message DiagnoseClusterResults { + // Output only. The Cloud Storage URI of the diagnostic output. + // The output report is a plain text file with a summary of collected + // diagnostics. + string output_uri = 1; +} diff --git a/google/cloud/dataproc/v1/dataproc.yaml b/google/cloud/dataproc/v1/dataproc.yaml new file mode 100644 index 000000000..e6d36de27 --- /dev/null +++ b/google/cloud/dataproc/v1/dataproc.yaml @@ -0,0 +1,40 @@ +type: google.api.Service +config_version: 2 +name: dataproc.googleapis.com +title: Google Cloud Dataproc API + +apis: +- name: google.cloud.dataproc.v1.ClusterController +- name: google.cloud.dataproc.v1.JobController +- name: google.cloud.dataproc.v1.WorkflowTemplateService + +types: +- name: google.cloud.dataproc.v1.DiagnoseClusterResults +- name: google.cloud.dataproc.v1.ClusterOperationMetadata +- name: google.cloud.dataproc.v1.WorkflowMetadata + +documentation: + summary: 'Manages Hadoop-based clusters and jobs on Google Cloud Platform.' + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1/{name=projects/*/regions/*/operations}' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=projects/*/regions/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/{name=projects/*/regions/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/{name=projects/*/regions/*/operations/*}:cancel' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + diff --git a/google/cloud/dataproc/v1/dataproc_gapic.yaml b/google/cloud/dataproc/v1/dataproc_gapic.yaml new file mode 100644 index 000000000..ab7e2bd3e --- /dev/null +++ b/google/cloud/dataproc/v1/dataproc_gapic.yaml @@ -0,0 +1,658 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.dataproc.v1 + python: + package_name: google.cloud.dataproc_v1.gapic + go: + package_name: cloud.google.com/go/dataproc/apiv1 + csharp: + package_name: Google.Cloud.Dataproc.V1 + ruby: + package_name: Google::Cloud::Dataproc::V1 + php: + package_name: Google\Cloud\Dataproc\V1 + nodejs: + package_name: dataproc.v1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.dataproc.v1.ClusterController + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for smoke test. + smoke_test: + method: ListClusters + init_fields: + - project_id=$PROJECT_ID + - region="global" + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - INTERNAL + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: + - UNAVAILABLE + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 10000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 10000 + total_timeout_millis: 300000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster + required_fields: + - project_id + - region + - cluster + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + long_running: + return_type: google.cloud.dataproc.v1.Cluster + metadata_type: google.cloud.dataproc.v1.ClusterOperationMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 900000 + - name: UpdateCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + - cluster + - update_mask + required_fields: + - project_id + - region + - cluster_name + - cluster + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + long_running: + return_type: google.cloud.dataproc.v1.Cluster + metadata_type: google.cloud.dataproc.v1.ClusterOperationMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 900000 + - name: DeleteCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + required_fields: + - project_id + - region + - cluster_name + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1.ClusterOperationMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 900000 + - name: GetCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + required_fields: + - project_id + - region + - cluster_name + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: ListClusters + flattening: + groups: + - parameters: + - project_id + - region + - parameters: + - project_id + - region + - filter + required_fields: + - project_id + - region + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: clusters + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: DiagnoseCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + required_fields: + - project_id + - region + - cluster_name + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1.DiagnoseClusterResults + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.dataproc.v1.JobController + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - INTERNAL + - UNAVAILABLE + - name: non_idempotent + retry_codes: + - UNAVAILABLE + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 30000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 30000 + total_timeout_millis: 900000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: SubmitJob + flattening: + groups: + - parameters: + - project_id + - region + - job + required_fields: + - project_id + - region + - job + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + - name: GetJob + flattening: + groups: + - parameters: + - project_id + - region + - job_id + required_fields: + - project_id + - region + - job_id + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: ListJobs + flattening: + groups: + - parameters: + - project_id + - region + - parameters: + - project_id + - region + - filter + required_fields: + - project_id + - region + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: jobs + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: UpdateJob + required_fields: + - project_id + - region + - job_id + - job + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + - name: CancelJob + flattening: + groups: + - parameters: + - project_id + - region + - job_id + required_fields: + - project_id + - region + - job_id + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: DeleteJob + flattening: + groups: + - parameters: + - project_id + - region + - job_id + required_fields: + - project_id + - region + - job_id + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.dataproc.v1.WorkflowTemplateService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/regions/{region} + entity_name: region + - name_pattern: projects/{project}/regions/{region}/workflowTemplates/{workflow_template} + entity_name: workflow_template + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - INTERNAL + - UNAVAILABLE + - name: non_idempotent + retry_codes: + - UNAVAILABLE + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateWorkflowTemplate + flattening: + groups: + - parameters: + - parent + - template + required_fields: + - parent + - template + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: region + timeout_millis: 30000 + - name: GetWorkflowTemplate + # params. + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: workflow_template + timeout_millis: 60000 + - name: InstantiateWorkflowTemplate + flattening: + groups: + - parameters: + - name + - parameters: + - name + - parameters + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: workflow_template + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1.WorkflowMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 43200000 + - name: InstantiateInlineWorkflowTemplate + flattening: + groups: + - parameters: + - parent + - template + required_fields: + - parent + - template + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: region + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1.WorkflowMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 43200000 + - name: UpdateWorkflowTemplate + flattening: + groups: + - parameters: + - template + required_fields: + - template + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + template.name: workflow_template + timeout_millis: 60000 + - name: ListWorkflowTemplates + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: templates + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: region + timeout_millis: 60000 + - name: DeleteWorkflowTemplate + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: workflow_template + timeout_millis: 60000 +resource_name_generation: +- message_name: WorkflowTemplate + field_entity_map: + name: workflow_template +- message_name: CreateWorkflowTemplateRequest + field_entity_map: + parent: region +- message_name: GetWorkflowTemplateRequest + field_entity_map: + name: workflow_template +- message_name: InstantiateWorkflowTemplateRequest + field_entity_map: + name: workflow_template +- message_name: ListWorkflowTemplatesRequest + field_entity_map: + parent: region +- message_name: DeleteWorkflowTemplateRequest + field_entity_map: + name: workflow_template diff --git a/google/cloud/dataproc/v1/jobs.proto b/google/cloud/dataproc/v1/jobs.proto new file mode 100644 index 000000000..c331ee236 --- /dev/null +++ b/google/cloud/dataproc/v1/jobs.proto @@ -0,0 +1,778 @@ +// Copyright 2018 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.dataproc.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "JobsProto"; +option java_package = "com.google.cloud.dataproc.v1"; + +// The JobController provides methods to manage jobs. +service JobController { + // Submits a job to a cluster. + rpc SubmitJob(SubmitJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1/projects/{project_id}/regions/{region}/jobs:submit" + body: "*" + }; + } + + // Gets the resource representation for a job in a project. + rpc GetJob(GetJobRequest) returns (Job) { + option (google.api.http) = { + get: "/v1/projects/{project_id}/regions/{region}/jobs/{job_id}" + }; + } + + // Lists regions/{region}/jobs in a project. + rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) { + option (google.api.http) = { + get: "/v1/projects/{project_id}/regions/{region}/jobs" + }; + } + + // Updates a job in a project. + rpc UpdateJob(UpdateJobRequest) returns (Job) { + option (google.api.http) = { + patch: "/v1/projects/{project_id}/regions/{region}/jobs/{job_id}" + body: "job" + }; + } + + // Starts a job cancellation request. To access the job resource + // after cancellation, call + // [regions/{region}/jobs.list](/dataproc/docs/reference/rest/v1/projects.regions.jobs/list) + // or + // [regions/{region}/jobs.get](/dataproc/docs/reference/rest/v1/projects.regions.jobs/get). + rpc CancelJob(CancelJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1/projects/{project_id}/regions/{region}/jobs/{job_id}:cancel" + body: "*" + }; + } + + // Deletes the job from the project. If the job is active, the delete fails, + // and the response returns `FAILED_PRECONDITION`. + rpc DeleteJob(DeleteJobRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/projects/{project_id}/regions/{region}/jobs/{job_id}" + }; + } +} + +// The runtime logging config of the job. +message LoggingConfig { + // The Log4j level for job execution. When running an + // [Apache Hive](http://hive.apache.org/) job, Cloud + // Dataproc configures the Hive client to an equivalent verbosity level. + enum Level { + // Level is unspecified. Use default level for log4j. + LEVEL_UNSPECIFIED = 0; + + // Use ALL level for log4j. + ALL = 1; + + // Use TRACE level for log4j. + TRACE = 2; + + // Use DEBUG level for log4j. + DEBUG = 3; + + // Use INFO level for log4j. + INFO = 4; + + // Use WARN level for log4j. + WARN = 5; + + // Use ERROR level for log4j. + ERROR = 6; + + // Use FATAL level for log4j. + FATAL = 7; + + // Turn off log4j. + OFF = 8; + } + + // The per-package log levels for the driver. This may include + // "root" package name to configure rootLogger. + // Examples: + // 'com.google = FATAL', 'root = INFO', 'org.apache = DEBUG' + map<string, Level> driver_log_levels = 2; +} + +// A Cloud Dataproc job for running +// [Apache Hadoop +// MapReduce](https://hadoop.apache.org/docs/current/hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapReduceTutorial.html) +// jobs on [Apache Hadoop +// YARN](https://hadoop.apache.org/docs/r2.7.1/hadoop-yarn/hadoop-yarn-site/YARN.html). +message HadoopJob { + // Required. Indicates the location of the driver's main class. Specify + // either the jar file that contains the main class or the main class name. + // To specify both, add the jar file to `jar_file_uris`, and then specify + // the main class name in this property. + oneof driver { + // The HCFS URI of the jar file containing the main class. + // Examples: + // 'gs://foo-bucket/analytics-binaries/extract-useful-metrics-mr.jar' + // 'hdfs:/tmp/test-samples/custom-wordcount.jar' + // 'file:///home/usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar' + string main_jar_file_uri = 1; + + // The name of the driver's main class. The jar file containing the class + // must be in the default CLASSPATH or specified in `jar_file_uris`. + string main_class = 2; + } + + // Optional. The arguments to pass to the driver. Do not + // include arguments, such as `-libjars` or `-Dfoo=bar`, that can be set as + // job properties, since a collision may occur that causes an incorrect job + // submission. + repeated string args = 3; + + // Optional. Jar file URIs to add to the CLASSPATHs of the + // Hadoop driver and tasks. + repeated string jar_file_uris = 4; + + // Optional. HCFS (Hadoop Compatible Filesystem) URIs of files to be copied + // to the working directory of Hadoop drivers and distributed tasks. Useful + // for naively parallel tasks. + repeated string file_uris = 5; + + // Optional. HCFS URIs of archives to be extracted in the working directory of + // Hadoop drivers and tasks. Supported file types: + // .jar, .tar, .tar.gz, .tgz, or .zip. + repeated string archive_uris = 6; + + // Optional. A mapping of property names to values, used to configure Hadoop. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in /etc/hadoop/conf/*-site and + // classes in user code. + map<string, string> properties = 7; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 8; +} + +// A Cloud Dataproc job for running [Apache Spark](http://spark.apache.org/) +// applications on YARN. +message SparkJob { + // Required. The specification of the main method to call to drive the job. + // Specify either the jar file that contains the main class or the main class + // name. To pass both a main jar and a main class in that jar, add the jar to + // `CommonJob.jar_file_uris`, and then specify the main class name in + // `main_class`. + oneof driver { + // The HCFS URI of the jar file that contains the main class. + string main_jar_file_uri = 1; + + // The name of the driver's main class. The jar file that contains the class + // must be in the default CLASSPATH or specified in `jar_file_uris`. + string main_class = 2; + } + + // Optional. The arguments to pass to the driver. Do not include arguments, + // such as `--conf`, that can be set as job properties, since a collision may + // occur that causes an incorrect job submission. + repeated string args = 3; + + // Optional. HCFS URIs of jar files to add to the CLASSPATHs of the + // Spark driver and tasks. + repeated string jar_file_uris = 4; + + // Optional. HCFS URIs of files to be copied to the working directory of + // Spark drivers and distributed tasks. Useful for naively parallel tasks. + repeated string file_uris = 5; + + // Optional. HCFS URIs of archives to be extracted in the working directory + // of Spark drivers and tasks. Supported file types: + // .jar, .tar, .tar.gz, .tgz, and .zip. + repeated string archive_uris = 6; + + // Optional. A mapping of property names to values, used to configure Spark. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in + // /etc/spark/conf/spark-defaults.conf and classes in user code. + map<string, string> properties = 7; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 8; +} + +// A Cloud Dataproc job for running +// [Apache +// PySpark](https://spark.apache.org/docs/0.9.0/python-programming-guide.html) +// applications on YARN. +message PySparkJob { + // Required. The HCFS URI of the main Python file to use as the driver. Must + // be a .py file. + string main_python_file_uri = 1; + + // Optional. The arguments to pass to the driver. Do not include arguments, + // such as `--conf`, that can be set as job properties, since a collision may + // occur that causes an incorrect job submission. + repeated string args = 2; + + // Optional. HCFS file URIs of Python files to pass to the PySpark + // framework. Supported file types: .py, .egg, and .zip. + repeated string python_file_uris = 3; + + // Optional. HCFS URIs of jar files to add to the CLASSPATHs of the + // Python driver and tasks. + repeated string jar_file_uris = 4; + + // Optional. HCFS URIs of files to be copied to the working directory of + // Python drivers and distributed tasks. Useful for naively parallel tasks. + repeated string file_uris = 5; + + // Optional. HCFS URIs of archives to be extracted in the working directory of + // .jar, .tar, .tar.gz, .tgz, and .zip. + repeated string archive_uris = 6; + + // Optional. A mapping of property names to values, used to configure PySpark. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in + // /etc/spark/conf/spark-defaults.conf and classes in user code. + map<string, string> properties = 7; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 8; +} + +// A list of queries to run on a cluster. +message QueryList { + // Required. The queries to execute. You do not need to terminate a query + // with a semicolon. Multiple queries can be specified in one string + // by separating each with a semicolon. Here is an example of an Cloud + // Dataproc API snippet that uses a QueryList to specify a HiveJob: + // + // "hiveJob": { + // "queryList": { + // "queries": [ + // "query1", + // "query2", + // "query3;query4", + // ] + // } + // } + repeated string queries = 1; +} + +// A Cloud Dataproc job for running [Apache Hive](https://hive.apache.org/) +// queries on YARN. +message HiveJob { + // Required. The sequence of Hive queries to execute, specified as either + // an HCFS file URI or a list of queries. + oneof queries { + // The HCFS URI of the script that contains Hive queries. + string query_file_uri = 1; + + // A list of queries. + QueryList query_list = 2; + } + + // Optional. Whether to continue executing queries if a query fails. + // The default value is `false`. Setting to `true` can be useful when + // executing independent parallel queries. + bool continue_on_failure = 3; + + // Optional. Mapping of query variable names to values (equivalent to the + // Hive command: `SET name="value";`). + map<string, string> script_variables = 4; + + // Optional. A mapping of property names and values, used to configure Hive. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in /etc/hadoop/conf/*-site.xml, + // /etc/hive/conf/hive-site.xml, and classes in user code. + map<string, string> properties = 5; + + // Optional. HCFS URIs of jar files to add to the CLASSPATH of the + // Hive server and Hadoop MapReduce (MR) tasks. Can contain Hive SerDes + // and UDFs. + repeated string jar_file_uris = 6; +} + +// A Cloud Dataproc job for running [Apache Spark +// SQL](http://spark.apache.org/sql/) queries. +message SparkSqlJob { + // Required. The sequence of Spark SQL queries to execute, specified as + // either an HCFS file URI or as a list of queries. + oneof queries { + // The HCFS URI of the script that contains SQL queries. + string query_file_uri = 1; + + // A list of queries. + QueryList query_list = 2; + } + + // Optional. Mapping of query variable names to values (equivalent to the + // Spark SQL command: SET `name="value";`). + map<string, string> script_variables = 3; + + // Optional. A mapping of property names to values, used to configure + // Spark SQL's SparkConf. Properties that conflict with values set by the + // Cloud Dataproc API may be overwritten. + map<string, string> properties = 4; + + // Optional. HCFS URIs of jar files to be added to the Spark CLASSPATH. + repeated string jar_file_uris = 56; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 6; +} + +// A Cloud Dataproc job for running [Apache Pig](https://pig.apache.org/) +// queries on YARN. +message PigJob { + // Required. The sequence of Pig queries to execute, specified as an HCFS + // file URI or a list of queries. + oneof queries { + // The HCFS URI of the script that contains the Pig queries. + string query_file_uri = 1; + + // A list of queries. + QueryList query_list = 2; + } + + // Optional. Whether to continue executing queries if a query fails. + // The default value is `false`. Setting to `true` can be useful when + // executing independent parallel queries. + bool continue_on_failure = 3; + + // Optional. Mapping of query variable names to values (equivalent to the Pig + // command: `name=[value]`). + map<string, string> script_variables = 4; + + // Optional. A mapping of property names to values, used to configure Pig. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in /etc/hadoop/conf/*-site.xml, + // /etc/pig/conf/pig.properties, and classes in user code. + map<string, string> properties = 5; + + // Optional. HCFS URIs of jar files to add to the CLASSPATH of + // the Pig Client and Hadoop MapReduce (MR) tasks. Can contain Pig UDFs. + repeated string jar_file_uris = 6; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 7; +} + +// Cloud Dataproc job config. +message JobPlacement { + // Required. The name of the cluster where the job will be submitted. + string cluster_name = 1; + + // Output only. A cluster UUID generated by the Cloud Dataproc service when + // the job is submitted. + string cluster_uuid = 2; +} + +// Cloud Dataproc job status. +message JobStatus { + // The job state. + enum State { + // The job state is unknown. + STATE_UNSPECIFIED = 0; + + // The job is pending; it has been submitted, but is not yet running. + PENDING = 1; + + // Job has been received by the service and completed initial setup; + // it will soon be submitted to the cluster. + SETUP_DONE = 8; + + // The job is running on the cluster. + RUNNING = 2; + + // A CancelJob request has been received, but is pending. + CANCEL_PENDING = 3; + + // Transient in-flight resources have been canceled, and the request to + // cancel the running job has been issued to the cluster. + CANCEL_STARTED = 7; + + // The job cancellation was successful. + CANCELLED = 4; + + // The job has completed successfully. + DONE = 5; + + // The job has completed, but encountered an error. + ERROR = 6; + + // Job attempt has failed. The detail field contains failure details for + // this attempt. + // + // Applies to restartable jobs only. + ATTEMPT_FAILURE = 9; + } + + // The job substate. + enum Substate { + // The job substate is unknown. + UNSPECIFIED = 0; + + // The Job is submitted to the agent. + // + // Applies to RUNNING state. + SUBMITTED = 1; + + // The Job has been received and is awaiting execution (it may be waiting + // for a condition to be met). See the "details" field for the reason for + // the delay. + // + // Applies to RUNNING state. + QUEUED = 2; + + // The agent-reported status is out of date, which may be caused by a + // loss of communication between the agent and Cloud Dataproc. If the + // agent does not send a timely update, the job will fail. + // + // Applies to RUNNING state. + STALE_STATUS = 3; + } + + // Output only. A state message specifying the overall job state. + State state = 1; + + // Output only. Optional job state details, such as an error + // description if the state is <code>ERROR</code>. + string details = 2; + + // Output only. The time when this state was entered. + google.protobuf.Timestamp state_start_time = 6; + + // Output only. Additional state information, which includes + // status reported by the agent. + Substate substate = 7; +} + +// Encapsulates the full scoping used to reference a job. +message JobReference { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Optional. The job ID, which must be unique within the project. The job ID + // is generated by the server upon job submission or provided by the user as a + // means to perform retries without creating duplicate jobs. The ID must + // contain only letters (a-z, A-Z), numbers (0-9), underscores (_), or + // hyphens (-). The maximum length is 100 characters. + string job_id = 2; +} + +// A YARN application created by a job. Application information is a subset of +// <code>org.apache.hadoop.yarn.proto.YarnProtos.ApplicationReportProto</code>. +// +// **Beta Feature**: This report is available for testing purposes only. It may +// be changed before final release. +message YarnApplication { + // The application state, corresponding to + // <code>YarnProtos.YarnApplicationStateProto</code>. + enum State { + // Status is unspecified. + STATE_UNSPECIFIED = 0; + + // Status is NEW. + NEW = 1; + + // Status is NEW_SAVING. + NEW_SAVING = 2; + + // Status is SUBMITTED. + SUBMITTED = 3; + + // Status is ACCEPTED. + ACCEPTED = 4; + + // Status is RUNNING. + RUNNING = 5; + + // Status is FINISHED. + FINISHED = 6; + + // Status is FAILED. + FAILED = 7; + + // Status is KILLED. + KILLED = 8; + } + + // Required. The application name. + string name = 1; + + // Required. The application state. + State state = 2; + + // Required. The numerical progress of the application, from 1 to 100. + float progress = 3; + + // Optional. The HTTP URL of the ApplicationMaster, HistoryServer, or + // TimelineServer that provides application-specific information. The URL uses + // the internal hostname, and requires a proxy server for resolution and, + // possibly, access. + string tracking_url = 4; +} + +// A Cloud Dataproc job resource. +message Job { + // Optional. The fully qualified reference to the job, which can be used to + // obtain the equivalent REST path of the job resource. If this property + // is not specified when a job is created, the server generates a + // <code>job_id</code>. + JobReference reference = 1; + + // Required. Job information, including how, when, and where to + // run the job. + JobPlacement placement = 2; + + // Required. The application/framework-specific portion of the job. + oneof type_job { + // Job is a Hadoop job. + HadoopJob hadoop_job = 3; + + // Job is a Spark job. + SparkJob spark_job = 4; + + // Job is a Pyspark job. + PySparkJob pyspark_job = 5; + + // Job is a Hive job. + HiveJob hive_job = 6; + + // Job is a Pig job. + PigJob pig_job = 7; + + // Job is a SparkSql job. + SparkSqlJob spark_sql_job = 12; + } + + // Output only. The job status. Additional application-specific + // status information may be contained in the <code>type_job</code> + // and <code>yarn_applications</code> fields. + JobStatus status = 8; + + // Output only. The previous job status. + repeated JobStatus status_history = 13; + + // Output only. The collection of YARN applications spun up by this job. + // + // **Beta** Feature: This report is available for testing purposes only. It + // may be changed before final release. + repeated YarnApplication yarn_applications = 9; + + // Output only. A URI pointing to the location of the stdout of the job's + // driver program. + string driver_output_resource_uri = 17; + + // Output only. If present, the location of miscellaneous control files + // which may be used as part of job setup and handling. If not present, + // control files may be placed in the same location as `driver_output_uri`. + string driver_control_files_uri = 15; + + // Optional. The labels to associate with this job. + // Label **keys** must contain 1 to 63 characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // Label **values** may be empty, but, if present, must contain 1 to 63 + // characters, and must conform to [RFC + // 1035](https://www.ietf.org/rfc/rfc1035.txt). No more than 32 labels can be + // associated with a job. + map<string, string> labels = 18; + + // Optional. Job scheduling configuration. + JobScheduling scheduling = 20; + + // Output only. A UUID that uniquely identifies a job within the project + // over time. This is in contrast to a user-settable reference.job_id that + // may be reused over time. + string job_uuid = 22; +} + +// Job scheduling options. +message JobScheduling { + // Optional. Maximum number of times per hour a driver may be restarted as + // a result of driver terminating with non-zero code before job is + // reported failed. + // + // A job may be reported as thrashing if driver exits with non-zero code + // 4 times within 10 minute window. + // + // Maximum value is 10. + int32 max_failures_per_hour = 1; +} + +// A request to submit a job. +message SubmitJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job resource. + Job job = 2; + + // Optional. A unique id used to identify the request. If the server + // receives two [SubmitJobRequest][google.cloud.dataproc.v1.SubmitJobRequest] + // requests with the same id, then the second request will be ignored and the + // first [Job][google.cloud.dataproc.v1.Job] created and stored in the backend + // is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 4; +} + +// A request to get the resource representation for a job in a project. +message GetJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job ID. + string job_id = 2; +} + +// A request to list jobs in a project. +message ListJobsRequest { + // A matcher that specifies categories of job states. + enum JobStateMatcher { + // Match all jobs, regardless of state. + ALL = 0; + + // Only match jobs in non-terminal states: PENDING, RUNNING, or + // CANCEL_PENDING. + ACTIVE = 1; + + // Only match jobs in terminal states: CANCELLED, DONE, or ERROR. + NON_ACTIVE = 2; + } + + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 6; + + // Optional. The number of results to return in each response. + int32 page_size = 2; + + // Optional. The page token, returned by a previous call, to request the + // next page of results. + string page_token = 3; + + // Optional. If set, the returned jobs list includes only jobs that were + // submitted to the named cluster. + string cluster_name = 4; + + // Optional. Specifies enumerated categories of jobs to list. + // (default = match ALL jobs). + // + // If `filter` is provided, `jobStateMatcher` will be ignored. + JobStateMatcher job_state_matcher = 5; + + // Optional. A filter constraining the jobs to list. Filters are + // case-sensitive and have the following syntax: + // + // [field = value] AND [field [= value]] ... + // + // where **field** is `status.state` or `labels.[KEY]`, and `[KEY]` is a label + // key. **value** can be `*` to match all values. + // `status.state` can be either `ACTIVE` or `NON_ACTIVE`. + // Only the logical `AND` operator is supported; space-separated items are + // treated as having an implicit `AND` operator. + // + // Example filter: + // + // status.state = ACTIVE AND labels.env = staging AND labels.starred = * + string filter = 7; +} + +// A request to update a job. +message UpdateJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 2; + + // Required. The job ID. + string job_id = 3; + + // Required. The changes to the job. + Job job = 4; + + // Required. Specifies the path, relative to <code>Job</code>, of + // the field to update. For example, to update the labels of a Job the + // <code>update_mask</code> parameter would be specified as + // <code>labels</code>, and the `PATCH` request body would specify the new + // value. <strong>Note:</strong> Currently, <code>labels</code> is the only + // field that can be updated. + google.protobuf.FieldMask update_mask = 5; +} + +// A list of jobs in a project. +message ListJobsResponse { + // Output only. Jobs list. + repeated Job jobs = 1; + + // Optional. This token is included in the response if there are more results + // to fetch. To fetch additional results, provide this value as the + // `page_token` in a subsequent <code>ListJobsRequest</code>. + string next_page_token = 2; +} + +// A request to cancel a job. +message CancelJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job ID. + string job_id = 2; +} + +// A request to delete a job. +message DeleteJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job ID. + string job_id = 2; +} diff --git a/google/cloud/dataproc/v1/operations.proto b/google/cloud/dataproc/v1/operations.proto new file mode 100644 index 000000000..7c0587662 --- /dev/null +++ b/google/cloud/dataproc/v1/operations.proto @@ -0,0 +1,83 @@ +// Copyright 2018 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.dataproc.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "OperationsProto"; +option java_package = "com.google.cloud.dataproc.v1"; + +// The status of the operation. +message ClusterOperationStatus { + // The operation state. + enum State { + // Unused. + UNKNOWN = 0; + + // The operation has been created. + PENDING = 1; + + // The operation is running. + RUNNING = 2; + + // The operation is done; either cancelled or completed. + DONE = 3; + } + + // Output only. A message containing the operation state. + State state = 1; + + // Output only. A message containing the detailed operation state. + string inner_state = 2; + + // Output only. A message containing any operation metadata details. + string details = 3; + + // Output only. The time this state was entered. + google.protobuf.Timestamp state_start_time = 4; +} + +// Metadata describing the operation. +message ClusterOperationMetadata { + // Output only. Name of the cluster for the operation. + string cluster_name = 7; + + // Output only. Cluster UUID for the operation. + string cluster_uuid = 8; + + // Output only. Current operation status. + ClusterOperationStatus status = 9; + + // Output only. The previous operation status. + repeated ClusterOperationStatus status_history = 10; + + // Output only. The operation type. + string operation_type = 11; + + // Output only. Short description of operation. + string description = 12; + + // Output only. Labels associated with the operation + map<string, string> labels = 13; + + // Output only. Errors encountered during operation execution. + repeated string warnings = 14; +} diff --git a/google/cloud/dataproc/v1/workflow_templates.proto b/google/cloud/dataproc/v1/workflow_templates.proto new file mode 100644 index 000000000..a536698b7 --- /dev/null +++ b/google/cloud/dataproc/v1/workflow_templates.proto @@ -0,0 +1,670 @@ +// Copyright 2018 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.dataproc.v1; + +import "google/api/annotations.proto"; +import "google/cloud/dataproc/v1/clusters.proto"; +import "google/cloud/dataproc/v1/jobs.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "WorkflowTemplatesProto"; +option java_package = "com.google.cloud.dataproc.v1"; + +// The API interface for managing Workflow Templates in the +// Cloud Dataproc API. +service WorkflowTemplateService { + // Creates new workflow template. + rpc CreateWorkflowTemplate(CreateWorkflowTemplateRequest) + returns (WorkflowTemplate) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/workflowTemplates" + body: "template" + additional_bindings { + post: "/v1/{parent=projects/*/regions/*}/workflowTemplates" + body: "template" + } + }; + } + + // Retrieves the latest workflow template. + // + // Can retrieve previously instantiated template by specifying optional + // version parameter. + rpc GetWorkflowTemplate(GetWorkflowTemplateRequest) + returns (WorkflowTemplate) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/workflowTemplates/*}" + additional_bindings { + get: "/v1/{name=projects/*/regions/*/workflowTemplates/*}" + } + }; + } + + // Instantiates a template and begins execution. + // + // The returned Operation can be used to track execution of + // workflow by polling + // [operations.get][google.longrunning.Operations.GetOperation]. + // The Operation will complete when entire workflow is finished. + // + // The running workflow can be aborted via + // [operations.cancel][google.longrunning.Operations.CancelOperation]. + // This will cause any inflight jobs to be cancelled and workflow-owned + // clusters to be deleted. + // + // The [Operation.metadata][google.longrunning.Operation.metadata] will be + // [WorkflowMetadata][google.cloud.dataproc.v1.WorkflowMetadata]. + // + // On successful completion, + // [Operation.response][google.longrunning.Operation.response] will be + // [Empty][google.protobuf.Empty]. + rpc InstantiateWorkflowTemplate(InstantiateWorkflowTemplateRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/workflowTemplates/*}:instantiate" + body: "*" + additional_bindings { + post: "/v1/{name=projects/*/regions/*/workflowTemplates/*}:instantiate" + body: "*" + } + }; + } + + // Instantiates a template and begins execution. + // + // This method is equivalent to executing the sequence + // [CreateWorkflowTemplate][google.cloud.dataproc.v1.WorkflowTemplateService.CreateWorkflowTemplate], + // [InstantiateWorkflowTemplate][google.cloud.dataproc.v1.WorkflowTemplateService.InstantiateWorkflowTemplate], + // [DeleteWorkflowTemplate][google.cloud.dataproc.v1.WorkflowTemplateService.DeleteWorkflowTemplate]. + // + // The returned Operation can be used to track execution of + // workflow by polling + // [operations.get][google.longrunning.Operations.GetOperation]. + // The Operation will complete when entire workflow is finished. + // + // The running workflow can be aborted via + // [operations.cancel][google.longrunning.Operations.CancelOperation]. + // This will cause any inflight jobs to be cancelled and workflow-owned + // clusters to be deleted. + // + // The [Operation.metadata][google.longrunning.Operation.metadata] will be + // [WorkflowMetadata][google.cloud.dataproc.v1.WorkflowMetadata]. + // + // On successful completion, + // [Operation.response][google.longrunning.Operation.response] will be + // [Empty][google.protobuf.Empty]. + rpc InstantiateInlineWorkflowTemplate( + InstantiateInlineWorkflowTemplateRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/workflowTemplates:instantiateInline" + body: "template" + additional_bindings { + post: "/v1/{parent=projects/*/regions/*}/workflowTemplates:instantiateInline" + body: "template" + } + }; + } + + // Updates (replaces) workflow template. The updated template + // must contain version that matches the current server version. + rpc UpdateWorkflowTemplate(UpdateWorkflowTemplateRequest) + returns (WorkflowTemplate) { + option (google.api.http) = { + put: "/v1/{template.name=projects/*/locations/*/workflowTemplates/*}" + body: "template" + additional_bindings { + put: "/v1/{template.name=projects/*/regions/*/workflowTemplates/*}" + body: "template" + } + }; + } + + // Lists workflows that match the specified filter in the request. + rpc ListWorkflowTemplates(ListWorkflowTemplatesRequest) + returns (ListWorkflowTemplatesResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/workflowTemplates" + additional_bindings { + get: "/v1/{parent=projects/*/regions/*}/workflowTemplates" + } + }; + } + + // Deletes a workflow template. It does not cancel in-progress workflows. + rpc DeleteWorkflowTemplate(DeleteWorkflowTemplateRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/workflowTemplates/*}" + additional_bindings { + delete: "/v1/{name=projects/*/regions/*/workflowTemplates/*}" + } + }; + } +} + +// A Cloud Dataproc workflow template resource. +message WorkflowTemplate { + // Required. The template id. + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). Cannot begin or end with underscore + // or hyphen. Must consist of between 3 and 50 characters. + string id = 2; + + // Output only. The "resource name" of the template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. Used to perform a consistent read-modify-write. + // + // This field should be left blank for a `CreateWorkflowTemplate` request. It + // is required for an `UpdateWorkflowTemplate` request, and must match the + // current server version. A typical update template flow would fetch the + // current template with a `GetWorkflowTemplate` request, which will return + // the current template with the `version` field filled in with the + // current server version. The user updates other fields in the template, + // then returns it as part of the `UpdateWorkflowTemplate` request. + int32 version = 3; + + // Output only. The time template was created. + google.protobuf.Timestamp create_time = 4; + + // Output only. The time template was last updated. + google.protobuf.Timestamp update_time = 5; + + // Optional. The labels to associate with this template. These labels + // will be propagated to all jobs and clusters created by the workflow + // instance. + // + // Label **keys** must contain 1 to 63 characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // + // Label **values** may be empty, but, if present, must contain 1 to 63 + // characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // + // No more than 32 labels can be associated with a template. + map<string, string> labels = 6; + + // Required. WorkflowTemplate scheduling information. + WorkflowTemplatePlacement placement = 7; + + // Required. The Directed Acyclic Graph of Jobs to submit. + repeated OrderedJob jobs = 8; + + // Optional. Template parameters whose values are substituted into the + // template. Values for parameters must be provided when the template is + // instantiated. + repeated TemplateParameter parameters = 9; +} + +// Specifies workflow execution target. +// +// Either `managed_cluster` or `cluster_selector` is required. +message WorkflowTemplatePlacement { + // Required. Specifies where workflow executes; either on a managed + // cluster or an existing cluster chosen by labels. + oneof placement { + // Optional. A cluster that is managed by the workflow. + ManagedCluster managed_cluster = 1; + + // Optional. A selector that chooses target cluster for jobs based + // on metadata. + // + // The selector is evaluated at the time each job is submitted. + ClusterSelector cluster_selector = 2; + } +} + +// Cluster that is managed by the workflow. +message ManagedCluster { + // Required. The cluster name prefix. A unique cluster name will be formed by + // appending a random suffix. + // + // The name must contain only lower-case letters (a-z), numbers (0-9), + // and hyphens (-). Must begin with a letter. Cannot begin or end with + // hyphen. Must consist of between 2 and 35 characters. + string cluster_name = 2; + + // Required. The cluster configuration. + ClusterConfig config = 3; + + // Optional. The labels to associate with this cluster. + // + // Label keys must be between 1 and 63 characters long, and must conform to + // the following PCRE regular expression: + // [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62} + // + // Label values must be between 1 and 63 characters long, and must conform to + // the following PCRE regular expression: [\p{Ll}\p{Lo}\p{N}_-]{0,63} + // + // No more than 32 labels can be associated with a given cluster. + map<string, string> labels = 4; +} + +// A selector that chooses target cluster for jobs based on metadata. +message ClusterSelector { + // Optional. The zone where workflow process executes. This parameter does not + // affect the selection of the cluster. + // + // If unspecified, the zone of the first cluster matching the selector + // is used. + string zone = 1; + + // Required. The cluster labels. Cluster must have all labels + // to match. + map<string, string> cluster_labels = 2; +} + +// A job executed by the workflow. +message OrderedJob { + // Required. The step id. The id must be unique among all jobs + // within the template. + // + // The step id is used as prefix for job id, as job + // `goog-dataproc-workflow-step-id` label, and in + // [prerequisiteStepIds][google.cloud.dataproc.v1.OrderedJob.prerequisite_step_ids] + // field from other steps. + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). Cannot begin or end with underscore + // or hyphen. Must consist of between 3 and 50 characters. + string step_id = 1; + + // Required. The job definition. + oneof job_type { + // Job is a Hadoop job. + HadoopJob hadoop_job = 2; + + // Job is a Spark job. + SparkJob spark_job = 3; + + // Job is a Pyspark job. + PySparkJob pyspark_job = 4; + + // Job is a Hive job. + HiveJob hive_job = 5; + + // Job is a Pig job. + PigJob pig_job = 6; + + // Job is a SparkSql job. + SparkSqlJob spark_sql_job = 7; + } + + // Optional. The labels to associate with this job. + // + // Label keys must be between 1 and 63 characters long, and must conform to + // the following regular expression: + // [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62} + // + // Label values must be between 1 and 63 characters long, and must conform to + // the following regular expression: [\p{Ll}\p{Lo}\p{N}_-]{0,63} + // + // No more than 32 labels can be associated with a given job. + map<string, string> labels = 8; + + // Optional. Job scheduling configuration. + JobScheduling scheduling = 9; + + // Optional. The optional list of prerequisite job step_ids. + // If not specified, the job will start at the beginning of workflow. + repeated string prerequisite_step_ids = 10; +} + +// A configurable parameter that replaces one or more fields in the template. +// Parameterizable fields: +// - Labels +// - File uris +// - Job properties +// - Job arguments +// - Script variables +// - Main class (in HadoopJob and SparkJob) +// - Zone (in ClusterSelector) +message TemplateParameter { + // Required. Parameter name. + // The parameter name is used as the key, and paired with the + // parameter value, which are passed to the template when the template + // is instantiated. + // The name must contain only capital letters (A-Z), numbers (0-9), and + // underscores (_), and must not start with a number. The maximum length is + // 40 characters. + string name = 1; + + // Required. Paths to all fields that the parameter replaces. + // A field is allowed to appear in at most one parameter's list of field + // paths. + // + // A field path is similar in syntax to a + // [google.protobuf.FieldMask][google.protobuf.FieldMask]. For example, a + // field path that references the zone field of a workflow template's cluster + // selector would be specified as `placement.clusterSelector.zone`. + // + // Also, field paths can reference fields using the following syntax: + // + // * Values in maps can be referenced by key: + // * labels['key'] + // * placement.clusterSelector.clusterLabels['key'] + // * placement.managedCluster.labels['key'] + // * placement.clusterSelector.clusterLabels['key'] + // * jobs['step-id'].labels['key'] + // + // * Jobs in the jobs list can be referenced by step-id: + // * jobs['step-id'].hadoopJob.mainJarFileUri + // * jobs['step-id'].hiveJob.queryFileUri + // * jobs['step-id'].pySparkJob.mainPythonFileUri + // * jobs['step-id'].hadoopJob.jarFileUris[0] + // * jobs['step-id'].hadoopJob.archiveUris[0] + // * jobs['step-id'].hadoopJob.fileUris[0] + // * jobs['step-id'].pySparkJob.pythonFileUris[0] + // + // * Items in repeated fields can be referenced by a zero-based index: + // * jobs['step-id'].sparkJob.args[0] + // + // * Other examples: + // * jobs['step-id'].hadoopJob.properties['key'] + // * jobs['step-id'].hadoopJob.args[0] + // * jobs['step-id'].hiveJob.scriptVariables['key'] + // * jobs['step-id'].hadoopJob.mainJarFileUri + // * placement.clusterSelector.zone + // + // It may not be possible to parameterize maps and repeated fields in their + // entirety since only individual map values and individual items in repeated + // fields can be referenced. For example, the following field paths are + // invalid: + // + // - placement.clusterSelector.clusterLabels + // - jobs['step-id'].sparkJob.args + repeated string fields = 2; + + // Optional. Brief description of the parameter. + // Must not exceed 1024 characters. + string description = 3; + + // Optional. Validation rules to be applied to this parameter's value. + ParameterValidation validation = 4; +} + +// Configuration for parameter validation. +message ParameterValidation { + // Required. The type of validation to be performed. + oneof validation_type { + // Validation based on regular expressions. + RegexValidation regex = 1; + + // Validation based on a list of allowed values. + ValueValidation values = 2; + } +} + +// Validation based on regular expressions. +message RegexValidation { + // Required. RE2 regular expressions used to validate the parameter's value. + // The value must match the regex in its entirety (substring + // matches are not sufficient). + repeated string regexes = 1; +} + +// Validation based on a list of allowed values. +message ValueValidation { + // Required. List of allowed values for the parameter. + repeated string values = 1; +} + +// A Cloud Dataproc workflow template resource. +message WorkflowMetadata { + // The operation state. + enum State { + // Unused. + UNKNOWN = 0; + + // The operation has been created. + PENDING = 1; + + // The operation is running. + RUNNING = 2; + + // The operation is done; either cancelled or completed. + DONE = 3; + } + + // Output only. The "resource name" of the template. + string template = 1; + + // Output only. The version of template at the time of + // workflow instantiation. + int32 version = 2; + + // Output only. The create cluster operation metadata. + ClusterOperation create_cluster = 3; + + // Output only. The workflow graph. + WorkflowGraph graph = 4; + + // Output only. The delete cluster operation metadata. + ClusterOperation delete_cluster = 5; + + // Output only. The workflow state. + State state = 6; + + // Output only. The name of the target cluster. + string cluster_name = 7; + + // Map from parameter names to values that were used for those parameters. + map<string, string> parameters = 8; + + // Output only. Workflow start time. + google.protobuf.Timestamp start_time = 9; + + // Output only. Workflow end time. + google.protobuf.Timestamp end_time = 10; + + // Output only. The UUID of target cluster. + string cluster_uuid = 11; +} + +// The cluster operation triggered by a workflow. +message ClusterOperation { + // Output only. The id of the cluster operation. + string operation_id = 1; + + // Output only. Error, if operation failed. + string error = 2; + + // Output only. Indicates the operation is done. + bool done = 3; +} + +// The workflow graph. +message WorkflowGraph { + // Output only. The workflow nodes. + repeated WorkflowNode nodes = 1; +} + +// The workflow node. +message WorkflowNode { + // The workflow node state. + enum NodeState { + // State is unspecified. + NODE_STATE_UNSPECIFIED = 0; + + // The node is awaiting prerequisite node to finish. + BLOCKED = 1; + + // The node is runnable but not running. + RUNNABLE = 2; + + // The node is running. + RUNNING = 3; + + // The node completed successfully. + COMPLETED = 4; + + // The node failed. A node can be marked FAILED because + // its ancestor or peer failed. + FAILED = 5; + } + + // Output only. The name of the node. + string step_id = 1; + + // Output only. Node's prerequisite nodes. + repeated string prerequisite_step_ids = 2; + + // Output only. The job id; populated after the node enters RUNNING state. + string job_id = 3; + + // Output only. The node state. + NodeState state = 5; + + // Output only. The error detail. + string error = 6; +} + +// A request to create a workflow template. +message CreateWorkflowTemplateRequest { + // Required. The "resource name" of the region, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}` + string parent = 1; + + // Required. The Dataproc workflow template to create. + WorkflowTemplate template = 2; +} + +// A request to fetch a workflow template. +message GetWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. The version of workflow template to retrieve. Only previously + // instatiated versions can be retrieved. + // + // If unspecified, retrieves the current version. + int32 version = 2; +} + +// A request to instantiate a workflow template. +message InstantiateWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. The version of workflow template to instantiate. If specified, + // the workflow will be instantiated only if the current version of + // the workflow template has the supplied version. + // + // This option cannot be used to instantiate a previous version of + // workflow template. + int32 version = 2; + + // Optional. A tag that prevents multiple concurrent workflow + // instances with the same tag from running. This mitigates risk of + // concurrent instances started due to retries. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The tag must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 5; + + // Optional. Map from parameter names to values that should be used for those + // parameters. Values may not exceed 100 characters. + map<string, string> parameters = 6; +} + +// A request to instantiate an inline workflow template. +message InstantiateInlineWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template region, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}` + string parent = 1; + + // Required. The workflow template to instantiate. + WorkflowTemplate template = 2; + + // Optional. A tag that prevents multiple concurrent workflow + // instances with the same tag from running. This mitigates risk of + // concurrent instances started due to retries. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The tag must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 3; +} + +// A request to update a workflow template. +message UpdateWorkflowTemplateRequest { + // Required. The updated workflow template. + // + // The `template.version` field must match the current version. + WorkflowTemplate template = 1; +} + +// A request to list workflow templates in a project. +message ListWorkflowTemplatesRequest { + // Required. The "resource name" of the region, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}` + string parent = 1; + + // Optional. The maximum number of results to return in each response. + int32 page_size = 2; + + // Optional. The page token, returned by a previous call, to request the + // next page of results. + string page_token = 3; +} + +// A response to a request to list workflow templates in a project. +message ListWorkflowTemplatesResponse { + // Output only. WorkflowTemplates list. + repeated WorkflowTemplate templates = 1; + + // Output only. This token is included in the response if there are more + // results to fetch. To fetch additional results, provide this value as the + // page_token in a subsequent <code>ListWorkflowTemplatesRequest</code>. + string next_page_token = 2; +} + +// A request to delete a workflow template. +// +// Currently started workflows will remain running. +message DeleteWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. The version of workflow template to delete. If specified, + // will only delete the template if the current server version matches + // specified version. + int32 version = 2; +} diff --git a/google/cloud/dataproc/v1beta2/BUILD.bazel b/google/cloud/dataproc/v1beta2/BUILD.bazel new file mode 100644 index 000000000..6d96f674d --- /dev/null +++ b/google/cloud/dataproc/v1beta2/BUILD.bazel @@ -0,0 +1,154 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "dataproc_proto", + srcs = [ + "clusters.proto", + "jobs.proto", + "operations.proto", + "shared.proto", + "workflow_templates.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "dataproc_proto_with_info", + deps = [":dataproc_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "dataproc_java_proto", + deps = [":dataproc_proto"], +) + +java_grpc_library( + name = "dataproc_java_grpc", + srcs = [":dataproc_proto"], + deps = [":dataproc_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "dataproc_resource_name_java_proto", + gapic_yaml = "dataproc_gapic.yaml", + deps = [":dataproc_proto"], +) + +java_gapic_library( + name = "dataproc_java_gapic", + src = ":dataproc_proto_with_info", + gapic_yaml = "dataproc_gapic.yaml", + service_yaml = "dataproc.yaml", + test_deps = [":dataproc_java_grpc"], + deps = [ + ":dataproc_java_proto", + ":dataproc_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":dataproc_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.dataproc.v1beta2.ClusterControllerClientTest", + "com.google.cloud.dataproc.v1beta2.JobControllerClientTest", + "com.google.cloud.dataproc.v1beta2.WorkflowTemplateServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-dataproc-v1beta2-java", + client_deps = [":dataproc_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":dataproc_java_gapic_test"], + grpc_deps = [":dataproc_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":dataproc_java_proto", + ":dataproc_proto", + ":dataproc_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "dataproc_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/dataproc/v1beta2", + protos = [":dataproc_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + ], +) + +go_gapic_library( + name = "dataproc_go_gapic", + src = ":dataproc_proto_with_info", + gapic_yaml = "dataproc_gapic.yaml", + importpath = "cloud.google.com/go/dataproc/apiv1beta2", + service_yaml = "dataproc.yaml", + deps = [ + ":dataproc_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "dataproc_go_gapic_test", + srcs = [":dataproc_go_gapic_srcjar_test"], + embed = [":dataproc_go_gapic"], + importpath = "cloud.google.com/go/dataproc/apiv1beta2", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-dataproc-v1beta2-go", + deps = [ + ":dataproc_go_gapic", + ":dataproc_go_gapic_srcjar-smoke-test.srcjar", + ":dataproc_go_gapic_srcjar-test.srcjar", + ":dataproc_go_proto", + ], +) diff --git a/google/cloud/dataproc/v1beta2/clusters.proto b/google/cloud/dataproc/v1beta2/clusters.proto new file mode 100644 index 000000000..fd89fbffe --- /dev/null +++ b/google/cloud/dataproc/v1beta2/clusters.proto @@ -0,0 +1,753 @@ +// Copyright 2018 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.dataproc.v1beta2; + +import "google/api/annotations.proto"; +import "google/cloud/dataproc/v1beta2/operations.proto"; +import "google/cloud/dataproc/v1beta2/shared.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1beta2;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "ClustersProto"; +option java_package = "com.google.cloud.dataproc.v1beta2"; + +// The ClusterControllerService provides methods to manage clusters +// of Compute Engine instances. +service ClusterController { + // Creates a cluster in a project. + rpc CreateCluster(CreateClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta2/projects/{project_id}/regions/{region}/clusters" + body: "cluster" + }; + } + + // Updates a cluster in a project. + rpc UpdateCluster(UpdateClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v1beta2/projects/{project_id}/regions/{region}/clusters/{cluster_name}" + body: "cluster" + }; + } + + // Deletes a cluster in a project. + rpc DeleteCluster(DeleteClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1beta2/projects/{project_id}/regions/{region}/clusters/{cluster_name}" + }; + } + + // Gets the resource representation for a cluster in a project. + rpc GetCluster(GetClusterRequest) returns (Cluster) { + option (google.api.http) = { + get: "/v1beta2/projects/{project_id}/regions/{region}/clusters/{cluster_name}" + }; + } + + // Lists all regions/{region}/clusters in a project. + rpc ListClusters(ListClustersRequest) returns (ListClustersResponse) { + option (google.api.http) = { + get: "/v1beta2/projects/{project_id}/regions/{region}/clusters" + }; + } + + // Gets cluster diagnostic information. + // After the operation completes, the Operation.response field + // contains `DiagnoseClusterOutputLocation`. + rpc DiagnoseCluster(DiagnoseClusterRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta2/projects/{project_id}/regions/{region}/clusters/{cluster_name}:diagnose" + body: "*" + }; + } +} + +// Describes the identifying information, config, and status of +// a cluster of Compute Engine instances. +message Cluster { + // Required. The Google Cloud Platform project ID that the cluster belongs to. + string project_id = 1; + + // Required. The cluster name. Cluster names within a project must be + // unique. Names of deleted clusters can be reused. + string cluster_name = 2; + + // Required. The cluster config. Note that Cloud Dataproc may set + // default values, and values may change when clusters are updated. + ClusterConfig config = 3; + + // Optional. The labels to associate with this cluster. + // Label **keys** must contain 1 to 63 characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // Label **values** may be empty, but, if present, must contain 1 to 63 + // characters, and must conform to [RFC + // 1035](https://www.ietf.org/rfc/rfc1035.txt). No more than 32 labels can be + // associated with a cluster. + map<string, string> labels = 8; + + // Output only. Cluster status. + ClusterStatus status = 4; + + // Output only. The previous cluster status. + repeated ClusterStatus status_history = 7; + + // Output only. A cluster UUID (Unique Universal Identifier). Cloud Dataproc + // generates this value when it creates the cluster. + string cluster_uuid = 6; + + // Output only. Contains cluster daemon metrics such as HDFS and YARN stats. + // + // **Beta Feature**: This report is available for testing purposes only. It + // may be changed before final release. + ClusterMetrics metrics = 9; +} + +// The cluster config. +message ClusterConfig { + // Optional. A Cloud Storage staging bucket used for sharing generated + // SSH keys and config. If you do not specify a staging bucket, Cloud + // Dataproc will determine an appropriate Cloud Storage location (US, + // ASIA, or EU) for your cluster's staging bucket according to the Google + // Compute Engine zone where your cluster is deployed, and then it will create + // and manage this project-level, per-location bucket for you. + string config_bucket = 1; + + // Required. The shared Compute Engine config settings for + // all instances in a cluster. + GceClusterConfig gce_cluster_config = 8; + + // Optional. The Compute Engine config settings for + // the master instance in a cluster. + InstanceGroupConfig master_config = 9; + + // Optional. The Compute Engine config settings for + // worker instances in a cluster. + InstanceGroupConfig worker_config = 10; + + // Optional. The Compute Engine config settings for + // additional worker instances in a cluster. + InstanceGroupConfig secondary_worker_config = 12; + + // Optional. The config settings for software inside the cluster. + SoftwareConfig software_config = 13; + + // Optional. The config setting for auto delete cluster schedule. + LifecycleConfig lifecycle_config = 14; + + // Optional. Commands to execute on each node after config is + // completed. By default, executables are run on master and all worker nodes. + // You can test a node's <code>role</code> metadata to run an executable on + // a master or worker node, as shown below using `curl` (you can also use + // `wget`): + // + // ROLE=$(curl -H Metadata-Flavor:Google + // http://metadata/computeMetadata/v1beta2/instance/attributes/dataproc-role) + // if [[ "${ROLE}" == 'Master' ]]; then + // ... master specific actions ... + // else + // ... worker specific actions ... + // fi + repeated NodeInitializationAction initialization_actions = 11; + + // Optional. Encryption settings for the cluster. + EncryptionConfig encryption_config = 15; +} + +// Encryption settings for the cluster. +message EncryptionConfig { + // Optional. The Cloud KMS key name to use for PD disk encryption for all + // instances in the cluster. + string gce_pd_kms_key_name = 1; +} + +// Common config settings for resources of Compute Engine cluster +// instances, applicable to all instances in the cluster. +message GceClusterConfig { + // Optional. The zone where the Compute Engine cluster will be located. + // On a create request, it is required in the "global" region. If omitted + // in a non-global Cloud Dataproc region, the service will pick a zone in the + // corresponding Compute Engine region. On a get request, zone will always be + // present. + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/zones/[zone]` + // * `projects/[project_id]/zones/[zone]` + // * `us-central1-f` + string zone_uri = 1; + + // Optional. The Compute Engine network to be used for machine + // communications. Cannot be specified with subnetwork_uri. If neither + // `network_uri` nor `subnetwork_uri` is specified, the "default" network of + // the project is used, if it exists. Cannot be a "Custom Subnet Network" (see + // [Using Subnetworks](/compute/docs/subnetworks) for more information). + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/regions/global/default` + // * `projects/[project_id]/regions/global/default` + // * `default` + string network_uri = 2; + + // Optional. The Compute Engine subnetwork to be used for machine + // communications. Cannot be specified with network_uri. + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/regions/us-east1/sub0` + // * `projects/[project_id]/regions/us-east1/sub0` + // * `sub0` + string subnetwork_uri = 6; + + // Optional. If true, all instances in the cluster will only have internal IP + // addresses. By default, clusters are not restricted to internal IP + // addresses, and will have ephemeral external IP addresses assigned to each + // instance. This `internal_ip_only` restriction can only be enabled for + // subnetwork enabled networks, and all off-cluster dependencies must be + // configured to be accessible without external IP addresses. + bool internal_ip_only = 7; + + // Optional. The service account of the instances. Defaults to the default + // Compute Engine service account. Custom service accounts need + // permissions equivalent to the following IAM roles: + // + // * roles/logging.logWriter + // * roles/storage.objectAdmin + // + // (see + // https://cloud.google.com/compute/docs/access/service-accounts#custom_service_accounts + // for more information). + // Example: `[account_id]@[project_id].iam.gserviceaccount.com` + string service_account = 8; + + // Optional. The URIs of service account scopes to be included in + // Compute Engine instances. The following base set of scopes is always + // included: + // + // * https://www.googleapis.com/auth/cloud.useraccounts.readonly + // * https://www.googleapis.com/auth/devstorage.read_write + // * https://www.googleapis.com/auth/logging.write + // + // If no scopes are specified, the following defaults are also provided: + // + // * https://www.googleapis.com/auth/bigquery + // * https://www.googleapis.com/auth/bigtable.admin.table + // * https://www.googleapis.com/auth/bigtable.data + // * https://www.googleapis.com/auth/devstorage.full_control + repeated string service_account_scopes = 3; + + // The Compute Engine tags to add to all instances (see + // [Tagging instances](/compute/docs/label-or-tag-resources#tags)). + repeated string tags = 4; + + // The Compute Engine metadata entries to add to all instances (see + // [Project and instance + // metadata](https://cloud.google.com/compute/docs/storing-retrieving-metadata#project_and_instance_metadata)). + map<string, string> metadata = 5; +} + +// Optional. The config settings for Compute Engine resources in +// an instance group, such as a master or worker group. +message InstanceGroupConfig { + // Optional. The number of VM instances in the instance group. + // For master instance groups, must be set to 1. + int32 num_instances = 1; + + // Output only. The list of instance names. Cloud Dataproc derives the names + // from `cluster_name`, `num_instances`, and the instance group. + repeated string instance_names = 2; + + // Optional. The Compute Engine image resource used for cluster + // instances. It can be specified or may be inferred from + // `SoftwareConfig.image_version`. + string image_uri = 3; + + // Optional. The Compute Engine machine type used for cluster instances. + // + // A full URL, partial URI, or short name are valid. Examples: + // + // * `https://www.googleapis.com/compute/v1/projects/[project_id]/zones/us-east1-a/machineTypes/n1-standard-2` + // * `projects/[project_id]/zones/us-east1-a/machineTypes/n1-standard-2` + // * `n1-standard-2` + // + // **Auto Zone Exception**: If you are using the Cloud Dataproc + // [Auto Zone + // Placement](/dataproc/docs/concepts/configuring-clusters/auto-zone#using_auto_zone_placement) + // feature, you must use the short name of the machine type + // resource, for example, `n1-standard-2`. + string machine_type_uri = 4; + + // Optional. Disk option config settings. + DiskConfig disk_config = 5; + + // Optional. Specifies that this instance group contains preemptible + // instances. + bool is_preemptible = 6; + + // Output only. The config for Compute Engine Instance Group + // Manager that manages this group. + // This is only used for preemptible instance groups. + ManagedGroupConfig managed_group_config = 7; + + // Optional. The Compute Engine accelerator configuration for these + // instances. + // + // **Beta Feature**: This feature is still under development. It may be + // changed before final release. + repeated AcceleratorConfig accelerators = 8; + + // Optional. Specifies the minimum cpu platform for the Instance Group. + // See [Cloud Dataproc→Minimum CPU Platform] + // (/dataproc/docs/concepts/compute/dataproc-min-cpu). + string min_cpu_platform = 9; +} + +// Specifies the resources used to actively manage an instance group. +message ManagedGroupConfig { + // Output only. The name of the Instance Template used for the Managed + // Instance Group. + string instance_template_name = 1; + + // Output only. The name of the Instance Group Manager for this group. + string instance_group_manager_name = 2; +} + +// Specifies the type and number of accelerator cards attached to the instances +// of an instance group (see [GPUs on Compute Engine](/compute/docs/gpus/)). +message AcceleratorConfig { + // Full URL, partial URI, or short name of the accelerator type resource to + // expose to this instance. See [Compute Engine AcceleratorTypes]( + // /compute/docs/reference/beta/acceleratorTypes) + // + // Examples + // * `https://www.googleapis.com/compute/beta/projects/[project_id]/zones/us-east1-a/acceleratorTypes/nvidia-tesla-k80` + // * `projects/[project_id]/zones/us-east1-a/acceleratorTypes/nvidia-tesla-k80` + // * `nvidia-tesla-k80` + // + // **Auto Zone Exception**: If you are using the Cloud Dataproc + // [Auto Zone + // Placement](/dataproc/docs/concepts/configuring-clusters/auto-zone#using_auto_zone_placement) + // feature, you must use the short name of the accelerator type + // resource, for example, `nvidia-tesla-k80`. + string accelerator_type_uri = 1; + + // The number of the accelerator cards of this type exposed to this instance. + int32 accelerator_count = 2; +} + +// Specifies the config of disk options for a group of VM instances. +message DiskConfig { + // Optional. Type of the boot disk (default is "pd-standard"). + // Valid values: "pd-ssd" (Persistent Disk Solid State Drive) or + // "pd-standard" (Persistent Disk Hard Disk Drive). + string boot_disk_type = 3; + + // Optional. Size in GB of the boot disk (default is 500GB). + int32 boot_disk_size_gb = 1; + + // Optional. Number of attached SSDs, from 0 to 4 (default is 0). + // If SSDs are not attached, the boot disk is used to store runtime logs and + // [HDFS](https://hadoop.apache.org/docs/r1.2.1/hdfs_user_guide.html) data. + // If one or more SSDs are attached, this runtime bulk + // data is spread across them, and the boot disk contains only basic + // config and installed binaries. + int32 num_local_ssds = 2; +} + +// Specifies the cluster auto-delete schedule configuration. +message LifecycleConfig { + // Optional. The duration to keep the cluster alive while idling. + // Passing this threshold will cause the cluster to be + // deleted. Valid range: **[10m, 14d]**. + // + // Example: **"10m"**, the minimum value, to delete the + // cluster when it has had no jobs running for 10 minutes. + google.protobuf.Duration idle_delete_ttl = 1; + + // Optional. Either the exact time the cluster should be deleted at or + // the cluster maximum age. + oneof ttl { + // Optional. The time when cluster will be auto-deleted. + google.protobuf.Timestamp auto_delete_time = 2; + + // Optional. The lifetime duration of cluster. The cluster will be + // auto-deleted at the end of this period. Valid range: **[10m, 14d]**. + // + // Example: **"1d"**, to delete the cluster 1 day after its creation.. + google.protobuf.Duration auto_delete_ttl = 3; + } +} + +// Specifies an executable to run on a fully configured node and a +// timeout period for executable completion. +message NodeInitializationAction { + // Required. Cloud Storage URI of executable file. + string executable_file = 1; + + // Optional. Amount of time executable has to complete. Default is + // 10 minutes. Cluster creation fails with an explanatory error message (the + // name of the executable that caused the error and the exceeded timeout + // period) if the executable is not completed at end of the timeout period. + google.protobuf.Duration execution_timeout = 2; +} + +// The status of a cluster and its instances. +message ClusterStatus { + // The cluster state. + enum State { + // The cluster state is unknown. + UNKNOWN = 0; + + // The cluster is being created and set up. It is not ready for use. + CREATING = 1; + + // The cluster is currently running and healthy. It is ready for use. + RUNNING = 2; + + // The cluster encountered an error. It is not ready for use. + ERROR = 3; + + // The cluster is being deleted. It cannot be used. + DELETING = 4; + + // The cluster is being updated. It continues to accept and process jobs. + UPDATING = 5; + } + + // The cluster substate. + enum Substate { + // The cluster substate is unknown. + UNSPECIFIED = 0; + + // The cluster is known to be in an unhealthy state + // (for example, critical daemons are not running or HDFS capacity is + // exhausted). + // + // Applies to RUNNING state. + UNHEALTHY = 1; + + // The agent-reported status is out of date (may occur if + // Cloud Dataproc loses communication with Agent). + // + // Applies to RUNNING state. + STALE_STATUS = 2; + } + + // Output only. The cluster's state. + State state = 1; + + // Output only. Optional details of cluster's state. + string detail = 2; + + // Output only. Time when this state was entered. + google.protobuf.Timestamp state_start_time = 3; + + // Output only. Additional state information that includes + // status reported by the agent. + Substate substate = 4; +} + +// Specifies the selection and config of software inside the cluster. +message SoftwareConfig { + // Optional. The version of software inside the cluster. It must be one of the + // supported [Cloud Dataproc + // Versions](/dataproc/docs/concepts/versioning/dataproc-versions#supported_cloud_dataproc_versions), + // such as "1.2" (including a subminor version, such as "1.2.29"), or the + // ["preview" + // version](/dataproc/docs/concepts/versioning/dataproc-versions#other_versions). + // If unspecified, it defaults to the latest version. + string image_version = 1; + + // Optional. The properties to set on daemon config files. + // + // Property keys are specified in `prefix:property` format, such as + // `core:fs.defaultFS`. The following are supported prefixes + // and their mappings: + // + // * capacity-scheduler: `capacity-scheduler.xml` + // * core: `core-site.xml` + // * distcp: `distcp-default.xml` + // * hdfs: `hdfs-site.xml` + // * hive: `hive-site.xml` + // * mapred: `mapred-site.xml` + // * pig: `pig.properties` + // * spark: `spark-defaults.conf` + // * yarn: `yarn-site.xml` + // + // For more information, see + // [Cluster properties](/dataproc/docs/concepts/cluster-properties). + map<string, string> properties = 2; +} + +// Contains cluster daemon metrics, such as HDFS and YARN stats. +// +// **Beta Feature**: This report is available for testing purposes only. It may +// be changed before final release. +message ClusterMetrics { + // The HDFS metrics. + map<string, int64> hdfs_metrics = 1; + + // The YARN metrics. + map<string, int64> yarn_metrics = 2; +} + +// A request to create a cluster. +message CreateClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster to create. + Cluster cluster = 2; + + // Optional. A unique id used to identify the request. If the server + // receives two + // [CreateClusterRequest][google.cloud.dataproc.v1beta2.CreateClusterRequest] + // requests with the same id, then the second request will be ignored and the + // first [google.longrunning.Operation][google.longrunning.Operation] created + // and stored in the backend is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 4; +} + +// A request to update a cluster. +message UpdateClusterRequest { + // Required. The ID of the Google Cloud Platform project the + // cluster belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 5; + + // Required. The cluster name. + string cluster_name = 2; + + // Required. The changes to the cluster. + Cluster cluster = 3; + + // Optional. Timeout for graceful YARN decomissioning. Graceful + // decommissioning allows removing nodes from the cluster without + // interrupting jobs in progress. Timeout specifies how long to wait for jobs + // in progress to finish before forcefully removing nodes (and potentially + // interrupting jobs). Default timeout is 0 (for forceful decommission), and + // the maximum allowed timeout is 1 day. + // + // Only supported on Dataproc image versions 1.2 and higher. + google.protobuf.Duration graceful_decommission_timeout = 6; + + // Required. Specifies the path, relative to `Cluster`, of + // the field to update. For example, to change the number of workers + // in a cluster to 5, the `update_mask` parameter would be + // specified as `config.worker_config.num_instances`, + // and the `PATCH` request body would specify the new value, as follows: + // + // { + // "config":{ + // "workerConfig":{ + // "numInstances":"5" + // } + // } + // } + // + // Similarly, to change the number of preemptible workers in a cluster to 5, + // the `update_mask` parameter would be + // `config.secondary_worker_config.num_instances`, and the `PATCH` request + // body would be set as follows: + // + // { + // "config":{ + // "secondaryWorkerConfig":{ + // "numInstances":"5" + // } + // } + // } + // <strong>Note:</strong> currently only the following fields can be updated: + // + // <table> + // <tr> + // <td><strong>Mask</strong></td><td><strong>Purpose</strong></td> + // </tr> + // <tr> + // <td>labels</td><td>Updates labels</td> + // </tr> + // <tr> + // <td>config.worker_config.num_instances</td><td>Resize primary worker + // group</td> + // </tr> + // <tr> + // <td>config.secondary_worker_config.num_instances</td><td>Resize secondary + // worker group</td> + // </tr> + // <tr> + // <td>config.lifecycle_config.auto_delete_ttl</td><td>Reset MAX TTL + // duration</td> + // </tr> + // <tr> + // <td>config.lifecycle_config.auto_delete_time</td><td>Update MAX TTL + // deletion timestamp</td> + // </tr> + // <tr> + // <td>config.lifecycle_config.idle_delete_ttl</td><td>Update Idle TTL + // duration</td> + // </tr> + // </table> + google.protobuf.FieldMask update_mask = 4; + + // Optional. A unique id used to identify the request. If the server + // receives two + // [UpdateClusterRequest][google.cloud.dataproc.v1beta2.UpdateClusterRequest] + // requests with the same id, then the second request will be ignored and the + // first [google.longrunning.Operation][google.longrunning.Operation] created + // and stored in the backend is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 7; +} + +// A request to delete a cluster. +message DeleteClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster name. + string cluster_name = 2; + + // Optional. Specifying the `cluster_uuid` means the RPC should fail + // (with error NOT_FOUND) if cluster with specified UUID does not exist. + string cluster_uuid = 4; + + // Optional. A unique id used to identify the request. If the server + // receives two + // [DeleteClusterRequest][google.cloud.dataproc.v1beta2.DeleteClusterRequest] + // requests with the same id, then the second request will be ignored and the + // first [google.longrunning.Operation][google.longrunning.Operation] created + // and stored in the backend is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 5; +} + +// Request to get the resource representation for a cluster in a project. +message GetClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster name. + string cluster_name = 2; +} + +// A request to list the clusters in a project. +message ListClustersRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 4; + + // Optional. A filter constraining the clusters to list. Filters are + // case-sensitive and have the following syntax: + // + // field = value [AND [field = value]] ... + // + // where **field** is one of `status.state`, `clusterName`, or `labels.[KEY]`, + // and `[KEY]` is a label key. **value** can be `*` to match all values. + // `status.state` can be one of the following: `ACTIVE`, `INACTIVE`, + // `CREATING`, `RUNNING`, `ERROR`, `DELETING`, or `UPDATING`. `ACTIVE` + // contains the `CREATING`, `UPDATING`, and `RUNNING` states. `INACTIVE` + // contains the `DELETING` and `ERROR` states. + // `clusterName` is the name of the cluster provided at creation time. + // Only the logical `AND` operator is supported; space-separated items are + // treated as having an implicit `AND` operator. + // + // Example filter: + // + // status.state = ACTIVE AND clusterName = mycluster + // AND labels.env = staging AND labels.starred = * + string filter = 5; + + // Optional. The standard List page size. + int32 page_size = 2; + + // Optional. The standard List page token. + string page_token = 3; +} + +// The list of all clusters in a project. +message ListClustersResponse { + // Output only. The clusters in the project. + repeated Cluster clusters = 1; + + // Output only. This token is included in the response if there are more + // results to fetch. To fetch additional results, provide this value as the + // `page_token` in a subsequent <code>ListClustersRequest</code>. + string next_page_token = 2; +} + +// A request to collect cluster diagnostic information. +message DiagnoseClusterRequest { + // Required. The ID of the Google Cloud Platform project that the cluster + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The cluster name. + string cluster_name = 2; +} + +// The location of diagnostic output. +message DiagnoseClusterResults { + // Output only. The Cloud Storage URI of the diagnostic output. + // The output report is a plain text file with a summary of collected + // diagnostics. + string output_uri = 1; +} diff --git a/google/cloud/dataproc/v1beta2/dataproc.yaml b/google/cloud/dataproc/v1beta2/dataproc.yaml new file mode 100644 index 000000000..67a40809a --- /dev/null +++ b/google/cloud/dataproc/v1beta2/dataproc.yaml @@ -0,0 +1,51 @@ +type: google.api.Service +config_version: 2 +name: dataproc.googleapis.com +title: Google Cloud Dataproc API + +apis: +- name: google.cloud.dataproc.v1beta2.ClusterController +- name: google.cloud.dataproc.v1beta2.JobController +- name: google.cloud.dataproc.v1beta2.WorkflowTemplateService + +types: +- name: google.cloud.dataproc.v1beta2.DiagnoseClusterResults +- name: google.cloud.dataproc.v1beta2.ClusterOperationMetadata +- name: google.cloud.dataproc.v1beta2.WorkflowMetadata + +documentation: + summary: 'Manages Hadoop-based clusters and jobs on Google Cloud Platform.' + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1beta2/{name=projects/*/regions/*/operations}' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1beta2/{name=projects/*/regions/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1beta2/{name=projects/*/regions/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1beta2/{name=projects/*/regions/*/operations/*}:cancel' + + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + post: '/v1beta2/{resource=projects/*/regions/*/clusters/*}:setIamPolicy' + body: '*' + + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + get: '/v1beta2/{resource=projects/*/regions/*/clusters/*}:getIamPolicy' + + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + post: '/v1beta2/{resource=projects/*/regions/*/clusters/*}:testIamPermissions' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + diff --git a/google/cloud/dataproc/v1beta2/dataproc_gapic.yaml b/google/cloud/dataproc/v1beta2/dataproc_gapic.yaml new file mode 100644 index 000000000..f9aa4028f --- /dev/null +++ b/google/cloud/dataproc/v1beta2/dataproc_gapic.yaml @@ -0,0 +1,657 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.dataproc.v1beta2 + python: + package_name: google.cloud.dataproc_v1beta2.gapic + go: + package_name: cloud.google.com/go/dataproc/apiv1beta2 + csharp: + package_name: Google.Cloud.Dataproc.V1Beta2 + ruby: + package_name: Google::Cloud::Dataproc::V1beta2 + php: + package_name: Google\Cloud\Dataproc\V1beta2 + nodejs: + package_name: dataproc.v1beta2 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.dataproc.v1beta2.ClusterController + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for smoke test. + smoke_test: + method: ListClusters + init_fields: + - project_id=$PROJECT_ID + - region="global" + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - INTERNAL + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: + - UNAVAILABLE + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 10000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 10000 + total_timeout_millis: 300000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster + required_fields: + - project_id + - region + - cluster + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + long_running: + return_type: google.cloud.dataproc.v1beta2.Cluster + metadata_type: google.cloud.dataproc.v1beta2.ClusterOperationMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 900000 + - name: UpdateCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + - cluster + - update_mask + required_fields: + - project_id + - region + - cluster_name + - cluster + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + long_running: + return_type: google.cloud.dataproc.v1beta2.Cluster + metadata_type: google.cloud.dataproc.v1beta2.ClusterOperationMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 900000 + - name: DeleteCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + required_fields: + - project_id + - region + - cluster_name + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1beta2.ClusterOperationMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 900000 + - name: GetCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + required_fields: + - project_id + - region + - cluster_name + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: ListClusters + flattening: + groups: + - parameters: + - project_id + - region + - parameters: + - project_id + - region + - filter + required_fields: + - project_id + - region + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: clusters + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: DiagnoseCluster + flattening: + groups: + - parameters: + - project_id + - region + - cluster_name + required_fields: + - project_id + - region + - cluster_name + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1beta2.DiagnoseClusterResults + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.dataproc.v1beta2.JobController + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - INTERNAL + - UNAVAILABLE + - name: non_idempotent + retry_codes: + - UNAVAILABLE + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 30000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 30000 + total_timeout_millis: 900000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: SubmitJob + flattening: + groups: + - parameters: + - project_id + - region + - job + required_fields: + - project_id + - region + - job + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + - name: GetJob + flattening: + groups: + - parameters: + - project_id + - region + - job_id + required_fields: + - project_id + - region + - job_id + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: ListJobs + flattening: + groups: + - parameters: + - project_id + - region + - parameters: + - project_id + - region + - filter + required_fields: + - project_id + - region + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: jobs + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: UpdateJob + required_fields: + - project_id + - region + - job_id + - job + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + - name: CancelJob + flattening: + groups: + - parameters: + - project_id + - region + - job_id + required_fields: + - project_id + - region + - job_id + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: DeleteJob + flattening: + groups: + - parameters: + - project_id + - region + - job_id + required_fields: + - project_id + - region + - job_id + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.dataproc.v1beta2.WorkflowTemplateService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/regions/{region} + entity_name: region + - name_pattern: projects/{project}/regions/{region}/workflowTemplates/{workflow_template} + entity_name: workflow_template + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - INTERNAL + - UNAVAILABLE + - name: non_idempotent + retry_codes: + - UNAVAILABLE + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateWorkflowTemplate + flattening: + groups: + - parameters: + - parent + - template + required_fields: + - parent + - template + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: region + timeout_millis: 30000 + - name: GetWorkflowTemplate + # params. + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: workflow_template + timeout_millis: 60000 + - name: InstantiateWorkflowTemplate + flattening: + groups: + - parameters: + - name + - parameters: + - parameters + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: workflow_template + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1beta2.WorkflowMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 43200000 + - name: InstantiateInlineWorkflowTemplate + flattening: + groups: + - parameters: + - parent + - template + required_fields: + - parent + - template + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: region + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.dataproc.v1beta2.WorkflowMetadata + implements_delete: false + implements_cancel: false + initial_poll_delay_millis: 1000 + poll_delay_multiplier: 2 + max_poll_delay_millis: 10000 + total_poll_timeout_millis: 43200000 + - name: UpdateWorkflowTemplate + flattening: + groups: + - parameters: + - template + required_fields: + - template + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + template.name: workflow_template + timeout_millis: 60000 + - name: ListWorkflowTemplates + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: templates + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: region + timeout_millis: 60000 + - name: DeleteWorkflowTemplate + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: workflow_template + timeout_millis: 60000 +resource_name_generation: +- message_name: WorkflowTemplate + field_entity_map: + name: workflow_template +- message_name: CreateWorkflowTemplateRequest + field_entity_map: + parent: region +- message_name: GetWorkflowTemplateRequest + field_entity_map: + name: workflow_template +- message_name: InstantiateWorkflowTemplateRequest + field_entity_map: + name: workflow_template +- message_name: ListWorkflowTemplatesRequest + field_entity_map: + parent: region +- message_name: DeleteWorkflowTemplateRequest + field_entity_map: + name: workflow_template diff --git a/google/cloud/dataproc/v1beta2/jobs.proto b/google/cloud/dataproc/v1beta2/jobs.proto new file mode 100644 index 000000000..4f949ba94 --- /dev/null +++ b/google/cloud/dataproc/v1beta2/jobs.proto @@ -0,0 +1,783 @@ +// Copyright 2018 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.dataproc.v1beta2; + +import "google/api/annotations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1beta2;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "JobsProto"; +option java_package = "com.google.cloud.dataproc.v1beta2"; + +// The JobController provides methods to manage jobs. +service JobController { + // Submits a job to a cluster. + rpc SubmitJob(SubmitJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1beta2/projects/{project_id}/regions/{region}/jobs:submit" + body: "*" + }; + } + + // Gets the resource representation for a job in a project. + rpc GetJob(GetJobRequest) returns (Job) { + option (google.api.http) = { + get: "/v1beta2/projects/{project_id}/regions/{region}/jobs/{job_id}" + }; + } + + // Lists regions/{region}/jobs in a project. + rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) { + option (google.api.http) = { + get: "/v1beta2/projects/{project_id}/regions/{region}/jobs" + }; + } + + // Updates a job in a project. + rpc UpdateJob(UpdateJobRequest) returns (Job) { + option (google.api.http) = { + patch: "/v1beta2/projects/{project_id}/regions/{region}/jobs/{job_id}" + body: "job" + }; + } + + // Starts a job cancellation request. To access the job resource + // after cancellation, call + // [regions/{region}/jobs.list](/dataproc/docs/reference/rest/v1beta2/projects.regions.jobs/list) + // or + // [regions/{region}/jobs.get](/dataproc/docs/reference/rest/v1beta2/projects.regions.jobs/get). + rpc CancelJob(CancelJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1beta2/projects/{project_id}/regions/{region}/jobs/{job_id}:cancel" + body: "*" + }; + } + + // Deletes the job from the project. If the job is active, the delete fails, + // and the response returns `FAILED_PRECONDITION`. + rpc DeleteJob(DeleteJobRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta2/projects/{project_id}/regions/{region}/jobs/{job_id}" + }; + } +} + +// The runtime logging config of the job. +message LoggingConfig { + // The Log4j level for job execution. When running an + // [Apache Hive](http://hive.apache.org/) job, Cloud + // Dataproc configures the Hive client to an equivalent verbosity level. + enum Level { + // Level is unspecified. Use default level for log4j. + LEVEL_UNSPECIFIED = 0; + + // Use ALL level for log4j. + ALL = 1; + + // Use TRACE level for log4j. + TRACE = 2; + + // Use DEBUG level for log4j. + DEBUG = 3; + + // Use INFO level for log4j. + INFO = 4; + + // Use WARN level for log4j. + WARN = 5; + + // Use ERROR level for log4j. + ERROR = 6; + + // Use FATAL level for log4j. + FATAL = 7; + + // Turn off log4j. + OFF = 8; + } + + // The per-package log levels for the driver. This may include + // "root" package name to configure rootLogger. + // Examples: + // 'com.google = FATAL', 'root = INFO', 'org.apache = DEBUG' + map<string, Level> driver_log_levels = 2; +} + +// A Cloud Dataproc job for running +// [Apache Hadoop +// MapReduce](https://hadoop.apache.org/docs/current/hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapReduceTutorial.html) +// jobs on [Apache Hadoop +// YARN](https://hadoop.apache.org/docs/r2.7.1/hadoop-yarn/hadoop-yarn-site/YARN.html). +message HadoopJob { + // Required. Indicates the location of the driver's main class. Specify + // either the jar file that contains the main class or the main class name. + // To specify both, add the jar file to `jar_file_uris`, and then specify + // the main class name in this property. + oneof driver { + // The HCFS URI of the jar file containing the main class. + // Examples: + // 'gs://foo-bucket/analytics-binaries/extract-useful-metrics-mr.jar' + // 'hdfs:/tmp/test-samples/custom-wordcount.jar' + // 'file:///home/usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar' + string main_jar_file_uri = 1; + + // The name of the driver's main class. The jar file containing the class + // must be in the default CLASSPATH or specified in `jar_file_uris`. + string main_class = 2; + } + + // Optional. The arguments to pass to the driver. Do not + // include arguments, such as `-libjars` or `-Dfoo=bar`, that can be set as + // job properties, since a collision may occur that causes an incorrect job + // submission. + repeated string args = 3; + + // Optional. Jar file URIs to add to the CLASSPATHs of the + // Hadoop driver and tasks. + repeated string jar_file_uris = 4; + + // Optional. HCFS (Hadoop Compatible Filesystem) URIs of files to be copied + // to the working directory of Hadoop drivers and distributed tasks. Useful + // for naively parallel tasks. + repeated string file_uris = 5; + + // Optional. HCFS URIs of archives to be extracted in the working directory of + // Hadoop drivers and tasks. Supported file types: + // .jar, .tar, .tar.gz, .tgz, or .zip. + repeated string archive_uris = 6; + + // Optional. A mapping of property names to values, used to configure Hadoop. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in /etc/hadoop/conf/*-site and + // classes in user code. + map<string, string> properties = 7; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 8; +} + +// A Cloud Dataproc job for running [Apache Spark](http://spark.apache.org/) +// applications on YARN. +message SparkJob { + // Required. The specification of the main method to call to drive the job. + // Specify either the jar file that contains the main class or the main class + // name. To pass both a main jar and a main class in that jar, add the jar to + // `CommonJob.jar_file_uris`, and then specify the main class name in + // `main_class`. + oneof driver { + // The HCFS URI of the jar file that contains the main class. + string main_jar_file_uri = 1; + + // The name of the driver's main class. The jar file that contains the class + // must be in the default CLASSPATH or specified in `jar_file_uris`. + string main_class = 2; + } + + // Optional. The arguments to pass to the driver. Do not include arguments, + // such as `--conf`, that can be set as job properties, since a collision may + // occur that causes an incorrect job submission. + repeated string args = 3; + + // Optional. HCFS URIs of jar files to add to the CLASSPATHs of the + // Spark driver and tasks. + repeated string jar_file_uris = 4; + + // Optional. HCFS URIs of files to be copied to the working directory of + // Spark drivers and distributed tasks. Useful for naively parallel tasks. + repeated string file_uris = 5; + + // Optional. HCFS URIs of archives to be extracted in the working directory + // of Spark drivers and tasks. Supported file types: + // .jar, .tar, .tar.gz, .tgz, and .zip. + repeated string archive_uris = 6; + + // Optional. A mapping of property names to values, used to configure Spark. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in + // /etc/spark/conf/spark-defaults.conf and classes in user code. + map<string, string> properties = 7; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 8; +} + +// A Cloud Dataproc job for running +// [Apache +// PySpark](https://spark.apache.org/docs/0.9.0/python-programming-guide.html) +// applications on YARN. +message PySparkJob { + // Required. The HCFS URI of the main Python file to use as the driver. Must + // be a .py file. + string main_python_file_uri = 1; + + // Optional. The arguments to pass to the driver. Do not include arguments, + // such as `--conf`, that can be set as job properties, since a collision may + // occur that causes an incorrect job submission. + repeated string args = 2; + + // Optional. HCFS file URIs of Python files to pass to the PySpark + // framework. Supported file types: .py, .egg, and .zip. + repeated string python_file_uris = 3; + + // Optional. HCFS URIs of jar files to add to the CLASSPATHs of the + // Python driver and tasks. + repeated string jar_file_uris = 4; + + // Optional. HCFS URIs of files to be copied to the working directory of + // Python drivers and distributed tasks. Useful for naively parallel tasks. + repeated string file_uris = 5; + + // Optional. HCFS URIs of archives to be extracted in the working directory of + // .jar, .tar, .tar.gz, .tgz, and .zip. + repeated string archive_uris = 6; + + // Optional. A mapping of property names to values, used to configure PySpark. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in + // /etc/spark/conf/spark-defaults.conf and classes in user code. + map<string, string> properties = 7; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 8; +} + +// A list of queries to run on a cluster. +message QueryList { + // Required. The queries to execute. You do not need to terminate a query + // with a semicolon. Multiple queries can be specified in one string + // by separating each with a semicolon. Here is an example of an Cloud + // Dataproc API snippet that uses a QueryList to specify a HiveJob: + // + // "hiveJob": { + // "queryList": { + // "queries": [ + // "query1", + // "query2", + // "query3;query4", + // ] + // } + // } + repeated string queries = 1; +} + +// A Cloud Dataproc job for running [Apache Hive](https://hive.apache.org/) +// queries on YARN. +message HiveJob { + // Required. The sequence of Hive queries to execute, specified as either + // an HCFS file URI or a list of queries. + oneof queries { + // The HCFS URI of the script that contains Hive queries. + string query_file_uri = 1; + + // A list of queries. + QueryList query_list = 2; + } + + // Optional. Whether to continue executing queries if a query fails. + // The default value is `false`. Setting to `true` can be useful when + // executing independent parallel queries. + bool continue_on_failure = 3; + + // Optional. Mapping of query variable names to values (equivalent to the + // Hive command: `SET name="value";`). + map<string, string> script_variables = 4; + + // Optional. A mapping of property names and values, used to configure Hive. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in /etc/hadoop/conf/*-site.xml, + // /etc/hive/conf/hive-site.xml, and classes in user code. + map<string, string> properties = 5; + + // Optional. HCFS URIs of jar files to add to the CLASSPATH of the + // Hive server and Hadoop MapReduce (MR) tasks. Can contain Hive SerDes + // and UDFs. + repeated string jar_file_uris = 6; +} + +// A Cloud Dataproc job for running [Apache Spark +// SQL](http://spark.apache.org/sql/) queries. +message SparkSqlJob { + // Required. The sequence of Spark SQL queries to execute, specified as + // either an HCFS file URI or as a list of queries. + oneof queries { + // The HCFS URI of the script that contains SQL queries. + string query_file_uri = 1; + + // A list of queries. + QueryList query_list = 2; + } + + // Optional. Mapping of query variable names to values (equivalent to the + // Spark SQL command: SET `name="value";`). + map<string, string> script_variables = 3; + + // Optional. A mapping of property names to values, used to configure + // Spark SQL's SparkConf. Properties that conflict with values set by the + // Cloud Dataproc API may be overwritten. + map<string, string> properties = 4; + + // Optional. HCFS URIs of jar files to be added to the Spark CLASSPATH. + repeated string jar_file_uris = 56; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 6; +} + +// A Cloud Dataproc job for running [Apache Pig](https://pig.apache.org/) +// queries on YARN. +message PigJob { + // Required. The sequence of Pig queries to execute, specified as an HCFS + // file URI or a list of queries. + oneof queries { + // The HCFS URI of the script that contains the Pig queries. + string query_file_uri = 1; + + // A list of queries. + QueryList query_list = 2; + } + + // Optional. Whether to continue executing queries if a query fails. + // The default value is `false`. Setting to `true` can be useful when + // executing independent parallel queries. + bool continue_on_failure = 3; + + // Optional. Mapping of query variable names to values (equivalent to the Pig + // command: `name=[value]`). + map<string, string> script_variables = 4; + + // Optional. A mapping of property names to values, used to configure Pig. + // Properties that conflict with values set by the Cloud Dataproc API may be + // overwritten. Can include properties set in /etc/hadoop/conf/*-site.xml, + // /etc/pig/conf/pig.properties, and classes in user code. + map<string, string> properties = 5; + + // Optional. HCFS URIs of jar files to add to the CLASSPATH of + // the Pig Client and Hadoop MapReduce (MR) tasks. Can contain Pig UDFs. + repeated string jar_file_uris = 6; + + // Optional. The runtime log config for job execution. + LoggingConfig logging_config = 7; +} + +// Cloud Dataproc job config. +message JobPlacement { + // Required. The name of the cluster where the job will be submitted. + string cluster_name = 1; + + // Output only. A cluster UUID generated by the Cloud Dataproc service when + // the job is submitted. + string cluster_uuid = 2; +} + +// Cloud Dataproc job status. +message JobStatus { + // The job state. + enum State { + // The job state is unknown. + STATE_UNSPECIFIED = 0; + + // The job is pending; it has been submitted, but is not yet running. + PENDING = 1; + + // Job has been received by the service and completed initial setup; + // it will soon be submitted to the cluster. + SETUP_DONE = 8; + + // The job is running on the cluster. + RUNNING = 2; + + // A CancelJob request has been received, but is pending. + CANCEL_PENDING = 3; + + // Transient in-flight resources have been canceled, and the request to + // cancel the running job has been issued to the cluster. + CANCEL_STARTED = 7; + + // The job cancellation was successful. + CANCELLED = 4; + + // The job has completed successfully. + DONE = 5; + + // The job has completed, but encountered an error. + ERROR = 6; + + // Job attempt has failed. The detail field contains failure details for + // this attempt. + // + // Applies to restartable jobs only. + ATTEMPT_FAILURE = 9; + } + + // The job substate. + enum Substate { + // The job substate is unknown. + UNSPECIFIED = 0; + + // The Job is submitted to the agent. + // + // Applies to RUNNING state. + SUBMITTED = 1; + + // The Job has been received and is awaiting execution (it may be waiting + // for a condition to be met). See the "details" field for the reason for + // the delay. + // + // Applies to RUNNING state. + QUEUED = 2; + + // The agent-reported status is out of date, which may be caused by a + // loss of communication between the agent and Cloud Dataproc. If the + // agent does not send a timely update, the job will fail. + // + // Applies to RUNNING state. + STALE_STATUS = 3; + } + + // Output only. A state message specifying the overall job state. + State state = 1; + + // Output only. Optional job state details, such as an error + // description if the state is <code>ERROR</code>. + string details = 2; + + // Output only. The time when this state was entered. + google.protobuf.Timestamp state_start_time = 6; + + // Output only. Additional state information, which includes + // status reported by the agent. + Substate substate = 7; +} + +// Encapsulates the full scoping used to reference a job. +message JobReference { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Optional. The job ID, which must be unique within the project. The job ID + // is generated by the server upon job submission or provided by the user as a + // means to perform retries without creating duplicate jobs. The ID must + // contain only letters (a-z, A-Z), numbers (0-9), underscores (_), or + // hyphens (-). The maximum length is 100 characters. + string job_id = 2; +} + +// A YARN application created by a job. Application information is a subset of +// <code>org.apache.hadoop.yarn.proto.YarnProtos.ApplicationReportProto</code>. +// +// **Beta Feature**: This report is available for testing purposes only. It may +// be changed before final release. +message YarnApplication { + // The application state, corresponding to + // <code>YarnProtos.YarnApplicationStateProto</code>. + enum State { + // Status is unspecified. + STATE_UNSPECIFIED = 0; + + // Status is NEW. + NEW = 1; + + // Status is NEW_SAVING. + NEW_SAVING = 2; + + // Status is SUBMITTED. + SUBMITTED = 3; + + // Status is ACCEPTED. + ACCEPTED = 4; + + // Status is RUNNING. + RUNNING = 5; + + // Status is FINISHED. + FINISHED = 6; + + // Status is FAILED. + FAILED = 7; + + // Status is KILLED. + KILLED = 8; + } + + // Required. The application name. + string name = 1; + + // Required. The application state. + State state = 2; + + // Required. The numerical progress of the application, from 1 to 100. + float progress = 3; + + // Optional. The HTTP URL of the ApplicationMaster, HistoryServer, or + // TimelineServer that provides application-specific information. The URL uses + // the internal hostname, and requires a proxy server for resolution and, + // possibly, access. + string tracking_url = 4; +} + +// A Cloud Dataproc job resource. +message Job { + // Optional. The fully qualified reference to the job, which can be used to + // obtain the equivalent REST path of the job resource. If this property + // is not specified when a job is created, the server generates a + // <code>job_id</code>. + JobReference reference = 1; + + // Required. Job information, including how, when, and where to + // run the job. + JobPlacement placement = 2; + + // Required. The application/framework-specific portion of the job. + oneof type_job { + // Job is a Hadoop job. + HadoopJob hadoop_job = 3; + + // Job is a Spark job. + SparkJob spark_job = 4; + + // Job is a Pyspark job. + PySparkJob pyspark_job = 5; + + // Job is a Hive job. + HiveJob hive_job = 6; + + // Job is a Pig job. + PigJob pig_job = 7; + + // Job is a SparkSql job. + SparkSqlJob spark_sql_job = 12; + } + + // Output only. The job status. Additional application-specific + // status information may be contained in the <code>type_job</code> + // and <code>yarn_applications</code> fields. + JobStatus status = 8; + + // Output only. The previous job status. + repeated JobStatus status_history = 13; + + // Output only. The collection of YARN applications spun up by this job. + // + // **Beta** Feature: This report is available for testing purposes only. It + // may be changed before final release. + repeated YarnApplication yarn_applications = 9; + + // Output only. The email address of the user submitting the job. For jobs + // submitted on the cluster, the address is <code>username@hostname</code>. + string submitted_by = 10; + + // Output only. A URI pointing to the location of the stdout of the job's + // driver program. + string driver_output_resource_uri = 17; + + // Output only. If present, the location of miscellaneous control files + // which may be used as part of job setup and handling. If not present, + // control files may be placed in the same location as `driver_output_uri`. + string driver_control_files_uri = 15; + + // Optional. The labels to associate with this job. + // Label **keys** must contain 1 to 63 characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // Label **values** may be empty, but, if present, must contain 1 to 63 + // characters, and must conform to [RFC + // 1035](https://www.ietf.org/rfc/rfc1035.txt). No more than 32 labels can be + // associated with a job. + map<string, string> labels = 18; + + // Optional. Job scheduling configuration. + JobScheduling scheduling = 20; + + // Output only. A UUID that uniquely identifies a job within the project + // over time. This is in contrast to a user-settable reference.job_id that + // may be reused over time. + string job_uuid = 22; +} + +// Job scheduling options. +message JobScheduling { + // Optional. Maximum number of times per hour a driver may be restarted as + // a result of driver terminating with non-zero code before job is + // reported failed. + // + // A job may be reported as thrashing if driver exits with non-zero code + // 4 times within 10 minute window. + // + // Maximum value is 10. + int32 max_failures_per_hour = 1; +} + +// A request to submit a job. +message SubmitJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job resource. + Job job = 2; + + // Optional. A unique id used to identify the request. If the server + // receives two + // [SubmitJobRequest][google.cloud.dataproc.v1beta2.SubmitJobRequest] requests + // with the same id, then the second request will be ignored and the first + // [Job][google.cloud.dataproc.v1beta2.Job] created and stored in the backend + // is returned. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 4; +} + +// A request to get the resource representation for a job in a project. +message GetJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job ID. + string job_id = 2; +} + +// A request to list jobs in a project. +message ListJobsRequest { + // A matcher that specifies categories of job states. + enum JobStateMatcher { + // Match all jobs, regardless of state. + ALL = 0; + + // Only match jobs in non-terminal states: PENDING, RUNNING, or + // CANCEL_PENDING. + ACTIVE = 1; + + // Only match jobs in terminal states: CANCELLED, DONE, or ERROR. + NON_ACTIVE = 2; + } + + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 6; + + // Optional. The number of results to return in each response. + int32 page_size = 2; + + // Optional. The page token, returned by a previous call, to request the + // next page of results. + string page_token = 3; + + // Optional. If set, the returned jobs list includes only jobs that were + // submitted to the named cluster. + string cluster_name = 4; + + // Optional. Specifies enumerated categories of jobs to list. + // (default = match ALL jobs). + // + // If `filter` is provided, `jobStateMatcher` will be ignored. + JobStateMatcher job_state_matcher = 5; + + // Optional. A filter constraining the jobs to list. Filters are + // case-sensitive and have the following syntax: + // + // [field = value] AND [field [= value]] ... + // + // where **field** is `status.state` or `labels.[KEY]`, and `[KEY]` is a label + // key. **value** can be `*` to match all values. + // `status.state` can be either `ACTIVE` or `NON_ACTIVE`. + // Only the logical `AND` operator is supported; space-separated items are + // treated as having an implicit `AND` operator. + // + // Example filter: + // + // status.state = ACTIVE AND labels.env = staging AND labels.starred = * + string filter = 7; +} + +// A request to update a job. +message UpdateJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 2; + + // Required. The job ID. + string job_id = 3; + + // Required. The changes to the job. + Job job = 4; + + // Required. Specifies the path, relative to <code>Job</code>, of + // the field to update. For example, to update the labels of a Job the + // <code>update_mask</code> parameter would be specified as + // <code>labels</code>, and the `PATCH` request body would specify the new + // value. <strong>Note:</strong> Currently, <code>labels</code> is the only + // field that can be updated. + google.protobuf.FieldMask update_mask = 5; +} + +// A list of jobs in a project. +message ListJobsResponse { + // Output only. Jobs list. + repeated Job jobs = 1; + + // Optional. This token is included in the response if there are more results + // to fetch. To fetch additional results, provide this value as the + // `page_token` in a subsequent <code>ListJobsRequest</code>. + string next_page_token = 2; +} + +// A request to cancel a job. +message CancelJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job ID. + string job_id = 2; +} + +// A request to delete a job. +message DeleteJobRequest { + // Required. The ID of the Google Cloud Platform project that the job + // belongs to. + string project_id = 1; + + // Required. The Cloud Dataproc region in which to handle the request. + string region = 3; + + // Required. The job ID. + string job_id = 2; +} diff --git a/google/cloud/dataproc/v1beta2/operations.proto b/google/cloud/dataproc/v1beta2/operations.proto new file mode 100644 index 000000000..b77eeddee --- /dev/null +++ b/google/cloud/dataproc/v1beta2/operations.proto @@ -0,0 +1,83 @@ +// Copyright 2018 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.dataproc.v1beta2; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1beta2;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "OperationsProto"; +option java_package = "com.google.cloud.dataproc.v1beta2"; + +// The status of the operation. +message ClusterOperationStatus { + // The operation state. + enum State { + // Unused. + UNKNOWN = 0; + + // The operation has been created. + PENDING = 1; + + // The operation is running. + RUNNING = 2; + + // The operation is done; either cancelled or completed. + DONE = 3; + } + + // Output only. A message containing the operation state. + State state = 1; + + // Output only. A message containing the detailed operation state. + string inner_state = 2; + + // Output only. A message containing any operation metadata details. + string details = 3; + + // Output only. The time this state was entered. + google.protobuf.Timestamp state_start_time = 4; +} + +// Metadata describing the operation. +message ClusterOperationMetadata { + // Output only. Name of the cluster for the operation. + string cluster_name = 7; + + // Output only. Cluster UUID for the operation. + string cluster_uuid = 8; + + // Output only. Current operation status. + ClusterOperationStatus status = 9; + + // Output only. The previous operation status. + repeated ClusterOperationStatus status_history = 10; + + // Output only. The operation type. + string operation_type = 11; + + // Output only. Short description of operation. + string description = 12; + + // Output only. Labels associated with the operation + map<string, string> labels = 13; + + // Output only. Errors encountered during operation execution. + repeated string warnings = 14; +} diff --git a/google/cloud/dataproc/v1beta2/shared.proto b/google/cloud/dataproc/v1beta2/shared.proto new file mode 100644 index 000000000..c9bea686a --- /dev/null +++ b/google/cloud/dataproc/v1beta2/shared.proto @@ -0,0 +1,25 @@ +// Copyright 2018 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.dataproc.v1beta2; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1beta2;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "SharedProto"; +option java_package = "com.google.cloud.dataproc.v1beta2"; diff --git a/google/cloud/dataproc/v1beta2/workflow_templates.proto b/google/cloud/dataproc/v1beta2/workflow_templates.proto new file mode 100644 index 000000000..cb2584496 --- /dev/null +++ b/google/cloud/dataproc/v1beta2/workflow_templates.proto @@ -0,0 +1,676 @@ +// Copyright 2018 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.dataproc.v1beta2; + +import "google/api/annotations.proto"; +import "google/cloud/dataproc/v1beta2/clusters.proto"; +import "google/cloud/dataproc/v1beta2/jobs.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/dataproc/v1beta2;dataproc"; +option java_multiple_files = true; +option java_outer_classname = "WorkflowTemplatesProto"; +option java_package = "com.google.cloud.dataproc.v1beta2"; + +// The API interface for managing Workflow Templates in the +// Cloud Dataproc API. +service WorkflowTemplateService { + // Creates new workflow template. + rpc CreateWorkflowTemplate(CreateWorkflowTemplateRequest) + returns (WorkflowTemplate) { + option (google.api.http) = { + post: "/v1beta2/{parent=projects/*/regions/*}/workflowTemplates" + body: "template" + additional_bindings { + post: "/v1beta2/{parent=projects/*/locations/*}/workflowTemplates" + body: "template" + } + }; + } + + // Retrieves the latest workflow template. + // + // Can retrieve previously instantiated template by specifying optional + // version parameter. + rpc GetWorkflowTemplate(GetWorkflowTemplateRequest) + returns (WorkflowTemplate) { + option (google.api.http) = { + get: "/v1beta2/{name=projects/*/regions/*/workflowTemplates/*}" + additional_bindings { + get: "/v1beta2/{name=projects/*/locations/*/workflowTemplates/*}" + } + }; + } + + // Instantiates a template and begins execution. + // + // The returned Operation can be used to track execution of + // workflow by polling + // [operations.get][google.longrunning.Operations.GetOperation]. + // The Operation will complete when entire workflow is finished. + // + // The running workflow can be aborted via + // [operations.cancel][google.longrunning.Operations.CancelOperation]. + // This will cause any inflight jobs to be cancelled and workflow-owned + // clusters to be deleted. + // + // The [Operation.metadata][google.longrunning.Operation.metadata] will be + // [WorkflowMetadata][google.cloud.dataproc.v1beta2.WorkflowMetadata]. + // + // On successful completion, + // [Operation.response][google.longrunning.Operation.response] will be + // [Empty][google.protobuf.Empty]. + rpc InstantiateWorkflowTemplate(InstantiateWorkflowTemplateRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta2/{name=projects/*/regions/*/workflowTemplates/*}:instantiate" + body: "*" + additional_bindings { + post: "/v1beta2/{name=projects/*/locations/*/workflowTemplates/*}:instantiate" + body: "*" + } + }; + } + + // Instantiates a template and begins execution. + // + // This method is equivalent to executing the sequence + // [CreateWorkflowTemplate][google.cloud.dataproc.v1beta2.WorkflowTemplateService.CreateWorkflowTemplate], + // [InstantiateWorkflowTemplate][google.cloud.dataproc.v1beta2.WorkflowTemplateService.InstantiateWorkflowTemplate], + // [DeleteWorkflowTemplate][google.cloud.dataproc.v1beta2.WorkflowTemplateService.DeleteWorkflowTemplate]. + // + // The returned Operation can be used to track execution of + // workflow by polling + // [operations.get][google.longrunning.Operations.GetOperation]. + // The Operation will complete when entire workflow is finished. + // + // The running workflow can be aborted via + // [operations.cancel][google.longrunning.Operations.CancelOperation]. + // This will cause any inflight jobs to be cancelled and workflow-owned + // clusters to be deleted. + // + // The [Operation.metadata][google.longrunning.Operation.metadata] will be + // [WorkflowMetadata][google.cloud.dataproc.v1beta2.WorkflowMetadata]. + // + // On successful completion, + // [Operation.response][google.longrunning.Operation.response] will be + // [Empty][google.protobuf.Empty]. + rpc InstantiateInlineWorkflowTemplate( + InstantiateInlineWorkflowTemplateRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta2/{parent=projects/*/locations/*}/workflowTemplates:instantiateInline" + body: "template" + additional_bindings { + post: "/v1beta2/{parent=projects/*/regions/*}/workflowTemplates:instantiateInline" + body: "template" + } + }; + } + + // Updates (replaces) workflow template. The updated template + // must contain version that matches the current server version. + rpc UpdateWorkflowTemplate(UpdateWorkflowTemplateRequest) + returns (WorkflowTemplate) { + option (google.api.http) = { + put: "/v1beta2/{template.name=projects/*/regions/*/workflowTemplates/*}" + body: "template" + additional_bindings { + put: "/v1beta2/{template.name=projects/*/locations/*/workflowTemplates/*}" + body: "template" + } + }; + } + + // Lists workflows that match the specified filter in the request. + rpc ListWorkflowTemplates(ListWorkflowTemplatesRequest) + returns (ListWorkflowTemplatesResponse) { + option (google.api.http) = { + get: "/v1beta2/{parent=projects/*/regions/*}/workflowTemplates" + additional_bindings { + get: "/v1beta2/{parent=projects/*/locations/*}/workflowTemplates" + } + }; + } + + // Deletes a workflow template. It does not cancel in-progress workflows. + rpc DeleteWorkflowTemplate(DeleteWorkflowTemplateRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta2/{name=projects/*/regions/*/workflowTemplates/*}" + additional_bindings { + delete: "/v1beta2/{name=projects/*/locations/*/workflowTemplates/*}" + } + }; + } +} + +// A Cloud Dataproc workflow template resource. +message WorkflowTemplate { + // Required. The template id. + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). Cannot begin or end with underscore + // or hyphen. Must consist of between 3 and 50 characters. + string id = 2; + + // Output only. The "resource name" of the template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. Used to perform a consistent read-modify-write. + // + // This field should be left blank for a `CreateWorkflowTemplate` request. It + // is required for an `UpdateWorkflowTemplate` request, and must match the + // current server version. A typical update template flow would fetch the + // current template with a `GetWorkflowTemplate` request, which will return + // the current template with the `version` field filled in with the + // current server version. The user updates other fields in the template, + // then returns it as part of the `UpdateWorkflowTemplate` request. + int32 version = 3; + + // Output only. The time template was created. + google.protobuf.Timestamp create_time = 4; + + // Output only. The time template was last updated. + google.protobuf.Timestamp update_time = 5; + + // Optional. The labels to associate with this template. These labels + // will be propagated to all jobs and clusters created by the workflow + // instance. + // + // Label **keys** must contain 1 to 63 characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // + // Label **values** may be empty, but, if present, must contain 1 to 63 + // characters, and must conform to + // [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt). + // + // No more than 32 labels can be associated with a template. + map<string, string> labels = 6; + + // Required. WorkflowTemplate scheduling information. + WorkflowTemplatePlacement placement = 7; + + // Required. The Directed Acyclic Graph of Jobs to submit. + repeated OrderedJob jobs = 8; + + // Optional. Template parameters whose values are substituted into the + // template. Values for parameters must be provided when the template is + // instantiated. + repeated TemplateParameter parameters = 9; +} + +// Specifies workflow execution target. +// +// Either `managed_cluster` or `cluster_selector` is required. +message WorkflowTemplatePlacement { + // Required. Specifies where workflow executes; either on a managed + // cluster or an existing cluster chosen by labels. + oneof placement { + // Optional. A cluster that is managed by the workflow. + ManagedCluster managed_cluster = 1; + + // Optional. A selector that chooses target cluster for jobs based + // on metadata. + // + // The selector is evaluated at the time each job is submitted. + ClusterSelector cluster_selector = 2; + } +} + +// Cluster that is managed by the workflow. +message ManagedCluster { + // Required. The cluster name prefix. A unique cluster name will be formed by + // appending a random suffix. + // + // The name must contain only lower-case letters (a-z), numbers (0-9), + // and hyphens (-). Must begin with a letter. Cannot begin or end with + // hyphen. Must consist of between 2 and 35 characters. + string cluster_name = 2; + + // Required. The cluster configuration. + ClusterConfig config = 3; + + // Optional. The labels to associate with this cluster. + // + // Label keys must be between 1 and 63 characters long, and must conform to + // the following PCRE regular expression: + // [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62} + // + // Label values must be between 1 and 63 characters long, and must conform to + // the following PCRE regular expression: [\p{Ll}\p{Lo}\p{N}_-]{0,63} + // + // No more than 32 labels can be associated with a given cluster. + map<string, string> labels = 4; +} + +// A selector that chooses target cluster for jobs based on metadata. +message ClusterSelector { + // Optional. The zone where workflow process executes. This parameter does not + // affect the selection of the cluster. + // + // If unspecified, the zone of the first cluster matching the selector + // is used. + string zone = 1; + + // Required. The cluster labels. Cluster must have all labels + // to match. + map<string, string> cluster_labels = 2; +} + +// A job executed by the workflow. +message OrderedJob { + // Required. The step id. The id must be unique among all jobs + // within the template. + // + // The step id is used as prefix for job id, as job + // `goog-dataproc-workflow-step-id` label, and in + // [prerequisiteStepIds][google.cloud.dataproc.v1beta2.OrderedJob.prerequisite_step_ids] + // field from other steps. + // + // The id must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). Cannot begin or end with underscore + // or hyphen. Must consist of between 3 and 50 characters. + string step_id = 1; + + // Required. The job definition. + oneof job_type { + // Job is a Hadoop job. + HadoopJob hadoop_job = 2; + + // Job is a Spark job. + SparkJob spark_job = 3; + + // Job is a Pyspark job. + PySparkJob pyspark_job = 4; + + // Job is a Hive job. + HiveJob hive_job = 5; + + // Job is a Pig job. + PigJob pig_job = 6; + + // Job is a SparkSql job. + SparkSqlJob spark_sql_job = 7; + } + + // Optional. The labels to associate with this job. + // + // Label keys must be between 1 and 63 characters long, and must conform to + // the following regular expression: + // [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62} + // + // Label values must be between 1 and 63 characters long, and must conform to + // the following regular expression: [\p{Ll}\p{Lo}\p{N}_-]{0,63} + // + // No more than 32 labels can be associated with a given job. + map<string, string> labels = 8; + + // Optional. Job scheduling configuration. + JobScheduling scheduling = 9; + + // Optional. The optional list of prerequisite job step_ids. + // If not specified, the job will start at the beginning of workflow. + repeated string prerequisite_step_ids = 10; +} + +// A configurable parameter that replaces one or more fields in the template. +// Parameterizable fields: +// - Labels +// - File uris +// - Job properties +// - Job arguments +// - Script variables +// - Main class (in HadoopJob and SparkJob) +// - Zone (in ClusterSelector) +message TemplateParameter { + // Required. Parameter name. + // The parameter name is used as the key, and paired with the + // parameter value, which are passed to the template when the template + // is instantiated. + // The name must contain only capital letters (A-Z), numbers (0-9), and + // underscores (_), and must not start with a number. The maximum length is + // 40 characters. + string name = 1; + + // Required. Paths to all fields that the parameter replaces. + // A field is allowed to appear in at most one parameter's list of field + // paths. + // + // A field path is similar in syntax to a + // [google.protobuf.FieldMask][google.protobuf.FieldMask]. For example, a + // field path that references the zone field of a workflow template's cluster + // selector would be specified as `placement.clusterSelector.zone`. + // + // Also, field paths can reference fields using the following syntax: + // + // * Values in maps can be referenced by key: + // * labels['key'] + // * placement.clusterSelector.clusterLabels['key'] + // * placement.managedCluster.labels['key'] + // * placement.clusterSelector.clusterLabels['key'] + // * jobs['step-id'].labels['key'] + // + // * Jobs in the jobs list can be referenced by step-id: + // * jobs['step-id'].hadoopJob.mainJarFileUri + // * jobs['step-id'].hiveJob.queryFileUri + // * jobs['step-id'].pySparkJob.mainPythonFileUri + // * jobs['step-id'].hadoopJob.jarFileUris[0] + // * jobs['step-id'].hadoopJob.archiveUris[0] + // * jobs['step-id'].hadoopJob.fileUris[0] + // * jobs['step-id'].pySparkJob.pythonFileUris[0] + // + // * Items in repeated fields can be referenced by a zero-based index: + // * jobs['step-id'].sparkJob.args[0] + // + // * Other examples: + // * jobs['step-id'].hadoopJob.properties['key'] + // * jobs['step-id'].hadoopJob.args[0] + // * jobs['step-id'].hiveJob.scriptVariables['key'] + // * jobs['step-id'].hadoopJob.mainJarFileUri + // * placement.clusterSelector.zone + // + // It may not be possible to parameterize maps and repeated fields in their + // entirety since only individual map values and individual items in repeated + // fields can be referenced. For example, the following field paths are + // invalid: + // + // - placement.clusterSelector.clusterLabels + // - jobs['step-id'].sparkJob.args + repeated string fields = 2; + + // Optional. Brief description of the parameter. + // Must not exceed 1024 characters. + string description = 3; + + // Optional. Validation rules to be applied to this parameter's value. + ParameterValidation validation = 4; +} + +// Configuration for parameter validation. +message ParameterValidation { + // Required. The type of validation to be performed. + oneof validation_type { + // Validation based on regular expressions. + RegexValidation regex = 1; + + // Validation based on a list of allowed values. + ValueValidation values = 2; + } +} + +// Validation based on regular expressions. +message RegexValidation { + // Required. RE2 regular expressions used to validate the parameter's value. + // The value must match the regex in its entirety (substring + // matches are not sufficient). + repeated string regexes = 1; +} + +// Validation based on a list of allowed values. +message ValueValidation { + // Required. List of allowed values for the parameter. + repeated string values = 1; +} + +// A Cloud Dataproc workflow template resource. +message WorkflowMetadata { + // The operation state. + enum State { + // Unused. + UNKNOWN = 0; + + // The operation has been created. + PENDING = 1; + + // The operation is running. + RUNNING = 2; + + // The operation is done; either cancelled or completed. + DONE = 3; + } + + // Output only. The "resource name" of the template. + string template = 1; + + // Output only. The version of template at the time of + // workflow instantiation. + int32 version = 2; + + // Output only. The create cluster operation metadata. + ClusterOperation create_cluster = 3; + + // Output only. The workflow graph. + WorkflowGraph graph = 4; + + // Output only. The delete cluster operation metadata. + ClusterOperation delete_cluster = 5; + + // Output only. The workflow state. + State state = 6; + + // Output only. The name of the target cluster. + string cluster_name = 7; + + // Map from parameter names to values that were used for those parameters. + map<string, string> parameters = 8; + + // Output only. Workflow start time. + google.protobuf.Timestamp start_time = 9; + + // Output only. Workflow end time. + google.protobuf.Timestamp end_time = 10; + + // Output only. The UUID of target cluster. + string cluster_uuid = 11; +} + +// The cluster operation triggered by a workflow. +message ClusterOperation { + // Output only. The id of the cluster operation. + string operation_id = 1; + + // Output only. Error, if operation failed. + string error = 2; + + // Output only. Indicates the operation is done. + bool done = 3; +} + +// The workflow graph. +message WorkflowGraph { + // Output only. The workflow nodes. + repeated WorkflowNode nodes = 1; +} + +// The workflow node. +message WorkflowNode { + // The workflow node state. + enum NodeState { + // State is unspecified. + NODE_STATUS_UNSPECIFIED = 0; + + // The node is awaiting prerequisite node to finish. + BLOCKED = 1; + + // The node is runnable but not running. + RUNNABLE = 2; + + // The node is running. + RUNNING = 3; + + // The node completed successfully. + COMPLETED = 4; + + // The node failed. A node can be marked FAILED because + // its ancestor or peer failed. + FAILED = 5; + } + + // Output only. The name of the node. + string step_id = 1; + + // Output only. Node's prerequisite nodes. + repeated string prerequisite_step_ids = 2; + + // Output only. The job id; populated after the node enters RUNNING state. + string job_id = 3; + + // Output only. The node state. + NodeState state = 5; + + // Output only. The error detail. + string error = 6; +} + +// A request to create a workflow template. +message CreateWorkflowTemplateRequest { + // Required. The "resource name" of the region, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}` + string parent = 1; + + // Required. The Dataproc workflow template to create. + WorkflowTemplate template = 2; +} + +// A request to fetch a workflow template. +message GetWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. The version of workflow template to retrieve. Only previously + // instatiated versions can be retrieved. + // + // If unspecified, retrieves the current version. + int32 version = 2; +} + +// A request to instantiate a workflow template. +message InstantiateWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. The version of workflow template to instantiate. If specified, + // the workflow will be instantiated only if the current version of + // the workflow template has the supplied version. + // + // This option cannot be used to instantiate a previous version of + // workflow template. + int32 version = 2; + + // Deprecated. Please use `request_id` field instead. + string instance_id = 3 [deprecated = true]; + + // Optional. A tag that prevents multiple concurrent workflow + // instances with the same tag from running. This mitigates risk of + // concurrent instances started due to retries. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The tag must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 5; + + // Optional. Map from parameter names to values that should be used for those + // parameters. Values may not exceed 100 characters. + map<string, string> parameters = 4; +} + +// A request to instantiate an inline workflow template. +message InstantiateInlineWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template region, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}` + string parent = 1; + + // Required. The workflow template to instantiate. + WorkflowTemplate template = 2; + + // Deprecated. Please use `request_id` field instead. + string instance_id = 3; + + // Optional. A tag that prevents multiple concurrent workflow + // instances with the same tag from running. This mitigates risk of + // concurrent instances started due to retries. + // + // It is recommended to always set this value to a + // [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). + // + // The tag must contain only letters (a-z, A-Z), numbers (0-9), + // underscores (_), and hyphens (-). The maximum length is 40 characters. + string request_id = 4; +} + +// A request to update a workflow template. +message UpdateWorkflowTemplateRequest { + // Required. The updated workflow template. + // + // The `template.version` field must match the current version. + WorkflowTemplate template = 1; +} + +// A request to list workflow templates in a project. +message ListWorkflowTemplatesRequest { + // Required. The "resource name" of the region, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}` + string parent = 1; + + // Optional. The maximum number of results to return in each response. + int32 page_size = 2; + + // Optional. The page token, returned by a previous call, to request the + // next page of results. + string page_token = 3; +} + +// A response to a request to list workflow templates in a project. +message ListWorkflowTemplatesResponse { + // Output only. WorkflowTemplates list. + repeated WorkflowTemplate templates = 1; + + // Output only. This token is included in the response if there are more + // results to fetch. To fetch additional results, provide this value as the + // page_token in a subsequent <code>ListWorkflowTemplatesRequest</code>. + string next_page_token = 2; +} + +// A request to delete a workflow template. +// +// Currently started workflows will remain running. +message DeleteWorkflowTemplateRequest { + // Required. The "resource name" of the workflow template, as described + // in https://cloud.google.com/apis/design/resource_names of the form + // `projects/{project_id}/regions/{region}/workflowTemplates/{template_id}` + string name = 1; + + // Optional. The version of workflow template to delete. If specified, + // will only delete the template if the current server version matches + // specified version. + int32 version = 2; +} diff --git a/google/cloud/dialogflow/BUILD.bazel b/google/cloud/dialogflow/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/dialogflow/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/dialogflow/artman_dialogflow_v2.yaml b/google/cloud/dialogflow/artman_dialogflow_v2.yaml new file mode 100644 index 000000000..c3c4c92c1 --- /dev/null +++ b/google/cloud/dialogflow/artman_dialogflow_v2.yaml @@ -0,0 +1,34 @@ +common: + api_name: dialogflow + api_version: v2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v2 + service_yaml: dialogflow_v2.yaml + gapic_yaml: v2/dialogflow_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/dialogflow/artman_dialogflow_v2beta1.yaml b/google/cloud/dialogflow/artman_dialogflow_v2beta1.yaml new file mode 100644 index 000000000..4a94bb0aa --- /dev/null +++ b/google/cloud/dialogflow/artman_dialogflow_v2beta1.yaml @@ -0,0 +1,30 @@ +common: + api_name: dialogflow + api_version: v2beta1 + proto_deps: + - name: google-common-protos + src_proto_paths: + - v2beta1 + service_yaml: dialogflow_v2beta1.yaml + gapic_yaml: v2beta1/dialogflow_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/dialogflow/artman_dialogflow_v2beta1_java.yaml b/google/cloud/dialogflow/artman_dialogflow_v2beta1_java.yaml new file mode 100644 index 000000000..9f13a0416 --- /dev/null +++ b/google/cloud/dialogflow/artman_dialogflow_v2beta1_java.yaml @@ -0,0 +1,15 @@ +common: + api_name: dialogflow + api_version: v2beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v2beta1 + service_yaml: dialogflow_v2beta1.yaml + gapic_yaml: v2beta1/dialogflow_gapic.yaml +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA + release_level: BETA diff --git a/google/cloud/dialogflow/dialogflow_v2.yaml b/google/cloud/dialogflow/dialogflow_v2.yaml new file mode 100644 index 000000000..2115edd4a --- /dev/null +++ b/google/cloud/dialogflow/dialogflow_v2.yaml @@ -0,0 +1,135 @@ +type: google.api.Service +config_version: 3 +name: dialogflow.googleapis.com +title: Dialogflow API + +apis: +- name: google.cloud.dialogflow.v2.Agents +- name: google.cloud.dialogflow.v2.Contexts +- name: google.cloud.dialogflow.v2.EntityTypes +- name: google.cloud.dialogflow.v2.Intents +- name: google.cloud.dialogflow.v2.SessionEntityTypes +- name: google.cloud.dialogflow.v2.Sessions + +types: +- name: google.cloud.dialogflow.v2.BatchUpdateEntityTypesResponse +- name: google.cloud.dialogflow.v2.BatchUpdateIntentsResponse +- name: google.cloud.dialogflow.v2.ExportAgentResponse +- name: google.cloud.dialogflow.v2.OriginalDetectIntentRequest +- name: google.cloud.dialogflow.v2.WebhookRequest +- name: google.cloud.dialogflow.v2.WebhookResponse + +documentation: + summary: |- + Builds conversational interfaces (for example, chatbots, and voice-powered + apps and devices). + overview: |- + [Dialogflow](http://dialogflow.com/) is a natural language + understanding platform that makes it easy for you to design and integrate + a conversational user interface into your mobile app, web application, + device, bot, and so on. Using Dialogflow you can provide users new and + engaging ways to interact with your product using both voice recognition + and text input. + + For information on how Dialogflow agents, intents, entities, and so on + work, see the [Dialogflow getting + started + guide](https://dialogflow.com/docs/getting-started/basics) in the + dialogflow.com documentation. + + ## Dialogflow Editions + + Dialogflow is available in two editions: Standard and Enterprise. For + information on the difference in Dialogflow editions, see [Dialogflow + Editions](https://cloud.google.com/dialogflow-enterprise/docs/editions). + + ## The Dialogflow API + + The Dialogflow API provides a REST and gRPC API that you can use to + incorporate the Dialogflow into your product. After you have created a + Google Cloud project and a Dialogflow agent, you can use the API to create + intents, entities, and so on, and then pass user input to your Dialogflow + agent to determine user intent using + the + [detectIntent](https://cloud.google.com/dialogflow-enterprise/docs/reference/rest/v2beta1/projects.agent.sessions/detectIntent) REST + API, or the + [StreamingDetectIntentRequest](https://cloud.google.com/dialogflow-enterprise/docs/reference/rpc/google.cloud.dialogflow.v2beta1#google.cloud.dialogflow.v2beta1.StreamingDetectIntentRequest) gRPC + API. + + ## Getting Started + + * For information on setting up a Google Cloud Platform project and + creating an agent using the Dialogflow Enterprise Edition, see + [Quickstart](https://cloud.google.com/dialogflow-enterprise/docs/quickstart). * + For information on creating an agent using the Dialogflow Standard + Edition, see [Building Your First + Agent](https://dialogflow.com/docs/getting-started/building-your-first-agent) + +backend: + rules: + - selector: 'google.cloud.dialogflow.v2.Agents.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2.Contexts.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2.EntityTypes.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2.Intents.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2.SessionEntityTypes.*' + deadline: 60.0 + - selector: google.cloud.dialogflow.v2.Sessions.DetectIntent + deadline: 230.0 + - selector: google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent + deadline: 230.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 60.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 60.0 + +authentication: + rules: + - selector: 'google.cloud.dialogflow.v2.Agents.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2.Contexts.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2.EntityTypes.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2.Intents.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2.SessionEntityTypes.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.cloud.dialogflow.v2.Sessions.DetectIntent + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.longrunning.Operations.GetOperation + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.longrunning.Operations.WaitOperation + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow diff --git a/google/cloud/dialogflow/dialogflow_v2beta1.yaml b/google/cloud/dialogflow/dialogflow_v2beta1.yaml new file mode 100644 index 000000000..f2a079c6c --- /dev/null +++ b/google/cloud/dialogflow/dialogflow_v2beta1.yaml @@ -0,0 +1,157 @@ +type: google.api.Service +config_version: 3 +name: dialogflow.googleapis.com +title: Dialogflow API + +apis: +- name: google.cloud.dialogflow.v2beta1.Agents +- name: google.cloud.dialogflow.v2beta1.Contexts +- name: google.cloud.dialogflow.v2beta1.Documents +- name: google.cloud.dialogflow.v2beta1.EntityTypes +- name: google.cloud.dialogflow.v2beta1.Intents +- name: google.cloud.dialogflow.v2beta1.KnowledgeBases +- name: google.cloud.dialogflow.v2beta1.SessionEntityTypes +- name: google.cloud.dialogflow.v2beta1.Sessions + +types: +- name: google.cloud.dialogflow.v2beta1.BatchUpdateEntityTypesResponse +- name: google.cloud.dialogflow.v2beta1.BatchUpdateIntentsResponse +- name: google.cloud.dialogflow.v2beta1.ExportAgentResponse +- name: google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata +- name: google.cloud.dialogflow.v2beta1.OriginalDetectIntentRequest +- name: google.cloud.dialogflow.v2beta1.WebhookRequest +- name: google.cloud.dialogflow.v2beta1.WebhookResponse + +documentation: + summary: |- + Builds conversational interfaces (for example, chatbots, and voice-powered + apps and devices). + overview: |- + [Dialogflow](http://dialogflow.com/) is a natural language + understanding platform that makes it easy for you to design and integrate + a conversational user interface into your mobile app, web application, + device, bot, and so on. Using Dialogflow you can provide users new and + engaging ways to interact with your product using both voice recognition + and text input. + + For information on how Dialogflow agents, intents, entities, and so on + work, see the [Dialogflow getting + started + guide](https://dialogflow.com/docs/getting-started/basics) in the + dialogflow.com documentation. + + ## Dialogflow Editions + + Dialogflow is available in two editions: Standard and Enterprise. For + information on the difference in Dialogflow editions, see [Dialogflow + Editions](https://cloud.google.com/dialogflow-enterprise/docs/editions). + + ## The Dialogflow API + + The Dialogflow API provides a REST and gRPC API that you can use to + incorporate the Dialogflow into your product. After you have created a + Google Cloud project and a Dialogflow agent, you can use the API to create + intents, entities, and so on, and then pass user input to your Dialogflow + agent to determine user intent using + the + [detectIntent](https://cloud.google.com/dialogflow-enterprise/docs/reference/rest/v2beta1/projects.agent.sessions/detectIntent) REST + API, or the + [StreamingDetectIntentRequest](https://cloud.google.com/dialogflow-enterprise/docs/reference/rpc/google.cloud.dialogflow.v2beta1#google.cloud.dialogflow.v2beta1.StreamingDetectIntentRequest) gRPC + API. + + ## Getting Started + + * For information on setting up a Google Cloud Platform project and + creating an agent using the Dialogflow Enterprise Edition, see + [Quickstart](https://cloud.google.com/dialogflow-enterprise/docs/quickstart). * + For information on creating an agent using the Dialogflow Standard + Edition, see [Building Your First + Agent](https://dialogflow.com/docs/getting-started/building-your-first-agent) + +backend: + rules: + - selector: 'google.cloud.dialogflow.v2beta1.Agents.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2beta1.Contexts.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2beta1.Documents.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2beta1.EntityTypes.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2beta1.Intents.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2beta1.KnowledgeBases.*' + deadline: 60.0 + - selector: 'google.cloud.dialogflow.v2beta1.SessionEntityTypes.*' + deadline: 60.0 + - selector: google.cloud.dialogflow.v2beta1.Sessions.DetectIntent + deadline: 230.0 + - selector: google.cloud.dialogflow.v2beta1.Sessions.StreamingDetectIntent + deadline: 230.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 60.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 60.0 + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v2beta1/{name=projects/*/operations/*}' + +authentication: + rules: + - selector: 'google.cloud.dialogflow.v2beta1.Agents.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2beta1.Contexts.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2beta1.Documents.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2beta1.EntityTypes.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2beta1.Intents.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2beta1.KnowledgeBases.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.v2beta1.SessionEntityTypes.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.cloud.dialogflow.v2beta1.Sessions.DetectIntent + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.cloud.dialogflow.v2beta1.Sessions.StreamingDetectIntent + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.longrunning.Operations.GetOperation + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow + - selector: google.longrunning.Operations.WaitOperation + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow diff --git a/google/cloud/dialogflow/v2/BUILD.bazel b/google/cloud/dialogflow/v2/BUILD.bazel new file mode 100644 index 000000000..df2ea23fd --- /dev/null +++ b/google/cloud/dialogflow/v2/BUILD.bazel @@ -0,0 +1,164 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "dialogflow_proto", + srcs = [ + "agent.proto", + "context.proto", + "entity_type.proto", + "intent.proto", + "session.proto", + "session_entity_type.proto", + "webhook.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "//google/type:latlng_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:struct_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "dialogflow_proto_with_info", + deps = [":dialogflow_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "dialogflow_java_proto", + deps = [":dialogflow_proto"], +) + +java_grpc_library( + name = "dialogflow_java_grpc", + srcs = [":dialogflow_proto"], + deps = [":dialogflow_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "dialogflow_resource_name_java_proto", + gapic_yaml = "dialogflow_gapic.yaml", + deps = [":dialogflow_proto"], +) + +java_gapic_library( + name = "dialogflow_java_gapic", + src = ":dialogflow_proto_with_info", + gapic_yaml = "dialogflow_gapic.yaml", + service_yaml = "//google/cloud/dialogflow:dialogflow_v2.yaml", + test_deps = [":dialogflow_java_grpc"], + deps = [ + ":dialogflow_java_proto", + ":dialogflow_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":dialogflow_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.dialogflow.v2.AgentsClientTest", + "com.google.cloud.dialogflow.v2.ContextsClientTest", + "com.google.cloud.dialogflow.v2.EntityTypesClientTest", + "com.google.cloud.dialogflow.v2.IntentsClientTest", + "com.google.cloud.dialogflow.v2.SessionEntityTypesClientTest", + "com.google.cloud.dialogflow.v2.SessionsClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-dialogflow-v2-java", + client_deps = [":dialogflow_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":dialogflow_java_gapic_test"], + grpc_deps = [":dialogflow_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":dialogflow_java_proto", + ":dialogflow_proto", + ":dialogflow_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "dialogflow_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2", + protos = [":dialogflow_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + "//google/type:latlng_go_proto", + ], +) + +go_gapic_library( + name = "dialogflow_go_gapic", + src = ":dialogflow_proto_with_info", + gapic_yaml = "dialogflow_gapic.yaml", + importpath = "cloud.google.com/go/dialogflow/apiv2", + service_yaml = "//google/cloud/dialogflow:dialogflow_v2.yaml", + deps = [ + ":dialogflow_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + "@io_bazel_rules_go//proto/wkt:struct_go_proto", + ], +) + +go_test( + name = "dialogflow_go_gapic_test", + srcs = [":dialogflow_go_gapic_srcjar_test"], + embed = [":dialogflow_go_gapic"], + importpath = "cloud.google.com/go/dialogflow/apiv2", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-dialogflow-v2-go", + deps = [ + ":dialogflow_go_gapic", + ":dialogflow_go_gapic_srcjar-smoke-test.srcjar", + ":dialogflow_go_gapic_srcjar-test.srcjar", + ":dialogflow_go_proto", + ], +) diff --git a/google/cloud/dialogflow/v2/agent.proto b/google/cloud/dialogflow/v2/agent.proto new file mode 100644 index 000000000..a0c7c0d0f --- /dev/null +++ b/google/cloud/dialogflow/v2/agent.proto @@ -0,0 +1,335 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "AgentProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// Agents are best described as Natural Language Understanding (NLU) modules +// that transform user requests into actionable data. You can include agents +// in your app, product, or service to determine user intent and respond to the +// user in a natural way. +// +// After you create an agent, you can add [Intents][google.cloud.dialogflow.v2.Intents], [Contexts][google.cloud.dialogflow.v2.Contexts], +// [Entity Types][google.cloud.dialogflow.v2.EntityTypes], [Webhooks][google.cloud.dialogflow.v2.WebhookRequest], and so on to +// manage the flow of a conversation and match user input to predefined intents +// and actions. +// +// You can create an agent using both Dialogflow Standard Edition and +// Dialogflow Enterprise Edition. For details, see +// [Dialogflow +// Editions](https://cloud.google.com/dialogflow-enterprise/docs/editions). +// +// You can save your agent for backup or versioning by exporting the agent by +// using the [ExportAgent][google.cloud.dialogflow.v2.Agents.ExportAgent] method. You can import a saved +// agent by using the [ImportAgent][google.cloud.dialogflow.v2.Agents.ImportAgent] method. +// +// Dialogflow provides several +// [prebuilt +// agents](https://cloud.google.com/dialogflow-enterprise/docs/agents-prebuilt) +// for common conversation scenarios such as determining a date and time, +// converting currency, and so on. +// +// For more information about agents, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/agents-overview). +service Agents { + // Retrieves the specified agent. + rpc GetAgent(GetAgentRequest) returns (Agent) { + option (google.api.http) = { + get: "/v2/{parent=projects/*}/agent" + }; + } + + // Returns the list of agents. + // + // Since there is at most one conversational agent per project, this method is + // useful primarily for listing all agents across projects the caller has + // access to. One can achieve that with a wildcard project collection id "-". + // Refer to [List + // Sub-Collections](https://cloud.google.com/apis/design/design_patterns#list_sub-collections). + rpc SearchAgents(SearchAgentsRequest) returns (SearchAgentsResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*}/agent:search" + }; + } + + // Trains the specified agent. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc TrainAgent(TrainAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*}/agent:train" + body: "*" + }; + } + + // Exports the specified agent to a ZIP file. + // + // Operation <response: [ExportAgentResponse][google.cloud.dialogflow.v2.ExportAgentResponse]> + rpc ExportAgent(ExportAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*}/agent:export" + body: "*" + }; + } + + // Imports the specified agent from a ZIP file. + // + // Uploads new intents and entity types without deleting the existing ones. + // Intents and entity types with the same name are replaced with the new + // versions from ImportAgentRequest. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc ImportAgent(ImportAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*}/agent:import" + body: "*" + }; + } + + // Restores the specified agent from a ZIP file. + // + // Replaces the current agent version with a new one. All the intents and + // entity types in the older version are deleted. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc RestoreAgent(RestoreAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*}/agent:restore" + body: "*" + }; + } +} + +// Represents a conversational agent. +message Agent { + // Match mode determines how intents are detected from user queries. + enum MatchMode { + // Not specified. + MATCH_MODE_UNSPECIFIED = 0; + + // Best for agents with a small number of examples in intents and/or wide + // use of templates syntax and composite entities. + MATCH_MODE_HYBRID = 1; + + // Can be used for agents with a large number of examples in intents, + // especially the ones using @sys.any or very large developer entities. + MATCH_MODE_ML_ONLY = 2; + } + + // Required. The project of this agent. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Required. The name of this agent. + string display_name = 2; + + // Required. The default language of the agent as a language tag. See + // [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. This field cannot be + // set by the `Update` method. + string default_language_code = 3; + + // Optional. The list of all languages supported by this agent (except for the + // `default_language_code`). + repeated string supported_language_codes = 4; + + // Required. The time zone of this agent from the + // [time zone database](https://www.iana.org/time-zones), e.g., + // America/New_York, Europe/Paris. + string time_zone = 5; + + // Optional. The description of this agent. + // The maximum length is 500 characters. If exceeded, the request is rejected. + string description = 6; + + // Optional. The URI of the agent's avatar. + // Avatars are used throughout the Dialogflow console and in the self-hosted + // [Web + // Demo](https://cloud.google.com/dialogflow-enterprise/docs/integrations/web-demo) + // integration. + string avatar_uri = 7; + + // Optional. Determines whether this agent should log conversation queries. + bool enable_logging = 8; + + // Optional. Determines how intents are detected from user queries. + MatchMode match_mode = 9; + + // Optional. To filter out false positive results and still get variety in + // matched natural language inputs for your agent, you can tune the machine + // learning classification threshold. If the returned score value is less than + // the threshold value, then a fallback intent will be triggered or, if there + // are no fallback intents defined, no intent will be triggered. The score + // values range from 0.0 (completely uncertain) to 1.0 (completely certain). + // If set to 0.0, the default of 0.3 is used. + float classification_threshold = 10; +} + +// The request message for [Agents.GetAgent][google.cloud.dialogflow.v2.Agents.GetAgent]. +message GetAgentRequest { + // Required. The project that the agent to fetch is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; +} + +// The request message for [Agents.SearchAgents][google.cloud.dialogflow.v2.Agents.SearchAgents]. +message SearchAgentsRequest { + // Required. The project to list agents from. + // Format: `projects/<Project ID or '-'>`. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// The response message for [Agents.SearchAgents][google.cloud.dialogflow.v2.Agents.SearchAgents]. +message SearchAgentsResponse { + // The list of agents. There will be a maximum number of items returned based + // on the page_size field in the request. + repeated Agent agents = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [Agents.TrainAgent][google.cloud.dialogflow.v2.Agents.TrainAgent]. +message TrainAgentRequest { + // Required. The project that the agent to train is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; +} + +// The request message for [Agents.ExportAgent][google.cloud.dialogflow.v2.Agents.ExportAgent]. +message ExportAgentRequest { + // Required. The project that the agent to export is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Optional. The + // [Google Cloud Storage](https://cloud.google.com/storage/docs/) + // URI to export the agent to. + // The format of this URI must be `gs://<bucket-name>/<object-name>`. + // If left unspecified, the serialized agent is returned inline. + string agent_uri = 2; +} + +// The response message for [Agents.ExportAgent][google.cloud.dialogflow.v2.Agents.ExportAgent]. +message ExportAgentResponse { + // Required. The exported agent. + oneof agent { + // The URI to a file containing the exported agent. This field is populated + // only if `agent_uri` is specified in `ExportAgentRequest`. + string agent_uri = 1; + + // The exported agent. + // + // Example for how to export an agent to a zip file via a command line: + // <pre>curl \ + // 'https://dialogflow.googleapis.com/v2/projects/<project_name>/agent:export'\ + // -X POST \ + // -H 'Authorization: Bearer '$(gcloud auth application-default + // print-access-token) \ + // -H 'Accept: application/json' \ + // -H 'Content-Type: application/json' \ + // --compressed \ + // --data-binary '{}' \ + // | grep agentContent | sed -e 's/.*"agentContent": "\([^"]*\)".*/\1/' \ + // | base64 --decode > <agent zip file></pre> + bytes agent_content = 2; + } +} + +// The request message for [Agents.ImportAgent][google.cloud.dialogflow.v2.Agents.ImportAgent]. +message ImportAgentRequest { + // Required. The project that the agent to import is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Required. The agent to import. + oneof agent { + // The URI to a Google Cloud Storage file containing the agent to import. + // Note: The URI must start with "gs://". + string agent_uri = 2; + + // The agent to import. + // + // Example for how to import an agent via the command line: + // <pre>curl \ + // 'https://dialogflow.googleapis.com/v2/projects/<project_name>/agent:import\ + // -X POST \ + // -H 'Authorization: Bearer '$(gcloud auth application-default + // print-access-token) \ + // -H 'Accept: application/json' \ + // -H 'Content-Type: application/json' \ + // --compressed \ + // --data-binary "{ + // 'agentContent': '$(cat <agent zip file> | base64 -w 0)' + // }"</pre> + bytes agent_content = 3; + } +} + +// The request message for [Agents.RestoreAgent][google.cloud.dialogflow.v2.Agents.RestoreAgent]. +message RestoreAgentRequest { + // Required. The project that the agent to restore is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Required. The agent to restore. + oneof agent { + // The URI to a Google Cloud Storage file containing the agent to restore. + // Note: The URI must start with "gs://". + string agent_uri = 2; + + // The agent to restore. + // + // Example for how to restore an agent via the command line: + // <pre>curl \ + // 'https://dialogflow.googleapis.com/v2/projects/<project_name>/agent:restore\ + // -X POST \ + // -H 'Authorization: Bearer '$(gcloud auth application-default + // print-access-token) \ + // -H 'Accept: application/json' \ + // -H 'Content-Type: application/json' \ + // --compressed \ + // --data-binary "{ + // 'agentContent': '$(cat <agent zip file> | base64 -w 0)' + // }"</pre> + bytes agent_content = 3; + } +} diff --git a/google/cloud/dialogflow/v2/audio_config.proto b/google/cloud/dialogflow/v2/audio_config.proto new file mode 100644 index 000000000..d3ae64e9f --- /dev/null +++ b/google/cloud/dialogflow/v2/audio_config.proto @@ -0,0 +1,126 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "AudioConfigProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// Gender of the voice as described in +// [SSML voice element](https://www.w3.org/TR/speech-synthesis11/#edef_voice). +enum SsmlVoiceGender { + // An unspecified gender, which means that the client doesn't care which + // gender the selected voice will have. + SSML_VOICE_GENDER_UNSPECIFIED = 0; + + // A male voice. + SSML_VOICE_GENDER_MALE = 1; + + // A female voice. + SSML_VOICE_GENDER_FEMALE = 2; + + // A gender-neutral voice. + SSML_VOICE_GENDER_NEUTRAL = 3; +} + +// Description of which voice to use for speech synthesis. +message VoiceSelectionParams { + // Optional. The name of the voice. If not set, the service will choose a + // voice based on the other parameters such as language_code and gender. + string name = 1; + + // Optional. The preferred gender of the voice. If not set, the service will + // choose a voice based on the other parameters such as language_code and + // name. Note that this is only a preference, not requirement. If a + // voice of the appropriate gender is not available, the synthesizer should + // substitute a voice with a different gender rather than failing the request. + SsmlVoiceGender ssml_gender = 2; +} + +// Configuration of how speech should be synthesized. +message SynthesizeSpeechConfig { + // Optional. Speaking rate/speed, in the range [0.25, 4.0]. 1.0 is the normal + // native speed supported by the specific voice. 2.0 is twice as fast, and + // 0.5 is half as fast. If unset(0.0), defaults to the native 1.0 speed. Any + // other values < 0.25 or > 4.0 will return an error. + double speaking_rate = 1; + + // Optional. Speaking pitch, in the range [-20.0, 20.0]. 20 means increase 20 + // semitones from the original pitch. -20 means decrease 20 semitones from the + // original pitch. + double pitch = 2; + + // Optional. Volume gain (in dB) of the normal native volume supported by the + // specific voice, in the range [-96.0, 16.0]. If unset, or set to a value of + // 0.0 (dB), will play at normal native signal amplitude. A value of -6.0 (dB) + // will play at approximately half the amplitude of the normal native signal + // amplitude. A value of +6.0 (dB) will play at approximately twice the + // amplitude of the normal native signal amplitude. We strongly recommend not + // to exceed +10 (dB) as there's usually no effective increase in loudness for + // any value greater than that. + double volume_gain_db = 3; + + // Optional. An identifier which selects 'audio effects' profiles that are + // applied on (post synthesized) text to speech. Effects are applied on top of + // each other in the order they are given. + repeated string effects_profile_id = 5; + + // Optional. The desired voice of the synthesized audio. + VoiceSelectionParams voice = 4; +} + +// Audio encoding of the output audio format in Text-To-Speech. +enum OutputAudioEncoding { + // Not specified. + OUTPUT_AUDIO_ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + // Audio content returned as LINEAR16 also contains a WAV header. + OUTPUT_AUDIO_ENCODING_LINEAR_16 = 1; + + // MP3 audio. + OUTPUT_AUDIO_ENCODING_MP3 = 2; + + // Opus encoded audio wrapped in an ogg container. The result will be a + // file which can be played natively on Android, and in browsers (at least + // Chrome and Firefox). The quality of the encoding is considerably higher + // than MP3 while using approximately the same bitrate. + OUTPUT_AUDIO_ENCODING_OGG_OPUS = 3; +} + +// Instructs the speech synthesizer how to generate the output audio content. +message OutputAudioConfig { + // Required. Audio encoding of the synthesized audio content. + OutputAudioEncoding audio_encoding = 1; + + // Optional. The synthesis sample rate (in hertz) for this audio. If not + // provided, then the synthesizer will use the default sample rate based on + // the audio encoding. If this is different from the voice's natural sample + // rate, then the synthesizer will honor this request by converting to the + // desired sample rate (which might result in worse audio quality). + int32 sample_rate_hertz = 2; + + // Optional. Configuration of how speech should be synthesized. + SynthesizeSpeechConfig synthesize_speech_config = 3; +} diff --git a/google/cloud/dialogflow/v2/context.proto b/google/cloud/dialogflow/v2/context.proto new file mode 100644 index 000000000..3c870e32b --- /dev/null +++ b/google/cloud/dialogflow/v2/context.proto @@ -0,0 +1,185 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "ContextProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// A context represents additional information included with user input or with +// an intent returned by the Dialogflow API. Contexts are helpful for +// differentiating user input which may be vague or have a different meaning +// depending on additional details from your application such as user setting +// and preferences, previous user input, where the user is in your application, +// geographic location, and so on. +// +// You can include contexts as input parameters of a +// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or +// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) request, +// or as output contexts included in the returned intent. +// Contexts expire when an intent is matched, after the number of `DetectIntent` +// requests specified by the `lifespan_count` parameter, or after 20 minutes +// if no intents are matched for a `DetectIntent` request. +// +// For more information about contexts, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/contexts-overview). +service Contexts { + // Returns the list of all contexts in the specified session. + rpc ListContexts(ListContextsRequest) returns (ListContextsResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/agent/sessions/*}/contexts" + }; + } + + // Retrieves the specified context. + rpc GetContext(GetContextRequest) returns (Context) { + option (google.api.http) = { + get: "/v2/{name=projects/*/agent/sessions/*/contexts/*}" + }; + } + + // Creates a context. + // + // If the specified context already exists, overrides the context. + rpc CreateContext(CreateContextRequest) returns (Context) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent/sessions/*}/contexts" + body: "context" + }; + } + + // Updates the specified context. + rpc UpdateContext(UpdateContextRequest) returns (Context) { + option (google.api.http) = { + patch: "/v2/{context.name=projects/*/agent/sessions/*/contexts/*}" + body: "context" + }; + } + + // Deletes the specified context. + rpc DeleteContext(DeleteContextRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/agent/sessions/*/contexts/*}" + }; + } + + // Deletes all active contexts in the specified session. + rpc DeleteAllContexts(DeleteAllContextsRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{parent=projects/*/agent/sessions/*}/contexts" + }; + } +} + +// Represents a context. +message Context { + // Required. The unique identifier of the context. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>`. + // + // The `Context ID` is always converted to lowercase, may only contain + // characters in [a-zA-Z0-9_-%] and may be at most 250 bytes long. + string name = 1; + + // Optional. The number of conversational query requests after which the + // context expires. If set to `0` (the default) the context expires + // immediately. Contexts expire automatically after 20 minutes if there + // are no matching queries. + int32 lifespan_count = 2; + + // Optional. The collection of parameters associated with this context. + // Refer to [this + // doc](https://cloud.google.com/dialogflow-enterprise/docs/intents-actions-parameters) + // for syntax. + google.protobuf.Struct parameters = 3; +} + +// The request message for [Contexts.ListContexts][google.cloud.dialogflow.v2.Contexts.ListContexts]. +message ListContextsRequest { + // Required. The session to list all contexts from. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>`. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// The response message for [Contexts.ListContexts][google.cloud.dialogflow.v2.Contexts.ListContexts]. +message ListContextsResponse { + // The list of contexts. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated Context contexts = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [Contexts.GetContext][google.cloud.dialogflow.v2.Contexts.GetContext]. +message GetContextRequest { + // Required. The name of the context. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>`. + string name = 1; +} + +// The request message for [Contexts.CreateContext][google.cloud.dialogflow.v2.Contexts.CreateContext]. +message CreateContextRequest { + // Required. The session to create a context for. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>`. + string parent = 1; + + // Required. The context to create. + Context context = 2; +} + +// The request message for [Contexts.UpdateContext][google.cloud.dialogflow.v2.Contexts.UpdateContext]. +message UpdateContextRequest { + // Required. The context to update. + Context context = 1; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 2; +} + +// The request message for [Contexts.DeleteContext][google.cloud.dialogflow.v2.Contexts.DeleteContext]. +message DeleteContextRequest { + // Required. The name of the context to delete. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>`. + string name = 1; +} + +// The request message for [Contexts.DeleteAllContexts][google.cloud.dialogflow.v2.Contexts.DeleteAllContexts]. +message DeleteAllContextsRequest { + // Required. The name of the session to delete all contexts from. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>`. + string parent = 1; +} diff --git a/google/cloud/dialogflow/v2/dialogflow_gapic.yaml b/google/cloud/dialogflow/v2/dialogflow_gapic.yaml new file mode 100644 index 000000000..61edb1959 --- /dev/null +++ b/google/cloud/dialogflow/v2/dialogflow_gapic.yaml @@ -0,0 +1,1227 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.dialogflow.v2 + python: + package_name: google.cloud.dialogflow_v2.gapic + go: + package_name: cloud.google.com/go/dialogflow/apiv2 + csharp: + package_name: Google.Cloud.Dialogflow.V2 + ruby: + package_name: Google::Cloud::Dialogflow::V2 + php: + package_name: Google\Cloud\Dialogflow\V2 + nodejs: + package_name: dialogflow.v2 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2.Agents + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: GetAgent + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: SearchAgents + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: agents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: TrainAgent + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(train_agent_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: ExportAgent + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(export_agent_long_running_operation) + return_type: google.cloud.dialogflow.v2.ExportAgentResponse + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: ImportAgent + required_fields: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(import_agent_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: RestoreAgent + + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(restore_agent_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2.Contexts + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent/sessions/{session} + entity_name: session + - name_pattern: projects/{project}/agent/sessions/{session}/contexts/{context} + entity_name: context + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListContexts + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: contexts + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetContext + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: context + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateContext + flattening: + groups: + - parameters: + - parent + - context + required_fields: + - parent + - context + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateContext + flattening: + groups: + - parameters: + - context + required_fields: + - context + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + context.name: context + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteContext + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: context + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteAllContexts + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2.EntityTypes + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent + entity_name: project_agent + - name_pattern: projects/{project}/agent/entityTypes/{entity_type} + entity_name: entity_type + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListEntityTypes + flattening: + groups: + - parameters: + - parent + - parameters: + - parent + - language_code + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: entity_types + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetEntityType + flattening: + groups: + - parameters: + - name + - parameters: + - name + - language_code + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateEntityType + flattening: + groups: + - parameters: + - parent + - entity_type + - parameters: + - parent + - entity_type + - language_code + required_fields: + - parent + - entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateEntityType + flattening: + groups: + - parameters: + - entity_type + - parameters: + - entity_type + - language_code + required_fields: + - entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + entity_type.name: entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteEntityType + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: BatchUpdateEntityTypes + required_fields: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_update_entity_types_long_running_operation) + return_type: google.cloud.dialogflow.v2.BatchUpdateEntityTypesResponse + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchDeleteEntityTypes + flattening: + groups: + - parameters: + - parent + - entity_type_names + required_fields: + - parent + - entity_type_names + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_delete_entity_types_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchCreateEntities + flattening: + groups: + - parameters: + - parent + - entities + - parameters: + - parent + - entities + - language_code + required_fields: + - parent + - entities + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: entity_type + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_create_entities_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchUpdateEntities + flattening: + groups: + - parameters: + - parent + - entities + - parameters: + - parent + - entities + - language_code + required_fields: + - parent + - entities + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: entity_type + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_update_entities_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchDeleteEntities + flattening: + groups: + - parameters: + - parent + - entity_values + - parameters: + - parent + - entity_values + - language_code + required_fields: + - parent + - entity_values + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: entity_type + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_delete_entities_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2.Intents + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent + entity_name: project_agent + - name_pattern: projects/{project}/agent/intents/{intent} + entity_name: intent + - name_pattern: projects/{project}/agents/{agent} + entity_name: agent + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListIntents + flattening: + groups: + - parameters: + - parent + - parameters: + - parent + - language_code + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: intents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetIntent + flattening: + groups: + - parameters: + - name + - parameters: + - name + - language_code + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: intent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateIntent + flattening: + groups: + - parameters: + - parent + - intent + - parameters: + - parent + - intent + - language_code + required_fields: + - parent + - intent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateIntent + flattening: + groups: + - parameters: + - intent + - language_code + - parameters: + - intent + - language_code + - update_mask + required_fields: + - intent + - language_code + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + intent.name: intent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteIntent + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: intent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: BatchUpdateIntents + required_fields: + - parent + - language_code + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_update_intents_long_running_operation) + return_type: google.cloud.dialogflow.v2.BatchUpdateIntentsResponse + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchDeleteIntents + flattening: + groups: + - parameters: + - parent + - intents + required_fields: + - parent + - intents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_delete_intents_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2.SessionEntityTypes + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent/sessions/{session} + entity_name: session + - name_pattern: projects/{project}/agent/sessions/{session}/entityTypes/{entity_type} + entity_name: session_entity_type + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListSessionEntityTypes + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: session_entity_types + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetSessionEntityType + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: session_entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateSessionEntityType + flattening: + groups: + - parameters: + - parent + - session_entity_type + required_fields: + - parent + - session_entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateSessionEntityType + flattening: + groups: + - parameters: + - session_entity_type + required_fields: + - session_entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + session_entity_type.name: session_entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteSessionEntityType + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: session_entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2.Sessions + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent/sessions/{session} + entity_name: session + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: DetectIntent + flattening: + groups: + - parameters: + - session + - query_input + required_fields: + - session + - query_input + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + session: session + timeout_millis: 220000 + resource_name_treatment: STATIC_TYPES + - name: StreamingDetectIntent + required_fields: + - session + - query_input + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 220000 +resource_name_generation: +- message_name: GetAgentRequest + field_entity_map: + parent: project +- message_name: SearchAgentsRequest + field_entity_map: + parent: project +- message_name: TrainAgentRequest + field_entity_map: + parent: project +- message_name: ExportAgentRequest + field_entity_map: + parent: project +- message_name: ImportAgentRequest + field_entity_map: + parent: project +- message_name: RestoreAgentRequest + field_entity_map: + parent: project +- message_name: ListContextsRequest + field_entity_map: + parent: session +- message_name: GetContextRequest + field_entity_map: + name: context +- message_name: CreateContextRequest + field_entity_map: + parent: session +- message_name: Context + field_entity_map: + name: context +- message_name: DeleteContextRequest + field_entity_map: + name: context +- message_name: DeleteAllContextsRequest + field_entity_map: + parent: session +- message_name: ListEntityTypesRequest + field_entity_map: + parent: project_agent +- message_name: GetEntityTypeRequest + field_entity_map: + name: entity_type +- message_name: CreateEntityTypeRequest + field_entity_map: + parent: project_agent +- message_name: EntityType + field_entity_map: + name: entity_type +- message_name: DeleteEntityTypeRequest + field_entity_map: + name: entity_type +- message_name: BatchUpdateEntityTypesRequest + field_entity_map: + parent: project_agent +- message_name: BatchDeleteEntityTypesRequest + field_entity_map: + parent: project_agent +- message_name: BatchCreateEntitiesRequest + field_entity_map: + parent: entity_type +- message_name: BatchUpdateEntitiesRequest + field_entity_map: + parent: entity_type +- message_name: BatchDeleteEntitiesRequest + field_entity_map: + parent: entity_type +- message_name: ListIntentsRequest + field_entity_map: + parent: project_agent +- message_name: GetIntentRequest + field_entity_map: + name: intent +- message_name: CreateIntentRequest + field_entity_map: + parent: project_agent +- message_name: Intent + field_entity_map: + name: intent +- message_name: DeleteIntentRequest + field_entity_map: + name: intent +- message_name: BatchUpdateIntentsRequest + field_entity_map: + parent: project_agent +- message_name: BatchDeleteIntentsRequest + field_entity_map: + parent: project_agent +- message_name: ListSessionEntityTypesRequest + field_entity_map: + parent: session +- message_name: GetSessionEntityTypeRequest + field_entity_map: + name: session_entity_type +- message_name: CreateSessionEntityTypeRequest + field_entity_map: + parent: session +- message_name: SessionEntityType + field_entity_map: + name: session_entity_type +- message_name: DeleteSessionEntityTypeRequest + field_entity_map: + name: session_entity_type +- message_name: DetectIntentRequest + field_entity_map: + session: session diff --git a/google/cloud/dialogflow/v2/entity_type.proto b/google/cloud/dialogflow/v2/entity_type.proto new file mode 100644 index 000000000..ea24d9d1b --- /dev/null +++ b/google/cloud/dialogflow/v2/entity_type.proto @@ -0,0 +1,436 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "EntityTypeProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// Entities are extracted from user input and represent parameters that are +// meaningful to your application. For example, a date range, a proper name +// such as a geographic location or landmark, and so on. Entities represent +// actionable data for your application. +// +// When you define an entity, you can also include synonyms that all map to +// that entity. For example, "soft drink", "soda", "pop", and so on. +// +// There are three types of entities: +// +// * **System** - entities that are defined by the Dialogflow API for common +// data types such as date, time, currency, and so on. A system entity is +// represented by the `EntityType` type. +// +// * **Developer** - entities that are defined by you that represent +// actionable data that is meaningful to your application. For example, +// you could define a `pizza.sauce` entity for red or white pizza sauce, +// a `pizza.cheese` entity for the different types of cheese on a pizza, +// a `pizza.topping` entity for different toppings, and so on. A developer +// entity is represented by the `EntityType` type. +// +// * **User** - entities that are built for an individual user such as +// favorites, preferences, playlists, and so on. A user entity is +// represented by the [SessionEntityType][google.cloud.dialogflow.v2.SessionEntityType] type. +// +// For more information about entity types, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/entities-overview). +service EntityTypes { + // Returns the list of all entity types in the specified agent. + rpc ListEntityTypes(ListEntityTypesRequest) returns (ListEntityTypesResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/agent}/entityTypes" + }; + } + + // Retrieves the specified entity type. + rpc GetEntityType(GetEntityTypeRequest) returns (EntityType) { + option (google.api.http) = { + get: "/v2/{name=projects/*/agent/entityTypes/*}" + }; + } + + // Creates an entity type in the specified agent. + rpc CreateEntityType(CreateEntityTypeRequest) returns (EntityType) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent}/entityTypes" + body: "entity_type" + }; + } + + // Updates the specified entity type. + rpc UpdateEntityType(UpdateEntityTypeRequest) returns (EntityType) { + option (google.api.http) = { + patch: "/v2/{entity_type.name=projects/*/agent/entityTypes/*}" + body: "entity_type" + }; + } + + // Deletes the specified entity type. + rpc DeleteEntityType(DeleteEntityTypeRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/agent/entityTypes/*}" + }; + } + + // Updates/Creates multiple entity types in the specified agent. + // + // Operation <response: [BatchUpdateEntityTypesResponse][google.cloud.dialogflow.v2.BatchUpdateEntityTypesResponse]> + rpc BatchUpdateEntityTypes(BatchUpdateEntityTypesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent}/entityTypes:batchUpdate" + body: "*" + }; + } + + // Deletes entity types in the specified agent. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchDeleteEntityTypes(BatchDeleteEntityTypesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent}/entityTypes:batchDelete" + body: "*" + }; + } + + // Creates multiple new entities in the specified entity type. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchCreateEntities(BatchCreateEntitiesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchCreate" + body: "*" + }; + } + + // Updates or creates multiple entities in the specified entity type. This + // method does not affect entities in the entity type that aren't explicitly + // specified in the request. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchUpdateEntities(BatchUpdateEntitiesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchUpdate" + body: "*" + }; + } + + // Deletes entities in the specified entity type. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchDeleteEntities(BatchDeleteEntitiesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchDelete" + body: "*" + }; + } +} + +// Represents an entity type. +// Entity types serve as a tool for extracting parameter values from natural +// language queries. +message EntityType { + // An **entity entry** for an associated entity type. + message Entity { + // Required. The primary value associated with this entity entry. + // For example, if the entity type is *vegetable*, the value could be + // *scallions*. + // + // For `KIND_MAP` entity types: + // + // * A canonical value to be used in place of synonyms. + // + // For `KIND_LIST` entity types: + // + // * A string that can contain references to other entity types (with or + // without aliases). + string value = 1; + + // Required. A collection of value synonyms. For example, if the entity type + // is *vegetable*, and `value` is *scallions*, a synonym could be *green + // onions*. + // + // For `KIND_LIST` entity types: + // + // * This collection must contain exactly one synonym equal to `value`. + repeated string synonyms = 2; + } + + // Represents kinds of entities. + enum Kind { + // Not specified. This value should be never used. + KIND_UNSPECIFIED = 0; + + // Map entity types allow mapping of a group of synonyms to a canonical + // value. + KIND_MAP = 1; + + // List entity types contain a set of entries that do not map to canonical + // values. However, list entity types can contain references to other entity + // types (with or without aliases). + KIND_LIST = 2; + } + + // Represents different entity type expansion modes. Automated expansion + // allows an agent to recognize values that have not been explicitly listed in + // the entity (for example, new kinds of shopping list items). + enum AutoExpansionMode { + // Auto expansion disabled for the entity. + AUTO_EXPANSION_MODE_UNSPECIFIED = 0; + + // Allows an agent to recognize values that have not been explicitly + // listed in the entity. + AUTO_EXPANSION_MODE_DEFAULT = 1; + } + + // The unique identifier of the entity type. + // Required for [EntityTypes.UpdateEntityType][google.cloud.dialogflow.v2.EntityTypes.UpdateEntityType] and + // [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntityTypes] methods. + // Format: `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string name = 1; + + // Required. The name of the entity type. + string display_name = 2; + + // Required. Indicates the kind of entity type. + Kind kind = 3; + + // Optional. Indicates whether the entity type can be automatically + // expanded. + AutoExpansionMode auto_expansion_mode = 4; + + // Optional. The collection of entity entries associated with the entity type. + repeated Entity entities = 6; +} + +// The request message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2.EntityTypes.ListEntityTypes]. +message ListEntityTypesRequest { + // Required. The agent to list all entity types from. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Optional. The language to list entity synonyms for. If not specified, + // the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 3; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 4; +} + +// The response message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2.EntityTypes.ListEntityTypes]. +message ListEntityTypesResponse { + // The list of agent entity types. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated EntityType entity_types = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [EntityTypes.GetEntityType][google.cloud.dialogflow.v2.EntityTypes.GetEntityType]. +message GetEntityTypeRequest { + // Required. The name of the entity type. + // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`. + string name = 1; + + // Optional. The language to retrieve entity synonyms for. If not specified, + // the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; +} + +// The request message for [EntityTypes.CreateEntityType][google.cloud.dialogflow.v2.EntityTypes.CreateEntityType]. +message CreateEntityTypeRequest { + // Required. The agent to create a entity type for. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The entity type to create. + EntityType entity_type = 2; + + // Optional. The language of entity synonyms defined in `entity_type`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; +} + +// The request message for [EntityTypes.UpdateEntityType][google.cloud.dialogflow.v2.EntityTypes.UpdateEntityType]. +message UpdateEntityTypeRequest { + // Required. The entity type to update. + EntityType entity_type = 1; + + // Optional. The language of entity synonyms defined in `entity_type`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 3; +} + +// The request message for [EntityTypes.DeleteEntityType][google.cloud.dialogflow.v2.EntityTypes.DeleteEntityType]. +message DeleteEntityTypeRequest { + // Required. The name of the entity type to delete. + // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`. + string name = 1; +} + +// The request message for [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntityTypes]. +message BatchUpdateEntityTypesRequest { + // Required. The name of the agent to update or create entity types in. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The source of the entity type batch. + // + // For each entity type in the batch: + // + // * If `name` is specified, we update an existing entity type. + // * If `name` is not specified, we create a new entity type. + oneof entity_type_batch { + // The URI to a Google Cloud Storage file containing entity types to update + // or create. The file format can either be a serialized proto (of + // EntityBatch type) or a JSON object. Note: The URI must start with + // "gs://". + string entity_type_batch_uri = 2; + + // The collection of entity types to update or create. + EntityTypeBatch entity_type_batch_inline = 3; + } + + // Optional. The language of entity synonyms defined in `entity_types`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 4; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 5; +} + +// The response message for [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntityTypes]. +message BatchUpdateEntityTypesResponse { + // The collection of updated or created entity types. + repeated EntityType entity_types = 1; +} + +// The request message for [EntityTypes.BatchDeleteEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchDeleteEntityTypes]. +message BatchDeleteEntityTypesRequest { + // Required. The name of the agent to delete all entities types for. Format: + // `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The names entity types to delete. All names must point to the + // same agent as `parent`. + repeated string entity_type_names = 2; +} + +// The request message for [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2.EntityTypes.BatchCreateEntities]. +message BatchCreateEntitiesRequest { + // Required. The name of the entity type to create entities in. Format: + // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string parent = 1; + + // Required. The entities to create. + repeated EntityType.Entity entities = 2; + + // Optional. The language of entity synonyms defined in `entities`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; +} + +// The request message for [EntityTypes.BatchUpdateEntities][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntities]. +message BatchUpdateEntitiesRequest { + // Required. The name of the entity type to update or create entities in. + // Format: `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string parent = 1; + + // Required. The entities to update or create. + repeated EntityType.Entity entities = 2; + + // Optional. The language of entity synonyms defined in `entities`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 4; +} + +// The request message for [EntityTypes.BatchDeleteEntities][google.cloud.dialogflow.v2.EntityTypes.BatchDeleteEntities]. +message BatchDeleteEntitiesRequest { + // Required. The name of the entity type to delete entries for. Format: + // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string parent = 1; + + // Required. The canonical `values` of the entities to delete. Note that + // these are not fully-qualified names, i.e. they don't start with + // `projects/<Project ID>`. + repeated string entity_values = 2; + + // Optional. The language of entity synonyms defined in `entities`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; +} + +// This message is a wrapper around a collection of entity types. +message EntityTypeBatch { + // A collection of entity types. + repeated EntityType entity_types = 1; +} diff --git a/google/cloud/dialogflow/v2/intent.proto b/google/cloud/dialogflow/v2/intent.proto new file mode 100644 index 000000000..bd7382fcf --- /dev/null +++ b/google/cloud/dialogflow/v2/intent.proto @@ -0,0 +1,848 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/dialogflow/v2/context.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/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "IntentProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// An intent represents a mapping between input from a user and an action to +// be taken by your application. When you pass user input to the +// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or +// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method, the +// Dialogflow API analyzes the input and searches +// for a matching intent. If no match is found, the Dialogflow API returns a +// fallback intent (`is_fallback` = true). +// +// You can provide additional information for the Dialogflow API to use to +// match user input to an intent by adding the following to your intent. +// +// * **Contexts** - provide additional context for intent analysis. For +// example, if an intent is related to an object in your application that +// plays music, you can provide a context to determine when to match the +// intent if the user input is "turn it off". You can include a context +// that matches the intent when there is previous user input of +// "play music", and not when there is previous user input of +// "turn on the light". +// +// * **Events** - allow for matching an intent by using an event name +// instead of user input. Your application can provide an event name and +// related parameters to the Dialogflow API to match an intent. For +// example, when your application starts, you can send a welcome event +// with a user name parameter to the Dialogflow API to match an intent with +// a personalized welcome message for the user. +// +// * **Training phrases** - provide examples of user input to train the +// Dialogflow API agent to better match intents. +// +// For more information about intents, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/intents-overview). +service Intents { + // Returns the list of all intents in the specified agent. + rpc ListIntents(ListIntentsRequest) returns (ListIntentsResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/agent}/intents" + }; + } + + // Retrieves the specified intent. + rpc GetIntent(GetIntentRequest) returns (Intent) { + option (google.api.http) = { + get: "/v2/{name=projects/*/agent/intents/*}" + }; + } + + // Creates an intent in the specified agent. + rpc CreateIntent(CreateIntentRequest) returns (Intent) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent}/intents" + body: "intent" + }; + } + + // Updates the specified intent. + rpc UpdateIntent(UpdateIntentRequest) returns (Intent) { + option (google.api.http) = { + patch: "/v2/{intent.name=projects/*/agent/intents/*}" + body: "intent" + }; + } + + // Deletes the specified intent and its direct or indirect followup intents. + rpc DeleteIntent(DeleteIntentRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/agent/intents/*}" + }; + } + + // Updates/Creates multiple intents in the specified agent. + // + // Operation <response: [BatchUpdateIntentsResponse][google.cloud.dialogflow.v2.BatchUpdateIntentsResponse]> + rpc BatchUpdateIntents(BatchUpdateIntentsRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent}/intents:batchUpdate" + body: "*" + }; + } + + // Deletes intents in the specified agent. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchDeleteIntents(BatchDeleteIntentsRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent}/intents:batchDelete" + body: "*" + }; + } +} + +// Represents an intent. +// Intents convert a number of user expressions or patterns into an action. An +// action is an extraction of a user command or sentence semantics. +message Intent { + // Represents an example that the agent is trained on. + message TrainingPhrase { + // Represents a part of a training phrase. + message Part { + // Required. The text for this part. + string text = 1; + + // Optional. The entity type name prefixed with `@`. + // This field is required for annotated parts of the training phrase. + string entity_type = 2; + + // Optional. The parameter name for the value extracted from the + // annotated part of the example. + // This field is required for annotated parts of the training phrase. + string alias = 3; + + // Optional. Indicates whether the text was manually annotated. + // This field is set to true when the Dialogflow Console is used to + // manually annotate the part. When creating an annotated part with the + // API, you must set this to true. + bool user_defined = 4; + } + + // Represents different types of training phrases. + enum Type { + // Not specified. This value should never be used. + TYPE_UNSPECIFIED = 0; + + // Examples do not contain @-prefixed entity type names, but example parts + // can be annotated with entity types. + EXAMPLE = 1; + + // Templates are not annotated with entity types, but they can contain + // @-prefixed entity type names as substrings. + // Template mode has been deprecated. Example mode is the only supported + // way to create new training phrases. If you have existing training + // phrases that you've created in template mode, those will continue to + // work. + TEMPLATE = 2 [deprecated = true]; + } + + // Output only. The unique identifier of this training phrase. + string name = 1; + + // Required. The type of the training phrase. + Type type = 2; + + // Required. The ordered list of training phrase parts. + // The parts are concatenated in order to form the training phrase. + // + // Note: The API does not automatically annotate training phrases like the + // Dialogflow Console does. + // + // Note: Do not forget to include whitespace at part boundaries, + // so the training phrase is well formatted when the parts are concatenated. + // + // If the training phrase does not need to be annotated with parameters, + // you just need a single part with only the [Part.text][google.cloud.dialogflow.v2.Intent.TrainingPhrase.Part.text] field set. + // + // If you want to annotate the training phrase, you must create multiple + // parts, where the fields of each part are populated in one of two ways: + // + // - `Part.text` is set to a part of the phrase that has no parameters. + // - `Part.text` is set to a part of the phrase that you want to annotate, + // and the `entity_type`, `alias`, and `user_defined` fields are all + // set. + repeated Part parts = 3; + + // Optional. Indicates how many times this example was added to + // the intent. Each time a developer adds an existing sample by editing an + // intent or training, this counter is increased. + int32 times_added_count = 4; + } + + // Represents intent parameters. + message Parameter { + // The unique identifier of this parameter. + string name = 1; + + // Required. The name of the parameter. + string display_name = 2; + + // Optional. The definition of the parameter value. It can be: + // - a constant string, + // - a parameter value defined as `$parameter_name`, + // - an original parameter value defined as `$parameter_name.original`, + // - a parameter value from some context defined as + // `#context_name.parameter_name`. + string value = 3; + + // Optional. The default value to use when the `value` yields an empty + // result. + // Default values can be extracted from contexts by using the following + // syntax: `#context_name.parameter_name`. + string default_value = 4; + + // Optional. The name of the entity type, prefixed with `@`, that + // describes values of the parameter. If the parameter is + // required, this must be provided. + string entity_type_display_name = 5; + + // Optional. Indicates whether the parameter is required. That is, + // whether the intent cannot be completed without collecting the parameter + // value. + bool mandatory = 6; + + // Optional. The collection of prompts that the agent can present to the + // user in order to collect value for the parameter. + repeated string prompts = 7; + + // Optional. Indicates whether the parameter represents a list of values. + bool is_list = 8; + } + + // Corresponds to the `Response` field in the Dialogflow console. + message Message { + // The text response message. + message Text { + // Optional. The collection of the agent's responses. + repeated string text = 1; + } + + // The image response message. + message Image { + // Optional. The public URI to an image file. + string image_uri = 1; + + // Optional. A text description of the image to be used for accessibility, + // e.g., screen readers. + string accessibility_text = 2; + } + + // The quick replies response message. + message QuickReplies { + // Optional. The title of the collection of quick replies. + string title = 1; + + // Optional. The collection of quick replies. + repeated string quick_replies = 2; + } + + // The card response message. + message Card { + // Optional. Contains information about a button. + message Button { + // Optional. The text to show on the button. + string text = 1; + + // Optional. The text to send back to the Dialogflow API or a URI to + // open. + string postback = 2; + } + + // Optional. The title of the card. + string title = 1; + + // Optional. The subtitle of the card. + string subtitle = 2; + + // Optional. The public URI to an image file for the card. + string image_uri = 3; + + // Optional. The collection of card buttons. + repeated Button buttons = 4; + } + + // The simple response message containing speech or text. + message SimpleResponse { + // One of text_to_speech or ssml must be provided. The plain text of the + // speech output. Mutually exclusive with ssml. + string text_to_speech = 1; + + // One of text_to_speech or ssml must be provided. Structured spoken + // response to the user in the SSML format. Mutually exclusive with + // text_to_speech. + string ssml = 2; + + // Optional. The text to display. + string display_text = 3; + } + + // The collection of simple response candidates. + // This message in `QueryResult.fulfillment_messages` and + // `WebhookResponse.fulfillment_messages` should contain only one + // `SimpleResponse`. + message SimpleResponses { + // Required. The list of simple responses. + repeated SimpleResponse simple_responses = 1; + } + + // The basic card message. Useful for displaying information. + message BasicCard { + // The button object that appears at the bottom of a card. + message Button { + // Opens the given URI. + message OpenUriAction { + // Required. The HTTP or HTTPS scheme URI. + string uri = 1; + } + + // Required. The title of the button. + string title = 1; + + // Required. Action to take when a user taps on the button. + OpenUriAction open_uri_action = 2; + } + + // Optional. The title of the card. + string title = 1; + + // Optional. The subtitle of the card. + string subtitle = 2; + + // Required, unless image is present. The body text of the card. + string formatted_text = 3; + + // Optional. The image for the card. + Image image = 4; + + // Optional. The collection of card buttons. + repeated Button buttons = 5; + } + + // The suggestion chip message that the user can tap to quickly post a reply + // to the conversation. + message Suggestion { + // Required. The text shown the in the suggestion chip. + string title = 1; + } + + // The collection of suggestions. + message Suggestions { + // Required. The list of suggested replies. + repeated Suggestion suggestions = 1; + } + + // The suggestion chip message that allows the user to jump out to the app + // or website associated with this agent. + message LinkOutSuggestion { + // Required. The name of the app or site this chip is linking to. + string destination_name = 1; + + // Required. The URI of the app or site to open when the user taps the + // suggestion chip. + string uri = 2; + } + + // The card for presenting a list of options to select from. + message ListSelect { + // An item in the list. + message Item { + // Required. Additional information about this option. + SelectItemInfo info = 1; + + // Required. The title of the list item. + string title = 2; + + // Optional. The main text describing the item. + string description = 3; + + // Optional. The image to display. + Image image = 4; + } + + // Optional. The overall title of the list. + string title = 1; + + // Required. List items. + repeated Item items = 2; + } + + // The card for presenting a carousel of options to select from. + message CarouselSelect { + // An item in the carousel. + message Item { + // Required. Additional info about the option item. + SelectItemInfo info = 1; + + // Required. Title of the carousel item. + string title = 2; + + // Optional. The body text of the card. + string description = 3; + + // Optional. The image to display. + Image image = 4; + } + + // Required. Carousel items. + repeated Item items = 1; + } + + // Additional info about the select item for when it is triggered in a + // dialog. + message SelectItemInfo { + // Required. A unique key that will be sent back to the agent if this + // response is given. + string key = 1; + + // Optional. A list of synonyms that can also be used to trigger this + // item in dialog. + repeated string synonyms = 2; + } + + // Represents different platforms that a rich message can be intended for. + enum Platform { + // Not specified. + PLATFORM_UNSPECIFIED = 0; + + // Facebook. + FACEBOOK = 1; + + // Slack. + SLACK = 2; + + // Telegram. + TELEGRAM = 3; + + // Kik. + KIK = 4; + + // Skype. + SKYPE = 5; + + // Line. + LINE = 6; + + // Viber. + VIBER = 7; + + // Actions on Google. + // When using Actions on Google, you can choose one of the specific + // Intent.Message types that mention support for Actions on Google, + // or you can use the advanced Intent.Message.payload field. + // The payload field provides access to AoG features not available in the + // specific message types. + // If using the Intent.Message.payload field, it should have a structure + // similar to the JSON message shown here. For more information, see + // [Actions on Google Webhook + // Format](https://developers.google.com/actions/dialogflow/webhook) + // <pre>{ + // "expectUserResponse": true, + // "isSsml": false, + // "noInputPrompts": [], + // "richResponse": { + // "items": [ + // { + // "simpleResponse": { + // "displayText": "hi", + // "textToSpeech": "hello" + // } + // } + // ], + // "suggestions": [ + // { + // "title": "Say this" + // }, + // { + // "title": "or this" + // } + // ] + // }, + // "systemIntent": { + // "data": { + // "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec", + // "listSelect": { + // "items": [ + // { + // "optionInfo": { + // "key": "key1", + // "synonyms": [ + // "key one" + // ] + // }, + // "title": "must not be empty, but unique" + // }, + // { + // "optionInfo": { + // "key": "key2", + // "synonyms": [ + // "key two" + // ] + // }, + // "title": "must not be empty, but unique" + // } + // ] + // } + // }, + // "intent": "actions.intent.OPTION" + // } + // }</pre> + ACTIONS_ON_GOOGLE = 8; + } + + // Required. The rich response message. + oneof message { + // The text response. + Text text = 1; + + // The image response. + Image image = 2; + + // The quick replies response. + QuickReplies quick_replies = 3; + + // The card response. + Card card = 4; + + // Returns a response containing a custom, platform-specific payload. + // See the Intent.Message.Platform type for a description of the + // structure that may be required for your platform. + google.protobuf.Struct payload = 5; + + // The voice and text-only responses for Actions on Google. + SimpleResponses simple_responses = 7; + + // The basic card response for Actions on Google. + BasicCard basic_card = 8; + + // The suggestion chips for Actions on Google. + Suggestions suggestions = 9; + + // The link out suggestion chip for Actions on Google. + LinkOutSuggestion link_out_suggestion = 10; + + // The list card response for Actions on Google. + ListSelect list_select = 11; + + // The carousel card response for Actions on Google. + CarouselSelect carousel_select = 12; + } + + // Optional. The platform that this message is intended for. + Platform platform = 6; + } + + // Represents a single followup intent in the chain. + message FollowupIntentInfo { + // The unique identifier of the followup intent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string followup_intent_name = 1; + + // The unique identifier of the followup intent's parent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string parent_followup_intent_name = 2; + } + + // Represents the different states that webhooks can be in. + enum WebhookState { + // Webhook is disabled in the agent and in the intent. + WEBHOOK_STATE_UNSPECIFIED = 0; + + // Webhook is enabled in the agent and in the intent. + WEBHOOK_STATE_ENABLED = 1; + + // Webhook is enabled in the agent and in the intent. Also, each slot + // filling prompt is forwarded to the webhook. + WEBHOOK_STATE_ENABLED_FOR_SLOT_FILLING = 2; + } + + // The unique identifier of this intent. + // Required for [Intents.UpdateIntent][google.cloud.dialogflow.v2.Intents.UpdateIntent] and [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2.Intents.BatchUpdateIntents] + // methods. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string name = 1; + + // Required. The name of this intent. + string display_name = 2; + + // Optional. Indicates whether webhooks are enabled for the intent. + WebhookState webhook_state = 6; + + // Optional. The priority of this intent. Higher numbers represent higher + // priorities. If this is zero or unspecified, we use the default + // priority 500000. + // + // Negative numbers mean that the intent is disabled. + int32 priority = 3; + + // Optional. Indicates whether this is a fallback intent. + bool is_fallback = 4; + + // Optional. Indicates whether Machine Learning is disabled for the intent. + // Note: If `ml_diabled` setting is set to true, then this intent is not + // taken into account during inference in `ML ONLY` match mode. Also, + // auto-markup in the UI is turned off. + bool ml_disabled = 19; + + // Optional. The list of context names required for this intent to be + // triggered. + // Format: `projects/<Project ID>/agent/sessions/-/contexts/<Context ID>`. + repeated string input_context_names = 7; + + // Optional. The collection of event names that trigger the intent. + // If the collection of input contexts is not empty, all of the contexts must + // be present in the active user session for an event to trigger this intent. + repeated string events = 8; + + // Optional. The collection of examples that the agent is + // trained on. + repeated TrainingPhrase training_phrases = 9; + + // Optional. The name of the action associated with the intent. + // Note: The action name must not contain whitespaces. + string action = 10; + + // Optional. The collection of contexts that are activated when the intent + // is matched. Context messages in this collection should not set the + // parameters field. Setting the `lifespan_count` to 0 will reset the context + // when the intent is matched. + // Format: `projects/<Project ID>/agent/sessions/-/contexts/<Context ID>`. + repeated Context output_contexts = 11; + + // Optional. Indicates whether to delete all contexts in the current + // session when this intent is matched. + bool reset_contexts = 12; + + // Optional. The collection of parameters associated with the intent. + repeated Parameter parameters = 13; + + // Optional. The collection of rich messages corresponding to the + // `Response` field in the Dialogflow console. + repeated Message messages = 14; + + // Optional. The list of platforms for which the first response will be + // taken from among the messages assigned to the DEFAULT_PLATFORM. + repeated Message.Platform default_response_platforms = 15; + + // Read-only. The unique identifier of the root intent in the chain of + // followup intents. It identifies the correct followup intents chain for + // this intent. We populate this field only in the output. + // + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string root_followup_intent_name = 16; + + // Read-only after creation. The unique identifier of the parent intent in the + // chain of followup intents. You can set this field when creating an intent, + // for example with [CreateIntent][] or [BatchUpdateIntents][], in order to + // make this intent a followup intent. + // + // It identifies the parent followup intent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string parent_followup_intent_name = 17; + + // Read-only. Information about all followup intents that have this intent as + // a direct or indirect parent. We populate this field only in the output. + repeated FollowupIntentInfo followup_intent_info = 18; +} + +// The request message for [Intents.ListIntents][google.cloud.dialogflow.v2.Intents.ListIntents]. +message ListIntentsRequest { + // Required. The agent to list all intents from. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Optional. The language to list training phrases, parameters and rich + // messages for. If not specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 3; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 4; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 5; +} + +// The response message for [Intents.ListIntents][google.cloud.dialogflow.v2.Intents.ListIntents]. +message ListIntentsResponse { + // The list of agent intents. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated Intent intents = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [Intents.GetIntent][google.cloud.dialogflow.v2.Intents.GetIntent]. +message GetIntentRequest { + // Required. The name of the intent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string name = 1; + + // Optional. The language to retrieve training phrases, parameters and rich + // messages for. If not specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 3; +} + +// The request message for [Intents.CreateIntent][google.cloud.dialogflow.v2.Intents.CreateIntent]. +message CreateIntentRequest { + // Required. The agent to create a intent for. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The intent to create. + Intent intent = 2; + + // Optional. The language of training phrases, parameters and rich messages + // defined in `intent`. If not specified, the agent's default language is + // used. [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 4; +} + +// The request message for [Intents.UpdateIntent][google.cloud.dialogflow.v2.Intents.UpdateIntent]. +message UpdateIntentRequest { + // Required. The intent to update. + Intent intent = 1; + + // Optional. The language of training phrases, parameters and rich messages + // defined in `intent`. If not specified, the agent's default language is + // used. [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 3; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 4; +} + +// The request message for [Intents.DeleteIntent][google.cloud.dialogflow.v2.Intents.DeleteIntent]. +message DeleteIntentRequest { + // Required. The name of the intent to delete. If this intent has direct or + // indirect followup intents, we also delete them. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string name = 1; +} + +// The request message for [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2.Intents.BatchUpdateIntents]. +message BatchUpdateIntentsRequest { + // Required. The name of the agent to update or create intents in. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The source of the intent batch. + oneof intent_batch { + // The URI to a Google Cloud Storage file containing intents to update or + // create. The file format can either be a serialized proto (of IntentBatch + // type) or JSON object. Note: The URI must start with "gs://". + string intent_batch_uri = 2; + + // The collection of intents to update or create. + IntentBatch intent_batch_inline = 3; + } + + // Optional. The language of training phrases, parameters and rich messages + // defined in `intents`. If not specified, the agent's default language is + // used. [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 4; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 5; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 6; +} + +// The response message for [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2.Intents.BatchUpdateIntents]. +message BatchUpdateIntentsResponse { + // The collection of updated or created intents. + repeated Intent intents = 1; +} + +// The request message for [Intents.BatchDeleteIntents][google.cloud.dialogflow.v2.Intents.BatchDeleteIntents]. +message BatchDeleteIntentsRequest { + // Required. The name of the agent to delete all entities types for. Format: + // `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The collection of intents to delete. Only intent `name` must be + // filled in. + repeated Intent intents = 2; +} + +// This message is a wrapper around a collection of intents. +message IntentBatch { + // A collection of intents. + repeated Intent intents = 1; +} + +// Represents the options for views of an intent. +// An intent can be a sizable object. Therefore, we provide a resource view that +// does not return training phrases in the response by default. +enum IntentView { + // Training phrases field is not populated in the response. + INTENT_VIEW_UNSPECIFIED = 0; + + // All fields are populated. + INTENT_VIEW_FULL = 1; +} diff --git a/google/cloud/dialogflow/v2/session.proto b/google/cloud/dialogflow/v2/session.proto new file mode 100644 index 000000000..e10bb6db8 --- /dev/null +++ b/google/cloud/dialogflow/v2/session.proto @@ -0,0 +1,555 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/dialogflow/v2/audio_config.proto"; +import "google/cloud/dialogflow/v2/context.proto"; +import "google/cloud/dialogflow/v2/intent.proto"; +import "google/cloud/dialogflow/v2/session_entity_type.proto"; +import "google/protobuf/struct.proto"; +import "google/rpc/status.proto"; +import "google/type/latlng.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "SessionProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// A session represents an interaction with a user. You retrieve user input +// and pass it to the [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or +// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method to determine +// user intent and respond. +service Sessions { + // Processes a natural language query and returns structured, actionable data + // as a result. This method is not idempotent, because it may cause contexts + // and session entity types to be updated, which in turn might affect + // results of future queries. + rpc DetectIntent(DetectIntentRequest) returns (DetectIntentResponse) { + option (google.api.http) = { + post: "/v2/{session=projects/*/agent/sessions/*}:detectIntent" + body: "*" + }; + } + + // Processes a natural language query in audio format in a streaming fashion + // and returns structured, actionable data as a result. This method is only + // available via the gRPC API (not REST). + rpc StreamingDetectIntent(stream StreamingDetectIntentRequest) returns (stream StreamingDetectIntentResponse) { + } +} + +// The request to detect user's intent. +message DetectIntentRequest { + // Required. The name of the session this query is sent to. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>`. It's up to the API + // caller to choose an appropriate session ID. It can be a random number or + // some type of user identifier (preferably hashed). The length of the session + // ID must not exceed 36 bytes. + string session = 1; + + // Optional. The parameters of this query. + QueryParameters query_params = 2; + + // Required. The input specification. It can be set to: + // + // 1. an audio config + // which instructs the speech recognizer how to process the speech audio, + // + // 2. a conversational query in the form of text, or + // + // 3. an event that specifies which intent to trigger. + QueryInput query_input = 3; + + // Optional. Instructs the speech synthesizer how to generate the output + // audio. If this field is not set and agent-level speech synthesizer is not + // configured, no output audio is generated. + OutputAudioConfig output_audio_config = 4; + + // Optional. The natural language speech audio to be processed. This field + // should be populated iff `query_input` is set to an input audio config. + // A single request can contain up to 1 minute of speech audio data. + bytes input_audio = 5; +} + +// The message returned from the DetectIntent method. +message DetectIntentResponse { + // The unique identifier of the response. It can be used to + // locate a response in the training example set or for reporting issues. + string response_id = 1; + + // The selected results of the conversational query or event processing. + // See `alternative_query_results` for additional potential results. + QueryResult query_result = 2; + + // Specifies the status of the webhook request. + google.rpc.Status webhook_status = 3; + + // The audio data bytes encoded as specified in the request. + // Note: The output audio is generated based on the values of default platform + // text responses found in the `query_result.fulfillment_messages` field. If + // multiple default text responses exist, they will be concatenated when + // generating audio. If no default platform text responses exist, the + // generated audio content will be empty. + bytes output_audio = 4; + + // The config used by the speech synthesizer to generate the output audio. + OutputAudioConfig output_audio_config = 6; +} + +// Represents the parameters of the conversational query. +message QueryParameters { + // Optional. The time zone of this conversational query from the + // [time zone database](https://www.iana.org/time-zones), e.g., + // America/New_York, Europe/Paris. If not provided, the time zone specified in + // agent settings is used. + string time_zone = 1; + + // Optional. The geo location of this conversational query. + google.type.LatLng geo_location = 2; + + // Optional. The collection of contexts to be activated before this query is + // executed. + repeated Context contexts = 3; + + // Optional. Specifies whether to delete all contexts in the current session + // before the new ones are activated. + bool reset_contexts = 4; + + // Optional. Additional session entity types to replace or extend developer + // entity types with. The entity synonyms apply to all languages and persist + // for the session of this query. + repeated SessionEntityType session_entity_types = 5; + + // Optional. This field can be used to pass custom data into the webhook + // associated with the agent. Arbitrary JSON objects are supported. + google.protobuf.Struct payload = 6; + + // Optional. Configures the type of sentiment analysis to perform. If not + // provided, sentiment analysis is not performed. + SentimentAnalysisRequestConfig sentiment_analysis_request_config = 10; +} + +// Represents the query input. It can contain either: +// +// 1. An audio config which +// instructs the speech recognizer how to process the speech audio. +// +// 2. A conversational query in the form of text,. +// +// 3. An event that specifies which intent to trigger. +message QueryInput { + // Required. The input specification. + oneof input { + // Instructs the speech recognizer how to process the speech audio. + InputAudioConfig audio_config = 1; + + // The natural language text to be processed. + TextInput text = 2; + + // The event to be processed. + EventInput event = 3; + } +} + +// Represents the result of conversational query or event processing. +message QueryResult { + // The original conversational query text: + // - If natural language text was provided as input, `query_text` contains + // a copy of the input. + // - If natural language speech audio was provided as input, `query_text` + // contains the speech recognition result. If speech recognizer produced + // multiple alternatives, a particular one is picked. + // - If an event was provided as input, `query_text` is not set. + string query_text = 1; + + // The language that was triggered during intent detection. + // See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. + string language_code = 15; + + // The Speech recognition confidence between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. The default of 0.0 is a sentinel value indicating that confidence + // was not set. + // + // This field is not guaranteed to be accurate or set. In particular this + // field isn't set for StreamingDetectIntent since the streaming endpoint has + // separate confidence estimates per portion of the audio in + // StreamingRecognitionResult. + float speech_recognition_confidence = 2; + + // The action name from the matched intent. + string action = 3; + + // The collection of extracted parameters. + google.protobuf.Struct parameters = 4; + + // This field is set to: + // - `false` if the matched intent has required parameters and not all of + // the required parameter values have been collected. + // - `true` if all required parameter values have been collected, or if the + // matched intent doesn't contain any required parameters. + bool all_required_params_present = 5; + + // The text to be pronounced to the user or shown on the screen. + // Note: This is a legacy field, `fulfillment_messages` should be preferred. + string fulfillment_text = 6; + + // The collection of rich messages to present to the user. + repeated Intent.Message fulfillment_messages = 7; + + // If the query was fulfilled by a webhook call, this field is set to the + // value of the `source` field returned in the webhook response. + string webhook_source = 8; + + // If the query was fulfilled by a webhook call, this field is set to the + // value of the `payload` field returned in the webhook response. + google.protobuf.Struct webhook_payload = 9; + + // The collection of output contexts. If applicable, + // `output_contexts.parameters` contains entries with name + // `<parameter name>.original` containing the original parameter values + // before the query. + repeated Context output_contexts = 10; + + // The intent that matched the conversational query. Some, not + // all fields are filled in this message, including but not limited to: + // `name`, `display_name` and `webhook_state`. + Intent intent = 11; + + // The intent detection confidence. Values range from 0.0 + // (completely uncertain) to 1.0 (completely certain). + // If there are `multiple knowledge_answers` messages, this value is set to + // the greatest `knowledgeAnswers.match_confidence` value in the list. + float intent_detection_confidence = 12; + + // The free-form diagnostic info. For example, this field could contain + // webhook call latency. The string keys of the Struct's fields map can change + // without notice. + google.protobuf.Struct diagnostic_info = 14; + + // The sentiment analysis result, which depends on the + // `sentiment_analysis_request_config` specified in the request. + SentimentAnalysisResult sentiment_analysis_result = 17; +} + +// The top-level message sent by the client to the +// `StreamingDetectIntent` method. +// +// Multiple request messages should be sent in order: +// +// 1. The first message must contain `session`, `query_input` plus optionally +// `query_params` and/or `single_utterance`. The message must not contain `input_audio`. +// +// 2. If `query_input` was set to a streaming input audio config, +// all subsequent messages must contain only `input_audio`. +// Otherwise, finish the request stream. +message StreamingDetectIntentRequest { + // Required. The name of the session the query is sent to. + // Format of the session name: + // `projects/<Project ID>/agent/sessions/<Session ID>`. It’s up to the API + // caller to choose an appropriate `Session ID`. It can be a random number or + // some type of user identifier (preferably hashed). The length of the session + // ID must not exceed 36 characters. + string session = 1; + + // Optional. The parameters of this query. + QueryParameters query_params = 2; + + // Required. The input specification. It can be set to: + // + // 1. an audio config which instructs the speech recognizer how to process + // the speech audio, + // + // 2. a conversational query in the form of text, or + // + // 3. an event that specifies which intent to trigger. + QueryInput query_input = 3; + + // Optional. If `false` (default), recognition does not cease until the + // client closes the stream. + // If `true`, the recognizer will detect a single spoken utterance in input + // audio. Recognition ceases when it detects the audio's voice has + // stopped or paused. In this case, once a detected intent is received, the + // client should close the stream and start a new request with a new stream as + // needed. + // This setting is ignored when `query_input` is a piece of text or an event. + bool single_utterance = 4; + + // Optional. Instructs the speech synthesizer how to generate the output + // audio. If this field is not set and agent-level speech synthesizer is not + // configured, no output audio is generated. + OutputAudioConfig output_audio_config = 5; + + // Optional. The input audio content to be recognized. Must be sent if + // `query_input` was set to a streaming input audio config. The complete audio + // over all streaming messages must not exceed 1 minute. + bytes input_audio = 6; +} + +// The top-level message returned from the +// `StreamingDetectIntent` method. +// +// Multiple response messages can be returned in order: +// +// 1. If the input was set to streaming audio, the first one or more messages +// contain `recognition_result`. Each `recognition_result` represents a more +// complete transcript of what the user said. The last `recognition_result` +// has `is_final` set to `true`. +// +// 2. The next message contains `response_id`, `query_result` +// and optionally `webhook_status` if a WebHook was called. +message StreamingDetectIntentResponse { + // The unique identifier of the response. It can be used to + // locate a response in the training example set or for reporting issues. + string response_id = 1; + + // The result of speech recognition. + StreamingRecognitionResult recognition_result = 2; + + // The result of the conversational query or event processing. + QueryResult query_result = 3; + + // Specifies the status of the webhook request. + google.rpc.Status webhook_status = 4; + + // The audio data bytes encoded as specified in the request. + bytes output_audio = 5; + + // Instructs the speech synthesizer how to generate the output audio. This + // field is populated from the agent-level speech synthesizer configuration, + // if enabled. + OutputAudioConfig output_audio_config = 6; +} + +// Contains a speech recognition result corresponding to a portion of the audio +// that is currently being processed or an indication that this is the end +// of the single requested utterance. +// +// Example: +// +// 1. transcript: "tube" +// +// 2. transcript: "to be a" +// +// 3. transcript: "to be" +// +// 4. transcript: "to be or not to be" +// is_final: true +// +// 5. transcript: " that's" +// +// 6. transcript: " that is" +// +// 7. message_type: `MESSAGE_TYPE_END_OF_SINGLE_UTTERANCE` +// +// 8. transcript: " that is the question" +// is_final: true +// +// Only two of the responses contain final results (#4 and #8 indicated by +// `is_final: true`). Concatenating these generates the full transcript: "to be +// or not to be that is the question". +// +// In each response we populate: +// +// * for `MESSAGE_TYPE_TRANSCRIPT`: `transcript` and possibly `is_final`. +// +// * for `MESSAGE_TYPE_END_OF_SINGLE_UTTERANCE`: only `message_type`. +message StreamingRecognitionResult { + // Type of the response message. + enum MessageType { + // Not specified. Should never be used. + MESSAGE_TYPE_UNSPECIFIED = 0; + + // Message contains a (possibly partial) transcript. + TRANSCRIPT = 1; + + // Event indicates that the server has detected the end of the user's speech + // utterance and expects no additional speech. Therefore, the server will + // not process additional audio (although it may subsequently return + // additional results). The client should stop sending additional audio + // data, half-close the gRPC connection, and wait for any additional results + // until the server closes the gRPC connection. This message is only sent if + // `single_utterance` was set to `true`, and is not used otherwise. + END_OF_SINGLE_UTTERANCE = 2; + } + + // Type of the result message. + MessageType message_type = 1; + + // Transcript text representing the words that the user spoke. + // Populated if and only if `message_type` = `MESSAGE_TYPE_TRANSCRIPT`. + string transcript = 2; + + // If `false`, the `StreamingRecognitionResult` represents an + // interim result that may change. If `true`, the recognizer will not return + // any further hypotheses about this piece of the audio. May only be populated + // for `message_type` = `MESSAGE_TYPE_TRANSCRIPT`. + bool is_final = 3; + + // The Speech confidence between 0.0 and 1.0 for the current portion of audio. + // A higher number indicates an estimated greater likelihood that the + // recognized words are correct. The default of 0.0 is a sentinel value + // indicating that confidence was not set. + // + // This field is typically only provided if `is_final` is true and you should + // not rely on it being accurate or even set. + float confidence = 4; +} + +// Instructs the speech recognizer how to process the audio content. +message InputAudioConfig { + // Required. Audio encoding of the audio content to process. + AudioEncoding audio_encoding = 1; + + // Required. Sample rate (in Hertz) of the audio content sent in the query. + // Refer to + // [Cloud Speech API + // documentation](https://cloud.google.com/speech-to-text/docs/basics) for + // more details. + int32 sample_rate_hertz = 2; + + // Required. The language of the supplied audio. Dialogflow does not do + // translations. See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. Note that queries in + // the same session do not necessarily need to specify the same language. + string language_code = 3; + + // Optional. The collection of phrase hints which are used to boost accuracy + // of speech recognition. + // Refer to + // [Cloud Speech API + // documentation](https://cloud.google.com/speech-to-text/docs/basics#phrase-hints) + // for more details. + repeated string phrase_hints = 4; +} + +// Represents the natural language text to be processed. +message TextInput { + // Required. The UTF-8 encoded natural language text to be processed. + // Text length must not exceed 256 characters. + string text = 1; + + // Required. The language of this conversational query. See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. Note that queries in + // the same session do not necessarily need to specify the same language. + string language_code = 2; +} + +// Audio encoding of the audio content sent in the conversational query request. +// Refer to the +// [Cloud Speech API +// documentation](https://cloud.google.com/speech-to-text/docs/basics) for more +// details. +enum AudioEncoding { + // Not specified. + AUDIO_ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + AUDIO_ENCODING_LINEAR_16 = 1; + + // [`FLAC`](https://xiph.org/flac/documentation.html) (Free Lossless Audio + // Codec) is the recommended encoding because it is lossless (therefore + // recognition is not compromised) and requires only about half the + // bandwidth of `LINEAR16`. `FLAC` stream encoding supports 16-bit and + // 24-bit samples, however, not all fields in `STREAMINFO` are supported. + AUDIO_ENCODING_FLAC = 2; + + // 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law. + AUDIO_ENCODING_MULAW = 3; + + // Adaptive Multi-Rate Narrowband codec. `sample_rate_hertz` must be 8000. + AUDIO_ENCODING_AMR = 4; + + // Adaptive Multi-Rate Wideband codec. `sample_rate_hertz` must be 16000. + AUDIO_ENCODING_AMR_WB = 5; + + // Opus encoded audio frames in Ogg container + // ([OggOpus](https://wiki.xiph.org/OggOpus)). + // `sample_rate_hertz` must be 16000. + AUDIO_ENCODING_OGG_OPUS = 6; + + // Although the use of lossy encodings is not recommended, if a very low + // bitrate encoding is required, `OGG_OPUS` is highly preferred over + // Speex encoding. The [Speex](https://speex.org/) encoding supported by + // Dialogflow API has a header byte in each block, as in MIME type + // `audio/x-speex-with-header-byte`. + // It is a variant of the RTP Speex encoding defined in + // [RFC 5574](https://tools.ietf.org/html/rfc5574). + // The stream is a sequence of blocks, one block per RTP packet. Each block + // starts with a byte containing the length of the block, in bytes, followed + // by one or more frames of Speex data, padded to an integral number of + // bytes (octets) as specified in RFC 5574. In other words, each RTP header + // is replaced with a single byte containing the block length. Only Speex + // wideband is supported. `sample_rate_hertz` must be 16000. + AUDIO_ENCODING_SPEEX_WITH_HEADER_BYTE = 7; +} + +// Events allow for matching intents by event name instead of the natural +// language input. For instance, input `<event: { name: "welcome_event", +// parameters: { name: "Sam" } }>` can trigger a personalized welcome response. +// The parameter `name` may be used by the agent in the response: +// `"Hello #welcome_event.name! What can I do for you today?"`. +message EventInput { + // Required. The unique identifier of the event. + string name = 1; + + // Optional. The collection of parameters associated with the event. + google.protobuf.Struct parameters = 2; + + // Required. The language of this query. See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. Note that queries in + // the same session do not necessarily need to specify the same language. + string language_code = 3; +} + +// Configures the types of sentiment analysis to perform. +message SentimentAnalysisRequestConfig { + // Optional. Instructs the service to perform sentiment analysis on + // `query_text`. If not provided, sentiment analysis is not performed on + // `query_text`. + bool analyze_query_text_sentiment = 1; +} + +// The result of sentiment analysis as configured by +// `sentiment_analysis_request_config`. +message SentimentAnalysisResult { + // The sentiment analysis result for `query_text`. + Sentiment query_text_sentiment = 1; +} + +// The sentiment, such as positive/negative feeling or association, for a unit +// of analysis, such as the query text. +message Sentiment { + // Sentiment score between -1.0 (negative sentiment) and 1.0 (positive + // sentiment). + float score = 1; + + // A non-negative number in the [0, +inf) range, which represents the absolute + // magnitude of sentiment, regardless of score (positive or negative). + float magnitude = 2; +} diff --git a/google/cloud/dialogflow/v2/session_entity_type.proto b/google/cloud/dialogflow/v2/session_entity_type.proto new file mode 100644 index 000000000..10d666fd1 --- /dev/null +++ b/google/cloud/dialogflow/v2/session_entity_type.proto @@ -0,0 +1,195 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/dialogflow/v2/entity_type.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "SessionEntityTypeProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// Entities are extracted from user input and represent parameters that are +// meaningful to your application. For example, a date range, a proper name +// such as a geographic location or landmark, and so on. Entities represent +// actionable data for your application. +// +// Session entity types are referred to as **User** entity types and are +// entities that are built for an individual user such as +// favorites, preferences, playlists, and so on. You can redefine a session +// entity type at the session level. +// +// For more information about entity types, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/entities-overview). +service SessionEntityTypes { + // Returns the list of all session entity types in the specified session. + rpc ListSessionEntityTypes(ListSessionEntityTypesRequest) returns (ListSessionEntityTypesResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/agent/sessions/*}/entityTypes" + }; + } + + // Retrieves the specified session entity type. + rpc GetSessionEntityType(GetSessionEntityTypeRequest) returns (SessionEntityType) { + option (google.api.http) = { + get: "/v2/{name=projects/*/agent/sessions/*/entityTypes/*}" + }; + } + + // Creates a session entity type. + // + // If the specified session entity type already exists, overrides the session + // entity type. + rpc CreateSessionEntityType(CreateSessionEntityTypeRequest) returns (SessionEntityType) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/agent/sessions/*}/entityTypes" + body: "session_entity_type" + }; + } + + // Updates the specified session entity type. + rpc UpdateSessionEntityType(UpdateSessionEntityTypeRequest) returns (SessionEntityType) { + option (google.api.http) = { + patch: "/v2/{session_entity_type.name=projects/*/agent/sessions/*/entityTypes/*}" + body: "session_entity_type" + }; + } + + // Deletes the specified session entity type. + rpc DeleteSessionEntityType(DeleteSessionEntityTypeRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/agent/sessions/*/entityTypes/*}" + }; + } +} + +// Represents a session entity type. +// +// Extends or replaces a developer entity type at the user session level (we +// refer to the entity types defined at the agent level as "developer entity +// types"). +// +// Note: session entity types apply to all queries, regardless of the language. +message SessionEntityType { + // The types of modifications for a session entity type. + enum EntityOverrideMode { + // Not specified. This value should be never used. + ENTITY_OVERRIDE_MODE_UNSPECIFIED = 0; + + // The collection of session entities overrides the collection of entities + // in the corresponding developer entity type. + ENTITY_OVERRIDE_MODE_OVERRIDE = 1; + + // The collection of session entities extends the collection of entities in + // the corresponding developer entity type. + // + // Note: Even in this override mode calls to `ListSessionEntityTypes`, + // `GetSessionEntityType`, `CreateSessionEntityType` and + // `UpdateSessionEntityType` only return the additional entities added in + // this session entity type. If you want to get the supplemented list, + // please call [EntityTypes.GetEntityType][google.cloud.dialogflow.v2.EntityTypes.GetEntityType] on the developer entity type + // and merge. + ENTITY_OVERRIDE_MODE_SUPPLEMENT = 2; + } + + // Required. The unique identifier of this session entity type. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>`. + // + // `<Entity Type Display Name>` must be the display name of an existing entity + // type in the same agent that will be overridden or supplemented. + string name = 1; + + // Required. Indicates whether the additional data should override or + // supplement the developer entity type definition. + EntityOverrideMode entity_override_mode = 2; + + // Required. The collection of entities associated with this session entity + // type. + repeated EntityType.Entity entities = 3; +} + +// The request message for [SessionEntityTypes.ListSessionEntityTypes][google.cloud.dialogflow.v2.SessionEntityTypes.ListSessionEntityTypes]. +message ListSessionEntityTypesRequest { + // Required. The session to list all session entity types from. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>`. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// The response message for [SessionEntityTypes.ListSessionEntityTypes][google.cloud.dialogflow.v2.SessionEntityTypes.ListSessionEntityTypes]. +message ListSessionEntityTypesResponse { + // The list of session entity types. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated SessionEntityType session_entity_types = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [SessionEntityTypes.GetSessionEntityType][google.cloud.dialogflow.v2.SessionEntityTypes.GetSessionEntityType]. +message GetSessionEntityTypeRequest { + // Required. The name of the session entity type. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>`. + string name = 1; +} + +// The request message for [SessionEntityTypes.CreateSessionEntityType][google.cloud.dialogflow.v2.SessionEntityTypes.CreateSessionEntityType]. +message CreateSessionEntityTypeRequest { + // Required. The session to create a session entity type for. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>`. + string parent = 1; + + // Required. The session entity type to create. + SessionEntityType session_entity_type = 2; +} + +// The request message for [SessionEntityTypes.UpdateSessionEntityType][google.cloud.dialogflow.v2.SessionEntityTypes.UpdateSessionEntityType]. +message UpdateSessionEntityTypeRequest { + // Required. The entity type to update. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>`. + SessionEntityType session_entity_type = 1; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 2; +} + +// The request message for [SessionEntityTypes.DeleteSessionEntityType][google.cloud.dialogflow.v2.SessionEntityTypes.DeleteSessionEntityType]. +message DeleteSessionEntityTypeRequest { + // Required. The name of the entity type to delete. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>`. + string name = 1; +} diff --git a/google/cloud/dialogflow/v2/webhook.proto b/google/cloud/dialogflow/v2/webhook.proto new file mode 100644 index 000000000..4c958cebe --- /dev/null +++ b/google/cloud/dialogflow/v2/webhook.proto @@ -0,0 +1,128 @@ +// Copyright 2019 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.dialogflow.v2; + +import "google/cloud/dialogflow/v2/context.proto"; +import "google/cloud/dialogflow/v2/intent.proto"; +import "google/cloud/dialogflow/v2/session.proto"; +import "google/protobuf/struct.proto"; +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "WebhookProto"; +option java_package = "com.google.cloud.dialogflow.v2"; +option objc_class_prefix = "DF"; + +// The request message for a webhook call. +message WebhookRequest { + // The unique identifier of detectIntent request session. + // Can be used to identify end-user inside webhook implementation. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>`, or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>`. + string session = 4; + + // The unique identifier of the response. Contains the same value as + // `[Streaming]DetectIntentResponse.response_id`. + string response_id = 1; + + // The result of the conversational query or event processing. Contains the + // same value as `[Streaming]DetectIntentResponse.query_result`. + QueryResult query_result = 2; + + // Optional. The contents of the original request that was passed to + // `[Streaming]DetectIntent` call. + OriginalDetectIntentRequest original_detect_intent_request = 3; +} + +// The response message for a webhook call. +message WebhookResponse { + // Optional. The text to be shown on the screen. This value is passed directly + // to `QueryResult.fulfillment_text`. + string fulfillment_text = 1; + + // Optional. The collection of rich messages to present to the user. This + // value is passed directly to `QueryResult.fulfillment_messages`. + repeated Intent.Message fulfillment_messages = 2; + + // Optional. This value is passed directly to `QueryResult.webhook_source`. + string source = 3; + + // Optional. This value is passed directly to `QueryResult.webhook_payload`. + // See the related `fulfillment_messages[i].payload field`, which may be used + // as an alternative to this field. + // + // This field can be used for Actions on Google responses. + // It should have a structure similar to the JSON message shown here. For more + // information, see + // [Actions on Google Webhook + // Format](https://developers.google.com/actions/dialogflow/webhook) + // <pre>{ + // "google": { + // "expectUserResponse": true, + // "richResponse": { + // "items": [ + // { + // "simpleResponse": { + // "textToSpeech": "this is a simple response" + // } + // } + // ] + // } + // } + // }</pre> + google.protobuf.Struct payload = 4; + + // Optional. The collection of output contexts. This value is passed directly + // to `QueryResult.output_contexts`. + repeated Context output_contexts = 5; + + // Optional. Makes the platform immediately invoke another `DetectIntent` call + // internally with the specified event as input. + EventInput followup_event_input = 6; +} + +// Represents the contents of the original request that was passed to +// the `[Streaming]DetectIntent` call. +message OriginalDetectIntentRequest { + // The source of this request, e.g., `google`, `facebook`, `slack`. It is set + // by Dialogflow-owned servers. + string source = 1; + + // Optional. The version of the protocol used for this request. + // This field is AoG-specific. + string version = 2; + + // Optional. This field is set to the value of the `QueryParameters.payload` + // field passed in the request. Some integrations that query a Dialogflow + // agent may provide additional information in the payload. + // + // In particular for the Telephony Gateway this field has the form: + // <pre>{ + // "telephony": { + // "caller_id": "+18558363987" + // } + // }</pre> + // Note: The caller ID field (`caller_id`) will be redacted for Standard + // Edition agents and populated with the caller ID in [E.164 + // format](https://en.wikipedia.org/wiki/E.164) for Enterprise Edition agents. + google.protobuf.Struct payload = 3; +} diff --git a/google/cloud/dialogflow/v2beta1/BUILD.bazel b/google/cloud/dialogflow/v2beta1/BUILD.bazel new file mode 100644 index 000000000..705c61fe9 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/BUILD.bazel @@ -0,0 +1,169 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "dialogflow_proto", + srcs = [ + "agent.proto", + "audio_config.proto", + "context.proto", + "document.proto", + "entity_type.proto", + "intent.proto", + "knowledge_base.proto", + "session.proto", + "session_entity_type.proto", + "webhook.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "//google/type:latlng_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:struct_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "dialogflow_proto_with_info", + deps = [":dialogflow_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "dialogflow_java_proto", + deps = [":dialogflow_proto"], +) + +java_grpc_library( + name = "dialogflow_java_grpc", + srcs = [":dialogflow_proto"], + deps = [":dialogflow_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "dialogflow_resource_name_java_proto", + gapic_yaml = "dialogflow_gapic.yaml", + deps = [":dialogflow_proto"], +) + +java_gapic_library( + name = "dialogflow_java_gapic", + src = ":dialogflow_proto_with_info", + gapic_yaml = "dialogflow_gapic.yaml", + service_yaml = "//google/cloud/dialogflow:dialogflow_v2beta1.yaml", + test_deps = [":dialogflow_java_grpc"], + deps = [ + ":dialogflow_java_proto", + ":dialogflow_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":dialogflow_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.dialogflow.v2beta1.AgentsClientTest", + "com.google.cloud.dialogflow.v2beta1.ContextsClientTest", + "com.google.cloud.dialogflow.v2beta1.EntityTypesClientTest", + "com.google.cloud.dialogflow.v2beta1.DocumentsClientTest", + "com.google.cloud.dialogflow.v2beta1.IntentsClientTest", + "com.google.cloud.dialogflow.v2beta1.SessionEntityTypesClientTest", + "com.google.cloud.dialogflow.v2beta1.SessionsClientTest", + "com.google.cloud.dialogflow.v2beta1.KnowledgeBasesClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-dialogflow-v2beta1-java", + client_deps = [":dialogflow_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":dialogflow_java_gapic_test"], + grpc_deps = [":dialogflow_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":dialogflow_java_proto", + ":dialogflow_proto", + ":dialogflow_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "dialogflow_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1", + protos = [":dialogflow_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + "//google/type:latlng_go_proto", + ], +) + +go_gapic_library( + name = "dialogflow_go_gapic", + src = ":dialogflow_proto_with_info", + gapic_yaml = "dialogflow_gapic.yaml", + importpath = "cloud.google.com/go/cloud/dialogflow/apiv2beta1", + service_yaml = "//google/cloud/dialogflow:dialogflow_v2beta1.yaml", + deps = [ + ":dialogflow_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + "@io_bazel_rules_go//proto/wkt:struct_go_proto", + ], +) + +go_test( + name = "dialogflow_go_gapic_test", + srcs = [":dialogflow_go_gapic_srcjar_test"], + embed = [":dialogflow_go_gapic"], + importpath = "cloud.google.com/go/cloud/dialogflow/apiv2beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-dialogflow-v2beta1-go", + deps = [ + ":dialogflow_go_gapic", + ":dialogflow_go_gapic_srcjar-smoke-test.srcjar", + ":dialogflow_go_gapic_srcjar-test.srcjar", + ":dialogflow_go_proto", + ], +) diff --git a/google/cloud/dialogflow/v2beta1/agent.proto b/google/cloud/dialogflow/v2beta1/agent.proto new file mode 100644 index 000000000..9e4c7a2a0 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/agent.proto @@ -0,0 +1,339 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "AgentProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// Agents are best described as Natural Language Understanding (NLU) modules +// that transform user requests into actionable data. You can include agents +// in your app, product, or service to determine user intent and respond to the +// user in a natural way. +// +// After you create an agent, you can add [Intents][google.cloud.dialogflow.v2beta1.Intents], [Contexts][google.cloud.dialogflow.v2beta1.Contexts], +// [Entity Types][google.cloud.dialogflow.v2beta1.EntityTypes], [Webhooks][google.cloud.dialogflow.v2beta1.WebhookRequest], and so on to +// manage the flow of a conversation and match user input to predefined intents +// and actions. +// +// You can create an agent using both Dialogflow Standard Edition and +// Dialogflow Enterprise Edition. For details, see +// [Dialogflow +// Editions](https://cloud.google.com/dialogflow-enterprise/docs/editions). +// +// You can save your agent for backup or versioning by exporting the agent by +// using the [ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent] method. You can import a saved +// agent by using the [ImportAgent][google.cloud.dialogflow.v2beta1.Agents.ImportAgent] method. +// +// Dialogflow provides several +// [prebuilt +// agents](https://cloud.google.com/dialogflow-enterprise/docs/agents-prebuilt) +// for common conversation scenarios such as determining a date and time, +// converting currency, and so on. +// +// For more information about agents, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/agents-overview). +service Agents { + // Retrieves the specified agent. + rpc GetAgent(GetAgentRequest) returns (Agent) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*}/agent" + }; + } + + // Returns the list of agents. + // + // Since there is at most one conversational agent per project, this method is + // useful primarily for listing all agents across projects the caller has + // access to. One can achieve that with a wildcard project collection id "-". + // Refer to [List + // Sub-Collections](https://cloud.google.com/apis/design/design_patterns#list_sub-collections). + rpc SearchAgents(SearchAgentsRequest) returns (SearchAgentsResponse) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*}/agent:search" + }; + } + + // Trains the specified agent. + // + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc TrainAgent(TrainAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*}/agent:train" + body: "*" + }; + } + + // Exports the specified agent to a ZIP file. + // + // + // Operation <response: [ExportAgentResponse][google.cloud.dialogflow.v2beta1.ExportAgentResponse]> + rpc ExportAgent(ExportAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*}/agent:export" + body: "*" + }; + } + + // Imports the specified agent from a ZIP file. + // + // Uploads new intents and entity types without deleting the existing ones. + // Intents and entity types with the same name are replaced with the new + // versions from ImportAgentRequest. + // + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc ImportAgent(ImportAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*}/agent:import" + body: "*" + }; + } + + // Restores the specified agent from a ZIP file. + // + // Replaces the current agent version with a new one. All the intents and + // entity types in the older version are deleted. + // + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc RestoreAgent(RestoreAgentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*}/agent:restore" + body: "*" + }; + } +} + +// Represents a conversational agent. +message Agent { + // Match mode determines how intents are detected from user queries. + enum MatchMode { + // Not specified. + MATCH_MODE_UNSPECIFIED = 0; + + // Best for agents with a small number of examples in intents and/or wide + // use of templates syntax and composite entities. + MATCH_MODE_HYBRID = 1; + + // Can be used for agents with a large number of examples in intents, + // especially the ones using @sys.any or very large developer entities. + MATCH_MODE_ML_ONLY = 2; + } + + // Required. The project of this agent. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Required. The name of this agent. + string display_name = 2; + + // Required. The default language of the agent as a language tag. See + // [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. This field cannot be + // set by the `Update` method. + string default_language_code = 3; + + // Optional. The list of all languages supported by this agent (except for the + // `default_language_code`). + repeated string supported_language_codes = 4; + + // Required. The time zone of this agent from the + // [time zone database](https://www.iana.org/time-zones), e.g., + // America/New_York, Europe/Paris. + string time_zone = 5; + + // Optional. The description of this agent. + // The maximum length is 500 characters. If exceeded, the request is rejected. + string description = 6; + + // Optional. The URI of the agent's avatar. + // Avatars are used throughout the Dialogflow console and in the self-hosted + // [Web + // Demo](https://cloud.google.com/dialogflow-enterprise/docs/integrations/web-demo) + // integration. + string avatar_uri = 7; + + // Optional. Determines whether this agent should log conversation queries. + bool enable_logging = 8; + + // Optional. Determines how intents are detected from user queries. + MatchMode match_mode = 9; + + // Optional. To filter out false positive results and still get variety in + // matched natural language inputs for your agent, you can tune the machine + // learning classification threshold. If the returned score value is less than + // the threshold value, then a fallback intent will be triggered or, if there + // are no fallback intents defined, no intent will be triggered. The score + // values range from 0.0 (completely uncertain) to 1.0 (completely certain). + // If set to 0.0, the default of 0.3 is used. + float classification_threshold = 10; +} + +// The request message for [Agents.GetAgent][google.cloud.dialogflow.v2beta1.Agents.GetAgent]. +message GetAgentRequest { + // Required. The project that the agent to fetch is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; +} + +// The request message for [Agents.SearchAgents][google.cloud.dialogflow.v2beta1.Agents.SearchAgents]. +message SearchAgentsRequest { + // Required. The project to list agents from. + // Format: `projects/<Project ID or '-'>`. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// The response message for [Agents.SearchAgents][google.cloud.dialogflow.v2beta1.Agents.SearchAgents]. +message SearchAgentsResponse { + // The list of agents. There will be a maximum number of items returned based + // on the page_size field in the request. + repeated Agent agents = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [Agents.TrainAgent][google.cloud.dialogflow.v2beta1.Agents.TrainAgent]. +message TrainAgentRequest { + // Required. The project that the agent to train is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; +} + +// The request message for [Agents.ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent]. +message ExportAgentRequest { + // Required. The project that the agent to export is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Optional. The + // [Google Cloud Storage](https://cloud.google.com/storage/docs/) + // URI to export the agent to. + // The format of this URI must be `gs://<bucket-name>/<object-name>`. + // If left unspecified, the serialized agent is returned inline. + string agent_uri = 2; +} + +// The response message for [Agents.ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent]. +message ExportAgentResponse { + // Required. The exported agent. + oneof agent { + // The URI to a file containing the exported agent. This field is populated + // only if `agent_uri` is specified in `ExportAgentRequest`. + string agent_uri = 1; + + // The exported agent. + // + // Example for how to export an agent to a zip file via a command line: + // <pre>curl \ + // 'https://dialogflow.googleapis.com/v2beta1/projects/<project_name>/agent:export'\ + // -X POST \ + // -H 'Authorization: Bearer '$(gcloud auth application-default + // print-access-token) \ + // -H 'Accept: application/json' \ + // -H 'Content-Type: application/json' \ + // --compressed \ + // --data-binary '{}' \ + // | grep agentContent | sed -e 's/.*"agentContent": "\([^"]*\)".*/\1/' \ + // | base64 --decode > <agent zip file></pre> + bytes agent_content = 2; + } +} + +// The request message for [Agents.ImportAgent][google.cloud.dialogflow.v2beta1.Agents.ImportAgent]. +message ImportAgentRequest { + // Required. The project that the agent to import is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Required. The agent to import. + oneof agent { + // The URI to a Google Cloud Storage file containing the agent to import. + // Note: The URI must start with "gs://". + string agent_uri = 2; + + // The agent to import. + // + // Example for how to import an agent via the command line: + // <pre>curl \ + // 'https://dialogflow.googleapis.com/v2beta1/projects/<project_name>/agent:import\ + // -X POST \ + // -H 'Authorization: Bearer '$(gcloud auth application-default + // print-access-token) \ + // -H 'Accept: application/json' \ + // -H 'Content-Type: application/json' \ + // --compressed \ + // --data-binary "{ + // 'agentContent': '$(cat <agent zip file> | base64 -w 0)' + // }"</pre> + bytes agent_content = 3; + } +} + +// The request message for [Agents.RestoreAgent][google.cloud.dialogflow.v2beta1.Agents.RestoreAgent]. +message RestoreAgentRequest { + // Required. The project that the agent to restore is associated with. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Required. The agent to restore. + oneof agent { + // The URI to a Google Cloud Storage file containing the agent to restore. + // Note: The URI must start with "gs://". + string agent_uri = 2; + + // The agent to restore. + // + // Example for how to restore an agent via the command line: + // <pre>curl \ + // 'https://dialogflow.googleapis.com/v2beta1/projects/<project_name>/agent:restore\ + // -X POST \ + // -H 'Authorization: Bearer '$(gcloud auth application-default + // print-access-token) \ + // -H 'Accept: application/json' \ + // -H 'Content-Type: application/json' \ + // --compressed \ + // --data-binary "{ + // 'agentContent': '$(cat <agent zip file> | base64 -w 0)' + // }"</pre> + bytes agent_content = 3; + } +} diff --git a/google/cloud/dialogflow/v2beta1/audio_config.proto b/google/cloud/dialogflow/v2beta1/audio_config.proto new file mode 100644 index 000000000..8045290b2 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/audio_config.proto @@ -0,0 +1,216 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "AudioConfigProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// Audio encoding of the audio content sent in the conversational query request. +// Refer to the +// [Cloud Speech API +// documentation](https://cloud.google.com/speech-to-text/docs/basics) for more +// details. +enum AudioEncoding { + // Not specified. + AUDIO_ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + AUDIO_ENCODING_LINEAR_16 = 1; + + // [`FLAC`](https://xiph.org/flac/documentation.html) (Free Lossless Audio + // Codec) is the recommended encoding because it is lossless (therefore + // recognition is not compromised) and requires only about half the + // bandwidth of `LINEAR16`. `FLAC` stream encoding supports 16-bit and + // 24-bit samples, however, not all fields in `STREAMINFO` are supported. + AUDIO_ENCODING_FLAC = 2; + + // 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law. + AUDIO_ENCODING_MULAW = 3; + + // Adaptive Multi-Rate Narrowband codec. `sample_rate_hertz` must be 8000. + AUDIO_ENCODING_AMR = 4; + + // Adaptive Multi-Rate Wideband codec. `sample_rate_hertz` must be 16000. + AUDIO_ENCODING_AMR_WB = 5; + + // Opus encoded audio frames in Ogg container + // ([OggOpus](https://wiki.xiph.org/OggOpus)). + // `sample_rate_hertz` must be 16000. + AUDIO_ENCODING_OGG_OPUS = 6; + + // Although the use of lossy encodings is not recommended, if a very low + // bitrate encoding is required, `OGG_OPUS` is highly preferred over + // Speex encoding. The [Speex](https://speex.org/) encoding supported by + // Dialogflow API has a header byte in each block, as in MIME type + // `audio/x-speex-with-header-byte`. + // It is a variant of the RTP Speex encoding defined in + // [RFC 5574](https://tools.ietf.org/html/rfc5574). + // The stream is a sequence of blocks, one block per RTP packet. Each block + // starts with a byte containing the length of the block, in bytes, followed + // by one or more frames of Speex data, padded to an integral number of + // bytes (octets) as specified in RFC 5574. In other words, each RTP header + // is replaced with a single byte containing the block length. Only Speex + // wideband is supported. `sample_rate_hertz` must be 16000. + AUDIO_ENCODING_SPEEX_WITH_HEADER_BYTE = 7; +} + +// Instructs the speech recognizer how to process the audio content. +message InputAudioConfig { + // Required. Audio encoding of the audio content to process. + AudioEncoding audio_encoding = 1; + + // Required. Sample rate (in Hertz) of the audio content sent in the query. + // Refer to + // [Cloud Speech API + // documentation](https://cloud.google.com/speech-to-text/docs/basics) for + // more details. + int32 sample_rate_hertz = 2; + + // Required. The language of the supplied audio. Dialogflow does not do + // translations. See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. Note that queries in + // the same session do not necessarily need to specify the same language. + string language_code = 3; + + // Optional. The collection of phrase hints which are used to boost accuracy + // of speech recognition. + // Refer to + // [Cloud Speech API + // documentation](https://cloud.google.com/speech-to-text/docs/basics#phrase-hints) + // for more details. + repeated string phrase_hints = 4; + + // Optional. Which Speech model to select for the given request. Select the + // model best suited to your domain to get best results. If a model is not + // explicitly specified, then we auto-select a model based on the parameters + // in the InputAudioConfig. + // If enhanced speech model is enabled for the agent and an enhanced + // version of the specified model for the language does not exist, then the + // speech is recognized using the standard version of the specified model. + // Refer to + // [Cloud Speech API + // documentation](https://cloud.google.com/speech-to-text/docs/basics#select-model) + // for more details. + string model = 7; +} + +// Gender of the voice as described in +// [SSML voice element](https://www.w3.org/TR/speech-synthesis11/#edef_voice). +enum SsmlVoiceGender { + // An unspecified gender, which means that the client doesn't care which + // gender the selected voice will have. + SSML_VOICE_GENDER_UNSPECIFIED = 0; + + // A male voice. + SSML_VOICE_GENDER_MALE = 1; + + // A female voice. + SSML_VOICE_GENDER_FEMALE = 2; + + // A gender-neutral voice. + SSML_VOICE_GENDER_NEUTRAL = 3; +} + +// Description of which voice to use for speech synthesis. +message VoiceSelectionParams { + // Optional. The name of the voice. If not set, the service will choose a + // voice based on the other parameters such as language_code and gender. + string name = 1; + + // Optional. The preferred gender of the voice. If not set, the service will + // choose a voice based on the other parameters such as language_code and + // name. Note that this is only a preference, not requirement. If a + // voice of the appropriate gender is not available, the synthesizer should + // substitute a voice with a different gender rather than failing the request. + SsmlVoiceGender ssml_gender = 2; +} + +// Configuration of how speech should be synthesized. +message SynthesizeSpeechConfig { + // Optional. Speaking rate/speed, in the range [0.25, 4.0]. 1.0 is the normal + // native speed supported by the specific voice. 2.0 is twice as fast, and + // 0.5 is half as fast. If unset(0.0), defaults to the native 1.0 speed. Any + // other values < 0.25 or > 4.0 will return an error. + double speaking_rate = 1; + + // Optional. Speaking pitch, in the range [-20.0, 20.0]. 20 means increase 20 + // semitones from the original pitch. -20 means decrease 20 semitones from the + // original pitch. + double pitch = 2; + + // Optional. Volume gain (in dB) of the normal native volume supported by the + // specific voice, in the range [-96.0, 16.0]. If unset, or set to a value of + // 0.0 (dB), will play at normal native signal amplitude. A value of -6.0 (dB) + // will play at approximately half the amplitude of the normal native signal + // amplitude. A value of +6.0 (dB) will play at approximately twice the + // amplitude of the normal native signal amplitude. We strongly recommend not + // to exceed +10 (dB) as there's usually no effective increase in loudness for + // any value greater than that. + double volume_gain_db = 3; + + // Optional. An identifier which selects 'audio effects' profiles that are + // applied on (post synthesized) text to speech. Effects are applied on top of + // each other in the order they are given. + repeated string effects_profile_id = 5; + + // Optional. The desired voice of the synthesized audio. + VoiceSelectionParams voice = 4; +} + +// Audio encoding of the output audio format in Text-To-Speech. +enum OutputAudioEncoding { + // Not specified. + OUTPUT_AUDIO_ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + // Audio content returned as LINEAR16 also contains a WAV header. + OUTPUT_AUDIO_ENCODING_LINEAR_16 = 1; + + // MP3 audio. + OUTPUT_AUDIO_ENCODING_MP3 = 2; + + // Opus encoded audio wrapped in an ogg container. The result will be a + // file which can be played natively on Android, and in browsers (at least + // Chrome and Firefox). The quality of the encoding is considerably higher + // than MP3 while using approximately the same bitrate. + OUTPUT_AUDIO_ENCODING_OGG_OPUS = 3; +} + +// Instructs the speech synthesizer how to generate the output audio content. +message OutputAudioConfig { + // Required. Audio encoding of the synthesized audio content. + OutputAudioEncoding audio_encoding = 1; + + // Optional. The synthesis sample rate (in hertz) for this audio. If not + // provided, then the synthesizer will use the default sample rate based on + // the audio encoding. If this is different from the voice's natural sample + // rate, then the synthesizer will honor this request by converting to the + // desired sample rate (which might result in worse audio quality). + int32 sample_rate_hertz = 2; + + // Optional. Configuration of how speech should be synthesized. + SynthesizeSpeechConfig synthesize_speech_config = 3; +} diff --git a/google/cloud/dialogflow/v2beta1/context.proto b/google/cloud/dialogflow/v2beta1/context.proto new file mode 100644 index 000000000..bd5926aa4 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/context.proto @@ -0,0 +1,229 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "ContextProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// A context represents additional information included with user input or with +// an intent returned by the Dialogflow API. Contexts are helpful for +// differentiating user input which may be vague or have a different meaning +// depending on additional details from your application such as user setting +// and preferences, previous user input, where the user is in your application, +// geographic location, and so on. +// +// You can include contexts as input parameters of a +// [DetectIntent][google.cloud.dialogflow.v2beta1.Sessions.DetectIntent] (or +// [StreamingDetectIntent][google.cloud.dialogflow.v2beta1.Sessions.StreamingDetectIntent]) request, +// or as output contexts included in the returned intent. +// Contexts expire when an intent is matched, after the number of `DetectIntent` +// requests specified by the `lifespan_count` parameter, or after 20 minutes +// if no intents are matched for a `DetectIntent` request. +// +// For more information about contexts, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/contexts-overview). +service Contexts { + // Returns the list of all contexts in the specified session. + rpc ListContexts(ListContextsRequest) returns (ListContextsResponse) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*/agent/sessions/*}/contexts" + additional_bindings { + get: "/v2beta1/{parent=projects/*/agent/environments/*/users/*/sessions/*}/contexts" + } + }; + } + + // Retrieves the specified context. + rpc GetContext(GetContextRequest) returns (Context) { + option (google.api.http) = { + get: "/v2beta1/{name=projects/*/agent/sessions/*/contexts/*}" + additional_bindings { + get: "/v2beta1/{name=projects/*/agent/environments/*/users/*/sessions/*/contexts/*}" + } + }; + } + + // Creates a context. + // + // If the specified context already exists, overrides the context. + rpc CreateContext(CreateContextRequest) returns (Context) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent/sessions/*}/contexts" + body: "context" + additional_bindings { + post: "/v2beta1/{parent=projects/*/agent/environments/*/users/*/sessions/*}/contexts" + body: "context" + } + }; + } + + // Updates the specified context. + rpc UpdateContext(UpdateContextRequest) returns (Context) { + option (google.api.http) = { + patch: "/v2beta1/{context.name=projects/*/agent/sessions/*/contexts/*}" + body: "context" + additional_bindings { + patch: "/v2beta1/{context.name=projects/*/agent/environments/*/users/*/sessions/*/contexts/*}" + body: "context" + } + }; + } + + // Deletes the specified context. + rpc DeleteContext(DeleteContextRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta1/{name=projects/*/agent/sessions/*/contexts/*}" + additional_bindings { + delete: "/v2beta1/{name=projects/*/agent/environments/*/users/*/sessions/*/contexts/*}" + } + }; + } + + // Deletes all active contexts in the specified session. + rpc DeleteAllContexts(DeleteAllContextsRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta1/{parent=projects/*/agent/sessions/*}/contexts" + additional_bindings { + delete: "/v2beta1/{parent=projects/*/agent/environments/*/users/*/sessions/*}/contexts" + } + }; + } +} + +// Represents a context. +message Context { + // Required. The unique identifier of the context. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>`, + // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>/contexts/<Context ID>`. + // + // The `Context ID` is always converted to lowercase, may only contain + // characters in a-zA-Z0-9_-% and may be at most 250 bytes long. + // + // If `Environment ID` is not specified, we assume default 'draft' + // environment. If `User ID` is not specified, we assume default '-' user. + string name = 1; + + // Optional. The number of conversational query requests after which the + // context expires. If set to `0` (the default) the context expires + // immediately. Contexts expire automatically after 20 minutes if there + // are no matching queries. + int32 lifespan_count = 2; + + // Optional. The collection of parameters associated with this context. + // Refer to [this + // doc](https://cloud.google.com/dialogflow-enterprise/docs/intents-actions-parameters) + // for syntax. + google.protobuf.Struct parameters = 3; +} + +// The request message for [Contexts.ListContexts][google.cloud.dialogflow.v2beta1.Contexts.ListContexts]. +message ListContextsRequest { + // Required. The session to list all contexts from. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>`. If `Environment ID` is not specified, we assume + // default 'draft' environment. If `User ID` is not specified, we assume + // default '-' user. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// The response message for [Contexts.ListContexts][google.cloud.dialogflow.v2beta1.Contexts.ListContexts]. +message ListContextsResponse { + // The list of contexts. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated Context contexts = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [Contexts.GetContext][google.cloud.dialogflow.v2beta1.Contexts.GetContext]. +message GetContextRequest { + // Required. The name of the context. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>` + // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>/contexts/<Context ID>`. If `Environment ID` is + // not specified, we assume default 'draft' environment. If `User ID` is not + // specified, we assume default '-' user. + string name = 1; +} + +// The request message for [Contexts.CreateContext][google.cloud.dialogflow.v2beta1.Contexts.CreateContext]. +message CreateContextRequest { + // Required. The session to create a context for. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>`. If `Environment ID` is not specified, we assume + // default 'draft' environment. If `User ID` is not specified, we assume + // default '-' user. + string parent = 1; + + // Required. The context to create. + Context context = 2; +} + +// The request message for [Contexts.UpdateContext][google.cloud.dialogflow.v2beta1.Contexts.UpdateContext]. +message UpdateContextRequest { + // Required. The context to update. + Context context = 1; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 2; +} + +// The request message for [Contexts.DeleteContext][google.cloud.dialogflow.v2beta1.Contexts.DeleteContext]. +message DeleteContextRequest { + // Required. The name of the context to delete. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>` + // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>/contexts/<Context ID>`. If `Environment ID` is + // not specified, we assume default 'draft' environment. If `User ID` is not + // specified, we assume default '-' user. + string name = 1; +} + +// The request message for [Contexts.DeleteAllContexts][google.cloud.dialogflow.v2beta1.Contexts.DeleteAllContexts]. +message DeleteAllContextsRequest { + // Required. The name of the session to delete all contexts from. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>` or `projects/<Project + // ID>/agent/environments/<Environment ID>/users/<User ID>/sessions/<Session + // ID>`. If `Environment ID` is not specified we assume default 'draft' + // environment. If `User ID` is not specified, we assume default '-' user. + string parent = 1; +} diff --git a/google/cloud/dialogflow/v2beta1/dialogflow_gapic.yaml b/google/cloud/dialogflow/v2beta1/dialogflow_gapic.yaml new file mode 100644 index 000000000..ff7ab5002 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/dialogflow_gapic.yaml @@ -0,0 +1,1588 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.dialogflow.v2beta1 + release_level: BETA + python: + package_name: google.cloud.dialogflow_v2beta1.gapic + go: + package_name: cloud.google.com/go/cloud/dialogflow/apiv2beta1 + csharp: + package_name: Google.Cloud.Dialogflow.V2Beta1 + ruby: + package_name: Google::Cloud::Dialogflow::V2beta1 + php: + package_name: Google\Cloud\Dialogflow\V2beta1 + nodejs: + package_name: dialogflow.v2beta1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.Agents + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: GetAgent + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: SearchAgents + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: agents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: TrainAgent + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(train_agent_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: ExportAgent + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(export_agent_long_running_operation) + return_type: google.cloud.dialogflow.v2beta1.ExportAgentResponse + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: ImportAgent + required_fields: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(import_agent_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: RestoreAgent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + long_running: + # LINT.IfChange(restore_agent_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.Contexts + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent/sessions/{session} + entity_name: session + - name_pattern: projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session} + entity_name: environment_session + - name_pattern: projects/{project}/agent/sessions/{session}/contexts/{context} + entity_name: context + - name_pattern: projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}/contexts/{context} + entity_name: environment_context + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListContexts + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: contexts + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetContext + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: context + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateContext + flattening: + groups: + - parameters: + - parent + - context + required_fields: + - parent + - context + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateContext + flattening: + groups: + - parameters: + - context + required_fields: + - context + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + context.name: context + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteContext + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: context + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteAllContexts + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.EntityTypes + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent + entity_name: project_agent + - name_pattern: projects/{project}/agent/entityTypes/{entity_type} + entity_name: entity_type + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListEntityTypes + flattening: + groups: + - parameters: + - parent + - parameters: + - parent + - language_code + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: entity_types + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetEntityType + flattening: + groups: + - parameters: + - name + - parameters: + - name + - language_code + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateEntityType + flattening: + groups: + - parameters: + - parent + - entity_type + - parameters: + - parent + - entity_type + - language_code + required_fields: + - parent + - entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateEntityType + flattening: + groups: + - parameters: + - entity_type + - parameters: + - entity_type + - language_code + required_fields: + - entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + entity_type.name: entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteEntityType + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: BatchUpdateEntityTypes + required_fields: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_update_entity_types_long_running_operation) + return_type: google.cloud.dialogflow.v2beta1.BatchUpdateEntityTypesResponse + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchDeleteEntityTypes + flattening: + groups: + - parameters: + - parent + - entity_type_names + required_fields: + - parent + - entity_type_names + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_delete_entity_types_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchCreateEntities + flattening: + groups: + - parameters: + - parent + - entities + - parameters: + - parent + - entities + - language_code + required_fields: + - parent + - entities + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: entity_type + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_create_entities_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchUpdateEntities + flattening: + groups: + - parameters: + - parent + - entities + - parameters: + - parent + - entities + - language_code + required_fields: + - parent + - entities + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: entity_type + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_update_entities_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchDeleteEntities + flattening: + groups: + - parameters: + - parent + - entity_values + - parameters: + - parent + - entity_values + - language_code + required_fields: + - parent + - entity_values + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: entity_type + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_delete_entities_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.Intents + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent + entity_name: project_agent + - name_pattern: projects/{project}/agent/intents/{intent} + entity_name: intent + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListIntents + flattening: + groups: + - parameters: + - parent + - parameters: + - parent + - language_code + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: intents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetIntent + flattening: + groups: + - parameters: + - name + - parameters: + - name + - language_code + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: intent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateIntent + flattening: + groups: + - parameters: + - parent + - intent + - parameters: + - parent + - intent + - language_code + required_fields: + - parent + - intent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateIntent + flattening: + groups: + - parameters: + - intent + - language_code + - parameters: + - intent + - language_code + - update_mask + required_fields: + - intent + - language_code + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + intent.name: intent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteIntent + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: intent + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: BatchUpdateIntents + required_fields: + - parent + - language_code + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_update_intents_long_running_operation) + return_type: google.cloud.dialogflow.v2beta1.BatchUpdateIntentsResponse + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: BatchDeleteIntents + flattening: + groups: + - parameters: + - parent + - intents + required_fields: + - parent + - intents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project_agent + timeout_millis: 60000 + long_running: + # LINT.IfChange(batch_delete_intents_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Struct + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.SessionEntityTypes + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent/sessions/{session} + entity_name: session + - name_pattern: projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session} + entity_name: environment_session + - name_pattern: projects/{project}/agent/sessions/{session}/entityTypes/{entity_type} + entity_name: session_entity_type + - name_pattern: projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}/entityTypes/{entity_type} + entity_name: environment_session_entity_type + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListSessionEntityTypes + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: session_entity_types + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetSessionEntityType + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: session_entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateSessionEntityType + flattening: + groups: + - parameters: + - parent + - session_entity_type + required_fields: + - parent + - session_entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: session + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateSessionEntityType + flattening: + groups: + - parameters: + - session_entity_type + required_fields: + - session_entity_type + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + session_entity_type.name: session_entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteSessionEntityType + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: session_entity_type + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.Sessions + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/agent/sessions/{session} + entity_name: session + - name_pattern: projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session} + entity_name: environment_session + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: DetectIntent + flattening: + groups: + - parameters: + - session + - query_input + required_fields: + - session + - query_input + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + session: session + timeout_millis: 220000 + resource_name_treatment: STATIC_TYPES + - name: StreamingDetectIntent + required_fields: + - session + - query_input + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 220000 + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.KnowledgeBases + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + - name_pattern: projects/{project}/knowledgeBases/{knowledge_base} + entity_name: knowledge_base + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListKnowledgeBases + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: knowledge_bases + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetKnowledgeBase + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: knowledge_base + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateKnowledgeBase + flattening: + groups: + - parameters: + - parent + - knowledge_base + required_fields: + - parent + - knowledge_base + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteKnowledgeBase + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: knowledge_base + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + # The fully qualified name of the API interface. +- name: google.cloud.dialogflow.v2beta1.Documents + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/knowledgeBases/{knowledge_base} + entity_name: knowledge_base + - name_pattern: projects/{project}/knowledgeBases/{knowledge_base}/documents/{document} + entity_name: document + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListDocuments + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: documents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: knowledge_base + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetDocument + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: document + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: CreateDocument + flattening: + groups: + - parameters: + - parent + - document + required_fields: + - parent + - document + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: knowledge_base + timeout_millis: 60000 + long_running: + # LINT.IfChange(create_document_long_running_operation) + return_type: google.cloud.dialogflow.v2beta1.Document + metadata_type: google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES + - name: DeleteDocument + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: document + timeout_millis: 60000 + long_running: + # LINT.IfChange(delete_document_long_running_operation) + return_type: google.protobuf.Empty + metadata_type: google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata + # LINT.ThenChange() + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + resource_name_treatment: STATIC_TYPES +resource_name_generation: +- message_name: GetAgentRequest + field_entity_map: + parent: project +- message_name: SearchAgentsRequest + field_entity_map: + parent: project +- message_name: TrainAgentRequest + field_entity_map: + parent: project +- message_name: ExportAgentRequest + field_entity_map: + parent: project +- message_name: ImportAgentRequest + field_entity_map: + parent: project +- message_name: RestoreAgentRequest + field_entity_map: + parent: project +- message_name: CreateAogVersionRequest + field_entity_map: + parent: project +- message_name: WarmUpAogVersionRequest + field_entity_map: + parent: project +- message_name: ListContextsRequest + field_entity_map: + parent: session +- message_name: GetContextRequest + field_entity_map: + name: context +- message_name: CreateContextRequest + field_entity_map: + parent: session +- message_name: Context + field_entity_map: + name: context +- message_name: DeleteContextRequest + field_entity_map: + name: context +- message_name: DeleteAllContextsRequest + field_entity_map: + parent: session +- message_name: ListEntityTypesRequest + field_entity_map: + parent: project_agent +- message_name: GetEntityTypeRequest + field_entity_map: + name: entity_type +- message_name: CreateEntityTypeRequest + field_entity_map: + parent: project_agent +- message_name: EntityType + field_entity_map: + name: entity_type +- message_name: DeleteEntityTypeRequest + field_entity_map: + name: entity_type +- message_name: BatchUpdateEntityTypesRequest + field_entity_map: + parent: project_agent +- message_name: BatchDeleteEntityTypesRequest + field_entity_map: + parent: project_agent +- message_name: BatchCreateEntitiesRequest + field_entity_map: + parent: entity_type +- message_name: BatchUpdateEntitiesRequest + field_entity_map: + parent: entity_type +- message_name: BatchDeleteEntitiesRequest + field_entity_map: + parent: entity_type +- message_name: ListIntentsRequest + field_entity_map: + parent: project_agent +- message_name: GetIntentRequest + field_entity_map: + name: intent +- message_name: CreateIntentRequest + field_entity_map: + parent: project_agent +- message_name: Intent + field_entity_map: + name: intent +- message_name: DeleteIntentRequest + field_entity_map: + name: intent +- message_name: BatchUpdateIntentsRequest + field_entity_map: + parent: project_agent +- message_name: BatchDeleteIntentsRequest + field_entity_map: + parent: project_agent +- message_name: ListSessionEntityTypesRequest + field_entity_map: + parent: session +- message_name: GetSessionEntityTypeRequest + field_entity_map: + name: session_entity_type +- message_name: CreateSessionEntityTypeRequest + field_entity_map: + parent: session +- message_name: SessionEntityType + field_entity_map: + name: session_entity_type +- message_name: DeleteSessionEntityTypeRequest + field_entity_map: + name: session_entity_type +- message_name: DetectIntentRequest + field_entity_map: + session: session +- message_name: ListKnowledgeBasesRequest + field_entity_map: + parent: project +- message_name: GetKnowledgeBaseRequest + field_entity_map: + name: knowledge_base +- message_name: CreateKnowledgeBaseRequest + field_entity_map: + parent: project +- message_name: KnowledgeBase + field_entity_map: + name: knowledge_base +- message_name: DeleteKnowledgeBaseRequest + field_entity_map: + name: knowledge_base +- message_name: ListDocumentsRequest + field_entity_map: + parent: knowledge_base +- message_name: GetDocumentRequest + field_entity_map: + name: document +- message_name: CreateDocumentRequest + field_entity_map: + parent: knowledge_base +- message_name: Document + field_entity_map: + name: document +- message_name: DeleteDocumentRequest + field_entity_map: + name: document diff --git a/google/cloud/dialogflow/v2beta1/document.proto b/google/cloud/dialogflow/v2beta1/document.proto new file mode 100644 index 000000000..8bf7dbf7c --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/document.proto @@ -0,0 +1,270 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "DocumentProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// Manages documents of a knowledge base. +service Documents { + // Returns the list of all documents of the knowledge base. + rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*/knowledgeBases/*}/documents" + additional_bindings { + get: "/v2beta1/{parent=projects/*/agent/knowledgeBases/*}/documents" + } + }; + } + + // Retrieves the specified document. + rpc GetDocument(GetDocumentRequest) returns (Document) { + option (google.api.http) = { + get: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}" + additional_bindings { + get: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}" + } + }; + } + + // Creates a new document. + // + // Operation <response: [Document][google.cloud.dialogflow.v2beta1.Document], + // metadata: [KnowledgeOperationMetadata][google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata]> + rpc CreateDocument(CreateDocumentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/knowledgeBases/*}/documents" + body: "document" + additional_bindings { + post: "/v2beta1/{parent=projects/*/agent/knowledgeBases/*}/documents" + body: "document" + } + }; + } + + // Deletes the specified document. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty], + // metadata: [KnowledgeOperationMetadata][google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata]> + rpc DeleteDocument(DeleteDocumentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}" + additional_bindings { + delete: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}" + } + }; + } + + // Updates the specified document. + // Operation <response: [Document][google.cloud.dialogflow.v2beta1.Document], + // metadata: [KnowledgeOperationMetadata][google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata]> + rpc UpdateDocument(UpdateDocumentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v2beta1/{document.name=projects/*/knowledgeBases/*/documents/*}" + body: "document" + additional_bindings { + patch: "/v2beta1/{document.name=projects/*/agent/knowledgeBases/*/documents/*}" + body: "document" + } + }; + } + + // Reloads the specified document from its specified source, content_uri or + // content. The previously loaded content of the document will be deleted. + // Note: Even when the content of the document has not changed, there still + // may be side effects because of internal implementation changes. + // Operation <response: [Document][google.cloud.dialogflow.v2beta1.Document], + // metadata: [KnowledgeOperationMetadata][google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata]> + rpc ReloadDocument(ReloadDocumentRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}:reload" + body: "*" + additional_bindings { + post: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}:reload" + body: "*" + } + }; + } +} + +// A document resource. +// +// Note: resource `projects.agent.knowledgeBases.documents` is deprecated, +// please use `projects.knowledgeBases.documents` instead. +message Document { + // The knowledge type of document content. + enum KnowledgeType { + // The type is unspecified or arbitrary. + KNOWLEDGE_TYPE_UNSPECIFIED = 0; + + // The document content contains question and answer pairs as either HTML or + // CSV. Typical FAQ HTML formats are parsed accurately, but unusual formats + // may fail to be parsed. + // + // CSV must have questions in the first column and answers in the second, + // with no header. Because of this explicit format, they are always parsed + // accurately. + FAQ = 1; + + // Documents for which unstructured text is extracted and used for + // question answering. + EXTRACTIVE_QA = 2; + } + + // The document resource name. + // The name must be empty when creating a document. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base + // ID>/documents/<Document ID>`. + string name = 1; + + // Required. The display name of the document. The name must be 1024 bytes or + // less; otherwise, the creation request fails. + string display_name = 2; + + // Required. The MIME type of this document. + string mime_type = 3; + + // Required. The knowledge type of document content. + repeated KnowledgeType knowledge_types = 4; + + // Required. The source of this document. + oneof source { + // The URI where the file content is located. + // + // For documents stored in Google Cloud Storage, these URIs must have + // the form `gs://<bucket-name>/<object-name>`. + // + // NOTE: External URLs must correspond to public webpages, i.e., they must + // be indexed by Google Search. In particular, URLs for showing documents in + // Google Cloud Storage (i.e. the URL in your browser) are not supported. + // Instead use the `gs://` format URI described above. + string content_uri = 5; + + // The raw content of the document. This field is only permitted for + // EXTRACTIVE_QA and FAQ knowledge types. + // Note: This field is in the process of being deprecated, please use + // raw_content instead. + string content = 6 [deprecated = true]; + + // The raw content of the document. This field is only permitted for + // EXTRACTIVE_QA and FAQ knowledge types. + bytes raw_content = 9; + } +} + +// Request message for [Documents.ListDocuments][google.cloud.dialogflow.v2beta1.Documents.ListDocuments]. +message ListDocumentsRequest { + // Required. The knowledge base to list all documents for. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 10 and at most 100. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// Response message for [Documents.ListDocuments][google.cloud.dialogflow.v2beta1.Documents.ListDocuments]. +message ListDocumentsResponse { + // The list of documents. + repeated Document documents = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// Request message for [Documents.GetDocument][google.cloud.dialogflow.v2beta1.Documents.GetDocument]. +message GetDocumentRequest { + // Required. The name of the document to retrieve. + // Format `projects/<Project ID>/knowledgeBases/<Knowledge Base + // ID>/documents/<Document ID>`. + string name = 1; +} + +// Request message for [Documents.CreateDocument][google.cloud.dialogflow.v2beta1.Documents.CreateDocument]. +message CreateDocumentRequest { + // Required. The knoweldge base to create a document for. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`. + string parent = 1; + + // Required. The document to create. + Document document = 2; +} + +// Request message for [Documents.DeleteDocument][google.cloud.dialogflow.v2beta1.Documents.DeleteDocument]. +message DeleteDocumentRequest { + // The name of the document to delete. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base + // ID>/documents/<Document ID>`. + string name = 1; +} + +// Request message for [Documents.UpdateDocument][google.cloud.dialogflow.v2beta1.Documents.UpdateDocument]. +message UpdateDocumentRequest { + // Required. The document to update. + Document document = 1; + + // Optional. Not specified means `update all`. + // Currently, only `display_name` can be updated, an InvalidArgument will be + // returned for attempting to update other fields. + google.protobuf.FieldMask update_mask = 2; +} + +// Metadata in google::longrunning::Operation for Knowledge operations. +message KnowledgeOperationMetadata { + // States of the operation. + enum State { + // State unspecified. + STATE_UNSPECIFIED = 0; + + // The operation has been created. + PENDING = 1; + + // The operation is currently running. + RUNNING = 2; + + // The operation is done, either cancelled or completed. + DONE = 3; + } + + // Required. The current state of this operation. + State state = 1; +} + +// Request message for [Documents.ReloadDocument][google.cloud.dialogflow.v2beta1.Documents.ReloadDocument]. +message ReloadDocumentRequest { + // The name of the document to reload. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base + // ID>/documents/<Document ID>` + string name = 1; +} diff --git a/google/cloud/dialogflow/v2beta1/entity_type.proto b/google/cloud/dialogflow/v2beta1/entity_type.proto new file mode 100644 index 000000000..c49561ff3 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/entity_type.proto @@ -0,0 +1,436 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "EntityTypeProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// Entities are extracted from user input and represent parameters that are +// meaningful to your application. For example, a date range, a proper name +// such as a geographic location or landmark, and so on. Entities represent +// actionable data for your application. +// +// When you define an entity, you can also include synonyms that all map to +// that entity. For example, "soft drink", "soda", "pop", and so on. +// +// There are three types of entities: +// +// * **System** - entities that are defined by the Dialogflow API for common +// data types such as date, time, currency, and so on. A system entity is +// represented by the `EntityType` type. +// +// * **Developer** - entities that are defined by you that represent +// actionable data that is meaningful to your application. For example, +// you could define a `pizza.sauce` entity for red or white pizza sauce, +// a `pizza.cheese` entity for the different types of cheese on a pizza, +// a `pizza.topping` entity for different toppings, and so on. A developer +// entity is represented by the `EntityType` type. +// +// * **User** - entities that are built for an individual user such as +// favorites, preferences, playlists, and so on. A user entity is +// represented by the [SessionEntityType][google.cloud.dialogflow.v2beta1.SessionEntityType] type. +// +// For more information about entity types, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/entities-overview). +service EntityTypes { + // Returns the list of all entity types in the specified agent. + rpc ListEntityTypes(ListEntityTypesRequest) returns (ListEntityTypesResponse) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*/agent}/entityTypes" + }; + } + + // Retrieves the specified entity type. + rpc GetEntityType(GetEntityTypeRequest) returns (EntityType) { + option (google.api.http) = { + get: "/v2beta1/{name=projects/*/agent/entityTypes/*}" + }; + } + + // Creates an entity type in the specified agent. + rpc CreateEntityType(CreateEntityTypeRequest) returns (EntityType) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent}/entityTypes" + body: "entity_type" + }; + } + + // Updates the specified entity type. + rpc UpdateEntityType(UpdateEntityTypeRequest) returns (EntityType) { + option (google.api.http) = { + patch: "/v2beta1/{entity_type.name=projects/*/agent/entityTypes/*}" + body: "entity_type" + }; + } + + // Deletes the specified entity type. + rpc DeleteEntityType(DeleteEntityTypeRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta1/{name=projects/*/agent/entityTypes/*}" + }; + } + + // Updates/Creates multiple entity types in the specified agent. + // + // Operation <response: [BatchUpdateEntityTypesResponse][google.cloud.dialogflow.v2beta1.BatchUpdateEntityTypesResponse]> + rpc BatchUpdateEntityTypes(BatchUpdateEntityTypesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent}/entityTypes:batchUpdate" + body: "*" + }; + } + + // Deletes entity types in the specified agent. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchDeleteEntityTypes(BatchDeleteEntityTypesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent}/entityTypes:batchDelete" + body: "*" + }; + } + + // Creates multiple new entities in the specified entity type. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchCreateEntities(BatchCreateEntitiesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent/entityTypes/*}/entities:batchCreate" + body: "*" + }; + } + + // Updates or creates multiple entities in the specified entity type. This + // method does not affect entities in the entity type that aren't explicitly + // specified in the request. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchUpdateEntities(BatchUpdateEntitiesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent/entityTypes/*}/entities:batchUpdate" + body: "*" + }; + } + + // Deletes entities in the specified entity type. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchDeleteEntities(BatchDeleteEntitiesRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent/entityTypes/*}/entities:batchDelete" + body: "*" + }; + } +} + +// Represents an entity type. +// Entity types serve as a tool for extracting parameter values from natural +// language queries. +message EntityType { + // An **entity entry** for an associated entity type. + message Entity { + // Required. The primary value associated with this entity entry. + // For example, if the entity type is *vegetable*, the value could be + // *scallions*. + // + // For `KIND_MAP` entity types: + // + // * A canonical value to be used in place of synonyms. + // + // For `KIND_LIST` entity types: + // + // * A string that can contain references to other entity types (with or + // without aliases). + string value = 1; + + // Required. A collection of value synonyms. For example, if the entity type + // is *vegetable*, and `value` is *scallions*, a synonym could be *green + // onions*. + // + // For `KIND_LIST` entity types: + // + // * This collection must contain exactly one synonym equal to `value`. + repeated string synonyms = 2; + } + + // Represents kinds of entities. + enum Kind { + // Not specified. This value should be never used. + KIND_UNSPECIFIED = 0; + + // Map entity types allow mapping of a group of synonyms to a canonical + // value. + KIND_MAP = 1; + + // List entity types contain a set of entries that do not map to canonical + // values. However, list entity types can contain references to other entity + // types (with or without aliases). + KIND_LIST = 2; + } + + // Represents different entity type expansion modes. Automated expansion + // allows an agent to recognize values that have not been explicitly listed in + // the entity (for example, new kinds of shopping list items). + enum AutoExpansionMode { + // Auto expansion disabled for the entity. + AUTO_EXPANSION_MODE_UNSPECIFIED = 0; + + // Allows an agent to recognize values that have not been explicitly + // listed in the entity. + AUTO_EXPANSION_MODE_DEFAULT = 1; + } + + // The unique identifier of the entity type. + // Required for [EntityTypes.UpdateEntityType][google.cloud.dialogflow.v2beta1.EntityTypes.UpdateEntityType] and + // [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2beta1.EntityTypes.BatchUpdateEntityTypes] methods. + // Format: `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string name = 1; + + // Required. The name of the entity type. + string display_name = 2; + + // Required. Indicates the kind of entity type. + Kind kind = 3; + + // Optional. Indicates whether the entity type can be automatically + // expanded. + AutoExpansionMode auto_expansion_mode = 4; + + // Optional. The collection of entity entries associated with the entity type. + repeated Entity entities = 6; +} + +// The request message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2beta1.EntityTypes.ListEntityTypes]. +message ListEntityTypesRequest { + // Required. The agent to list all entity types from. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Optional. The language to list entity synonyms for. If not specified, + // the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 3; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 4; +} + +// The response message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2beta1.EntityTypes.ListEntityTypes]. +message ListEntityTypesResponse { + // The list of agent entity types. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated EntityType entity_types = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [EntityTypes.GetEntityType][google.cloud.dialogflow.v2beta1.EntityTypes.GetEntityType]. +message GetEntityTypeRequest { + // Required. The name of the entity type. + // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`. + string name = 1; + + // Optional. The language to retrieve entity synonyms for. If not specified, + // the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; +} + +// The request message for [EntityTypes.CreateEntityType][google.cloud.dialogflow.v2beta1.EntityTypes.CreateEntityType]. +message CreateEntityTypeRequest { + // Required. The agent to create a entity type for. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The entity type to create. + EntityType entity_type = 2; + + // Optional. The language of entity synonyms defined in `entity_type`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; +} + +// The request message for [EntityTypes.UpdateEntityType][google.cloud.dialogflow.v2beta1.EntityTypes.UpdateEntityType]. +message UpdateEntityTypeRequest { + // Required. The entity type to update. + EntityType entity_type = 1; + + // Optional. The language of entity synonyms defined in `entity_type`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 3; +} + +// The request message for [EntityTypes.DeleteEntityType][google.cloud.dialogflow.v2beta1.EntityTypes.DeleteEntityType]. +message DeleteEntityTypeRequest { + // Required. The name of the entity type to delete. + // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`. + string name = 1; +} + +// The request message for [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2beta1.EntityTypes.BatchUpdateEntityTypes]. +message BatchUpdateEntityTypesRequest { + // Required. The name of the agent to update or create entity types in. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The source of the entity type batch. + // + // For each entity type in the batch: + // + // * If `name` is specified, we update an existing entity type. + // * If `name` is not specified, we create a new entity type. + oneof entity_type_batch { + // The URI to a Google Cloud Storage file containing entity types to update + // or create. The file format can either be a serialized proto (of + // EntityBatch type) or a JSON object. Note: The URI must start with + // "gs://". + string entity_type_batch_uri = 2; + + // The collection of entity types to update or create. + EntityTypeBatch entity_type_batch_inline = 3; + } + + // Optional. The language of entity synonyms defined in `entity_types`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 4; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 5; +} + +// The response message for [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2beta1.EntityTypes.BatchUpdateEntityTypes]. +message BatchUpdateEntityTypesResponse { + // The collection of updated or created entity types. + repeated EntityType entity_types = 1; +} + +// The request message for [EntityTypes.BatchDeleteEntityTypes][google.cloud.dialogflow.v2beta1.EntityTypes.BatchDeleteEntityTypes]. +message BatchDeleteEntityTypesRequest { + // Required. The name of the agent to delete all entities types for. Format: + // `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The names entity types to delete. All names must point to the + // same agent as `parent`. + repeated string entity_type_names = 2; +} + +// The request message for [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2beta1.EntityTypes.BatchCreateEntities]. +message BatchCreateEntitiesRequest { + // Required. The name of the entity type to create entities in. Format: + // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string parent = 1; + + // Required. The entities to create. + repeated EntityType.Entity entities = 2; + + // Optional. The language of entity synonyms defined in `entities`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; +} + +// The request message for [EntityTypes.BatchUpdateEntities][google.cloud.dialogflow.v2beta1.EntityTypes.BatchUpdateEntities]. +message BatchUpdateEntitiesRequest { + // Required. The name of the entity type to update or create entities in. + // Format: `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string parent = 1; + + // Required. The entities to update or create. + repeated EntityType.Entity entities = 2; + + // Optional. The language of entity synonyms defined in `entities`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 4; +} + +// The request message for [EntityTypes.BatchDeleteEntities][google.cloud.dialogflow.v2beta1.EntityTypes.BatchDeleteEntities]. +message BatchDeleteEntitiesRequest { + // Required. The name of the entity type to delete entries for. Format: + // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`. + string parent = 1; + + // Required. The canonical `values` of the entities to delete. Note that + // these are not fully-qualified names, i.e. they don't start with + // `projects/<Project ID>`. + repeated string entity_values = 2; + + // Optional. The language of entity synonyms defined in `entities`. If not + // specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; +} + +// This message is a wrapper around a collection of entity types. +message EntityTypeBatch { + // A collection of entity types. + repeated EntityType entity_types = 1; +} diff --git a/google/cloud/dialogflow/v2beta1/intent.proto b/google/cloud/dialogflow/v2beta1/intent.proto new file mode 100644 index 000000000..9f33f88d2 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/intent.proto @@ -0,0 +1,924 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/dialogflow/v2beta1/context.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/struct.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "IntentProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// An intent represents a mapping between input from a user and an action to +// be taken by your application. When you pass user input to the +// [DetectIntent][google.cloud.dialogflow.v2beta1.Sessions.DetectIntent] (or +// [StreamingDetectIntent][google.cloud.dialogflow.v2beta1.Sessions.StreamingDetectIntent]) method, the +// Dialogflow API analyzes the input and searches +// for a matching intent. If no match is found, the Dialogflow API returns a +// fallback intent (`is_fallback` = true). +// +// You can provide additional information for the Dialogflow API to use to +// match user input to an intent by adding the following to your intent. +// +// * **Contexts** - provide additional context for intent analysis. For +// example, if an intent is related to an object in your application that +// plays music, you can provide a context to determine when to match the +// intent if the user input is "turn it off". You can include a context +// that matches the intent when there is previous user input of +// "play music", and not when there is previous user input of +// "turn on the light". +// +// * **Events** - allow for matching an intent by using an event name +// instead of user input. Your application can provide an event name and +// related parameters to the Dialogflow API to match an intent. For +// example, when your application starts, you can send a welcome event +// with a user name parameter to the Dialogflow API to match an intent with +// a personalized welcome message for the user. +// +// * **Training phrases** - provide examples of user input to train the +// Dialogflow API agent to better match intents. +// +// For more information about intents, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/intents-overview). +service Intents { + // Returns the list of all intents in the specified agent. + rpc ListIntents(ListIntentsRequest) returns (ListIntentsResponse) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*/agent}/intents" + }; + } + + // Retrieves the specified intent. + rpc GetIntent(GetIntentRequest) returns (Intent) { + option (google.api.http) = { + get: "/v2beta1/{name=projects/*/agent/intents/*}" + }; + } + + // Creates an intent in the specified agent. + rpc CreateIntent(CreateIntentRequest) returns (Intent) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent}/intents" + body: "intent" + }; + } + + // Updates the specified intent. + rpc UpdateIntent(UpdateIntentRequest) returns (Intent) { + option (google.api.http) = { + patch: "/v2beta1/{intent.name=projects/*/agent/intents/*}" + body: "intent" + }; + } + + // Deletes the specified intent and its direct or indirect followup intents. + rpc DeleteIntent(DeleteIntentRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta1/{name=projects/*/agent/intents/*}" + }; + } + + // Updates/Creates multiple intents in the specified agent. + // + // Operation <response: [BatchUpdateIntentsResponse][google.cloud.dialogflow.v2beta1.BatchUpdateIntentsResponse]> + rpc BatchUpdateIntents(BatchUpdateIntentsRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent}/intents:batchUpdate" + body: "*" + }; + } + + // Deletes intents in the specified agent. + // + // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]> + rpc BatchDeleteIntents(BatchDeleteIntentsRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent}/intents:batchDelete" + body: "*" + }; + } +} + +// Represents an intent. +// Intents convert a number of user expressions or patterns into an action. An +// action is an extraction of a user command or sentence semantics. +message Intent { + // Represents an example that the agent is trained on. + message TrainingPhrase { + // Represents a part of a training phrase. + message Part { + // Required. The text for this part. + string text = 1; + + // Optional. The entity type name prefixed with `@`. + // This field is required for annotated parts of the training phrase. + string entity_type = 2; + + // Optional. The parameter name for the value extracted from the + // annotated part of the example. + // This field is required for annotated parts of the training phrase. + string alias = 3; + + // Optional. Indicates whether the text was manually annotated. + // This field is set to true when the Dialogflow Console is used to + // manually annotate the part. When creating an annotated part with the + // API, you must set this to true. + bool user_defined = 4; + } + + // Represents different types of training phrases. + enum Type { + // Not specified. This value should never be used. + TYPE_UNSPECIFIED = 0; + + // Examples do not contain @-prefixed entity type names, but example parts + // can be annotated with entity types. + EXAMPLE = 1; + + // Templates are not annotated with entity types, but they can contain + // @-prefixed entity type names as substrings. + // Template mode has been deprecated. Example mode is the only supported + // way to create new training phrases. If you have existing training + // phrases that you've created in template mode, those will continue to + // work. + TEMPLATE = 2 [deprecated = true]; + } + + // Output only. The unique identifier of this training phrase. + string name = 1; + + // Required. The type of the training phrase. + Type type = 2; + + // Required. The ordered list of training phrase parts. + // The parts are concatenated in order to form the training phrase. + // + // Note: The API does not automatically annotate training phrases like the + // Dialogflow Console does. + // + // Note: Do not forget to include whitespace at part boundaries, + // so the training phrase is well formatted when the parts are concatenated. + // + // If the training phrase does not need to be annotated with parameters, + // you just need a single part with only the [Part.text][google.cloud.dialogflow.v2beta1.Intent.TrainingPhrase.Part.text] field set. + // + // If you want to annotate the training phrase, you must create multiple + // parts, where the fields of each part are populated in one of two ways: + // + // - `Part.text` is set to a part of the phrase that has no parameters. + // - `Part.text` is set to a part of the phrase that you want to annotate, + // and the `entity_type`, `alias`, and `user_defined` fields are all + // set. + repeated Part parts = 3; + + // Optional. Indicates how many times this example was added to + // the intent. Each time a developer adds an existing sample by editing an + // intent or training, this counter is increased. + int32 times_added_count = 4; + } + + // Represents intent parameters. + message Parameter { + // The unique identifier of this parameter. + string name = 1; + + // Required. The name of the parameter. + string display_name = 2; + + // Optional. The definition of the parameter value. It can be: + // - a constant string, + // - a parameter value defined as `$parameter_name`, + // - an original parameter value defined as `$parameter_name.original`, + // - a parameter value from some context defined as + // `#context_name.parameter_name`. + string value = 3; + + // Optional. The default value to use when the `value` yields an empty + // result. + // Default values can be extracted from contexts by using the following + // syntax: `#context_name.parameter_name`. + string default_value = 4; + + // Optional. The name of the entity type, prefixed with `@`, that + // describes values of the parameter. If the parameter is + // required, this must be provided. + string entity_type_display_name = 5; + + // Optional. Indicates whether the parameter is required. That is, + // whether the intent cannot be completed without collecting the parameter + // value. + bool mandatory = 6; + + // Optional. The collection of prompts that the agent can present to the + // user in order to collect value for the parameter. + repeated string prompts = 7; + + // Optional. Indicates whether the parameter represents a list of values. + bool is_list = 8; + } + + // Corresponds to the `Response` field in the Dialogflow console. + message Message { + // The text response message. + message Text { + // Optional. The collection of the agent's responses. + repeated string text = 1; + } + + // The image response message. + message Image { + // Optional. The public URI to an image file. + string image_uri = 1; + + // A text description of the image to be used for accessibility, + // e.g., screen readers. Required if image_uri is set for CarouselSelect. + string accessibility_text = 2; + } + + // The quick replies response message. + message QuickReplies { + // Optional. The title of the collection of quick replies. + string title = 1; + + // Optional. The collection of quick replies. + repeated string quick_replies = 2; + } + + // The card response message. + message Card { + // Optional. Contains information about a button. + message Button { + // Optional. The text to show on the button. + string text = 1; + + // Optional. The text to send back to the Dialogflow API or a URI to + // open. + string postback = 2; + } + + // Optional. The title of the card. + string title = 1; + + // Optional. The subtitle of the card. + string subtitle = 2; + + // Optional. The public URI to an image file for the card. + string image_uri = 3; + + // Optional. The collection of card buttons. + repeated Button buttons = 4; + } + + // The simple response message containing speech or text. + message SimpleResponse { + // One of text_to_speech or ssml must be provided. The plain text of the + // speech output. Mutually exclusive with ssml. + string text_to_speech = 1; + + // One of text_to_speech or ssml must be provided. Structured spoken + // response to the user in the SSML format. Mutually exclusive with + // text_to_speech. + string ssml = 2; + + // Optional. The text to display. + string display_text = 3; + } + + // The collection of simple response candidates. + // This message in `QueryResult.fulfillment_messages` and + // `WebhookResponse.fulfillment_messages` should contain only one + // `SimpleResponse`. + message SimpleResponses { + // Required. The list of simple responses. + repeated SimpleResponse simple_responses = 1; + } + + // The basic card message. Useful for displaying information. + message BasicCard { + // The button object that appears at the bottom of a card. + message Button { + // Opens the given URI. + message OpenUriAction { + // Required. The HTTP or HTTPS scheme URI. + string uri = 1; + } + + // Required. The title of the button. + string title = 1; + + // Required. Action to take when a user taps on the button. + OpenUriAction open_uri_action = 2; + } + + // Optional. The title of the card. + string title = 1; + + // Optional. The subtitle of the card. + string subtitle = 2; + + // Required, unless image is present. The body text of the card. + string formatted_text = 3; + + // Optional. The image for the card. + Image image = 4; + + // Optional. The collection of card buttons. + repeated Button buttons = 5; + } + + // The suggestion chip message that the user can tap to quickly post a reply + // to the conversation. + message Suggestion { + // Required. The text shown the in the suggestion chip. + string title = 1; + } + + // The collection of suggestions. + message Suggestions { + // Required. The list of suggested replies. + repeated Suggestion suggestions = 1; + } + + // The suggestion chip message that allows the user to jump out to the app + // or website associated with this agent. + message LinkOutSuggestion { + // Required. The name of the app or site this chip is linking to. + string destination_name = 1; + + // Required. The URI of the app or site to open when the user taps the + // suggestion chip. + string uri = 2; + } + + // The card for presenting a list of options to select from. + message ListSelect { + // An item in the list. + message Item { + // Required. Additional information about this option. + SelectItemInfo info = 1; + + // Required. The title of the list item. + string title = 2; + + // Optional. The main text describing the item. + string description = 3; + + // Optional. The image to display. + Image image = 4; + } + + // Optional. The overall title of the list. + string title = 1; + + // Required. List items. + repeated Item items = 2; + } + + // The card for presenting a carousel of options to select from. + message CarouselSelect { + // An item in the carousel. + message Item { + // Required. Additional info about the option item. + SelectItemInfo info = 1; + + // Required. Title of the carousel item. + string title = 2; + + // Optional. The body text of the card. + string description = 3; + + // Optional. The image to display. + Image image = 4; + } + + // Required. Carousel items. + repeated Item items = 1; + } + + // Additional info about the select item for when it is triggered in a + // dialog. + message SelectItemInfo { + // Required. A unique key that will be sent back to the agent if this + // response is given. + string key = 1; + + // Optional. A list of synonyms that can also be used to trigger this + // item in dialog. + repeated string synonyms = 2; + } + + // Plays audio from a file in Telephony Gateway. + message TelephonyPlayAudio { + // Required. URI to a Google Cloud Storage object containing the audio to + // play, e.g., "gs://bucket/object". The object must contain a single + // channel (mono) of linear PCM audio (2 bytes / sample) at 8kHz. + // + // This object must be readable by the `service-<Project + // Number>@gcp-sa-dialogflow.iam.gserviceaccount.com` service account + // where <Project Number> is the number of the Telephony Gateway project + // (usually the same as the Dialogflow agent project). If the Google Cloud + // Storage bucket is in the Telephony Gateway project, this permission is + // added by default when enabling the Dialogflow V2 API. + // + // For audio from other sources, consider using the + // `TelephonySynthesizeSpeech` message with SSML. + string audio_uri = 1; + } + + // Synthesizes speech and plays back the synthesized audio to the caller in + // Telephony Gateway. + // + // Telephony Gateway takes the synthesizer settings from + // `DetectIntentResponse.output_audio_config` which can either be set + // at request-level or can come from the agent-level synthesizer config. + message TelephonySynthesizeSpeech { + // Required. The source to be synthesized. + oneof source { + // The raw text to be synthesized. + string text = 1; + + // The SSML to be synthesized. For more information, see + // [SSML](https://developers.google.com/actions/reference/ssml). + string ssml = 2; + } + } + + // Transfers the call in Telephony Gateway. + message TelephonyTransferCall { + // Required. The phone number to transfer the call to + // in [E.164 format](https://en.wikipedia.org/wiki/E.164). + // + // We currently only allow transferring to US numbers (+1xxxyyyzzzz). + string phone_number = 1; + } + + // Represents different platforms that a rich message can be intended for. + enum Platform { + // Not specified. + PLATFORM_UNSPECIFIED = 0; + + // Facebook. + FACEBOOK = 1; + + // Slack. + SLACK = 2; + + // Telegram. + TELEGRAM = 3; + + // Kik. + KIK = 4; + + // Skype. + SKYPE = 5; + + // Line. + LINE = 6; + + // Viber. + VIBER = 7; + + // Actions on Google. + // When using Actions on Google, you can choose one of the specific + // Intent.Message types that mention support for Actions on Google, + // or you can use the advanced Intent.Message.payload field. + // The payload field provides access to AoG features not available in the + // specific message types. + // If using the Intent.Message.payload field, it should have a structure + // similar to the JSON message shown here. For more information, see + // [Actions on Google Webhook + // Format](https://developers.google.com/actions/dialogflow/webhook) + // <pre>{ + // "expectUserResponse": true, + // "isSsml": false, + // "noInputPrompts": [], + // "richResponse": { + // "items": [ + // { + // "simpleResponse": { + // "displayText": "hi", + // "textToSpeech": "hello" + // } + // } + // ], + // "suggestions": [ + // { + // "title": "Say this" + // }, + // { + // "title": "or this" + // } + // ] + // }, + // "systemIntent": { + // "data": { + // "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec", + // "listSelect": { + // "items": [ + // { + // "optionInfo": { + // "key": "key1", + // "synonyms": [ + // "key one" + // ] + // }, + // "title": "must not be empty, but unique" + // }, + // { + // "optionInfo": { + // "key": "key2", + // "synonyms": [ + // "key two" + // ] + // }, + // "title": "must not be empty, but unique" + // } + // ] + // } + // }, + // "intent": "actions.intent.OPTION" + // } + // }</pre> + ACTIONS_ON_GOOGLE = 8; + + // Telephony Gateway. + TELEPHONY = 10; + } + + // Required. The rich response message. + oneof message { + // Returns a text response. + Text text = 1; + + // Displays an image. + Image image = 2; + + // Displays quick replies. + QuickReplies quick_replies = 3; + + // Displays a card. + Card card = 4; + + // Returns a response containing a custom, platform-specific payload. + // See the Intent.Message.Platform type for a description of the + // structure that may be required for your platform. + google.protobuf.Struct payload = 5; + + // Returns a voice or text-only response for Actions on Google. + SimpleResponses simple_responses = 7; + + // Displays a basic card for Actions on Google. + BasicCard basic_card = 8; + + // Displays suggestion chips for Actions on Google. + Suggestions suggestions = 9; + + // Displays a link out suggestion chip for Actions on Google. + LinkOutSuggestion link_out_suggestion = 10; + + // Displays a list card for Actions on Google. + ListSelect list_select = 11; + + // Displays a carousel card for Actions on Google. + CarouselSelect carousel_select = 12; + + // Plays audio from a file in Telephony Gateway. + TelephonyPlayAudio telephony_play_audio = 13; + + // Synthesizes speech in Telephony Gateway. + TelephonySynthesizeSpeech telephony_synthesize_speech = 14; + + // Transfers the call in Telephony Gateway. + TelephonyTransferCall telephony_transfer_call = 15; + } + + // Optional. The platform that this message is intended for. + Platform platform = 6; + } + + // Represents a single followup intent in the chain. + message FollowupIntentInfo { + // The unique identifier of the followup intent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string followup_intent_name = 1; + + // The unique identifier of the followup intent's parent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string parent_followup_intent_name = 2; + } + + // Represents the different states that webhooks can be in. + enum WebhookState { + // Webhook is disabled in the agent and in the intent. + WEBHOOK_STATE_UNSPECIFIED = 0; + + // Webhook is enabled in the agent and in the intent. + WEBHOOK_STATE_ENABLED = 1; + + // Webhook is enabled in the agent and in the intent. Also, each slot + // filling prompt is forwarded to the webhook. + WEBHOOK_STATE_ENABLED_FOR_SLOT_FILLING = 2; + } + + // The unique identifier of this intent. + // Required for [Intents.UpdateIntent][google.cloud.dialogflow.v2beta1.Intents.UpdateIntent] and [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2beta1.Intents.BatchUpdateIntents] + // methods. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string name = 1; + + // Required. The name of this intent. + string display_name = 2; + + // Optional. Indicates whether webhooks are enabled for the intent. + WebhookState webhook_state = 6; + + // Optional. The priority of this intent. Higher numbers represent higher + // priorities. If this is zero or unspecified, we use the default + // priority 500000. + // + // Negative numbers mean that the intent is disabled. + int32 priority = 3; + + // Optional. Indicates whether this is a fallback intent. + bool is_fallback = 4; + + // Optional. Indicates whether Machine Learning is enabled for the intent. + // Note: If `ml_enabled` setting is set to false, then this intent is not + // taken into account during inference in `ML ONLY` match mode. Also, + // auto-markup in the UI is turned off. + // DEPRECATED! Please use `ml_disabled` field instead. + // NOTE: If both `ml_enabled` and `ml_disabled` are either not set or false, + // then the default value is determined as follows: + // - Before April 15th, 2018 the default is: + // ml_enabled = false / ml_disabled = true. + // - After April 15th, 2018 the default is: + // ml_enabled = true / ml_disabled = false. + bool ml_enabled = 5 [deprecated = true]; + + // Optional. Indicates whether Machine Learning is disabled for the intent. + // Note: If `ml_disabled` setting is set to true, then this intent is not + // taken into account during inference in `ML ONLY` match mode. Also, + // auto-markup in the UI is turned off. + bool ml_disabled = 19; + + // Optional. Indicates that this intent ends an interaction. Some integrations + // (e.g., Actions on Google or Dialogflow phone gateway) use this information + // to close interaction with an end user. Default is false. + bool end_interaction = 21; + + // Optional. The list of context names required for this intent to be + // triggered. + // Format: `projects/<Project ID>/agent/sessions/-/contexts/<Context ID>`. + repeated string input_context_names = 7; + + // Optional. The collection of event names that trigger the intent. + // If the collection of input contexts is not empty, all of the contexts must + // be present in the active user session for an event to trigger this intent. + repeated string events = 8; + + // Optional. The collection of examples that the agent is + // trained on. + repeated TrainingPhrase training_phrases = 9; + + // Optional. The name of the action associated with the intent. + // Note: The action name must not contain whitespaces. + string action = 10; + + // Optional. The collection of contexts that are activated when the intent + // is matched. Context messages in this collection should not set the + // parameters field. Setting the `lifespan_count` to 0 will reset the context + // when the intent is matched. + // Format: `projects/<Project ID>/agent/sessions/-/contexts/<Context ID>`. + repeated Context output_contexts = 11; + + // Optional. Indicates whether to delete all contexts in the current + // session when this intent is matched. + bool reset_contexts = 12; + + // Optional. The collection of parameters associated with the intent. + repeated Parameter parameters = 13; + + // Optional. The collection of rich messages corresponding to the + // `Response` field in the Dialogflow console. + repeated Message messages = 14; + + // Optional. The list of platforms for which the first response will be + // taken from among the messages assigned to the DEFAULT_PLATFORM. + repeated Message.Platform default_response_platforms = 15; + + // Read-only. The unique identifier of the root intent in the chain of + // followup intents. It identifies the correct followup intents chain for + // this intent. We populate this field only in the output. + // + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string root_followup_intent_name = 16; + + // Read-only after creation. The unique identifier of the parent intent in the + // chain of followup intents. You can set this field when creating an intent, + // for example with [CreateIntent][] or [BatchUpdateIntents][], in order to + // make this intent a followup intent. + // + // It identifies the parent followup intent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string parent_followup_intent_name = 17; + + // Read-only. Information about all followup intents that have this intent as + // a direct or indirect parent. We populate this field only in the output. + repeated FollowupIntentInfo followup_intent_info = 18; +} + +// The request message for [Intents.ListIntents][google.cloud.dialogflow.v2beta1.Intents.ListIntents]. +message ListIntentsRequest { + // Required. The agent to list all intents from. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Optional. The language to list training phrases, parameters and rich + // messages for. If not specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 3; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 4; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 5; +} + +// The response message for [Intents.ListIntents][google.cloud.dialogflow.v2beta1.Intents.ListIntents]. +message ListIntentsResponse { + // The list of agent intents. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated Intent intents = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [Intents.GetIntent][google.cloud.dialogflow.v2beta1.Intents.GetIntent]. +message GetIntentRequest { + // Required. The name of the intent. + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string name = 1; + + // Optional. The language to retrieve training phrases, parameters and rich + // messages for. If not specified, the agent's default language is used. + // [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 3; +} + +// The request message for [Intents.CreateIntent][google.cloud.dialogflow.v2beta1.Intents.CreateIntent]. +message CreateIntentRequest { + // Required. The agent to create a intent for. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The intent to create. + Intent intent = 2; + + // Optional. The language of training phrases, parameters and rich messages + // defined in `intent`. If not specified, the agent's default language is + // used. [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 3; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 4; +} + +// The request message for [Intents.UpdateIntent][google.cloud.dialogflow.v2beta1.Intents.UpdateIntent]. +message UpdateIntentRequest { + // Required. The intent to update. + Intent intent = 1; + + // Optional. The language of training phrases, parameters and rich messages + // defined in `intent`. If not specified, the agent's default language is + // used. [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 2; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 3; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 4; +} + +// The request message for [Intents.DeleteIntent][google.cloud.dialogflow.v2beta1.Intents.DeleteIntent]. +message DeleteIntentRequest { + // Required. The name of the intent to delete. If this intent has direct or + // indirect followup intents, we also delete them. + // + // Format: `projects/<Project ID>/agent/intents/<Intent ID>`. + string name = 1; +} + +// The request message for [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2beta1.Intents.BatchUpdateIntents]. +message BatchUpdateIntentsRequest { + // Required. The name of the agent to update or create intents in. + // Format: `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The source of the intent batch. + oneof intent_batch { + // The URI to a Google Cloud Storage file containing intents to update or + // create. The file format can either be a serialized proto (of IntentBatch + // type) or JSON object. Note: The URI must start with "gs://". + string intent_batch_uri = 2; + + // The collection of intents to update or create. + IntentBatch intent_batch_inline = 3; + } + + // Optional. The language of training phrases, parameters and rich messages + // defined in `intents`. If not specified, the agent's default language is + // used. [Many + // languages](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // are supported. Note: languages must be enabled in the agent before they can + // be used. + string language_code = 4; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 5; + + // Optional. The resource view to apply to the returned intent. + IntentView intent_view = 6; +} + +// The response message for [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2beta1.Intents.BatchUpdateIntents]. +message BatchUpdateIntentsResponse { + // The collection of updated or created intents. + repeated Intent intents = 1; +} + +// The request message for [Intents.BatchDeleteIntents][google.cloud.dialogflow.v2beta1.Intents.BatchDeleteIntents]. +message BatchDeleteIntentsRequest { + // Required. The name of the agent to delete all entities types for. Format: + // `projects/<Project ID>/agent`. + string parent = 1; + + // Required. The collection of intents to delete. Only intent `name` must be + // filled in. + repeated Intent intents = 2; +} + +// This message is a wrapper around a collection of intents. +message IntentBatch { + // A collection of intents. + repeated Intent intents = 1; +} + +// Represents the options for views of an intent. +// An intent can be a sizable object. Therefore, we provide a resource view that +// does not return training phrases in the response by default. +enum IntentView { + // Training phrases field is not populated in the response. + INTENT_VIEW_UNSPECIFIED = 0; + + // All fields are populated. + INTENT_VIEW_FULL = 1; +} diff --git a/google/cloud/dialogflow/v2beta1/knowledge_base.proto b/google/cloud/dialogflow/v2beta1/knowledge_base.proto new file mode 100644 index 000000000..af8d7bd28 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/knowledge_base.proto @@ -0,0 +1,168 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "KnowledgeBaseProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// Manages knowledge bases. +// +// Allows users to setup and maintain knowledge bases with their knowledge data. +service KnowledgeBases { + // Returns the list of all knowledge bases of the specified agent. + rpc ListKnowledgeBases(ListKnowledgeBasesRequest) returns (ListKnowledgeBasesResponse) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*}/knowledgeBases" + additional_bindings { + get: "/v2beta1/{parent=projects/*/agent}/knowledgeBases" + } + }; + } + + // Retrieves the specified knowledge base. + rpc GetKnowledgeBase(GetKnowledgeBaseRequest) returns (KnowledgeBase) { + option (google.api.http) = { + get: "/v2beta1/{name=projects/*/knowledgeBases/*}" + additional_bindings { + get: "/v2beta1/{name=projects/*/agent/knowledgeBases/*}" + } + }; + } + + // Creates a knowledge base. + rpc CreateKnowledgeBase(CreateKnowledgeBaseRequest) returns (KnowledgeBase) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*}/knowledgeBases" + body: "knowledge_base" + additional_bindings { + post: "/v2beta1/{parent=projects/*/agent}/knowledgeBases" + body: "knowledge_base" + } + }; + } + + // Deletes the specified knowledge base. + rpc DeleteKnowledgeBase(DeleteKnowledgeBaseRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta1/{name=projects/*/knowledgeBases/*}" + additional_bindings { + delete: "/v2beta1/{name=projects/*/agent/knowledgeBases/*}" + } + }; + } + + // Updates the specified knowledge base. + rpc UpdateKnowledgeBase(UpdateKnowledgeBaseRequest) returns (KnowledgeBase) { + option (google.api.http) = { + patch: "/v2beta1/{knowledge_base.name=projects/*/knowledgeBases/*}" + body: "knowledge_base" + additional_bindings { + patch: "/v2beta1/{knowledge_base.name=projects/*/agent/knowledgeBases/*}" + body: "knowledge_base" + } + }; + } +} + +// Represents knowledge base resource. +// +// Note: resource `projects.agent.knowledgeBases` is deprecated, please use +// `projects.knowledgeBases` instead. +message KnowledgeBase { + // The knowledge base resource name. + // The name must be empty when creating a knowledge base. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`. + string name = 1; + + // Required. The display name of the knowledge base. The name must be 1024 + // bytes or less; otherwise, the creation request fails. + string display_name = 2; +} + +// Request message for [KnowledgeBases.ListKnowledgeBases][google.cloud.dialogflow.v2beta1.KnowledgeBases.ListKnowledgeBases]. +message ListKnowledgeBasesRequest { + // Required. The project to list of knowledge bases for. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 10 and at most 100. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// Response message for [KnowledgeBases.ListKnowledgeBases][google.cloud.dialogflow.v2beta1.KnowledgeBases.ListKnowledgeBases]. +message ListKnowledgeBasesResponse { + // The list of knowledge bases. + repeated KnowledgeBase knowledge_bases = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// Request message for [KnowledgeBase.GetDocument][]. +message GetKnowledgeBaseRequest { + // Required. The name of the knowledge base to retrieve. + // Format `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`. + string name = 1; +} + +// Request message for [KnowledgeBases.CreateKnowledgeBase][google.cloud.dialogflow.v2beta1.KnowledgeBases.CreateKnowledgeBase]. +message CreateKnowledgeBaseRequest { + // Required. The project to create a knowledge base for. + // Format: `projects/<Project ID>`. + string parent = 1; + + // Required. The knowledge base to create. + KnowledgeBase knowledge_base = 2; +} + +// Request message for [KnowledgeBases.DeleteKnowledgeBase][google.cloud.dialogflow.v2beta1.KnowledgeBases.DeleteKnowledgeBase]. +message DeleteKnowledgeBaseRequest { + // Required. The name of the knowledge base to delete. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`. + string name = 1; + + // Optional. Force deletes the knowledge base. When set to true, any documents + // in the knowledge base are also deleted. + bool force = 2; +} + +// Request message for [KnowledgeBases.UpdateKnowledgeBase][google.cloud.dialogflow.v2beta1.KnowledgeBases.UpdateKnowledgeBase]. +message UpdateKnowledgeBaseRequest { + // Required. The knowledge base to update. + KnowledgeBase knowledge_base = 1; + + // Optional. Not specified means `update all`. + // Currently, only `display_name` can be updated, an InvalidArgument will be + // returned for attempting to update other fields. + google.protobuf.FieldMask update_mask = 2; +} diff --git a/google/cloud/dialogflow/v2beta1/session.proto b/google/cloud/dialogflow/v2beta1/session.proto new file mode 100644 index 000000000..62018794e --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/session.proto @@ -0,0 +1,586 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/dialogflow/v2beta1/agent.proto"; +import "google/cloud/dialogflow/v2beta1/audio_config.proto"; +import "google/cloud/dialogflow/v2beta1/context.proto"; +import "google/cloud/dialogflow/v2beta1/intent.proto"; +import "google/cloud/dialogflow/v2beta1/session_entity_type.proto"; +import "google/protobuf/struct.proto"; +import "google/rpc/status.proto"; +import "google/type/latlng.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "SessionProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// A session represents an interaction with a user. You retrieve user input +// and pass it to the [DetectIntent][google.cloud.dialogflow.v2beta1.Sessions.DetectIntent] (or +// [StreamingDetectIntent][google.cloud.dialogflow.v2beta1.Sessions.StreamingDetectIntent]) method to determine +// user intent and respond. +service Sessions { + // Processes a natural language query and returns structured, actionable data + // as a result. This method is not idempotent, because it may cause contexts + // and session entity types to be updated, which in turn might affect + // results of future queries. + rpc DetectIntent(DetectIntentRequest) returns (DetectIntentResponse) { + option (google.api.http) = { + post: "/v2beta1/{session=projects/*/agent/sessions/*}:detectIntent" + body: "*" + additional_bindings { + post: "/v2beta1/{session=projects/*/agent/environments/*/users/*/sessions/*}:detectIntent" + body: "*" + } + }; + } + + // Processes a natural language query in audio format in a streaming fashion + // and returns structured, actionable data as a result. This method is only + // available via the gRPC API (not REST). + rpc StreamingDetectIntent(stream StreamingDetectIntentRequest) returns (stream StreamingDetectIntentResponse) { + } +} + +// The request to detect user's intent. +message DetectIntentRequest { + // Required. The name of the session this query is sent to. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>`, or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>`. If `Environment ID` is not specified, we assume + // default 'draft' environment. If `User ID` is not specified, we are using + // "-". It’s up to the API caller to choose an appropriate `Session ID` and + // `User Id`. They can be a random numbers or some type of user and session + // identifiers (preferably hashed). The length of the `Session ID` and + // `User ID` must not exceed 36 characters. + string session = 1; + + // Optional. The parameters of this query. + QueryParameters query_params = 2; + + // Required. The input specification. It can be set to: + // + // 1. an audio config + // which instructs the speech recognizer how to process the speech audio, + // + // 2. a conversational query in the form of text, or + // + // 3. an event that specifies which intent to trigger. + QueryInput query_input = 3; + + // Optional. Instructs the speech synthesizer how to generate the output + // audio. If this field is not set and agent-level speech synthesizer is not + // configured, no output audio is generated. + OutputAudioConfig output_audio_config = 4; + + // Optional. The natural language speech audio to be processed. This field + // should be populated iff `query_input` is set to an input audio config. + // A single request can contain up to 1 minute of speech audio data. + bytes input_audio = 5; +} + +// The message returned from the DetectIntent method. +message DetectIntentResponse { + // The unique identifier of the response. It can be used to + // locate a response in the training example set or for reporting issues. + string response_id = 1; + + // The selected results of the conversational query or event processing. + // See `alternative_query_results` for additional potential results. + QueryResult query_result = 2; + + // If Knowledge Connectors are enabled, there could be more than one result + // returned for a given query or event, and this field will contain all + // results except for the top one, which is captured in query_result. The + // alternative results are ordered by decreasing + // `QueryResult.intent_detection_confidence`. If Knowledge Connectors are + // disabled, this field will be empty until multiple responses for regular + // intents are supported, at which point those additional results will be + // surfaced here. + repeated QueryResult alternative_query_results = 5; + + // Specifies the status of the webhook request. + google.rpc.Status webhook_status = 3; + + // The audio data bytes encoded as specified in the request. + // Note: The output audio is generated based on the values of default platform + // text responses found in the `query_result.fulfillment_messages` field. If + // multiple default text responses exist, they will be concatenated when + // generating audio. If no default platform text responses exist, the + // generated audio content will be empty. + bytes output_audio = 4; + + // Instructs the speech synthesizer how to generate the output audio. This + // field is populated from the agent-level speech synthesizer configuration, + // if enabled. + OutputAudioConfig output_audio_config = 6; +} + +// Represents the parameters of the conversational query. +message QueryParameters { + // Optional. The time zone of this conversational query from the + // [time zone database](https://www.iana.org/time-zones), e.g., + // America/New_York, Europe/Paris. If not provided, the time zone specified in + // agent settings is used. + string time_zone = 1; + + // Optional. The geo location of this conversational query. + google.type.LatLng geo_location = 2; + + // Optional. The collection of contexts to be activated before this query is + // executed. + repeated Context contexts = 3; + + // Optional. Specifies whether to delete all contexts in the current session + // before the new ones are activated. + bool reset_contexts = 4; + + // Optional. Additional session entity types to replace or extend developer + // entity types with. The entity synonyms apply to all languages and persist + // for the session of this query. + repeated SessionEntityType session_entity_types = 5; + + // Optional. This field can be used to pass custom data into the webhook + // associated with the agent. Arbitrary JSON objects are supported. + google.protobuf.Struct payload = 6; + + // Optional. KnowledgeBases to get alternative results from. If not set, the + // KnowledgeBases enabled in the agent (through UI) will be used. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`. + repeated string knowledge_base_names = 12; + + // Optional. Configures the type of sentiment analysis to perform. If not + // provided, sentiment analysis is not performed. + // Note: Sentiment Analysis is only currently available for Enterprise Edition + // agents. + SentimentAnalysisRequestConfig sentiment_analysis_request_config = 10; +} + +// Represents the query input. It can contain either: +// +// 1. An audio config which +// instructs the speech recognizer how to process the speech audio. +// +// 2. A conversational query in the form of text,. +// +// 3. An event that specifies which intent to trigger. +message QueryInput { + // Required. The input specification. + oneof input { + // Instructs the speech recognizer how to process the speech audio. + InputAudioConfig audio_config = 1; + + // The natural language text to be processed. + TextInput text = 2; + + // The event to be processed. + EventInput event = 3; + } +} + +// Represents the result of conversational query or event processing. +message QueryResult { + // The original conversational query text: + // - If natural language text was provided as input, `query_text` contains + // a copy of the input. + // - If natural language speech audio was provided as input, `query_text` + // contains the speech recognition result. If speech recognizer produced + // multiple alternatives, a particular one is picked. + // - If an event was provided as input, `query_text` is not set. + string query_text = 1; + + // The language that was triggered during intent detection. + // See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. + string language_code = 15; + + // The Speech recognition confidence between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. The default of 0.0 is a sentinel value indicating that confidence + // was not set. + // + // This field is not guaranteed to be accurate or set. In particular this + // field isn't set for StreamingDetectIntent since the streaming endpoint has + // separate confidence estimates per portion of the audio in + // StreamingRecognitionResult. + float speech_recognition_confidence = 2; + + // The action name from the matched intent. + string action = 3; + + // The collection of extracted parameters. + google.protobuf.Struct parameters = 4; + + // This field is set to: + // - `false` if the matched intent has required parameters and not all of + // the required parameter values have been collected. + // - `true` if all required parameter values have been collected, or if the + // matched intent doesn't contain any required parameters. + bool all_required_params_present = 5; + + // The text to be pronounced to the user or shown on the screen. + // Note: This is a legacy field, `fulfillment_messages` should be preferred. + string fulfillment_text = 6; + + // The collection of rich messages to present to the user. + repeated Intent.Message fulfillment_messages = 7; + + // If the query was fulfilled by a webhook call, this field is set to the + // value of the `source` field returned in the webhook response. + string webhook_source = 8; + + // If the query was fulfilled by a webhook call, this field is set to the + // value of the `payload` field returned in the webhook response. + google.protobuf.Struct webhook_payload = 9; + + // The collection of output contexts. If applicable, + // `output_contexts.parameters` contains entries with name + // `<parameter name>.original` containing the original parameter values + // before the query. + repeated Context output_contexts = 10; + + // The intent that matched the conversational query. Some, not + // all fields are filled in this message, including but not limited to: + // `name`, `display_name` and `webhook_state`. + Intent intent = 11; + + // The intent detection confidence. Values range from 0.0 + // (completely uncertain) to 1.0 (completely certain). + // If there are `multiple knowledge_answers` messages, this value is set to + // the greatest `knowledgeAnswers.match_confidence` value in the list. + float intent_detection_confidence = 12; + + // The free-form diagnostic info. For example, this field could contain + // webhook call latency. The string keys of the Struct's fields map can change + // without notice. + google.protobuf.Struct diagnostic_info = 14; + + // The sentiment analysis result, which depends on the + // `sentiment_analysis_request_config` specified in the request. + SentimentAnalysisResult sentiment_analysis_result = 17; + + // The result from Knowledge Connector (if any), ordered by decreasing + // `KnowledgeAnswers.match_confidence`. + KnowledgeAnswers knowledge_answers = 18; +} + +// Represents the result of querying a Knowledge base. +message KnowledgeAnswers { + // An answer from Knowledge Connector. + message Answer { + // Represents the system's confidence that this knowledge answer is a good + // match for this conversational query. + enum MatchConfidenceLevel { + // Not specified. + MATCH_CONFIDENCE_LEVEL_UNSPECIFIED = 0; + + // Indicates that the confidence is low. + LOW = 1; + + // Indicates our confidence is medium. + MEDIUM = 2; + + // Indicates our confidence is high. + HIGH = 3; + } + + // Indicates which Knowledge Document this answer was extracted from. + // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base + // ID>/documents/<Document ID>`. + string source = 1; + + // The corresponding FAQ question if the answer was extracted from a FAQ + // Document, empty otherwise. + string faq_question = 2; + + // The piece of text from the `source` knowledge base document that answers + // this conversational query. + string answer = 3; + + // The system's confidence level that this knowledge answer is a good match + // for this conversational query. + // NOTE: The confidence level for a given `<query, answer>` pair may change + // without notice, as it depends on models that are constantly being + // improved. However, it will change less frequently than the confidence + // score below, and should be preferred for referencing the quality of an + // answer. + MatchConfidenceLevel match_confidence_level = 4; + + // The system's confidence score that this Knowledge answer is a good match + // for this conversational query. + // The range is from 0.0 (completely uncertain) to 1.0 (completely certain). + // Note: The confidence score is likely to vary somewhat (possibly even for + // identical requests), as the underlying model is under constant + // improvement. It may be deprecated in the future. We recommend using + // `match_confidence_level` which should be generally more stable. + float match_confidence = 5; + } + + // A list of answers from Knowledge Connector. + repeated Answer answers = 1; +} + +// The top-level message sent by the client to the +// `StreamingDetectIntent` method. +// +// Multiple request messages should be sent in order: +// +// 1. The first message must contain `session`, `query_input` plus optionally +// `query_params` and/or `single_utterance`. If the client wants to receive +// an audio response, it should also contain `output_audio_config`. +// The message must not contain `input_audio`. +// +// 2. If `query_input` was set to a streaming input audio config, +// all subsequent messages must contain only `input_audio`. +// Otherwise, finish the request stream. +message StreamingDetectIntentRequest { + // Required. The name of the session the query is sent to. + // Format of the session name: + // `projects/<Project ID>/agent/sessions/<Session ID>`, or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>`. If `Environment ID` is not specified, we assume + // default 'draft' environment. If `User ID` is not specified, we are using + // "-". It’s up to the API caller to choose an appropriate `Session ID` and + // `User Id`. They can be a random numbers or some type of user and session + // identifiers (preferably hashed). The length of the `Session ID` and + // `User ID` must not exceed 36 characters. + string session = 1; + + // Optional. The parameters of this query. + QueryParameters query_params = 2; + + // Required. The input specification. It can be set to: + // + // 1. an audio config which instructs the speech recognizer how to process + // the speech audio, + // + // 2. a conversational query in the form of text, or + // + // 3. an event that specifies which intent to trigger. + QueryInput query_input = 3; + + // Optional. If `false` (default), recognition does not cease until the + // client closes the stream. + // If `true`, the recognizer will detect a single spoken utterance in input + // audio. Recognition ceases when it detects the audio's voice has + // stopped or paused. In this case, once a detected intent is received, the + // client should close the stream and start a new request with a new stream as + // needed. + // This setting is ignored when `query_input` is a piece of text or an event. + bool single_utterance = 4; + + // Optional. Instructs the speech synthesizer how to generate the output + // audio. If this field is not set and agent-level speech synthesizer is not + // configured, no output audio is generated. + OutputAudioConfig output_audio_config = 5; + + // Optional. The input audio content to be recognized. Must be sent if + // `query_input` was set to a streaming input audio config. The complete audio + // over all streaming messages must not exceed 1 minute. + bytes input_audio = 6; +} + +// The top-level message returned from the +// `StreamingDetectIntent` method. +// +// Multiple response messages can be returned in order: +// +// 1. If the input was set to streaming audio, the first one or more messages +// contain `recognition_result`. Each `recognition_result` represents a more +// complete transcript of what the user said. The last `recognition_result` +// has `is_final` set to `true`. +// +// 2. The next message contains `response_id`, `query_result`, +// `alternative_query_results` and optionally `webhook_status` if a WebHook +// was called. +// +// 3. If `output_audio_config` was specified in the request or agent-level +// speech synthesizer is configured, all subsequent messages contain +// `output_audio` and `output_audio_config`. +message StreamingDetectIntentResponse { + // The unique identifier of the response. It can be used to + // locate a response in the training example set or for reporting issues. + string response_id = 1; + + // The result of speech recognition. + StreamingRecognitionResult recognition_result = 2; + + // The selected results of the conversational query or event processing. + // See `alternative_query_results` for additional potential results. + QueryResult query_result = 3; + + // If Knowledge Connectors are enabled, there could be more than one result + // returned for a given query or event, and this field will contain all + // results except for the top one, which is captured in query_result. The + // alternative results are ordered by decreasing + // `QueryResult.intent_detection_confidence`. If Knowledge Connectors are + // disabled, this field will be empty until multiple responses for regular + // intents are supported, at which point those additional results will be + // surfaced here. + repeated QueryResult alternative_query_results = 7; + + // Specifies the status of the webhook request. + google.rpc.Status webhook_status = 4; + + // The audio data bytes encoded as specified in the request. + bytes output_audio = 5; + + // The config used by the speech synthesizer to generate the output audio. + OutputAudioConfig output_audio_config = 6; +} + +// Contains a speech recognition result corresponding to a portion of the audio +// that is currently being processed or an indication that this is the end +// of the single requested utterance. +// +// Example: +// +// 1. transcript: "tube" +// +// 2. transcript: "to be a" +// +// 3. transcript: "to be" +// +// 4. transcript: "to be or not to be" +// is_final: true +// +// 5. transcript: " that's" +// +// 6. transcript: " that is" +// +// 7. message_type: `MESSAGE_TYPE_END_OF_SINGLE_UTTERANCE` +// +// 8. transcript: " that is the question" +// is_final: true +// +// Only two of the responses contain final results (#4 and #8 indicated by +// `is_final: true`). Concatenating these generates the full transcript: "to be +// or not to be that is the question". +// +// In each response we populate: +// +// * for `MESSAGE_TYPE_TRANSCRIPT`: `transcript` and possibly `is_final`. +// +// * for `MESSAGE_TYPE_END_OF_SINGLE_UTTERANCE`: only `message_type`. +message StreamingRecognitionResult { + // Type of the response message. + enum MessageType { + // Not specified. Should never be used. + MESSAGE_TYPE_UNSPECIFIED = 0; + + // Message contains a (possibly partial) transcript. + TRANSCRIPT = 1; + + // Event indicates that the server has detected the end of the user's speech + // utterance and expects no additional speech. Therefore, the server will + // not process additional audio (although it may subsequently return + // additional results). The client should stop sending additional audio + // data, half-close the gRPC connection, and wait for any additional results + // until the server closes the gRPC connection. This message is only sent if + // `single_utterance` was set to `true`, and is not used otherwise. + END_OF_SINGLE_UTTERANCE = 2; + } + + // Type of the result message. + MessageType message_type = 1; + + // Transcript text representing the words that the user spoke. + // Populated if and only if `message_type` = `MESSAGE_TYPE_TRANSCRIPT`. + string transcript = 2; + + // If `false`, the `StreamingRecognitionResult` represents an + // interim result that may change. If `true`, the recognizer will not return + // any further hypotheses about this piece of the audio. May only be populated + // for `message_type` = `MESSAGE_TYPE_TRANSCRIPT`. + bool is_final = 3; + + // The Speech confidence between 0.0 and 1.0 for the current portion of audio. + // A higher number indicates an estimated greater likelihood that the + // recognized words are correct. The default of 0.0 is a sentinel value + // indicating that confidence was not set. + // + // This field is typically only provided if `is_final` is true and you should + // not rely on it being accurate or even set. + float confidence = 4; +} + +// Represents the natural language text to be processed. +message TextInput { + // Required. The UTF-8 encoded natural language text to be processed. + // Text length must not exceed 256 characters. + string text = 1; + + // Required. The language of this conversational query. See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. Note that queries in + // the same session do not necessarily need to specify the same language. + string language_code = 2; +} + +// Events allow for matching intents by event name instead of the natural +// language input. For instance, input `<event: { name: "welcome_event", +// parameters: { name: "Sam" } }>` can trigger a personalized welcome response. +// The parameter `name` may be used by the agent in the response: +// `"Hello #welcome_event.name! What can I do for you today?"`. +message EventInput { + // Required. The unique identifier of the event. + string name = 1; + + // Optional. The collection of parameters associated with the event. + google.protobuf.Struct parameters = 2; + + // Required. The language of this query. See [Language + // Support](https://cloud.google.com/dialogflow-enterprise/docs/reference/language) + // for a list of the currently supported language codes. Note that queries in + // the same session do not necessarily need to specify the same language. + string language_code = 3; +} + +// Configures the types of sentiment analysis to perform. +message SentimentAnalysisRequestConfig { + // Optional. Instructs the service to perform sentiment analysis on + // `query_text`. If not provided, sentiment analysis is not performed on + // `query_text`. + bool analyze_query_text_sentiment = 1; +} + +// The result of sentiment analysis as configured by +// `sentiment_analysis_request_config`. +message SentimentAnalysisResult { + // The sentiment analysis result for `query_text`. + Sentiment query_text_sentiment = 1; +} + +// The sentiment, such as positive/negative feeling or association, for a unit +// of analysis, such as the query text. +message Sentiment { + // Sentiment score between -1.0 (negative sentiment) and 1.0 (positive + // sentiment). + float score = 1; + + // A non-negative number in the [0, +inf) range, which represents the absolute + // magnitude of sentiment, regardless of score (positive or negative). + float magnitude = 2; +} diff --git a/google/cloud/dialogflow/v2beta1/session_entity_type.proto b/google/cloud/dialogflow/v2beta1/session_entity_type.proto new file mode 100644 index 000000000..3b6f14f14 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/session_entity_type.proto @@ -0,0 +1,233 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/dialogflow/v2beta1/entity_type.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "SessionEntityTypeProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// Entities are extracted from user input and represent parameters that are +// meaningful to your application. For example, a date range, a proper name +// such as a geographic location or landmark, and so on. Entities represent +// actionable data for your application. +// +// Session entity types are referred to as **User** entity types and are +// entities that are built for an individual user such as +// favorites, preferences, playlists, and so on. You can redefine a session +// entity type at the session level. +// +// For more information about entity types, see the +// [Dialogflow +// documentation](https://cloud.google.com/dialogflow-enterprise/docs/entities-overview). +service SessionEntityTypes { + // Returns the list of all session entity types in the specified session. + rpc ListSessionEntityTypes(ListSessionEntityTypesRequest) returns (ListSessionEntityTypesResponse) { + option (google.api.http) = { + get: "/v2beta1/{parent=projects/*/agent/sessions/*}/entityTypes" + additional_bindings { + get: "/v2beta1/{parent=projects/*/agent/environments/*/users/*/sessions/*}/entityTypes" + } + }; + } + + // Retrieves the specified session entity type. + rpc GetSessionEntityType(GetSessionEntityTypeRequest) returns (SessionEntityType) { + option (google.api.http) = { + get: "/v2beta1/{name=projects/*/agent/sessions/*/entityTypes/*}" + additional_bindings { + get: "/v2beta1/{name=projects/*/agent/environments/*/users/*/sessions/*/entityTypes/*}" + } + }; + } + + // Creates a session entity type. + // + // If the specified session entity type already exists, overrides the + // session entity type. + rpc CreateSessionEntityType(CreateSessionEntityTypeRequest) returns (SessionEntityType) { + option (google.api.http) = { + post: "/v2beta1/{parent=projects/*/agent/sessions/*}/entityTypes" + body: "session_entity_type" + additional_bindings { + post: "/v2beta1/{parent=projects/*/agent/environments/*/users/*/sessions/*}/entityTypes" + body: "session_entity_type" + } + }; + } + + // Updates the specified session entity type. + rpc UpdateSessionEntityType(UpdateSessionEntityTypeRequest) returns (SessionEntityType) { + option (google.api.http) = { + patch: "/v2beta1/{session_entity_type.name=projects/*/agent/sessions/*/entityTypes/*}" + body: "session_entity_type" + additional_bindings { + patch: "/v2beta1/{session_entity_type.name=projects/*/agent/environments/*/users/*/sessions/*/entityTypes/*}" + body: "session_entity_type" + } + }; + } + + // Deletes the specified session entity type. + rpc DeleteSessionEntityType(DeleteSessionEntityTypeRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta1/{name=projects/*/agent/sessions/*/entityTypes/*}" + additional_bindings { + delete: "/v2beta1/{name=projects/*/agent/environments/*/users/*/sessions/*/entityTypes/*}" + } + }; + } +} + +// Represents a session entity type. +// +// Extends or replaces a developer entity type at the user session level (we +// refer to the entity types defined at the agent level as "developer entity +// types"). +// +// Note: session entity types apply to all queries, regardless of the language. +message SessionEntityType { + // The types of modifications for a session entity type. + enum EntityOverrideMode { + // Not specified. This value should be never used. + ENTITY_OVERRIDE_MODE_UNSPECIFIED = 0; + + // The collection of session entities overrides the collection of entities + // in the corresponding developer entity type. + ENTITY_OVERRIDE_MODE_OVERRIDE = 1; + + // The collection of session entities extends the collection of entities in + // the corresponding developer entity type. + // + // Note: Even in this override mode calls to `ListSessionEntityTypes`, + // `GetSessionEntityType`, `CreateSessionEntityType` and + // `UpdateSessionEntityType` only return the additional entities added in + // this session entity type. If you want to get the supplemented list, + // please call [EntityTypes.GetEntityType][google.cloud.dialogflow.v2beta1.EntityTypes.GetEntityType] on the developer entity type + // and merge. + ENTITY_OVERRIDE_MODE_SUPPLEMENT = 2; + } + + // Required. The unique identifier of this session entity type. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>`, or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>/entityTypes/<Entity Type Display Name>`. + // If `Environment ID` is not specified, we assume default 'draft' + // environment. If `User ID` is not specified, we assume default '-' user. + // + // `<Entity Type Display Name>` must be the display name of an existing entity + // type in the same agent that will be overridden or supplemented. + string name = 1; + + // Required. Indicates whether the additional data should override or + // supplement the developer entity type definition. + EntityOverrideMode entity_override_mode = 2; + + // Required. The collection of entities associated with this session entity + // type. + repeated EntityType.Entity entities = 3; +} + +// The request message for [SessionEntityTypes.ListSessionEntityTypes][google.cloud.dialogflow.v2beta1.SessionEntityTypes.ListSessionEntityTypes]. +message ListSessionEntityTypesRequest { + // Required. The session to list all session entity types from. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User ID>/ + // sessions/<Session ID>`. + // If `Environment ID` is not specified, we assume default 'draft' + // environment. If `User ID` is not specified, we assume default '-' user. + string parent = 1; + + // Optional. The maximum number of items to return in a single page. By + // default 100 and at most 1000. + int32 page_size = 2; + + // Optional. The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// The response message for [SessionEntityTypes.ListSessionEntityTypes][google.cloud.dialogflow.v2beta1.SessionEntityTypes.ListSessionEntityTypes]. +message ListSessionEntityTypesResponse { + // The list of session entity types. There will be a maximum number of items + // returned based on the page_size field in the request. + repeated SessionEntityType session_entity_types = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// The request message for [SessionEntityTypes.GetSessionEntityType][google.cloud.dialogflow.v2beta1.SessionEntityTypes.GetSessionEntityType]. +message GetSessionEntityTypeRequest { + // Required. The name of the session entity type. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>` or `projects/<Project ID>/agent/environments/<Environment + // ID>/users/<User ID>/sessions/<Session ID>/entityTypes/<Entity Type Display + // Name>`. If `Environment ID` is not specified, we assume default 'draft' + // environment. If `User ID` is not specified, we assume default '-' user. + string name = 1; +} + +// The request message for [SessionEntityTypes.CreateSessionEntityType][google.cloud.dialogflow.v2beta1.SessionEntityTypes.CreateSessionEntityType]. +message CreateSessionEntityTypeRequest { + // Required. The session to create a session entity type for. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User ID>/ + // sessions/<Session ID>`. If `Environment ID` is not specified, we assume + // default 'draft' environment. If `User ID` is not specified, we assume + // default '-' user. + string parent = 1; + + // Required. The session entity type to create. + SessionEntityType session_entity_type = 2; +} + +// The request message for [SessionEntityTypes.UpdateSessionEntityType][google.cloud.dialogflow.v2beta1.SessionEntityTypes.UpdateSessionEntityType]. +message UpdateSessionEntityTypeRequest { + // Required. The entity type to update. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>` or `projects/<Project ID>/agent/environments/<Environment + // ID>/users/<User ID>/sessions/<Session ID>/entityTypes/<Entity Type Display + // Name>`. If `Environment ID` is not specified, we assume default 'draft' + // environment. If `User ID` is not specified, we assume default '-' user. + SessionEntityType session_entity_type = 1; + + // Optional. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 2; +} + +// The request message for [SessionEntityTypes.DeleteSessionEntityType][google.cloud.dialogflow.v2beta1.SessionEntityTypes.DeleteSessionEntityType]. +message DeleteSessionEntityTypeRequest { + // Required. The name of the entity type to delete. Format: + // `projects/<Project ID>/agent/sessions/<Session ID>/entityTypes/<Entity Type + // Display Name>` or `projects/<Project ID>/agent/environments/<Environment + // ID>/users/<User ID>/sessions/<Session ID>/entityTypes/<Entity Type Display + // Name>`. If `Environment ID` is not specified, we assume default 'draft' + // environment. If `User ID` is not specified, we assume default '-' user. + string name = 1; +} diff --git a/google/cloud/dialogflow/v2beta1/webhook.proto b/google/cloud/dialogflow/v2beta1/webhook.proto new file mode 100644 index 000000000..433c8c0b5 --- /dev/null +++ b/google/cloud/dialogflow/v2beta1/webhook.proto @@ -0,0 +1,137 @@ +// Copyright 2019 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.dialogflow.v2beta1; + +import "google/cloud/dialogflow/v2beta1/context.proto"; +import "google/cloud/dialogflow/v2beta1/intent.proto"; +import "google/cloud/dialogflow/v2beta1/session.proto"; +import "google/cloud/dialogflow/v2beta1/session_entity_type.proto"; +import "google/protobuf/struct.proto"; +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow"; +option java_multiple_files = true; +option java_outer_classname = "WebhookProto"; +option java_package = "com.google.cloud.dialogflow.v2beta1"; +option objc_class_prefix = "DF"; + +// The request message for a webhook call. +message WebhookRequest { + // The unique identifier of detectIntent request session. + // Can be used to identify end-user inside webhook implementation. + // Format: `projects/<Project ID>/agent/sessions/<Session ID>`, or + // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User + // ID>/sessions/<Session ID>`. + string session = 4; + + // The unique identifier of the response. Contains the same value as + // `[Streaming]DetectIntentResponse.response_id`. + string response_id = 1; + + // The result of the conversational query or event processing. Contains the + // same value as `[Streaming]DetectIntentResponse.query_result`. + QueryResult query_result = 2; + + // Alternative query results from KnowledgeService. + repeated QueryResult alternative_query_results = 5; + + // Optional. The contents of the original request that was passed to + // `[Streaming]DetectIntent` call. + OriginalDetectIntentRequest original_detect_intent_request = 3; +} + +// The response message for a webhook call. +message WebhookResponse { + // Optional. The text to be shown on the screen. This value is passed directly + // to `QueryResult.fulfillment_text`. + string fulfillment_text = 1; + + // Optional. The collection of rich messages to present to the user. This + // value is passed directly to `QueryResult.fulfillment_messages`. + repeated Intent.Message fulfillment_messages = 2; + + // Optional. This value is passed directly to `QueryResult.webhook_source`. + string source = 3; + + // Optional. This value is passed directly to `QueryResult.webhook_payload`. + // See the related `fulfillment_messages[i].payload field`, which may be used + // as an alternative to this field. + // + // This field can be used for Actions on Google responses. + // It should have a structure similar to the JSON message shown here. For more + // information, see + // [Actions on Google Webhook + // Format](https://developers.google.com/actions/dialogflow/webhook) + // <pre>{ + // "google": { + // "expectUserResponse": true, + // "richResponse": { + // "items": [ + // { + // "simpleResponse": { + // "textToSpeech": "this is a simple response" + // } + // } + // ] + // } + // } + // }</pre> + google.protobuf.Struct payload = 4; + + // Optional. The collection of output contexts. This value is passed directly + // to `QueryResult.output_contexts`. + repeated Context output_contexts = 5; + + // Optional. Makes the platform immediately invoke another `DetectIntent` call + // internally with the specified event as input. + EventInput followup_event_input = 6; + + // Optional. Indicates that this intent ends an interaction. Some integrations + // (e.g., Actions on Google or Dialogflow phone gateway) use this information + // to close interaction with an end user. Default is false. + bool end_interaction = 8; +} + +// Represents the contents of the original request that was passed to +// the `[Streaming]DetectIntent` call. +message OriginalDetectIntentRequest { + // The source of this request, e.g., `google`, `facebook`, `slack`. It is set + // by Dialogflow-owned servers. + string source = 1; + + // Optional. The version of the protocol used for this request. + // This field is AoG-specific. + string version = 2; + + // Optional. This field is set to the value of the `QueryParameters.payload` + // field passed in the request. Some integrations that query a Dialogflow + // agent may provide additional information in the payload. + // + // In particular for the Telephony Gateway this field has the form: + // <pre>{ + // "telephony": { + // "caller_id": "+18558363987" + // } + // }</pre> + // Note: The caller ID field (`caller_id`) will be redacted for Standard + // Edition agents and populated with the caller ID in [E.164 + // format](https://en.wikipedia.org/wiki/E.164) for Enterprise Edition agents. + google.protobuf.Struct payload = 3; +} diff --git a/google/cloud/functions/README.md b/google/cloud/functions/README.md new file mode 100644 index 000000000..4a9d225c7 --- /dev/null +++ b/google/cloud/functions/README.md @@ -0,0 +1,2 @@ +API for managing lightweight user-provided functions executed in response to +events.
\ No newline at end of file diff --git a/google/cloud/functions/artman_functions.yaml b/google/cloud/functions/artman_functions.yaml new file mode 100644 index 000000000..d23f76de3 --- /dev/null +++ b/google/cloud/functions/artman_functions.yaml @@ -0,0 +1,34 @@ +common: + api_name: functions + api_version: v1beta2 + organization_name: google-cloud + service_yaml: functions.yaml + gapic_yaml: v1beta2/functions_gapic.yaml + src_proto_paths: + - v1beta2 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/functions/functions.yaml b/google/cloud/functions/functions.yaml new file mode 100644 index 000000000..01c703bcd --- /dev/null +++ b/google/cloud/functions/functions.yaml @@ -0,0 +1,20 @@ +type: google.api.Service +config_version: 0 +name: cloudfunctions.googleapis.com +title: Google Cloud Functions API + +apis: +- name: google.cloud.functions.v1beta2.CloudFunctionsService + +documentation: + summary: + 'Google Cloud Functions is a lightweight, event-based, asynchronous compute + solution that allows you to create small, single-purpose functions that + respond to cloud events without the need to manage a server or a runtime + environment.' + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/functions/v1beta2/functions.proto b/google/cloud/functions/v1beta2/functions.proto new file mode 100644 index 000000000..77a66841a --- /dev/null +++ b/google/cloud/functions/v1beta2/functions.proto @@ -0,0 +1,312 @@ +// 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; +} diff --git a/google/cloud/functions/v1beta2/functions_gapic.yaml b/google/cloud/functions/v1beta2/functions_gapic.yaml new file mode 100644 index 000000000..3f7e53ade --- /dev/null +++ b/google/cloud/functions/v1beta2/functions_gapic.yaml @@ -0,0 +1,148 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.functions.v1beta2 + python: + package_name: google.cloud.functions_v1beta2.gapic + go: + package_name: cloud.google.com/go/cloud/functions/apiv1beta2 + csharp: + package_name: Google.Cloud.Functions.V1Beta2 + ruby: + package_name: Google::Cloud::Functions::V1beta2 + php: + package_name: Google\Cloud\Functions\V1beta2 + nodejs: + package_name: functions.v1beta2 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.functions.v1beta2.CloudFunctionsService + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/functions/{function} + entity_name: function + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + methods: + - name: ListFunctions + flattening: + groups: + - parameters: + - location + required_fields: + - location + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: functions + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + location: location + timeout_millis: 60000 + - name: GetFunction + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: function + timeout_millis: 60000 + - name: CreateFunction + flattening: + groups: + - parameters: + - location + - function + required_fields: + - location + - function + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + location: location + timeout_millis: 60000 + long_running: + return_type: google.cloud.functions.v1beta2.CloudFunction + metadata_type: google.cloud.functions.v1beta2.OperationMetadataV1Beta2 + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + - name: UpdateFunction + flattening: + groups: + - parameters: + - name + - function + required_fields: + - name + - function + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: function + timeout_millis: 60000 + long_running: + return_type: google.cloud.functions.v1beta2.CloudFunction + metadata_type: google.cloud.functions.v1beta2.OperationMetadataV1Beta2 + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + - name: DeleteFunction + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: function + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.functions.v1beta2.OperationMetadataV1Beta2 + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + - name: CallFunction + flattening: + groups: + - parameters: + - name + - data + required_fields: + - name + - data + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: function + timeout_millis: 60000 diff --git a/google/cloud/functions/v1beta2/operations.proto b/google/cloud/functions/v1beta2/operations.proto new file mode 100644 index 000000000..1456a924e --- /dev/null +++ b/google/cloud/functions/v1beta2/operations.proto @@ -0,0 +1,53 @@ +// 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/protobuf/any.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/functions/v1beta2;functions"; +option java_multiple_files = true; +option java_outer_classname = "FunctionsOperationsProto"; +option java_package = "com.google.cloud.functions.v1beta2"; + +// Metadata describing an [Operation][google.longrunning.Operation] +message OperationMetadataV1Beta2 { + // Target of the operation - for example + // projects/project-1/locations/region-1/functions/function-1 + string target = 1; + + // Type of operation. + OperationType type = 2; + + // The original request that started the operation. + google.protobuf.Any request = 3; +} + +// A type of an operation. +enum OperationType { + // Unknown operation type. + OPERATION_UNSPECIFIED = 0; + + // Triggered by CreateFunction call + CREATE_FUNCTION = 1; + + // Triggered by UpdateFunction call + UPDATE_FUNCTION = 2; + + // Triggered by DeleteFunction call. + DELETE_FUNCTION = 3; +} diff --git a/google/cloud/iot/BUILD.bazel b/google/cloud/iot/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/iot/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/iot/artman_cloudiot.yaml b/google/cloud/iot/artman_cloudiot.yaml new file mode 100644 index 000000000..4ff6d9a40 --- /dev/null +++ b/google/cloud/iot/artman_cloudiot.yaml @@ -0,0 +1,36 @@ +common: + api_name: iot + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + - name: google-iam-v1 + proto_path: google/iam/v1 + src_proto_paths: + - v1 + service_yaml: cloudiot.yaml + gapic_yaml: v1/cloudiot_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/iot/cloudiot.yaml b/google/cloud/iot/cloudiot.yaml new file mode 100644 index 000000000..2529f622a --- /dev/null +++ b/google/cloud/iot/cloudiot.yaml @@ -0,0 +1,20 @@ +type: google.api.Service +config_version: 3 +name: cloudiot.googleapis.com +title: Cloud IoT API + +apis: +- name: google.cloud.iot.v1.DeviceManager + +documentation: + summary: |- + Registers and manages IoT (Internet of Things) devices that connect to the + Google Cloud Platform. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloudiot diff --git a/google/cloud/iot/v1/BUILD.bazel b/google/cloud/iot/v1/BUILD.bazel new file mode 100644 index 000000000..0b149b507 --- /dev/null +++ b/google/cloud/iot/v1/BUILD.bazel @@ -0,0 +1,151 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "iot_proto", + srcs = [ + "device_manager.proto", + "resources.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/iam/v1:iam_policy_proto", + "//google/iam/v1:policy_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "iot_proto_with_info", + deps = [":iot_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", + "@com_google_api_grpc_proto_google_iam_v1//jar", +] + +java_proto_library( + name = "iot_java_proto", + deps = [":iot_proto"], +) + +java_grpc_library( + name = "iot_java_grpc", + srcs = [":iot_proto"], + deps = [":iot_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "iot_resource_name_java_proto", + gapic_yaml = "cloudiot_gapic.yaml", + deps = [":iot_proto"], +) + +java_gapic_library( + name = "iot_java_gapic", + src = ":iot_proto_with_info", + gapic_yaml = "cloudiot_gapic.yaml", + service_yaml = "//google/cloud/iot:cloudiot.yaml", + test_deps = [":iot_java_grpc"], + deps = [ + ":iot_java_proto", + ":iot_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":iot_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.iot.v1.DeviceManagerClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-iot-v1-java", + client_deps = [":iot_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":iot_java_gapic_test"], + grpc_deps = [":iot_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":iot_java_proto", + ":iot_proto", + ":iot_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "iot_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/iot/v1", + protos = [":iot_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/iam/v1:iam_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "iot_go_gapic", + src = ":iot_proto_with_info", + gapic_yaml = "cloudiot_gapic.yaml", + importpath = "cloud.google.com/go/iot/apiv1", + service_yaml = "//google/cloud/iot:cloudiot.yaml", + deps = [ + ":iot_go_proto", + "//google/iam/v1:iam_go_proto", + ], +) + +go_test( + name = "iot_go_gapic_test", + srcs = [":iot_go_gapic_srcjar_test"], + embed = [":iot_go_gapic"], + importpath = "cloud.google.com/go/iot/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-iot-v1-go", + deps = [ + ":iot_go_gapic", + ":iot_go_gapic_srcjar-smoke-test.srcjar", + ":iot_go_gapic_srcjar-test.srcjar", + ":iot_go_proto", + ], +) diff --git a/google/cloud/iot/v1/cloudiot_gapic.yaml b/google/cloud/iot/v1/cloudiot_gapic.yaml new file mode 100644 index 000000000..72ed2c09b --- /dev/null +++ b/google/cloud/iot/v1/cloudiot_gapic.yaml @@ -0,0 +1,514 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.iot.v1 + python: + package_name: google.cloud.iot_v1.gapic + go: + package_name: cloud.google.com/go/iot/apiv1 + csharp: + package_name: Google.Cloud.Iot.V1 + ruby: + package_name: Google::Cloud::Iot::V1 + php: + package_name: Google\Cloud\Iot\V1 + nodejs: + package_name: iot.v1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.iot.v1.DeviceManager + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/registries/{registry} + entity_name: registry + - name_pattern: projects/{project}/locations/{location}/registries/{registry}/devices/{device} + entity_name: device + # Definition for smoke test. + smoke_test: + method: ListDeviceRegistries + init_fields: + - parent%project=$PROJECT_ID + - parent%location="us-central1" + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + - name: rate_limited_aware + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - RESOURCE_EXHAUSTED + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 120000 + - name: rate_limited_aware + initial_retry_delay_millis: 1000 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 120000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateDeviceRegistry + flattening: + groups: + - parameters: + - parent + - device_registry + required_fields: + - parent + - device_registry + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetDeviceRegistry + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UpdateDeviceRegistry + flattening: + groups: + - parameters: + - device_registry + - update_mask + required_fields: + - device_registry + - update_mask + header_request_params: + - device_registry.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + device_registry.name: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: DeleteDeviceRegistry + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ListDeviceRegistries + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: device_registries + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: CreateDevice + flattening: + groups: + - parameters: + - parent + - device + required_fields: + - parent + - device + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetDevice + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: device + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UpdateDevice + flattening: + groups: + - parameters: + - device + - update_mask + required_fields: + - device + - update_mask + header_request_params: + - device.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + device.name: device + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: DeleteDevice + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: device + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ListDevices + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: devices + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ModifyCloudToDeviceConfig + flattening: + groups: + - parameters: + - name + - binary_data + required_fields: + - name + - binary_data + header_request_params: + - name + retry_codes_name: rate_limited_aware + retry_params_name: rate_limited_aware + field_name_patterns: + name: device + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ListDeviceConfigVersions + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: device + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ListDeviceStates + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: device + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: SetIamPolicy + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + header_request_params: + - resource + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetIamPolicy + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + header_request_params: + - resource + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: TestIamPermissions + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + header_request_params: + - resource + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: SendCommandToDevice + flattening: + groups: + - parameters: + - name + - binary_data + - subfolder + required_fields: + - name + - binary_data + header_request_params: + - name + retry_codes_name: rate_limited_aware + retry_params_name: rate_limited_aware + field_name_patterns: + name: device + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: BindDeviceToGateway + flattening: + groups: + - parameters: + - parent + - gateway_id + - device_id + required_fields: + - parent + - gateway_id + - device_id + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UnbindDeviceFromGateway + flattening: + groups: + - parameters: + - parent + - gateway_id + - device_id + required_fields: + - parent + - gateway_id + - device_id + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: registry + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 +resource_name_generation: +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: "*" +- message_name: CreateDeviceRegistryRequest + field_entity_map: + parent: location +- message_name: GetDeviceRegistryRequest + field_entity_map: + name: registry +- message_name: DeleteDeviceRegistryRequest + field_entity_map: + name: registry +- message_name: ListDeviceRegistriesRequest + field_entity_map: + parent: location +- message_name: CreateDeviceRequest + field_entity_map: + parent: registry +- message_name: GetDeviceRequest + field_entity_map: + name: device +- message_name: DeleteDeviceRequest + field_entity_map: + name: device +- message_name: ListDevicesRequest + field_entity_map: + parent: registry +- message_name: ModifyCloudToDeviceConfigRequest + field_entity_map: + name: device +- message_name: ListDeviceConfigVersionsRequest + field_entity_map: + name: device +- message_name: ListDeviceStatesRequest + field_entity_map: + name: device +- message_name: SendCommandToDeviceRequest + field_entity_map: + name: device +- message_name: BindDeviceToGatewayRequest + field_entity_map: + parent: registry +- message_name: UnbindDeviceFromGatewayRequest + field_entity_map: + parent: registry +- message_name: Device + field_entity_map: + name: device +- message_name: DeviceRegistry + field_entity_map: + name: registry diff --git a/google/cloud/iot/v1/device_manager.proto b/google/cloud/iot/v1/device_manager.proto new file mode 100644 index 000000000..27ec0f030 --- /dev/null +++ b/google/cloud/iot/v1/device_manager.proto @@ -0,0 +1,562 @@ +// Copyright 2018 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.iot.v1; + +import "google/api/annotations.proto"; +import "google/cloud/iot/v1/resources.proto"; +import "google/iam/v1/iam_policy.proto"; +import "google/iam/v1/policy.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/iot/v1;iot"; +option java_multiple_files = true; +option java_outer_classname = "DeviceManagerProto"; +option java_package = "com.google.cloud.iot.v1"; + +// Internet of Things (IoT) service. Securely connect and manage IoT devices. +service DeviceManager { + // Creates a device registry that contains devices. + rpc CreateDeviceRegistry(CreateDeviceRegistryRequest) + returns (DeviceRegistry) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/registries" + body: "device_registry" + }; + } + + // Gets a device registry configuration. + rpc GetDeviceRegistry(GetDeviceRegistryRequest) returns (DeviceRegistry) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/registries/*}" + }; + } + + // Updates a device registry configuration. + rpc UpdateDeviceRegistry(UpdateDeviceRegistryRequest) + returns (DeviceRegistry) { + option (google.api.http) = { + patch: "/v1/{device_registry.name=projects/*/locations/*/registries/*}" + body: "device_registry" + }; + } + + // Deletes a device registry configuration. + rpc DeleteDeviceRegistry(DeleteDeviceRegistryRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/registries/*}" + }; + } + + // Lists device registries. + rpc ListDeviceRegistries(ListDeviceRegistriesRequest) + returns (ListDeviceRegistriesResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/registries" + }; + } + + // Creates a device in a device registry. + rpc CreateDevice(CreateDeviceRequest) returns (Device) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*/registries/*}/devices" + body: "device" + }; + } + + // Gets details about a device. + rpc GetDevice(GetDeviceRequest) returns (Device) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}" + additional_bindings { + get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}" + } + }; + } + + // Updates a device. + rpc UpdateDevice(UpdateDeviceRequest) returns (Device) { + option (google.api.http) = { + patch: "/v1/{device.name=projects/*/locations/*/registries/*/devices/*}" + body: "device" + additional_bindings { + patch: "/v1/{device.name=projects/*/locations/*/registries/*/groups/*/devices/*}" + body: "device" + } + }; + } + + // Deletes a device. + rpc DeleteDevice(DeleteDeviceRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/registries/*/devices/*}" + }; + } + + // List devices in a device registry. + rpc ListDevices(ListDevicesRequest) returns (ListDevicesResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*/registries/*}/devices" + additional_bindings { + get: "/v1/{parent=projects/*/locations/*/registries/*/groups/*}/devices" + } + }; + } + + // Modifies the configuration for the device, which is eventually sent from + // the Cloud IoT Core servers. Returns the modified configuration version and + // its metadata. + rpc ModifyCloudToDeviceConfig(ModifyCloudToDeviceConfigRequest) + returns (DeviceConfig) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/registries/*/devices/*}:modifyCloudToDeviceConfig" + body: "*" + additional_bindings { + post: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}:modifyCloudToDeviceConfig" + body: "*" + } + }; + } + + // Lists the last few versions of the device configuration in descending + // order (i.e.: newest first). + rpc ListDeviceConfigVersions(ListDeviceConfigVersionsRequest) + returns (ListDeviceConfigVersionsResponse) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}/configVersions" + additional_bindings { + get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}/configVersions" + } + }; + } + + // Lists the last few versions of the device state in descending order (i.e.: + // newest first). + rpc ListDeviceStates(ListDeviceStatesRequest) + returns (ListDeviceStatesResponse) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}/states" + additional_bindings { + get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}/states" + } + }; + } + + // Sets the access control policy on the specified resource. Replaces any + // existing policy. + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v1/{resource=projects/*/locations/*/registries/*}:setIamPolicy" + body: "*" + additional_bindings { + post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:setIamPolicy" + body: "*" + } + }; + } + + // Gets the access control policy for a resource. + // Returns an empty policy if the resource exists and does not have a policy + // set. + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v1/{resource=projects/*/locations/*/registries/*}:getIamPolicy" + body: "*" + additional_bindings { + post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:getIamPolicy" + body: "*" + } + }; + } + + // Returns permissions that a caller has on the specified resource. + // If the resource does not exist, this will return an empty set of + // permissions, not a NOT_FOUND error. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) + returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v1/{resource=projects/*/locations/*/registries/*}:testIamPermissions" + body: "*" + additional_bindings { + post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:testIamPermissions" + body: "*" + } + }; + } + + // Sends a command to the specified device. In order for a device to be able + // to receive commands, it must: + // 1) be connected to Cloud IoT Core using the MQTT protocol, and + // 2) be subscribed to the group of MQTT topics specified by + // /devices/{device-id}/commands/#. This subscription will receive commands + // at the top-level topic /devices/{device-id}/commands as well as commands + // for subfolders, like /devices/{device-id}/commands/subfolder. + // Note that subscribing to specific subfolders is not supported. + // If the command could not be delivered to the device, this method will + // return an error; in particular, if the device is not subscribed, this + // method will return FAILED_PRECONDITION. Otherwise, this method will + // return OK. If the subscription is QoS 1, at least once delivery will be + // guaranteed; for QoS 0, no acknowledgment will be expected from the device. + rpc SendCommandToDevice(SendCommandToDeviceRequest) + returns (SendCommandToDeviceResponse) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/registries/*/devices/*}:sendCommandToDevice" + body: "*" + additional_bindings { + post: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}:sendCommandToDevice" + body: "*" + } + }; + } + + // Associates the device with the gateway. + rpc BindDeviceToGateway(BindDeviceToGatewayRequest) + returns (BindDeviceToGatewayResponse) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*/registries/*}:bindDeviceToGateway" + body: "*" + additional_bindings { + post: "/v1/{parent=projects/*/locations/*/registries/*/groups/*}:bindDeviceToGateway" + body: "*" + } + }; + } + + // Deletes the association between the device and the gateway. + rpc UnbindDeviceFromGateway(UnbindDeviceFromGatewayRequest) + returns (UnbindDeviceFromGatewayResponse) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*/registries/*}:unbindDeviceFromGateway" + body: "*" + additional_bindings { + post: "/v1/{parent=projects/*/locations/*/registries/*/groups/*}:unbindDeviceFromGateway" + body: "*" + } + }; + } +} + +// Request for `CreateDeviceRegistry`. +message CreateDeviceRegistryRequest { + // The project and cloud region where this device registry must be created. + // For example, `projects/example-project/locations/us-central1`. + string parent = 1; + + // The device registry. The field `name` must be empty. The server will + // generate that field from the device registry `id` provided and the + // `parent` field. + DeviceRegistry device_registry = 2; +} + +// Request for `GetDeviceRegistry`. +message GetDeviceRegistryRequest { + // The name of the device registry. For example, + // `projects/example-project/locations/us-central1/registries/my-registry`. + string name = 1; +} + +// Request for `DeleteDeviceRegistry`. +message DeleteDeviceRegistryRequest { + // The name of the device registry. For example, + // `projects/example-project/locations/us-central1/registries/my-registry`. + string name = 1; +} + +// Request for `UpdateDeviceRegistry`. +message UpdateDeviceRegistryRequest { + // The new values for the device registry. The `id` field must be empty, and + // the `name` field must indicate the path of the resource. For example, + // `projects/example-project/locations/us-central1/registries/my-registry`. + DeviceRegistry device_registry = 1; + + // Only updates the `device_registry` fields indicated by this mask. + // The field mask must not be empty, and it must not contain fields that + // are immutable or only set by the server. + // Mutable top-level fields: `event_notification_config`, `http_config`, + // `mqtt_config`, and `state_notification_config`. + google.protobuf.FieldMask update_mask = 2; +} + +// Request for `ListDeviceRegistries`. +message ListDeviceRegistriesRequest { + // The project and cloud region path. For example, + // `projects/example-project/locations/us-central1`. + string parent = 1; + + // The maximum number of registries to return in the response. If this value + // is zero, the service will select a default size. A call may return fewer + // objects than requested. A non-empty `next_page_token` in the response + // indicates that more data is available. + int32 page_size = 2; + + // The value returned by the last `ListDeviceRegistriesResponse`; indicates + // that this is a continuation of a prior `ListDeviceRegistries` call and + // the system should return the next page of data. + string page_token = 3; +} + +// Response for `ListDeviceRegistries`. +message ListDeviceRegistriesResponse { + // The registries that matched the query. + repeated DeviceRegistry device_registries = 1; + + // If not empty, indicates that there may be more registries that match the + // request; this value should be passed in a new + // `ListDeviceRegistriesRequest`. + string next_page_token = 2; +} + +// Request for `CreateDevice`. +message CreateDeviceRequest { + // The name of the device registry where this device should be created. + // For example, + // `projects/example-project/locations/us-central1/registries/my-registry`. + string parent = 1; + + // The device registration details. The field `name` must be empty. The server + // generates `name` from the device registry `id` and the + // `parent` field. + Device device = 2; +} + +// Request for `GetDevice`. +message GetDeviceRequest { + // The name of the device. For example, + // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or + // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. + string name = 1; + + // The fields of the `Device` resource to be returned in the response. If the + // field mask is unset or empty, all fields are returned. + google.protobuf.FieldMask field_mask = 2; +} + +// Request for `UpdateDevice`. +message UpdateDeviceRequest { + // The new values for the device. The `id` and `num_id` fields must + // be empty, and the field `name` must specify the name path. For example, + // `projects/p0/locations/us-central1/registries/registry0/devices/device0`or + // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. + Device device = 2; + + // Only updates the `device` fields indicated by this mask. + // The field mask must not be empty, and it must not contain fields that + // are immutable or only set by the server. + // Mutable top-level fields: `credentials`, `blocked`, and `metadata` + google.protobuf.FieldMask update_mask = 3; +} + +// Request for `DeleteDevice`. +message DeleteDeviceRequest { + // The name of the device. For example, + // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or + // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. + string name = 1; +} + +// Request for `ListDevices`. +message ListDevicesRequest { + // The device registry path. Required. For example, + // `projects/my-project/locations/us-central1/registries/my-registry`. + string parent = 1; + + // A list of device numeric IDs. If empty, this field is ignored. Maximum + // IDs: 10,000. + repeated uint64 device_num_ids = 2; + + // A list of device string IDs. For example, `['device0', 'device12']`. + // If empty, this field is ignored. Maximum IDs: 10,000 + repeated string device_ids = 3; + + // The fields of the `Device` resource to be returned in the response. The + // fields `id` and `num_id` are always returned, along with any + // other fields specified. + google.protobuf.FieldMask field_mask = 4; + + // Options related to gateways. + GatewayListOptions gateway_list_options = 6; + + // The maximum number of devices to return in the response. If this value + // is zero, the service will select a default size. A call may return fewer + // objects than requested. A non-empty `next_page_token` in the response + // indicates that more data is available. + int32 page_size = 100; + + // The value returned by the last `ListDevicesResponse`; indicates + // that this is a continuation of a prior `ListDevices` call and + // the system should return the next page of data. + string page_token = 101; +} + +// Options for limiting the list based on gateway type and associations. +message GatewayListOptions { + // If not set, all devices and gateways are returned. If set, the list is + // filtered based on gateway type and associations. + oneof filter { + // If `GATEWAY` is specified, only gateways are returned. If `NON_GATEWAY` + // is specified, only non-gateway devices are returned. If + // `GATEWAY_TYPE_UNSPECIFIED` is specified, all devices are returned. + GatewayType gateway_type = 1; + + // If set, only devices associated with the specified gateway are returned. + // The gateway ID can be numeric (`num_id`) or the user-defined string + // (`id`). For example, if `123` is specified, only devices bound to the + // gateway with `num_id` 123 are returned. + string associations_gateway_id = 2; + + // If set, returns only the gateways with which the specified device is + // associated. The device ID can be numeric (`num_id`) or the user-defined + // string (`id`). For example, if `456` is specified, returns only the + // gateways to which the device with `num_id` 456 is bound. + string associations_device_id = 3; + } +} + +// Response for `ListDevices`. +message ListDevicesResponse { + // The devices that match the request. + repeated Device devices = 1; + + // If not empty, indicates that there may be more devices that match the + // request; this value should be passed in a new `ListDevicesRequest`. + string next_page_token = 2; +} + +// Request for `ModifyCloudToDeviceConfig`. +message ModifyCloudToDeviceConfigRequest { + // The name of the device. For example, + // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or + // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. + string name = 1; + + // The version number to update. If this value is zero, it will not check the + // version number of the server and will always update the current version; + // otherwise, this update will fail if the version number found on the server + // does not match this version number. This is used to support multiple + // simultaneous updates without losing data. + int64 version_to_update = 2; + + // The configuration data for the device. + bytes binary_data = 3; +} + +// Request for `ListDeviceConfigVersions`. +message ListDeviceConfigVersionsRequest { + // The name of the device. For example, + // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or + // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. + string name = 1; + + // The number of versions to list. Versions are listed in decreasing order of + // the version number. The maximum number of versions retained is 10. If this + // value is zero, it will return all the versions available. + int32 num_versions = 2; +} + +// Response for `ListDeviceConfigVersions`. +message ListDeviceConfigVersionsResponse { + // The device configuration for the last few versions. Versions are listed + // in decreasing order, starting from the most recent one. + repeated DeviceConfig device_configs = 1; +} + +// Request for `ListDeviceStates`. +message ListDeviceStatesRequest { + // The name of the device. For example, + // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or + // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. + string name = 1; + + // The number of states to list. States are listed in descending order of + // update time. The maximum number of states retained is 10. If this + // value is zero, it will return all the states available. + int32 num_states = 2; +} + +// Response for `ListDeviceStates`. +message ListDeviceStatesResponse { + // The last few device states. States are listed in descending order of server + // update time, starting from the most recent one. + repeated DeviceState device_states = 1; +} + +// Request for `SendCommandToDevice`. +message SendCommandToDeviceRequest { + // The name of the device. For example, + // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or + // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. + string name = 1; + + // The command data to send to the device. + bytes binary_data = 2; + + // Optional subfolder for the command. If empty, the command will be delivered + // to the /devices/{device-id}/commands topic, otherwise it will be delivered + // to the /devices/{device-id}/commands/{subfolder} topic. Multi-level + // subfolders are allowed. This field must not have more than 256 characters, + // and must not contain any MQTT wildcards ("+" or "#") or null characters. + string subfolder = 3; +} + +// Response for `SendCommandToDevice`. +message SendCommandToDeviceResponse {} + +// Request for `BindDeviceToGateway`. +message BindDeviceToGatewayRequest { + // The name of the registry. For example, + // `projects/example-project/locations/us-central1/registries/my-registry`. + string parent = 1; + + // The value of `gateway_id` can be either the device numeric ID or the + // user-defined device identifier. + string gateway_id = 2; + + // The device to associate with the specified gateway. The value of + // `device_id` can be either the device numeric ID or the user-defined device + // identifier. + string device_id = 3; +} + +// Response for `BindDeviceToGateway`. +message BindDeviceToGatewayResponse {} + +// Request for `UnbindDeviceFromGateway`. +message UnbindDeviceFromGatewayRequest { + // The name of the registry. For example, + // `projects/example-project/locations/us-central1/registries/my-registry`. + string parent = 1; + + // The value of `gateway_id` can be either the device numeric ID or the + // user-defined device identifier. + string gateway_id = 2; + + // The device to disassociate from the specified gateway. The value of + // `device_id` can be either the device numeric ID or the user-defined device + // identifier. + string device_id = 3; +} + +// Response for `UnbindDeviceFromGateway`. +message UnbindDeviceFromGatewayResponse {} diff --git a/google/cloud/iot/v1/resources.proto b/google/cloud/iot/v1/resources.proto new file mode 100644 index 000000000..2a91e989e --- /dev/null +++ b/google/cloud/iot/v1/resources.proto @@ -0,0 +1,474 @@ +// Copyright 2018 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.iot.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/iot/v1;iot"; +option java_multiple_files = true; +option java_outer_classname = "ResourcesProto"; +option java_package = "com.google.cloud.iot.v1"; + +// The device resource. +message Device { + // The user-defined device identifier. The device ID must be unique + // within a device registry. + string id = 1; + + // The resource path name. For example, + // `projects/p1/locations/us-central1/registries/registry0/devices/dev0` or + // `projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`. + // When `name` is populated as a response from the service, it always ends + // in the device numeric ID. + string name = 2; + + // [Output only] A server-defined unique numeric ID for the device. This is a + // more compact way to identify devices, and it is globally unique. + uint64 num_id = 3; + + // The credentials used to authenticate this device. To allow credential + // rotation without interruption, multiple device credentials can be bound to + // this device. No more than 3 credentials can be bound to a single device at + // a time. When new credentials are added to a device, they are verified + // against the registry credentials. For details, see the description of the + // `DeviceRegistry.credentials` field. + repeated DeviceCredential credentials = 12; + + // [Output only] The last time an MQTT `PINGREQ` was received. This field + // applies only to devices connecting through MQTT. MQTT clients usually only + // send `PINGREQ` messages if the connection is idle, and no other messages + // have been sent. Timestamps are periodically collected and written to + // storage; they may be stale by a few minutes. + google.protobuf.Timestamp last_heartbeat_time = 7; + + // [Output only] The last time a telemetry event was received. Timestamps are + // periodically collected and written to storage; they may be stale by a few + // minutes. + google.protobuf.Timestamp last_event_time = 8; + + // [Output only] The last time a state event was received. Timestamps are + // periodically collected and written to storage; they may be stale by a few + // minutes. + google.protobuf.Timestamp last_state_time = 20; + + // [Output only] The last time a cloud-to-device config version acknowledgment + // was received from the device. This field is only for configurations + // sent through MQTT. + google.protobuf.Timestamp last_config_ack_time = 14; + + // [Output only] The last time a cloud-to-device config version was sent to + // the device. + google.protobuf.Timestamp last_config_send_time = 18; + + // If a device is blocked, connections or requests from this device will fail. + // Can be used to temporarily prevent the device from connecting if, for + // example, the sensor is generating bad data and needs maintenance. + bool blocked = 19; + + // [Output only] The time the most recent error occurred, such as a failure to + // publish to Cloud Pub/Sub. This field is the timestamp of + // 'last_error_status'. + google.protobuf.Timestamp last_error_time = 10; + + // [Output only] The error message of the most recent error, such as a failure + // to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this + // field. If no errors have occurred, this field has an empty message + // and the status code 0 == OK. Otherwise, this field is expected to have a + // status code other than OK. + google.rpc.Status last_error_status = 11; + + // The most recent device configuration, which is eventually sent from + // Cloud IoT Core to the device. If not present on creation, the + // configuration will be initialized with an empty payload and version value + // of `1`. To update this field after creation, use the + // `DeviceManager.ModifyCloudToDeviceConfig` method. + DeviceConfig config = 13; + + // [Output only] The state most recently received from the device. If no state + // has been reported, this field is not present. + DeviceState state = 16; + + // **Beta Feature** + // + // The logging verbosity for device activity. If unspecified, + // DeviceRegistry.log_level will be used. + LogLevel log_level = 21; + + // The metadata key-value pairs assigned to the device. This metadata is not + // interpreted or indexed by Cloud IoT Core. It can be used to add contextual + // information for the device. + // + // Keys must conform to the regular expression [a-zA-Z][a-zA-Z0-9-_.+~%]+ and + // be less than 128 bytes in length. + // + // Values are free-form strings. Each value must be less than or equal to 32 + // KB in size. + // + // The total size of all keys and values must be less than 256 KB, and the + // maximum number of key-value pairs is 500. + map<string, string> metadata = 17; + + // Gateway-related configuration and state. + GatewayConfig gateway_config = 24; +} + +// Gateway-related configuration and state. +message GatewayConfig { + // Indicates whether the device is a gateway. + GatewayType gateway_type = 1; + + // Indicates how to authorize and/or authenticate devices to access the + // gateway. + GatewayAuthMethod gateway_auth_method = 2; + + // [Output only] The ID of the gateway the device accessed most recently. + string last_accessed_gateway_id = 3; + + // [Output only] The most recent time at which the device accessed the gateway + // specified in `last_accessed_gateway`. + google.protobuf.Timestamp last_accessed_gateway_time = 4; +} + +// A container for a group of devices. +message DeviceRegistry { + // The identifier of this device registry. For example, `myRegistry`. + string id = 1; + + // The resource path name. For example, + // `projects/example-project/locations/us-central1/registries/my-registry`. + string name = 2; + + // The configuration for notification of telemetry events received from the + // device. All telemetry events that were successfully published by the + // device and acknowledged by Cloud IoT Core are guaranteed to be + // delivered to Cloud Pub/Sub. If multiple configurations match a message, + // only the first matching configuration is used. If you try to publish a + // device telemetry event using MQTT without specifying a Cloud Pub/Sub topic + // for the device's registry, the connection closes automatically. If you try + // to do so using an HTTP connection, an error is returned. Up to 10 + // configurations may be provided. + repeated EventNotificationConfig event_notification_configs = 10; + + // The configuration for notification of new states received from the device. + // State updates are guaranteed to be stored in the state history, but + // notifications to Cloud Pub/Sub are not guaranteed. For example, if + // permissions are misconfigured or the specified topic doesn't exist, no + // notification will be published but the state will still be stored in Cloud + // IoT Core. + StateNotificationConfig state_notification_config = 7; + + // The MQTT configuration for this device registry. + MqttConfig mqtt_config = 4; + + // The DeviceService (HTTP) configuration for this device registry. + HttpConfig http_config = 9; + + // **Beta Feature** + // + // The default logging verbosity for activity from devices in this registry. + // The verbosity level can be overridden by Device.log_level. + LogLevel log_level = 11; + + // The credentials used to verify the device credentials. No more than 10 + // credentials can be bound to a single registry at a time. The verification + // process occurs at the time of device creation or update. If this field is + // empty, no verification is performed. Otherwise, the credentials of a newly + // created device or added credentials of an updated device should be signed + // with one of these registry credentials. + // + // Note, however, that existing devices will never be affected by + // modifications to this list of credentials: after a device has been + // successfully created in a registry, it should be able to connect even if + // its registry credentials are revoked, deleted, or modified. + repeated RegistryCredential credentials = 8; +} + +// The configuration of MQTT for a device registry. +message MqttConfig { + // If enabled, allows connections using the MQTT protocol. Otherwise, MQTT + // connections to this registry will fail. + MqttState mqtt_enabled_state = 1; +} + +// The configuration of the HTTP bridge for a device registry. +message HttpConfig { + // If enabled, allows devices to use DeviceService via the HTTP protocol. + // Otherwise, any requests to DeviceService will fail for this registry. + HttpState http_enabled_state = 1; +} + +// The configuration for forwarding telemetry events. +message EventNotificationConfig { + // If the subfolder name matches this string exactly, this configuration will + // be used. The string must not include the leading '/' character. If empty, + // all strings are matched. This field is used only for telemetry events; + // subfolders are not supported for state changes. + string subfolder_matches = 2; + + // A Cloud Pub/Sub topic name. For example, + // `projects/myProject/topics/deviceEvents`. + string pubsub_topic_name = 1; +} + +// The configuration for notification of new states received from the device. +message StateNotificationConfig { + // A Cloud Pub/Sub topic name. For example, + // `projects/myProject/topics/deviceEvents`. + string pubsub_topic_name = 1; +} + +// A server-stored registry credential used to validate device credentials. +message RegistryCredential { + // The credential data. Reserved for expansion in the future. + oneof credential { + // A public key certificate used to verify the device credentials. + PublicKeyCertificate public_key_certificate = 1; + } +} + +// Details of an X.509 certificate. For informational purposes only. +message X509CertificateDetails { + // The entity that signed the certificate. + string issuer = 1; + + // The entity the certificate and public key belong to. + string subject = 2; + + // The time the certificate becomes valid. + google.protobuf.Timestamp start_time = 3; + + // The time the certificate becomes invalid. + google.protobuf.Timestamp expiry_time = 4; + + // The algorithm used to sign the certificate. + string signature_algorithm = 5; + + // The type of public key in the certificate. + string public_key_type = 6; +} + +// A public key certificate format and data. +message PublicKeyCertificate { + // The certificate format. + PublicKeyCertificateFormat format = 1; + + // The certificate data. + string certificate = 2; + + // [Output only] The certificate details. Used only for X.509 certificates. + X509CertificateDetails x509_details = 3; +} + +// A server-stored device credential used for authentication. +message DeviceCredential { + // The credential data. Reserved for expansion in the future. + oneof credential { + // A public key used to verify the signature of JSON Web Tokens (JWTs). + // When adding a new device credential, either via device creation or via + // modifications, this public key credential may be required to be signed by + // one of the registry level certificates. More specifically, if the + // registry contains at least one certificate, any new device credential + // must be signed by one of the registry certificates. As a result, + // when the registry contains certificates, only X.509 certificates are + // accepted as device credentials. However, if the registry does + // not contain a certificate, self-signed certificates and public keys will + // be accepted. New device credentials must be different from every + // registry-level certificate. + PublicKeyCredential public_key = 2; + } + + // [Optional] The time at which this credential becomes invalid. This + // credential will be ignored for new client authentication requests after + // this timestamp; however, it will not be automatically deleted. + google.protobuf.Timestamp expiration_time = 6; +} + +// A public key format and data. +message PublicKeyCredential { + // The format of the key. + PublicKeyFormat format = 1; + + // The key data. + string key = 2; +} + +// The device configuration. Eventually delivered to devices. +message DeviceConfig { + // [Output only] The version of this update. The version number is assigned by + // the server, and is always greater than 0 after device creation. The + // version must be 0 on the `CreateDevice` request if a `config` is + // specified; the response of `CreateDevice` will always have a value of 1. + int64 version = 1; + + // [Output only] The time at which this configuration version was updated in + // Cloud IoT Core. This timestamp is set by the server. + google.protobuf.Timestamp cloud_update_time = 2; + + // [Output only] The time at which Cloud IoT Core received the + // acknowledgment from the device, indicating that the device has received + // this configuration version. If this field is not present, the device has + // not yet acknowledged that it received this version. Note that when + // the config was sent to the device, many config versions may have been + // available in Cloud IoT Core while the device was disconnected, and on + // connection, only the latest version is sent to the device. Some + // versions may never be sent to the device, and therefore are never + // acknowledged. This timestamp is set by Cloud IoT Core. + google.protobuf.Timestamp device_ack_time = 3; + + // The device configuration data. + bytes binary_data = 4; +} + +// The device state, as reported by the device. +message DeviceState { + // [Output only] The time at which this state version was updated in Cloud + // IoT Core. + google.protobuf.Timestamp update_time = 1; + + // The device state data. + bytes binary_data = 2; +} + +// Indicates whether an MQTT connection is enabled or disabled. See the field +// description for details. +enum MqttState { + // No MQTT state specified. If not specified, MQTT will be enabled by default. + MQTT_STATE_UNSPECIFIED = 0; + + // Enables a MQTT connection. + MQTT_ENABLED = 1; + + // Disables a MQTT connection. + MQTT_DISABLED = 2; +} + +// Indicates whether DeviceService (HTTP) is enabled or disabled for the +// registry. See the field description for details. +enum HttpState { + // No HTTP state specified. If not specified, DeviceService will be + // enabled by default. + HTTP_STATE_UNSPECIFIED = 0; + + // Enables DeviceService (HTTP) service for the registry. + HTTP_ENABLED = 1; + + // Disables DeviceService (HTTP) service for the registry. + HTTP_DISABLED = 2; +} + +// **Beta Feature** +// +// The logging verbosity for device activity. Specifies which events should be +// written to logs. For example, if the LogLevel is ERROR, only events that +// terminate in errors will be logged. LogLevel is inclusive; enabling INFO +// logging will also enable ERROR logging. +enum LogLevel { + // No logging specified. If not specified, logging will be disabled. + LOG_LEVEL_UNSPECIFIED = 0; + + // Disables logging. + NONE = 10; + + // Error events will be logged. + ERROR = 20; + + // Informational events will be logged, such as connections and + // disconnections. + INFO = 30; + + // All events will be logged. + DEBUG = 40; +} + +// Gateway type. +enum GatewayType { + // If unspecified, the device is considered a non-gateway device. + GATEWAY_TYPE_UNSPECIFIED = 0; + + // The device is a gateway. + GATEWAY = 1; + + // The device is not a gateway. + NON_GATEWAY = 2; +} + +// The gateway authorization/authentication method. This setting determines how +// Cloud IoT Core authorizes/authenticate devices to access the gateway. +enum GatewayAuthMethod { + // No authentication/authorization method specified. No devices are allowed to + // access the gateway. + GATEWAY_AUTH_METHOD_UNSPECIFIED = 0; + + // The device is authenticated through the gateway association only. Device + // credentials are ignored even if provided. + ASSOCIATION_ONLY = 1; + + // The device is authenticated through its own credentials. Gateway + // association is not checked. + DEVICE_AUTH_TOKEN_ONLY = 2; + + // The device is authenticated through both device credentials and gateway + // association. The device must be bound to the gateway and must provide its + // own credentials. + ASSOCIATION_AND_DEVICE_AUTH_TOKEN = 3; +} + +// The supported formats for the public key. +enum PublicKeyCertificateFormat { + // The format has not been specified. This is an invalid default value and + // must not be used. + UNSPECIFIED_PUBLIC_KEY_CERTIFICATE_FORMAT = 0; + + // An X.509v3 certificate ([RFC5280](https://www.ietf.org/rfc/rfc5280.txt)), + // encoded in base64, and wrapped by `-----BEGIN CERTIFICATE-----` and + // `-----END CERTIFICATE-----`. + X509_CERTIFICATE_PEM = 1; +} + +// The supported formats for the public key. +enum PublicKeyFormat { + // The format has not been specified. This is an invalid default value and + // must not be used. + UNSPECIFIED_PUBLIC_KEY_FORMAT = 0; + + // An RSA public key encoded in base64, and wrapped by + // `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----`. This can be + // used to verify `RS256` signatures in JWT tokens ([RFC7518]( + // https://www.ietf.org/rfc/rfc7518.txt)). + RSA_PEM = 3; + + // As RSA_PEM, but wrapped in an X.509v3 certificate ([RFC5280]( + // https://www.ietf.org/rfc/rfc5280.txt)), encoded in base64, and wrapped by + // `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. + RSA_X509_PEM = 1; + + // Public key for the ECDSA algorithm using P-256 and SHA-256, encoded in + // base64, and wrapped by `-----BEGIN PUBLIC KEY-----` and `-----END + // PUBLIC KEY-----`. This can be used to verify JWT tokens with the `ES256` + // algorithm ([RFC7518](https://www.ietf.org/rfc/rfc7518.txt)). This curve is + // defined in [OpenSSL](https://www.openssl.org/) as the `prime256v1` curve. + ES256_PEM = 2; + + // As ES256_PEM, but wrapped in an X.509v3 certificate ([RFC5280]( + // https://www.ietf.org/rfc/rfc5280.txt)), encoded in base64, and wrapped by + // `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. + ES256_X509_PEM = 4; +} diff --git a/google/cloud/irm/artman_irm_v1alpha2.yaml b/google/cloud/irm/artman_irm_v1alpha2.yaml new file mode 100644 index 000000000..90ace2b94 --- /dev/null +++ b/google/cloud/irm/artman_irm_v1alpha2.yaml @@ -0,0 +1,34 @@ +common: + api_name: irm + api_version: v1alpha2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1alpha2 + service_yaml: irm_v1alpha2.yaml + gapic_yaml: v1alpha2/irm_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/irm/irm_v1alpha2.yaml b/google/cloud/irm/irm_v1alpha2.yaml new file mode 100644 index 000000000..114308b35 --- /dev/null +++ b/google/cloud/irm/irm_v1alpha2.yaml @@ -0,0 +1,25 @@ +type: google.api.Service +config_version: 3 +name: irm.googleapis.com +title: Stackdriver Incident Response & Management API + +apis: + - name: google.cloud.irm.v1alpha2.IncidentService + +types: + - name: google.cloud.irm.v1alpha2.User + - name: google.cloud.irm.v1alpha2.Synopsis + - name: google.cloud.irm.v1alpha2.IncidentRole + - name: google.cloud.irm.v1alpha2.CommunicationChannel + +documentation: + overview: |- + The Stackdriver Incident Response & Management API provides access to + incident data. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/irm/v1alpha2/incidents.proto b/google/cloud/irm/v1alpha2/incidents.proto new file mode 100644 index 000000000..af258ddbc --- /dev/null +++ b/google/cloud/irm/v1alpha2/incidents.proto @@ -0,0 +1,486 @@ +// Copyright 2018 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.irm.v1alpha2; + +import "google/api/annotations.proto"; +import "google/monitoring/v3/metric_service.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/irm/v1alpha2;irm"; +option java_multiple_files = true; +option java_package = "com.google.irm.service.v1alpha2.api"; + +// A user of the IRM app. +message User { + // One of several ways to uniquely identify a user. + oneof user { + // Output only. User id that will allow to get additional information from + // People API. This field will be populated implicitly if the caller creates + // or edits a resource (for example, posts an annotation). + string user_id = 1; + + // Email address of the user. This must be associated with a Google account. + // This field will be set if the user is explicitly identified (verbatim) by + // email address in an API request (potentially sometime in the past). It + // will not be populated based on the credentials of a caller of the API. + string email = 2; + } +} + +// A signal is a message calling attention to a (potential) incident. An example +// is a page based on a Stackdriver Alerting policy. +message Signal { + // An artifact associated with the Signal. + message SignalArtifact { + // The type of resource linked to + oneof artifact_type { + // A custom user type + string user_type = 2; + } + + // The URI for the artifact. + string uri = 3; + } + + // Describes whether the alerting condition is still firing. + enum State { + // Unspecified + STATE_UNSPECIFIED = 0; + + // Firing + STATE_OPEN = 1; + + // Non-firing + STATE_CLOSED = 2; + } + + // Resource name of the signal, for example, + // "projects/{project_id}/signals/{signal_id}". + string name = 1; + + // Etag to validate the object is unchanged for a read-modify-write operation. + // An empty etag will overwrite other changes. + string etag = 2; + + // Resource name of the incident this signal is currently assigned to. + // May be empty if signal is unassigned. + string incident = 3; + + // Output only. Time this signal was created. + google.protobuf.Timestamp create_time = 4; + + // Output only. Time this signal was closed. This field is not populated + // while the signal is still firing. + google.protobuf.Timestamp close_time = 10; + + // The time this Signal was first detected. This is identical to create_time + // for Signals created by Stackdriver Alerting. + google.protobuf.Timestamp detect_time = 15; + + // Output only. The user that created this signal for manually created + // signals. Empty if this signal was generated by a system (for example, + // Stackdriver Alerting). + User creator = 5; + + // One-line summary of the signal. + // Immutable. + string title = 6; + + // Content type string, for example, 'text/plain' or'text/html'. + string content_type = 7; + + // Full message of the signal. + // Immutable for Signals created by Stackdriver Alerting. + string content = 8; + + // The state of this signal. + // For Signals created by Stackdriver Alerting this field is output only. + State signal_state = 9; + + // A set of artifacts to additional resources for this Signal. For example, a + // link to Stackdriver logging for the Signal. + // Immutable for Signals created by Stackdriver Alerting. + repeated SignalArtifact signal_artifacts = 16; +} + +// A text annotation by a user. +message Annotation { + // Resource name of the annotation, for example, + // "projects/{project_id}/incidents/{incident_id}/annotations/{annotation_id}". + string name = 1; + + // Output only. Author of the annotation. + User author = 2; + + // Output only. Time the annotation was created. + google.protobuf.Timestamp create_time = 3; + + // Content of the annotation. Immutable. + string content = 4; +} + +// A tag by a user. +message Tag { + // Resource name of a tag, for example, + // "projects/{project_id}/incidents/{incident_id}/tags/{tag_id}" + string name = 1; + + // Display name of the resource (for example, "cause:rollout"). Immutable. + string display_name = 2; +} + +// Synopsis is a summary of an incident and it contains a textual content, +// an author and a last updated timestamp. +message Synopsis { + // Content type string, for example, 'text/plain' or 'text/html'. + string content_type = 1; + + // Textual content of the synopsis. It can be plain text or markdown as + // indicated by the content_type. + string content = 2; + + // Last updated timestamp. + google.protobuf.Timestamp update_time = 3; + + // Author of the synopsis. + User author = 4; +} + +// Representation of an incident. +message Incident { + // CommunicationVenue is a record of where conversations about an incident + // are happening. + message CommunicationVenue { + // The type of channel/venue for incident communications. + enum ChannelType { + // An unspecified communication channel. + CHANNEL_TYPE_UNSPECIFIED = 0; + + // A communication channel that is represented by a generic URI. + CHANNEL_TYPE_URI = 1; + + // A communication channel that represents a Slack channel. + CHANNEL_TYPE_SLACK = 5; + } + + // A URI to the web interface of the channel. + string uri = 1; + + // A name representing the channel in IRM UI. + string display_name = 2; + + // The type of channel/venue for incident communications. + ChannelType channel_type = 3; + } + + // Specifies the escalation level of this incident, within the IRM protocol + // for handling incidents. + enum EscalationLevel { + // The incident has not been escalated. This is the value used by all new + // and legacy incidents. + ESCALATION_LEVEL_UNSPECIFIED = 0; + + // The incident has been escalated to the organizational level. + ESCALATION_LEVEL_ORGANIZATION = 1; + } + + // Severity of an incident. + enum Severity { + // Severity is not specified. + SEVERITY_UNSPECIFIED = 0; + + // Huge incident. + SEVERITY_HUGE = 1; + + // Major incident. + SEVERITY_MAJOR = 2; + + // Medium incident. + SEVERITY_MEDIUM = 3; + + // Minor incident. + SEVERITY_MINOR = 4; + + // Negligible incident. + SEVERITY_NEGLIGIBLE = 5; + } + + // Stage of an incident. + enum Stage { + // This is the default value if no stage has been specified. + // Note: The caller of the API should set the stage to DETECTED. + STAGE_UNSPECIFIED = 0; + + // The incident has been detected. This is the initial stage of a new + // incident. + // Note: The caller still has to set the stage manually. + STAGE_DETECTED = 4; + + // This incident has been formally characterized. + STAGE_TRIAGED = 1; + + // This incident has been mitigated, i.e. does not affect the service level + // anymore. + STAGE_MITIGATED = 2; + + // This incident has been fully resolved, i.e. there are no immediate + // follow-up tasks. + STAGE_RESOLVED = 3; + + // Postmortem for the incident was written. + STAGE_DOCUMENTED = 5; + + // Stage for an incident with `duplicate_incident`. This incident is not + // authoritative anymore and the `duplicate_incident` should be used to + // determine the stage. + STAGE_DUPLICATE = 6; + } + + // Output only. Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string name = 1; + + // One-line summary of the incident. + string title = 2; + + // Escalation level of the incident. + EscalationLevel escalation_level = 3; + + // Etag to validate the object is unchanged for a read-modify-write operation. + // An empty etag will overwrite other changes. + string etag = 4; + + // Severity of the incident. + Severity severity = 5; + + // Stage of the incident. + Stage stage = 6; + + // Resource name of the incident this incident is a duplicate of. Empty if + // this incident is not a duplicate. + // An incident can only be a duplicate of an incident that is not marked as a + // duplicate already. Setting this to a non-empty value must also set the + // stage to `STAGE_DUPLICATE`. Unsetting this value value must also update + // `stage` to a value other than `STAGE_DUPLICATE`. + string duplicate_incident = 9; + + // Output only. Time this incident started. Used to measure the 'elapsed + // time'. Start time of an incident is the earliest creation time of any of + // its Signals or the create time of the incident if no Signals are assigned. + google.protobuf.Timestamp start_time = 7; + + // Output only. Synopsis of this incident. + Synopsis synopsis = 8; + + // Location of communications for this incident. This is informational + // only; IRM does not use this to send messages. + CommunicationVenue communication_venue = 10; +} + +// Describes a role that can be assigned to an incident. +message IncidentRole { + // List of possible roles. + enum Type { + // The role is unspecified. + TYPE_UNSPECIFIED = 0; + + // Incident Commander: Manages response plan, near-term and long-term + // objectives, establishes priorities, and delegates tasks as needed. + TYPE_INCIDENT_COMMANDER = 1; + + // Communications Lead: Keeps everybody outside and within the response team + // informed. + TYPE_COMMUNICATIONS_LEAD = 2; + + // Operations Lead: Figures out what to do, and gets it done. + TYPE_OPERATIONS_LEAD = 3; + + // External Customer Communications Lead: Responsible for communicating + // incident details to customers/public. + TYPE_EXTERNAL_CUSTOMER_COMMUNICATIONS_LEAD = 4; + + // Primary Oncall: Responds to the initial page and handles all + // responsibilities for pre-escalated incidents. + TYPE_PRIMARY_ONCALL = 5; + + // Secondary Oncall: Helps the primary oncall if necessary; mostly useful + // for pre-escalated incidents. + TYPE_SECONDARY_ONCALL = 6; + + // User-specified roles. One example is a Planning Lead, who keeps track of + // the incident. Another is an assistant Incident Commander. + TYPE_OTHER = 7; + } + + // The type of role. The role type is immutable in role assignments. Each role + // type can only be used once per incident, except for TYPE_OTHER. + Type type = 1; + + // Output only unless TYPE_OTHER is used. Title of the role. For TYPE_OTHER, + // must be unique within an incident. + string title = 2; + + // Output only unless TYPE_OTHER is used. Description of the role. + string description = 3; +} + +// Stores the assignee of a role as well as the proposed next assignee. +message IncidentRoleAssignment { + // Output only. Resource name such as + // "projects/{project_id}/incidents/{incident_id}/role_assignments/{role_id}". + string name = 1; + + // Output only. Etag for this version of the resource. Must be specified in + // update requests and match the current version in storage. Must not be + // modified by the client. + string etag = 2; + + // The role that is or will be assigned. + IncidentRole role = 3; + + // The user this role is assigned to. This field can only be directly set + // during creation request. Subsequent updates are done via the + // IncidentRoleHandover methods. + User assignee = 4; + + // The recipient of a requested role handoff. This field can only be directly + // set during creation request. Subsequent updates are done via the + // IncidentRoleHandover methods. + // + // `assignee` is always the current role-holder, and `proposed_assignee` is + // used to track unfinished assignments and handoffs. Let's say Bob assigns + // Alice to a role. Then the fields are: + // `assignee`: nil, `proposed_assignee`: Alice + // If Alice accepts, then the fields are: + // `assignee`: Alice, `proposed_assignee`: nil + // If she cancels, then the RoleAssignment is deleted. + // Let's say Alice has the role. Then the fields are: + // `assignee`: Alice, `proposed_assignee`: nil + // If Alice becomes incapacitated and Bob requests Carol to take over, then + // the fields are: + // `assignee`: Alice, `proposed_assignee`: Carol + // After Carol accepts the handover, the fields are: + // `assignee`: Carol, `proposed_assignee`: nil + // Or if Carol refuses the handover, the fields are: + // `assignee`: Alice, `proposed_assignee`: nil + User proposed_assignee = 5; +} + +// External artifact associated to an incident. +message Artifact { + // Possible types of an artifact. + enum Type { + // External type is unspecified. + TYPE_UNSPECIFIED = 0; + + // URL. + TYPE_URL = 1; + + // A JIRA issue. + TYPE_JIRA_ISSUE = 4; + } + + // Output only. Resource name such as + // "projects/{project_id}/incidents/{incident_id}/artifacts/{artifact_id}". + string name = 1; + + // User provided name of an artifact. + string display_name = 2; + + // Output only. Etag for this version of the resource. Must be specified in + // update requests and match the current version in storage. Must not be + // modified by the client. + string etag = 3; + + // URL to access the artifact. + string url = 4; + + // Type of this artifact. + Type type = 5; +} + +// Communication Channels are mechanisms used to receive notifications +// about changes to incidents. +message CommunicationChannel { + // A communication channel that delivers messages to an email address. + message Email { + // The email address, for example, "user@example.com". + string address = 1; + } + + // A communication channel that delivers messages to a Stackdriver + // notification channel. + message NotificationChannel { + // Stackdriver notification channel name. + string name = 1; + } + + // An endpoint describes how messages will be delivered. + oneof endpoint { + // Messages will be delivered via email. + Email email = 1; + + // Messages will be delivered via a Stackdriver notification channel. + NotificationChannel notification_channel = 2; + } +} + +// A subscription allows users to get notifications about changes to +// an incident. +message Subscription { + // Types of changes that users can subscribe to in an incident. + enum EventType { + // An event_type that's not specified is an error. + EVENT_TYPE_UNSPECIFIED = 0; + + // The incident's title has changed. + EVENT_TYPE_TITLE_CHANGE = 1; + + // The incident's synopsis has changed. + EVENT_TYPE_SYNOPSIS_CHANGE = 2; + + // The incident's stage has changed. + EVENT_TYPE_STAGE_CHANGE = 3; + + // The incident's severity has changed. + EVENT_TYPE_SEVERITY_CHANGE = 4; + + // A new annotation has been added to the incident. + EVENT_TYPE_ANNOTATION_ADD = 5; + + // An annotation has been modified. + EVENT_TYPE_ANNOTATION_CHANGE = 6; + } + + // Output only. Resource name such as + // "projects/{project_id}/incidents/{incident_id}/subscriptions/{subscription_id}". + string name = 1; + + // Output only. Etag for this version of the resource. Must be specified in + // update requests and match the current version in storage. Must not be + // modified by the client. + string etag = 2; + + // A communications channel to send subscription messages to. + CommunicationChannel subscription_channel = 3; + + // Types of events this subscription receives notifications for. + repeated EventType event_types = 4; +} diff --git a/google/cloud/irm/v1alpha2/incidents_service.proto b/google/cloud/irm/v1alpha2/incidents_service.proto new file mode 100644 index 000000000..e6cf44078 --- /dev/null +++ b/google/cloud/irm/v1alpha2/incidents_service.proto @@ -0,0 +1,832 @@ +// Copyright 2018 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.irm.v1alpha2; + +import "google/api/annotations.proto"; +import "google/cloud/irm/v1alpha2/incidents.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/irm/v1alpha2;irm"; +option java_multiple_files = true; +option java_package = "com.google.irm.service.v1alpha2.api"; + +// The Incident API for Incident Response & Management. +service IncidentService { + // Creates a new incident. + rpc CreateIncident(CreateIncidentRequest) returns (Incident) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*}/incidents" + body: "incident" + }; + } + + // Returns an incident by name. + rpc GetIncident(GetIncidentRequest) returns (Incident) { + option (google.api.http) = { + get: "/v1alpha2/{name=projects/*/incidents/*}" + }; + } + + // Returns a list of incidents. + // Incidents are ordered by start time, with the most recent incidents first. + rpc SearchIncidents(SearchIncidentsRequest) + returns (SearchIncidentsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{parent=projects/*}/incidents:search" + }; + } + + // Updates an existing incident. + rpc UpdateIncident(UpdateIncidentRequest) returns (Incident) { + option (google.api.http) = { + patch: "/v1alpha2/{incident.name=projects/*/incidents/*}" + body: "incident" + }; + } + + // Returns a list of incidents that are "similar" to the specified incident + // or signal. This functionality is provided on a best-effort basis and the + // definition of "similar" is subject to change. + rpc SearchSimilarIncidents(SearchSimilarIncidentsRequest) + returns (SearchSimilarIncidentsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{name=projects/*/incidents/*}:searchSimilar" + additional_bindings { + get: "/v1alpha2/{name=projects/*/signals/*}:searchSimilarIncidents" + } + }; + } + + // Creates an annotation on an existing incident. Only 'text/plain' and + // 'text/markdown' annotations can be created via this method. + rpc CreateAnnotation(CreateAnnotationRequest) returns (Annotation) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*/incidents/*}/annotations" + body: "annotation" + }; + } + + // Lists annotations that are part of an incident. No assumptions should be + // made on the content-type of the annotation returned. + rpc ListAnnotations(ListAnnotationsRequest) + returns (ListAnnotationsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{parent=projects/*/incidents/*}/annotations" + }; + } + + // Creates a tag on an existing incident. + rpc CreateTag(CreateTagRequest) returns (Tag) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*/incidents/*}/tags" + body: "tag" + }; + } + + // Deletes an existing tag. + rpc DeleteTag(DeleteTagRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1alpha2/{name=projects/*/incidents/*/tags/*}" + }; + } + + // Lists tags that are part of an incident. + rpc ListTags(ListTagsRequest) returns (ListTagsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{parent=projects/*/incidents/*}/tags" + }; + } + + // Creates a new signal. + rpc CreateSignal(CreateSignalRequest) returns (Signal) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*}/signals" + body: "signal" + }; + } + + // Lists signals that are part of an incident. + // Signals are returned in reverse chronological order. + rpc SearchSignals(SearchSignalsRequest) returns (SearchSignalsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{parent=projects/*}/signals:search" + }; + } + + // Returns a signal by name. + rpc GetSignal(GetSignalRequest) returns (Signal) { + option (google.api.http) = { + get: "/v1alpha2/{name=projects/*/signals/*}" + }; + } + + // Updates an existing signal (for example, to assign/unassign it to an + // incident). + rpc UpdateSignal(UpdateSignalRequest) returns (Signal) { + option (google.api.http) = { + patch: "/v1alpha2/{signal.name=projects/*/signals/*}" + body: "signal" + }; + } + + // Escalates an incident. + rpc EscalateIncident(EscalateIncidentRequest) + returns (EscalateIncidentResponse) { + option (google.api.http) = { + post: "/v1alpha2/{incident.name=projects/*/incidents/*}:escalate" + body: "*" + }; + } + + // Creates a new artifact. + rpc CreateArtifact(CreateArtifactRequest) returns (Artifact) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*/incidents/*}/artifacts" + body: "artifact" + }; + } + + // Returns a list of artifacts for an incident. + rpc ListArtifacts(ListArtifactsRequest) returns (ListArtifactsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{parent=projects/*/incidents/*}/artifacts" + }; + } + + // Updates an existing artifact. + rpc UpdateArtifact(UpdateArtifactRequest) returns (Artifact) { + option (google.api.http) = { + patch: "/v1alpha2/{artifact.name=projects/*/incidents/*/artifacts/*}" + body: "artifact" + }; + } + + // Deletes an existing artifact. + rpc DeleteArtifact(DeleteArtifactRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1alpha2/{name=projects/*/incidents/*/artifacts/*}" + }; + } + + // Sends a summary of the shift for oncall handoff. + rpc SendShiftHandoff(SendShiftHandoffRequest) + returns (SendShiftHandoffResponse) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*}/shiftHandoff:send" + body: "*" + }; + } + + // Creates a new subscription. + // This will fail if: + // a. there are too many (50) subscriptions in the incident already + // b. a subscription using the given channel already exists + rpc CreateSubscription(CreateSubscriptionRequest) returns (Subscription) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*/incidents/*}/subscriptions" + body: "subscription" + }; + } + + // Updates a subscription. + rpc UpdateSubscription(UpdateSubscriptionRequest) returns (Subscription) { + option (google.api.http) = { + patch: "/v1alpha2/{subscription.name=projects/*/incidents/*/subscriptions/*}" + body: "subscription" + }; + } + + // Returns a list of subscriptions for an incident. + rpc ListSubscriptions(ListSubscriptionsRequest) + returns (ListSubscriptionsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{parent=projects/*/incidents/*}/subscriptions" + }; + } + + // Deletes an existing subscription. + rpc DeleteSubscription(DeleteSubscriptionRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1alpha2/{name=projects/*/incidents/*/subscriptions/*}" + }; + } + + // Creates a role assignment on an existing incident. Normally, the user field + // will be set when assigning a role to oneself, and the next field will be + // set when proposing another user as the assignee. Setting the next field + // directly to a user other than oneself is equivalent to proposing and + // force-assigning the role to the user. + rpc CreateIncidentRoleAssignment(CreateIncidentRoleAssignmentRequest) + returns (IncidentRoleAssignment) { + option (google.api.http) = { + post: "/v1alpha2/{parent=projects/*/incidents/*}/roleAssignments" + body: "*" + }; + } + + // Deletes an existing role assignment. + rpc DeleteIncidentRoleAssignment(DeleteIncidentRoleAssignmentRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1alpha2/{name=projects/*/incidents/*/roleAssignments/*}" + }; + } + + // Lists role assignments that are part of an incident. + rpc ListIncidentRoleAssignments(ListIncidentRoleAssignmentsRequest) + returns (ListIncidentRoleAssignmentsResponse) { + option (google.api.http) = { + get: "/v1alpha2/{parent=projects/*/incidents/*}/roleAssignments" + }; + } + + // Starts a role handover. The proposed assignee will receive an email + // notifying them of the assignment. This will fail if a role handover is + // already pending. + rpc RequestIncidentRoleHandover(RequestIncidentRoleHandoverRequest) + returns (IncidentRoleAssignment) { + option (google.api.http) = { + post: "/v1alpha2/{name=projects/*/incidents/*/roleAssignments/*}:requestHandover" + body: "*" + }; + } + + // Confirms a role handover. This will fail if the 'proposed_assignee' field + // of the IncidentRoleAssignment is not equal to the 'new_assignee' field of + // the request. If the caller is not the new_assignee, + // ForceIncidentRoleHandover should be used instead. + rpc ConfirmIncidentRoleHandover(ConfirmIncidentRoleHandoverRequest) + returns (IncidentRoleAssignment) { + option (google.api.http) = { + post: "/v1alpha2/{name=projects/*/incidents/*/roleAssignments/*}:confirmHandover" + body: "*" + }; + } + + // Forces a role handover. This will fail if the 'proposed_assignee' field of + // the IncidentRoleAssignment is not equal to the 'new_assignee' field of the + // request. If the caller is the new_assignee, ConfirmIncidentRoleHandover + // should be used instead. + rpc ForceIncidentRoleHandover(ForceIncidentRoleHandoverRequest) + returns (IncidentRoleAssignment) { + option (google.api.http) = { + post: "/v1alpha2/{name=projects/*/incidents/*/roleAssignments/*}:forceHandover" + body: "*" + }; + } + + // Cancels a role handover. This will fail if the 'proposed_assignee' field of + // the IncidentRoleAssignment is not equal to the 'new_assignee' field of the + // request. + rpc CancelIncidentRoleHandover(CancelIncidentRoleHandoverRequest) + returns (IncidentRoleAssignment) { + option (google.api.http) = { + post: "/v1alpha2/{name=projects/*/incidents/*/roleAssignments/*}:cancelHandover" + body: "*" + }; + } +} + +// Request for the CreateIncident method. +message CreateIncidentRequest { + // The incident to create. + Incident incident = 1; + + // The resource name of the hosting Stackdriver project which the incident + // belongs to. + // The name is of the form `projects/{project_id_or_number}` + // . + string parent = 2; +} + +// Request for the GetIncident method. +message GetIncidentRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string name = 1; +} + +// Request for the UpdateIncident method. +message UpdateIncidentRequest { + // The incident to update with the new values. + Incident incident = 1; + + // List of fields that should be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request for the SearchSimilarIncidents method. +message SearchSimilarIncidentsRequest { + // Resource name of the incident or signal, for example, + // "projects/{project_id}/incidents/{incident_id}". + string name = 1; + + // Number of similar incidents to return. + int32 page_size = 2; + + // Page token from an earlier query, as returned in 'next_page_token'. + string page_token = 3; +} + +// Response for the SearchSimilarIncidents method. +message SearchSimilarIncidentsResponse { + // A single search result, i.e. an incident with (potentially) additional + // information. + message Result { + // An incident that is "similar" to the incident or signal specified in the + // request. + Incident incident = 1; + } + + // The search results, ordered by descending relevance. + repeated Result results = 1; + + // Page token to fetch the next set of similar incidents. + string next_page_token = 2; +} + +// Request for the CreateAnnotation method. +message CreateAnnotationRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Only annotation.content is an input argument. + Annotation annotation = 2; +} + +// Request for the ListAnnotations method. +message ListAnnotationsRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Number of annotations to return. + int32 page_size = 2; + + // Page token from an earlier query, as returned in `next_page_token`. + string page_token = 3; +} + +// Response for the ListAnnotations method. +message ListAnnotationsResponse { + // List of annotations. + repeated Annotation annotations = 1; + + // Page token to fetch the next set of annotations. + string next_page_token = 2; +} + +// Request for the CreateTag method. +message CreateTagRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Tag to create. Only tag.display_name is an input argument. + Tag tag = 2; +} + +// Request for the DeleteTag method. +message DeleteTagRequest { + // Resource name of the tag. + string name = 1; +} + +// Request for the ListTagsForIncident method. +message ListTagsRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Number of tags to return. + int32 page_size = 2; + + // Page token from an earlier query, as returned in `next_page_token`. + string page_token = 3; +} + +// Response for the ListTagsForIncident method. +message ListTagsResponse { + // Tags. + repeated Tag tags = 1; + + // Page token to fetch the next set of tags. + string next_page_token = 2; +} + +// Request for the CreateSignal method. +message CreateSignalRequest { + // The resource name of the hosting Stackdriver project which requested + // signal belongs to. + string parent = 1; + + // The signal to create. + Signal signal = 2; +} + +// Request for the SearchSignals method. +message SearchSignalsRequest { + // The resource name of the hosting Stackdriver project which requested + // incidents belong to. + string parent = 1; + + // Query to specify which signals should be returned. + string query = 2; + + // Maximum number of `signals` to return in the response. + int32 page_size = 3; + + // Page token from an earlier query, as returned in `next_page_token`. All + // field values except for page_size and page_token should be the same as the + // original query (may return an error or unexpected data otherwise). + string page_token = 4; +} + +// Response for the SearchSignals method. +message SearchSignalsResponse { + // Signals that matched the query in the request. + repeated Signal signals = 1; + + // Page token to fetch the next set of signals. + string next_page_token = 2; +} + +// Request for the GetSignal method. +message GetSignalRequest { + // Resource name of the Signal resource, for example, + // "projects/{project_id}/signals/{signal_id}". + string name = 1; +} + +// Request for the UpdateSignal method. +message UpdateSignalRequest { + // The signal to update with the new values. + Signal signal = 1; + + // List of fields that should be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request for the SearchIncidents method. +message SearchIncidentsRequest { + // The resource name of the hosting Stackdriver project which requested + // incidents belong to. + string parent = 1; + + // An expression that defines which incidents to return. + // + // Search atoms can be used to match certain specific fields. Otherwise, + // plain text will match text fields in the incident. + // + // Search atoms: + // * `start` - (timestamp) The time the incident started. + // * `stage` - The stage of the incident, one of detected, triaged, mitigated, + // resolved, documented, or duplicate (which correspond to values in the + // Incident.Stage enum). These are ordered, so `stage<resolved` is + // equivalent to `stage:detected OR stage:triaged OR stage:mitigated`. + // * `severity` - (Incident.Severity) The severity of the incident. + // + Supports matching on a specific severity (for example, + // `severity:major`) or on a range (for example, `severity>medium`, + // `severity<=minor`, etc.). + // + // Timestamp formats: + // * yyyy-MM-dd - an absolute date, treated as a calendar-day-wide window. + // In other words, the "<" operator will match dates before that date, the + // ">" operator will match dates after that date, and the ":" or "=" + // operators will match the entire day. + // * Nd (for example, 7d) - a relative number of days ago, treated as a moment + // in time (as opposed to a day-wide span). A multiple of 24 hours ago (as + // opposed to calendar days). In the case of daylight savings time, it will + // apply the current timezone to both ends of the range. Note that exact + // matching (for example, `start:7d`) is unlikely to be useful because that + // would only match incidents created precisely at a particular instant in + // time. + // + // Examples: + // + // * `foo` - matches incidents containing the word "foo" + // * `"foo bar"` - matches incidents containing the phrase "foo bar" + // * `foo bar` or `foo AND bar` - matches incidents containing the words "foo" + // and "bar" + // * `foo -bar` or `foo AND NOT bar` - matches incidents containing the word + // "foo" but not the word "bar" + // * `foo OR bar` - matches incidents containing the word "foo" or the word + // "bar" + // * `start>2018-11-28` - matches incidents which started after November 11, + // 2018. + // * `start<=2018-11-28` - matches incidents which started on or before + // November 11, 2018. + // * `start:2018-11-28` - matches incidents which started on November 11, + // 2018. + // * `start>7d` - matches incidents which started after the point in time 7*24 + // hours ago + // * `start>180d` - similar to 7d, but likely to cross the daylight savings + // time boundary, so the end time will be 1 hour different from "now." + // * `foo AND start>90d AND stage<resolved` - unresolved incidents from the + // past 90 days containing the word "foo" + string query = 2; + + // Number of incidents to return. + int32 page_size = 3; + + // Page token from an earlier query, as returned in `next_page_token`. + string page_token = 4; + + // The time zone name. It should be an IANA TZ name, such as + // "America/Los_Angeles". For more information, + // see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. + // If no time zone is specified, the default is UTC. + string time_zone = 5; +} + +// Response for the SearchIncidents method. +message SearchIncidentsResponse { + // Incidents. + repeated Incident incidents = 1; + + // Page token to fetch the next set of incidents. + string next_page_token = 2; +} + +// Request to escalate an incident. +message EscalateIncidentRequest { + // The incident to escalate with the new values. + Incident incident = 1; + + // List of fields that should be updated. + google.protobuf.FieldMask update_mask = 2; + + // Subscriptions to add or update. Existing subscriptions with the same + // channel and address as a subscription in the list will be updated. + repeated Subscription subscriptions = 3; + + // Tags to add. Tags identical to existing tags will be ignored. + repeated Tag tags = 4; + + // Roles to add or update. Existing roles with the same type (and title, for + // TYPE_OTHER roles) will be updated. + repeated IncidentRoleAssignment roles = 5; + + // Artifacts to add. All artifacts are added without checking for duplicates. + repeated Artifact artifacts = 6; +} + +// Response for EscalateIncident. +message EscalateIncidentResponse { + // The escalated incident. + Incident incident = 1; + + // New or modified subscriptions. + repeated Subscription subscriptions = 2; + + // New or modified tags. + repeated Tag tags = 3; + + // New or modified roles. + repeated IncidentRole roles = 4; + + // New or modified artifacts. + repeated Artifact artifacts = 5; +} + +// Request for the CreateArtifact method. +message CreateArtifactRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // The artifact to create. + Artifact artifact = 2; +} + +// Request for the ListArtifacts method. +message ListArtifactsRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Number of artifacts to return. + int32 page_size = 2; + + // Page token from an earlier query, as returned in `next_page_token`. + string page_token = 3; +} + +// Response for the ListArtifacts method. +message ListArtifactsResponse { + // List of artifacts. + repeated Artifact artifacts = 1; + + // Page token to fetch the next set of artifacts. + string next_page_token = 2; +} + +// Request for the UpdateArtifact method. +message UpdateArtifactRequest { + // The artifact to update with the new values. + Artifact artifact = 1; + + // List of fields that should be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request for deleting an artifact. +message DeleteArtifactRequest { + // Resource name of the artifact. + string name = 1; +} + +// SendShiftHandoff and PreviewShiftHandoff RPC request. +message SendShiftHandoffRequest { + // Describes an incident for inclusion in the handoff. + // This is wrapped in a message to provide flexibility for potentially + // attaching additional data to each incident in the future. + message Incident { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string name = 1; + } + + // The resource name of the Stackdriver project that the handoff is being sent + // from. for example, `projects/{project_id}` + string parent = 1; + + // Email addresses of the recipients of the handoff, for example, + // "user@example.com". Must contain at least one entry. + repeated string recipients = 2; + + // Email addresses that should be CC'd on the handoff. Optional. + repeated string cc = 3; + + // The subject of the email. Required. + string subject = 4; + + // Content type string, for example, 'text/plain' or 'text/html'. + string notes_content_type = 5; + + // Additional notes to be included in the handoff. Optional. + string notes_content = 6; + + // The set of incidents that should be included in the handoff. Optional. + repeated Incident incidents = 7; + + // If set to true a ShiftHandoffResponse will be returned but the handoff + // will not actually be sent. + bool preview_only = 8; +} + +// SendShiftHandoff and PreviewShiftHandoff RPC response. +message SendShiftHandoffResponse { + // Content type string, for example, 'text/plain' or 'text/html'. + string content_type = 1; + + // The contents of the handoff that was sent or would have been sent (if the + // request was preview_only). + // This will typically contain a full HTML document. + string content = 2; +} + +// Request for the CreateSubscription method. +message CreateSubscriptionRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // The subscription to create. + Subscription subscription = 2; +} + +// Request for the UpdateSubscription method. +message UpdateSubscriptionRequest { + // The subscription to update, with new values. + Subscription subscription = 1; + + // List of fields that should be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request for the ListSubscriptions method. +message ListSubscriptionsRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Number of subscriptions to return. + int32 page_size = 2; + + // Page token from an earlier query, as returned in `next_page_token`. + string page_token = 3; +} + +// Response for the ListSubscriptions method. +message ListSubscriptionsResponse { + // List of subscriptions. + repeated Subscription subscriptions = 1; + + // Page token to fetch the next set of subscriptions. + string next_page_token = 2; +} + +// Request for deleting a subscription. +message DeleteSubscriptionRequest { + // Resource name of the subscription. + string name = 1; +} + +// Request for creating a role assignment. +message CreateIncidentRoleAssignmentRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Role assignment to create. + IncidentRoleAssignment incident_role_assignment = 2; +} + +// Request for deleting a role assignment. +message DeleteIncidentRoleAssignmentRequest { + // Resource name of the role assignment. + string name = 1; +} + +// Request to list role assignments of an incident. +message ListIncidentRoleAssignmentsRequest { + // Resource name of the incident, for example, + // "projects/{project_id}/incidents/{incident_id}". + string parent = 1; + + // Number of assignments to return. + int32 page_size = 2; + + // Page token from an earlier query, as returned in `next_page_token`. + string page_token = 3; +} + +// Response for the ListIncidentRoleAssignments method. +message ListIncidentRoleAssignmentsResponse { + // List of assignments. + repeated IncidentRoleAssignment incident_role_assignments = 1; + + // Page token to fetch the next set of assignments. + string next_page_token = 2; +} + +// Request to start a role handover. +message RequestIncidentRoleHandoverRequest { + // Resource name of the role assignment. + string name = 1; + + // The proposed assignee. + User new_assignee = 2; +} + +// Request to confirm a role handover. +message ConfirmIncidentRoleHandoverRequest { + // Resource name of the role assignment. + string name = 1; + + // The proposed assignee, who will now be the assignee. This should be the + // current user; otherwise ForceRoleHandover should be called. + User new_assignee = 2; +} + +// Request to force a role handover. +message ForceIncidentRoleHandoverRequest { + // Resource name of the role assignment. + string name = 1; + + // The proposed assignee, who will now be the assignee. This should not be + // the current user; otherwise ConfirmRoleHandover should be called. + User new_assignee = 2; +} + +// Request to cancel a role handover. +message CancelIncidentRoleHandoverRequest { + // Resource name of the role assignment. + string name = 1; + + // Person who was proposed as the next assignee (i.e. + // IncidentRoleAssignment.proposed_assignee) and whose proposal is being + // cancelled. + User new_assignee = 2; +} diff --git a/google/cloud/irm/v1alpha2/irm_gapic.yaml b/google/cloud/irm/v1alpha2/irm_gapic.yaml new file mode 100644 index 000000000..b96625dc2 --- /dev/null +++ b/google/cloud/irm/v1alpha2/irm_gapic.yaml @@ -0,0 +1,719 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.irm.v1alpha2 + python: + package_name: google.cloud.irm_v1alpha2.gapic + go: + package_name: cloud.google.com/go/irm/apiv1alpha2 + csharp: + package_name: Google.Cloud.Irm.V1Alpha2 + ruby: + package_name: Google::Cloud::Irm::V1alpha2 + php: + package_name: Google\Cloud\Irm\V1alpha2 + nodejs: + package_name: irm.v1alpha2 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.irm.v1alpha2.IncidentService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/incidents/{incident} + entity_name: incident + - name_pattern: projects/{project}/incidents/{incident}/annotations/{annotation} + entity_name: annotation + - name_pattern: projects/{project}/incidents/{incident}/artifacts/{artifact} + entity_name: artifact + - name_pattern: projects/{project}/incidents/{incident}/roleAssignments/{role_assignment} + entity_name: role_assignment + - name_pattern: projects/{project}/incidents/{incident}/subscriptions/{subscription} + entity_name: subscription + - name_pattern: projects/{project}/incidents/{incident}/tags/{tag} + entity_name: tag + - name_pattern: projects/{project}/signals/{signal} + entity_name: signal + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateIncident + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - incident + - parent + required_fields: + - incident + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + - name: GetIncident + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: incident + timeout_millis: 60000 + - name: SearchIncidents + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - query + - time_zone + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: incidents + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + - name: UpdateIncident + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - incident + - update_mask + required_fields: + - incident + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + incident.name: incident + timeout_millis: 60000 + - name: SearchSimilarIncidents + flattening: + groups: + - parameters: + - name + required_fields: + - name + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: results + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: incident + timeout_millis: 60000 + - name: CreateAnnotation + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - annotation + required_fields: + - parent + - annotation + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: ListAnnotations + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: annotations + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: CreateTag + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - tag + required_fields: + - parent + - tag + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: DeleteTag + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: tag + timeout_millis: 60000 + - name: ListTags + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: tags + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: CreateSignal + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - signal + required_fields: + - parent + - signal + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + - name: SearchSignals + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - query + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: signals + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + - name: GetSignal + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: signal + timeout_millis: 60000 + - name: UpdateSignal + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - signal + - update_mask + required_fields: + - signal + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + signal.name: signal + timeout_millis: 60000 + - name: EscalateIncident + resource_name_treatment: STATIC_TYPES + required_fields: + - incident + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + incident.name: incident + timeout_millis: 60000 + - name: CreateArtifact + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - artifact + required_fields: + - parent + - artifact + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: ListArtifacts + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: artifacts + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: UpdateArtifact + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - artifact + - update_mask + required_fields: + - artifact + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + artifact.name: artifact + timeout_millis: 60000 + - name: DeleteArtifact + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: artifact + timeout_millis: 60000 + - name: SendShiftHandoff + resource_name_treatment: STATIC_TYPES + required_fields: + - parent + - recipients + - subject + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + - name: CreateSubscription + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - subscription + required_fields: + - parent + - subscription + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: UpdateSubscription + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - subscription + - update_mask + required_fields: + - subscription + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + subscription.name: subscription + timeout_millis: 60000 + - name: ListSubscriptions + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: subscriptions + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: DeleteSubscription + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: subscription + timeout_millis: 60000 + - name: CreateIncidentRoleAssignment + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - incident_role_assignment + required_fields: + - parent + - incident_role_assignment + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: DeleteIncidentRoleAssignment + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: role_assignment + timeout_millis: 60000 + - name: ListIncidentRoleAssignments + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: incident_role_assignments + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: incident + timeout_millis: 60000 + - name: RequestIncidentRoleHandover + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + - new_assignee + required_fields: + - name + - new_assignee + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: role_assignment + timeout_millis: 60000 + - name: ConfirmIncidentRoleHandover + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + - new_assignee + required_fields: + - name + - new_assignee + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: role_assignment + timeout_millis: 60000 + - name: ForceIncidentRoleHandover + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + - new_assignee + required_fields: + - name + - new_assignee + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: role_assignment + timeout_millis: 60000 + - name: CancelIncidentRoleHandover + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + - new_assignee + required_fields: + - name + - new_assignee + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: role_assignment + timeout_millis: 60000 +resource_name_generation: +- message_name: Annotation + field_entity_map: + name: annotation +- message_name: Artifact + field_entity_map: + name: artifact +- message_name: Incident + field_entity_map: + name: incident +- message_name: IncidentRoleAssignment + field_entity_map: + name: role_assignment +- message_name: Signal + field_entity_map: + name: signal +- message_name: Subscription + field_entity_map: + name: subscription +- message_name: Tag + field_entity_map: + name: tag +- message_name: CreateIncidentRequest + field_entity_map: + parent: project +- message_name: GetIncidentRequest + field_entity_map: + name: incident +- message_name: SearchIncidentsRequest + field_entity_map: + parent: project +- message_name: UpdateIncidentRequest + field_entity_map: + incident.name: incident +- message_name: EscalateIncidentRequest + field_entity_map: + incident.name: incident +- message_name: CreateSignalRequest + field_entity_map: + parent: project +- message_name: GetSignalRequest + field_entity_map: + name: signal +- message_name: SearchSignalsRequest + field_entity_map: + parent: project +- message_name: UpdateSignalRequest + field_entity_map: + signal.name: signal +- message_name: CreateArtifactRequest + field_entity_map: + parent: incident +- message_name: ListArtifactsRequest + field_entity_map: + parent: incident +- message_name: UpdateArtifactRequest + field_entity_map: + artifact.name: artifact +- message_name: DeleteArtifactRequest + field_entity_map: + name: artifact +- message_name: CreateIncidentRoleAssignmentRequest + field_entity_map: + parent: incident +- message_name: ListIncidentRoleAssignmentsRequest + field_entity_map: + parent: incident +- message_name: DeleteIncidentRoleAssignmentRequest + field_entity_map: + name: role_assignment +- message_name: RequestIncidentRoleHandoverRequest + field_entity_map: + name: role_assignment +- message_name: ConfirmIncidentRoleHandoverRequest + field_entity_map: + name: role_assignment +- message_name: ForceIncidentRoleHandoverRequest + field_entity_map: + name: role_assignment +- message_name: CancelIncidentRoleHandoverRequest + field_entity_map: + name: role_assignment +- message_name: CreateSubscriptionRequest + field_entity_map: + parent: incident +- message_name: ListSubscriptionsRequest + field_entity_map: + parent: incident +- message_name: UpdateSubscriptionRequest + field_entity_map: + subscription.name: subscription +- message_name: DeleteSubscriptionRequest + field_entity_map: + name: subscription +- message_name: CreateTagRequest + field_entity_map: + parent: incident +- message_name: ListTagsRequest + field_entity_map: + parent: incident +- message_name: DeleteTagRequest + field_entity_map: + name: tag +- message_name: CreateAnnotationRequest + field_entity_map: + parent: incident +- message_name: ListAnnotationsRequest + field_entity_map: + parent: incident +- message_name: SendShiftHandoffRequest + field_entity_map: + parent: project diff --git a/google/cloud/kms/BUILD.bazel b/google/cloud/kms/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/kms/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/kms/artman_cloudkms.yaml b/google/cloud/kms/artman_cloudkms.yaml new file mode 100644 index 000000000..4e2192ac1 --- /dev/null +++ b/google/cloud/kms/artman_cloudkms.yaml @@ -0,0 +1,39 @@ +common: + api_name: kms + api_version: v1 + organization_name: google-cloud + service_yaml: cloudkms.yaml + gapic_yaml: v1/cloudkms_gapic.yaml + src_proto_paths: + - v1 + proto_deps: + - name: google-common-protos + - name: google-iam-v1 + proto_path: google/iam/v1 + test_proto_deps: + - name: google-iam-v1 + proto_path: google/iam/v1 +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/kms/cloudkms.yaml b/google/cloud/kms/cloudkms.yaml new file mode 100644 index 000000000..f953630a5 --- /dev/null +++ b/google/cloud/kms/cloudkms.yaml @@ -0,0 +1,44 @@ +type: google.api.Service +config_version: 3 +name: cloudkms.googleapis.com +title: Cloud Key Management Service (KMS) API + +apis: +- name: google.cloud.kms.v1.KeyManagementService + +types: +- name: google.cloud.kms.v1.LocationMetadata + +documentation: + summary: |- + Manages keys and performs cryptographic operations in a central cloud + service, for direct use by other cloud resources and applications. + +http: + rules: + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + post: '/v1/{resource=projects/*/locations/*/keyRings/*}:setIamPolicy' + body: '*' + additional_bindings: + - post: '/v1/{resource=projects/*/locations/*/keyRings/*/cryptoKeys/*}:setIamPolicy' + body: '*' + + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + get: '/v1/{resource=projects/*/locations/*/keyRings/*}:getIamPolicy' + additional_bindings: + - get: '/v1/{resource=projects/*/locations/*/keyRings/*/cryptoKeys/*}:getIamPolicy' + + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + post: '/v1/{resource=projects/*/locations/*/keyRings/*}:testIamPermissions' + body: '*' + additional_bindings: + - post: '/v1/{resource=projects/*/locations/*/keyRings/*/cryptoKeys/*}:testIamPermissions' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/kms/v1/BUILD.bazel b/google/cloud/kms/v1/BUILD.bazel new file mode 100644 index 000000000..30bb57ba0 --- /dev/null +++ b/google/cloud/kms/v1/BUILD.bazel @@ -0,0 +1,156 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "kms_proto", + srcs = [ + "resources.proto", + "service.proto", + ], + deps = [ + "//google/api:annotations_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:struct_proto", + "@com_google_protobuf//:timestamp_proto", + "@com_google_protobuf//:wrappers_proto", + ], +) + +proto_library_with_info( + name = "kms_proto_with_info", + deps = [ + ":kms_proto", + "//google/iam/v1:iam_policy_proto", + "//google/iam/v1:policy_proto", + ], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", + "@com_google_api_grpc_proto_google_iam_v1//jar", +] + +java_proto_library( + name = "kms_java_proto", + deps = [":kms_proto"], +) + +java_grpc_library( + name = "kms_java_grpc", + srcs = [":kms_proto"], + deps = [":kms_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "kms_resource_name_java_proto", + gapic_yaml = "cloudkms_gapic.yaml", + deps = [":kms_proto"], +) + +java_gapic_library( + name = "kms_java_gapic", + src = ":kms_proto_with_info", + gapic_yaml = "cloudkms_gapic.yaml", + service_yaml = "//google/cloud/kms:cloudkms.yaml", + test_deps = [ + ":kms_java_grpc", + "@com_google_api_grpc_grpc_google_iam_v1//jar", + ], + deps = [ + ":kms_java_proto", + ":kms_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":kms_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.kms.v1.KeyManagementServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-kms-v1-java", + client_deps = [":kms_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":kms_java_gapic_test"], + grpc_deps = [":kms_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":kms_java_proto", + ":kms_proto", + ":kms_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "kms_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/kms/v1", + protos = [":kms_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/iam/v1:iam_go_proto", + ], +) + +go_gapic_library( + name = "kms_go_gapic", + src = ":kms_proto_with_info", + gapic_yaml = "cloudkms_gapic.yaml", + importpath = "cloud.google.com/go/kms/apiv1", + service_yaml = "//google/cloud/kms:cloudkms.yaml", + deps = [ + ":kms_go_proto", + "//google/iam/v1:iam_go_proto", + "@io_bazel_rules_go//proto/wkt:duration_go_proto", + ], +) + +go_test( + name = "kms_go_gapic_test", + srcs = [":kms_go_gapic_srcjar_test"], + embed = [":kms_go_gapic"], + importpath = "cloud.google.com/go/kms/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-kms-v1-go", + deps = [ + ":kms_go_gapic", + ":kms_go_gapic_srcjar-smoke-test.srcjar", + ":kms_go_gapic_srcjar-test.srcjar", + ":kms_go_proto", + ], +) diff --git a/google/cloud/kms/v1/cloudkms_gapic.yaml b/google/cloud/kms/v1/cloudkms_gapic.yaml new file mode 100644 index 000000000..808ab973e --- /dev/null +++ b/google/cloud/kms/v1/cloudkms_gapic.yaml @@ -0,0 +1,592 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.kms.v1 + python: + package_name: google.cloud.kms_v1.gapic + go: + package_name: cloud.google.com/go/kms/apiv1 + release_level: GA + csharp: + package_name: Google.Cloud.Kms.V1 + ruby: + package_name: Google::Cloud::Kms::V1 + release_level: GA + php: + package_name: Google\Cloud\Kms\V1 + nodejs: + package_name: kms.v1 + domain_layer_location: google-cloud +collection_oneofs: +- oneof_name: key_oneof + collection_names: + - key_ring + - crypto_key +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.kms.v1.KeyManagementService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location}/keyRings/{key_ring} + entity_name: key_ring + - name_pattern: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key_path=**} + entity_name: crypto_key_path + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key} + entity_name: crypto_key + - name_pattern: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version} + entity_name: crypto_key_version + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListKeyRings + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: key_rings + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ListCryptoKeys + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: crypto_keys + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: key_ring + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: ListCryptoKeyVersions + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: crypto_key_versions + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: crypto_key + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetKeyRing + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: key_ring + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetCryptoKey + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetCryptoKeyVersion + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key_version + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: CreateKeyRing + flattening: + groups: + - parameters: + - parent + - key_ring_id + - key_ring + required_fields: + - parent + - key_ring_id + - key_ring + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: CreateCryptoKey + flattening: + groups: + - parameters: + - parent + - crypto_key_id + - crypto_key + required_fields: + - parent + - crypto_key_id + - crypto_key + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: key_ring + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + sample_code_init_fields: + - crypto_key_id=my-app-key + - crypto_key.purpose=ENCRYPT_DECRYPT + - crypto_key.next_rotation_time.seconds=2147483647 + - crypto_key.rotation_period.seconds=604800 + - name: CreateCryptoKeyVersion + flattening: + groups: + - parameters: + - parent + - crypto_key_version + required_fields: + - parent + - crypto_key_version + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: crypto_key + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UpdateCryptoKey + flattening: + groups: + - parameters: + - crypto_key + - update_mask + required_fields: + - crypto_key + - update_mask + header_request_params: + - crypto_key.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + crypto_key.name: crypto_key + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UpdateCryptoKeyVersion + flattening: + groups: + - parameters: + - crypto_key_version + - update_mask + required_fields: + - crypto_key_version + - update_mask + header_request_params: + - crypto_key_version.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + crypto_key_version.name: crypto_key_version + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: Encrypt + flattening: + groups: + - parameters: + - name + - plaintext + required_fields: + - name + - plaintext + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key_path + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: Decrypt + flattening: + groups: + - parameters: + - name + - ciphertext + required_fields: + - name + - ciphertext + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: UpdateCryptoKeyPrimaryVersion + flattening: + groups: + - parameters: + - name + - crypto_key_version_id + required_fields: + - name + - crypto_key_version_id + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: DestroyCryptoKeyVersion + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key_version + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: RestoreCryptoKeyVersion + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key_version + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: GetPublicKey + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key_version + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: AsymmetricDecrypt + flattening: + groups: + - parameters: + - name + - ciphertext + required_fields: + - name + - ciphertext + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key_version + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: AsymmetricSign + flattening: + groups: + - parameters: + - name + - digest + required_fields: + - name + - digest + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: crypto_key_version + resource_name_treatment: STATIC_TYPES + timeout_millis: 60000 + - name: SetIamPolicy + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + header_request_params: + - resource + field_name_patterns: + resource: key_oneof + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + reroute_to_grpc_interface: google.iam.v1.IAMPolicy + surface_treatments: + - include_languages: + - go + visibility: DISABLED + - name: GetIamPolicy + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + header_request_params: + - resource + field_name_patterns: + resource: key_oneof + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + reroute_to_grpc_interface: google.iam.v1.IAMPolicy + surface_treatments: + - include_languages: + - go + visibility: DISABLED + - name: TestIamPermissions + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + header_request_params: + - resource + field_name_patterns: + resource: key_oneof + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + reroute_to_grpc_interface: google.iam.v1.IAMPolicy + surface_treatments: + - include_languages: + - go + visibility: DISABLED +resource_name_generation: +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: "*" +- message_name: KeyRing + field_entity_map: + name: key_ring +- message_name: CryptoKey #UpdateCryptoKeyRequest + field_entity_map: + name: crypto_key +- message_name: CryptoKeyVersion #UpdateCryptoKeyVersionRequest + field_entity_map: + name: crypto_key_version +- message_name: ListKeyRingsRequest + field_entity_map: + parent: location +- message_name: ListCryptoKeysRequest + field_entity_map: + parent: key_ring +- message_name: ListCryptoKeyVersionsRequest + field_entity_map: + parent: crypto_key +- message_name: GetKeyRingRequest + field_entity_map: + name: key_ring +- message_name: GetCryptoKeyRequest + field_entity_map: + name: crypto_key +- message_name: GetCryptoKeyVersionRequest + field_entity_map: + name: crypto_key_version +- message_name: CreateKeyRingRequest + field_entity_map: + parent: location +- message_name: CreateCryptoKeyRequest + field_entity_map: + parent: key_ring +- message_name: CreateCryptoKeyVersionRequest + field_entity_map: + parent: crypto_key +- message_name: EncryptRequest + field_entity_map: + name: crypto_key_path +- message_name: DecryptRequest + field_entity_map: + name: crypto_key +- message_name: UpdateCryptoKeyPrimaryVersionRequest + field_entity_map: + name: crypto_key +- message_name: DestroyCryptoKeyVersionRequest + field_entity_map: + name: crypto_key_version +- message_name: RestoreCryptoKeyVersionRequest + field_entity_map: + name: crypto_key_version +- message_name: GetPublicKeyRequest + field_entity_map: + name: crypto_key_version +- message_name: AsymmetricSignRequest + field_entity_map: + name: crypto_key_version +- message_name: AsymmetricDecryptRequest + field_entity_map: + name: crypto_key_version diff --git a/google/cloud/kms/v1/resources.proto b/google/cloud/kms/v1/resources.proto new file mode 100644 index 000000000..95dfc91b6 --- /dev/null +++ b/google/cloud/kms/v1/resources.proto @@ -0,0 +1,424 @@ +// Copyright 2018 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.kms.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Kms.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/kms/v1;kms"; +option java_multiple_files = true; +option java_outer_classname = "KmsResourcesProto"; +option java_package = "com.google.cloud.kms.v1"; +option php_namespace = "Google\\Cloud\\Kms\\V1"; + +// A [KeyRing][google.cloud.kms.v1.KeyRing] is a toplevel logical grouping of +// [CryptoKeys][google.cloud.kms.v1.CryptoKey]. +message KeyRing { + // Output only. The resource name for the + // [KeyRing][google.cloud.kms.v1.KeyRing] in the format + // `projects/*/locations/*/keyRings/*`. + string name = 1; + + // Output only. The time at which this [KeyRing][google.cloud.kms.v1.KeyRing] + // was created. + google.protobuf.Timestamp create_time = 2; +} + +// A [CryptoKey][google.cloud.kms.v1.CryptoKey] represents a logical key that +// can be used for cryptographic operations. +// +// A [CryptoKey][google.cloud.kms.v1.CryptoKey] is made up of one or more +// [versions][google.cloud.kms.v1.CryptoKeyVersion], which represent the actual +// key material used in cryptographic operations. +message CryptoKey { + // [CryptoKeyPurpose][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose] + // describes the cryptographic capabilities of a + // [CryptoKey][google.cloud.kms.v1.CryptoKey]. A given key can only be used + // for the operations allowed by its purpose. + enum CryptoKeyPurpose { + // Not specified. + CRYPTO_KEY_PURPOSE_UNSPECIFIED = 0; + + // [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used + // with [Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt] and + // [Decrypt][google.cloud.kms.v1.KeyManagementService.Decrypt]. + ENCRYPT_DECRYPT = 1; + + // [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used + // with + // [AsymmetricSign][google.cloud.kms.v1.KeyManagementService.AsymmetricSign] + // and + // [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey]. + ASYMMETRIC_SIGN = 5; + + // [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used + // with + // [AsymmetricDecrypt][google.cloud.kms.v1.KeyManagementService.AsymmetricDecrypt] + // and + // [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey]. + ASYMMETRIC_DECRYPT = 6; + } + + // Output only. The resource name for this + // [CryptoKey][google.cloud.kms.v1.CryptoKey] in the format + // `projects/*/locations/*/keyRings/*/cryptoKeys/*`. + string name = 1; + + // Output only. A copy of the "primary" + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] that will be used + // by [Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt] when this + // [CryptoKey][google.cloud.kms.v1.CryptoKey] is given in + // [EncryptRequest.name][google.cloud.kms.v1.EncryptRequest.name]. + // + // The [CryptoKey][google.cloud.kms.v1.CryptoKey]'s primary version can be + // updated via + // [UpdateCryptoKeyPrimaryVersion][google.cloud.kms.v1.KeyManagementService.UpdateCryptoKeyPrimaryVersion]. + // + // All keys with [purpose][google.cloud.kms.v1.CryptoKey.purpose] + // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT] + // have a primary. For other keys, this field will be omitted. + CryptoKeyVersion primary = 2; + + // The immutable purpose of this [CryptoKey][google.cloud.kms.v1.CryptoKey]. + CryptoKeyPurpose purpose = 3; + + // Output only. The time at which this + // [CryptoKey][google.cloud.kms.v1.CryptoKey] was created. + google.protobuf.Timestamp create_time = 5; + + // At [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time], + // the Key Management Service will automatically: + // + // 1. Create a new version of this [CryptoKey][google.cloud.kms.v1.CryptoKey]. + // 2. Mark the new version as primary. + // + // Key rotations performed manually via + // [CreateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.CreateCryptoKeyVersion] + // and + // [UpdateCryptoKeyPrimaryVersion][google.cloud.kms.v1.KeyManagementService.UpdateCryptoKeyPrimaryVersion] + // do not affect + // [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time]. + // + // Keys with [purpose][google.cloud.kms.v1.CryptoKey.purpose] + // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT] + // support automatic rotation. For other keys, this field must be omitted. + google.protobuf.Timestamp next_rotation_time = 7; + + // Controls the rate of automatic rotation. + oneof rotation_schedule { + // [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time] + // will be advanced by this period when the service automatically rotates a + // key. Must be at least one day. + // + // If [rotation_period][google.cloud.kms.v1.CryptoKey.rotation_period] is + // set, + // [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time] + // must also be set. + // + // Keys with [purpose][google.cloud.kms.v1.CryptoKey.purpose] + // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT] + // support automatic rotation. For other keys, this field must be omitted. + google.protobuf.Duration rotation_period = 8; + } + + // A template describing settings for new + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] instances. The + // properties of new [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] + // instances created by either + // [CreateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.CreateCryptoKeyVersion] + // or auto-rotation are controlled by this template. + CryptoKeyVersionTemplate version_template = 11; + + // Labels with user-defined metadata. For more information, see + // [Labeling Keys](/kms/docs/labeling-keys). + map<string, string> labels = 10; +} + +// A [CryptoKeyVersionTemplate][google.cloud.kms.v1.CryptoKeyVersionTemplate] +// specifies the properties to use when creating a new +// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], either manually +// with +// [CreateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.CreateCryptoKeyVersion] +// or automatically as a result of auto-rotation. +message CryptoKeyVersionTemplate { + // [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] to use when creating + // a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] based on this + // template. Immutable. Defaults to + // [SOFTWARE][google.cloud.kms.v1.ProtectionLevel.SOFTWARE]. + ProtectionLevel protection_level = 1; + + // Required. + // [Algorithm][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm] + // to use when creating a + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] based on this + // template. + // + // For backwards compatibility, GOOGLE_SYMMETRIC_ENCRYPTION is implied if both + // this field is omitted and + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] is + // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT]. + CryptoKeyVersion.CryptoKeyVersionAlgorithm algorithm = 3; +} + +// Contains an HSM-generated attestation about a key operation. +message KeyOperationAttestation { + // Attestion formats provided by the HSM. + enum AttestationFormat { + ATTESTATION_FORMAT_UNSPECIFIED = 0; + + // Cavium HSM attestation compressed with gzip. Note that this format is + // defined by Cavium and subject to change at any time. + CAVIUM_V1_COMPRESSED = 3; + + // Cavium HSM attestation V2 compressed with gzip. This is a new format + // Introduced in Cavium's version 3.2-08 + CAVIUM_V2_COMPRESSED = 4; + } + + // Output only. The format of the attestation data. + AttestationFormat format = 4; + + // Output only. The attestation data provided by the HSM when the key + // operation was performed. + bytes content = 5; +} + +// A [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] represents an +// individual cryptographic key, and the associated key material. +// +// An +// [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] +// version can be used for cryptographic operations. +// +// For security reasons, the raw cryptographic key material represented by a +// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] can never be viewed +// or exported. It can only be used to encrypt, decrypt, or sign data when an +// authorized user or application invokes Cloud KMS. +message CryptoKeyVersion { + // The algorithm of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], indicating what + // parameters must be used for each cryptographic operation. + // + // The + // [GOOGLE_SYMMETRIC_ENCRYPTION][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm.GOOGLE_SYMMETRIC_ENCRYPTION] + // algorithm is usable with + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] + // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT]. + // + // Algorithms beginning with "RSA_SIGN_" are usable with + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] + // [ASYMMETRIC_SIGN][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN]. + // + // The fields in the name after "RSA_SIGN_" correspond to the following + // parameters: padding algorithm, modulus bit length, and digest algorithm. + // + // For PSS, the salt length used is equal to the length of digest + // algorithm. For example, + // [RSA_SIGN_PSS_2048_SHA256][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm.RSA_SIGN_PSS_2048_SHA256] + // will use PSS with a salt length of 256 bits or 32 bytes. + // + // Algorithms beginning with "RSA_DECRYPT_" are usable with + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] + // [ASYMMETRIC_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_DECRYPT]. + // + // The fields in the name after "RSA_DECRYPT_" correspond to the following + // parameters: padding algorithm, modulus bit length, and digest algorithm. + // + // Algorithms beginning with "EC_SIGN_" are usable with + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] + // [ASYMMETRIC_SIGN][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN]. + // + // The fields in the name after "EC_SIGN_" correspond to the following + // parameters: elliptic curve, digest algorithm. + enum CryptoKeyVersionAlgorithm { + // Not specified. + CRYPTO_KEY_VERSION_ALGORITHM_UNSPECIFIED = 0; + + // Creates symmetric encryption keys. + GOOGLE_SYMMETRIC_ENCRYPTION = 1; + + // RSASSA-PSS 2048 bit key with a SHA256 digest. + RSA_SIGN_PSS_2048_SHA256 = 2; + + // RSASSA-PSS 3072 bit key with a SHA256 digest. + RSA_SIGN_PSS_3072_SHA256 = 3; + + // RSASSA-PSS 4096 bit key with a SHA256 digest. + RSA_SIGN_PSS_4096_SHA256 = 4; + + // RSASSA-PKCS1-v1_5 with a 2048 bit key and a SHA256 digest. + RSA_SIGN_PKCS1_2048_SHA256 = 5; + + // RSASSA-PKCS1-v1_5 with a 3072 bit key and a SHA256 digest. + RSA_SIGN_PKCS1_3072_SHA256 = 6; + + // RSASSA-PKCS1-v1_5 with a 4096 bit key and a SHA256 digest. + RSA_SIGN_PKCS1_4096_SHA256 = 7; + + // RSAES-OAEP 2048 bit key with a SHA256 digest. + RSA_DECRYPT_OAEP_2048_SHA256 = 8; + + // RSAES-OAEP 3072 bit key with a SHA256 digest. + RSA_DECRYPT_OAEP_3072_SHA256 = 9; + + // RSAES-OAEP 4096 bit key with a SHA256 digest. + RSA_DECRYPT_OAEP_4096_SHA256 = 10; + + // ECDSA on the NIST P-256 curve with a SHA256 digest. + EC_SIGN_P256_SHA256 = 12; + + // ECDSA on the NIST P-384 curve with a SHA384 digest. + EC_SIGN_P384_SHA384 = 13; + } + + // The state of a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], + // indicating if it can be used. + enum CryptoKeyVersionState { + // Not specified. + CRYPTO_KEY_VERSION_STATE_UNSPECIFIED = 0; + + // This version is still being generated. It may not be used, enabled, + // disabled, or destroyed yet. Cloud KMS will automatically mark this + // version + // [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] + // as soon as the version is ready. + PENDING_GENERATION = 5; + + // This version may be used for cryptographic operations. + ENABLED = 1; + + // This version may not be used, but the key material is still available, + // and the version can be placed back into the + // [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] + // state. + DISABLED = 2; + + // This version is destroyed, and the key material is no longer stored. + // A version may not leave this state once entered. + DESTROYED = 3; + + // This version is scheduled for destruction, and will be destroyed soon. + // Call + // [RestoreCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.RestoreCryptoKeyVersion] + // to put it back into the + // [DISABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DISABLED] + // state. + DESTROY_SCHEDULED = 4; + } + + // A view for [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]s. + // Controls the level of detail returned for + // [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] in + // [KeyManagementService.ListCryptoKeyVersions][google.cloud.kms.v1.KeyManagementService.ListCryptoKeyVersions] + // and + // [KeyManagementService.ListCryptoKeys][google.cloud.kms.v1.KeyManagementService.ListCryptoKeys]. + enum CryptoKeyVersionView { + // Default view for each + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. Does not + // include the + // [attestation][google.cloud.kms.v1.CryptoKeyVersion.attestation] field. + CRYPTO_KEY_VERSION_VIEW_UNSPECIFIED = 0; + + // Provides all fields in each + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], including the + // [attestation][google.cloud.kms.v1.CryptoKeyVersion.attestation]. + FULL = 1; + } + + // Output only. The resource name for this + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] in the format + // `projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*`. + string name = 1; + + // The current state of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. + CryptoKeyVersionState state = 3; + + // Output only. The [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] + // describing how crypto operations are performed with this + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. + ProtectionLevel protection_level = 7; + + // Output only. The + // [CryptoKeyVersionAlgorithm][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm] + // that this [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] + // supports. + CryptoKeyVersionAlgorithm algorithm = 10; + + // Output only. Statement that was generated and signed by the HSM at key + // creation time. Use this statement to verify attributes of the key as stored + // on the HSM, independently of Google. Only provided for key versions with + // [protection_level][google.cloud.kms.v1.CryptoKeyVersion.protection_level] + // [HSM][google.cloud.kms.v1.ProtectionLevel.HSM]. + KeyOperationAttestation attestation = 8; + + // Output only. The time at which this + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] was created. + google.protobuf.Timestamp create_time = 4; + + // Output only. The time this + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]'s key material was + // generated. + google.protobuf.Timestamp generate_time = 11; + + // Output only. The time this + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]'s key material is + // scheduled for destruction. Only present if + // [state][google.cloud.kms.v1.CryptoKeyVersion.state] is + // [DESTROY_SCHEDULED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROY_SCHEDULED]. + google.protobuf.Timestamp destroy_time = 5; + + // Output only. The time this CryptoKeyVersion's key material was + // destroyed. Only present if + // [state][google.cloud.kms.v1.CryptoKeyVersion.state] is + // [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED]. + google.protobuf.Timestamp destroy_event_time = 6; +} + +// The public key for a given +// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. Obtained via +// [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey]. +message PublicKey { + // The public key, encoded in PEM format. For more information, see the + // [RFC 7468](https://tools.ietf.org/html/rfc7468) sections for + // [General Considerations](https://tools.ietf.org/html/rfc7468#section-2) and + // [Textual Encoding of Subject Public Key Info] + // (https://tools.ietf.org/html/rfc7468#section-13). + string pem = 1; + + // The + // [Algorithm][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm] + // associated with this key. + CryptoKeyVersion.CryptoKeyVersionAlgorithm algorithm = 2; +} + +// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] specifies how +// cryptographic operations are performed. +enum ProtectionLevel { + // Not specified. + PROTECTION_LEVEL_UNSPECIFIED = 0; + + // Crypto operations are performed in software. + SOFTWARE = 1; + + // Crypto operations are performed in a Hardware Security Module. + HSM = 2; +} diff --git a/google/cloud/kms/v1/service.proto b/google/cloud/kms/v1/service.proto new file mode 100644 index 000000000..81e22c25f --- /dev/null +++ b/google/cloud/kms/v1/service.proto @@ -0,0 +1,656 @@ +// Copyright 2018 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.kms.v1; + +import "google/api/annotations.proto"; +import "google/cloud/kms/v1/resources.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Kms.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/kms/v1;kms"; +option java_multiple_files = true; +option java_outer_classname = "KmsProto"; +option java_package = "com.google.cloud.kms.v1"; +option php_namespace = "Google\\Cloud\\Kms\\V1"; + +// Google Cloud Key Management Service +// +// Manages cryptographic keys and operations using those keys. Implements a REST +// model with the following objects: +// +// * [KeyRing][google.cloud.kms.v1.KeyRing] +// * [CryptoKey][google.cloud.kms.v1.CryptoKey] +// * [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] +// +// If you are using manual gRPC libraries, see +// [Using gRPC with Cloud KMS](https://cloud.google.com/kms/docs/grpc). +service KeyManagementService { + // Lists [KeyRings][google.cloud.kms.v1.KeyRing]. + rpc ListKeyRings(ListKeyRingsRequest) returns (ListKeyRingsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/keyRings" + }; + } + + // Lists [CryptoKeys][google.cloud.kms.v1.CryptoKey]. + rpc ListCryptoKeys(ListCryptoKeysRequest) returns (ListCryptoKeysResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*/keyRings/*}/cryptoKeys" + }; + } + + // Lists [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion]. + rpc ListCryptoKeyVersions(ListCryptoKeyVersionsRequest) + returns (ListCryptoKeyVersionsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*/keyRings/*/cryptoKeys/*}/cryptoKeyVersions" + }; + } + + // Returns metadata for a given [KeyRing][google.cloud.kms.v1.KeyRing]. + rpc GetKeyRing(GetKeyRingRequest) returns (KeyRing) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/keyRings/*}" + }; + } + + // Returns metadata for a given [CryptoKey][google.cloud.kms.v1.CryptoKey], as + // well as its [primary][google.cloud.kms.v1.CryptoKey.primary] + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. + rpc GetCryptoKey(GetCryptoKeyRequest) returns (CryptoKey) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*}" + }; + } + + // Returns metadata for a given + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. + rpc GetCryptoKeyVersion(GetCryptoKeyVersionRequest) + returns (CryptoKeyVersion) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}" + }; + } + + // Returns the public key for the given + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. The + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] must be + // [ASYMMETRIC_SIGN][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN] + // or + // [ASYMMETRIC_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_DECRYPT]. + rpc GetPublicKey(GetPublicKeyRequest) returns (PublicKey) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}/publicKey" + }; + } + + // Create a new [KeyRing][google.cloud.kms.v1.KeyRing] in a given Project and + // Location. + rpc CreateKeyRing(CreateKeyRingRequest) returns (KeyRing) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/keyRings" + body: "key_ring" + }; + } + + // Create a new [CryptoKey][google.cloud.kms.v1.CryptoKey] within a + // [KeyRing][google.cloud.kms.v1.KeyRing]. + // + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] and + // [CryptoKey.version_template.algorithm][google.cloud.kms.v1.CryptoKeyVersionTemplate.algorithm] + // are required. + rpc CreateCryptoKey(CreateCryptoKeyRequest) returns (CryptoKey) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*/keyRings/*}/cryptoKeys" + body: "crypto_key" + }; + } + + // Create a new [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] in a + // [CryptoKey][google.cloud.kms.v1.CryptoKey]. + // + // The server will assign the next sequential id. If unset, + // [state][google.cloud.kms.v1.CryptoKeyVersion.state] will be set to + // [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED]. + rpc CreateCryptoKeyVersion(CreateCryptoKeyVersionRequest) + returns (CryptoKeyVersion) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*/keyRings/*/cryptoKeys/*}/cryptoKeyVersions" + body: "crypto_key_version" + }; + } + + // Update a [CryptoKey][google.cloud.kms.v1.CryptoKey]. + rpc UpdateCryptoKey(UpdateCryptoKeyRequest) returns (CryptoKey) { + option (google.api.http) = { + patch: "/v1/{crypto_key.name=projects/*/locations/*/keyRings/*/cryptoKeys/*}" + body: "crypto_key" + }; + } + + // Update a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]'s + // metadata. + // + // [state][google.cloud.kms.v1.CryptoKeyVersion.state] may be changed between + // [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] + // and + // [DISABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DISABLED] + // using this method. See + // [DestroyCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.DestroyCryptoKeyVersion] + // and + // [RestoreCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.RestoreCryptoKeyVersion] + // to move between other states. + rpc UpdateCryptoKeyVersion(UpdateCryptoKeyVersionRequest) + returns (CryptoKeyVersion) { + option (google.api.http) = { + patch: "/v1/{crypto_key_version.name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}" + body: "crypto_key_version" + }; + } + + // Encrypts data, so that it can only be recovered by a call to + // [Decrypt][google.cloud.kms.v1.KeyManagementService.Decrypt]. The + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] must be + // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT]. + rpc Encrypt(EncryptRequest) returns (EncryptResponse) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/**}:encrypt" + body: "*" + }; + } + + // Decrypts data that was protected by + // [Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt]. The + // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] must be + // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT]. + rpc Decrypt(DecryptRequest) returns (DecryptResponse) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*}:decrypt" + body: "*" + }; + } + + // Signs data using a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] + // with [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] + // ASYMMETRIC_SIGN, producing a signature that can be verified with the public + // key retrieved from + // [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey]. + rpc AsymmetricSign(AsymmetricSignRequest) returns (AsymmetricSignResponse) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}:asymmetricSign" + body: "*" + }; + } + + // Decrypts data that was encrypted with a public key retrieved from + // [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey] + // corresponding to a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] + // with [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] + // ASYMMETRIC_DECRYPT. + rpc AsymmetricDecrypt(AsymmetricDecryptRequest) + returns (AsymmetricDecryptResponse) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}:asymmetricDecrypt" + body: "*" + }; + } + + // Update the version of a [CryptoKey][google.cloud.kms.v1.CryptoKey] that + // will be used in + // [Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt]. + // + // Returns an error if called on an asymmetric key. + rpc UpdateCryptoKeyPrimaryVersion(UpdateCryptoKeyPrimaryVersionRequest) + returns (CryptoKey) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*}:updatePrimaryVersion" + body: "*" + }; + } + + // Schedule a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] for + // destruction. + // + // Upon calling this method, + // [CryptoKeyVersion.state][google.cloud.kms.v1.CryptoKeyVersion.state] will + // be set to + // [DESTROY_SCHEDULED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROY_SCHEDULED] + // and [destroy_time][google.cloud.kms.v1.CryptoKeyVersion.destroy_time] will + // be set to a time 24 hours in the future, at which point the + // [state][google.cloud.kms.v1.CryptoKeyVersion.state] will be changed to + // [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED], + // and the key material will be irrevocably destroyed. + // + // Before the + // [destroy_time][google.cloud.kms.v1.CryptoKeyVersion.destroy_time] is + // reached, + // [RestoreCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.RestoreCryptoKeyVersion] + // may be called to reverse the process. + rpc DestroyCryptoKeyVersion(DestroyCryptoKeyVersionRequest) + returns (CryptoKeyVersion) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}:destroy" + body: "*" + }; + } + + // Restore a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] in the + // [DESTROY_SCHEDULED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROY_SCHEDULED] + // state. + // + // Upon restoration of the CryptoKeyVersion, + // [state][google.cloud.kms.v1.CryptoKeyVersion.state] will be set to + // [DISABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DISABLED], + // and [destroy_time][google.cloud.kms.v1.CryptoKeyVersion.destroy_time] will + // be cleared. + rpc RestoreCryptoKeyVersion(RestoreCryptoKeyVersionRequest) + returns (CryptoKeyVersion) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*}:restore" + body: "*" + }; + } +} + +// Request message for +// [KeyManagementService.ListKeyRings][google.cloud.kms.v1.KeyManagementService.ListKeyRings]. +message ListKeyRingsRequest { + // Required. The resource name of the location associated with the + // [KeyRings][google.cloud.kms.v1.KeyRing], in the format + // `projects/*/locations/*`. + string parent = 1; + + // Optional limit on the number of [KeyRings][google.cloud.kms.v1.KeyRing] to + // include in the response. Further [KeyRings][google.cloud.kms.v1.KeyRing] + // can subsequently be obtained by including the + // [ListKeyRingsResponse.next_page_token][google.cloud.kms.v1.ListKeyRingsResponse.next_page_token] + // in a subsequent request. If unspecified, the server will pick an + // appropriate default. + int32 page_size = 2; + + // Optional pagination token, returned earlier via + // [ListKeyRingsResponse.next_page_token][google.cloud.kms.v1.ListKeyRingsResponse.next_page_token]. + string page_token = 3; +} + +// Request message for +// [KeyManagementService.ListCryptoKeys][google.cloud.kms.v1.KeyManagementService.ListCryptoKeys]. +message ListCryptoKeysRequest { + // Required. The resource name of the [KeyRing][google.cloud.kms.v1.KeyRing] + // to list, in the format `projects/*/locations/*/keyRings/*`. + string parent = 1; + + // Optional limit on the number of [CryptoKeys][google.cloud.kms.v1.CryptoKey] + // to include in the response. Further + // [CryptoKeys][google.cloud.kms.v1.CryptoKey] can subsequently be obtained by + // including the + // [ListCryptoKeysResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeysResponse.next_page_token] + // in a subsequent request. If unspecified, the server will pick an + // appropriate default. + int32 page_size = 2; + + // Optional pagination token, returned earlier via + // [ListCryptoKeysResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeysResponse.next_page_token]. + string page_token = 3; + + // The fields of the primary version to include in the response. + CryptoKeyVersion.CryptoKeyVersionView version_view = 4; +} + +// Request message for +// [KeyManagementService.ListCryptoKeyVersions][google.cloud.kms.v1.KeyManagementService.ListCryptoKeyVersions]. +message ListCryptoKeyVersionsRequest { + // Required. The resource name of the + // [CryptoKey][google.cloud.kms.v1.CryptoKey] to list, in the format + // `projects/*/locations/*/keyRings/*/cryptoKeys/*`. + string parent = 1; + + // Optional limit on the number of + // [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] to include in the + // response. Further [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] + // can subsequently be obtained by including the + // [ListCryptoKeyVersionsResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeyVersionsResponse.next_page_token] + // in a subsequent request. If unspecified, the server will pick an + // appropriate default. + int32 page_size = 2; + + // Optional pagination token, returned earlier via + // [ListCryptoKeyVersionsResponse.next_page_token][google.cloud.kms.v1.ListCryptoKeyVersionsResponse.next_page_token]. + string page_token = 3; + + // The fields to include in the response. + CryptoKeyVersion.CryptoKeyVersionView view = 4; +} + +// Response message for +// [KeyManagementService.ListKeyRings][google.cloud.kms.v1.KeyManagementService.ListKeyRings]. +message ListKeyRingsResponse { + // The list of [KeyRings][google.cloud.kms.v1.KeyRing]. + repeated KeyRing key_rings = 1; + + // A token to retrieve next page of results. Pass this value in + // [ListKeyRingsRequest.page_token][google.cloud.kms.v1.ListKeyRingsRequest.page_token] + // to retrieve the next page of results. + string next_page_token = 2; + + // The total number of [KeyRings][google.cloud.kms.v1.KeyRing] that matched + // the query. + int32 total_size = 3; +} + +// Response message for +// [KeyManagementService.ListCryptoKeys][google.cloud.kms.v1.KeyManagementService.ListCryptoKeys]. +message ListCryptoKeysResponse { + // The list of [CryptoKeys][google.cloud.kms.v1.CryptoKey]. + repeated CryptoKey crypto_keys = 1; + + // A token to retrieve next page of results. Pass this value in + // [ListCryptoKeysRequest.page_token][google.cloud.kms.v1.ListCryptoKeysRequest.page_token] + // to retrieve the next page of results. + string next_page_token = 2; + + // The total number of [CryptoKeys][google.cloud.kms.v1.CryptoKey] that + // matched the query. + int32 total_size = 3; +} + +// Response message for +// [KeyManagementService.ListCryptoKeyVersions][google.cloud.kms.v1.KeyManagementService.ListCryptoKeyVersions]. +message ListCryptoKeyVersionsResponse { + // The list of [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion]. + repeated CryptoKeyVersion crypto_key_versions = 1; + + // A token to retrieve next page of results. Pass this value in + // [ListCryptoKeyVersionsRequest.page_token][google.cloud.kms.v1.ListCryptoKeyVersionsRequest.page_token] + // to retrieve the next page of results. + string next_page_token = 2; + + // The total number of + // [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] that matched the + // query. + int32 total_size = 3; +} + +// Request message for +// [KeyManagementService.GetKeyRing][google.cloud.kms.v1.KeyManagementService.GetKeyRing]. +message GetKeyRingRequest { + // The [name][google.cloud.kms.v1.KeyRing.name] of the + // [KeyRing][google.cloud.kms.v1.KeyRing] to get. + string name = 1; +} + +// Request message for +// [KeyManagementService.GetCryptoKey][google.cloud.kms.v1.KeyManagementService.GetCryptoKey]. +message GetCryptoKeyRequest { + // The [name][google.cloud.kms.v1.CryptoKey.name] of the + // [CryptoKey][google.cloud.kms.v1.CryptoKey] to get. + string name = 1; +} + +// Request message for +// [KeyManagementService.GetCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.GetCryptoKeyVersion]. +message GetCryptoKeyVersionRequest { + // The [name][google.cloud.kms.v1.CryptoKeyVersion.name] of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to get. + string name = 1; +} + +// Request message for +// [KeyManagementService.GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey]. +message GetPublicKeyRequest { + // The [name][google.cloud.kms.v1.CryptoKeyVersion.name] of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] public key to get. + string name = 1; +} + +// Request message for +// [KeyManagementService.CreateKeyRing][google.cloud.kms.v1.KeyManagementService.CreateKeyRing]. +message CreateKeyRingRequest { + // Required. The resource name of the location associated with the + // [KeyRings][google.cloud.kms.v1.KeyRing], in the format + // `projects/*/locations/*`. + string parent = 1; + + // Required. It must be unique within a location and match the regular + // expression `[a-zA-Z0-9_-]{1,63}` + string key_ring_id = 2; + + // A [KeyRing][google.cloud.kms.v1.KeyRing] with initial field values. + KeyRing key_ring = 3; +} + +// Request message for +// [KeyManagementService.CreateCryptoKey][google.cloud.kms.v1.KeyManagementService.CreateCryptoKey]. +message CreateCryptoKeyRequest { + // Required. The [name][google.cloud.kms.v1.KeyRing.name] of the KeyRing + // associated with the [CryptoKeys][google.cloud.kms.v1.CryptoKey]. + string parent = 1; + + // Required. It must be unique within a KeyRing and match the regular + // expression `[a-zA-Z0-9_-]{1,63}` + string crypto_key_id = 2; + + // A [CryptoKey][google.cloud.kms.v1.CryptoKey] with initial field values. + CryptoKey crypto_key = 3; +} + +// Request message for +// [KeyManagementService.CreateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.CreateCryptoKeyVersion]. +message CreateCryptoKeyVersionRequest { + // Required. The [name][google.cloud.kms.v1.CryptoKey.name] of the + // [CryptoKey][google.cloud.kms.v1.CryptoKey] associated with the + // [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion]. + string parent = 1; + + // A [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] with initial + // field values. + CryptoKeyVersion crypto_key_version = 2; +} + +// Request message for +// [KeyManagementService.UpdateCryptoKey][google.cloud.kms.v1.KeyManagementService.UpdateCryptoKey]. +message UpdateCryptoKeyRequest { + // [CryptoKey][google.cloud.kms.v1.CryptoKey] with updated values. + CryptoKey crypto_key = 1; + + // Required list of fields to be updated in this request. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for +// [KeyManagementService.UpdateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.UpdateCryptoKeyVersion]. +message UpdateCryptoKeyVersionRequest { + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] with updated + // values. + CryptoKeyVersion crypto_key_version = 1; + + // Required list of fields to be updated in this request. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for +// [KeyManagementService.Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt]. +message EncryptRequest { + // Required. The resource name of the + // [CryptoKey][google.cloud.kms.v1.CryptoKey] or + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to use for + // encryption. + // + // If a [CryptoKey][google.cloud.kms.v1.CryptoKey] is specified, the server + // will use its [primary version][google.cloud.kms.v1.CryptoKey.primary]. + string name = 1; + + // Required. The data to encrypt. Must be no larger than 64KiB. + // + // The maximum size depends on the key version's + // [protection_level][google.cloud.kms.v1.CryptoKeyVersionTemplate.protection_level]. + // For [SOFTWARE][google.cloud.kms.v1.ProtectionLevel.SOFTWARE] keys, the + // plaintext must be no larger than 64KiB. For + // [HSM][google.cloud.kms.v1.ProtectionLevel.HSM] keys, the combined length of + // the plaintext and additional_authenticated_data fields must be no larger + // than 8KiB. + bytes plaintext = 2; + + // Optional data that, if specified, must also be provided during decryption + // through + // [DecryptRequest.additional_authenticated_data][google.cloud.kms.v1.DecryptRequest.additional_authenticated_data]. + // + // The maximum size depends on the key version's + // [protection_level][google.cloud.kms.v1.CryptoKeyVersionTemplate.protection_level]. + // For [SOFTWARE][google.cloud.kms.v1.ProtectionLevel.SOFTWARE] keys, the AAD + // must be no larger than 64KiB. For + // [HSM][google.cloud.kms.v1.ProtectionLevel.HSM] keys, the combined length of + // the plaintext and additional_authenticated_data fields must be no larger + // than 8KiB. + bytes additional_authenticated_data = 3; +} + +// Request message for +// [KeyManagementService.Decrypt][google.cloud.kms.v1.KeyManagementService.Decrypt]. +message DecryptRequest { + // Required. The resource name of the + // [CryptoKey][google.cloud.kms.v1.CryptoKey] to use for decryption. The + // server will choose the appropriate version. + string name = 1; + + // Required. The encrypted data originally returned in + // [EncryptResponse.ciphertext][google.cloud.kms.v1.EncryptResponse.ciphertext]. + bytes ciphertext = 2; + + // Optional data that must match the data originally supplied in + // [EncryptRequest.additional_authenticated_data][google.cloud.kms.v1.EncryptRequest.additional_authenticated_data]. + bytes additional_authenticated_data = 3; +} + +// Request message for +// [KeyManagementService.AsymmetricSign][google.cloud.kms.v1.KeyManagementService.AsymmetricSign]. +message AsymmetricSignRequest { + // Required. The resource name of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to use for + // signing. + string name = 1; + + // Required. The digest of the data to sign. The digest must be produced with + // the same digest algorithm as specified by the key version's + // [algorithm][google.cloud.kms.v1.CryptoKeyVersion.algorithm]. + Digest digest = 3; +} + +// Request message for +// [KeyManagementService.AsymmetricDecrypt][google.cloud.kms.v1.KeyManagementService.AsymmetricDecrypt]. +message AsymmetricDecryptRequest { + // Required. The resource name of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to use for + // decryption. + string name = 1; + + // Required. The data encrypted with the named + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]'s public key using + // OAEP. + bytes ciphertext = 3; +} + +// Response message for +// [KeyManagementService.Decrypt][google.cloud.kms.v1.KeyManagementService.Decrypt]. +message DecryptResponse { + // The decrypted data originally supplied in + // [EncryptRequest.plaintext][google.cloud.kms.v1.EncryptRequest.plaintext]. + bytes plaintext = 1; +} + +// Response message for +// [KeyManagementService.Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt]. +message EncryptResponse { + // The resource name of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] used in + // encryption. + string name = 1; + + // The encrypted data. + bytes ciphertext = 2; +} + +// Response message for +// [KeyManagementService.AsymmetricSign][google.cloud.kms.v1.KeyManagementService.AsymmetricSign]. +message AsymmetricSignResponse { + // The created signature. + bytes signature = 1; +} + +// Response message for +// [KeyManagementService.AsymmetricDecrypt][google.cloud.kms.v1.KeyManagementService.AsymmetricDecrypt]. +message AsymmetricDecryptResponse { + // The decrypted data originally encrypted with the matching public key. + bytes plaintext = 1; +} + +// Request message for +// [KeyManagementService.UpdateCryptoKeyPrimaryVersion][google.cloud.kms.v1.KeyManagementService.UpdateCryptoKeyPrimaryVersion]. +message UpdateCryptoKeyPrimaryVersionRequest { + // The resource name of the [CryptoKey][google.cloud.kms.v1.CryptoKey] to + // update. + string name = 1; + + // The id of the child + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to use as primary. + string crypto_key_version_id = 2; +} + +// Request message for +// [KeyManagementService.DestroyCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.DestroyCryptoKeyVersion]. +message DestroyCryptoKeyVersionRequest { + // The resource name of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to destroy. + string name = 1; +} + +// Request message for +// [KeyManagementService.RestoreCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.RestoreCryptoKeyVersion]. +message RestoreCryptoKeyVersionRequest { + // The resource name of the + // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to restore. + string name = 1; +} + +// A [Digest][google.cloud.kms.v1.Digest] holds a cryptographic message digest. +message Digest { + // Required. The message digest. + oneof digest { + // A message digest produced with the SHA-256 algorithm. + bytes sha256 = 1; + + // A message digest produced with the SHA-384 algorithm. + bytes sha384 = 2; + + // A message digest produced with the SHA-512 algorithm. + bytes sha512 = 3; + } +} + +// Cloud KMS metadata for the given +// [google.cloud.location.Location][google.cloud.location.Location]. +message LocationMetadata { + // Indicates whether [CryptoKeys][google.cloud.kms.v1.CryptoKey] with + // [protection_level][google.cloud.kms.v1.CryptoKeyVersionTemplate.protection_level] + // [HSM][google.cloud.kms.v1.ProtectionLevel.HSM] can be created in this + // location. + bool hsm_available = 1; +} diff --git a/google/cloud/language/BUILD.bazel b/google/cloud/language/BUILD.bazel new file mode 100644 index 000000000..a87c57fec --- /dev/null +++ b/google/cloud/language/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"])) diff --git a/google/cloud/language/README.md b/google/cloud/language/README.md new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/google/cloud/language/README.md diff --git a/google/cloud/language/artman_language_v1.yaml b/google/cloud/language/artman_language_v1.yaml new file mode 100644 index 000000000..56c301dd1 --- /dev/null +++ b/google/cloud/language/artman_language_v1.yaml @@ -0,0 +1,34 @@ +common: + api_name: language + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: language_v1.yaml + gapic_yaml: v1/language_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/language/artman_language_v1beta2.yaml b/google/cloud/language/artman_language_v1beta2.yaml new file mode 100644 index 000000000..11b3ad242 --- /dev/null +++ b/google/cloud/language/artman_language_v1beta2.yaml @@ -0,0 +1,35 @@ +common: + api_name: language + api_version: v1beta2 + organization_name: google-cloud + service_yaml: language_v1beta2.yaml + gapic_yaml: v1beta2/language_gapic.yaml + src_proto_paths: + - v1beta2 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/language/language.yaml b/google/cloud/language/language.yaml new file mode 100644 index 000000000..ad7201b9a --- /dev/null +++ b/google/cloud/language/language.yaml @@ -0,0 +1,33 @@ +type: google.api.Service +config_version: 3 +name: language.googleapis.com +title: Google Cloud Natural Language API + +apis: +- name: google.cloud.language.v1.LanguageService +- name: google.cloud.language.v1beta1.LanguageService +- name: google.cloud.language.v1beta2.LanguageService + +types: +- name: google.protobuf.Timestamp +- name: google.rpc.Status + +enums: +- name: google.rpc.Code + +documentation: + summary: |- + Provides natural language understanding technologies to developers. Examples + include sentiment analysis, entity recognition, entity sentiment analysis, + and text annotations. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-language, + https://www.googleapis.com/auth/cloud-platform + +legacy: + taxonomy_id: 8953562382 # http://teams/product/8953562382 diff --git a/google/cloud/language/language_v1.yaml b/google/cloud/language/language_v1.yaml new file mode 100644 index 000000000..9ef71698c --- /dev/null +++ b/google/cloud/language/language_v1.yaml @@ -0,0 +1,21 @@ +type: google.api.Service +config_version: 3 +name: language.googleapis.com +title: Cloud Natural Language API + +apis: + - name: google.cloud.language.v1.LanguageService + +documentation: + summary: |- + Provides natural language understanding technologies, such as sentiment + analysis, entity recognition, entity sentiment analysis, and other text + annotations, to developers. + +authentication: + rules: + - selector: 'google.cloud.language.v1.LanguageService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-language, + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/language/language_v1beta2.yaml b/google/cloud/language/language_v1beta2.yaml new file mode 100644 index 000000000..aae1f6f55 --- /dev/null +++ b/google/cloud/language/language_v1beta2.yaml @@ -0,0 +1,19 @@ +type: google.api.Service +config_version: 2 +name: language.googleapis.com +title: Google Cloud Natural Language API + +apis: +- name: google.cloud.language.v1beta2.LanguageService + +documentation: + summary: + 'Google Cloud Natural Language API provides natural language understanding + technologies to developers. Examples include sentiment analysis, entity + recognition, and text annotations.' + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/language/v1/BUILD.bazel b/google/cloud/language/v1/BUILD.bazel new file mode 100644 index 000000000..0b8322675 --- /dev/null +++ b/google/cloud/language/v1/BUILD.bazel @@ -0,0 +1,115 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "language_proto", + srcs = ["language_service.proto"], + deps = ["//google/api:annotations_proto"], +) + +proto_library_with_info( + name = "language_proto_with_info", + deps = [":language_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", "java_gapic_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "language_java_proto", + deps = [":language_proto"], +) + +java_grpc_library( + name = "language_java_grpc", + srcs = [":language_proto"], + deps = [":language_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_gapic_library( + name = "language_java_gapic", + src = ":language_proto_with_info", + gapic_yaml = "language_gapic.yaml", + service_yaml = "//google/cloud/language:language_v1.yaml", + test_deps = [":language_java_grpc"], + deps = [":language_java_proto"] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":language_java_gapic_test"], +) for test_name in [ + "com.google.cloud.language.v1.LanguageServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-language-v1-java", + client_deps = [":language_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":language_java_gapic_test"], + grpc_deps = [":language_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":language_java_proto", + ":language_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "language_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/language/v1", + protos = [":language_proto_with_info"], + deps = ["//google/api:annotations_go_proto"], +) + +go_gapic_library( + name = "language_go_gapic", + src = ":language_proto_with_info", + gapic_yaml = "language_gapic.yaml", + importpath = "cloud.google.com/go/language/apiv1", + service_yaml = "//google/cloud/language:language_v1.yaml", + deps = [":language_go_proto"], +) + +go_test( + name = "language_go_gapic_test", + srcs = [":language_go_gapic_srcjar_test"], + embed = [":language_go_gapic"], + importpath = "cloud.google.com/go/language/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-language-v1-go", + deps = [ + ":language_go_gapic", + ":language_go_gapic_srcjar-smoke-test.srcjar", + ":language_go_gapic_srcjar-test.srcjar", + ":language_go_proto", + ], +) diff --git a/google/cloud/language/v1/language_gapic.yaml b/google/cloud/language/v1/language_gapic.yaml new file mode 100644 index 000000000..2b05e8be2 --- /dev/null +++ b/google/cloud/language/v1/language_gapic.yaml @@ -0,0 +1,185 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.language.v1 + python: + package_name: google.cloud.language_v1.gapic + go: + package_name: cloud.google.com/go/language/apiv1 + csharp: + package_name: Google.Cloud.Language.V1 + ruby: + package_name: Google::Cloud::Language::V1 + php: + package_name: Google\Cloud\Language\V1 + nodejs: + package_name: language.v1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.language.v1.LanguageService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: AnalyzeSentiment + flattening: + groups: + - parameters: + - document + - encoding_type + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AnalyzeEntities + flattening: + groups: + - parameters: + - document + - encoding_type + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AnalyzeEntitySentiment + flattening: + groups: + - parameters: + - document + - encoding_type + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AnalyzeSyntax + flattening: + groups: + - parameters: + - document + - encoding_type + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: ClassifyText + flattening: + groups: + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AnnotateText + flattening: + groups: + - parameters: + - document + - features + - encoding_type + - parameters: + - document + - features + required_fields: + - document + - features + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/language/v1/language_service.proto b/google/cloud/language/v1/language_service.proto new file mode 100644 index 000000000..41d92f344 --- /dev/null +++ b/google/cloud/language/v1/language_service.proto @@ -0,0 +1,1122 @@ +// Copyright 2019 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.language.v1; + +import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/language/v1;language"; +option java_multiple_files = true; +option java_outer_classname = "LanguageServiceProto"; +option java_package = "com.google.cloud.language.v1"; + + +// Provides text analysis operations such as sentiment analysis and entity +// recognition. +service LanguageService { + option (google.api.default_host) = "language.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-language," + "https://www.googleapis.com/auth/cloud-platform"; + // Analyzes the sentiment of the provided text. + rpc AnalyzeSentiment(AnalyzeSentimentRequest) returns (AnalyzeSentimentResponse) { + option (google.api.http) = { + post: "/v1/documents:analyzeSentiment" + body: "*" + }; + option (google.api.method_signature) = "document,encoding_type"; + option (google.api.method_signature) = "document"; + } + + // Finds named entities (currently proper names and common nouns) in the text + // along with entity types, salience, mentions for each entity, and + // other properties. + rpc AnalyzeEntities(AnalyzeEntitiesRequest) returns (AnalyzeEntitiesResponse) { + option (google.api.http) = { + post: "/v1/documents:analyzeEntities" + body: "*" + }; + option (google.api.method_signature) = "document,encoding_type"; + option (google.api.method_signature) = "document"; + } + + // Finds entities, similar to [AnalyzeEntities][google.cloud.language.v1.LanguageService.AnalyzeEntities] in the text and analyzes + // sentiment associated with each entity and its mentions. + rpc AnalyzeEntitySentiment(AnalyzeEntitySentimentRequest) returns (AnalyzeEntitySentimentResponse) { + option (google.api.http) = { + post: "/v1/documents:analyzeEntitySentiment" + body: "*" + }; + option (google.api.method_signature) = "document,encoding_type"; + option (google.api.method_signature) = "document"; + } + + // Analyzes the syntax of the text and provides sentence boundaries and + // tokenization along with part of speech tags, dependency trees, and other + // properties. + rpc AnalyzeSyntax(AnalyzeSyntaxRequest) returns (AnalyzeSyntaxResponse) { + option (google.api.http) = { + post: "/v1/documents:analyzeSyntax" + body: "*" + }; + option (google.api.method_signature) = "document,encoding_type"; + option (google.api.method_signature) = "document"; + } + + // Classifies a document into categories. + rpc ClassifyText(ClassifyTextRequest) returns (ClassifyTextResponse) { + option (google.api.http) = { + post: "/v1/documents:classifyText" + body: "*" + }; + option (google.api.method_signature) = "document"; + } + + // A convenience method that provides all the features that analyzeSentiment, + // analyzeEntities, and analyzeSyntax provide in one call. + rpc AnnotateText(AnnotateTextRequest) returns (AnnotateTextResponse) { + option (google.api.http) = { + post: "/v1/documents:annotateText" + body: "*" + }; + option (google.api.method_signature) = "document,features,encoding_type"; + option (google.api.method_signature) = "document,features"; + } +} + +// ################################################################ # +// +// Represents the input to API methods. +message Document { + // The document types enum. + enum Type { + // The content type is not specified. + TYPE_UNSPECIFIED = 0; + + // Plain text + PLAIN_TEXT = 1; + + // HTML + HTML = 2; + } + + // Required. If the type is not set or is `TYPE_UNSPECIFIED`, + // returns an `INVALID_ARGUMENT` error. + Type type = 1; + + // The source of the document: a string containing the content or a + // Google Cloud Storage URI. + oneof source { + // The content of the input in string format. + // Cloud audit logging exempt since it is based on user data. + string content = 2; + + // The Google Cloud Storage URI where the file content is located. + // This URI must be of the form: gs://bucket_name/object_name. For more + // details, see https://cloud.google.com/storage/docs/reference-uris. + // NOTE: Cloud Storage object versioning is not supported. + string gcs_content_uri = 3; + } + + // The language of the document (if not specified, the language is + // automatically detected). Both ISO and BCP-47 language codes are + // accepted.<br> + // [Language Support](/natural-language/docs/languages) + // lists currently supported languages for each API method. + // If the language (either specified by the caller or automatically detected) + // is not supported by the called API method, an `INVALID_ARGUMENT` error + // is returned. + string language = 4; +} + +// Represents a sentence in the input document. +message Sentence { + // The sentence text. + TextSpan text = 1; + + // For calls to [AnalyzeSentiment][] or if + // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_document_sentiment] is set to + // true, this field will contain the sentiment for the sentence. + Sentiment sentiment = 2; +} + +// Represents a phrase in the text that is a known entity, such as +// a person, an organization, or location. The API associates information, such +// as salience and mentions, with entities. +message Entity { + // The type of the entity. For most entity types, the associated metadata is a + // Wikipedia URL (`wikipedia_url`) and Knowledge Graph MID (`mid`). The table + // below lists the associated fields for entities that have different + // metadata. + enum Type { + // Unknown + UNKNOWN = 0; + + // Person + PERSON = 1; + + // Location + LOCATION = 2; + + // Organization + ORGANIZATION = 3; + + // Event + EVENT = 4; + + // Artwork + WORK_OF_ART = 5; + + // Consumer product + CONSUMER_GOOD = 6; + + // Other types of entities + OTHER = 7; + + // Phone number<br><br> + // The metadata lists the phone number, formatted according to local + // convention, plus whichever additional elements appear in the text:<ul> + // <li><code>number</code> – the actual number, broken down into + // sections as per local convention</li> <li><code>national_prefix</code> + // – country code, if detected</li> <li><code>area_code</code> – + // region or area code, if detected</li> <li><code>extension</code> – + // phone extension (to be dialed after connection), if detected</li></ul> + PHONE_NUMBER = 9; + + // Address<br><br> + // The metadata identifies the street number and locality plus whichever + // additional elements appear in the text:<ul> + // <li><code>street_number</code> – street number</li> + // <li><code>locality</code> – city or town</li> + // <li><code>street_name</code> – street/route name, if detected</li> + // <li><code>postal_code</code> – postal code, if detected</li> + // <li><code>country</code> – country, if detected</li> + // <li><code>broad_region</code> – administrative area, such as the + // state, if detected</li> <li><code>narrow_region</code> – smaller + // administrative area, such as county, if detected</li> + // <li><code>sublocality</code> – used in Asian addresses to demark a + // district within a city, if detected</li></ul> + ADDRESS = 10; + + // Date<br><br> + // The metadata identifies the components of the date:<ul> + // <li><code>year</code> – four digit year, if detected</li> + // <li><code>month</code> – two digit month number, if detected</li> + // <li><code>day</code> – two digit day number, if detected</li></ul> + DATE = 11; + + // Number<br><br> + // The metadata is the number itself. + NUMBER = 12; + + // Price<br><br> + // The metadata identifies the <code>value</code> and <code>currency</code>. + PRICE = 13; + } + + // The representative name for the entity. + string name = 1; + + // The entity type. + Type type = 2; + + // Metadata associated with the entity. + // + // For most entity types, the metadata is a Wikipedia URL (`wikipedia_url`) + // and Knowledge Graph MID (`mid`), if they are available. For the metadata + // associated with other entity types, see the Type table below. + map<string, string> metadata = 3; + + // The salience score associated with the entity in the [0, 1.0] range. + // + // The salience score for an entity provides information about the + // importance or centrality of that entity to the entire document text. + // Scores closer to 0 are less salient, while scores closer to 1.0 are highly + // salient. + float salience = 4; + + // The mentions of this entity in the input document. The API currently + // supports proper noun mentions. + repeated EntityMention mentions = 5; + + // For calls to [AnalyzeEntitySentiment][] or if + // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_entity_sentiment] is set to + // true, this field will contain the aggregate sentiment expressed for this + // entity in the provided document. + Sentiment sentiment = 6; +} + +// Represents the text encoding that the caller uses to process the output. +// Providing an `EncodingType` is recommended because the API provides the +// beginning offsets for various outputs, such as tokens and mentions, and +// languages that natively use different text encodings may access offsets +// differently. +enum EncodingType { + // If `EncodingType` is not specified, encoding-dependent information (such as + // `begin_offset`) will be set at `-1`. + NONE = 0; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-8 encoding of the input. C++ and Go are examples of languages + // that use this encoding natively. + UTF8 = 1; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-16 encoding of the input. Java and JavaScript are examples of + // languages that use this encoding natively. + UTF16 = 2; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-32 encoding of the input. Python is an example of a language + // that uses this encoding natively. + UTF32 = 3; +} + +// Represents the smallest syntactic building block of the text. +message Token { + // The token text. + TextSpan text = 1; + + // Parts of speech tag for this token. + PartOfSpeech part_of_speech = 2; + + // Dependency tree parse for this token. + DependencyEdge dependency_edge = 3; + + // [Lemma](https://en.wikipedia.org/wiki/Lemma_%28morphology%29) of the token. + string lemma = 4; +} + +// Represents the feeling associated with the entire text or entities in +// the text. +message Sentiment { + // A non-negative number in the [0, +inf) range, which represents + // the absolute magnitude of sentiment regardless of score (positive or + // negative). + float magnitude = 2; + + // Sentiment score between -1.0 (negative sentiment) and 1.0 + // (positive sentiment). + float score = 3; +} + +// Represents part of speech information for a token. Parts of speech +// are as defined in +// http://www.lrec-conf.org/proceedings/lrec2012/pdf/274_Paper.pdf +message PartOfSpeech { + // The part of speech tags enum. + enum Tag { + // Unknown + UNKNOWN = 0; + + // Adjective + ADJ = 1; + + // Adposition (preposition and postposition) + ADP = 2; + + // Adverb + ADV = 3; + + // Conjunction + CONJ = 4; + + // Determiner + DET = 5; + + // Noun (common and proper) + NOUN = 6; + + // Cardinal number + NUM = 7; + + // Pronoun + PRON = 8; + + // Particle or other function word + PRT = 9; + + // Punctuation + PUNCT = 10; + + // Verb (all tenses and modes) + VERB = 11; + + // Other: foreign words, typos, abbreviations + X = 12; + + // Affix + AFFIX = 13; + } + + // The characteristic of a verb that expresses time flow during an event. + enum Aspect { + // Aspect is not applicable in the analyzed language or is not predicted. + ASPECT_UNKNOWN = 0; + + // Perfective + PERFECTIVE = 1; + + // Imperfective + IMPERFECTIVE = 2; + + // Progressive + PROGRESSIVE = 3; + } + + // The grammatical function performed by a noun or pronoun in a phrase, + // clause, or sentence. In some languages, other parts of speech, such as + // adjective and determiner, take case inflection in agreement with the noun. + enum Case { + // Case is not applicable in the analyzed language or is not predicted. + CASE_UNKNOWN = 0; + + // Accusative + ACCUSATIVE = 1; + + // Adverbial + ADVERBIAL = 2; + + // Complementive + COMPLEMENTIVE = 3; + + // Dative + DATIVE = 4; + + // Genitive + GENITIVE = 5; + + // Instrumental + INSTRUMENTAL = 6; + + // Locative + LOCATIVE = 7; + + // Nominative + NOMINATIVE = 8; + + // Oblique + OBLIQUE = 9; + + // Partitive + PARTITIVE = 10; + + // Prepositional + PREPOSITIONAL = 11; + + // Reflexive + REFLEXIVE_CASE = 12; + + // Relative + RELATIVE_CASE = 13; + + // Vocative + VOCATIVE = 14; + } + + // Depending on the language, Form can be categorizing different forms of + // verbs, adjectives, adverbs, etc. For example, categorizing inflected + // endings of verbs and adjectives or distinguishing between short and long + // forms of adjectives and participles + enum Form { + // Form is not applicable in the analyzed language or is not predicted. + FORM_UNKNOWN = 0; + + // Adnomial + ADNOMIAL = 1; + + // Auxiliary + AUXILIARY = 2; + + // Complementizer + COMPLEMENTIZER = 3; + + // Final ending + FINAL_ENDING = 4; + + // Gerund + GERUND = 5; + + // Realis + REALIS = 6; + + // Irrealis + IRREALIS = 7; + + // Short form + SHORT = 8; + + // Long form + LONG = 9; + + // Order form + ORDER = 10; + + // Specific form + SPECIFIC = 11; + } + + // Gender classes of nouns reflected in the behaviour of associated words. + enum Gender { + // Gender is not applicable in the analyzed language or is not predicted. + GENDER_UNKNOWN = 0; + + // Feminine + FEMININE = 1; + + // Masculine + MASCULINE = 2; + + // Neuter + NEUTER = 3; + } + + // The grammatical feature of verbs, used for showing modality and attitude. + enum Mood { + // Mood is not applicable in the analyzed language or is not predicted. + MOOD_UNKNOWN = 0; + + // Conditional + CONDITIONAL_MOOD = 1; + + // Imperative + IMPERATIVE = 2; + + // Indicative + INDICATIVE = 3; + + // Interrogative + INTERROGATIVE = 4; + + // Jussive + JUSSIVE = 5; + + // Subjunctive + SUBJUNCTIVE = 6; + } + + // Count distinctions. + enum Number { + // Number is not applicable in the analyzed language or is not predicted. + NUMBER_UNKNOWN = 0; + + // Singular + SINGULAR = 1; + + // Plural + PLURAL = 2; + + // Dual + DUAL = 3; + } + + // The distinction between the speaker, second person, third person, etc. + enum Person { + // Person is not applicable in the analyzed language or is not predicted. + PERSON_UNKNOWN = 0; + + // First + FIRST = 1; + + // Second + SECOND = 2; + + // Third + THIRD = 3; + + // Reflexive + REFLEXIVE_PERSON = 4; + } + + // This category shows if the token is part of a proper name. + enum Proper { + // Proper is not applicable in the analyzed language or is not predicted. + PROPER_UNKNOWN = 0; + + // Proper + PROPER = 1; + + // Not proper + NOT_PROPER = 2; + } + + // Reciprocal features of a pronoun. + enum Reciprocity { + // Reciprocity is not applicable in the analyzed language or is not + // predicted. + RECIPROCITY_UNKNOWN = 0; + + // Reciprocal + RECIPROCAL = 1; + + // Non-reciprocal + NON_RECIPROCAL = 2; + } + + // Time reference. + enum Tense { + // Tense is not applicable in the analyzed language or is not predicted. + TENSE_UNKNOWN = 0; + + // Conditional + CONDITIONAL_TENSE = 1; + + // Future + FUTURE = 2; + + // Past + PAST = 3; + + // Present + PRESENT = 4; + + // Imperfect + IMPERFECT = 5; + + // Pluperfect + PLUPERFECT = 6; + } + + // The relationship between the action that a verb expresses and the + // participants identified by its arguments. + enum Voice { + // Voice is not applicable in the analyzed language or is not predicted. + VOICE_UNKNOWN = 0; + + // Active + ACTIVE = 1; + + // Causative + CAUSATIVE = 2; + + // Passive + PASSIVE = 3; + } + + // The part of speech tag. + Tag tag = 1; + + // The grammatical aspect. + Aspect aspect = 2; + + // The grammatical case. + Case case = 3; + + // The grammatical form. + Form form = 4; + + // The grammatical gender. + Gender gender = 5; + + // The grammatical mood. + Mood mood = 6; + + // The grammatical number. + Number number = 7; + + // The grammatical person. + Person person = 8; + + // The grammatical properness. + Proper proper = 9; + + // The grammatical reciprocity. + Reciprocity reciprocity = 10; + + // The grammatical tense. + Tense tense = 11; + + // The grammatical voice. + Voice voice = 12; +} + +// Represents dependency parse tree information for a token. (For more +// information on dependency labels, see +// http://www.aclweb.org/anthology/P13-2017 +message DependencyEdge { + // The parse label enum for the token. + enum Label { + // Unknown + UNKNOWN = 0; + + // Abbreviation modifier + ABBREV = 1; + + // Adjectival complement + ACOMP = 2; + + // Adverbial clause modifier + ADVCL = 3; + + // Adverbial modifier + ADVMOD = 4; + + // Adjectival modifier of an NP + AMOD = 5; + + // Appositional modifier of an NP + APPOS = 6; + + // Attribute dependent of a copular verb + ATTR = 7; + + // Auxiliary (non-main) verb + AUX = 8; + + // Passive auxiliary + AUXPASS = 9; + + // Coordinating conjunction + CC = 10; + + // Clausal complement of a verb or adjective + CCOMP = 11; + + // Conjunct + CONJ = 12; + + // Clausal subject + CSUBJ = 13; + + // Clausal passive subject + CSUBJPASS = 14; + + // Dependency (unable to determine) + DEP = 15; + + // Determiner + DET = 16; + + // Discourse + DISCOURSE = 17; + + // Direct object + DOBJ = 18; + + // Expletive + EXPL = 19; + + // Goes with (part of a word in a text not well edited) + GOESWITH = 20; + + // Indirect object + IOBJ = 21; + + // Marker (word introducing a subordinate clause) + MARK = 22; + + // Multi-word expression + MWE = 23; + + // Multi-word verbal expression + MWV = 24; + + // Negation modifier + NEG = 25; + + // Noun compound modifier + NN = 26; + + // Noun phrase used as an adverbial modifier + NPADVMOD = 27; + + // Nominal subject + NSUBJ = 28; + + // Passive nominal subject + NSUBJPASS = 29; + + // Numeric modifier of a noun + NUM = 30; + + // Element of compound number + NUMBER = 31; + + // Punctuation mark + P = 32; + + // Parataxis relation + PARATAXIS = 33; + + // Participial modifier + PARTMOD = 34; + + // The complement of a preposition is a clause + PCOMP = 35; + + // Object of a preposition + POBJ = 36; + + // Possession modifier + POSS = 37; + + // Postverbal negative particle + POSTNEG = 38; + + // Predicate complement + PRECOMP = 39; + + // Preconjunt + PRECONJ = 40; + + // Predeterminer + PREDET = 41; + + // Prefix + PREF = 42; + + // Prepositional modifier + PREP = 43; + + // The relationship between a verb and verbal morpheme + PRONL = 44; + + // Particle + PRT = 45; + + // Associative or possessive marker + PS = 46; + + // Quantifier phrase modifier + QUANTMOD = 47; + + // Relative clause modifier + RCMOD = 48; + + // Complementizer in relative clause + RCMODREL = 49; + + // Ellipsis without a preceding predicate + RDROP = 50; + + // Referent + REF = 51; + + // Remnant + REMNANT = 52; + + // Reparandum + REPARANDUM = 53; + + // Root + ROOT = 54; + + // Suffix specifying a unit of number + SNUM = 55; + + // Suffix + SUFF = 56; + + // Temporal modifier + TMOD = 57; + + // Topic marker + TOPIC = 58; + + // Clause headed by an infinite form of the verb that modifies a noun + VMOD = 59; + + // Vocative + VOCATIVE = 60; + + // Open clausal complement + XCOMP = 61; + + // Name suffix + SUFFIX = 62; + + // Name title + TITLE = 63; + + // Adverbial phrase modifier + ADVPHMOD = 64; + + // Causative auxiliary + AUXCAUS = 65; + + // Helper auxiliary + AUXVV = 66; + + // Rentaishi (Prenominal modifier) + DTMOD = 67; + + // Foreign words + FOREIGN = 68; + + // Keyword + KW = 69; + + // List for chains of comparable items + LIST = 70; + + // Nominalized clause + NOMC = 71; + + // Nominalized clausal subject + NOMCSUBJ = 72; + + // Nominalized clausal passive + NOMCSUBJPASS = 73; + + // Compound of numeric modifier + NUMC = 74; + + // Copula + COP = 75; + + // Dislocated relation (for fronted/topicalized elements) + DISLOCATED = 76; + + // Aspect marker + ASP = 77; + + // Genitive modifier + GMOD = 78; + + // Genitive object + GOBJ = 79; + + // Infinitival modifier + INFMOD = 80; + + // Measure + MES = 81; + + // Nominal complement of a noun + NCOMP = 82; + } + + // Represents the head of this token in the dependency tree. + // This is the index of the token which has an arc going to this token. + // The index is the position of the token in the array of tokens returned + // by the API method. If this token is a root token, then the + // `head_token_index` is its own index. + int32 head_token_index = 1; + + // The parse label for the token. + Label label = 2; +} + +// Represents a mention for an entity in the text. Currently, proper noun +// mentions are supported. +message EntityMention { + // The supported types of mentions. + enum Type { + // Unknown + TYPE_UNKNOWN = 0; + + // Proper name + PROPER = 1; + + // Common noun (or noun compound) + COMMON = 2; + } + + // The mention text. + TextSpan text = 1; + + // The type of the entity mention. + Type type = 2; + + // For calls to [AnalyzeEntitySentiment][] or if + // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_entity_sentiment] is set to + // true, this field will contain the sentiment expressed for this mention of + // the entity in the provided document. + Sentiment sentiment = 3; +} + +// Represents an output piece of text. +message TextSpan { + // The content of the output text. + string content = 1; + + // The API calculates the beginning offset of the content in the original + // document according to the [EncodingType][google.cloud.language.v1.EncodingType] specified in the API request. + int32 begin_offset = 2; +} + +// Represents a category returned from the text classifier. +message ClassificationCategory { + // The name of the category representing the document, from the [predefined + // taxonomy](/natural-language/docs/categories). + string name = 1; + + // The classifier's confidence of the category. Number represents how certain + // the classifier is that this category represents the given text. + float confidence = 2; +} + +// The sentiment analysis request message. +message AnalyzeSentimentRequest { + // Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; + + // The encoding type used by the API to calculate sentence offsets. + EncodingType encoding_type = 2; +} + +// The sentiment analysis response message. +message AnalyzeSentimentResponse { + // The overall sentiment of the input document. + Sentiment document_sentiment = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1.Document.language] field for more details. + string language = 2; + + // The sentiment for all the sentences in the document. + repeated Sentence sentences = 3; +} + +// The entity-level sentiment analysis request message. +message AnalyzeEntitySentimentRequest { + // Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The entity-level sentiment analysis response message. +message AnalyzeEntitySentimentResponse { + // The recognized entities in the input document with associated sentiments. + repeated Entity entities = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1.Document.language] field for more details. + string language = 2; +} + +// The entity analysis request message. +message AnalyzeEntitiesRequest { + // Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The entity analysis response message. +message AnalyzeEntitiesResponse { + // The recognized entities in the input document. + repeated Entity entities = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1.Document.language] field for more details. + string language = 2; +} + +// The syntax analysis request message. +message AnalyzeSyntaxRequest { + // Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The syntax analysis response message. +message AnalyzeSyntaxResponse { + // Sentences in the input document. + repeated Sentence sentences = 1; + + // Tokens, along with their syntactic information, in the input document. + repeated Token tokens = 2; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1.Document.language] field for more details. + string language = 3; +} + +// The document classification request message. +message ClassifyTextRequest { + // Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// The document classification response message. +message ClassifyTextResponse { + // Categories representing the input document. + repeated ClassificationCategory categories = 1; +} + +// The request message for the text annotation API, which can perform multiple +// analysis types (sentiment, entities, and syntax) in one call. +message AnnotateTextRequest { + // All available features for sentiment, syntax, and semantic analysis. + // Setting each one to true will enable that specific analysis for the input. + message Features { + // Extract syntax information. + bool extract_syntax = 1; + + // Extract entities. + bool extract_entities = 2; + + // Extract document-level sentiment. + bool extract_document_sentiment = 3; + + // Extract entities and their associated sentiment. + bool extract_entity_sentiment = 4; + + // Classify the full document into categories. + bool classify_text = 6; + } + + // Input document. + Document document = 1 [(google.api.field_behavior) = REQUIRED]; + + // The enabled features. + Features features = 2 [(google.api.field_behavior) = REQUIRED]; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 3; +} + +// The text annotations response message. +message AnnotateTextResponse { + // Sentences in the input document. Populated if the user enables + // [AnnotateTextRequest.Features.extract_syntax][google.cloud.language.v1.AnnotateTextRequest.Features.extract_syntax]. + repeated Sentence sentences = 1; + + // Tokens, along with their syntactic information, in the input document. + // Populated if the user enables + // [AnnotateTextRequest.Features.extract_syntax][google.cloud.language.v1.AnnotateTextRequest.Features.extract_syntax]. + repeated Token tokens = 2; + + // Entities, along with their semantic information, in the input document. + // Populated if the user enables + // [AnnotateTextRequest.Features.extract_entities][google.cloud.language.v1.AnnotateTextRequest.Features.extract_entities]. + repeated Entity entities = 3; + + // The overall sentiment for the document. Populated if the user enables + // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_document_sentiment]. + Sentiment document_sentiment = 4; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1.Document.language] field for more details. + string language = 5; + + // Categories identified in the input document. + repeated ClassificationCategory categories = 6; +} diff --git a/google/cloud/language/v1beta1/language_gapic.yaml b/google/cloud/language/v1beta1/language_gapic.yaml new file mode 100644 index 000000000..63d633a1a --- /dev/null +++ b/google/cloud/language/v1beta1/language_gapic.yaml @@ -0,0 +1,78 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.language.v1beta1 + python: + package_name: google.cloud.language_v1beta1.gapic + go: + package_name: cloud.google.com/go/language/apiv1beta1 + csharp: + package_name: Google.Cloud.Language.V1Beta1 + ruby: + package_name: Google::Cloud::Language::V1beta1 + php: + package_name: Google\Cloud\Language\V1Beta1 + nodejs: + package_name: language.v1beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.language.v1beta1.LanguageService + smoke_test: + method: AnalyzeSentiment + init_fields: + - document.type=PLAIN_TEXT + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + methods: + - name: AnalyzeSentiment + flattening: + groups: + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: AnalyzeEntities + flattening: + groups: + - parameters: + - document + - encoding_type + required_fields: + - document + - encoding_type + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: AnnotateText + flattening: + groups: + - parameters: + - document + - features + - encoding_type + required_fields: + - document + - features + - encoding_type + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 diff --git a/google/cloud/language/v1beta1/language_service.proto b/google/cloud/language/v1beta1/language_service.proto new file mode 100644 index 000000000..1158bb96e --- /dev/null +++ b/google/cloud/language/v1beta1/language_service.proto @@ -0,0 +1,969 @@ +// 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.language.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/language/v1beta1;language"; +option java_multiple_files = true; +option java_outer_classname = "LanguageServiceProto"; +option java_package = "com.google.cloud.language.v1beta1"; + +// Provides text analysis operations such as sentiment analysis and entity +// recognition. +service LanguageService { + // Analyzes the sentiment of the provided text. + rpc AnalyzeSentiment(AnalyzeSentimentRequest) + returns (AnalyzeSentimentResponse) { + option (google.api.http) = { + post: "/v1beta1/documents:analyzeSentiment" + body: "*" + }; + } + + // Finds named entities (currently proper names and common nouns) in the text + // along with entity types, salience, mentions for each entity, and + // other properties. + rpc AnalyzeEntities(AnalyzeEntitiesRequest) + returns (AnalyzeEntitiesResponse) { + option (google.api.http) = { + post: "/v1beta1/documents:analyzeEntities" + body: "*" + }; + } + + // Analyzes the syntax of the text and provides sentence boundaries and + // tokenization along with part of speech tags, dependency trees, and other + // properties. + rpc AnalyzeSyntax(AnalyzeSyntaxRequest) returns (AnalyzeSyntaxResponse) { + option (google.api.http) = { + post: "/v1beta1/documents:analyzeSyntax" + body: "*" + }; + } + + // A convenience method that provides all the features that analyzeSentiment, + // analyzeEntities, and analyzeSyntax provide in one call. + rpc AnnotateText(AnnotateTextRequest) returns (AnnotateTextResponse) { + option (google.api.http) = { + post: "/v1beta1/documents:annotateText" + body: "*" + }; + } +} + +// ################################################################ # +// +// Represents the input to API methods. +message Document { + // The document types enum. + enum Type { + // The content type is not specified. + TYPE_UNSPECIFIED = 0; + + // Plain text + PLAIN_TEXT = 1; + + // HTML + HTML = 2; + } + + // Required. If the type is not set or is `TYPE_UNSPECIFIED`, + // returns an `INVALID_ARGUMENT` error. + Type type = 1; + + // The source of the document: a string containing the content or a + // Google Cloud Storage URI. + oneof source { + // The content of the input in string format. + string content = 2; + + // The Google Cloud Storage URI where the file content is located. + // This URI must be of the form: gs://bucket_name/object_name. For more + // details, see https://cloud.google.com/storage/docs/reference-uris. + // NOTE: Cloud Storage object versioning is not supported. + string gcs_content_uri = 3; + } + + // The language of the document (if not specified, the language is + // automatically detected). Both ISO and BCP-47 language codes are + // accepted.<br> + // [Language + // Support](https://cloud.google.com/natural-language/docs/languages) lists + // currently supported languages for each API method. If the language (either + // specified by the caller or automatically detected) is not supported by the + // called API method, an `INVALID_ARGUMENT` error is returned. + string language = 4; +} + +// Represents a sentence in the input document. +message Sentence { + // The sentence text. + TextSpan text = 1; + + // For calls to [AnalyzeSentiment][] or if + // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1beta1.AnnotateTextRequest.Features.extract_document_sentiment] + // is set to true, this field will contain the sentiment for the sentence. + Sentiment sentiment = 2; +} + +// Represents a phrase in the text that is a known entity, such as +// a person, an organization, or location. The API associates information, such +// as salience and mentions, with entities. +message Entity { + // The type of the entity. + enum Type { + // Unknown + UNKNOWN = 0; + + // Person + PERSON = 1; + + // Location + LOCATION = 2; + + // Organization + ORGANIZATION = 3; + + // Event + EVENT = 4; + + // Work of art + WORK_OF_ART = 5; + + // Consumer goods + CONSUMER_GOOD = 6; + + // Other types + OTHER = 7; + } + + // The representative name for the entity. + string name = 1; + + // The entity type. + Type type = 2; + + // Metadata associated with the entity. + // + // Currently, Wikipedia URLs and Knowledge Graph MIDs are provided, if + // available. The associated keys are "wikipedia_url" and "mid", respectively. + map<string, string> metadata = 3; + + // The salience score associated with the entity in the [0, 1.0] range. + // + // The salience score for an entity provides information about the + // importance or centrality of that entity to the entire document text. + // Scores closer to 0 are less salient, while scores closer to 1.0 are highly + // salient. + float salience = 4; + + // The mentions of this entity in the input document. The API currently + // supports proper noun mentions. + repeated EntityMention mentions = 5; +} + +// Represents the smallest syntactic building block of the text. +message Token { + // The token text. + TextSpan text = 1; + + // Parts of speech tag for this token. + PartOfSpeech part_of_speech = 2; + + // Dependency tree parse for this token. + DependencyEdge dependency_edge = 3; + + // [Lemma](https://en.wikipedia.org/wiki/Lemma_%28morphology%29) of the token. + string lemma = 4; +} + +// Represents the feeling associated with the entire text or entities in +// the text. +message Sentiment { + // DEPRECATED FIELD - This field is being deprecated in + // favor of score. Please refer to our documentation at + // https://cloud.google.com/natural-language/docs for more information. + float polarity = 1; + + // A non-negative number in the [0, +inf) range, which represents + // the absolute magnitude of sentiment regardless of score (positive or + // negative). + float magnitude = 2; + + // Sentiment score between -1.0 (negative sentiment) and 1.0 + // (positive sentiment). + float score = 3; +} + +// Represents part of speech information for a token. +message PartOfSpeech { + // The part of speech tags enum. + enum Tag { + // Unknown + UNKNOWN = 0; + + // Adjective + ADJ = 1; + + // Adposition (preposition and postposition) + ADP = 2; + + // Adverb + ADV = 3; + + // Conjunction + CONJ = 4; + + // Determiner + DET = 5; + + // Noun (common and proper) + NOUN = 6; + + // Cardinal number + NUM = 7; + + // Pronoun + PRON = 8; + + // Particle or other function word + PRT = 9; + + // Punctuation + PUNCT = 10; + + // Verb (all tenses and modes) + VERB = 11; + + // Other: foreign words, typos, abbreviations + X = 12; + + // Affix + AFFIX = 13; + } + + // The characteristic of a verb that expresses time flow during an event. + enum Aspect { + // Aspect is not applicable in the analyzed language or is not predicted. + ASPECT_UNKNOWN = 0; + + // Perfective + PERFECTIVE = 1; + + // Imperfective + IMPERFECTIVE = 2; + + // Progressive + PROGRESSIVE = 3; + } + + // The grammatical function performed by a noun or pronoun in a phrase, + // clause, or sentence. In some languages, other parts of speech, such as + // adjective and determiner, take case inflection in agreement with the noun. + enum Case { + // Case is not applicable in the analyzed language or is not predicted. + CASE_UNKNOWN = 0; + + // Accusative + ACCUSATIVE = 1; + + // Adverbial + ADVERBIAL = 2; + + // Complementive + COMPLEMENTIVE = 3; + + // Dative + DATIVE = 4; + + // Genitive + GENITIVE = 5; + + // Instrumental + INSTRUMENTAL = 6; + + // Locative + LOCATIVE = 7; + + // Nominative + NOMINATIVE = 8; + + // Oblique + OBLIQUE = 9; + + // Partitive + PARTITIVE = 10; + + // Prepositional + PREPOSITIONAL = 11; + + // Reflexive + REFLEXIVE_CASE = 12; + + // Relative + RELATIVE_CASE = 13; + + // Vocative + VOCATIVE = 14; + } + + // Depending on the language, Form can be categorizing different forms of + // verbs, adjectives, adverbs, etc. For example, categorizing inflected + // endings of verbs and adjectives or distinguishing between short and long + // forms of adjectives and participles + enum Form { + // Form is not applicable in the analyzed language or is not predicted. + FORM_UNKNOWN = 0; + + // Adnomial + ADNOMIAL = 1; + + // Auxiliary + AUXILIARY = 2; + + // Complementizer + COMPLEMENTIZER = 3; + + // Final ending + FINAL_ENDING = 4; + + // Gerund + GERUND = 5; + + // Realis + REALIS = 6; + + // Irrealis + IRREALIS = 7; + + // Short form + SHORT = 8; + + // Long form + LONG = 9; + + // Order form + ORDER = 10; + + // Specific form + SPECIFIC = 11; + } + + // Gender classes of nouns reflected in the behaviour of associated words. + enum Gender { + // Gender is not applicable in the analyzed language or is not predicted. + GENDER_UNKNOWN = 0; + + // Feminine + FEMININE = 1; + + // Masculine + MASCULINE = 2; + + // Neuter + NEUTER = 3; + } + + // The grammatical feature of verbs, used for showing modality and attitude. + enum Mood { + // Mood is not applicable in the analyzed language or is not predicted. + MOOD_UNKNOWN = 0; + + // Conditional + CONDITIONAL_MOOD = 1; + + // Imperative + IMPERATIVE = 2; + + // Indicative + INDICATIVE = 3; + + // Interrogative + INTERROGATIVE = 4; + + // Jussive + JUSSIVE = 5; + + // Subjunctive + SUBJUNCTIVE = 6; + } + + // Count distinctions. + enum Number { + // Number is not applicable in the analyzed language or is not predicted. + NUMBER_UNKNOWN = 0; + + // Singular + SINGULAR = 1; + + // Plural + PLURAL = 2; + + // Dual + DUAL = 3; + } + + // The distinction between the speaker, second person, third person, etc. + enum Person { + // Person is not applicable in the analyzed language or is not predicted. + PERSON_UNKNOWN = 0; + + // First + FIRST = 1; + + // Second + SECOND = 2; + + // Third + THIRD = 3; + + // Reflexive + REFLEXIVE_PERSON = 4; + } + + // This category shows if the token is part of a proper name. + enum Proper { + // Proper is not applicable in the analyzed language or is not predicted. + PROPER_UNKNOWN = 0; + + // Proper + PROPER = 1; + + // Not proper + NOT_PROPER = 2; + } + + // Reciprocal features of a pronoun. + enum Reciprocity { + // Reciprocity is not applicable in the analyzed language or is not + // predicted. + RECIPROCITY_UNKNOWN = 0; + + // Reciprocal + RECIPROCAL = 1; + + // Non-reciprocal + NON_RECIPROCAL = 2; + } + + // Time reference. + enum Tense { + // Tense is not applicable in the analyzed language or is not predicted. + TENSE_UNKNOWN = 0; + + // Conditional + CONDITIONAL_TENSE = 1; + + // Future + FUTURE = 2; + + // Past + PAST = 3; + + // Present + PRESENT = 4; + + // Imperfect + IMPERFECT = 5; + + // Pluperfect + PLUPERFECT = 6; + } + + // The relationship between the action that a verb expresses and the + // participants identified by its arguments. + enum Voice { + // Voice is not applicable in the analyzed language or is not predicted. + VOICE_UNKNOWN = 0; + + // Active + ACTIVE = 1; + + // Causative + CAUSATIVE = 2; + + // Passive + PASSIVE = 3; + } + + // The part of speech tag. + Tag tag = 1; + + // The grammatical aspect. + Aspect aspect = 2; + + // The grammatical case. + Case case = 3; + + // The grammatical form. + Form form = 4; + + // The grammatical gender. + Gender gender = 5; + + // The grammatical mood. + Mood mood = 6; + + // The grammatical number. + Number number = 7; + + // The grammatical person. + Person person = 8; + + // The grammatical properness. + Proper proper = 9; + + // The grammatical reciprocity. + Reciprocity reciprocity = 10; + + // The grammatical tense. + Tense tense = 11; + + // The grammatical voice. + Voice voice = 12; +} + +// Represents dependency parse tree information for a token. +message DependencyEdge { + // The parse label enum for the token. + enum Label { + // Unknown + UNKNOWN = 0; + + // Abbreviation modifier + ABBREV = 1; + + // Adjectival complement + ACOMP = 2; + + // Adverbial clause modifier + ADVCL = 3; + + // Adverbial modifier + ADVMOD = 4; + + // Adjectival modifier of an NP + AMOD = 5; + + // Appositional modifier of an NP + APPOS = 6; + + // Attribute dependent of a copular verb + ATTR = 7; + + // Auxiliary (non-main) verb + AUX = 8; + + // Passive auxiliary + AUXPASS = 9; + + // Coordinating conjunction + CC = 10; + + // Clausal complement of a verb or adjective + CCOMP = 11; + + // Conjunct + CONJ = 12; + + // Clausal subject + CSUBJ = 13; + + // Clausal passive subject + CSUBJPASS = 14; + + // Dependency (unable to determine) + DEP = 15; + + // Determiner + DET = 16; + + // Discourse + DISCOURSE = 17; + + // Direct object + DOBJ = 18; + + // Expletive + EXPL = 19; + + // Goes with (part of a word in a text not well edited) + GOESWITH = 20; + + // Indirect object + IOBJ = 21; + + // Marker (word introducing a subordinate clause) + MARK = 22; + + // Multi-word expression + MWE = 23; + + // Multi-word verbal expression + MWV = 24; + + // Negation modifier + NEG = 25; + + // Noun compound modifier + NN = 26; + + // Noun phrase used as an adverbial modifier + NPADVMOD = 27; + + // Nominal subject + NSUBJ = 28; + + // Passive nominal subject + NSUBJPASS = 29; + + // Numeric modifier of a noun + NUM = 30; + + // Element of compound number + NUMBER = 31; + + // Punctuation mark + P = 32; + + // Parataxis relation + PARATAXIS = 33; + + // Participial modifier + PARTMOD = 34; + + // The complement of a preposition is a clause + PCOMP = 35; + + // Object of a preposition + POBJ = 36; + + // Possession modifier + POSS = 37; + + // Postverbal negative particle + POSTNEG = 38; + + // Predicate complement + PRECOMP = 39; + + // Preconjunt + PRECONJ = 40; + + // Predeterminer + PREDET = 41; + + // Prefix + PREF = 42; + + // Prepositional modifier + PREP = 43; + + // The relationship between a verb and verbal morpheme + PRONL = 44; + + // Particle + PRT = 45; + + // Associative or possessive marker + PS = 46; + + // Quantifier phrase modifier + QUANTMOD = 47; + + // Relative clause modifier + RCMOD = 48; + + // Complementizer in relative clause + RCMODREL = 49; + + // Ellipsis without a preceding predicate + RDROP = 50; + + // Referent + REF = 51; + + // Remnant + REMNANT = 52; + + // Reparandum + REPARANDUM = 53; + + // Root + ROOT = 54; + + // Suffix specifying a unit of number + SNUM = 55; + + // Suffix + SUFF = 56; + + // Temporal modifier + TMOD = 57; + + // Topic marker + TOPIC = 58; + + // Clause headed by an infinite form of the verb that modifies a noun + VMOD = 59; + + // Vocative + VOCATIVE = 60; + + // Open clausal complement + XCOMP = 61; + + // Name suffix + SUFFIX = 62; + + // Name title + TITLE = 63; + + // Adverbial phrase modifier + ADVPHMOD = 64; + + // Causative auxiliary + AUXCAUS = 65; + + // Helper auxiliary + AUXVV = 66; + + // Rentaishi (Prenominal modifier) + DTMOD = 67; + + // Foreign words + FOREIGN = 68; + + // Keyword + KW = 69; + + // List for chains of comparable items + LIST = 70; + + // Nominalized clause + NOMC = 71; + + // Nominalized clausal subject + NOMCSUBJ = 72; + + // Nominalized clausal passive + NOMCSUBJPASS = 73; + + // Compound of numeric modifier + NUMC = 74; + + // Copula + COP = 75; + + // Dislocated relation (for fronted/topicalized elements) + DISLOCATED = 76; + } + + // Represents the head of this token in the dependency tree. + // This is the index of the token which has an arc going to this token. + // The index is the position of the token in the array of tokens returned + // by the API method. If this token is a root token, then the + // `head_token_index` is its own index. + int32 head_token_index = 1; + + // The parse label for the token. + Label label = 2; +} + +// Represents a mention for an entity in the text. Currently, proper noun +// mentions are supported. +message EntityMention { + // The supported types of mentions. + enum Type { + // Unknown + TYPE_UNKNOWN = 0; + + // Proper name + PROPER = 1; + + // Common noun (or noun compound) + COMMON = 2; + } + + // The mention text. + TextSpan text = 1; + + // The type of the entity mention. + Type type = 2; +} + +// Represents an output piece of text. +message TextSpan { + // The content of the output text. + string content = 1; + + // The API calculates the beginning offset of the content in the original + // document according to the + // [EncodingType][google.cloud.language.v1beta1.EncodingType] specified in the + // API request. + int32 begin_offset = 2; +} + +// The sentiment analysis request message. +message AnalyzeSentimentRequest { + // Input document. + Document document = 1; + + // The encoding type used by the API to calculate sentence offsets for the + // sentence sentiment. + EncodingType encoding_type = 2; +} + +// The sentiment analysis response message. +message AnalyzeSentimentResponse { + // The overall sentiment of the input document. + Sentiment document_sentiment = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta1.Document.language] + // field for more details. + string language = 2; + + // The sentiment for all the sentences in the document. + repeated Sentence sentences = 3; +} + +// The entity analysis request message. +message AnalyzeEntitiesRequest { + // Input document. + Document document = 1; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The entity analysis response message. +message AnalyzeEntitiesResponse { + // The recognized entities in the input document. + repeated Entity entities = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta1.Document.language] + // field for more details. + string language = 2; +} + +// The syntax analysis request message. +message AnalyzeSyntaxRequest { + // Input document. + Document document = 1; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The syntax analysis response message. +message AnalyzeSyntaxResponse { + // Sentences in the input document. + repeated Sentence sentences = 1; + + // Tokens, along with their syntactic information, in the input document. + repeated Token tokens = 2; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta1.Document.language] + // field for more details. + string language = 3; +} + +// The request message for the text annotation API, which can perform multiple +// analysis types (sentiment, entities, and syntax) in one call. +message AnnotateTextRequest { + // All available features for sentiment, syntax, and semantic analysis. + // Setting each one to true will enable that specific analysis for the input. + message Features { + // Extract syntax information. + bool extract_syntax = 1; + + // Extract entities. + bool extract_entities = 2; + + // Extract document-level sentiment. + bool extract_document_sentiment = 3; + } + + // Input document. + Document document = 1; + + // The enabled features. + Features features = 2; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 3; +} + +// The text annotations response message. +message AnnotateTextResponse { + // Sentences in the input document. Populated if the user enables + // [AnnotateTextRequest.Features.extract_syntax][google.cloud.language.v1beta1.AnnotateTextRequest.Features.extract_syntax]. + repeated Sentence sentences = 1; + + // Tokens, along with their syntactic information, in the input document. + // Populated if the user enables + // [AnnotateTextRequest.Features.extract_syntax][google.cloud.language.v1beta1.AnnotateTextRequest.Features.extract_syntax]. + repeated Token tokens = 2; + + // Entities, along with their semantic information, in the input document. + // Populated if the user enables + // [AnnotateTextRequest.Features.extract_entities][google.cloud.language.v1beta1.AnnotateTextRequest.Features.extract_entities]. + repeated Entity entities = 3; + + // The overall sentiment for the document. Populated if the user enables + // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1beta1.AnnotateTextRequest.Features.extract_document_sentiment]. + Sentiment document_sentiment = 4; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta1.Document.language] + // field for more details. + string language = 5; +} + +// Represents the text encoding that the caller uses to process the output. +// Providing an `EncodingType` is recommended because the API provides the +// beginning offsets for various outputs, such as tokens and mentions, and +// languages that natively use different text encodings may access offsets +// differently. +enum EncodingType { + // If `EncodingType` is not specified, encoding-dependent information (such as + // `begin_offset`) will be set at `-1`. + NONE = 0; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-8 encoding of the input. C++ and Go are examples of languages + // that use this encoding natively. + UTF8 = 1; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-16 encoding of the input. Java and Javascript are examples of + // languages that use this encoding natively. + UTF16 = 2; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-32 encoding of the input. Python is an example of a language + // that uses this encoding natively. + UTF32 = 3; +} diff --git a/google/cloud/language/v1beta2/BUILD.bazel b/google/cloud/language/v1beta2/BUILD.bazel new file mode 100644 index 000000000..fff77964e --- /dev/null +++ b/google/cloud/language/v1beta2/BUILD.bazel @@ -0,0 +1,124 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "language_proto", + srcs = ["language_service.proto"], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "language_proto_with_info", + deps = [":language_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", "java_gapic_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "language_java_proto", + deps = [":language_proto"], +) + +java_grpc_library( + name = "language_java_grpc", + srcs = [":language_proto"], + deps = [":language_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_gapic_library( + name = "language_java_gapic", + src = ":language_proto_with_info", + gapic_yaml = "language_gapic.yaml", + service_yaml = "//google/cloud/language:language_v1beta2.yaml", + test_deps = [":language_java_grpc"], + deps = [":language_java_proto"] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":language_java_gapic_test"], +) for test_name in [ + "com.google.cloud.language.v1beta2.LanguageServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-language-v1beta2-java", + client_deps = [":language_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":language_java_gapic_test"], + grpc_deps = [":language_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":language_java_proto", + ":language_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "language_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/language/v1beta2", + protos = [":language_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "language_go_gapic", + src = ":language_proto_with_info", + gapic_yaml = "language_gapic.yaml", + importpath = "cloud.google.com/go/language/apiv1beta2", + service_yaml = "//google/cloud/language:language_v1beta2.yaml", + deps = [":language_go_proto"], +) + +go_test( + name = "language_go_gapic_test", + srcs = [":language_go_gapic_srcjar_test"], + embed = [":language_go_gapic"], + importpath = "cloud.google.com/go/language/apiv1beta2", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-language-v1beta2-go", + deps = [ + ":language_go_gapic", + ":language_go_gapic_srcjar-smoke-test.srcjar", + ":language_go_gapic_srcjar-test.srcjar", + ":language_go_proto", + ], +) diff --git a/google/cloud/language/v1beta2/language_gapic.yaml b/google/cloud/language/v1beta2/language_gapic.yaml new file mode 100644 index 000000000..7fcf68f14 --- /dev/null +++ b/google/cloud/language/v1beta2/language_gapic.yaml @@ -0,0 +1,109 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.language.v1beta2 + python: + package_name: google.cloud.language_v1beta2.gapic + go: + package_name: cloud.google.com/go/language/apiv1beta2 + csharp: + package_name: Google.Cloud.Language.V1Beta2 + ruby: + package_name: Google::Cloud::Language::V1beta2 + php: + package_name: Google\Cloud\Language\V1beta2 + nodejs: + package_name: language.v1beta2 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.language.v1beta2.LanguageService + smoke_test: + method: AnalyzeSentiment + init_fields: + - document.content="Hello, world!" + - document.type=PLAIN_TEXT + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + methods: + - name: AnalyzeSentiment + flattening: + groups: + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: AnalyzeEntities + flattening: + groups: + - parameters: + - document + - encoding_type + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: AnalyzeEntitySentiment + flattening: + groups: + - parameters: + - document + - encoding_type + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: AnalyzeSyntax + flattening: + groups: + - parameters: + - document + - encoding_type + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: ClassifyText + flattening: + groups: + - parameters: + - document + required_fields: + - document + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: AnnotateText + flattening: + groups: + - parameters: + - document + - features + - encoding_type + required_fields: + - document + - features + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 diff --git a/google/cloud/language/v1beta2/language_service.proto b/google/cloud/language/v1beta2/language_service.proto new file mode 100644 index 000000000..0263be04a --- /dev/null +++ b/google/cloud/language/v1beta2/language_service.proto @@ -0,0 +1,1069 @@ +// 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.language.v1beta2; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/language/v1beta2;language"; +option java_multiple_files = true; +option java_outer_classname = "LanguageServiceProto"; +option java_package = "com.google.cloud.language.v1beta2"; + +// Provides text analysis operations such as sentiment analysis and entity +// recognition. +service LanguageService { + // Analyzes the sentiment of the provided text. + rpc AnalyzeSentiment(AnalyzeSentimentRequest) + returns (AnalyzeSentimentResponse) { + option (google.api.http) = { + post: "/v1beta2/documents:analyzeSentiment" + body: "*" + }; + } + + // Finds named entities (currently proper names and common nouns) in the text + // along with entity types, salience, mentions for each entity, and + // other properties. + rpc AnalyzeEntities(AnalyzeEntitiesRequest) + returns (AnalyzeEntitiesResponse) { + option (google.api.http) = { + post: "/v1beta2/documents:analyzeEntities" + body: "*" + }; + } + + // Finds entities, similar to + // [AnalyzeEntities][google.cloud.language.v1beta2.LanguageService.AnalyzeEntities] + // in the text and analyzes sentiment associated with each entity and its + // mentions. + rpc AnalyzeEntitySentiment(AnalyzeEntitySentimentRequest) + returns (AnalyzeEntitySentimentResponse) { + option (google.api.http) = { + post: "/v1beta2/documents:analyzeEntitySentiment" + body: "*" + }; + } + + // Analyzes the syntax of the text and provides sentence boundaries and + // tokenization along with part of speech tags, dependency trees, and other + // properties. + rpc AnalyzeSyntax(AnalyzeSyntaxRequest) returns (AnalyzeSyntaxResponse) { + option (google.api.http) = { + post: "/v1beta2/documents:analyzeSyntax" + body: "*" + }; + } + + // Classifies a document into categories. + rpc ClassifyText(ClassifyTextRequest) returns (ClassifyTextResponse) { + option (google.api.http) = { + post: "/v1beta2/documents:classifyText" + body: "*" + }; + } + + // A convenience method that provides all syntax, sentiment, entity, and + // classification features in one call. + rpc AnnotateText(AnnotateTextRequest) returns (AnnotateTextResponse) { + option (google.api.http) = { + post: "/v1beta2/documents:annotateText" + body: "*" + }; + } +} + +// ################################################################ # +// +// Represents the input to API methods. +message Document { + // The document types enum. + enum Type { + // The content type is not specified. + TYPE_UNSPECIFIED = 0; + + // Plain text + PLAIN_TEXT = 1; + + // HTML + HTML = 2; + } + + // Required. If the type is not set or is `TYPE_UNSPECIFIED`, + // returns an `INVALID_ARGUMENT` error. + Type type = 1; + + // The source of the document: a string containing the content or a + // Google Cloud Storage URI. + oneof source { + // The content of the input in string format. + string content = 2; + + // The Google Cloud Storage URI where the file content is located. + // This URI must be of the form: gs://bucket_name/object_name. For more + // details, see https://cloud.google.com/storage/docs/reference-uris. + // NOTE: Cloud Storage object versioning is not supported. + string gcs_content_uri = 3; + } + + // The language of the document (if not specified, the language is + // automatically detected). Both ISO and BCP-47 language codes are + // accepted.<br> + // [Language Support](/natural-language/docs/languages) + // lists currently supported languages for each API method. + // If the language (either specified by the caller or automatically detected) + // is not supported by the called API method, an `INVALID_ARGUMENT` error + // is returned. + string language = 4; +} + +// Represents a sentence in the input document. +message Sentence { + // The sentence text. + TextSpan text = 1; + + // For calls to [AnalyzeSentiment][] or if + // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_document_sentiment] + // is set to true, this field will contain the sentiment for the sentence. + Sentiment sentiment = 2; +} + +// Represents a phrase in the text that is a known entity, such as +// a person, an organization, or location. The API associates information, such +// as salience and mentions, with entities. +message Entity { + // The type of the entity. + enum Type { + // Unknown + UNKNOWN = 0; + + // Person + PERSON = 1; + + // Location + LOCATION = 2; + + // Organization + ORGANIZATION = 3; + + // Event + EVENT = 4; + + // Work of art + WORK_OF_ART = 5; + + // Consumer goods + CONSUMER_GOOD = 6; + + // Other types + OTHER = 7; + } + + // The representative name for the entity. + string name = 1; + + // The entity type. + Type type = 2; + + // Metadata associated with the entity. + // + // Currently, Wikipedia URLs and Knowledge Graph MIDs are provided, if + // available. The associated keys are "wikipedia_url" and "mid", respectively. + map<string, string> metadata = 3; + + // The salience score associated with the entity in the [0, 1.0] range. + // + // The salience score for an entity provides information about the + // importance or centrality of that entity to the entire document text. + // Scores closer to 0 are less salient, while scores closer to 1.0 are highly + // salient. + float salience = 4; + + // The mentions of this entity in the input document. The API currently + // supports proper noun mentions. + repeated EntityMention mentions = 5; + + // For calls to [AnalyzeEntitySentiment][] or if + // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_entity_sentiment] + // is set to true, this field will contain the aggregate sentiment expressed + // for this entity in the provided document. + Sentiment sentiment = 6; +} + +// Represents the smallest syntactic building block of the text. +message Token { + // The token text. + TextSpan text = 1; + + // Parts of speech tag for this token. + PartOfSpeech part_of_speech = 2; + + // Dependency tree parse for this token. + DependencyEdge dependency_edge = 3; + + // [Lemma](https://en.wikipedia.org/wiki/Lemma_%28morphology%29) of the token. + string lemma = 4; +} + +// Represents the feeling associated with the entire text or entities in +// the text. +message Sentiment { + // A non-negative number in the [0, +inf) range, which represents + // the absolute magnitude of sentiment regardless of score (positive or + // negative). + float magnitude = 2; + + // Sentiment score between -1.0 (negative sentiment) and 1.0 + // (positive sentiment). + float score = 3; +} + +// Represents part of speech information for a token. +message PartOfSpeech { + // The part of speech tags enum. + enum Tag { + // Unknown + UNKNOWN = 0; + + // Adjective + ADJ = 1; + + // Adposition (preposition and postposition) + ADP = 2; + + // Adverb + ADV = 3; + + // Conjunction + CONJ = 4; + + // Determiner + DET = 5; + + // Noun (common and proper) + NOUN = 6; + + // Cardinal number + NUM = 7; + + // Pronoun + PRON = 8; + + // Particle or other function word + PRT = 9; + + // Punctuation + PUNCT = 10; + + // Verb (all tenses and modes) + VERB = 11; + + // Other: foreign words, typos, abbreviations + X = 12; + + // Affix + AFFIX = 13; + } + + // The characteristic of a verb that expresses time flow during an event. + enum Aspect { + // Aspect is not applicable in the analyzed language or is not predicted. + ASPECT_UNKNOWN = 0; + + // Perfective + PERFECTIVE = 1; + + // Imperfective + IMPERFECTIVE = 2; + + // Progressive + PROGRESSIVE = 3; + } + + // The grammatical function performed by a noun or pronoun in a phrase, + // clause, or sentence. In some languages, other parts of speech, such as + // adjective and determiner, take case inflection in agreement with the noun. + enum Case { + // Case is not applicable in the analyzed language or is not predicted. + CASE_UNKNOWN = 0; + + // Accusative + ACCUSATIVE = 1; + + // Adverbial + ADVERBIAL = 2; + + // Complementive + COMPLEMENTIVE = 3; + + // Dative + DATIVE = 4; + + // Genitive + GENITIVE = 5; + + // Instrumental + INSTRUMENTAL = 6; + + // Locative + LOCATIVE = 7; + + // Nominative + NOMINATIVE = 8; + + // Oblique + OBLIQUE = 9; + + // Partitive + PARTITIVE = 10; + + // Prepositional + PREPOSITIONAL = 11; + + // Reflexive + REFLEXIVE_CASE = 12; + + // Relative + RELATIVE_CASE = 13; + + // Vocative + VOCATIVE = 14; + } + + // Depending on the language, Form can be categorizing different forms of + // verbs, adjectives, adverbs, etc. For example, categorizing inflected + // endings of verbs and adjectives or distinguishing between short and long + // forms of adjectives and participles + enum Form { + // Form is not applicable in the analyzed language or is not predicted. + FORM_UNKNOWN = 0; + + // Adnomial + ADNOMIAL = 1; + + // Auxiliary + AUXILIARY = 2; + + // Complementizer + COMPLEMENTIZER = 3; + + // Final ending + FINAL_ENDING = 4; + + // Gerund + GERUND = 5; + + // Realis + REALIS = 6; + + // Irrealis + IRREALIS = 7; + + // Short form + SHORT = 8; + + // Long form + LONG = 9; + + // Order form + ORDER = 10; + + // Specific form + SPECIFIC = 11; + } + + // Gender classes of nouns reflected in the behaviour of associated words. + enum Gender { + // Gender is not applicable in the analyzed language or is not predicted. + GENDER_UNKNOWN = 0; + + // Feminine + FEMININE = 1; + + // Masculine + MASCULINE = 2; + + // Neuter + NEUTER = 3; + } + + // The grammatical feature of verbs, used for showing modality and attitude. + enum Mood { + // Mood is not applicable in the analyzed language or is not predicted. + MOOD_UNKNOWN = 0; + + // Conditional + CONDITIONAL_MOOD = 1; + + // Imperative + IMPERATIVE = 2; + + // Indicative + INDICATIVE = 3; + + // Interrogative + INTERROGATIVE = 4; + + // Jussive + JUSSIVE = 5; + + // Subjunctive + SUBJUNCTIVE = 6; + } + + // Count distinctions. + enum Number { + // Number is not applicable in the analyzed language or is not predicted. + NUMBER_UNKNOWN = 0; + + // Singular + SINGULAR = 1; + + // Plural + PLURAL = 2; + + // Dual + DUAL = 3; + } + + // The distinction between the speaker, second person, third person, etc. + enum Person { + // Person is not applicable in the analyzed language or is not predicted. + PERSON_UNKNOWN = 0; + + // First + FIRST = 1; + + // Second + SECOND = 2; + + // Third + THIRD = 3; + + // Reflexive + REFLEXIVE_PERSON = 4; + } + + // This category shows if the token is part of a proper name. + enum Proper { + // Proper is not applicable in the analyzed language or is not predicted. + PROPER_UNKNOWN = 0; + + // Proper + PROPER = 1; + + // Not proper + NOT_PROPER = 2; + } + + // Reciprocal features of a pronoun. + enum Reciprocity { + // Reciprocity is not applicable in the analyzed language or is not + // predicted. + RECIPROCITY_UNKNOWN = 0; + + // Reciprocal + RECIPROCAL = 1; + + // Non-reciprocal + NON_RECIPROCAL = 2; + } + + // Time reference. + enum Tense { + // Tense is not applicable in the analyzed language or is not predicted. + TENSE_UNKNOWN = 0; + + // Conditional + CONDITIONAL_TENSE = 1; + + // Future + FUTURE = 2; + + // Past + PAST = 3; + + // Present + PRESENT = 4; + + // Imperfect + IMPERFECT = 5; + + // Pluperfect + PLUPERFECT = 6; + } + + // The relationship between the action that a verb expresses and the + // participants identified by its arguments. + enum Voice { + // Voice is not applicable in the analyzed language or is not predicted. + VOICE_UNKNOWN = 0; + + // Active + ACTIVE = 1; + + // Causative + CAUSATIVE = 2; + + // Passive + PASSIVE = 3; + } + + // The part of speech tag. + Tag tag = 1; + + // The grammatical aspect. + Aspect aspect = 2; + + // The grammatical case. + Case case = 3; + + // The grammatical form. + Form form = 4; + + // The grammatical gender. + Gender gender = 5; + + // The grammatical mood. + Mood mood = 6; + + // The grammatical number. + Number number = 7; + + // The grammatical person. + Person person = 8; + + // The grammatical properness. + Proper proper = 9; + + // The grammatical reciprocity. + Reciprocity reciprocity = 10; + + // The grammatical tense. + Tense tense = 11; + + // The grammatical voice. + Voice voice = 12; +} + +// Represents dependency parse tree information for a token. +message DependencyEdge { + // The parse label enum for the token. + enum Label { + // Unknown + UNKNOWN = 0; + + // Abbreviation modifier + ABBREV = 1; + + // Adjectival complement + ACOMP = 2; + + // Adverbial clause modifier + ADVCL = 3; + + // Adverbial modifier + ADVMOD = 4; + + // Adjectival modifier of an NP + AMOD = 5; + + // Appositional modifier of an NP + APPOS = 6; + + // Attribute dependent of a copular verb + ATTR = 7; + + // Auxiliary (non-main) verb + AUX = 8; + + // Passive auxiliary + AUXPASS = 9; + + // Coordinating conjunction + CC = 10; + + // Clausal complement of a verb or adjective + CCOMP = 11; + + // Conjunct + CONJ = 12; + + // Clausal subject + CSUBJ = 13; + + // Clausal passive subject + CSUBJPASS = 14; + + // Dependency (unable to determine) + DEP = 15; + + // Determiner + DET = 16; + + // Discourse + DISCOURSE = 17; + + // Direct object + DOBJ = 18; + + // Expletive + EXPL = 19; + + // Goes with (part of a word in a text not well edited) + GOESWITH = 20; + + // Indirect object + IOBJ = 21; + + // Marker (word introducing a subordinate clause) + MARK = 22; + + // Multi-word expression + MWE = 23; + + // Multi-word verbal expression + MWV = 24; + + // Negation modifier + NEG = 25; + + // Noun compound modifier + NN = 26; + + // Noun phrase used as an adverbial modifier + NPADVMOD = 27; + + // Nominal subject + NSUBJ = 28; + + // Passive nominal subject + NSUBJPASS = 29; + + // Numeric modifier of a noun + NUM = 30; + + // Element of compound number + NUMBER = 31; + + // Punctuation mark + P = 32; + + // Parataxis relation + PARATAXIS = 33; + + // Participial modifier + PARTMOD = 34; + + // The complement of a preposition is a clause + PCOMP = 35; + + // Object of a preposition + POBJ = 36; + + // Possession modifier + POSS = 37; + + // Postverbal negative particle + POSTNEG = 38; + + // Predicate complement + PRECOMP = 39; + + // Preconjunt + PRECONJ = 40; + + // Predeterminer + PREDET = 41; + + // Prefix + PREF = 42; + + // Prepositional modifier + PREP = 43; + + // The relationship between a verb and verbal morpheme + PRONL = 44; + + // Particle + PRT = 45; + + // Associative or possessive marker + PS = 46; + + // Quantifier phrase modifier + QUANTMOD = 47; + + // Relative clause modifier + RCMOD = 48; + + // Complementizer in relative clause + RCMODREL = 49; + + // Ellipsis without a preceding predicate + RDROP = 50; + + // Referent + REF = 51; + + // Remnant + REMNANT = 52; + + // Reparandum + REPARANDUM = 53; + + // Root + ROOT = 54; + + // Suffix specifying a unit of number + SNUM = 55; + + // Suffix + SUFF = 56; + + // Temporal modifier + TMOD = 57; + + // Topic marker + TOPIC = 58; + + // Clause headed by an infinite form of the verb that modifies a noun + VMOD = 59; + + // Vocative + VOCATIVE = 60; + + // Open clausal complement + XCOMP = 61; + + // Name suffix + SUFFIX = 62; + + // Name title + TITLE = 63; + + // Adverbial phrase modifier + ADVPHMOD = 64; + + // Causative auxiliary + AUXCAUS = 65; + + // Helper auxiliary + AUXVV = 66; + + // Rentaishi (Prenominal modifier) + DTMOD = 67; + + // Foreign words + FOREIGN = 68; + + // Keyword + KW = 69; + + // List for chains of comparable items + LIST = 70; + + // Nominalized clause + NOMC = 71; + + // Nominalized clausal subject + NOMCSUBJ = 72; + + // Nominalized clausal passive + NOMCSUBJPASS = 73; + + // Compound of numeric modifier + NUMC = 74; + + // Copula + COP = 75; + + // Dislocated relation (for fronted/topicalized elements) + DISLOCATED = 76; + + // Aspect marker + ASP = 77; + + // Genitive modifier + GMOD = 78; + + // Genitive object + GOBJ = 79; + + // Infinitival modifier + INFMOD = 80; + + // Measure + MES = 81; + + // Nominal complement of a noun + NCOMP = 82; + } + + // Represents the head of this token in the dependency tree. + // This is the index of the token which has an arc going to this token. + // The index is the position of the token in the array of tokens returned + // by the API method. If this token is a root token, then the + // `head_token_index` is its own index. + int32 head_token_index = 1; + + // The parse label for the token. + Label label = 2; +} + +// Represents a mention for an entity in the text. Currently, proper noun +// mentions are supported. +message EntityMention { + // The supported types of mentions. + enum Type { + // Unknown + TYPE_UNKNOWN = 0; + + // Proper name + PROPER = 1; + + // Common noun (or noun compound) + COMMON = 2; + } + + // The mention text. + TextSpan text = 1; + + // The type of the entity mention. + Type type = 2; + + // For calls to [AnalyzeEntitySentiment][] or if + // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_entity_sentiment] + // is set to true, this field will contain the sentiment expressed for this + // mention of the entity in the provided document. + Sentiment sentiment = 3; +} + +// Represents an output piece of text. +message TextSpan { + // The content of the output text. + string content = 1; + + // The API calculates the beginning offset of the content in the original + // document according to the + // [EncodingType][google.cloud.language.v1beta2.EncodingType] specified in the + // API request. + int32 begin_offset = 2; +} + +// Represents a category returned from the text classifier. +message ClassificationCategory { + // The name of the category representing the document. + string name = 1; + + // The classifier's confidence of the category. Number represents how certain + // the classifier is that this category represents the given text. + float confidence = 2; +} + +// The sentiment analysis request message. +message AnalyzeSentimentRequest { + // Input document. + Document document = 1; + + // The encoding type used by the API to calculate sentence offsets for the + // sentence sentiment. + EncodingType encoding_type = 2; +} + +// The sentiment analysis response message. +message AnalyzeSentimentResponse { + // The overall sentiment of the input document. + Sentiment document_sentiment = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta2.Document.language] + // field for more details. + string language = 2; + + // The sentiment for all the sentences in the document. + repeated Sentence sentences = 3; +} + +// The entity-level sentiment analysis request message. +message AnalyzeEntitySentimentRequest { + // Input document. + Document document = 1; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The entity-level sentiment analysis response message. +message AnalyzeEntitySentimentResponse { + // The recognized entities in the input document with associated sentiments. + repeated Entity entities = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta2.Document.language] + // field for more details. + string language = 2; +} + +// The entity analysis request message. +message AnalyzeEntitiesRequest { + // Input document. + Document document = 1; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The entity analysis response message. +message AnalyzeEntitiesResponse { + // The recognized entities in the input document. + repeated Entity entities = 1; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta2.Document.language] + // field for more details. + string language = 2; +} + +// The syntax analysis request message. +message AnalyzeSyntaxRequest { + // Input document. + Document document = 1; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 2; +} + +// The syntax analysis response message. +message AnalyzeSyntaxResponse { + // Sentences in the input document. + repeated Sentence sentences = 1; + + // Tokens, along with their syntactic information, in the input document. + repeated Token tokens = 2; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta2.Document.language] + // field for more details. + string language = 3; +} + +// The document classification request message. +message ClassifyTextRequest { + // Input document. + Document document = 1; +} + +// The document classification response message. +message ClassifyTextResponse { + // Categories representing the input document. + repeated ClassificationCategory categories = 1; +} + +// The request message for the text annotation API, which can perform multiple +// analysis types (sentiment, entities, and syntax) in one call. +message AnnotateTextRequest { + // All available features for sentiment, syntax, and semantic analysis. + // Setting each one to true will enable that specific analysis for the input. + message Features { + // Extract syntax information. + bool extract_syntax = 1; + + // Extract entities. + bool extract_entities = 2; + + // Extract document-level sentiment. + bool extract_document_sentiment = 3; + + // Extract entities and their associated sentiment. + bool extract_entity_sentiment = 4; + + // Classify the full document into categories. + bool classify_text = 6; + } + + // Input document. + Document document = 1; + + // The enabled features. + Features features = 2; + + // The encoding type used by the API to calculate offsets. + EncodingType encoding_type = 3; +} + +// The text annotations response message. +message AnnotateTextResponse { + // Sentences in the input document. Populated if the user enables + // [AnnotateTextRequest.Features.extract_syntax][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_syntax]. + repeated Sentence sentences = 1; + + // Tokens, along with their syntactic information, in the input document. + // Populated if the user enables + // [AnnotateTextRequest.Features.extract_syntax][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_syntax]. + repeated Token tokens = 2; + + // Entities, along with their semantic information, in the input document. + // Populated if the user enables + // [AnnotateTextRequest.Features.extract_entities][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_entities]. + repeated Entity entities = 3; + + // The overall sentiment for the document. Populated if the user enables + // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1beta2.AnnotateTextRequest.Features.extract_document_sentiment]. + Sentiment document_sentiment = 4; + + // The language of the text, which will be the same as the language specified + // in the request or, if not specified, the automatically-detected language. + // See [Document.language][google.cloud.language.v1beta2.Document.language] + // field for more details. + string language = 5; + + // Categories identified in the input document. + repeated ClassificationCategory categories = 6; +} + +// Represents the text encoding that the caller uses to process the output. +// Providing an `EncodingType` is recommended because the API provides the +// beginning offsets for various outputs, such as tokens and mentions, and +// languages that natively use different text encodings may access offsets +// differently. +enum EncodingType { + // If `EncodingType` is not specified, encoding-dependent information (such as + // `begin_offset`) will be set at `-1`. + NONE = 0; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-8 encoding of the input. C++ and Go are examples of languages + // that use this encoding natively. + UTF8 = 1; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-16 encoding of the input. Java and Javascript are examples of + // languages that use this encoding natively. + UTF16 = 2; + + // Encoding-dependent information (such as `begin_offset`) is calculated based + // on the UTF-32 encoding of the input. Python is an example of a language + // that uses this encoding natively. + UTF32 = 3; +} diff --git a/google/cloud/location/location.yaml b/google/cloud/location/location.yaml new file mode 100644 index 000000000..901d8764c --- /dev/null +++ b/google/cloud/location/location.yaml @@ -0,0 +1,15 @@ +type: google.api.Service +config_version: 1 +name: cloudlocations.googleapis.com +title: Cloud Location API + +apis: +- name: google.cloud.location.Locations + +documentation: + overview: |- + # Google Cloud Locations API + + This package contains the definition of an abstract interface that manages + locations within API services. See + cs/symbol:google.cloud.location.Locations for details. diff --git a/google/cloud/location/locations.proto b/google/cloud/location/locations.proto new file mode 100644 index 000000000..03f327268 --- /dev/null +++ b/google/cloud/location/locations.proto @@ -0,0 +1,101 @@ +// Copyright 2018 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.location; + +import "google/api/annotations.proto"; +import "google/protobuf/any.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/location;location"; +option java_multiple_files = true; +option java_outer_classname = "LocationsProto"; +option java_package = "com.google.cloud.location"; + +// An abstract interface that provides location-related information for +// a service. Service-specific metadata is provided through the +// [Location.metadata][google.cloud.location.Location.metadata] field. +service Locations { + // Lists information about the supported locations for this service. + rpc ListLocations(ListLocationsRequest) returns (ListLocationsResponse) { + option (google.api.http) = { + get: "/v1/{name=projects/*}/locations" + }; + } + + // Gets information about a location. + rpc GetLocation(GetLocationRequest) returns (Location) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*}" + }; + } +} + +// The request message for +// [Locations.ListLocations][google.cloud.location.Locations.ListLocations]. +message ListLocationsRequest { + // The resource that owns the locations collection, if applicable. + string name = 1; + + // The standard list filter. + string filter = 2; + + // The standard list page size. + int32 page_size = 3; + + // The standard list page token. + string page_token = 4; +} + +// The response message for +// [Locations.ListLocations][google.cloud.location.Locations.ListLocations]. +message ListLocationsResponse { + // A list of locations that matches the specified filter in the request. + repeated Location locations = 1; + + // The standard List next-page token. + string next_page_token = 2; +} + +// The request message for +// [Locations.GetLocation][google.cloud.location.Locations.GetLocation]. +message GetLocationRequest { + // Resource name for the location. + string name = 1; +} + +// A resource that represents Google Cloud Platform location. +message Location { + // Resource name for the location, which may vary between implementations. + // For example: `"projects/example-project/locations/us-east1"` + string name = 1; + + // The canonical id for this location. For example: `"us-east1"`. + string location_id = 4; + + // The friendly name for this location, typically a nearby city name. + // For example, "Tokyo". + string display_name = 5; + + // Cross-service attributes for the location. For example + // + // {"cloud.googleapis.com/region": "us-east1"} + map<string, string> labels = 2; + + // Service-specific metadata. For example the available capacity at the given + // location. + google.protobuf.Any metadata = 3; +} diff --git a/google/cloud/ml/v1/job_service.proto b/google/cloud/ml/v1/job_service.proto new file mode 100644 index 000000000..d1f608941 --- /dev/null +++ b/google/cloud/ml/v1/job_service.proto @@ -0,0 +1,613 @@ +// 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.ml.v1; + +import "google/api/annotations.proto"; +import "google/api/auth.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml"; +option java_multiple_files = true; +option java_outer_classname = "JobServiceProto"; +option java_package = "com.google.cloud.ml.api.v1"; + +// Copyright 2017 Google Inc. All Rights Reserved. +// +// Proto file for the Google Cloud Machine Learning Engine. +// Describes the 'job service' to manage training and prediction jobs. + +// Service to create and manage training and batch prediction jobs. +service JobService { + // Creates a training or a batch prediction job. + rpc CreateJob(CreateJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1/{parent=projects/*}/jobs" + body: "job" + }; + } + + // Lists the jobs in the project. + rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*}/jobs" + }; + } + + // Describes a job. + rpc GetJob(GetJobRequest) returns (Job) { + option (google.api.http) = { + get: "/v1/{name=projects/*/jobs/*}" + }; + } + + // Cancels a running job. + rpc CancelJob(CancelJobRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1/{name=projects/*/jobs/*}:cancel" + body: "*" + }; + } +} + +// Represents input parameters for a training job. +message TrainingInput { + // A scale tier is an abstract representation of the resources Cloud ML + // will allocate to a training job. When selecting a scale tier for your + // training job, you should consider the size of your training dataset and + // the complexity of your model. As the tiers increase, virtual machines are + // added to handle your job, and the individual machines in the cluster + // generally have more memory and greater processing power than they do at + // lower tiers. The number of training units charged per hour of processing + // increases as tiers get more advanced. Refer to the + // [pricing guide](/ml/pricing) for more details. Note that in addition to + // incurring costs, your use of training resources is constrained by the + // [quota policy](/ml/quota). + enum ScaleTier { + // A single worker instance. This tier is suitable for learning how to use + // Cloud ML, and for experimenting with new models using small datasets. + BASIC = 0; + + // Many workers and a few parameter servers. + STANDARD_1 = 1; + + // A large number of workers with many parameter servers. + PREMIUM_1 = 3; + + // A single worker instance [with a GPU](ml/docs/how-tos/using-gpus). + BASIC_GPU = 6; + + // The CUSTOM tier is not a set tier, but rather enables you to use your + // own cluster specification. When you use this tier, set values to + // configure your processing cluster according to these guidelines: + // + // * You _must_ set `TrainingInput.masterType` to specify the type + // of machine to use for your master node. This is the only required + // setting. + // + // * You _may_ set `TrainingInput.workerCount` to specify the number of + // workers to use. If you specify one or more workers, you _must_ also + // set `TrainingInput.workerType` to specify the type of machine to use + // for your worker nodes. + // + // * You _may_ set `TrainingInput.parameterServerCount` to specify the + // number of parameter servers to use. If you specify one or more + // parameter servers, you _must_ also set + // `TrainingInput.parameterServerType` to specify the type of machine to + // use for your parameter servers. + // + // Note that all of your workers must use the same machine type, which can + // be different from your parameter server type and master type. Your + // parameter servers must likewise use the same machine type, which can be + // different from your worker type and master type. + CUSTOM = 5; + } + + // Required. Specifies the machine types, the number of replicas for workers + // and parameter servers. + ScaleTier scale_tier = 1; + + // Optional. Specifies the type of virtual machine to use for your training + // job's master worker. + // + // The following types are supported: + // + // <dl> + // <dt>standard</dt> + // <dd> + // A basic machine configuration suitable for training simple models with + // small to moderate datasets. + // </dd> + // <dt>large_model</dt> + // <dd> + // A machine with a lot of memory, specially suited for parameter servers + // when your model is large (having many hidden layers or layers with very + // large numbers of nodes). + // </dd> + // <dt>complex_model_s</dt> + // <dd> + // A machine suitable for the master and workers of the cluster when your + // model requires more computation than the standard machine can handle + // satisfactorily. + // </dd> + // <dt>complex_model_m</dt> + // <dd> + // A machine with roughly twice the number of cores and roughly double the + // memory of <code suppresswarning="true">complex_model_s</code>. + // </dd> + // <dt>complex_model_l</dt> + // <dd> + // A machine with roughly twice the number of cores and roughly double the + // memory of <code suppresswarning="true">complex_model_m</code>. + // </dd> + // <dt>standard_gpu</dt> + // <dd> + // A machine equivalent to <code suppresswarning="true">standard</code> that + // also includes a + // <a href="ml/docs/how-tos/using-gpus"> + // GPU that you can use in your trainer</a>. + // </dd> + // <dt>complex_model_m_gpu</dt> + // <dd> + // A machine equivalent to + // <code suppresswarning="true">coplex_model_m</code> that also includes + // four GPUs. + // </dd> + // </dl> + // + // You must set this value when `scaleTier` is set to `CUSTOM`. + string master_type = 2; + + // Optional. Specifies the type of virtual machine to use for your training + // job's worker nodes. + // + // The supported values are the same as those described in the entry for + // `masterType`. + // + // This value must be present when `scaleTier` is set to `CUSTOM` and + // `workerCount` is greater than zero. + string worker_type = 3; + + // Optional. Specifies the type of virtual machine to use for your training + // job's parameter server. + // + // The supported values are the same as those described in the entry for + // `master_type`. + // + // This value must be present when `scaleTier` is set to `CUSTOM` and + // `parameter_server_count` is greater than zero. + string parameter_server_type = 4; + + // Optional. The number of worker replicas to use for the training job. Each + // replica in the cluster will be of the type specified in `worker_type`. + // + // This value can only be used when `scale_tier` is set to `CUSTOM`. If you + // set this value, you must also set `worker_type`. + int64 worker_count = 5; + + // Optional. The number of parameter server replicas to use for the training + // job. Each replica in the cluster will be of the type specified in + // `parameter_server_type`. + // + // This value can only be used when `scale_tier` is set to `CUSTOM`.If you + // set this value, you must also set `parameter_server_type`. + int64 parameter_server_count = 6; + + // Required. The Google Cloud Storage location of the packages with + // the training program and any additional dependencies. + repeated string package_uris = 7; + + // Required. The Python module name to run after installing the packages. + string python_module = 8; + + // Optional. Command line arguments to pass to the program. + repeated string args = 10; + + // Optional. The set of Hyperparameters to tune. + HyperparameterSpec hyperparameters = 12; + + // Required. The Google Compute Engine region to run the training job in. + string region = 14; + + // Optional. A Google Cloud Storage path in which to store training outputs + // and other data needed for training. This path is passed to your TensorFlow + // program as the 'job_dir' command-line argument. The benefit of specifying + // this field is that Cloud ML validates the path for use in training. + string job_dir = 16; + + // Optional. The Google Cloud ML runtime version to use for training. If not + // set, Google Cloud ML will choose the latest stable version. + string runtime_version = 15; +} + +// Represents a set of hyperparameters to optimize. +message HyperparameterSpec { + // The available types of optimization goals. + enum GoalType { + // Goal Type will default to maximize. + GOAL_TYPE_UNSPECIFIED = 0; + + // Maximize the goal metric. + MAXIMIZE = 1; + + // Minimize the goal metric. + MINIMIZE = 2; + } + + // Required. The type of goal to use for tuning. Available types are + // `MAXIMIZE` and `MINIMIZE`. + // + // Defaults to `MAXIMIZE`. + GoalType goal = 1; + + // Required. The set of parameters to tune. + repeated ParameterSpec params = 2; + + // Optional. How many training trials should be attempted to optimize + // the specified hyperparameters. + // + // Defaults to one. + int32 max_trials = 3; + + // Optional. The number of training trials to run concurrently. + // You can reduce the time it takes to perform hyperparameter tuning by adding + // trials in parallel. However, each trail only benefits from the information + // gained in completed trials. That means that a trial does not get access to + // the results of trials running at the same time, which could reduce the + // quality of the overall optimization. + // + // Each trial will use the same scale tier and machine types. + // + // Defaults to one. + int32 max_parallel_trials = 4; + + // Optional. The Tensorflow summary tag name to use for optimizing trials. For + // current versions of Tensorflow, this tag name should exactly match what is + // shown in Tensorboard, including all scopes. For versions of Tensorflow + // prior to 0.12, this should be only the tag passed to tf.Summary. + // By default, "training/hptuning/metric" will be used. + string hyperparameter_metric_tag = 5; +} + +// Represents a single hyperparameter to optimize. +message ParameterSpec { + // The type of the parameter. + enum ParameterType { + // You must specify a valid type. Using this unspecified type will result in + // an error. + PARAMETER_TYPE_UNSPECIFIED = 0; + + // Type for real-valued parameters. + DOUBLE = 1; + + // Type for integral parameters. + INTEGER = 2; + + // The parameter is categorical, with a value chosen from the categories + // field. + CATEGORICAL = 3; + + // The parameter is real valued, with a fixed set of feasible points. If + // `type==DISCRETE`, feasible_points must be provided, and + // {`min_value`, `max_value`} will be ignored. + DISCRETE = 4; + } + + // The type of scaling that should be applied to this parameter. + enum ScaleType { + // By default, no scaling is applied. + NONE = 0; + + // Scales the feasible space to (0, 1) linearly. + UNIT_LINEAR_SCALE = 1; + + // Scales the feasible space logarithmically to (0, 1). The entire feasible + // space must be strictly positive. + UNIT_LOG_SCALE = 2; + + // Scales the feasible space "reverse" logarithmically to (0, 1). The result + // is that values close to the top of the feasible space are spread out more + // than points near the bottom. The entire feasible space must be strictly + // positive. + UNIT_REVERSE_LOG_SCALE = 3; + } + + // Required. The parameter name must be unique amongst all ParameterConfigs in + // a HyperparameterSpec message. E.g., "learning_rate". + string parameter_name = 1; + + // Required. The type of the parameter. + ParameterType type = 4; + + // Required if type is `DOUBLE` or `INTEGER`. This field + // should be unset if type is `CATEGORICAL`. This value should be integers if + // type is INTEGER. + double min_value = 2; + + // Required if typeis `DOUBLE` or `INTEGER`. This field + // should be unset if type is `CATEGORICAL`. This value should be integers if + // type is `INTEGER`. + double max_value = 3; + + // Required if type is `CATEGORICAL`. The list of possible categories. + repeated string categorical_values = 5; + + // Required if type is `DISCRETE`. + // A list of feasible points. + // The list should be in strictly increasing order. For instance, this + // parameter might have possible settings of 1.5, 2.5, and 4.0. This list + // should not contain more than 1,000 values. + repeated double discrete_values = 6; + + // Optional. How the parameter should be scaled to the hypercube. + // Leave unset for categorical parameters. + // Some kind of scaling is strongly recommended for real or integral + // parameters (e.g., `UNIT_LINEAR_SCALE`). + ScaleType scale_type = 7; +} + +// Represents the result of a single hyperparameter tuning trial from a +// training job. The TrainingOutput object that is returned on successful +// completion of a training job with hyperparameter tuning includes a list +// of HyperparameterOutput objects, one for each successful trial. +message HyperparameterOutput { + // An observed value of a metric. + message HyperparameterMetric { + // The global training step for this metric. + int64 training_step = 1; + + // The objective value at this training step. + double objective_value = 2; + } + + // The trial id for these results. + string trial_id = 1; + + // The hyperparameters given to this trial. + map<string, string> hyperparameters = 2; + + // The final objective metric seen for this trial. + HyperparameterMetric final_metric = 3; + + // All recorded object metrics for this trial. + repeated HyperparameterMetric all_metrics = 4; +} + +// Represents results of a training job. Output only. +message TrainingOutput { + // The number of hyperparameter tuning trials that completed successfully. + // Only set for hyperparameter tuning jobs. + int64 completed_trial_count = 1; + + // Results for individual Hyperparameter trials. + // Only set for hyperparameter tuning jobs. + repeated HyperparameterOutput trials = 2; + + // The amount of ML units consumed by the job. + double consumed_ml_units = 3; + + // Whether this job is a hyperparameter tuning job. + bool is_hyperparameter_tuning_job = 4; +} + +// Represents input parameters for a prediction job. +message PredictionInput { + // The format used to separate data instances in the source files. + enum DataFormat { + // Unspecified format. + DATA_FORMAT_UNSPECIFIED = 0; + + // The source file is a text file with instances separated by the + // new-line character. + TEXT = 1; + + // The source file is a TFRecord file. + TF_RECORD = 2; + + // The source file is a GZIP-compressed TFRecord file. + TF_RECORD_GZIP = 3; + } + + // Required. The model or the version to use for prediction. + oneof model_version { + // Use this field if you want to use the default version for the specified + // model. The string must use the following format: + // + // `"projects/<var>[YOUR_PROJECT]</var>/models/<var>[YOUR_MODEL]</var>"` + string model_name = 1; + + // Use this field if you want to specify a version of the model to use. The + // string is formatted the same way as `model_version`, with the addition + // of the version information: + // + // `"projects/<var>[YOUR_PROJECT]</var>/models/<var>YOUR_MODEL/versions/<var>[YOUR_VERSION]</var>"` + string version_name = 2; + + // Use this field if you want to specify a Google Cloud Storage path for + // the model to use. + string uri = 9; + } + + // Required. The format of the input data files. + DataFormat data_format = 3; + + // Required. The Google Cloud Storage location of the input data files. + // May contain wildcards. + repeated string input_paths = 4; + + // Required. The output Google Cloud Storage location. + string output_path = 5; + + // Optional. The maximum number of workers to be used for parallel processing. + // Defaults to 10 if not specified. + int64 max_worker_count = 6; + + // Required. The Google Compute Engine region to run the prediction job in. + string region = 7; + + // Optional. The Google Cloud ML runtime version to use for this batch + // prediction. If not set, Google Cloud ML will pick the runtime version used + // during the CreateVersion request for this model version, or choose the + // latest stable version when model version information is not available + // such as when the model is specified by uri. + string runtime_version = 8; +} + +// Represents results of a prediction job. +message PredictionOutput { + // The output Google Cloud Storage location provided at the job creation time. + string output_path = 1; + + // The number of generated predictions. + int64 prediction_count = 2; + + // The number of data instances which resulted in errors. + int64 error_count = 3; + + // Node hours used by the batch prediction job. + double node_hours = 4; +} + +// Represents a training or prediction job. +message Job { + // Describes the job state. + enum State { + // The job state is unspecified. + STATE_UNSPECIFIED = 0; + + // The job has been just created and processing has not yet begun. + QUEUED = 1; + + // The service is preparing to run the job. + PREPARING = 2; + + // The job is in progress. + RUNNING = 3; + + // The job completed successfully. + SUCCEEDED = 4; + + // The job failed. + // `error_message` should contain the details of the failure. + FAILED = 5; + + // The job is being cancelled. + // `error_message` should describe the reason for the cancellation. + CANCELLING = 6; + + // The job has been cancelled. + // `error_message` should describe the reason for the cancellation. + CANCELLED = 7; + } + + // Required. The user-specified id of the job. + string job_id = 1; + + // Required. Parameters to create a job. + oneof input { + // Input parameters to create a training job. + TrainingInput training_input = 2; + + // Input parameters to create a prediction job. + PredictionInput prediction_input = 3; + } + + // Output only. When the job was created. + google.protobuf.Timestamp create_time = 4; + + // Output only. When the job processing was started. + google.protobuf.Timestamp start_time = 5; + + // Output only. When the job processing was completed. + google.protobuf.Timestamp end_time = 6; + + // Output only. The detailed state of a job. + State state = 7; + + // Output only. The details of a failure or a cancellation. + string error_message = 8; + + // Output only. The current result of the job. + oneof output { + // The current training job result. + TrainingOutput training_output = 9; + + // The current prediction job result. + PredictionOutput prediction_output = 10; + } +} + +// Request message for the CreateJob method. +message CreateJobRequest { + // Required. The project name. + // + // Authorization: requires `Editor` role on the specified project. + string parent = 1; + + // Required. The job to create. + Job job = 2; +} + +// Request message for the ListJobs method. +message ListJobsRequest { + // Required. The name of the project for which to list jobs. + // + // Authorization: requires `Viewer` role on the specified project. + string parent = 1; + + // Optional. Specifies the subset of jobs to retrieve. + string filter = 2; + + // Optional. A page token to request the next page of results. + // + // You get the token from the `next_page_token` field of the response from + // the previous call. + string page_token = 4; + + // Optional. The number of jobs to retrieve per "page" of results. If there + // are more remaining results than this number, the response message will + // contain a valid value in the `next_page_token` field. + // + // The default value is 20, and the maximum page size is 100. + int32 page_size = 5; +} + +// Response message for the ListJobs method. +message ListJobsResponse { + // The list of jobs. + repeated Job jobs = 1; + + // Optional. Pass this token as the `page_token` field of the request for a + // subsequent call. + string next_page_token = 2; +} + +// Request message for the GetJob method. +message GetJobRequest { + // Required. The name of the job to get the description of. + // + // Authorization: requires `Viewer` role on the parent project. + string name = 1; +} + +// Request message for the CancelJob method. +message CancelJobRequest { + // Required. The name of the job to cancel. + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} diff --git a/google/cloud/ml/v1/model_service.proto b/google/cloud/ml/v1/model_service.proto new file mode 100644 index 000000000..c57b16b50 --- /dev/null +++ b/google/cloud/ml/v1/model_service.proto @@ -0,0 +1,392 @@ +// 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.ml.v1; + +import "google/api/annotations.proto"; +import "google/api/auth.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml"; +option java_multiple_files = true; +option java_outer_classname = "ModelServiceProto"; +option java_package = "com.google.cloud.ml.api.v1"; + +// Copyright 2017 Google Inc. All Rights Reserved. +// +// Proto file for the Google Cloud Machine Learning Engine. +// Describes the 'models service' to work with the 'model' and 'version' +// resources. + +// Provides methods that create and manage machine learning models and their +// versions. +// +// A model in this context is a container for versions. The model can't provide +// predictions without first having a version created for it. +// +// Each version is a trained machine learning model, and each is assumed to be +// an iteration of the same machine learning problem as the other versions of +// the same model. +// +// Your project can define multiple models, each with multiple versions. +// +// The basic life cycle of a model is: +// +// * Create and train the machine learning model and save it to a +// Google Cloud Storage location. +// * Use +// [projects.models.create](/ml/reference/rest/v1/projects.models/create) +// to make a new model in your project. +// * Use +// [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create) +// to deploy your saved model. +// * Use [projects.predict](/ml/reference/rest/v1/projects/predict to +// request predictions of a version of your model, or use +// [projects.jobs.create](/ml/reference/rest/v1/projects.jobs/create) +// to start a batch prediction job. +service ModelService { + // Creates a model which will later contain one or more versions. + // + // You must add at least one version before you can request predictions from + // the model. Add versions by calling + // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create). + rpc CreateModel(CreateModelRequest) returns (Model) { + option (google.api.http) = { + post: "/v1/{parent=projects/*}/models" + body: "model" + }; + } + + // Lists the models in a project. + // + // Each project can contain multiple models, and each model can have multiple + // versions. + rpc ListModels(ListModelsRequest) returns (ListModelsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*}/models" + }; + } + + // Gets information about a model, including its name, the description (if + // set), and the default version (if at least one version of the model has + // been deployed). + rpc GetModel(GetModelRequest) returns (Model) { + option (google.api.http) = { + get: "/v1/{name=projects/*/models/*}" + }; + } + + // Deletes a model. + // + // You can only delete a model if there are no versions in it. You can delete + // versions by calling + // [projects.models.versions.delete](/ml/reference/rest/v1/projects.models.versions/delete). + rpc DeleteModel(DeleteModelRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/models/*}" + }; + } + + // Creates a new version of a model from a trained TensorFlow model. + // + // If the version created in the cloud by this call is the first deployed + // version of the specified model, it will be made the default version of the + // model. When you add a version to a model that already has one or more + // versions, the default version does not automatically change. If you want a + // new version to be the default, you must call + // [projects.models.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault). + rpc CreateVersion(CreateVersionRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/models/*}/versions" + body: "version" + }; + } + + // Gets basic information about all the versions of a model. + // + // If you expect that a model has a lot of versions, or if you need to handle + // only a limited number of results at a time, you can request that the list + // be retrieved in batches (called pages): + rpc ListVersions(ListVersionsRequest) returns (ListVersionsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/models/*}/versions" + }; + } + + // Gets information about a model version. + // + // Models can have multiple versions. You can call + // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list) + // to get the same information that this method returns for all of the + // versions of a model. + rpc GetVersion(GetVersionRequest) returns (Version) { + option (google.api.http) = { + get: "/v1/{name=projects/*/models/*/versions/*}" + }; + } + + // Deletes a model version. + // + // Each model can have multiple versions deployed and in use at any given + // time. Use this method to remove a single version. + // + // Note: You cannot delete the version that is set as the default version + // of the model unless it is the only remaining version. + rpc DeleteVersion(DeleteVersionRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/models/*/versions/*}" + }; + } + + // Designates a version to be the default for the model. + // + // The default version is used for prediction requests made against the model + // that don't specify a version. + // + // The first version to be created for a model is automatically set as the + // default. You must make any subsequent changes to the default version + // setting manually using this method. + rpc SetDefaultVersion(SetDefaultVersionRequest) returns (Version) { + option (google.api.http) = { + post: "/v1/{name=projects/*/models/*/versions/*}:setDefault" + body: "*" + }; + } +} + +// Represents a machine learning solution. +// +// A model can have multiple versions, each of which is a deployed, trained +// model ready to receive prediction requests. The model itself is just a +// container. +message Model { + // Required. The name specified for the model when it was created. + // + // The model name must be unique within the project it is created in. + string name = 1; + + // Optional. The description specified for the model when it was created. + string description = 2; + + // Output only. The default version of the model. This version will be used to + // handle prediction requests that do not specify a version. + // + // You can change the default version by calling + // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault). + Version default_version = 3; + + // Optional. The list of regions where the model is going to be deployed. + // Currently only one region per model is supported. + // Defaults to 'us-central1' if nothing is set. + repeated string regions = 4; + + // Optional. If true, enables StackDriver Logging for online prediction. + // Default is false. + bool online_prediction_logging = 5; +} + +// Represents a version of the model. +// +// Each version is a trained model deployed in the cloud, ready to handle +// prediction requests. A model can have multiple versions. You can get +// information about all of the versions of a given model by calling +// [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list). +message Version { + // Required.The name specified for the version when it was created. + // + // The version name must be unique within the model it is created in. + string name = 1; + + // Optional. The description specified for the version when it was created. + string description = 2; + + // Output only. If true, this version will be used to handle prediction + // requests that do not specify a version. + // + // You can change the default version by calling + // [projects.methods.versions.setDefault](/ml/reference/rest/v1/projects.models.versions/setDefault). + bool is_default = 3; + + // Required. The Google Cloud Storage location of the trained model used to + // create the version. See the + // [overview of model deployment](/ml/docs/concepts/deployment-overview) for + // more informaiton. + // + // When passing Version to + // [projects.models.versions.create](/ml/reference/rest/v1/projects.models.versions/create) + // the model service uses the specified location as the source of the model. + // Once deployed, the model version is hosted by the prediction service, so + // this location is useful only as a historical record. + string deployment_uri = 4; + + // Output only. The time the version was created. + google.protobuf.Timestamp create_time = 5; + + // Output only. The time the version was last used for prediction. + google.protobuf.Timestamp last_use_time = 6; + + // Optional. The Google Cloud ML runtime version to use for this deployment. + // If not set, Google Cloud ML will choose a version. + string runtime_version = 8; + + // Optional. Manually select the number of nodes to use for serving the + // model. If unset (i.e., by default), the number of nodes used to serve + // the model automatically scales with traffic. However, care should be + // taken to ramp up traffic according to the model's ability to scale. If + // your model needs to handle bursts of traffic beyond it's ability to + // scale, it is recommended you set this field appropriately. + ManualScaling manual_scaling = 9; +} + +// Options for manually scaling a model. +message ManualScaling { + // The number of nodes to allocate for this model. These nodes are always up, + // starting from the time the model is deployed, so the cost of operating + // this model will be proportional to nodes * number of hours since + // deployment. + int32 nodes = 1; +} + +// Request message for the CreateModel method. +message CreateModelRequest { + // Required. The project name. + // + // Authorization: requires `Editor` role on the specified project. + string parent = 1; + + // Required. The model to create. + Model model = 2; +} + +// Request message for the ListModels method. +message ListModelsRequest { + // Required. The name of the project whose models are to be listed. + // + // Authorization: requires `Viewer` role on the specified project. + string parent = 1; + + // Optional. A page token to request the next page of results. + // + // You get the token from the `next_page_token` field of the response from + // the previous call. + string page_token = 4; + + // Optional. The number of models to retrieve per "page" of results. If there + // are more remaining results than this number, the response message will + // contain a valid value in the `next_page_token` field. + // + // The default value is 20, and the maximum page size is 100. + int32 page_size = 5; +} + +// Response message for the ListModels method. +message ListModelsResponse { + // The list of models. + repeated Model models = 1; + + // Optional. Pass this token as the `page_token` field of the request for a + // subsequent call. + string next_page_token = 2; +} + +// Request message for the GetModel method. +message GetModelRequest { + // Required. The name of the model. + // + // Authorization: requires `Viewer` role on the parent project. + string name = 1; +} + +// Request message for the DeleteModel method. +message DeleteModelRequest { + // Required. The name of the model. + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} + +// Uploads the provided trained model version to Cloud Machine Learning. +message CreateVersionRequest { + // Required. The name of the model. + // + // Authorization: requires `Editor` role on the parent project. + string parent = 1; + + // Required. The version details. + Version version = 2; +} + +// Request message for the ListVersions method. +message ListVersionsRequest { + // Required. The name of the model for which to list the version. + // + // Authorization: requires `Viewer` role on the parent project. + string parent = 1; + + // Optional. A page token to request the next page of results. + // + // You get the token from the `next_page_token` field of the response from + // the previous call. + string page_token = 4; + + // Optional. The number of versions to retrieve per "page" of results. If + // there are more remaining results than this number, the response message + // will contain a valid value in the `next_page_token` field. + // + // The default value is 20, and the maximum page size is 100. + int32 page_size = 5; +} + +// Response message for the ListVersions method. +message ListVersionsResponse { + // The list of versions. + repeated Version versions = 1; + + // Optional. Pass this token as the `page_token` field of the request for a + // subsequent call. + string next_page_token = 2; +} + +// Request message for the GetVersion method. +message GetVersionRequest { + // Required. The name of the version. + // + // Authorization: requires `Viewer` role on the parent project. + string name = 1; +} + +// Request message for the DeleteVerionRequest method. +message DeleteVersionRequest { + // Required. The name of the version. You can get the names of all the + // versions of a model by calling + // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list). + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} + +// Request message for the SetDefaultVersion request. +message SetDefaultVersionRequest { + // Required. The name of the version to make the default for the model. You + // can get the names of all the versions of a model by calling + // [projects.models.versions.list](/ml/reference/rest/v1/projects.models.versions/list). + // + // Authorization: requires `Editor` role on the parent project. + string name = 1; +} diff --git a/google/cloud/ml/v1/operation_metadata.proto b/google/cloud/ml/v1/operation_metadata.proto new file mode 100644 index 000000000..0220cfd7e --- /dev/null +++ b/google/cloud/ml/v1/operation_metadata.proto @@ -0,0 +1,70 @@ +// 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.ml.v1; + +import "google/api/annotations.proto"; +import "google/cloud/ml/v1/model_service.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml"; +option java_multiple_files = true; +option java_outer_classname = "OperationMetadataProto"; +option java_package = "com.google.cloud.ml.api.v1"; + +// Copyright 2017 Google Inc. All Rights Reserved. +// +// Proto file for the Google Cloud Machine Learning Engine. +// Describes the metadata for longrunning operations. + +// Represents the metadata of the long-running operation. +message OperationMetadata { + // The operation type. + enum OperationType { + // Unspecified operation type. + OPERATION_TYPE_UNSPECIFIED = 0; + + // An operation to create a new version. + CREATE_VERSION = 1; + + // An operation to delete an existing version. + DELETE_VERSION = 2; + + // An operation to delete an existing model. + DELETE_MODEL = 3; + } + + // The time the operation was submitted. + google.protobuf.Timestamp create_time = 1; + + // The time operation processing started. + google.protobuf.Timestamp start_time = 2; + + // The time operation processing completed. + google.protobuf.Timestamp end_time = 3; + + // Indicates whether a request to cancel this operation has been made. + bool is_cancellation_requested = 4; + + // The operation type. + OperationType operation_type = 5; + + // Contains the name of the model associated with the operation. + string model_name = 6; + + // Contains the version associated with the operation. + Version version = 7; +} diff --git a/google/cloud/ml/v1/prediction_service.proto b/google/cloud/ml/v1/prediction_service.proto new file mode 100644 index 000000000..dba49277c --- /dev/null +++ b/google/cloud/ml/v1/prediction_service.proto @@ -0,0 +1,241 @@ +// 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.ml.v1; + +import "google/api/annotations.proto"; +import "google/api/httpbody.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml"; +option java_multiple_files = true; +option java_outer_classname = "PredictionServiceProto"; +option java_package = "com.google.cloud.ml.api.v1"; + +// Copyright 2017 Google Inc. All Rights Reserved. +// +// Proto file for the Google Cloud Machine Learning Engine. +// Describes the online prediction service. + +// The Prediction API, which serves predictions for models managed by +// ModelService. +service OnlinePredictionService { + // Performs prediction on the data in the request. + // + // **** REMOVE FROM GENERATED DOCUMENTATION + rpc Predict(PredictRequest) returns (google.api.HttpBody) { + option (google.api.http) = { + post: "/v1/{name=projects/**}:predict" + body: "*" + }; + } +} + +// Request for predictions to be issued against a trained model. +// +// The body of the request is a single JSON object with a single top-level +// field: +// +// <dl> +// <dt>instances</dt> +// <dd>A JSON array containing values representing the instances to use for +// prediction.</dd> +// </dl> +// +// The structure of each element of the instances list is determined by your +// model's input definition. Instances can include named inputs or can contain +// only unlabeled values. +// +// Not all data includes named inputs. Some instances will be simple +// JSON values (boolean, number, or string). However, instances are often lists +// of simple values, or complex nested lists. Here are some examples of request +// bodies: +// +// CSV data with each row encoded as a string value: +// <pre> +// {"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]} +// </pre> +// Plain text: +// <pre> +// {"instances": ["the quick brown fox", "la bruja le dio"]} +// </pre> +// Sentences encoded as lists of words (vectors of strings): +// <pre> +// { +// "instances": [ +// ["the","quick","brown"], +// ["la","bruja","le"], +// ... +// ] +// } +// </pre> +// Floating point scalar values: +// <pre> +// {"instances": [0.0, 1.1, 2.2]} +// </pre> +// Vectors of integers: +// <pre> +// { +// "instances": [ +// [0, 1, 2], +// [3, 4, 5], +// ... +// ] +// } +// </pre> +// Tensors (in this case, two-dimensional tensors): +// <pre> +// { +// "instances": [ +// [ +// [0, 1, 2], +// [3, 4, 5] +// ], +// ... +// ] +// } +// </pre> +// Images can be represented different ways. In this encoding scheme the first +// two dimensions represent the rows and columns of the image, and the third +// contains lists (vectors) of the R, G, and B values for each pixel. +// <pre> +// { +// "instances": [ +// [ +// [ +// [138, 30, 66], +// [130, 20, 56], +// ... +// ], +// [ +// [126, 38, 61], +// [122, 24, 57], +// ... +// ], +// ... +// ], +// ... +// ] +// } +// </pre> +// JSON strings must be encoded as UTF-8. To send binary data, you must +// base64-encode the data and mark it as binary. To mark a JSON string +// as binary, replace it with a JSON object with a single attribute named `b64`: +// <pre>{"b64": "..."} </pre> +// For example: +// +// Two Serialized tf.Examples (fake data, for illustrative purposes only): +// <pre> +// {"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]} +// </pre> +// Two JPEG image byte strings (fake data, for illustrative purposes only): +// <pre> +// {"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]} +// </pre> +// If your data includes named references, format each instance as a JSON object +// with the named references as the keys: +// +// JSON input data to be preprocessed: +// <pre> +// { +// "instances": [ +// { +// "a": 1.0, +// "b": true, +// "c": "x" +// }, +// { +// "a": -2.0, +// "b": false, +// "c": "y" +// } +// ] +// } +// </pre> +// Some models have an underlying TensorFlow graph that accepts multiple input +// tensors. In this case, you should use the names of JSON name/value pairs to +// identify the input tensors, as shown in the following exmaples: +// +// For a graph with input tensor aliases "tag" (string) and "image" +// (base64-encoded string): +// <pre> +// { +// "instances": [ +// { +// "tag": "beach", +// "image": {"b64": "ASa8asdf"} +// }, +// { +// "tag": "car", +// "image": {"b64": "JLK7ljk3"} +// } +// ] +// } +// </pre> +// For a graph with input tensor aliases "tag" (string) and "image" +// (3-dimensional array of 8-bit ints): +// <pre> +// { +// "instances": [ +// { +// "tag": "beach", +// "image": [ +// [ +// [138, 30, 66], +// [130, 20, 56], +// ... +// ], +// [ +// [126, 38, 61], +// [122, 24, 57], +// ... +// ], +// ... +// ] +// }, +// { +// "tag": "car", +// "image": [ +// [ +// [255, 0, 102], +// [255, 0, 97], +// ... +// ], +// [ +// [254, 1, 101], +// [254, 2, 93], +// ... +// ], +// ... +// ] +// }, +// ... +// ] +// } +// </pre> +// If the call is successful, the response body will contain one prediction +// entry per instance in the request body. If prediction fails for any +// instance, the response body will contain no predictions and will contian +// a single error entry instead. +message PredictRequest { + // Required. The resource name of a model or a version. + // + // Authorization: requires `Viewer` role on the parent project. + string name = 1; + + // + // Required. The prediction request body. + google.api.HttpBody http_body = 2; +} diff --git a/google/cloud/ml/v1/project_service.proto b/google/cloud/ml/v1/project_service.proto new file mode 100644 index 000000000..b5949093d --- /dev/null +++ b/google/cloud/ml/v1/project_service.proto @@ -0,0 +1,59 @@ +// 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.ml.v1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/ml/v1;ml"; +option java_multiple_files = true; +option java_outer_classname = "ProjectServiceProto"; +option java_package = "com.google.cloud.ml.api.v1"; + +// Copyright 2017 Google Inc. All Rights Reserved. +// +// Proto file for the Google Cloud Machine Learning Engine. +// Describes the project management service. + +// Allows retrieving project related information. +service ProjectManagementService { + // Get the service account information associated with your project. You need + // this information in order to grant the service account persmissions for + // the Google Cloud Storage location where you put your model training code + // for training the model with Google Cloud Machine Learning. + rpc GetConfig(GetConfigRequest) returns (GetConfigResponse) { + option (google.api.http) = { + get: "/v1/{name=projects/*}:getConfig" + }; + } +} + +// Requests service account information associated with a project. +message GetConfigRequest { + // Required. The project name. + // + // Authorization: requires `Viewer` role on the specified project. + string name = 1; +} + +// Returns service account information associated with a project. +message GetConfigResponse { + // The service account Cloud ML uses to access resources in the project. + string service_account = 1; + + // The project number for `service_account`. + int64 service_account_project = 2; +} diff --git a/google/cloud/oslogin/BUILD.bazel b/google/cloud/oslogin/BUILD.bazel new file mode 100644 index 000000000..a87c57fec --- /dev/null +++ b/google/cloud/oslogin/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"])) diff --git a/google/cloud/oslogin/artman_oslogin_v1.yaml b/google/cloud/oslogin/artman_oslogin_v1.yaml new file mode 100644 index 000000000..70e9022e2 --- /dev/null +++ b/google/cloud/oslogin/artman_oslogin_v1.yaml @@ -0,0 +1,35 @@ +common: + api_name: os-login + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - common + - v1 + service_yaml: oslogin_v1.yaml + gapic_yaml: v1/oslogin_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/oslogin/artman_oslogin_v1beta.yaml b/google/cloud/oslogin/artman_oslogin_v1beta.yaml new file mode 100644 index 000000000..6e3c099b6 --- /dev/null +++ b/google/cloud/oslogin/artman_oslogin_v1beta.yaml @@ -0,0 +1,35 @@ +common: + api_name: os-login + api_version: v1beta + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - common + - v1beta + service_yaml: oslogin_v1beta.yaml + gapic_yaml: v1beta/oslogin_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/oslogin/common/BUILD.bazel b/google/cloud/oslogin/common/BUILD.bazel new file mode 100644 index 000000000..72887421e --- /dev/null +++ b/google/cloud/oslogin/common/BUILD.bazel @@ -0,0 +1,58 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "common_proto", + srcs = [ + "common.proto", + ], + deps = [ + "//google/api:annotations_proto", + ], +) + +proto_library_with_info( + name = "common_proto_with_info", + deps = [":common_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", "java_resource_name_proto_library") + +java_proto_library( + name = "common_java_proto", + deps = [":common_proto"], +) + +java_grpc_library( + name = "common_java_grpc", + srcs = [":common_proto"], + deps = [":common_java_proto"], +) + +java_resource_name_proto_library( + name = "common_resource_name_java_proto", + gapic_yaml = "//google/logging/v2:logging_gapic.yaml", + deps = [":common_proto"], +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") + +go_proto_library( + name = "common_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/oslogin/common", + protos = [":common_proto_with_info"], + deps = ["//google/api:annotations_go_proto"], +) diff --git a/google/cloud/oslogin/common/common.proto b/google/cloud/oslogin/common/common.proto new file mode 100644 index 000000000..6c45ebb6d --- /dev/null +++ b/google/cloud/oslogin/common/common.proto @@ -0,0 +1,70 @@ +// 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.oslogin.common; + +import "google/api/annotations.proto"; + +option csharp_namespace = "Google.Cloud.OsLogin.Common"; +option go_package = "google.golang.org/genproto/googleapis/cloud/oslogin/common;common"; +option java_outer_classname = "OsLoginProto"; +option java_package = "com.google.cloud.oslogin.common"; +option php_namespace = "Google\\Cloud\\OsLogin\\Common"; + +// The POSIX account information associated with a Google account. +message PosixAccount { + // Only one POSIX account can be marked as primary. + bool primary = 1; + + // The username of the POSIX account. + string username = 2; + + // The user ID. + int64 uid = 3; + + // The default group ID. + int64 gid = 4; + + // The path to the home directory for this account. + string home_directory = 5; + + // The path to the logic shell for this account. + string shell = 6; + + // The GECOS (user information) entry for this account. + string gecos = 7; + + // System identifier for which account the username or uid applies to. + // By default, the empty value is used. + string system_id = 8; + + // Output only. A POSIX account identifier. + string account_id = 9; +} + +// The SSH public key information associated with a Google account. +message SshPublicKey { + // Public key text in SSH format, defined by + // <a href="https://www.ietf.org/rfc/rfc4253.txt" target="_blank">RFC4253</a> + // section 6.6. + string key = 1; + + // An expiration time in microseconds since epoch. + int64 expiration_time_usec = 2; + + // Output only. The SHA-256 fingerprint of the SSH public key. + string fingerprint = 3; +} diff --git a/google/cloud/oslogin/oslogin_v1.yaml b/google/cloud/oslogin/oslogin_v1.yaml new file mode 100644 index 000000000..ae1e989cf --- /dev/null +++ b/google/cloud/oslogin/oslogin_v1.yaml @@ -0,0 +1,40 @@ +type: google.api.Service +config_version: 3 +name: oslogin.googleapis.com +title: Google Cloud OS Login API + +apis: +- name: google.cloud.oslogin.v1.OsLoginService + +documentation: + summary: Manages OS login configuration for Google account users. + +backend: + rules: + - selector: google.cloud.oslogin.v1.OsLoginService.DeletePosixAccount + deadline: 10.0 + - selector: google.cloud.oslogin.v1.OsLoginService.DeleteSshPublicKey + deadline: 10.0 + - selector: google.cloud.oslogin.v1.OsLoginService.GetLoginProfile + deadline: 10.0 + - selector: google.cloud.oslogin.v1.OsLoginService.GetSshPublicKey + deadline: 10.0 + - selector: google.cloud.oslogin.v1.OsLoginService.ImportSshPublicKey + deadline: 10.0 + - selector: google.cloud.oslogin.v1.OsLoginService.UpdateSshPublicKey + deadline: 10.0 + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/compute + - selector: google.cloud.oslogin.v1.OsLoginService.GetLoginProfile + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-platform.read-only, + https://www.googleapis.com/auth/compute, + https://www.googleapis.com/auth/compute.readonly diff --git a/google/cloud/oslogin/oslogin_v1beta.yaml b/google/cloud/oslogin/oslogin_v1beta.yaml new file mode 100644 index 000000000..eb2975286 --- /dev/null +++ b/google/cloud/oslogin/oslogin_v1beta.yaml @@ -0,0 +1,40 @@ +type: google.api.Service +config_version: 3 +name: oslogin.googleapis.com +title: Google Cloud OS Login API + +apis: +- name: google.cloud.oslogin.v1beta.OsLoginService + +documentation: + summary: Manages OS login configuration for Google account users. + +backend: + rules: + - selector: google.cloud.oslogin.v1beta.OsLoginService.DeletePosixAccount + deadline: 10.0 + - selector: google.cloud.oslogin.v1beta.OsLoginService.DeleteSshPublicKey + deadline: 10.0 + - selector: google.cloud.oslogin.v1beta.OsLoginService.GetLoginProfile + deadline: 10.0 + - selector: google.cloud.oslogin.v1beta.OsLoginService.GetSshPublicKey + deadline: 10.0 + - selector: google.cloud.oslogin.v1beta.OsLoginService.ImportSshPublicKey + deadline: 10.0 + - selector: google.cloud.oslogin.v1beta.OsLoginService.UpdateSshPublicKey + deadline: 10.0 + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/compute + - selector: google.cloud.oslogin.v1beta.OsLoginService.GetLoginProfile + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-platform.read-only, + https://www.googleapis.com/auth/compute, + https://www.googleapis.com/auth/compute.readonly diff --git a/google/cloud/oslogin/v1/BUILD.bazel b/google/cloud/oslogin/v1/BUILD.bazel new file mode 100644 index 000000000..8a6d860d4 --- /dev/null +++ b/google/cloud/oslogin/v1/BUILD.bazel @@ -0,0 +1,160 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +_PROTO_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_proto", +] + +proto_library( + name = "oslogin_proto", + srcs = [ + "oslogin.proto", + ], + deps = [ + "//google/api:annotations_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + ] + _PROTO_SUBPACKAGE_DEPS, +) + +proto_library_with_info( + name = "oslogin_proto_with_info", + deps = [":oslogin_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +_JAVA_PROTO_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_java_proto", +] + +_JAVA_GRPC_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_java_grpc", +] + +_RESOURCE_NAME_JAVA_PROTO_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_resource_name_java_proto", +] + +java_proto_library( + name = "oslogin_java_proto", + deps = [":oslogin_proto"], +) + +java_grpc_library( + name = "oslogin_java_grpc", + srcs = [":oslogin_proto"], + deps = [":oslogin_java_proto"] + _JAVA_GRPC_DEPS + _JAVA_PROTO_SUBPACKAGE_DEPS, +) + +java_resource_name_proto_library( + name = "oslogin_resource_name_java_proto", + gapic_yaml = "oslogin_gapic.yaml", + deps = [":oslogin_proto"], +) + +java_gapic_library( + name = "oslogin_java_gapic", + src = ":oslogin_proto_with_info", + gapic_yaml = "oslogin_gapic.yaml", + service_yaml = "//google/cloud/oslogin:oslogin_v1.yaml", + test_deps = [ + ":oslogin_java_grpc", + ] + _JAVA_GRPC_SUBPACKAGE_DEPS, + deps = [ + ":oslogin_java_proto", + ":oslogin_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS + _JAVA_PROTO_SUBPACKAGE_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":oslogin_java_gapic_test"], +) for test_name in [ + "com.google.cloud.oslogin.v1.OsLoginServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-oslogin-v1-java", + client_deps = [":oslogin_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":oslogin_java_gapic_test"], + grpc_deps = [":oslogin_java_grpc"] + _JAVA_GRPC_SUBPACKAGE_DEPS, + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":oslogin_java_proto", + ":oslogin_proto", + ":oslogin_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS + _JAVA_PROTO_SUBPACKAGE_DEPS + _PROTO_SUBPACKAGE_DEPS + _RESOURCE_NAME_JAVA_PROTO_SUBPACKAGE_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "oslogin_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/oslogin/v1", + protos = [":oslogin_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/cloud/oslogin/common:common_go_proto", + ], +) + +go_gapic_library( + name = "oslogin_go_gapic", + src = ":oslogin_proto_with_info", + gapic_yaml = "oslogin_gapic.yaml", + importpath = "cloud.google.com/go/oslogin/apiv1", + service_yaml = "//google/cloud/oslogin:oslogin_v1.yaml", + deps = [ + ":oslogin_go_proto", + "//google/cloud/oslogin/common:common_go_proto", + ], +) + +go_test( + name = "oslogin_go_gapic_test", + srcs = [":oslogin_go_gapic_srcjar_test"], + embed = [":oslogin_go_gapic"], + importpath = "cloud.google.com/go/oslogin/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-oslogin-v1-go", + deps = [ + ":oslogin_go_gapic", + ":oslogin_go_gapic_srcjar-smoke-test.srcjar", + ":oslogin_go_gapic_srcjar-test.srcjar", + ":oslogin_go_proto", + "//google/cloud/oslogin/common:common_go_proto", + ], +) diff --git a/google/cloud/oslogin/v1/oslogin.proto b/google/cloud/oslogin/v1/oslogin.proto new file mode 100644 index 000000000..d76bd47e6 --- /dev/null +++ b/google/cloud/oslogin/v1/oslogin.proto @@ -0,0 +1,167 @@ +// 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.oslogin.v1; + +import "google/api/annotations.proto"; +import "google/cloud/oslogin/common/common.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option csharp_namespace = "Google.Cloud.OsLogin.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/oslogin/v1;oslogin"; +option java_multiple_files = true; +option java_outer_classname = "OsLoginProto"; +option java_package = "com.google.cloud.oslogin.v1"; +option php_namespace = "Google\\Cloud\\OsLogin\\V1"; + +// Cloud OS Login API +// +// The Cloud OS Login API allows you to manage users and their associated SSH +// public keys for logging into virtual machines on Google Cloud Platform. +service OsLoginService { + // Deletes a POSIX account. + rpc DeletePosixAccount(DeletePosixAccountRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=users/*/projects/*}" + }; + } + + // Deletes an SSH public key. + rpc DeleteSshPublicKey(DeleteSshPublicKeyRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=users/*/sshPublicKeys/*}" + }; + } + + // Retrieves the profile information used for logging in to a virtual machine + // on Google Compute Engine. + rpc GetLoginProfile(GetLoginProfileRequest) returns (LoginProfile) { + option (google.api.http) = { + get: "/v1/{name=users/*}/loginProfile" + }; + } + + // Retrieves an SSH public key. + rpc GetSshPublicKey(GetSshPublicKeyRequest) + returns (google.cloud.oslogin.common.SshPublicKey) { + option (google.api.http) = { + get: "/v1/{name=users/*/sshPublicKeys/*}" + }; + } + + // Adds an SSH public key and returns the profile information. Default POSIX + // account information is set when no username and UID exist as part of the + // login profile. + rpc ImportSshPublicKey(ImportSshPublicKeyRequest) + returns (ImportSshPublicKeyResponse) { + option (google.api.http) = { + post: "/v1/{parent=users/*}:importSshPublicKey" + body: "ssh_public_key" + }; + } + + // Updates an SSH public key and returns the profile information. This method + // supports patch semantics. + rpc UpdateSshPublicKey(UpdateSshPublicKeyRequest) + returns (google.cloud.oslogin.common.SshPublicKey) { + option (google.api.http) = { + patch: "/v1/{name=users/*/sshPublicKeys/*}" + body: "ssh_public_key" + }; + } +} + +// The user profile information used for logging in to a virtual machine on +// Google Compute Engine. +message LoginProfile { + // The primary email address that uniquely identifies the user. + string name = 1; + + // The list of POSIX accounts associated with the user. + repeated google.cloud.oslogin.common.PosixAccount posix_accounts = 2; + + // A map from SSH public key fingerprint to the associated key object. + map<string, google.cloud.oslogin.common.SshPublicKey> ssh_public_keys = 3; + + // Indicates if the user is suspended. A suspended user cannot log in but + // their profile information is retained. + bool suspended = 4; +} + +// A request message for deleting a POSIX account entry. +message DeletePosixAccountRequest { + // A reference to the POSIX account to update. POSIX accounts are identified + // by the project ID they are associated with. A reference to the POSIX + // account is in format `users/{user}/projects/{project}`. + string name = 1; +} + +// A request message for deleting an SSH public key. +message DeleteSshPublicKeyRequest { + // The fingerprint of the public key to update. Public keys are identified by + // their SHA-256 fingerprint. The fingerprint of the public key is in format + // `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; +} + +// A request message for retrieving the login profile information for a user. +message GetLoginProfileRequest { + // The unique ID for the user in format `users/{user}`. + string name = 1; +} + +// A request message for retrieving an SSH public key. +message GetSshPublicKeyRequest { + // The fingerprint of the public key to retrieve. Public keys are identified + // by their SHA-256 fingerprint. The fingerprint of the public key is in + // format `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; +} + +// A request message for importing an SSH public key. +message ImportSshPublicKeyRequest { + // The unique ID for the user in format `users/{user}`. + string parent = 1; + + // The SSH public key and expiration time. + google.cloud.oslogin.common.SshPublicKey ssh_public_key = 2; + + // The project ID of the Google Cloud Platform project. + string project_id = 3; +} + +// A response message for importing an SSH public key. +message ImportSshPublicKeyResponse { + // The login profile information for the user. + LoginProfile login_profile = 1; +} + +// A request message for updating an SSH public key. +message UpdateSshPublicKeyRequest { + // The fingerprint of the public key to update. Public keys are identified by + // their SHA-256 fingerprint. The fingerprint of the public key is in format + // `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; + + // The SSH public key and expiration time. + google.cloud.oslogin.common.SshPublicKey ssh_public_key = 2; + + // Mask to control which fields get updated. Updates all if not present. + google.protobuf.FieldMask update_mask = 3; +} diff --git a/google/cloud/oslogin/v1/oslogin_gapic.yaml b/google/cloud/oslogin/v1/oslogin_gapic.yaml new file mode 100644 index 000000000..167c821f3 --- /dev/null +++ b/google/cloud/oslogin/v1/oslogin_gapic.yaml @@ -0,0 +1,222 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.oslogin.v1 + python: + package_name: google.cloud.oslogin_v1.gapic + go: + package_name: cloud.google.com/go/oslogin/apiv1 + csharp: + package_name: Google.Cloud.OsLogin.V1 + ruby: + package_name: Google::Cloud::OsLogin::V1 + php: + package_name: Google\Cloud\OsLogin\V1 + nodejs: + package_name: os-login.v1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.oslogin.v1.OsLoginService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: users/{user} + entity_name: user + - name_pattern: users/{user}/projects/{project} + entity_name: project + - name_pattern: users/{user}/sshPublicKeys/{fingerprint} + entity_name: fingerprint + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 10000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 10000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: DeletePosixAccount + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: DeleteSshPublicKey + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: fingerprint + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: GetLoginProfile + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: user + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: GetSshPublicKey + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: fingerprint + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: ImportSshPublicKey + flattening: + groups: + - parameters: + - parent + - ssh_public_key + - parameters: + - parent + - ssh_public_key + - project_id + required_fields: + - parent + - ssh_public_key + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: user + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: UpdateSshPublicKey + flattening: + groups: + - parameters: + - name + - ssh_public_key + - parameters: + - name + - ssh_public_key + - update_mask + required_fields: + - name + - ssh_public_key + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: fingerprint + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 +resource_name_generation: +- message_name: DeletePosixAccountRequest + field_entity_map: + name: project +- message_name: DeleteSshPublicKeyRequest + field_entity_map: + name: fingerprint +- message_name: GetLoginProfileRequest + field_entity_map: + name: user +- message_name: GetSshPublicKeyRequest + field_entity_map: + name: fingerprint +- message_name: ImportSshPublicKeyRequest + field_entity_map: + parent: user +- message_name: UpdateSshPublicKeyRequest + field_entity_map: + name: fingerprint diff --git a/google/cloud/oslogin/v1alpha/oslogin.proto b/google/cloud/oslogin/v1alpha/oslogin.proto new file mode 100644 index 000000000..f3b754cca --- /dev/null +++ b/google/cloud/oslogin/v1alpha/oslogin.proto @@ -0,0 +1,166 @@ +// 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.oslogin.v1alpha; + +import "google/api/annotations.proto"; +import "google/cloud/oslogin/common/common.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option csharp_namespace = "Google.Cloud.OsLogin.V1Alpha"; +option go_package = "google.golang.org/genproto/googleapis/cloud/oslogin/v1alpha;oslogin"; +option java_multiple_files = true; +option java_outer_classname = "OsLoginProto"; +option java_package = "com.google.cloud.oslogin.v1alpha"; +option php_namespace = "Google\\Cloud\\OsLogin\\V1alpha"; + +// Cloud OS Login API +// +// The Cloud OS Login API allows you to manage users and their associated SSH +// public keys for logging into virtual machines on Google Cloud Platform. +service OsLoginService { + // Deletes a POSIX account. + rpc DeletePosixAccount(DeletePosixAccountRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1alpha/{name=users/*/projects/*}" + }; + } + + // Deletes an SSH public key. + rpc DeleteSshPublicKey(DeleteSshPublicKeyRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1alpha/{name=users/*/sshPublicKeys/*}" + }; + } + + // Retrieves the profile information used for logging in to a virtual machine + // on Google Compute Engine. + rpc GetLoginProfile(GetLoginProfileRequest) returns (LoginProfile) { + option (google.api.http) = { + get: "/v1alpha/{name=users/*}/loginProfile" + }; + } + + // Retrieves an SSH public key. + rpc GetSshPublicKey(GetSshPublicKeyRequest) + returns (google.cloud.oslogin.common.SshPublicKey) { + option (google.api.http) = { + get: "/v1alpha/{name=users/*/sshPublicKeys/*}" + }; + } + + // Adds an SSH public key and returns the profile information. Default POSIX + // account information is set when no username and UID exist as part of the + // login profile. + rpc ImportSshPublicKey(ImportSshPublicKeyRequest) + returns (ImportSshPublicKeyResponse) { + option (google.api.http) = { + post: "/v1alpha/{parent=users/*}:importSshPublicKey" + body: "ssh_public_key" + }; + } + + // Updates an SSH public key and returns the profile information. This method + // supports patch semantics. + rpc UpdateSshPublicKey(UpdateSshPublicKeyRequest) + returns (google.cloud.oslogin.common.SshPublicKey) { + option (google.api.http) = { + patch: "/v1alpha/{name=users/*/sshPublicKeys/*}" + body: "ssh_public_key" + }; + } +} + +// The user profile information used for logging in to a virtual machine on +// Google Compute Engine. +message LoginProfile { + // A unique user ID for identifying the user. + string name = 1; + + // The list of POSIX accounts associated with the Directory API user. + repeated google.cloud.oslogin.common.PosixAccount posix_accounts = 2; + + // A map from SSH public key fingerprint to the associated key object. + map<string, google.cloud.oslogin.common.SshPublicKey> ssh_public_keys = 3; + + // Indicates if the user is suspended. + bool suspended = 4; +} + +// A request message for deleting a POSIX account entry. +message DeletePosixAccountRequest { + // A reference to the POSIX account to update. POSIX accounts are identified + // by the project ID they are associated with. A reference to the POSIX + // account is in format `users/{user}/projects/{project}`. + string name = 1; +} + +// A request message for deleting an SSH public key. +message DeleteSshPublicKeyRequest { + // The fingerprint of the public key to update. Public keys are identified by + // their SHA-256 fingerprint. The fingerprint of the public key is in format + // `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; +} + +// A request message for retrieving the login profile information for a user. +message GetLoginProfileRequest { + // The unique ID for the user in format `users/{user}`. + string name = 1; +} + +// A request message for retrieving an SSH public key. +message GetSshPublicKeyRequest { + // The fingerprint of the public key to retrieve. Public keys are identified + // by their SHA-256 fingerprint. The fingerprint of the public key is in + // format `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; +} + +// A request message for importing an SSH public key. +message ImportSshPublicKeyRequest { + // The unique ID for the user in format `users/{user}`. + string parent = 1; + + // The SSH public key and expiration time. + google.cloud.oslogin.common.SshPublicKey ssh_public_key = 2; + + // The project ID of the Google Cloud Platform project. + string project_id = 3; +} + +// A response message for importing an SSH public key. +message ImportSshPublicKeyResponse { + // The login profile information for the user. + LoginProfile login_profile = 1; +} + +// A request message for updating an SSH public key. +message UpdateSshPublicKeyRequest { + // The fingerprint of the public key to update. Public keys are identified by + // their SHA-256 fingerprint. The fingerprint of the public key is in format + // `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; + + // The SSH public key and expiration time. + google.cloud.oslogin.common.SshPublicKey ssh_public_key = 2; + + // Mask to control which fields get updated. Updates all if not present. + google.protobuf.FieldMask update_mask = 3; +} diff --git a/google/cloud/oslogin/v1beta/BUILD.bazel b/google/cloud/oslogin/v1beta/BUILD.bazel new file mode 100644 index 000000000..425f5f6cf --- /dev/null +++ b/google/cloud/oslogin/v1beta/BUILD.bazel @@ -0,0 +1,160 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +_PROTO_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_proto", +] + +proto_library( + name = "oslogin_proto", + srcs = [ + "oslogin.proto", + ], + deps = [ + "//google/api:annotations_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + ] + _PROTO_SUBPACKAGE_DEPS, +) + +proto_library_with_info( + name = "oslogin_proto_with_info", + deps = [":oslogin_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +_JAVA_PROTO_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_java_proto", +] + +_JAVA_GRPC_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_java_grpc", +] + +_RESOURCE_NAME_JAVA_PROTO_SUBPACKAGE_DEPS = [ + "//google/cloud/oslogin/common:common_resource_name_java_proto", +] + +java_proto_library( + name = "oslogin_java_proto", + deps = [":oslogin_proto"], +) + +java_grpc_library( + name = "oslogin_java_grpc", + srcs = [":oslogin_proto"], + deps = [":oslogin_java_proto"] + _JAVA_GRPC_DEPS + _JAVA_PROTO_SUBPACKAGE_DEPS, +) + +java_resource_name_proto_library( + name = "oslogin_resource_name_java_proto", + gapic_yaml = "oslogin_gapic.yaml", + deps = [":oslogin_proto"], +) + +java_gapic_library( + name = "oslogin_java_gapic", + src = ":oslogin_proto_with_info", + gapic_yaml = "oslogin_gapic.yaml", + service_yaml = "//google/cloud/oslogin:oslogin_v1beta.yaml", + test_deps = [ + ":oslogin_java_grpc", + ] + _JAVA_GRPC_SUBPACKAGE_DEPS, + deps = [ + ":oslogin_java_proto", + ":oslogin_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS + _JAVA_PROTO_SUBPACKAGE_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":oslogin_java_gapic_test"], +) for test_name in [ + "com.google.cloud.oslogin.v1beta.OsLoginServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-oslogin-v1beta-java", + client_deps = [":oslogin_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":oslogin_java_gapic_test"], + grpc_deps = [":oslogin_java_grpc"] + _JAVA_GRPC_SUBPACKAGE_DEPS, + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":oslogin_java_proto", + ":oslogin_proto", + ":oslogin_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS + _JAVA_PROTO_SUBPACKAGE_DEPS + _PROTO_SUBPACKAGE_DEPS + _RESOURCE_NAME_JAVA_PROTO_SUBPACKAGE_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "oslogin_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/oslogin/v1beta", + protos = [":oslogin_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/cloud/oslogin/common:common_go_proto", + ], +) + +go_gapic_library( + name = "oslogin_go_gapic", + src = ":oslogin_proto_with_info", + gapic_yaml = "oslogin_gapic.yaml", + importpath = "cloud.google.com/go/oslogin/apiv1beta", + service_yaml = "//google/cloud/oslogin:oslogin_v1beta.yaml", + deps = [ + ":oslogin_go_proto", + "//google/cloud/oslogin/common:common_go_proto", + ], +) + +go_test( + name = "oslogin_go_gapic_test", + srcs = [":oslogin_go_gapic_srcjar_test"], + embed = [":oslogin_go_gapic"], + importpath = "cloud.google.com/go/oslogin/apiv1beta", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-oslogin-v1beta-go", + deps = [ + ":oslogin_go_gapic", + ":oslogin_go_gapic_srcjar-smoke-test.srcjar", + ":oslogin_go_gapic_srcjar-test.srcjar", + ":oslogin_go_proto", + "//google/cloud/oslogin/common:common_go_proto", + ], +) diff --git a/google/cloud/oslogin/v1beta/oslogin.proto b/google/cloud/oslogin/v1beta/oslogin.proto new file mode 100644 index 000000000..304c4d9f6 --- /dev/null +++ b/google/cloud/oslogin/v1beta/oslogin.proto @@ -0,0 +1,167 @@ +// 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.oslogin.v1beta; + +import "google/api/annotations.proto"; +import "google/cloud/oslogin/common/common.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option csharp_namespace = "Google.Cloud.OsLogin.V1Beta"; +option go_package = "google.golang.org/genproto/googleapis/cloud/oslogin/v1beta;oslogin"; +option java_multiple_files = true; +option java_outer_classname = "OsLoginProto"; +option java_package = "com.google.cloud.oslogin.v1beta"; +option php_namespace = "Google\\Cloud\\OsLogin\\V1beta"; + +// Cloud OS Login API +// +// The Cloud OS Login API allows you to manage users and their associated SSH +// public keys for logging into virtual machines on Google Cloud Platform. +service OsLoginService { + // Deletes a POSIX account. + rpc DeletePosixAccount(DeletePosixAccountRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta/{name=users/*/projects/*}" + }; + } + + // Deletes an SSH public key. + rpc DeleteSshPublicKey(DeleteSshPublicKeyRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta/{name=users/*/sshPublicKeys/*}" + }; + } + + // Retrieves the profile information used for logging in to a virtual machine + // on Google Compute Engine. + rpc GetLoginProfile(GetLoginProfileRequest) returns (LoginProfile) { + option (google.api.http) = { + get: "/v1beta/{name=users/*}/loginProfile" + }; + } + + // Retrieves an SSH public key. + rpc GetSshPublicKey(GetSshPublicKeyRequest) + returns (google.cloud.oslogin.common.SshPublicKey) { + option (google.api.http) = { + get: "/v1beta/{name=users/*/sshPublicKeys/*}" + }; + } + + // Adds an SSH public key and returns the profile information. Default POSIX + // account information is set when no username and UID exist as part of the + // login profile. + rpc ImportSshPublicKey(ImportSshPublicKeyRequest) + returns (ImportSshPublicKeyResponse) { + option (google.api.http) = { + post: "/v1beta/{parent=users/*}:importSshPublicKey" + body: "ssh_public_key" + }; + } + + // Updates an SSH public key and returns the profile information. This method + // supports patch semantics. + rpc UpdateSshPublicKey(UpdateSshPublicKeyRequest) + returns (google.cloud.oslogin.common.SshPublicKey) { + option (google.api.http) = { + patch: "/v1beta/{name=users/*/sshPublicKeys/*}" + body: "ssh_public_key" + }; + } +} + +// The user profile information used for logging in to a virtual machine on +// Google Compute Engine. +message LoginProfile { + // The primary email address that uniquely identifies the user. + string name = 1; + + // The list of POSIX accounts associated with the user. + repeated google.cloud.oslogin.common.PosixAccount posix_accounts = 2; + + // A map from SSH public key fingerprint to the associated key object. + map<string, google.cloud.oslogin.common.SshPublicKey> ssh_public_keys = 3; + + // Indicates if the user is suspended. A suspended user cannot log in but + // their profile information is retained. + bool suspended = 4; +} + +// A request message for deleting a POSIX account entry. +message DeletePosixAccountRequest { + // A reference to the POSIX account to update. POSIX accounts are identified + // by the project ID they are associated with. A reference to the POSIX + // account is in format `users/{user}/projects/{project}`. + string name = 1; +} + +// A request message for deleting an SSH public key. +message DeleteSshPublicKeyRequest { + // The fingerprint of the public key to update. Public keys are identified by + // their SHA-256 fingerprint. The fingerprint of the public key is in format + // `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; +} + +// A request message for retrieving the login profile information for a user. +message GetLoginProfileRequest { + // The unique ID for the user in format `users/{user}`. + string name = 1; +} + +// A request message for retrieving an SSH public key. +message GetSshPublicKeyRequest { + // The fingerprint of the public key to retrieve. Public keys are identified + // by their SHA-256 fingerprint. The fingerprint of the public key is in + // format `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; +} + +// A request message for importing an SSH public key. +message ImportSshPublicKeyRequest { + // The unique ID for the user in format `users/{user}`. + string parent = 1; + + // The SSH public key and expiration time. + google.cloud.oslogin.common.SshPublicKey ssh_public_key = 2; + + // The project ID of the Google Cloud Platform project. + string project_id = 3; +} + +// A response message for importing an SSH public key. +message ImportSshPublicKeyResponse { + // The login profile information for the user. + LoginProfile login_profile = 1; +} + +// A request message for updating an SSH public key. +message UpdateSshPublicKeyRequest { + // The fingerprint of the public key to update. Public keys are identified by + // their SHA-256 fingerprint. The fingerprint of the public key is in format + // `users/{user}/sshPublicKeys/{fingerprint}`. + string name = 1; + + // The SSH public key and expiration time. + google.cloud.oslogin.common.SshPublicKey ssh_public_key = 2; + + // Mask to control which fields get updated. Updates all if not present. + google.protobuf.FieldMask update_mask = 3; +} diff --git a/google/cloud/oslogin/v1beta/oslogin_gapic.yaml b/google/cloud/oslogin/v1beta/oslogin_gapic.yaml new file mode 100644 index 000000000..09251d436 --- /dev/null +++ b/google/cloud/oslogin/v1beta/oslogin_gapic.yaml @@ -0,0 +1,222 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.oslogin.v1beta + python: + package_name: google.cloud.oslogin_v1beta.gapic + go: + package_name: cloud.google.com/go/oslogin/apiv1beta + csharp: + package_name: Google.Cloud.OsLogin.V1Beta + ruby: + package_name: Google::Cloud::OsLogin::V1beta + php: + package_name: Google\Cloud\OsLogin\V1beta + nodejs: + package_name: os-login.v1beta + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.oslogin.v1beta.OsLoginService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: users/{user} + entity_name: user + - name_pattern: users/{user}/projects/{project} + entity_name: project + - name_pattern: users/{user}/sshPublicKeys/{fingerprint} + entity_name: fingerprint + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 10000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 10000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: DeletePosixAccount + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: project + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: DeleteSshPublicKey + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: fingerprint + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: GetLoginProfile + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: user + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: GetSshPublicKey + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: fingerprint + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: ImportSshPublicKey + flattening: + groups: + - parameters: + - parent + - ssh_public_key + - parameters: + - parent + - ssh_public_key + - project_id + required_fields: + - parent + - ssh_public_key + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: user + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 + - name: UpdateSshPublicKey + flattening: + groups: + - parameters: + - name + - ssh_public_key + - parameters: + - name + - ssh_public_key + - update_mask + required_fields: + - name + - ssh_public_key + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: fingerprint + resource_name_treatment: STATIC_TYPES + timeout_millis: 10000 +resource_name_generation: +- message_name: DeletePosixAccountRequest + field_entity_map: + name: project +- message_name: DeleteSshPublicKeyRequest + field_entity_map: + name: fingerprint +- message_name: GetLoginProfileRequest + field_entity_map: + name: user +- message_name: GetSshPublicKeyRequest + field_entity_map: + name: fingerprint +- message_name: ImportSshPublicKeyRequest + field_entity_map: + parent: user +- message_name: UpdateSshPublicKeyRequest + field_entity_map: + name: fingerprint diff --git a/google/cloud/phishingprotection/artman_phishingprotection_v1beta1.yaml b/google/cloud/phishingprotection/artman_phishingprotection_v1beta1.yaml new file mode 100644 index 000000000..547e0fa99 --- /dev/null +++ b/google/cloud/phishingprotection/artman_phishingprotection_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: phishingprotection + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: phishingprotection.yaml + gapic_yaml: v1beta1/phishingprotection_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/phishingprotection/phishingprotection.yaml b/google/cloud/phishingprotection/phishingprotection.yaml new file mode 100644 index 000000000..7adec2ebb --- /dev/null +++ b/google/cloud/phishingprotection/phishingprotection.yaml @@ -0,0 +1,14 @@ +type: google.api.Service +config_version: 3 +name: phishingprotection.googleapis.com +title: Phishing Protection API + +apis: +- name: google.cloud.phishingprotection.v1beta1.PhishingProtectionServiceV1Beta1 + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/phishingprotection/v1beta1/phishingprotection.proto b/google/cloud/phishingprotection/v1beta1/phishingprotection.proto new file mode 100644 index 000000000..62a9fd03e --- /dev/null +++ b/google/cloud/phishingprotection/v1beta1/phishingprotection.proto @@ -0,0 +1,57 @@ +// Copyright 2019 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.phishingprotection.v1beta1; + +import "google/api/annotations.proto"; + +option csharp_namespace = "Google.Cloud.PhishingProtection.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/phishingprotection/v1beta1;phishingprotection"; +option java_multiple_files = true; +option java_outer_classname = "PhishingProtectionProto"; +option java_package = "com.google.phishingprotection.v1beta1"; +option objc_class_prefix = "GCPP"; +option php_namespace = "Google\\Cloud\\PhishingProtection\\V1beta1"; + +// Service to report phishing URIs. +service PhishingProtectionServiceV1Beta1 { + // Reports a URI suspected of containing phishing content to be reviewed. Once + // the report review is completed, if its result verifies the existince of + // malicious phishing content, the site will be added the to [Google's Social + // Engineering lists](https://support.google.com/webmasters/answer/6350487/) + // in order to protect users that could get exposed to this threat in + // the future. + rpc ReportPhishing(ReportPhishingRequest) returns (ReportPhishingResponse) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*}/phishing:report" + body: "*" + }; + } +} + +// The ReportPhishing request message. +message ReportPhishingRequest { + // Required. The name of the project for which the report will be created, + // in the format "projects/{project_number}". + string parent = 1; + + // The URI that is being reported for phishing content to be analyzed. + string uri = 2; +} + +// The ReportPhishing (empty) response message. +message ReportPhishingResponse {} diff --git a/google/cloud/phishingprotection/v1beta1/phishingprotection_gapic.yaml b/google/cloud/phishingprotection/v1beta1/phishingprotection_gapic.yaml new file mode 100644 index 000000000..02d430412 --- /dev/null +++ b/google/cloud/phishingprotection/v1beta1/phishingprotection_gapic.yaml @@ -0,0 +1,135 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.phishingprotection.v1beta1 + python: + package_name: google.cloud.phishingprotection_v1beta1.gapic + go: + package_name: cloud.google.com/go/phishingprotection/apiv1beta1 + csharp: + package_name: Google.Cloud.PhishingProtection.V1Beta1 + ruby: + package_name: Google::Cloud::PhishingProtection::V1beta1 + php: + package_name: Google\Cloud\PhishingProtection\V1beta1 + nodejs: + package_name: phishingprotection.v1beta1 +# The configuration for the license header to put on generated files. +license_header: + # The file containing the copyright line(s). + copyright_file: copyright-google.txt + # The file containing the raw license header without any copyright line(s). + license_file: license-header-apache-2.0.txt +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.phishingprotection.v1beta1.PhishingProtectionServiceV1Beta1 + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ReportPhishing + flattening: + groups: + - parameters: + - parent + - uri + required_fields: + - parent + - uri + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 +resource_name_generation: +- message_name: ReportPhishingRequest + field_entity_map: + parent: project diff --git a/google/cloud/recaptchaenterprise/artman_recaptchaenterprise_v1beta1.yaml b/google/cloud/recaptchaenterprise/artman_recaptchaenterprise_v1beta1.yaml new file mode 100644 index 000000000..9303e71b4 --- /dev/null +++ b/google/cloud/recaptchaenterprise/artman_recaptchaenterprise_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: recaptchaenterprise + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: recaptchaenterprise_v1beta1.yaml + gapic_yaml: v1beta1/recaptchaenterprise_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/recaptchaenterprise/recaptchaenterprise_v1beta1.yaml b/google/cloud/recaptchaenterprise/recaptchaenterprise_v1beta1.yaml new file mode 100644 index 000000000..4996c5a4f --- /dev/null +++ b/google/cloud/recaptchaenterprise/recaptchaenterprise_v1beta1.yaml @@ -0,0 +1,18 @@ +type: google.api.Service +config_version: 3 +name: recaptchaenterprise.googleapis.com +title: reCAPTCHA Enterprise API + +apis: +- name: google.cloud.recaptchaenterprise.v1beta1.RecaptchaEnterpriseServiceV1Beta1 + +authentication: + rules: + - selector: google.cloud.recaptchaenterprise.v1beta1.RecaptchaEnterpriseServiceV1Beta1.AnnotateAssessment + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: google.cloud.recaptchaenterprise.v1beta1.RecaptchaEnterpriseServiceV1Beta1.CreateAssessment + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/recaptchaenterprise/v1beta1/recaptchaenterprise.proto b/google/cloud/recaptchaenterprise/v1beta1/recaptchaenterprise.proto new file mode 100644 index 000000000..188f99f6f --- /dev/null +++ b/google/cloud/recaptchaenterprise/v1beta1/recaptchaenterprise.proto @@ -0,0 +1,183 @@ +// Copyright 2019 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.recaptchaenterprise.v1beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.RecaptchaEnterprise.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/recaptchaenterprise/v1beta1;recaptchaenterprise"; +option java_multiple_files = true; +option java_outer_classname = "RecaptchaEnterpriseProto"; +option java_package = "com.google.recaptchaenterprise.v1beta1"; +option objc_class_prefix = "GCRE"; +option php_namespace = "Google\\Cloud\\RecaptchaEnterprise\\V1beta1"; + + +// Service to determine the likelihood an event is legitimate. +service RecaptchaEnterpriseServiceV1Beta1 { + // Creates an Assessment of the likelihood an event is legitimate. + rpc CreateAssessment(CreateAssessmentRequest) returns (Assessment) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*}/assessments" + body: "assessment" + }; + } + + // Annotates a previously created Assessment to provide additional information + // on whether the event turned out to be authentic or fradulent. + rpc AnnotateAssessment(AnnotateAssessmentRequest) returns (AnnotateAssessmentResponse) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/assessments/*}:annotate" + body: "*" + }; + } +} + +// The create assessment request message. +message CreateAssessmentRequest { + // Required. The name of the project in which the assessment will be created, + // in the format "projects/{project_number}". + string parent = 1; + + // The asessment details. + Assessment assessment = 2; +} + +// The request message to annotate an Assessment. +message AnnotateAssessmentRequest { + // Enum that reprensents the types of annotations. + enum Annotation { + // Default unspecified type. + ANNOTATION_UNSPECIFIED = 0; + + // Provides information that the event turned out to be legitimate. + LEGITIMATE = 1; + + // Provides information that the event turned out to be fraudulent. + FRAUDULENT = 2; + } + + // Required. The resource name of the Assessment, in the format + // "projects/{project_number}/assessments/{assessment_id}". + string name = 1; + + // The annotation that will be assigned to the Event. + Annotation annotation = 2; +} + +// Empty response for AnnotateAssessment. +message AnnotateAssessmentResponse { + +} + +// A recaptcha assessment resource. +message Assessment { + // LINT.IfChange(classification_reason) + // Reasons contributing to the risk analysis verdict. + enum ClassificationReason { + // Default unspecified type. + CLASSIFICATION_REASON_UNSPECIFIED = 0; + + // The event appeared to be automated. + AUTOMATION = 1; + + // The event was not made from the proper context on the real site. + UNEXPECTED_ENVIRONMENT = 2; + + // Browsing behavior leading up to the event was generated was out of the + // ordinary. + UNEXPECTED_USAGE_PATTERNS = 4; + + // Too little traffic has been received from this site thus far to generate + // quality risk analysis. + PROVISIONAL_RISK_ANALYSIS = 5; + } + + // Output only. The resource name for the Assessment in the format + // "projects/{project_number}/assessments/{assessment_id}". + string name = 1; + + // The event being assessed. + Event event = 2; + + // Output only. Legitimate event score from 0.0 to 1.0. + // (1.0 means very likely legitimate traffic while 0.0 means very likely + // non-legitimate traffic). + float score = 3; + + // Output only. Properties of the provided event token. + TokenProperties token_properties = 4; + + // Output only. Reasons contributing to the risk analysis verdict. + repeated ClassificationReason reasons = 5; +} + +message Event { + // The user response token provided by the reCAPTCHA client-side integration + // on your site. + string token = 1; + + // The site key that was used to invoke reCAPTCHA on your site and generate + // the token. + string site_key = 2; +} + +message TokenProperties { + // Enum that represents the types of invalid token reasons. + enum InvalidReason { + // Default unspecified type. + INVALID_REASON_UNSPECIFIED = 0; + + // If the failure reason was not accounted for. + UNKNOWN_INVALID_REASON = 1; + + // The provided user verification token was malformed. + MALFORMED = 2; + + // The user verification token had expired. + EXPIRED = 3; + + // The user verification had already been seen. + DUPE = 4; + + // The user verification token did not match the provided site secret. + // This may be a configuration error (e.g. development keys used in + // production) or end users trying to use verification tokens from other + // sites. + SITE_MISMATCH = 5; + + // The user verification token was not present. It is a required input. + MISSING = 6; + } + + // Output only. Whether the provided user response token is valid. + bool valid = 1; + + // Output only. Reason associated with the response when valid = false. + InvalidReason invalid_reason = 2; + + // Output only. The timestamp corresponding to the generation of the token. + google.protobuf.Timestamp create_time = 3; + + // Output only. The hostname of the page on which the token was generated. + string hostname = 4; + + // Output only. Action name provided at token generation. + string action = 5; +} diff --git a/google/cloud/recaptchaenterprise/v1beta1/recaptchaenterprise_gapic.yaml b/google/cloud/recaptchaenterprise/v1beta1/recaptchaenterprise_gapic.yaml new file mode 100644 index 000000000..7417a669c --- /dev/null +++ b/google/cloud/recaptchaenterprise/v1beta1/recaptchaenterprise_gapic.yaml @@ -0,0 +1,154 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.recaptchaenterprise.v1beta1 + python: + package_name: google.cloud.recaptchaenterprise_v1beta1.gapic + go: + package_name: cloud.google.com/go/recaptchaenterprise/apiv1beta1 + csharp: + package_name: Google.Cloud.RecaptchaEnterprise.V1Beta1 + ruby: + package_name: Google::Cloud::RecaptchaEnterprise::V1beta1 + php: + package_name: Google\Cloud\RecaptchaEnterprise\V1beta1 + nodejs: + package_name: recaptchaenterprise.v1beta1 +# The configuration for the license header to put on generated files. +license_header: + # The file containing the copyright line(s). + copyright_file: copyright-google.txt + # The file containing the raw license header without any copyright line(s). + license_file: license-header-apache-2.0.txt +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.recaptchaenterprise.v1beta1.RecaptchaEnterpriseServiceV1Beta1 + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/assessments/{assessment} + entity_name: assessment + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateAssessment + flattening: + groups: + - parameters: + - parent + - assessment + required_fields: + - parent + - assessment + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + - name: AnnotateAssessment + flattening: + groups: + - parameters: + - name + - annotation + required_fields: + - name + - annotation + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: assessment + timeout_millis: 60000 +resource_name_generation: +- message_name: CreateAssessmentRequest + field_entity_map: + parent: project +- message_name: AnnotateAssessmentRequest + field_entity_map: + name: assessment diff --git a/google/cloud/redis/BUILD.bazel b/google/cloud/redis/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/redis/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/redis/artman_redis_v1.yaml b/google/cloud/redis/artman_redis_v1.yaml new file mode 100644 index 000000000..e603fda38 --- /dev/null +++ b/google/cloud/redis/artman_redis_v1.yaml @@ -0,0 +1,34 @@ +common: + api_name: redis + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: redis_v1.yaml + gapic_yaml: v1/redis_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/redis/artman_redis_v1beta1.yaml b/google/cloud/redis/artman_redis_v1beta1.yaml new file mode 100644 index 000000000..7ac7287ce --- /dev/null +++ b/google/cloud/redis/artman_redis_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: redis + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: redis_v1beta1.yaml + gapic_yaml: v1beta1/redis_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/redis/redis_v1.yaml b/google/cloud/redis/redis_v1.yaml new file mode 100644 index 000000000..65935a14b --- /dev/null +++ b/google/cloud/redis/redis_v1.yaml @@ -0,0 +1,65 @@ +type: google.api.Service +config_version: 3 +name: redis.googleapis.com +title: Google Cloud Memorystore for Redis API + +apis: + - name: google.cloud.redis.v1.CloudRedis + +types: + - name: google.cloud.redis.v1.LocationMetadata + - name: google.cloud.redis.v1.OperationMetadata + - name: google.cloud.redis.v1.ZoneMetadata + +documentation: + summary: Creates and manages Redis instances on the Google Cloud Platform. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 60.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 60.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 60.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 60.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 60.0 + - selector: google.cloud.redis.v1.CloudRedis.ListInstances + deadline: 60.0 + - selector: google.cloud.redis.v1.CloudRedis.GetInstance + deadline: 60.0 + - selector: google.cloud.redis.v1.CloudRedis.CreateInstance + deadline: 60.0 + - selector: google.cloud.redis.v1.CloudRedis.UpdateInstance + deadline: 60.0 + - selector: google.cloud.redis.v1.CloudRedis.FailoverInstance + deadline: 60.0 + - selector: google.cloud.redis.v1.CloudRedis.DeleteInstance + deadline: 60.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1/{name=projects/*/locations/*}/operations' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=projects/*/locations/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/{name=projects/*/locations/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/{name=projects/*/locations/*/operations/*}:cancel' + +authentication: + rules: + - selector: 'google.cloud.redis.v1.CloudRedis.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: 'google.longrunning.Operations.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/redis/redis_v1beta1.yaml b/google/cloud/redis/redis_v1beta1.yaml new file mode 100644 index 000000000..1abe57a6d --- /dev/null +++ b/google/cloud/redis/redis_v1beta1.yaml @@ -0,0 +1,61 @@ +type: google.api.Service +config_version: 3 +name: redis.googleapis.com +title: Google Cloud Memorystore for Redis API + +apis: +- name: google.cloud.redis.v1beta1.CloudRedis + +types: +- name: google.cloud.redis.v1beta1.LocationMetadata +- name: google.cloud.redis.v1beta1.ZoneMetadata + +documentation: + summary: Creates and manages Redis instances on the Google Cloud Platform. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 60.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 60.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 60.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 60.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 60.0 + - selector: google.cloud.redis.v1beta1.CloudRedis.ListInstances + deadline: 60.0 + - selector: google.cloud.redis.v1beta1.CloudRedis.GetInstance + deadline: 60.0 + - selector: google.cloud.redis.v1beta1.CloudRedis.CreateInstance + deadline: 60.0 + - selector: google.cloud.redis.v1beta1.CloudRedis.UpdateInstance + deadline: 60.0 + - selector: google.cloud.redis.v1beta1.CloudRedis.FailoverInstance + deadline: 60.0 + - selector: google.cloud.redis.v1beta1.CloudRedis.DeleteInstance + deadline: 60.0 + +http: + rules: + - selector: google.longrunning.Operations.CancelOperation + post: '/v1beta1/{name=projects/*/locations/*/operations/*}:cancel' + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1beta1/{name=projects/*/locations/*/operations/*}' + - selector: google.longrunning.Operations.GetOperation + get: '/v1beta1/{name=projects/*/locations/*/operations/*}' + - selector: google.longrunning.Operations.ListOperations + get: '/v1beta1/{name=projects/*/locations/*}/operations' + +authentication: + rules: + - selector: 'google.cloud.redis.v1beta1.CloudRedis.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: 'google.longrunning.Operations.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/redis/v1/BUILD.bazel b/google/cloud/redis/v1/BUILD.bazel new file mode 100644 index 000000000..6c297792e --- /dev/null +++ b/google/cloud/redis/v1/BUILD.bazel @@ -0,0 +1,147 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "redis_proto", + srcs = [ + "cloud_redis.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/api:resource_proto", + "//google/longrunning:operations_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "redis_proto_with_info", + deps = [":redis_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "redis_java_proto", + deps = [":redis_proto"], +) + +java_grpc_library( + name = "redis_java_grpc", + srcs = [":redis_proto"], + deps = [":redis_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "redis_resource_name_java_proto", + gapic_yaml = "redis_gapic.yaml", + deps = [":redis_proto"], +) + +java_gapic_library( + name = "redis_java_gapic", + src = ":redis_proto_with_info", + gapic_yaml = "redis_gapic.yaml", + service_yaml = "//google/cloud/redis:redis_v1.yaml", + test_deps = [":redis_java_grpc"], + deps = [ + ":redis_java_proto", + ":redis_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":redis_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.redis.v1.CloudRedisClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-redis-v1-java", + client_deps = [":redis_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":redis_java_gapic_test"], + grpc_deps = [":redis_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":redis_java_proto", + ":redis_proto", + ":redis_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "redis_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/redis/v1", + protos = [":redis_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + ], +) + +go_gapic_library( + name = "redis_go_gapic", + src = ":redis_proto_with_info", + gapic_yaml = "redis_gapic.yaml", + importpath = "cloud.google.com/go/redis/apiv1", + service_yaml = "//google/cloud/redis:redis_v1.yaml", + deps = [ + ":redis_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "redis_go_gapic_test", + srcs = [":redis_go_gapic_srcjar_test"], + embed = [":redis_go_gapic"], + importpath = "cloud.google.com/go/redis/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-redis-v1-go", + deps = [ + ":redis_go_gapic", + ":redis_go_gapic_srcjar-smoke-test.srcjar", + ":redis_go_gapic_srcjar-test.srcjar", + ":redis_go_proto", + ], +) diff --git a/google/cloud/redis/v1/cloud_redis.proto b/google/cloud/redis/v1/cloud_redis.proto new file mode 100644 index 000000000..8520addad --- /dev/null +++ b/google/cloud/redis/v1/cloud_redis.proto @@ -0,0 +1,409 @@ +// Copyright 2019 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.redis.v1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/redis/v1;redis"; +option java_multiple_files = true; +option java_outer_classname = "CloudRedisServiceV1Proto"; +option java_package = "com.google.cloud.redis.v1"; + + +// Configures and manages Cloud Memorystore for Redis instances +// +// Google Cloud Memorystore for Redis v1 +// +// The `redis.googleapis.com` service implements the Google Cloud Memorystore +// for Redis API and defines the following resource model for managing Redis +// instances: +// * The service works with a collection of cloud projects, named: `/projects/*` +// * Each project has a collection of available locations, named: `/locations/*` +// * Each location has a collection of Redis instances, named: `/instances/*` +// * As such, Redis instances are resources of the form: +// `/projects/{project_id}/locations/{location_id}/instances/{instance_id}` +// +// Note that location_id must be referring to a GCP `region`; for example: +// * `projects/redpepper-1290/locations/us-central1/instances/my-redis` +service CloudRedis { + // Lists all Redis instances owned by a project in either the specified + // location (region) or all locations. + // + // The location should have the following format: + // * `projects/{project_id}/locations/{location_id}` + // + // If `location_id` is specified as `-` (wildcard), then all regions + // available to the project are queried, and the results are aggregated. + rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/instances" + }; + } + + // Gets the details of a specific Redis instance. + rpc GetInstance(GetInstanceRequest) returns (Instance) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/instances/*}" + }; + } + + // Creates a Redis instance based on the specified tier and memory size. + // + // By default, the instance is accessible from the project's + // [default network](/compute/docs/networks-and-firewalls#networks). + // + // The creation is executed asynchronously and callers may check the returned + // operation to track its progress. Once the operation is completed the Redis + // instance will be fully functional. Completed longrunning.Operation will + // contain the new instance object in the response field. + // + // The returned operation is automatically deleted after a few hours, so there + // is no need to call DeleteOperation. + rpc CreateInstance(CreateInstanceRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/instances" + body: "instance" + }; + } + + // Updates the metadata and configuration of a specific Redis instance. + // + // Completed longrunning.Operation will contain the new instance object + // in the response field. The returned operation is automatically deleted + // after a few hours, so there is no need to call DeleteOperation. + rpc UpdateInstance(UpdateInstanceRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v1/{instance.name=projects/*/locations/*/instances/*}" + body: "instance" + }; + } + + // Failover the master role to current replica node against a specific + // STANDARD tier redis instance. + rpc FailoverInstance(FailoverInstanceRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/instances/*}:failover" + body: "*" + }; + } + + // Deletes a specific Redis instance. Instance stops serving and data is + // deleted. + rpc DeleteInstance(DeleteInstanceRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/instances/*}" + }; + } +} + +// A Google Cloud Redis instance. +message Instance { + // Represents the different states of a Redis instance. + enum State { + // Not set. + STATE_UNSPECIFIED = 0; + + // Redis instance is being created. + CREATING = 1; + + // Redis instance has been created and is fully usable. + READY = 2; + + // Redis instance configuration is being updated. Certain kinds of updates + // may cause the instance to become unusable while the update is in + // progress. + UPDATING = 3; + + // Redis instance is being deleted. + DELETING = 4; + + // Redis instance is being repaired and may be unusable. + REPAIRING = 5; + + // Maintenance is being performed on this Redis instance. + MAINTENANCE = 6; + + // Redis instance is failing over (availability may be affected). + FAILING_OVER = 9; + } + + // Available service tiers to choose from + enum Tier { + // Not set. + TIER_UNSPECIFIED = 0; + + // BASIC tier: standalone instance + BASIC = 1; + + // STANDARD_HA tier: highly available primary/replica instances + STANDARD_HA = 3; + } + + // Required. Unique name of the resource in this scope including project and + // location using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // + // Note: Redis instances are managed and addressed at regional level so + // location_id here refers to a GCP region; however, users may choose which + // specific zone (or collection of zones for cross-zone instances) an instance + // should be provisioned in. Refer to [location_id] and + // [alternative_location_id] fields for more details. + string name = 1; + + // An arbitrary and optional user-provided name for the instance. + string display_name = 2; + + // Resource labels to represent user provided metadata + map<string, string> labels = 3; + + // Optional. The zone where the instance will be provisioned. If not provided, + // the service will choose a zone for the instance. For STANDARD_HA tier, + // instances will be created across two zones for protection against zonal + // failures. If [alternative_location_id] is also provided, it must be + // different from [location_id]. + string location_id = 4; + + // Optional. Only applicable to STANDARD_HA tier which protects the instance + // against zonal failures by provisioning it across two zones. If provided, it + // must be a different zone from the one provided in [location_id]. + string alternative_location_id = 5; + + // Optional. The version of Redis software. + // If not provided, latest supported version will be used. Updating the + // version will perform an upgrade/downgrade to the new version. Currently, + // the supported values are `REDIS_3_2` for Redis 3.2. + string redis_version = 7; + + // Optional. The CIDR range of internal addresses that are reserved for this + // instance. If not provided, the service will choose an unused /29 block, + // for example, 10.0.0.0/29 or 192.168.0.0/29. Ranges must be unique + // and non-overlapping with existing subnets in an authorized network. + string reserved_ip_range = 9; + + // Output only. Hostname or IP address of the exposed Redis endpoint used by + // clients to connect to the service. + string host = 10; + + // Output only. The port number of the exposed Redis endpoint. + int32 port = 11; + + // Output only. The current zone where the Redis endpoint is placed. For Basic + // Tier instances, this will always be the same as the [location_id] + // provided by the user at creation time. For Standard Tier instances, + // this can be either [location_id] or [alternative_location_id] and can + // change after a failover event. + string current_location_id = 12; + + // Output only. The time the instance was created. + google.protobuf.Timestamp create_time = 13; + + // Output only. The current state of this instance. + State state = 14; + + // Output only. Additional information about the current status of this + // instance, if available. + string status_message = 15; + + // Optional. Redis configuration parameters, according to + // http://redis.io/topics/config. Currently, the only supported parameters + // are: + // + // * maxmemory-policy + // * notify-keyspace-events + map<string, string> redis_configs = 16; + + // Required. The service tier of the instance. + Tier tier = 17; + + // Required. Redis memory size in GiB. + int32 memory_size_gb = 18; + + // Optional. The full name of the Google Compute Engine + // [network](/compute/docs/networks-and-firewalls#networks) to which the + // instance is connected. If left unspecified, the `default` network + // will be used. + string authorized_network = 20; +} + +// Request for [ListInstances][google.cloud.redis.v1.CloudRedis.ListInstances]. +message ListInstancesRequest { + // Required. The resource name of the instance location using the form: + // `projects/{project_id}/locations/{location_id}` + // where `location_id` refers to a GCP region + string parent = 1; + + // The maximum number of items to return. + // + // If not specified, a default value of 1000 will be used by the service. + // Regardless of the page_size value, the response may include a partial list + // and a caller should only rely on response's + // [next_page_token][CloudRedis.ListInstancesResponse.next_page_token] + // to determine if there are more instances left to be queried. + int32 page_size = 2; + + // The next_page_token value returned from a previous List request, + // if any. + string page_token = 3; +} + +// Response for [ListInstances][google.cloud.redis.v1.CloudRedis.ListInstances]. +message ListInstancesResponse { + // A list of Redis instances in the project in the specified location, + // or across all locations. + // + // If the `location_id` in the parent field of the request is "-", all regions + // available to the project are queried, and the results aggregated. + // If in such an aggregated query a location is unavailable, a dummy Redis + // entry is included in the response with the "name" field set to a value of + // the form projects/{project_id}/locations/{location_id}/instances/- and the + // "status" field set to ERROR and "status_message" field set to "location not + // available for ListInstances". + repeated Instance instances = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; + + // Locations that could not be reached. + repeated string unreachable = 3; +} + +// Request for [GetInstance][google.cloud.redis.v1.CloudRedis.GetInstance]. +message GetInstanceRequest { + // Required. Redis instance resource name using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // where `location_id` refers to a GCP region + string name = 1; +} + +// Request for [CreateInstance][google.cloud.redis.v1.CloudRedis.CreateInstance]. +message CreateInstanceRequest { + // Required. The resource name of the instance location using the form: + // `projects/{project_id}/locations/{location_id}` + // where `location_id` refers to a GCP region + string parent = 1; + + // Required. The logical name of the Redis instance in the customer project + // with the following restrictions: + // + // * Must contain only lowercase letters, numbers, and hyphens. + // * Must start with a letter. + // * Must be between 1-40 characters. + // * Must end with a number or a letter. + // * Must be unique within the customer project / location + string instance_id = 2; + + // Required. A Redis [Instance] resource + Instance instance = 3; +} + +// Request for [UpdateInstance][google.cloud.redis.v1.CloudRedis.UpdateInstance]. +message UpdateInstanceRequest { + // Required. Mask of fields to update. At least one path must be supplied in + // this field. The elements of the repeated paths field may only include these + // fields from [Instance][CloudRedis.Instance]: + // + // * `displayName` + // * `labels` + // * `memorySizeGb` + // * `redisConfig` + google.protobuf.FieldMask update_mask = 1; + + // Required. Update description. + // Only fields specified in update_mask are updated. + Instance instance = 2; +} + +// Request for [DeleteInstance][google.cloud.redis.v1.CloudRedis.DeleteInstance]. +message DeleteInstanceRequest { + // Required. Redis instance resource name using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // where `location_id` refers to a GCP region + string name = 1; +} + +// Request for [Failover][google.cloud.redis.v1.CloudRedis.FailoverInstance]. +message FailoverInstanceRequest { + enum DataProtectionMode { + DATA_PROTECTION_MODE_UNSPECIFIED = 0; + + // Instance failover will be protected with data loss control. More + // specifically, the failover will only be performed if the current + // replication offset diff between master and replica is under a certain + // threshold. + LIMITED_DATA_LOSS = 1; + + // Instance failover will be performed without data loss control. + FORCE_DATA_LOSS = 2; + } + + // Required. Redis instance resource name using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // where `location_id` refers to a GCP region + string name = 1; + + // Optional. Available data protection modes that the user can choose. If it's + // unspecified, data protection mode will be LIMITED_DATA_LOSS by default. + DataProtectionMode data_protection_mode = 2; +} + +// Represents the v1 metadata of the long-running operation. +message OperationMetadata { + // Creation timestamp. + google.protobuf.Timestamp create_time = 1; + + // End timestamp. + google.protobuf.Timestamp end_time = 2; + + // Operation target. + string target = 3; + + // Operation verb. + string verb = 4; + + // Operation status details. + string status_detail = 5; + + // Specifies if cancellation was requested for the operation. + bool cancel_requested = 6; + + // API version. + string api_version = 7; +} + +// This location metadata represents additional configuration options for a +// given location where a Redis instance may be created. All fields are output +// only. It is returned as content of the +// `google.cloud.location.Location.metadata` field. +message LocationMetadata { + // Output only. The set of available zones in the location. The map is keyed + // by the lowercase ID of each zone, as defined by GCE. These keys can be + // specified in `location_id` or `alternative_location_id` fields when + // creating a Redis instance. + map<string, ZoneMetadata> available_zones = 1; +} + +// Defines specific information for a particular zone. Currently empty and +// reserved for future use only. +message ZoneMetadata { + +} diff --git a/google/cloud/redis/v1/redis_gapic.yaml b/google/cloud/redis/v1/redis_gapic.yaml new file mode 100644 index 000000000..83b49a9aa --- /dev/null +++ b/google/cloud/redis/v1/redis_gapic.yaml @@ -0,0 +1,256 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.redis.v1 + python: + package_name: google.cloud.redis_v1.gapic + go: + package_name: cloud.google.com/go/redis/apiv1 + csharp: + package_name: Google.Cloud.Redis.V1 + ruby: + package_name: Google::Cloud::Redis::V1 + php: + package_name: Google\Cloud\Redis\V1 + nodejs: + package_name: redis.v1 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.redis.v1.CloudRedis + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/instances/{instance} + entity_name: instance + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListInstances + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: instances + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetInstance + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: instance + timeout_millis: 60000 + - name: CreateInstance + flattening: + groups: + - parameters: + - parent + - instance_id + - instance + required_fields: + - parent + - instance_id + - instance + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + long_running: + return_type: google.cloud.redis.v1.Instance + metadata_type: google.cloud.redis.v1.OperationMetadata + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 1200000 # 20 minutes + sample_code_init_fields: + - instance_id="test_instance" + - instance.tier="BASIC" + - instance.memory_size_gb=1 + - name: UpdateInstance + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - update_mask + - instance + required_fields: + - update_mask + - instance + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + instance.name: instance + timeout_millis: 60000 + long_running: + return_type: google.cloud.redis.v1.Instance + metadata_type: google.cloud.redis.v1.OperationMetadata + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 7200000 # 120 minutes + sample_code_init_fields: + - update_mask.paths[0]="display_name" + - update_mask.paths[1]="memory_size_gb" + - instance.display_name="UpdatedDisplayName" + - instance.memory_size_gb=4 + - name: DeleteInstance + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: instance + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.cloud.redis.v1.OperationMetadata + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 1200000 # 20 minutes + - name: FailoverInstance + flattening: + groups: + - parameters: + - name + - data_protection_mode + required_fields: + - name + - data_protection_mode + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: instance + resource_name_treatment: STATIC_TYPES + long_running: + return_type: google.cloud.redis.v1.Instance + metadata_type: google.cloud.redis.v1.OperationMetadata + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 1200000 # 20 minutes + timeout_millis: 60000 +resource_name_generation: +- message_name: ListInstancesRequest + field_entity_map: + parent: location +- message_name: GetInstanceRequest + field_entity_map: + name: instance +- message_name: CreateInstanceRequest + field_entity_map: + parent: location +- message_name: DeleteInstanceRequest + field_entity_map: + name: instance +- message_name: FailoverInstanceRequest + field_entity_map: + name: instance diff --git a/google/cloud/redis/v1beta1/BUILD.bazel b/google/cloud/redis/v1beta1/BUILD.bazel new file mode 100644 index 000000000..ab0090334 --- /dev/null +++ b/google/cloud/redis/v1beta1/BUILD.bazel @@ -0,0 +1,148 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "redis_proto", + srcs = [ + "cloud_redis.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "redis_proto_with_info", + deps = [":redis_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "redis_java_proto", + deps = [":redis_proto"], +) + +java_grpc_library( + name = "redis_java_grpc", + srcs = [":redis_proto"], + deps = [":redis_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "redis_resource_name_java_proto", + gapic_yaml = "redis_gapic.yaml", + deps = [":redis_proto"], +) + +java_gapic_library( + name = "redis_java_gapic", + src = ":redis_proto_with_info", + gapic_yaml = "redis_gapic.yaml", + service_yaml = "//google/cloud/redis:redis_v1beta1.yaml", + test_deps = [":redis_java_grpc"], + deps = [ + ":redis_java_proto", + ":redis_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":redis_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.redis.v1beta1.CloudRedisClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-redis-v1beta1-java", + client_deps = [":redis_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":redis_java_gapic_test"], + grpc_deps = [":redis_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":redis_java_proto", + ":redis_proto", + ":redis_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "redis_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/redis/v1beta1", + protos = [":redis_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + ], +) + +go_gapic_library( + name = "redis_go_gapic", + src = ":redis_proto_with_info", + gapic_yaml = "redis_gapic.yaml", + importpath = "cloud.google.com/go/redis/apiv1beta1", + service_yaml = "//google/cloud/redis:redis_v1beta1.yaml", + deps = [ + ":redis_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + "@io_bazel_rules_go//proto/wkt:any_go_proto", + ], +) + +go_test( + name = "redis_go_gapic_test", + srcs = [":redis_go_gapic_srcjar_test"], + embed = [":redis_go_gapic"], + importpath = "cloud.google.com/go/redis/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-redis-v1beta1-go", + deps = [ + ":redis_go_gapic", + ":redis_go_gapic_srcjar-smoke-test.srcjar", + ":redis_go_gapic_srcjar-test.srcjar", + ":redis_go_proto", + ], +) diff --git a/google/cloud/redis/v1beta1/cloud_redis.proto b/google/cloud/redis/v1beta1/cloud_redis.proto new file mode 100644 index 000000000..0335a0026 --- /dev/null +++ b/google/cloud/redis/v1beta1/cloud_redis.proto @@ -0,0 +1,406 @@ +// Copyright 2019 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.redis.v1beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/redis/v1beta1;redis"; +option java_multiple_files = true; +option java_outer_classname = "CloudRedisServiceBetaProto"; +option java_package = "com.google.cloud.redis.v1beta1"; + +// Configures and manages Cloud Memorystore for Redis instances +// +// Google Cloud Memorystore for Redis v1beta1 +// +// The `redis.googleapis.com` service implements the Google Cloud Memorystore +// for Redis API and defines the following resource model for managing Redis +// instances: +// * The service works with a collection of cloud projects, named: `/projects/*` +// * Each project has a collection of available locations, named: `/locations/*` +// * Each location has a collection of Redis instances, named: `/instances/*` +// * As such, Redis instances are resources of the form: +// `/projects/{project_id}/locations/{location_id}/instances/{instance_id}` +// +// Note that location_id must be refering to a GCP `region`; for example: +// * `projects/redpepper-1290/locations/us-central1/instances/my-redis` +service CloudRedis { + // Lists all Redis instances owned by a project in either the specified + // location (region) or all locations. + // + // The location should have the following format: + // * `projects/{project_id}/locations/{location_id}` + // + // If `location_id` is specified as `-` (wildcard), then all regions + // available to the project are queried, and the results are aggregated. + rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*}/instances" + }; + } + + // Gets the details of a specific Redis instance. + rpc GetInstance(GetInstanceRequest) returns (Instance) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/instances/*}" + }; + } + + // Creates a Redis instance based on the specified tier and memory size. + // + // By default, the instance is accessible from the project's + // [default network](/compute/docs/networks-and-firewalls#networks). + // + // The creation is executed asynchronously and callers may check the returned + // operation to track its progress. Once the operation is completed the Redis + // instance will be fully functional. Completed longrunning.Operation will + // contain the new instance object in the response field. + // + // The returned operation is automatically deleted after a few hours, so there + // is no need to call DeleteOperation. + rpc CreateInstance(CreateInstanceRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/locations/*}/instances" + body: "instance" + }; + } + + // Updates the metadata and configuration of a specific Redis instance. + // + // Completed longrunning.Operation will contain the new instance object + // in the response field. The returned operation is automatically deleted + // after a few hours, so there is no need to call DeleteOperation. + rpc UpdateInstance(UpdateInstanceRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + patch: "/v1beta1/{instance.name=projects/*/locations/*/instances/*}" + body: "instance" + }; + } + + // Failover the master role to current replica node against a specific + // STANDARD tier redis instance. + rpc FailoverInstance(FailoverInstanceRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/instances/*}:failover" + body: "*" + }; + } + + // Deletes a specific Redis instance. Instance stops serving and data is + // deleted. + rpc DeleteInstance(DeleteInstanceRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/locations/*/instances/*}" + }; + } +} + +// A Google Cloud Redis instance. +message Instance { + // Represents the different states of a Redis instance. + enum State { + // Not set. + STATE_UNSPECIFIED = 0; + + // Redis instance is being created. + CREATING = 1; + + // Redis instance has been created and is fully usable. + READY = 2; + + // Redis instance configuration is being updated. Certain kinds of updates + // may cause the instance to become unusable while the update is in + // progress. + UPDATING = 3; + + // Redis instance is being deleted. + DELETING = 4; + + // Redis instance is being repaired and may be unusable. + REPAIRING = 5; + + // Maintenance is being performed on this Redis instance. + MAINTENANCE = 6; + + // Redis instance is importing data (availability may be affected). + IMPORTING = 8; + + // Redis instance is failing over (availability may be affected). + FAILING_OVER = 10; + } + + // Available service tiers to choose from + enum Tier { + // Not set. + TIER_UNSPECIFIED = 0; + + // BASIC tier: standalone instance + BASIC = 1; + + // STANDARD_HA tier: highly available primary/replica instances + STANDARD_HA = 3; + } + + // Required. Unique name of the resource in this scope including project and + // location using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // + // Note: Redis instances are managed and addressed at regional level so + // location_id here refers to a GCP region; however, users may choose which + // specific zone (or collection of zones for cross-zone instances) an instance + // should be provisioned in. Refer to [location_id] and + // [alternative_location_id] fields for more details. + string name = 1; + + // An arbitrary and optional user-provided name for the instance. + string display_name = 2; + + // Resource labels to represent user provided metadata + map<string, string> labels = 3; + + // Optional. The zone where the instance will be provisioned. If not provided, + // the service will choose a zone for the instance. For STANDARD_HA tier, + // instances will be created across two zones for protection against zonal + // failures. If [alternative_location_id] is also provided, it must be + // different from [location_id]. + string location_id = 4; + + // Optional. Only applicable to STANDARD_HA tier which protects the instance + // against zonal failures by provisioning it across two zones. If provided, it + // must be a different zone from the one provided in [location_id]. + string alternative_location_id = 5; + + // Optional. The version of Redis software. + // If not provided, latest supported version will be used. Updating the + // version will perform an upgrade/downgrade to the new version. Currently, + // the supported values are: + // + // * `REDIS_4_0` for Redis 4.0 compatibility + // * `REDIS_3_2` for Redis 3.2 compatibility (default) + string redis_version = 7; + + // Optional. The CIDR range of internal addresses that are reserved for this + // instance. If not provided, the service will choose an unused /29 block, + // for example, 10.0.0.0/29 or 192.168.0.0/29. Ranges must be unique + // and non-overlapping with existing subnets in an authorized network. + string reserved_ip_range = 9; + + // Output only. Hostname or IP address of the exposed Redis endpoint used by + // clients to connect to the service. + string host = 10; + + // Output only. The port number of the exposed Redis endpoint. + int32 port = 11; + + // Output only. The current zone where the Redis endpoint is placed. For Basic + // Tier instances, this will always be the same as the [location_id] + // provided by the user at creation time. For Standard Tier instances, + // this can be either [location_id] or [alternative_location_id] and can + // change after a failover event. + string current_location_id = 12; + + // Output only. The time the instance was created. + google.protobuf.Timestamp create_time = 13; + + // Output only. The current state of this instance. + State state = 14; + + // Output only. Additional information about the current status of this + // instance, if available. + string status_message = 15; + + // Optional. Redis configuration parameters, according to + // http://redis.io/topics/config. Currently, the only supported parameters + // are: + // + // Redis 3.2 and above: + // + // * maxmemory-policy + // * notify-keyspace-events + // + // Redis 4.0 and above: + // + // * activedefrag + // * lfu-log-factor + // * lfu-decay-time + map<string, string> redis_configs = 16; + + // Required. The service tier of the instance. + Tier tier = 17; + + // Required. Redis memory size in GiB. + int32 memory_size_gb = 18; + + // Optional. The full name of the Google Compute Engine + // [network](/compute/docs/networks-and-firewalls#networks) to which the + // instance is connected. If left unspecified, the `default` network + // will be used. + string authorized_network = 20; +} + +// Request for +// [ListInstances][google.cloud.redis.v1beta1.CloudRedis.ListInstances]. +message ListInstancesRequest { + // Required. The resource name of the instance location using the form: + // `projects/{project_id}/locations/{location_id}` + // where `location_id` refers to a GCP region + string parent = 1; + + // The maximum number of items to return. + // + // If not specified, a default value of 1000 will be used by the service. + // Regardless of the page_size value, the response may include a partial list + // and a caller should only rely on response's + // [next_page_token][CloudRedis.ListInstancesResponse.next_page_token] + // to determine if there are more instances left to be queried. + int32 page_size = 2; + + // The next_page_token value returned from a previous List request, + // if any. + string page_token = 3; +} + +// Response for +// [ListInstances][google.cloud.redis.v1beta1.CloudRedis.ListInstances]. +message ListInstancesResponse { + // A list of Redis instances in the project in the specified location, + // or across all locations. + // + // If the `location_id` in the parent field of the request is "-", all regions + // available to the project are queried, and the results aggregated. + // If in such an aggregated query a location is unavailable, a dummy Redis + // entry is included in the response with the "name" field set to a value of + // the form projects/{project_id}/locations/{location_id}/instances/- and the + // "status" field set to ERROR and "status_message" field set to "location not + // available for ListInstances". + repeated Instance instances = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; + + // Locations that could not be reached. + repeated string unreachable = 3; +} + +// Request for [GetInstance][google.cloud.redis.v1beta1.CloudRedis.GetInstance]. +message GetInstanceRequest { + // Required. Redis instance resource name using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // where `location_id` refers to a GCP region + string name = 1; +} + +// Request for +// [CreateInstance][google.cloud.redis.v1beta1.CloudRedis.CreateInstance]. +message CreateInstanceRequest { + // Required. The resource name of the instance location using the form: + // `projects/{project_id}/locations/{location_id}` + // where `location_id` refers to a GCP region + string parent = 1; + + // Required. The logical name of the Redis instance in the customer project + // with the following restrictions: + // + // * Must contain only lowercase letters, numbers, and hyphens. + // * Must start with a letter. + // * Must be between 1-40 characters. + // * Must end with a number or a letter. + // * Must be unique within the customer project / location + string instance_id = 2; + + // Required. A Redis [Instance] resource + Instance instance = 3; +} + +// Request for +// [UpdateInstance][google.cloud.redis.v1beta1.CloudRedis.UpdateInstance]. +message UpdateInstanceRequest { + // Required. Mask of fields to update. At least one path must be supplied in + // this field. The elements of the repeated paths field may only include these + // fields from [Instance][google.cloud.redis.v1beta1.Instance]: + // + // * `displayName` + // * `labels` + // * `memorySizeGb` + // * `redisConfig` + google.protobuf.FieldMask update_mask = 1; + + // Required. Update description. + // Only fields specified in update_mask are updated. + Instance instance = 2; +} + +// Request for +// [DeleteInstance][google.cloud.redis.v1beta1.CloudRedis.DeleteInstance]. +message DeleteInstanceRequest { + // Required. Redis instance resource name using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // where `location_id` refers to a GCP region + string name = 1; +} + +// Request for +// [Failover][google.cloud.redis.v1beta1.CloudRedis.FailoverInstance]. +message FailoverInstanceRequest { + enum DataProtectionMode { + DATA_PROTECTION_MODE_UNSPECIFIED = 0; + + // Instance failover will be protected with data loss control. More + // specifically, the failover will only be performed if the current + // replication offset diff between master and replica is under a certain + // threshold. + LIMITED_DATA_LOSS = 1; + + // Instance failover will be performed without data loss control. + FORCE_DATA_LOSS = 2; + } + + // Required. Redis instance resource name using the form: + // `projects/{project_id}/locations/{location_id}/instances/{instance_id}` + // where `location_id` refers to a GCP region + string name = 1; + + // Optional. Available data protection modes that the user can choose. If it's + // unspecified, data protection mode will be LIMITED_DATA_LOSS by default. + DataProtectionMode data_protection_mode = 2; +} + +// This location metadata represents additional configuration options for a +// given location where a Redis instance may be created. All fields are output +// only. It is returned as content of the +// `google.cloud.location.Location.metadata` field. +message LocationMetadata { + // Output only. The set of available zones in the location. The map is keyed + // by the lowercase ID of each zone, as defined by GCE. These keys can be + // specified in `location_id` or `alternative_location_id` fields when + // creating a Redis instance. + map<string, ZoneMetadata> available_zones = 1; +} + +// Defines specific information for a particular zone. Currently empty and +// reserved for future use only. +message ZoneMetadata {} diff --git a/google/cloud/redis/v1beta1/redis_gapic.yaml b/google/cloud/redis/v1beta1/redis_gapic.yaml new file mode 100644 index 000000000..858b35bf6 --- /dev/null +++ b/google/cloud/redis/v1beta1/redis_gapic.yaml @@ -0,0 +1,252 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.redis.v1beta1 + python: + package_name: google.cloud.redis_v1beta1.gapic + go: + package_name: cloud.google.com/go/redis/apiv1beta1 + csharp: + package_name: Google.Cloud.Redis.V1Beta1 + ruby: + package_name: Google::Cloud::Redis::V1beta1 + php: + package_name: Google\Cloud\Redis\V1beta1 + nodejs: + package_name: redis.v1beta1 +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.redis.v1beta1.CloudRedis + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/instances/{instance} + entity_name: instance + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListInstances + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: instances + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetInstance + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: instance + timeout_millis: 60000 + - name: CreateInstance + flattening: + groups: + - parameters: + - parent + - instance_id + - instance + required_fields: + - parent + - instance_id + - instance + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + long_running: + return_type: google.cloud.redis.v1beta1.Instance + metadata_type: google.protobuf.Any + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 1200000 # 20 minutes + sample_code_init_fields: + - instance_id="test_instance" + - instance.tier="BASIC" + - instance.memory_size_gb=1 + - name: UpdateInstance + flattening: + groups: + - parameters: + - update_mask + - instance + required_fields: + - update_mask + - instance + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + instance.name: instance + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + long_running: + return_type: google.cloud.redis.v1beta1.Instance + metadata_type: google.protobuf.Any + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 7200000 # 120 minutes + sample_code_init_fields: + - update_mask.paths[0]="display_name" + - update_mask.paths[1]="memory_size_gb" + - instance.display_name="UpdatedDisplayName" + - instance.memory_size_gb=4 + - name: DeleteInstance + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: instance + timeout_millis: 60000 + long_running: + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Any + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 1200000 # 20 minutes + - name: FailoverInstance + flattening: + groups: + - parameters: + - name + - data_protection_mode + required_fields: + - name + - data_protection_mode + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: instance + long_running: + return_type: google.cloud.redis.v1beta1.Instance + metadata_type: google.protobuf.Any + initial_poll_delay_millis: 60000 # 1 minutes + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 360000 # 6 minutes + total_poll_timeout_millis: 1200000 # 20 minutes + timeout_millis: 60000 +resource_name_generation: +- message_name: ListInstancesRequest + field_entity_map: + parent: location +- message_name: GetInstanceRequest + field_entity_map: + name: instance +- message_name: CreateInstanceRequest + field_entity_map: + parent: location +- message_name: DeleteInstanceRequest + field_entity_map: + name: instance diff --git a/google/cloud/resourcemanager/artman_cloudresourcemanager.yaml b/google/cloud/resourcemanager/artman_cloudresourcemanager.yaml new file mode 100644 index 000000000..c3d61249c --- /dev/null +++ b/google/cloud/resourcemanager/artman_cloudresourcemanager.yaml @@ -0,0 +1,36 @@ +common: + api_name: cloudresourcemanager + api_version: v2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + - name: google-iam-v1 + proto_path: google/iam/v1 + src_proto_paths: + - v2 + service_yaml: cloudresourcemanager.yaml + gapic_yaml: v2/cloudresourcemanager_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/resourcemanager/cloudresourcemanager.yaml b/google/cloud/resourcemanager/cloudresourcemanager.yaml new file mode 100644 index 000000000..7780c301d --- /dev/null +++ b/google/cloud/resourcemanager/cloudresourcemanager.yaml @@ -0,0 +1,56 @@ +type: google.api.Service +config_version: 1 +name: cloudresourcemanager.googleapis.com +title: Google Cloud Resource Manager API + +apis: +- name: google.cloud.resourcemanager.v2.Folders + +types: +- name: google.cloud.resourcemanager.v2.FolderOperation + +documentation: + summary: |- + The Google Cloud Resource Manager API provides methods for creating, + reading, and updating project metadata. + +backend: + rules: + - selector: google.cloud.resourcemanager.v2.Folders.ListFolders + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.SearchFolders + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.GetFolder + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.CreateFolder + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.UpdateFolder + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.MoveFolder + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.DeleteFolder + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.UndeleteFolder + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.GetIamPolicy + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.SetIamPolicy + deadline: 30.0 + - selector: google.cloud.resourcemanager.v2.Folders.TestIamPermissions + deadline: 30.0 + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: |- + google.cloud.resourcemanager.v2.Folders.GetFolder, + google.cloud.resourcemanager.v2.Folders.GetIamPolicy, + google.cloud.resourcemanager.v2.Folders.ListFolders, + google.cloud.resourcemanager.v2.Folders.SearchFolders + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-platform.read-only diff --git a/google/cloud/resourcemanager/v2/cloudresourcemanager_gapic.yaml b/google/cloud/resourcemanager/v2/cloudresourcemanager_gapic.yaml new file mode 100644 index 000000000..49a394d39 --- /dev/null +++ b/google/cloud/resourcemanager/v2/cloudresourcemanager_gapic.yaml @@ -0,0 +1,302 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.resourcemanager.v2 + python: + package_name: google.cloud.resourcemanager_v2.gapic + go: + package_name: cloud.google.com/go/resourcemanager/apiv2 + csharp: + package_name: Google.Cloud.ResourceManager.V2 + ruby: + package_name: Google::Cloud::ResourceManager::V2 + php: + package_name: Google\Cloud\ResourceManager\V2 + nodejs: + package_name: resourcemanager.v2 + domain_layer_location: google-cloud +collection_oneofs: +- oneof_name: parent_oneof + collection_names: + - organization + - folder +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.resourcemanager.v2.Folders + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: folders/{folder} + entity_name: folder + - name_pattern: organizations/{org_id} + entity_name: organization + # Definition for smoke test. + smoke_test: + method: SearchFolders + init_fields: + - query="" # Returns all folders that the caller has access to. + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 30000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # name - The simple name of the method. + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce + # method overloads which allow a client to directly pass request message + # fields as method parameters. This information may or may not be used, + # depending on the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request + # message. + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the + # resource name formats defined in the field_name_patterns + # and response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a + # paging list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It + # defines which fields match the paging pattern in the request. The + # request consists of a page_size_field and a token_field. The + # page_size_field is the name of the optional field specifying the + # maximum number of elements to be returned in the response. The + # token_field is the name of the field in the request containing the + # page token. + # The response specifies response information of the list method. It + # defines which fields match the paging pattern in the response. The + # response consists of a token_field and a resources_field. The + # token_field is the name of the field in the response containing the + # next page token. The resources_field is the name of the field in the + # response containing the list of resources belonging to the page. + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListFolders + flattening: + groups: + - parameters: + - parent + - show_deleted + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: folders + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: parent_oneof + resource_name_treatment: STATIC_TYPES + timeout_millis: 30000 + - name: SearchFolders + flattening: + groups: + - parameters: + - query + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: folders + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: GetFolder + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: folder + resource_name_treatment: STATIC_TYPES + timeout_millis: 30000 + - name: CreateFolder + flattening: + groups: + - parameters: + - parent + - folder + required_fields: + - parent + - folder + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: parent_oneof + resource_name_treatment: STATIC_TYPES + timeout_millis: 30000 + - name: UpdateFolder + flattening: + groups: + - parameters: + - folder + - update_mask + required_fields: + - folder + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 30000 + - name: MoveFolder + flattening: + groups: + - parameters: + - name + - destination_parent + required_fields: + - name + - destination_parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: folder + destination_parent: parent_oneof + resource_name_treatment: STATIC_TYPES + timeout_millis: 30000 + - name: DeleteFolder + flattening: + groups: + - parameters: + - name + - parameters: + - name + - recursive_delete + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: folder + resource_name_treatment: STATIC_TYPES + timeout_millis: 30000 + - name: UndeleteFolder + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: folder + resource_name_treatment: STATIC_TYPES + timeout_millis: 30000 + - name: GetIamPolicy + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: folder + timeout_millis: 30000 + - name: SetIamPolicy + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: folder + timeout_millis: 30000 + - name: TestIamPermissions + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: folder + timeout_millis: 30000 +resource_name_generation: +- message_name: ListFoldersRequest + field_entity_map: + parent: parent_oneof +- message_name: GetFolderRequest + field_entity_map: + name: folder +- message_name: CreateFolderRequest + field_entity_map: + parent: parent_oneof +- message_name: MoveFolderRequest + field_entity_map: + name: folder + destination_parent: parent_oneof +- message_name: DeleteFolderRequest + field_entity_map: + name: folder +- message_name: UndeleteFolderRequest + field_entity_map: + name: folder +- message_name: Folder + field_entity_map: + name: folder + parent: parent_oneof diff --git a/google/cloud/resourcemanager/v2/folders.proto b/google/cloud/resourcemanager/v2/folders.proto new file mode 100644 index 000000000..b231babfd --- /dev/null +++ b/google/cloud/resourcemanager/v2/folders.proto @@ -0,0 +1,427 @@ +// 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.resourcemanager.v2; + +import "google/api/annotations.proto"; +import "google/iam/v1/iam_policy.proto"; +import "google/iam/v1/policy.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/resourcemanager/v2;resourcemanager"; +option java_multiple_files = true; +option java_outer_classname = "FoldersProto"; +option java_package = "com.google.cloud.resourcemanager.v2"; +option csharp_namespace = "Google.Cloud.ResourceManager.V2"; +option php_namespace = "Google\\Cloud\\ResourceManager\\V2"; + +// Manages Cloud Resource Folders. +// Cloud Resource Folders can be used to organize the resources under an +// organization and to control the IAM policies applied to groups of resources. +service Folders { + // Lists the Folders that are direct descendants of supplied parent resource. + // List provides a strongly consistent view of the Folders underneath + // the specified parent resource. + // List returns Folders sorted based upon the (ascending) lexical ordering + // of their display_name. + // The caller must have `resourcemanager.folders.list` permission on the + // identified parent. + rpc ListFolders(ListFoldersRequest) returns (ListFoldersResponse) { + option (google.api.http) = { + get: "/v2/folders" + }; + } + + // Search for folders that match specific filter criteria. + // Search provides an eventually consistent view of the folders a user has + // access to which meet the specified filter criteria. + // + // This will only return folders on which the caller has the + // permission `resourcemanager.folders.get`. + rpc SearchFolders(SearchFoldersRequest) returns (SearchFoldersResponse) { + option (google.api.http) = { + post: "/v2/folders:search" + body: "*" + }; + } + + // Retrieves a Folder identified by the supplied resource name. + // Valid Folder resource names have the format `folders/{folder_id}` + // (for example, `folders/1234`). + // The caller must have `resourcemanager.folders.get` permission on the + // identified folder. + rpc GetFolder(GetFolderRequest) returns (Folder) { + option (google.api.http) = { + get: "/v2/{name=folders/*}" + }; + } + + // Creates a Folder in the resource hierarchy. + // Returns an Operation which can be used to track the progress of the + // folder creation workflow. + // Upon success the Operation.response field will be populated with the + // created Folder. + // + // In order to succeed, the addition of this new Folder must not violate + // the Folder naming, height or fanout constraints. + // + The Folder's display_name must be distinct from all other Folder's that + // share its parent. + // + The addition of the Folder must not cause the active Folder hierarchy + // to exceed a height of 4. Note, the full active + deleted Folder hierarchy + // is allowed to reach a height of 8; this provides additional headroom when + // moving folders that contain deleted folders. + // + The addition of the Folder must not cause the total number of Folders + // under its parent to exceed 100. + // + // If the operation fails due to a folder constraint violation, + // a PreconditionFailure explaining the violation will be returned. + // If the failure occurs synchronously then the PreconditionFailure + // will be returned via the Status.details field and if it occurs + // asynchronously then the PreconditionFailure will be returned + // via the Operation.error field. + // + // The caller must have `resourcemanager.folders.create` permission on the + // identified parent. + rpc CreateFolder(CreateFolderRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/folders" + body: "folder" + }; + } + + // Updates a Folder, changing its display_name. + // Changes to the folder display_name will be rejected if they violate either + // the display_name formatting rules or naming constraints described in + // the [CreateFolder] documentation. + // + The Folder's display name must start and end with a letter or digit, + // may contain letters, digits, spaces, hyphens and underscores and can be + // no longer than 30 characters. This is captured by the regular expression: + // [\p{L}\p{N}]({\p{L}\p{N}_- ]{0,28}[\p{L}\p{N}])?. + // The caller must have `resourcemanager.folders.update` permission on the + // identified folder. + // + // If the update fails due to the unique name constraint then a + // PreconditionFailure explaining this violation will be returned + // in the Status.details field. + rpc UpdateFolder(UpdateFolderRequest) returns (Folder) { + option (google.api.http) = { + patch: "/v2/{folder.name=folders/*}" + body: "folder" + }; + } + + // Moves a Folder under a new resource parent. + // Returns an Operation which can be used to track the progress of the + // folder move workflow. + // Upon success the Operation.response field will be populated with the + // moved Folder. + // Upon failure, a FolderOperationError categorizing the failure cause will + // be returned - if the failure occurs synchronously then the + // FolderOperationError will be returned via the Status.details field + // and if it occurs asynchronously then the FolderOperation will be returned + // via the the Operation.error field. + // In addition, the Operation.metadata field will be populated with a + // FolderOperation message as an aid to stateless clients. + // Folder moves will be rejected if they violate either the naming, height + // or fanout constraints described in the [CreateFolder] documentation. + // The caller must have `resourcemanager.folders.move` permission on the + // folder's current and proposed new parent. + rpc MoveFolder(MoveFolderRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v2/{name=folders/*}:move" + body: "*" + }; + } + + // Requests deletion of a Folder. The Folder is moved into the + // [DELETE_REQUESTED] state immediately, and is deleted approximately 30 days + // later. This method may only be called on an empty Folder in the [ACTIVE] + // state, where a Folder is empty if it doesn't contain any Folders or + // Projects in the [ACTIVE] state. + // The caller must have `resourcemanager.folders.delete` permission on the + // identified folder. + rpc DeleteFolder(DeleteFolderRequest) returns (Folder) { + option (google.api.http) = { + delete: "/v2/{name=folders/*}" + }; + } + + // Cancels the deletion request for a Folder. This method may only be + // called on a Folder in the [DELETE_REQUESTED] state. + // In order to succeed, the Folder's parent must be in the [ACTIVE] state. + // In addition, reintroducing the folder into the tree must not violate + // folder naming, height and fanout constraints described in the + // [CreateFolder] documentation. + // The caller must have `resourcemanager.folders.undelete` permission on the + // identified folder. + rpc UndeleteFolder(UndeleteFolderRequest) returns (Folder) { + option (google.api.http) = { + post: "/v2/{name=folders/*}:undelete" + body: "*" + }; + } + + // Gets the access control policy for a Folder. The returned policy may be + // empty if no such policy or resource exists. The `resource` field should + // be the Folder's resource name, e.g. "folders/1234". + // The caller must have `resourcemanager.folders.getIamPolicy` permission + // on the identified folder. + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2/{resource=folders/*}:getIamPolicy" + body: "*" + }; + } + + // Sets the access control policy on a Folder, replacing any existing policy. + // The `resource` field should be the Folder's resource name, e.g. + // "folders/1234". + // The caller must have `resourcemanager.folders.setIamPolicy` permission + // on the identified folder. + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2/{resource=folders/*}:setIamPolicy" + body: "*" + }; + } + + // Returns permissions that a caller has on the specified Folder. + // The `resource` field should be the Folder's resource name, + // e.g. "folders/1234". + // + // There are no permissions required for making this API call. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) + returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v2/{resource=folders/*}:testIamPermissions" + body: "*" + }; + } +} + +// A Folder in an Organization's resource hierarchy, used to +// organize that Organization's resources. +message Folder { + // Folder lifecycle states. + enum LifecycleState { + // Unspecified state. + LIFECYCLE_STATE_UNSPECIFIED = 0; + + // The normal and active state. + ACTIVE = 1; + + // The folder has been marked for deletion by the user. + DELETE_REQUESTED = 2; + } + + // Output only. The resource name of the Folder. + // Its format is `folders/{folder_id}`, for example: "folders/1234". + string name = 1; + + // The Folder’s parent's resource name. + // Updates to the folder's parent must be performed via [MoveFolders]. + string parent = 2; + + // The folder’s display name. + // A folder’s display name must be unique amongst its siblings, e.g. + // no two folders with the same parent can share the same display name. + // The display name must start and end with a letter or digit, may contain + // letters, digits, spaces, hyphens and underscores and can be no longer + // than 30 characters. This is captured by the regular expression: + // [\p{L}\p{N}]({\p{L}\p{N}_- ]{0,28}[\p{L}\p{N}])?. + string display_name = 3; + + // Output only. The lifecycle state of the folder. + // Updates to the lifecycle_state must be performed via + // [DeleteFolder] and [UndeleteFolder]. + LifecycleState lifecycle_state = 4; + + // Output only. Timestamp when the Folder was created. Assigned by the server. + google.protobuf.Timestamp create_time = 5; + + // Output only. Timestamp when the Folder was last modified. + google.protobuf.Timestamp update_time = 6; +} + +// The ListFolders request message. +message ListFoldersRequest { + // The resource name of the Organization or Folder whose Folders are + // being listed. + // Must be of the form `folders/{folder_id}` or `organizations/{org_id}`. + // Access to this method is controlled by checking the + // `resourcemanager.folders.list` permission on the `parent`. + string parent = 1; + + // The maximum number of Folders to return in the response. + // This field is optional. + int32 page_size = 2; + + // A pagination token returned from a previous call to `ListFolders` + // that indicates where this listing should continue from. + // This field is optional. + string page_token = 3; + + // Controls whether Folders in the [DELETE_REQUESTED} state should + // be returned. + bool show_deleted = 4; +} + +// The ListFolders response message. +message ListFoldersResponse { + // A possibly paginated list of Folders that are direct descendants of + // the specified parent resource. + repeated Folder folders = 1; + + // A pagination token returned from a previous call to `ListFolders` + // that indicates from where listing should continue. + // This field is optional. + string next_page_token = 2; +} + +// The request message for searching folders. +message SearchFoldersRequest { + // The maximum number of folders to return in the response. + // This field is optional. + int32 page_size = 1; + + // A pagination token returned from a previous call to `SearchFolders` + // that indicates from where search should continue. + // This field is optional. + string page_token = 2; + + // Search criteria used to select the Folders to return. + // If no search criteria is specified then all accessible folders will be + // returned. + // + // Query expressions can be used to restrict results based upon displayName, + // lifecycleState and parent, where the operators `=`, `NOT`, `AND` and `OR` + // can be used along with the suffix wildcard symbol `*`. + // + // Some example queries are: + // |Query|Description| + // |------|-----------| + // |displayName=Test*|Folders whose display name starts with "Test".| + // |lifecycleState=ACTIVE|Folders whose lifecycleState is ACTIVE.| + // |parent=folders/123|Folders whose parent is "folders/123".| + // |parent=folders/123 AND lifecycleState=ACTIVE|Active folders whose + // parent is "folders/123".| + string query = 3; +} + +// The response message for searching folders. +message SearchFoldersResponse { + // A possibly paginated folder search results. + // the specified parent resource. + repeated Folder folders = 1; + + // A pagination token returned from a previous call to `SearchFolders` + // that indicates from where searching should continue. + // This field is optional. + string next_page_token = 2; +} + +// The GetFolder request message. +message GetFolderRequest { + // The resource name of the Folder to retrieve. + // Must be of the form `folders/{folder_id}`. + string name = 1; +} + +// The CreateFolder request message. +message CreateFolderRequest { + // The resource name of the new Folder's parent. + // Must be of the form `folders/{folder_id}` or `organizations/{org_id}`. + string parent = 1; + + // The Folder being created, only the display name will be consulted. + // All other fields will be ignored. + Folder folder = 2; +} + +// The MoveFolder request message. +message MoveFolderRequest { + // The resource name of the Folder to move. + // Must be of the form folders/{folder_id} + string name = 1; + + // The resource name of the Folder or Organization to reparent + // the folder under. + // Must be of the form `folders/{folder_id}` or `organizations/{org_id}`. + string destination_parent = 2; +} + +// The request message for updating a folder's display name. +message UpdateFolderRequest { + // The new definition of the Folder. It must include a + // a `name` and `display_name` field. The other fields + // will be ignored. + Folder folder = 1; + + // Fields to be updated. + // Only the `display_name` can be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// The DeleteFolder request message. +message DeleteFolderRequest { + // the resource name of the Folder to be deleted. + // Must be of the form `folders/{folder_id}`. + string name = 1; + + // Instructs DeleteFolderAction to delete a folder even when the folder is not + // empty. + bool recursive_delete = 2; +} + +// The UndeleteFolder request message. +message UndeleteFolderRequest { + // The resource name of the Folder to undelete. + // Must be of the form `folders/{folder_id}`. + string name = 1; +} + +// Metadata describing a long running folder operation +message FolderOperation { + // The type of operation that failed. + enum OperationType { + // Operation type not specified. + OPERATION_TYPE_UNSPECIFIED = 0; + + // A create folder operation. + CREATE = 1; + + // A move folder operation. + MOVE = 2; + } + + // The display name of the folder. + string display_name = 1; + + // The type of this operation. + OperationType operation_type = 2; + + // The resource name of the folder's parent. + // Only applicable when the operation_type is MOVE. + string source_parent = 3; + + // The resource name of the folder or organization we are either creating + // the folder under or moving the folder to. + string destination_parent = 4; +} diff --git a/google/cloud/runtimeconfig/BUILD.bazel b/google/cloud/runtimeconfig/BUILD.bazel new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/google/cloud/runtimeconfig/BUILD.bazel diff --git a/google/cloud/runtimeconfig/README.md b/google/cloud/runtimeconfig/README.md new file mode 100644 index 000000000..49c1d8717 --- /dev/null +++ b/google/cloud/runtimeconfig/README.md @@ -0,0 +1,39 @@ +[TOC] + +# Introduction + +The RuntimeConfig service provides Google Cloud Platform users the ability to +dynamically configure your service. + +The RuntimConfig service creates and manages RuntimeConfig resources +within a Google Cloud Project and various variables within said resource. + +## Details + +Each cloud project can create multiple **Config** objects. A **Config** object +by itself does not contain any configuration information, but rather is a +logical grouping of variables. Variable names are hierarchical and follow file +system style, where only leaf nodes can contain values. + +For example, you can have a configuration called *Flags*. Within that +configuration object, you can create the following variables. + +* `/ports/service_port` +* `/ports/monitoring_port` +* `/ports/admin_port` + +This creates three variables: `/ports/serve_port`, `/ports/monitoring_port`, +`/ports/admin_port`. Note that `/ports` cannot have a value but it can be +listed. + +### Setup + +In order to make requests to RuntimeConfig service, you need to enable the API +for your project. + +To achieve that, go to the +[Google Cloud Console](https://console.cloud.google.com/apis/api/runtimeconfig.googleapis.com/overview) +and enable *Google Cloud RuntimeConfig API* for your project. + +The documentation for this service is located +[here](https://cloud.google.com/deployment-manager/runtime-configurator/reference/rest/). diff --git a/google/cloud/runtimeconfig/runtimeconfig.yaml b/google/cloud/runtimeconfig/runtimeconfig.yaml new file mode 100644 index 000000000..1f66c9b60 --- /dev/null +++ b/google/cloud/runtimeconfig/runtimeconfig.yaml @@ -0,0 +1,49 @@ +type: google.api.Service +config_version: 3 +name: runtimeconfig.googleapis.com +title: Google Cloud RuntimeConfig API + +apis: +- name: google.longrunning.Operations +- name: google.cloud.runtimeconfig.v1beta1.RuntimeConfigManager +- name: google.iam.v1.IAMPolicy + +# Documentation section +documentation: + summary: + Provides capabilities for dynamic configuration and coordination for applications running on Google Cloud Platform. + + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1beta1/{name=projects/*/configs/*/operations/**}' + + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + post: '/v1beta1/{resource=projects/*/configs/*}:setIamPolicy' + body: '*' + + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + get: '/v1beta1/{resource=projects/*/configs/*}:getIamPolicy' + + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + post: '/v1beta1/{resource=projects/*/configs/*}:testIamPermissions' + body: '*' + additional_bindings: + - post: '/v1beta1/{resource=projects/*/configs/*/waiters/*}:testIamPermissions' + body: '*' + + - post: '/v1beta1/{resource=projects/*/configs/*/variables/**}:testIamPermissions' + body: '*' + + - post: '/v1beta1/{resource=projects/*/configs/*/operations/**}:testIamPermissions' + body: '*' + + +# Auth section +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloudruntimeconfig diff --git a/google/cloud/runtimeconfig/v1beta1/resources.proto b/google/cloud/runtimeconfig/v1beta1/resources.proto new file mode 100644 index 000000000..165cbf78a --- /dev/null +++ b/google/cloud/runtimeconfig/v1beta1/resources.proto @@ -0,0 +1,209 @@ +// 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.runtimeconfig.v1beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.RuntimeConfig.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/runtimeconfig/v1beta1;runtimeconfig"; +option java_multiple_files = true; +option java_package = "com.google.cloud.runtimeconfig.v1beta1"; +option php_namespace = "Google\\Cloud\\RuntimeConfig\\V1beta1"; + +// A RuntimeConfig resource is the primary resource in the Cloud RuntimeConfig +// service. A RuntimeConfig resource consists of metadata and a hierarchy of +// variables. +message RuntimeConfig { + // The resource name of a runtime config. The name must have the format: + // + // projects/[PROJECT_ID]/configs/[CONFIG_NAME] + // + // The `[PROJECT_ID]` must be a valid project ID, and `[CONFIG_NAME]` is an + // arbitrary name that matches RFC 1035 segment specification. The length of + // `[CONFIG_NAME]` must be less than 64 bytes. + // + // You pick the RuntimeConfig resource name, but the server will validate that + // the name adheres to this format. After you create the resource, you cannot + // change the resource's name. + string name = 1; + + // An optional description of the RuntimeConfig object. + string description = 2; +} + +// Describes a single variable within a RuntimeConfig resource. +// The name denotes the hierarchical variable name. For example, +// `ports/serving_port` is a valid variable name. The variable value is an +// opaque string and only leaf variables can have values (that is, variables +// that do not have any child variables). +message Variable { + // The name of the variable resource, in the format: + // + // projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_NAME] + // + // The `[PROJECT_ID]` must be a valid project ID, `[CONFIG_NAME]` must be a + // valid RuntimeConfig reource and `[VARIABLE_NAME]` follows Unix file system + // file path naming. + // + // The `[VARIABLE_NAME]` can contain ASCII letters, numbers, slashes and + // dashes. Slashes are used as path element separators and are not part of the + // `[VARIABLE_NAME]` itself, so `[VARIABLE_NAME]` must contain at least one + // non-slash character. Multiple slashes are coalesced into single slash + // character. Each path segment should follow RFC 1035 segment specification. + // The length of a `[VARIABLE_NAME]` must be less than 256 bytes. + // + // Once you create a variable, you cannot change the variable name. + string name = 1; + + // The value of the variable. It can be either a binary or a string + // value. You must specify one of either `value` or `text`. Specifying both + // will cause the server to return an error. + oneof contents { + // The binary value of the variable. The length of the value must be less + // than 4096 bytes. Empty values are also accepted. The value must be + // base64 encoded. Only one of `value` or `text` can be set. + bytes value = 2; + + // The string value of the variable. The length of the value must be less + // than 4096 bytes. Empty values are also accepted. For example, + // `text: "my text value"`. The string must be valid UTF-8. + string text = 5; + } + + // [Output Only] The time of the last variable update. + google.protobuf.Timestamp update_time = 3; + + // [Ouput only] The current state of the variable. The variable state + // indicates the outcome of the `variables().watch` call and is visible + // through the `get` and `list` calls. + VariableState state = 4; +} + +// The condition that a Waiter resource is waiting for. +message EndCondition { + // A Cardinality condition for the Waiter resource. A cardinality condition is + // met when the number of variables under a specified path prefix reaches a + // predefined number. For example, if you set a Cardinality condition where + // the `path` is set to `/foo` and the number of paths is set to 2, the + // following variables would meet the condition in a RuntimeConfig resource: + // + // + `/foo/variable1 = "value1"` + // + `/foo/variable2 = "value2"` + // + `/bar/variable3 = "value3"` + // + // It would not would not satisify the same condition with the `number` set to + // 3, however, because there is only 2 paths that start with `/foo`. + // Cardinality conditions are recursive; all subtrees under the specific + // path prefix are counted. + message Cardinality { + // The root of the variable subtree to monitor. For example, `/foo`. + string path = 1; + + // The number variables under the `path` that must exist to meet this + // condition. Defaults to 1 if not specified. + int32 number = 2; + } + + // The condition oneof holds the available condition types for this + // EndCondition. Currently, the only available type is Cardinality. + oneof condition { + // The cardinality of the `EndCondition`. + Cardinality cardinality = 1; + } +} + +// A Waiter resource waits for some end condition within a RuntimeConfig +// resource to be met before it returns. For example, assume you have a +// distributed system where each node writes to a Variable resource indidicating +// the node's readiness as part of the startup process. +// +// You then configure a Waiter resource with the success condition set to wait +// until some number of nodes have checked in. Afterwards, your application +// runs some arbitrary code after the condition has been met and the waiter +// returns successfully. +// +// Once created, a Waiter resource is immutable. +// +// To learn more about using waiters, read the +// [Creating a +// Waiter](/deployment-manager/runtime-configurator/creating-a-waiter) +// documentation. +message Waiter { + // The name of the Waiter resource, in the format: + // + // projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME] + // + // The `[PROJECT_ID]` must be a valid Google Cloud project ID, + // the `[CONFIG_NAME]` must be a valid RuntimeConfig resource, the + // `[WAITER_NAME]` must match RFC 1035 segment specification, and the length + // of `[WAITER_NAME]` must be less than 64 bytes. + // + // After you create a Waiter resource, you cannot change the resource name. + string name = 1; + + // [Required] Specifies the timeout of the waiter in seconds, beginning from + // the instant that `waiters().create` method is called. If this time elapses + // before the success or failure conditions are met, the waiter fails and sets + // the `error` code to `DEADLINE_EXCEEDED`. + google.protobuf.Duration timeout = 2; + + // [Optional] The failure condition of this waiter. If this condition is met, + // `done` will be set to `true` and the `error` code will be set to `ABORTED`. + // The failure condition takes precedence over the success condition. If both + // conditions are met, a failure will be indicated. This value is optional; if + // no failure condition is set, the only failure scenario will be a timeout. + EndCondition failure = 3; + + // [Required] The success condition. If this condition is met, `done` will be + // set to `true` and the `error` value will remain unset. The failure + // condition takes precedence over the success condition. If both conditions + // are met, a failure will be indicated. + EndCondition success = 4; + + // [Output Only] The instant at which this Waiter resource was created. Adding + // the value of `timeout` to this instant yields the timeout deadline for the + // waiter. + google.protobuf.Timestamp create_time = 5; + + // [Output Only] If the value is `false`, it means the waiter is still waiting + // for one of its conditions to be met. + // + // If true, the waiter has finished. If the waiter finished due to a timeout + // or failure, `error` will be set. + bool done = 6; + + // [Output Only] If the waiter ended due to a failure or timeout, this value + // will be set. + google.rpc.Status error = 7; +} + +// The `VariableState` describes the last known state of the variable and is +// used during a `variables().watch` call to distinguish the state of the +// variable. +enum VariableState { + // Default variable state. + VARIABLE_STATE_UNSPECIFIED = 0; + + // The variable was updated, while `variables().watch` was executing. + UPDATED = 1; + + // The variable was deleted, while `variables().watch` was executing. + DELETED = 2; +} diff --git a/google/cloud/runtimeconfig/v1beta1/runtimeconfig.proto b/google/cloud/runtimeconfig/v1beta1/runtimeconfig.proto new file mode 100644 index 000000000..fbd1d4105 --- /dev/null +++ b/google/cloud/runtimeconfig/v1beta1/runtimeconfig.proto @@ -0,0 +1,451 @@ +// 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.runtimeconfig.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/runtimeconfig/v1beta1/resources.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.RuntimeConfig.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/runtimeconfig/v1beta1;runtimeconfig"; +option java_multiple_files = true; +option java_package = "com.google.cloud.runtimeconfig.v1beta1"; +option php_namespace = "Google\\Cloud\\RuntimeConfig\\V1beta1"; + +// RuntimeConfig API represents configuration objects and operations on those +// configuration objects. +// RuntimeConfig objects consist of Variables logically grouped in the those +// objects. +// Variables are simple key-value pairs. Variables can be watched for changes or +// deletions. Variable key can be hieararchical, e.g. ports/serving_port, +// ports/monitoring_port, etc. Variable names can be hierarchical. No variable +// name can be prefix of another. +// Config objects represent logical containers for variables, e.g. flags, +// passwords, etc. +service RuntimeConfigManager { + // Lists all the RuntimeConfig resources within project. + rpc ListConfigs(ListConfigsRequest) returns (ListConfigsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*}/configs" + }; + } + + // Gets information about a RuntimeConfig resource. + rpc GetConfig(GetConfigRequest) returns (RuntimeConfig) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/configs/*}" + }; + } + + // Creates a new RuntimeConfig resource. The configuration name must be + // unique within project. + rpc CreateConfig(CreateConfigRequest) returns (RuntimeConfig) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*}/configs" + body: "config" + }; + } + + // Updates a RuntimeConfig resource. The configuration must exist beforehand. + rpc UpdateConfig(UpdateConfigRequest) returns (RuntimeConfig) { + option (google.api.http) = { + put: "/v1beta1/{name=projects/*/configs/*}" + body: "config" + }; + } + + // Deletes a RuntimeConfig resource. + rpc DeleteConfig(DeleteConfigRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/configs/*}" + }; + } + + // Lists variables within given a configuration, matching any provided + // filters. This only lists variable names, not the values, unless + // `return_values` is true, in which case only variables that user has IAM + // permission to GetVariable will be returned. + rpc ListVariables(ListVariablesRequest) returns (ListVariablesResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/configs/*}/variables" + }; + } + + // Gets information about a single variable. + rpc GetVariable(GetVariableRequest) returns (Variable) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/configs/*/variables/**}" + }; + } + + // Watches a specific variable and waits for a change in the variable's value. + // When there is a change, this method returns the new value or times out. + // + // If a variable is deleted while being watched, the `variableState` state is + // set to `DELETED` and the method returns the last known variable `value`. + // + // If you set the deadline for watching to a larger value than internal + // timeout (60 seconds), the current variable value is returned and the + // `variableState` will be `VARIABLE_STATE_UNSPECIFIED`. + // + // To learn more about creating a watcher, read the + // [Watching a Variable for + // Changes](/deployment-manager/runtime-configurator/watching-a-variable) + // documentation. + rpc WatchVariable(WatchVariableRequest) returns (Variable) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/configs/*/variables/**}:watch" + body: "*" + }; + } + + // Creates a variable within the given configuration. You cannot create + // a variable with a name that is a prefix of an existing variable name, or a + // name that has an existing variable name as a prefix. + // + // To learn more about creating a variable, read the + // [Setting and Getting + // Data](/deployment-manager/runtime-configurator/set-and-get-variables) + // documentation. + rpc CreateVariable(CreateVariableRequest) returns (Variable) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/configs/*}/variables" + body: "variable" + }; + } + + // Updates an existing variable with a new value. + rpc UpdateVariable(UpdateVariableRequest) returns (Variable) { + option (google.api.http) = { + put: "/v1beta1/{name=projects/*/configs/*/variables/**}" + body: "variable" + }; + } + + // Deletes a variable or multiple variables. + // + // If you specify a variable name, then that variable is deleted. If you + // specify a prefix and `recursive` is true, then all variables with that + // prefix are deleted. You must set a `recursive` to true if you delete + // variables by prefix. + rpc DeleteVariable(DeleteVariableRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/configs/*/variables/**}" + }; + } + + // List waiters within the given configuration. + rpc ListWaiters(ListWaitersRequest) returns (ListWaitersResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/configs/*}/waiters" + }; + } + + // Gets information about a single waiter. + rpc GetWaiter(GetWaiterRequest) returns (Waiter) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/configs/*/waiters/*}" + }; + } + + // Creates a Waiter resource. This operation returns a long-running Operation + // resource which can be polled for completion. However, a waiter with the + // given name will exist (and can be retrieved) prior to the operation + // completing. If the operation fails, the failed Waiter resource will + // still exist and must be deleted prior to subsequent creation attempts. + rpc CreateWaiter(CreateWaiterRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/configs/*}/waiters" + body: "waiter" + }; + } + + // Deletes the waiter with the specified name. + rpc DeleteWaiter(DeleteWaiterRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/configs/*/waiters/*}" + }; + } +} + +// Request for the `ListConfigs()` method. +message ListConfigsRequest { + // The [project + // ID](https://support.google.com/cloud/answer/6158840?hl=en&ref_topic=6158848) + // for this request, in the format `projects/[PROJECT_ID]`. + string parent = 1; + + // Specifies the number of results to return per page. If there are fewer + // elements than the specified number, returns all elements. + int32 page_size = 2; + + // Specifies a page token to use. Set `pageToken` to a `nextPageToken` + // returned by a previous list request to get the next page of results. + string page_token = 3; +} + +// `ListConfigs()` returns the following response. The order of returned +// objects is arbitrary; that is, it is not ordered in any particular way. +message ListConfigsResponse { + // A list of the configurations in the project. The order of returned + // objects is arbitrary; that is, it is not ordered in any particular way. + repeated RuntimeConfig configs = 1; + + // This token allows you to get the next page of results for list requests. + // If the number of results is larger than `pageSize`, use the `nextPageToken` + // as a value for the query parameter `pageToken` in the next list request. + // Subsequent list requests will have their own `nextPageToken` to continue + // paging through the results + string next_page_token = 2; +} + +// Gets a RuntimeConfig resource. +message GetConfigRequest { + // The name of the RuntimeConfig resource to retrieve, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]` + string name = 2; +} + +// Creates a RuntimeConfig resource. +message CreateConfigRequest { + // The [project + // ID](https://support.google.com/cloud/answer/6158840?hl=en&ref_topic=6158848) + // for this request, in the format `projects/[PROJECT_ID]`. + string parent = 1; + + // The RuntimeConfig to create. + RuntimeConfig config = 2; + + // An optional but recommended unique `request_id`. If the server + // receives two `create()` requests with the same + // `request_id`, then the second request will be ignored and the + // first resource created and stored in the backend is returned. + // Empty `request_id` fields are ignored. + // + // It is responsibility of the client to ensure uniqueness of the + // `request_id` strings. + // + // `request_id` strings are limited to 64 characters. + string request_id = 3; +} + +// Request message for `UpdateConfig()` method. +message UpdateConfigRequest { + // The name of the RuntimeConfig resource to update, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]` + string name = 1; + + // The config resource to update. + RuntimeConfig config = 2; +} + +// Request for the `DeleteConfig()` method. +message DeleteConfigRequest { + // The RuntimeConfig resource to delete, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]` + string name = 1; +} + +// Request for the `ListVariables()` method. +message ListVariablesRequest { + // The path to the RuntimeConfig resource for which you want to list + // variables. The configuration must exist beforehand; the path must by in the + // format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]` + string parent = 1; + + // Filters variables by matching the specified filter. For example: + // + // `projects/example-project/config/[CONFIG_NAME]/variables/example-variable`. + string filter = 2; + + // Specifies the number of results to return per page. If there are fewer + // elements than the specified number, returns all elements. + int32 page_size = 3; + + // Specifies a page token to use. Set `pageToken` to a `nextPageToken` + // returned by a previous list request to get the next page of results. + string page_token = 4; + + // The flag indicates whether the user wants to return values of variables. + // If true, then only those variables that user has IAM GetVariable permission + // will be returned along with their values. + bool return_values = 5; +} + +// Response for the `ListVariables()` method. +message ListVariablesResponse { + // A list of variables and their values. The order of returned variable + // objects is arbitrary. + repeated Variable variables = 1; + + // This token allows you to get the next page of results for list requests. + // If the number of results is larger than `pageSize`, use the `nextPageToken` + // as a value for the query parameter `pageToken` in the next list request. + // Subsequent list requests will have their own `nextPageToken` to continue + // paging through the results + string next_page_token = 2; +} + +// Request for the `WatchVariable()` method. +message WatchVariableRequest { + // The name of the variable to watch, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]` + string name = 1; + + // If specified, checks the current timestamp of the variable and if the + // current timestamp is newer than `newerThan` timestamp, the method returns + // immediately. + // + // If not specified or the variable has an older timestamp, the watcher waits + // for a the value to change before returning. + google.protobuf.Timestamp newer_than = 4; +} + +// Request for the `GetVariable()` method. +message GetVariableRequest { + // The name of the variable to return, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIBLE_NAME]` + string name = 1; +} + +// Request for the `CreateVariable()` method. +message CreateVariableRequest { + // The path to the RutimeConfig resource that this variable should belong to. + // The configuration must exist beforehand; the path must by in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]` + string parent = 1; + + // The variable to create. + Variable variable = 2; + + // An optional but recommended unique `request_id`. If the server + // receives two `create()` requests with the same + // `request_id`, then the second request will be ignored and the + // first resource created and stored in the backend is returned. + // Empty `request_id` fields are ignored. + // + // It is responsibility of the client to ensure uniqueness of the + // `request_id` strings. + // + // `request_id` strings are limited to 64 characters. + string request_id = 3; +} + +// Request for the `UpdateVariable()` method. +message UpdateVariableRequest { + // The name of the variable to update, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_NAME]` + string name = 1; + + // The variable to update. + Variable variable = 2; +} + +// Request for the `DeleteVariable()` method. +message DeleteVariableRequest { + // The name of the variable to delete, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_NAME]` + string name = 1; + + // Set to `true` to recursively delete multiple variables with the same + // prefix. + bool recursive = 2; +} + +// Request for the `ListWaiters()` method. +message ListWaitersRequest { + // The path to the configuration for which you want to get a list of waiters. + // The configuration must exist beforehand; the path must by in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]` + string parent = 1; + + // Specifies the number of results to return per page. If there are fewer + // elements than the specified number, returns all elements. + int32 page_size = 2; + + // Specifies a page token to use. Set `pageToken` to a `nextPageToken` + // returned by a previous list request to get the next page of results. + string page_token = 3; +} + +// Response for the `ListWaiters()` method. +// Order of returned waiter objects is arbitrary. +message ListWaitersResponse { + // Found waiters in the project. + repeated Waiter waiters = 1; + + // This token allows you to get the next page of results for list requests. + // If the number of results is larger than `pageSize`, use the `nextPageToken` + // as a value for the query parameter `pageToken` in the next list request. + // Subsequent list requests will have their own `nextPageToken` to continue + // paging through the results + string next_page_token = 2; +} + +// Request for the `GetWaiter()` method. +message GetWaiterRequest { + // The fully-qualified name of the Waiter resource object to retrieve, in the + // format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]` + string name = 1; +} + +// Request message for `CreateWaiter()` method. +message CreateWaiterRequest { + // The path to the configuration that will own the waiter. + // The configuration must exist beforehand; the path must by in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]`. + string parent = 1; + + // The Waiter resource to create. + Waiter waiter = 2; + + // An optional but recommended unique `request_id`. If the server + // receives two `create()` requests with the same + // `request_id`, then the second request will be ignored and the + // first resource created and stored in the backend is returned. + // Empty `request_id` fields are ignored. + // + // It is responsibility of the client to ensure uniqueness of the + // `request_id` strings. + // + // `request_id` strings are limited to 64 characters. + string request_id = 3; +} + +// Request for the `DeleteWaiter()` method. +message DeleteWaiterRequest { + // The Waiter resource to delete, in the format: + // + // `projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]` + string name = 1; +} diff --git a/google/cloud/scheduler/BUILD.bazel b/google/cloud/scheduler/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/scheduler/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/scheduler/artman_cloudscheduler_v1.yaml b/google/cloud/scheduler/artman_cloudscheduler_v1.yaml new file mode 100644 index 000000000..ab2c4fa10 --- /dev/null +++ b/google/cloud/scheduler/artman_cloudscheduler_v1.yaml @@ -0,0 +1,34 @@ +common: + api_name: cloudscheduler + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: cloudscheduler_v1.yaml + gapic_yaml: v1/cloudscheduler_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/scheduler/artman_cloudscheduler_v1beta1.yaml b/google/cloud/scheduler/artman_cloudscheduler_v1beta1.yaml new file mode 100644 index 000000000..44313ae1b --- /dev/null +++ b/google/cloud/scheduler/artman_cloudscheduler_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: cloudscheduler + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: cloudscheduler_v1beta1.yaml + gapic_yaml: v1beta1/cloudscheduler_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/scheduler/cloudscheduler_v1.yaml b/google/cloud/scheduler/cloudscheduler_v1.yaml new file mode 100644 index 000000000..0ed2ecd80 --- /dev/null +++ b/google/cloud/scheduler/cloudscheduler_v1.yaml @@ -0,0 +1,36 @@ +type: google.api.Service +config_version: 3 +name: cloudscheduler.googleapis.com +title: Cloud Scheduler API + +apis: + - name: google.cloud.scheduler.v1.CloudScheduler + +documentation: + summary: Creates and manages jobs run on a regular recurring schedule. + +backend: + rules: + - selector: google.cloud.scheduler.v1.CloudScheduler.ListJobs + deadline: 30.0 + - selector: google.cloud.scheduler.v1.CloudScheduler.GetJob + deadline: 30.0 + - selector: google.cloud.scheduler.v1.CloudScheduler.CreateJob + deadline: 30.0 + - selector: google.cloud.scheduler.v1.CloudScheduler.UpdateJob + deadline: 30.0 + - selector: google.cloud.scheduler.v1.CloudScheduler.DeleteJob + deadline: 30.0 + - selector: google.cloud.scheduler.v1.CloudScheduler.PauseJob + deadline: 30.0 + - selector: google.cloud.scheduler.v1.CloudScheduler.ResumeJob + deadline: 30.0 + - selector: google.cloud.scheduler.v1.CloudScheduler.RunJob + deadline: 30.0 + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/scheduler/cloudscheduler_v1beta1.yaml b/google/cloud/scheduler/cloudscheduler_v1beta1.yaml new file mode 100644 index 000000000..8b9fdadca --- /dev/null +++ b/google/cloud/scheduler/cloudscheduler_v1beta1.yaml @@ -0,0 +1,22 @@ +type: google.api.Service +config_version: 3 +name: cloudscheduler.googleapis.com +title: Cloud Scheduler API + +apis: +- name: google.cloud.scheduler.v1beta1.CloudScheduler + +documentation: + summary: Creates and manages jobs run on a regular recurring schedule. + +backend: + rules: + - selector: 'google.cloud.scheduler.v1beta1.CloudScheduler.*' + deadline: 30.0 + +authentication: + rules: + - selector: 'google.cloud.scheduler.v1beta1.CloudScheduler.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/scheduler/v1/cloudscheduler.proto b/google/cloud/scheduler/v1/cloudscheduler.proto new file mode 100644 index 000000000..d12027a72 --- /dev/null +++ b/google/cloud/scheduler/v1/cloudscheduler.proto @@ -0,0 +1,237 @@ +// Copyright 2019 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.scheduler.v1; + +import "google/api/annotations.proto"; +import "google/cloud/scheduler/v1/job.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/scheduler/v1;scheduler"; +option java_multiple_files = true; +option java_outer_classname = "SchedulerProto"; +option java_package = "com.google.cloud.scheduler.v1"; +option objc_class_prefix = "SCHEDULER"; + + +// The Cloud Scheduler API allows external entities to reliably +// schedule asynchronous jobs. +service CloudScheduler { + // Lists jobs. + rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/jobs" + }; + } + + // Gets a job. + rpc GetJob(GetJobRequest) returns (Job) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/jobs/*}" + }; + } + + // Creates a job. + rpc CreateJob(CreateJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/jobs" + body: "job" + }; + } + + // Updates a job. + // + // If successful, the updated [Job][google.cloud.scheduler.v1.Job] is returned. If the job does + // not exist, `NOT_FOUND` is returned. + // + // If UpdateJob does not successfully return, it is possible for the + // job to be in an [Job.State.UPDATE_FAILED][google.cloud.scheduler.v1.Job.State.UPDATE_FAILED] state. A job in this state may + // not be executed. If this happens, retry the UpdateJob request + // until a successful response is received. + rpc UpdateJob(UpdateJobRequest) returns (Job) { + option (google.api.http) = { + patch: "/v1/{job.name=projects/*/locations/*/jobs/*}" + body: "job" + }; + } + + // Deletes a job. + rpc DeleteJob(DeleteJobRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/jobs/*}" + }; + } + + // Pauses a job. + // + // If a job is paused then the system will stop executing the job + // until it is re-enabled via [ResumeJob][google.cloud.scheduler.v1.CloudScheduler.ResumeJob]. The + // state of the job is stored in [state][google.cloud.scheduler.v1.Job.state]; if paused it + // will be set to [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED]. A job must be in [Job.State.ENABLED][google.cloud.scheduler.v1.Job.State.ENABLED] + // to be paused. + rpc PauseJob(PauseJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/jobs/*}:pause" + body: "*" + }; + } + + // Resume a job. + // + // This method reenables a job after it has been [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED]. The + // state of a job is stored in [Job.state][google.cloud.scheduler.v1.Job.state]; after calling this method it + // will be set to [Job.State.ENABLED][google.cloud.scheduler.v1.Job.State.ENABLED]. A job must be in + // [Job.State.PAUSED][google.cloud.scheduler.v1.Job.State.PAUSED] to be resumed. + rpc ResumeJob(ResumeJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/jobs/*}:resume" + body: "*" + }; + } + + // Forces a job to run now. + // + // When this method is called, Cloud Scheduler will dispatch the job, even + // if the job is already running. + rpc RunJob(RunJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/jobs/*}:run" + body: "*" + }; + } +} + +// Request message for listing jobs using [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs]. +message ListJobsRequest { + // Required. + // + // The location name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID`. + string parent = 1; + + // Requested page size. + // + // The maximum page size is 500. If unspecified, the page size will + // be the maximum. Fewer jobs than requested might be returned, + // even if more jobs exist; use next_page_token to determine if more + // jobs exist. + int32 page_size = 5; + + // A token identifying a page of results the server will return. To + // request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.scheduler.v1.ListJobsResponse.next_page_token] returned from + // the previous call to [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs]. It is an error to + // switch the value of [filter][google.cloud.scheduler.v1.ListJobsRequest.filter] or + // [order_by][google.cloud.scheduler.v1.ListJobsRequest.order_by] while iterating through pages. + string page_token = 6; +} + +// Response message for listing jobs using [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs]. +message ListJobsResponse { + // The list of jobs. + repeated Job jobs = 1; + + // A token to retrieve next page of results. Pass this value in the + // [page_token][google.cloud.scheduler.v1.ListJobsRequest.page_token] field in the subsequent call to + // [ListJobs][google.cloud.scheduler.v1.CloudScheduler.ListJobs] to retrieve the next page of results. + // If this is empty it indicates that there are no more results + // through which to paginate. + // + // The page token is valid for only 2 hours. + string next_page_token = 2; +} + +// Request message for [GetJob][google.cloud.scheduler.v1.CloudScheduler.GetJob]. +message GetJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob]. +message CreateJobRequest { + // Required. + // + // The location name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID`. + string parent = 1; + + // Required. + // + // The job to add. The user can optionally specify a name for the + // job in [name][google.cloud.scheduler.v1.Job.name]. [name][google.cloud.scheduler.v1.Job.name] cannot be the same as an + // existing job. If a name is not specified then the system will + // generate a random unique name that will be returned + // ([name][google.cloud.scheduler.v1.Job.name]) in the response. + Job job = 2; +} + +// Request message for [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]. +message UpdateJobRequest { + // Required. + // + // The new job properties. [name][google.cloud.scheduler.v1.Job.name] must be specified. + // + // Output only fields cannot be modified using UpdateJob. + // Any value specified for an output only field will be ignored. + Job job = 1; + + // A mask used to specify which fields of the job are being updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for deleting a job using +// [DeleteJob][google.cloud.scheduler.v1.CloudScheduler.DeleteJob]. +message DeleteJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for [PauseJob][google.cloud.scheduler.v1.CloudScheduler.PauseJob]. +message PauseJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for [ResumeJob][google.cloud.scheduler.v1.CloudScheduler.ResumeJob]. +message ResumeJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for forcing a job to run now using +// [RunJob][google.cloud.scheduler.v1.CloudScheduler.RunJob]. +message RunJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} diff --git a/google/cloud/scheduler/v1/cloudscheduler_gapic.yaml b/google/cloud/scheduler/v1/cloudscheduler_gapic.yaml new file mode 100644 index 000000000..51856eda4 --- /dev/null +++ b/google/cloud/scheduler/v1/cloudscheduler_gapic.yaml @@ -0,0 +1,259 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.scheduler.v1 + python: + package_name: google.cloud.scheduler_v1.gapic + go: + package_name: cloud.google.com/go/scheduler/apiv1 + csharp: + package_name: Google.Cloud.Scheduler.V1 + ruby: + package_name: Google::Cloud::Scheduler::V1 + php: + package_name: Google\Cloud\Scheduler\V1 + nodejs: + package_name: scheduler.v1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.scheduler.v1.CloudScheduler + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/jobs/{job} + entity_name: job + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListJobs + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: jobs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 30000 + - name: GetJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 30000 + - name: CreateJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - job + required_fields: + - parent + - job + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 30000 + - name: UpdateJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - job + - update_mask + required_fields: + - job + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + job.name: job + timeout_millis: 30000 + - name: DeleteJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 30000 + - name: PauseJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 30000 + - name: ResumeJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 30000 + - name: RunJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 30000 +resource_name_generation: +- message_name: Job + field_entity_map: + name: job +- message_name: ListJobsRequest + field_entity_map: + parent: location +- message_name: GetJobRequest + field_entity_map: + name: job +- message_name: CreateJobRequest + field_entity_map: + parent: location +- message_name: UpdateJobRequest + field_entity_map: + job.name: job +- message_name: DeleteJobRequest + field_entity_map: + name: job +- message_name: PauseJobRequest + field_entity_map: + name: job +- message_name: ResumeJobRequest + field_entity_map: + name: job +- message_name: RunJobRequest + field_entity_map: + name: job diff --git a/google/cloud/scheduler/v1/job.proto b/google/cloud/scheduler/v1/job.proto new file mode 100644 index 000000000..8cf36c4d2 --- /dev/null +++ b/google/cloud/scheduler/v1/job.proto @@ -0,0 +1,220 @@ +// Copyright 2019 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.scheduler.v1; + +import "google/api/annotations.proto"; +import "google/cloud/scheduler/v1/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/scheduler/v1;scheduler"; +option java_multiple_files = true; +option java_outer_classname = "JobProto"; +option java_package = "com.google.cloud.scheduler.v1"; + + +// Configuration for a job. +// The maximum allowed size for a job is 100KB. +message Job { + // State of the job. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The job is executing normally. + ENABLED = 1; + + // The job is paused by the user. It will not execute. A user can + // intentionally pause the job using + // [PauseJobRequest][google.cloud.scheduler.v1.PauseJobRequest]. + PAUSED = 2; + + // The job is disabled by the system due to error. The user + // cannot directly set a job to be disabled. + DISABLED = 3; + + // The job state resulting from a failed [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob] + // operation. To recover a job from this state, retry + // [CloudScheduler.UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob] until a successful response is received. + UPDATE_FAILED = 4; + } + + // Optionally caller-specified in [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob], after + // which it becomes output only. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the job's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `JOB_ID` can contain only letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), or underscores (_). The maximum length is 500 characters. + string name = 1; + + // Optionally caller-specified in [CreateJob][google.cloud.scheduler.v1.CloudScheduler.CreateJob] or + // [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]. + // + // A human-readable description for the job. This string must not contain + // more than 500 characters. + string description = 2; + + // Required. + // + // Delivery settings containing destination and parameters. + oneof target { + // Pub/Sub target. + PubsubTarget pubsub_target = 4; + + // App Engine HTTP target. + AppEngineHttpTarget app_engine_http_target = 5; + + // HTTP target. + HttpTarget http_target = 6; + } + + // Required, except when used with [UpdateJob][google.cloud.scheduler.v1.CloudScheduler.UpdateJob]. + // + // Describes the schedule on which the job will be executed. + // + // The schedule can be either of the following types: + // + // * [Crontab](http://en.wikipedia.org/wiki/Cron#Overview) + // * English-like + // [schedule](https://cloud.google.com/scheduler/docs/configuring/cron-job-schedules) + // + // As a general rule, execution `n + 1` of a job will not begin + // until execution `n` has finished. Cloud Scheduler will never + // allow two simultaneously outstanding executions. For example, + // this implies that if the `n+1`th execution is scheduled to run at + // 16:00 but the `n`th execution takes until 16:15, the `n+1`th + // execution will not start until `16:15`. + // A scheduled start time will be delayed if the previous + // execution has not ended when its scheduled time occurs. + // + // If [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] > 0 and a job attempt fails, + // the job will be tried a total of [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] + // times, with exponential backoff, until the next scheduled start + // time. + string schedule = 20; + + // Specifies the time zone to be used in interpreting + // [schedule][google.cloud.scheduler.v1.Job.schedule]. The value of this field must be a time + // zone name from the [tz database](http://en.wikipedia.org/wiki/Tz_database). + // + // Note that some time zones include a provision for + // daylight savings time. The rules for daylight saving time are + // determined by the chosen tz. For UTC use the string "utc". If a + // time zone is not specified, the default will be in UTC (also known + // as GMT). + string time_zone = 21; + + // Output only. The creation time of the job. + google.protobuf.Timestamp user_update_time = 9; + + // Output only. State of the job. + State state = 10; + + // Output only. The response from the target for the last attempted execution. + google.rpc.Status status = 11; + + // Output only. The next time the job is scheduled. Note that this may be a + // retry of a previously failed attempt or the next execution time + // according to the schedule. + google.protobuf.Timestamp schedule_time = 17; + + // Output only. The time the last job attempt started. + google.protobuf.Timestamp last_attempt_time = 18; + + // Settings that determine the retry behavior. + RetryConfig retry_config = 19; +} + +// Settings that determine the retry behavior. +// +// By default, if a job does not complete successfully (meaning that +// an acknowledgement is not received from the handler, then it will be retried +// with exponential backoff according to the settings in [RetryConfig][google.cloud.scheduler.v1.RetryConfig]. +message RetryConfig { + // The number of attempts that the system will make to run a job using the + // exponential backoff procedure described by + // [max_doublings][google.cloud.scheduler.v1.RetryConfig.max_doublings]. + // + // The default value of retry_count is zero. + // + // If retry_count is zero, a job attempt will *not* be retried if + // it fails. Instead the Cloud Scheduler system will wait for the + // next scheduled execution time. + // + // If retry_count is set to a non-zero number then Cloud Scheduler + // will retry failed attempts, using exponential backoff, + // retry_count times, or until the next scheduled execution time, + // whichever comes first. + // + // Values greater than 5 and negative values are not allowed. + int32 retry_count = 1; + + // The time limit for retrying a failed job, measured from time when an + // execution was first attempted. If specified with + // [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count], the job will be retried until both + // limits are reached. + // + // The default value for max_retry_duration is zero, which means retry + // duration is unlimited. + google.protobuf.Duration max_retry_duration = 2; + + // The minimum amount of time to wait before retrying a job after + // it fails. + // + // The default value of this field is 5 seconds. + google.protobuf.Duration min_backoff_duration = 3; + + // The maximum amount of time to wait before retrying a job after + // it fails. + // + // The default value of this field is 1 hour. + google.protobuf.Duration max_backoff_duration = 4; + + // The time between retries will double `max_doublings` times. + // + // A job's retry interval starts at + // [min_backoff_duration][google.cloud.scheduler.v1.RetryConfig.min_backoff_duration], then doubles + // `max_doublings` times, then increases linearly, and finally + // retries retries at intervals of + // [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration] up to + // [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] times. + // + // For example, if [min_backoff_duration][google.cloud.scheduler.v1.RetryConfig.min_backoff_duration] is + // 10s, [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration] is 300s, and + // `max_doublings` is 3, then the a job will first be retried in 10s. The + // retry interval will double three times, and then increase linearly by + // 2^3 * 10s. Finally, the job will retry at intervals of + // [max_backoff_duration][google.cloud.scheduler.v1.RetryConfig.max_backoff_duration] until the job has + // been attempted [retry_count][google.cloud.scheduler.v1.RetryConfig.retry_count] times. Thus, the + // requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s, .... + // + // The default value of this field is 5. + int32 max_doublings = 5; +} diff --git a/google/cloud/scheduler/v1/target.proto b/google/cloud/scheduler/v1/target.proto new file mode 100644 index 000000000..56de3b737 --- /dev/null +++ b/google/cloud/scheduler/v1/target.proto @@ -0,0 +1,291 @@ +// Copyright 2019 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.scheduler.v1; + +import "google/api/annotations.proto"; +import "google/protobuf/any.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/scheduler/v1;scheduler"; +option java_multiple_files = true; +option java_outer_classname = "TargetProto"; +option java_package = "com.google.cloud.scheduler.v1"; + + +// Http target. The job will be pushed to the job handler by means of +// an HTTP request via an [http_method][google.cloud.scheduler.v1.HttpTarget.http_method] such as HTTP +// POST, HTTP GET, etc. The job is acknowledged by means of an HTTP +// response code in the range [200 - 299]. A failure to receive a response +// constitutes a failed execution. For a redirected request, the response +// returned by the redirected request is considered. +message HttpTarget { + // Required. + // + // The full URI path that the request will be sent to. This string + // must begin with either "http://" or "https://". Some examples of + // valid values for [uri][google.cloud.scheduler.v1.HttpTarget.uri] are: + // `http://acme.com` and `https://acme.com/sales:8080`. Cloud Scheduler will + // encode some characters for safety and compatibility. The maximum allowed + // URL length is 2083 characters after encoding. + string uri = 1; + + // Which HTTP method to use for the request. + HttpMethod http_method = 2; + + // The user can specify HTTP request headers to send with the job's + // HTTP request. This map contains the header field names and + // values. Repeated headers are not supported, but a header value can + // contain commas. These headers represent a subset of the headers + // that will accompany the job's HTTP request. Some HTTP request + // headers will be ignored or replaced. A partial list of headers that + // will be ignored or replaced is below: + // - Host: This will be computed by Cloud Scheduler and derived from + // [uri][google.cloud.scheduler.v1.HttpTarget.uri]. + // * `Content-Length`: This will be computed by Cloud Scheduler. + // * `User-Agent`: This will be set to `"Google-Cloud-Scheduler"`. + // * `X-Google-*`: Google internal use only. + // * `X-AppEngine-*`: Google internal use only. + // + // The total size of headers must be less than 80KB. + map<string, string> headers = 3; + + // HTTP request body. A request body is allowed only if the HTTP + // method is POST, PUT, or PATCH. It is an error to set body on a job with an + // incompatible [HttpMethod][google.cloud.scheduler.v1.HttpMethod]. + bytes body = 4; +} + +// App Engine target. The job will be pushed to a job handler by means +// of an HTTP request via an [http_method][google.cloud.scheduler.v1.AppEngineHttpTarget.http_method] such +// as HTTP POST, HTTP GET, etc. The job is acknowledged by means of an +// HTTP response code in the range [200 - 299]. Error 503 is +// considered an App Engine system error instead of an application +// error. Requests returning error 503 will be retried regardless of +// retry configuration and not counted against retry counts. Any other +// response code, or a failure to receive a response before the +// deadline, constitutes a failed attempt. +message AppEngineHttpTarget { + // The HTTP method to use for the request. PATCH and OPTIONS are not + // permitted. + HttpMethod http_method = 1; + + // App Engine Routing setting for the job. + AppEngineRouting app_engine_routing = 2; + + // The relative URI. + // + // The relative URL must begin with "/" and must be a valid HTTP relative URL. + // It can contain a path, query string arguments, and `#` fragments. + // If the relative URL is empty, then the root path "/" will be used. + // No spaces are allowed, and the maximum length allowed is 2083 characters. + string relative_uri = 3; + + // HTTP request headers. + // + // This map contains the header field names and values. Headers can be set + // when the job is created. + // + // Cloud Scheduler sets some headers to default values: + // + // * `User-Agent`: By default, this header is + // `"AppEngine-Google; (+http://code.google.com/appengine)"`. + // This header can be modified, but Cloud Scheduler will append + // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the + // modified `User-Agent`. + // * `X-CloudScheduler`: This header will be set to true. + // + // If the job has an [body][google.cloud.scheduler.v1.AppEngineHttpTarget.body], Cloud Scheduler sets + // the following headers: + // + // * `Content-Type`: By default, the `Content-Type` header is set to + // `"application/octet-stream"`. The default can be overridden by explictly + // setting `Content-Type` to a particular media type when the job is + // created. + // For example, `Content-Type` can be set to `"application/json"`. + // * `Content-Length`: This is computed by Cloud Scheduler. This value is + // output only. It cannot be changed. + // + // The headers below are output only. They cannot be set or overridden: + // + // * `X-Google-*`: For Google internal use only. + // * `X-AppEngine-*`: For Google internal use only. + // + // In addition, some App Engine headers, which contain + // job-specific information, are also be sent to the job handler. + map<string, string> headers = 4; + + // Body. + // + // HTTP request body. A request body is allowed only if the HTTP method is + // POST or PUT. It will result in invalid argument error to set a body on a + // job with an incompatible [HttpMethod][google.cloud.scheduler.v1.HttpMethod]. + bytes body = 5; +} + +// Pub/Sub target. The job will be delivered by publishing a message to +// the given Pub/Sub topic. +message PubsubTarget { + // Required. + // + // The name of the Cloud Pub/Sub topic to which messages will + // be published when a job is delivered. The topic name must be in the + // same format as required by PubSub's + // [PublishRequest.name](https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#publishrequest), + // for example `projects/PROJECT_ID/topics/TOPIC_ID`. + // + // The topic must be in the same project as the Cloud Scheduler job. + string topic_name = 1; + + // The message payload for PubsubMessage. + // + // Pubsub message must contain either non-empty data, or at least one + // attribute. + bytes data = 3; + + // Attributes for PubsubMessage. + // + // Pubsub message must contain either non-empty data, or at least one + // attribute. + map<string, string> attributes = 4; +} + +// App Engine Routing. +// +// For more information about services, versions, and instances see +// [An Overview of App +// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), +// [Microservices Architecture on Google App +// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), +// [App Engine Standard request +// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), +// and [App Engine Flex request +// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). +message AppEngineRouting { + // App service. + // + // By default, the job is sent to the service which is the default + // service when the job is attempted. + string service = 1; + + // App version. + // + // By default, the job is sent to the version which is the default + // version when the job is attempted. + string version = 2; + + // App instance. + // + // By default, the job is sent to an instance which is available when + // the job is attempted. + // + // Requests can only be sent to a specific instance if + // [manual scaling is used in App Engine + // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). + // App Engine Flex does not support instances. For more information, see + // [App Engine Standard request + // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) + // and [App Engine Flex request + // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). + string instance = 3; + + // Output only. The host that the job is sent to. + // + // For more information about how App Engine requests are routed, see + // [here](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). + // + // The host is constructed as: + // + // + // * `host = [application_domain_name]`</br> + // `| [service] + '.' + [application_domain_name]`</br> + // `| [version] + '.' + [application_domain_name]`</br> + // `| [version_dot_service]+ '.' + [application_domain_name]`</br> + // `| [instance] + '.' + [application_domain_name]`</br> + // `| [instance_dot_service] + '.' + [application_domain_name]`</br> + // `| [instance_dot_version] + '.' + [application_domain_name]`</br> + // `| [instance_dot_version_dot_service] + '.' + [application_domain_name]` + // + // * `application_domain_name` = The domain name of the app, for + // example <app-id>.appspot.com, which is associated with the + // job's project ID. + // + // * `service =` [service][google.cloud.scheduler.v1.AppEngineRouting.service] + // + // * `version =` [version][google.cloud.scheduler.v1.AppEngineRouting.version] + // + // * `version_dot_service =` + // [version][google.cloud.scheduler.v1.AppEngineRouting.version] `+ '.' +` + // [service][google.cloud.scheduler.v1.AppEngineRouting.service] + // + // * `instance =` [instance][google.cloud.scheduler.v1.AppEngineRouting.instance] + // + // * `instance_dot_service =` + // [instance][google.cloud.scheduler.v1.AppEngineRouting.instance] `+ '.' +` + // [service][google.cloud.scheduler.v1.AppEngineRouting.service] + // + // * `instance_dot_version =` + // [instance][google.cloud.scheduler.v1.AppEngineRouting.instance] `+ '.' +` + // [version][google.cloud.scheduler.v1.AppEngineRouting.version] + // + // * `instance_dot_version_dot_service =` + // [instance][google.cloud.scheduler.v1.AppEngineRouting.instance] `+ '.' +` + // [version][google.cloud.scheduler.v1.AppEngineRouting.version] `+ '.' +` + // [service][google.cloud.scheduler.v1.AppEngineRouting.service] + // + // + // If [service][google.cloud.scheduler.v1.AppEngineRouting.service] is empty, then the job will be sent + // to the service which is the default service when the job is attempted. + // + // If [version][google.cloud.scheduler.v1.AppEngineRouting.version] is empty, then the job will be sent + // to the version which is the default version when the job is attempted. + // + // If [instance][google.cloud.scheduler.v1.AppEngineRouting.instance] is empty, then the job will be + // sent to an instance which is available when the job is attempted. + // + // If [service][google.cloud.scheduler.v1.AppEngineRouting.service], + // [version][google.cloud.scheduler.v1.AppEngineRouting.version], or + // [instance][google.cloud.scheduler.v1.AppEngineRouting.instance] is invalid, then the job will be sent + // to the default version of the default service when the job is attempted. + string host = 4; +} + +// The HTTP method used to execute the job. +enum HttpMethod { + // HTTP method unspecified. Defaults to POST. + HTTP_METHOD_UNSPECIFIED = 0; + + // HTTP POST + POST = 1; + + // HTTP GET + GET = 2; + + // HTTP HEAD + HEAD = 3; + + // HTTP PUT + PUT = 4; + + // HTTP DELETE + DELETE = 5; + + // HTTP PATCH + PATCH = 6; + + // HTTP OPTIONS + OPTIONS = 7; +} diff --git a/google/cloud/scheduler/v1beta1/BUILD.bazel b/google/cloud/scheduler/v1beta1/BUILD.bazel new file mode 100644 index 000000000..4a304bfae --- /dev/null +++ b/google/cloud/scheduler/v1beta1/BUILD.bazel @@ -0,0 +1,143 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "scheduler_proto", + srcs = [ + "cloudscheduler.proto", + "job.proto", + "target.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:any_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "scheduler_proto_with_info", + deps = [":scheduler_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "scheduler_java_proto", + deps = [":scheduler_proto"], +) + +java_grpc_library( + name = "scheduler_java_grpc", + srcs = [":scheduler_proto"], + deps = [":scheduler_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "scheduler_resource_name_java_proto", + gapic_yaml = "cloudscheduler_gapic.yaml", + deps = [":scheduler_proto"], +) + +java_gapic_library( + name = "scheduler_java_gapic", + src = ":scheduler_proto_with_info", + gapic_yaml = "cloudscheduler_gapic.yaml", + service_yaml = "//google/cloud/scheduler:cloudscheduler_v1beta1.yaml", + test_deps = [":scheduler_java_grpc"], + deps = [ + ":scheduler_java_proto", + "scheduler_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":scheduler_java_gapic_test"], +) for test_name in [ + "com.google.cloud.scheduler.v1beta1.CloudSchedulerClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-scheduler-v1beta1-java", + client_deps = [":scheduler_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":scheduler_java_gapic_test"], + grpc_deps = [":scheduler_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":scheduler_java_proto", + ":scheduler_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "scheduler_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/scheduler/v1beta1", + protos = [":scheduler_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "scheduler_go_gapic", + src = ":scheduler_proto_with_info", + gapic_yaml = "cloudscheduler_gapic.yaml", + importpath = "cloud.google.com/go/scheduler/apiv1beta1", + service_yaml = "//google/cloud/scheduler:cloudscheduler_v1beta1.yaml", + deps = [":scheduler_go_proto"], +) + +go_test( + name = "scheduler_go_gapic_test", + srcs = [":scheduler_go_gapic_srcjar_test"], + embed = [":scheduler_go_gapic"], + importpath = "cloud.google.com/go/scheduler/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-scheduler-v1beta1-go", + deps = [ + ":scheduler_go_gapic", + ":scheduler_go_gapic_srcjar-smoke-test.srcjar", + ":scheduler_go_gapic_srcjar-test.srcjar", + ":scheduler_go_proto", + ], +) diff --git a/google/cloud/scheduler/v1beta1/cloudscheduler.proto b/google/cloud/scheduler/v1beta1/cloudscheduler.proto new file mode 100644 index 000000000..4c1d96618 --- /dev/null +++ b/google/cloud/scheduler/v1beta1/cloudscheduler.proto @@ -0,0 +1,237 @@ +// Copyright 2019 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.scheduler.v1beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/scheduler/v1beta1/job.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/scheduler/v1beta1;scheduler"; +option java_multiple_files = true; +option java_outer_classname = "SchedulerProto"; +option java_package = "com.google.cloud.scheduler.v1beta1"; +option objc_class_prefix = "SCHEDULER"; + +// The Cloud Scheduler API allows external entities to reliably +// schedule asynchronous jobs. +service CloudScheduler { + // Lists jobs. + rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*}/jobs" + }; + } + + // Gets a job. + rpc GetJob(GetJobRequest) returns (Job) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/jobs/*}" + }; + } + + // Creates a job. + rpc CreateJob(CreateJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/locations/*}/jobs" + body: "job" + }; + } + + // Updates a job. + // + // If successful, the updated [Job][google.cloud.scheduler.v1beta1.Job] is returned. If the job does + // not exist, `NOT_FOUND` is returned. + // + // If UpdateJob does not successfully return, it is possible for the + // job to be in an [Job.State.UPDATE_FAILED][google.cloud.scheduler.v1beta1.Job.State.UPDATE_FAILED] state. A job in this state may + // not be executed. If this happens, retry the UpdateJob request + // until a successful response is received. + rpc UpdateJob(UpdateJobRequest) returns (Job) { + option (google.api.http) = { + patch: "/v1beta1/{job.name=projects/*/locations/*/jobs/*}" + body: "job" + }; + } + + // Deletes a job. + rpc DeleteJob(DeleteJobRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/locations/*/jobs/*}" + }; + } + + // Pauses a job. + // + // If a job is paused then the system will stop executing the job + // until it is re-enabled via [ResumeJob][google.cloud.scheduler.v1beta1.CloudScheduler.ResumeJob]. The + // state of the job is stored in [state][google.cloud.scheduler.v1beta1.Job.state]; if paused it + // will be set to [Job.State.PAUSED][google.cloud.scheduler.v1beta1.Job.State.PAUSED]. A job must be in [Job.State.ENABLED][google.cloud.scheduler.v1beta1.Job.State.ENABLED] + // to be paused. + rpc PauseJob(PauseJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/jobs/*}:pause" + body: "*" + }; + } + + // Resume a job. + // + // This method reenables a job after it has been [Job.State.PAUSED][google.cloud.scheduler.v1beta1.Job.State.PAUSED]. The + // state of a job is stored in [Job.state][google.cloud.scheduler.v1beta1.Job.state]; after calling this method it + // will be set to [Job.State.ENABLED][google.cloud.scheduler.v1beta1.Job.State.ENABLED]. A job must be in + // [Job.State.PAUSED][google.cloud.scheduler.v1beta1.Job.State.PAUSED] to be resumed. + rpc ResumeJob(ResumeJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/jobs/*}:resume" + body: "*" + }; + } + + // Forces a job to run now. + // + // When this method is called, Cloud Scheduler will dispatch the job, even + // if the job is already running. + rpc RunJob(RunJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/jobs/*}:run" + body: "*" + }; + } +} + +// Request message for listing jobs using [ListJobs][google.cloud.scheduler.v1beta1.CloudScheduler.ListJobs]. +message ListJobsRequest { + // Required. + // + // The location name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID`. + string parent = 1; + + // Requested page size. + // + // The maximum page size is 500. If unspecified, the page size will + // be the maximum. Fewer jobs than requested might be returned, + // even if more jobs exist; use next_page_token to determine if more + // jobs exist. + int32 page_size = 5; + + // A token identifying a page of results the server will return. To + // request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.scheduler.v1beta1.ListJobsResponse.next_page_token] returned from + // the previous call to [ListJobs][google.cloud.scheduler.v1beta1.CloudScheduler.ListJobs]. It is an error to + // switch the value of [filter][google.cloud.scheduler.v1beta1.ListJobsRequest.filter] or + // [order_by][google.cloud.scheduler.v1beta1.ListJobsRequest.order_by] while iterating through pages. + string page_token = 6; +} + +// Response message for listing jobs using [ListJobs][google.cloud.scheduler.v1beta1.CloudScheduler.ListJobs]. +message ListJobsResponse { + // The list of jobs. + repeated Job jobs = 1; + + // A token to retrieve next page of results. Pass this value in the + // [page_token][google.cloud.scheduler.v1beta1.ListJobsRequest.page_token] field in the subsequent call to + // [ListJobs][google.cloud.scheduler.v1beta1.CloudScheduler.ListJobs] to retrieve the next page of results. + // If this is empty it indicates that there are no more results + // through which to paginate. + // + // The page token is valid for only 2 hours. + string next_page_token = 2; +} + +// Request message for [GetJob][google.cloud.scheduler.v1beta1.CloudScheduler.GetJob]. +message GetJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for [CreateJob][google.cloud.scheduler.v1beta1.CloudScheduler.CreateJob]. +message CreateJobRequest { + // Required. + // + // The location name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID`. + string parent = 1; + + // Required. + // + // The job to add. The user can optionally specify a name for the + // job in [name][google.cloud.scheduler.v1beta1.Job.name]. [name][google.cloud.scheduler.v1beta1.Job.name] cannot be the same as an + // existing job. If a name is not specified then the system will + // generate a random unique name that will be returned + // ([name][google.cloud.scheduler.v1beta1.Job.name]) in the response. + Job job = 2; +} + +// Request message for [UpdateJob][google.cloud.scheduler.v1beta1.CloudScheduler.UpdateJob]. +message UpdateJobRequest { + // Required. + // + // The new job properties. [name][google.cloud.scheduler.v1beta1.Job.name] must be specified. + // + // Output only fields cannot be modified using UpdateJob. + // Any value specified for an output only field will be ignored. + Job job = 1; + + // A mask used to specify which fields of the job are being updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for deleting a job using +// [DeleteJob][google.cloud.scheduler.v1beta1.CloudScheduler.DeleteJob]. +message DeleteJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for [PauseJob][google.cloud.scheduler.v1beta1.CloudScheduler.PauseJob]. +message PauseJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for [ResumeJob][google.cloud.scheduler.v1beta1.CloudScheduler.ResumeJob]. +message ResumeJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} + +// Request message for forcing a job to run now using +// [RunJob][google.cloud.scheduler.v1beta1.CloudScheduler.RunJob]. +message RunJobRequest { + // Required. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + string name = 1; +} diff --git a/google/cloud/scheduler/v1beta1/cloudscheduler_gapic.yaml b/google/cloud/scheduler/v1beta1/cloudscheduler_gapic.yaml new file mode 100644 index 000000000..abc706b61 --- /dev/null +++ b/google/cloud/scheduler/v1beta1/cloudscheduler_gapic.yaml @@ -0,0 +1,258 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.scheduler.v1beta1 + python: + package_name: google.cloud.scheduler_v1beta1.gapic + go: + package_name: cloud.google.com/go/scheduler/apiv1beta1 + csharp: + package_name: Google.Cloud.Scheduler.V1Beta1 + ruby: + package_name: Google::Cloud::Scheduler::V1beta1 + php: + package_name: Google\Cloud\Scheduler\V1beta1 + nodejs: + package_name: scheduler.v1beta1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.scheduler.v1beta1.CloudScheduler + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/jobs/{job} + entity_name: job + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListJobs + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: jobs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: GetJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 10000 + - name: CreateJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - job + required_fields: + - parent + - job + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: UpdateJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - job + - update_mask + required_fields: + - job + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + job.name: job + timeout_millis: 10000 + - name: DeleteJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 10000 + - name: PauseJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 10000 + - name: ResumeJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 10000 + - name: RunJob + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: job + timeout_millis: 10000 +resource_name_generation: +- message_name: Job + field_entity_map: + name: job +- message_name: ListJobsRequest + field_entity_map: + parent: location +- message_name: GetJobRequest + field_entity_map: + name: job +- message_name: CreateJobRequest + field_entity_map: + parent: location +- message_name: UpdateJobRequest + field_entity_map: + job.name: job +- message_name: DeleteJobRequest + field_entity_map: + name: job +- message_name: PauseJobRequest + field_entity_map: + name: job +- message_name: ResumeJobRequest + field_entity_map: + name: job +- message_name: RunJobRequest + field_entity_map: + name: job diff --git a/google/cloud/scheduler/v1beta1/job.proto b/google/cloud/scheduler/v1beta1/job.proto new file mode 100644 index 000000000..ddf910b03 --- /dev/null +++ b/google/cloud/scheduler/v1beta1/job.proto @@ -0,0 +1,234 @@ +// Copyright 2019 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.scheduler.v1beta1; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/scheduler/v1beta1/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/scheduler/v1beta1;scheduler"; +option java_multiple_files = true; +option java_outer_classname = "JobProto"; +option java_package = "com.google.cloud.scheduler.v1beta1"; + +// Configuration for a job. +// The maximum allowed size for a job is 100KB. +message Job { + // State of the job. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The job is executing normally. + ENABLED = 1; + + // The job is paused by the user. It will not execute. A user can + // intentionally pause the job using + // [PauseJobRequest][google.cloud.scheduler.v1beta1.PauseJobRequest]. + PAUSED = 2; + + // The job is disabled by the system due to error. The user + // cannot directly set a job to be disabled. + DISABLED = 3; + + // The job state resulting from a failed [CloudScheduler.UpdateJob][google.cloud.scheduler.v1beta1.CloudScheduler.UpdateJob] + // operation. To recover a job from this state, retry + // [CloudScheduler.UpdateJob][google.cloud.scheduler.v1beta1.CloudScheduler.UpdateJob] until a successful response is received. + UPDATE_FAILED = 4; + } + + // Optionally caller-specified in [CreateJob][google.cloud.scheduler.v1beta1.CloudScheduler.CreateJob], after + // which it becomes output only. + // + // The job name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/jobs/JOB_ID`. + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the job's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `JOB_ID` can contain only letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), or underscores (_). The maximum length is 500 characters. + string name = 1; + + // Optionally caller-specified in [CreateJob][google.cloud.scheduler.v1beta1.CloudScheduler.CreateJob] or + // [UpdateJob][google.cloud.scheduler.v1beta1.CloudScheduler.UpdateJob]. + // + // A human-readable description for the job. This string must not contain + // more than 500 characters. + string description = 2; + + // Required. + // + // Delivery settings containing destination and parameters. + oneof target { + // Pub/Sub target. + PubsubTarget pubsub_target = 4; + + // App Engine HTTP target. + AppEngineHttpTarget app_engine_http_target = 5; + + // HTTP target. + HttpTarget http_target = 6; + } + + // Required, except when used with [UpdateJob][google.cloud.scheduler.v1beta1.CloudScheduler.UpdateJob]. + // + // Describes the schedule on which the job will be executed. + // + // The schedule can be either of the following types: + // + // * [Crontab](http://en.wikipedia.org/wiki/Cron#Overview) + // * English-like + // [schedule](https://cloud.google.com/scheduler/docs/configuring/cron-job-schedules) + // + // As a general rule, execution `n + 1` of a job will not begin + // until execution `n` has finished. Cloud Scheduler will never + // allow two simultaneously outstanding executions. For example, + // this implies that if the `n+1`th execution is scheduled to run at + // 16:00 but the `n`th execution takes until 16:15, the `n+1`th + // execution will not start until `16:15`. + // A scheduled start time will be delayed if the previous + // execution has not ended when its scheduled time occurs. + // + // If [retry_count][google.cloud.scheduler.v1beta1.RetryConfig.retry_count] > 0 and a job attempt fails, + // the job will be tried a total of [retry_count][google.cloud.scheduler.v1beta1.RetryConfig.retry_count] + // times, with exponential backoff, until the next scheduled start + // time. + string schedule = 20; + + // Specifies the time zone to be used in interpreting + // [schedule][google.cloud.scheduler.v1beta1.Job.schedule]. The value of this field must be a time + // zone name from the [tz database](http://en.wikipedia.org/wiki/Tz_database). + // + // Note that some time zones include a provision for + // daylight savings time. The rules for daylight saving time are + // determined by the chosen tz. For UTC use the string "utc". If a + // time zone is not specified, the default will be in UTC (also known + // as GMT). + string time_zone = 21; + + // Output only. The creation time of the job. + google.protobuf.Timestamp user_update_time = 9; + + // Output only. State of the job. + State state = 10; + + // Output only. The response from the target for the last attempted execution. + google.rpc.Status status = 11; + + // Output only. The next time the job is scheduled. Note that this may be a + // retry of a previously failed attempt or the next execution time + // according to the schedule. + google.protobuf.Timestamp schedule_time = 17; + + // Output only. The time the last job attempt started. + google.protobuf.Timestamp last_attempt_time = 18; + + // Settings that determine the retry behavior. + RetryConfig retry_config = 19; + + // The deadline for job attempts. If the request handler does not respond by + // this deadline then the request is cancelled and the attempt is marked as a + // `DEADLINE_EXCEEDED` failure. The failed attempt can be viewed in + // execution logs. Cloud Scheduler will retry the job according + // to the [RetryConfig][google.cloud.scheduler.v1beta1.RetryConfig]. + // + // The allowed duration for this deadline is: + // + // * For [HTTP targets][google.cloud.scheduler.v1beta1.Job.http_target], between 15 seconds and 30 minutes. + // * For [App Engine HTTP targets][google.cloud.scheduler.v1beta1.Job.app_engine_http_target], between 15 + // seconds and 24 hours. + // * For [PubSub targets][google.cloud.scheduler.v1beta1.Job.pubsub_target], this field is ignored. + google.protobuf.Duration attempt_deadline = 22; +} + +// Settings that determine the retry behavior. +// +// By default, if a job does not complete successfully (meaning that +// an acknowledgement is not received from the handler, then it will be retried +// with exponential backoff according to the settings in [RetryConfig][google.cloud.scheduler.v1beta1.RetryConfig]. +message RetryConfig { + // The number of attempts that the system will make to run a job using the + // exponential backoff procedure described by + // [max_doublings][google.cloud.scheduler.v1beta1.RetryConfig.max_doublings]. + // + // The default value of retry_count is zero. + // + // If retry_count is zero, a job attempt will *not* be retried if + // it fails. Instead the Cloud Scheduler system will wait for the + // next scheduled execution time. + // + // If retry_count is set to a non-zero number then Cloud Scheduler + // will retry failed attempts, using exponential backoff, + // retry_count times, or until the next scheduled execution time, + // whichever comes first. + // + // Values greater than 5 and negative values are not allowed. + int32 retry_count = 1; + + // The time limit for retrying a failed job, measured from time when an + // execution was first attempted. If specified with + // [retry_count][google.cloud.scheduler.v1beta1.RetryConfig.retry_count], the job will be retried until both + // limits are reached. + // + // The default value for max_retry_duration is zero, which means retry + // duration is unlimited. + google.protobuf.Duration max_retry_duration = 2; + + // The minimum amount of time to wait before retrying a job after + // it fails. + // + // The default value of this field is 5 seconds. + google.protobuf.Duration min_backoff_duration = 3; + + // The maximum amount of time to wait before retrying a job after + // it fails. + // + // The default value of this field is 1 hour. + google.protobuf.Duration max_backoff_duration = 4; + + // The time between retries will double `max_doublings` times. + // + // A job's retry interval starts at + // [min_backoff_duration][google.cloud.scheduler.v1beta1.RetryConfig.min_backoff_duration], then doubles + // `max_doublings` times, then increases linearly, and finally + // retries retries at intervals of + // [max_backoff_duration][google.cloud.scheduler.v1beta1.RetryConfig.max_backoff_duration] up to + // [retry_count][google.cloud.scheduler.v1beta1.RetryConfig.retry_count] times. + // + // For example, if [min_backoff_duration][google.cloud.scheduler.v1beta1.RetryConfig.min_backoff_duration] is + // 10s, [max_backoff_duration][google.cloud.scheduler.v1beta1.RetryConfig.max_backoff_duration] is 300s, and + // `max_doublings` is 3, then the a job will first be retried in 10s. The + // retry interval will double three times, and then increase linearly by + // 2^3 * 10s. Finally, the job will retry at intervals of + // [max_backoff_duration][google.cloud.scheduler.v1beta1.RetryConfig.max_backoff_duration] until the job has + // been attempted [retry_count][google.cloud.scheduler.v1beta1.RetryConfig.retry_count] times. Thus, the + // requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s, .... + // + // The default value of this field is 5. + int32 max_doublings = 5; +} diff --git a/google/cloud/scheduler/v1beta1/target.proto b/google/cloud/scheduler/v1beta1/target.proto new file mode 100644 index 000000000..3bb44a1fb --- /dev/null +++ b/google/cloud/scheduler/v1beta1/target.proto @@ -0,0 +1,348 @@ +// Copyright 2019 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.scheduler.v1beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/any.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/scheduler/v1beta1;scheduler"; +option java_multiple_files = true; +option java_outer_classname = "TargetProto"; +option java_package = "com.google.cloud.scheduler.v1beta1"; + +// Http target. The job will be pushed to the job handler by means of +// an HTTP request via an [http_method][google.cloud.scheduler.v1beta1.HttpTarget.http_method] such as HTTP +// POST, HTTP GET, etc. The job is acknowledged by means of an HTTP +// response code in the range [200 - 299]. A failure to receive a response +// constitutes a failed execution. For a redirected request, the response +// returned by the redirected request is considered. +message HttpTarget { + // Required. + // + // The full URI path that the request will be sent to. This string + // must begin with either "http://" or "https://". Some examples of + // valid values for [uri][google.cloud.scheduler.v1beta1.HttpTarget.uri] are: + // `http://acme.com` and `https://acme.com/sales:8080`. Cloud Scheduler will + // encode some characters for safety and compatibility. The maximum allowed + // URL length is 2083 characters after encoding. + string uri = 1; + + // Which HTTP method to use for the request. + HttpMethod http_method = 2; + + // The user can specify HTTP request headers to send with the job's + // HTTP request. This map contains the header field names and + // values. Repeated headers are not supported, but a header value can + // contain commas. These headers represent a subset of the headers + // that will accompany the job's HTTP request. Some HTTP request + // headers will be ignored or replaced. A partial list of headers that + // will be ignored or replaced is below: + // - Host: This will be computed by Cloud Scheduler and derived from + // [uri][google.cloud.scheduler.v1beta1.HttpTarget.uri]. + // * `Content-Length`: This will be computed by Cloud Scheduler. + // * `User-Agent`: This will be set to `"Google-Cloud-Scheduler"`. + // * `X-Google-*`: Google internal use only. + // * `X-AppEngine-*`: Google internal use only. + // + // The total size of headers must be less than 80KB. + map<string, string> headers = 3; + + // HTTP request body. A request body is allowed only if the HTTP + // method is POST, PUT, or PATCH. It is an error to set body on a job with an + // incompatible [HttpMethod][google.cloud.scheduler.v1beta1.HttpMethod]. + bytes body = 4; + + // The mode for generating an `Authorization` header for HTTP requests. + // + // If specified, all `Authorization` headers in the [HttpTarget.headers][google.cloud.scheduler.v1beta1.HttpTarget.headers] + // field will be overridden. + oneof authorization_header { + // If specified, an + // [OAuth token](https://developers.google.com/identity/protocols/OAuth2) + // will be generated and attached as an `Authorization` header in the HTTP + // request. + // + // This type of authorization should be used when sending requests to a GCP + // endpoint. + OAuthToken oauth_token = 5; + + // If specified, an + // [OIDC](https://developers.google.com/identity/protocols/OpenIDConnect) + // token will be generated and attached as an `Authorization` header in the + // HTTP request. + // + // This type of authorization should be used when sending requests to third + // party endpoints. + OidcToken oidc_token = 6; + } +} + +// App Engine target. The job will be pushed to a job handler by means +// of an HTTP request via an [http_method][google.cloud.scheduler.v1beta1.AppEngineHttpTarget.http_method] such +// as HTTP POST, HTTP GET, etc. The job is acknowledged by means of an +// HTTP response code in the range [200 - 299]. Error 503 is +// considered an App Engine system error instead of an application +// error. Requests returning error 503 will be retried regardless of +// retry configuration and not counted against retry counts. Any other +// response code, or a failure to receive a response before the +// deadline, constitutes a failed attempt. +message AppEngineHttpTarget { + // The HTTP method to use for the request. PATCH and OPTIONS are not + // permitted. + HttpMethod http_method = 1; + + // App Engine Routing setting for the job. + AppEngineRouting app_engine_routing = 2; + + // The relative URI. + // + // The relative URL must begin with "/" and must be a valid HTTP relative URL. + // It can contain a path, query string arguments, and `#` fragments. + // If the relative URL is empty, then the root path "/" will be used. + // No spaces are allowed, and the maximum length allowed is 2083 characters. + string relative_uri = 3; + + // HTTP request headers. + // + // This map contains the header field names and values. Headers can be set + // when the job is created. + // + // Cloud Scheduler sets some headers to default values: + // + // * `User-Agent`: By default, this header is + // `"AppEngine-Google; (+http://code.google.com/appengine)"`. + // This header can be modified, but Cloud Scheduler will append + // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the + // modified `User-Agent`. + // * `X-CloudScheduler`: This header will be set to true. + // + // If the job has an [body][google.cloud.scheduler.v1beta1.AppEngineHttpTarget.body], Cloud Scheduler sets + // the following headers: + // + // * `Content-Type`: By default, the `Content-Type` header is set to + // `"application/octet-stream"`. The default can be overridden by explictly + // setting `Content-Type` to a particular media type when the job is + // created. + // For example, `Content-Type` can be set to `"application/json"`. + // * `Content-Length`: This is computed by Cloud Scheduler. This value is + // output only. It cannot be changed. + // + // The headers below are output only. They cannot be set or overridden: + // + // * `X-Google-*`: For Google internal use only. + // * `X-AppEngine-*`: For Google internal use only. + // + // In addition, some App Engine headers, which contain + // job-specific information, are also be sent to the job handler. + map<string, string> headers = 4; + + // Body. + // + // HTTP request body. A request body is allowed only if the HTTP method is + // POST or PUT. It will result in invalid argument error to set a body on a + // job with an incompatible [HttpMethod][google.cloud.scheduler.v1beta1.HttpMethod]. + bytes body = 5; +} + +// Pub/Sub target. The job will be delivered by publishing a message to +// the given Pub/Sub topic. +message PubsubTarget { + // Required. + // + // The name of the Cloud Pub/Sub topic to which messages will + // be published when a job is delivered. The topic name must be in the + // same format as required by PubSub's + // [PublishRequest.name](https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#publishrequest), + // for example `projects/PROJECT_ID/topics/TOPIC_ID`. + // + // The topic must be in the same project as the Cloud Scheduler job. + string topic_name = 1; + + // The message payload for PubsubMessage. + // + // Pubsub message must contain either non-empty data, or at least one + // attribute. + bytes data = 3; + + // Attributes for PubsubMessage. + // + // Pubsub message must contain either non-empty data, or at least one + // attribute. + map<string, string> attributes = 4; +} + +// App Engine Routing. +// +// For more information about services, versions, and instances see +// [An Overview of App +// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), +// [Microservices Architecture on Google App +// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), +// [App Engine Standard request +// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), +// and [App Engine Flex request +// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). +message AppEngineRouting { + // App service. + // + // By default, the job is sent to the service which is the default + // service when the job is attempted. + string service = 1; + + // App version. + // + // By default, the job is sent to the version which is the default + // version when the job is attempted. + string version = 2; + + // App instance. + // + // By default, the job is sent to an instance which is available when + // the job is attempted. + // + // Requests can only be sent to a specific instance if + // [manual scaling is used in App Engine + // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). + // App Engine Flex does not support instances. For more information, see + // [App Engine Standard request + // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) + // and [App Engine Flex request + // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). + string instance = 3; + + // Output only. The host that the job is sent to. + // + // For more information about how App Engine requests are routed, see + // [here](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). + // + // The host is constructed as: + // + // + // * `host = [application_domain_name]`</br> + // `| [service] + '.' + [application_domain_name]`</br> + // `| [version] + '.' + [application_domain_name]`</br> + // `| [version_dot_service]+ '.' + [application_domain_name]`</br> + // `| [instance] + '.' + [application_domain_name]`</br> + // `| [instance_dot_service] + '.' + [application_domain_name]`</br> + // `| [instance_dot_version] + '.' + [application_domain_name]`</br> + // `| [instance_dot_version_dot_service] + '.' + [application_domain_name]` + // + // * `application_domain_name` = The domain name of the app, for + // example <app-id>.appspot.com, which is associated with the + // job's project ID. + // + // * `service =` [service][google.cloud.scheduler.v1beta1.AppEngineRouting.service] + // + // * `version =` [version][google.cloud.scheduler.v1beta1.AppEngineRouting.version] + // + // * `version_dot_service =` + // [version][google.cloud.scheduler.v1beta1.AppEngineRouting.version] `+ '.' +` + // [service][google.cloud.scheduler.v1beta1.AppEngineRouting.service] + // + // * `instance =` [instance][google.cloud.scheduler.v1beta1.AppEngineRouting.instance] + // + // * `instance_dot_service =` + // [instance][google.cloud.scheduler.v1beta1.AppEngineRouting.instance] `+ '.' +` + // [service][google.cloud.scheduler.v1beta1.AppEngineRouting.service] + // + // * `instance_dot_version =` + // [instance][google.cloud.scheduler.v1beta1.AppEngineRouting.instance] `+ '.' +` + // [version][google.cloud.scheduler.v1beta1.AppEngineRouting.version] + // + // * `instance_dot_version_dot_service =` + // [instance][google.cloud.scheduler.v1beta1.AppEngineRouting.instance] `+ '.' +` + // [version][google.cloud.scheduler.v1beta1.AppEngineRouting.version] `+ '.' +` + // [service][google.cloud.scheduler.v1beta1.AppEngineRouting.service] + // + // + // If [service][google.cloud.scheduler.v1beta1.AppEngineRouting.service] is empty, then the job will be sent + // to the service which is the default service when the job is attempted. + // + // If [version][google.cloud.scheduler.v1beta1.AppEngineRouting.version] is empty, then the job will be sent + // to the version which is the default version when the job is attempted. + // + // If [instance][google.cloud.scheduler.v1beta1.AppEngineRouting.instance] is empty, then the job will be + // sent to an instance which is available when the job is attempted. + // + // If [service][google.cloud.scheduler.v1beta1.AppEngineRouting.service], + // [version][google.cloud.scheduler.v1beta1.AppEngineRouting.version], or + // [instance][google.cloud.scheduler.v1beta1.AppEngineRouting.instance] is invalid, then the job will be sent + // to the default version of the default service when the job is attempted. + string host = 4; +} + +// The HTTP method used to execute the job. +enum HttpMethod { + // HTTP method unspecified. Defaults to POST. + HTTP_METHOD_UNSPECIFIED = 0; + + // HTTP POST + POST = 1; + + // HTTP GET + GET = 2; + + // HTTP HEAD + HEAD = 3; + + // HTTP PUT + PUT = 4; + + // HTTP DELETE + DELETE = 5; + + // HTTP PATCH + PATCH = 6; + + // HTTP OPTIONS + OPTIONS = 7; +} + +// Contains information needed for generating an +// [OAuth token](https://developers.google.com/identity/protocols/OAuth2). +// This type of authorization should be used when sending requests to a GCP +// endpoint. +message OAuthToken { + // [Service account email](https://cloud.google.com/iam/docs/service-accounts) + // to be used for generating OAuth token. + // The service account must be within the same project as the job. The caller + // must have iam.serviceAccounts.actAs permission for the service account. + string service_account_email = 1; + + // OAuth scope to be used for generating OAuth access token. + // If not specified, "https://www.googleapis.com/auth/cloud-platform" + // will be used. + string scope = 2; +} + +// Contains information needed for generating an +// [OpenID Connect +// token](https://developers.google.com/identity/protocols/OpenIDConnect). This +// type of authorization should be used when sending requests to third party +// endpoints. +message OidcToken { + // [Service account email](https://cloud.google.com/iam/docs/service-accounts) + // to be used for generating OIDC token. + // The service account must be within the same project as the job. The caller + // must have iam.serviceAccounts.actAs permission for the service account. + string service_account_email = 1; + + // Audience to be used when generating OIDC token. If not specified, the URI + // specified in target will be used. + string audience = 2; +} diff --git a/google/cloud/securitycenter/BUILD.bazel b/google/cloud/securitycenter/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/securitycenter/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/securitycenter/artman_securitycenter_v1.yaml b/google/cloud/securitycenter/artman_securitycenter_v1.yaml new file mode 100644 index 000000000..7e30bd835 --- /dev/null +++ b/google/cloud/securitycenter/artman_securitycenter_v1.yaml @@ -0,0 +1,34 @@ +common: + api_name: securitycenter + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: securitycenter_v1.yaml + gapic_yaml: v1/securitycenter_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/securitycenter/artman_securitycenter_v1beta1.yaml b/google/cloud/securitycenter/artman_securitycenter_v1beta1.yaml new file mode 100644 index 000000000..ff2d5207d --- /dev/null +++ b/google/cloud/securitycenter/artman_securitycenter_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: securitycenter + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: securitycenter_v1beta1.yaml + gapic_yaml: v1beta1/securitycenter_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/securitycenter/securitycenter_v1.yaml b/google/cloud/securitycenter/securitycenter_v1.yaml new file mode 100644 index 000000000..7953a8812 --- /dev/null +++ b/google/cloud/securitycenter/securitycenter_v1.yaml @@ -0,0 +1,73 @@ +type: google.api.Service +config_version: 3 +name: securitycenter.googleapis.com +title: Cloud Security Command Center API + +apis: +- name: google.cloud.securitycenter.v1.SecurityCenter + +documentation: + summary: |- + Cloud Security Command Center API provides access to temporal views of + assets and findings within an organization. + +backend: + rules: + - selector: google.cloud.securitycenter.v1.SecurityCenter.CreateSource + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.CreateFinding + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.GetIamPolicy + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.GetOrganizationSettings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.GetSource + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.GroupAssets + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.GroupFindings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.ListAssets + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.ListFindings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.ListSources + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.RunAssetDiscovery + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.SetFindingState + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.SetIamPolicy + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.TestIamPermissions + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.UpdateFinding + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.UpdateOrganizationSettings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.UpdateSource + deadline: 60.0 + - selector: google.cloud.securitycenter.v1.SecurityCenter.UpdateSecurityMarks + deadline: 60.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1/{name=organizations/*/operations}' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=organizations/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/{name=organizations/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/{name=organizations/*/operations/*}:cancel' + body: '*' + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/securitycenter/securitycenter_v1beta1.yaml b/google/cloud/securitycenter/securitycenter_v1beta1.yaml new file mode 100644 index 000000000..c3a5c91ed --- /dev/null +++ b/google/cloud/securitycenter/securitycenter_v1beta1.yaml @@ -0,0 +1,74 @@ +type: google.api.Service +config_version: 3 +name: securitycenter.googleapis.com +title: Cloud Security Command Center API + +apis: +- name: google.cloud.securitycenter.v1beta1.SecurityCenter + +documentation: + summary: |- + Cloud Security Command Center API provides access to temporal views of + assets and findings within an organization. + +backend: + rules: + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.CreateSource + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.CreateFinding + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.GetIamPolicy + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.GetOrganizationSettings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.GetSource + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.GroupAssets + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.GroupFindings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.ListAssets + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.ListFindings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.ListSources + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.RunAssetDiscovery + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.SetFindingState + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.SetIamPolicy + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.TestIamPermissions + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.UpdateFinding + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.UpdateOrganizationSettings + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.UpdateSource + deadline: 60.0 + - selector: google.cloud.securitycenter.v1beta1.SecurityCenter.UpdateSecurityMarks + deadline: 60.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: '/v1beta1/{name=organizations/*/operations}' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1beta1/{name=organizations/*/operations/*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1beta1/{name=organizations/*/operations/*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1beta1/{name=organizations/*/operations/*}:cancel' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/securitycenter/v1/asset.proto b/google/cloud/securitycenter/v1/asset.proto new file mode 100644 index 000000000..8e8bcb297 --- /dev/null +++ b/google/cloud/securitycenter/v1/asset.proto @@ -0,0 +1,103 @@ +// Copyright 2019 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.securitycenter.v1; + +import "google/api/annotations.proto"; +import "google/cloud/securitycenter/v1/security_marks.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.SecurityCenter.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1"; +option php_namespace = "Google\\Cloud\\SecurityCenter\\V1"; + +// Cloud Security Command Center's (Cloud SCC) representation of a Google Cloud +// Platform (GCP) resource. +// +// The Asset is a Cloud SCC resource that captures information about a single +// GCP resource. All modifications to an Asset are only within the context of +// Cloud SCC and don't affect the referenced GCP resource. +message Asset { + // Cloud SCC managed properties. These properties are managed by Cloud SCC and + // cannot be modified by the user. + message SecurityCenterProperties { + // The full resource name of the GCP resource this asset + // represents. This field is immutable after create time. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + string resource_name = 1; + + // The type of the GCP resource. Examples include: APPLICATION, + // PROJECT, and ORGANIZATION. This is a case insensitive field defined by + // Cloud SCC and/or the producer of the resource and is immutable + // after create time. + string resource_type = 2; + + // The full resource name of the immediate parent of the resource. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + string resource_parent = 3; + + // The full resource name of the project the resource belongs to. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + string resource_project = 4; + + // Owners of the Google Cloud resource. + repeated string resource_owners = 5; + } + + // IAM Policy information associated with the GCP resource described by the + // Cloud SCC asset. This information is managed and defined by the GCP + // resource and cannot be modified by the user. + message IamPolicy { + // The JSON representation of the Policy associated with the asset. + // See https://cloud.google.com/iam/reference/rest/v1/Policy for format + // details. + string policy_blob = 1; + } + + // The relative resource name of this asset. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/assets/456". + string name = 1; + + // Cloud SCC managed properties. These properties are managed by + // Cloud SCC and cannot be modified by the user. + SecurityCenterProperties security_center_properties = 2; + + // Resource managed properties. These properties are managed and defined by + // the GCP resource and cannot be modified by the user. + map<string, google.protobuf.Value> resource_properties = 7; + + // User specified security marks. These marks are entirely managed by the user + // and come from the SecurityMarks resource that belongs to the asset. + SecurityMarks security_marks = 8; + + // The time at which the asset was created in Cloud SCC. + google.protobuf.Timestamp create_time = 9; + + // The time at which the asset was last updated, added, or deleted in Cloud + // SCC. + google.protobuf.Timestamp update_time = 10; + + // IAM Policy information associated with the GCP resource described by the + // Cloud SCC asset. This information is managed and defined by the GCP + // resource and cannot be modified by the user. + IamPolicy iam_policy = 11; +} diff --git a/google/cloud/securitycenter/v1/finding.proto b/google/cloud/securitycenter/v1/finding.proto new file mode 100644 index 000000000..2a8e75b9c --- /dev/null +++ b/google/cloud/securitycenter/v1/finding.proto @@ -0,0 +1,101 @@ +// Copyright 2019 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.securitycenter.v1; + +import "google/api/annotations.proto"; +import "google/cloud/securitycenter/v1/security_marks.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.SecurityCenter.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1"; +option php_namespace = "Google\\Cloud\\SecurityCenter\\V1"; + +// Cloud Security Command Center (Cloud SCC) finding. +// +// A finding is a record of assessment data (security, risk, health or privacy) +// ingested into Cloud SCC for presentation, notification, analysis, +// policy testing, and enforcement. For example, an XSS vulnerability in an +// App Engine application is a finding. +message Finding { + // The state of the finding. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The finding requires attention and has not been addressed yet. + ACTIVE = 1; + + // The finding has been fixed, triaged as a non-issue or otherwise addressed + // and is no longer active. + INACTIVE = 2; + } + + // The relative resource name of this finding. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/sources/456/findings/789" + string name = 1; + + // The relative resource name of the source the finding belongs to. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // This field is immutable after creation time. + // For example: + // "organizations/123/sources/456" + string parent = 2; + + // The full resource name of the Google Cloud Platform (GCP) resource this + // finding is for. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + // This field is immutable after creation time. + string resource_name = 3; + + // The state of the finding. + State state = 4; + + // The additional taxonomy group within findings from a given source. + // This field is immutable after creation time. + // Example: "XSS_FLASH_INJECTION" + string category = 5; + + // The URI that, if available, points to a web page outside of Cloud SCC + // where additional information about the finding can be found. This field is + // guaranteed to be either empty or a well formed URL. + string external_uri = 6; + + // Source specific properties. These properties are managed by the source + // that writes the finding. The key names in the source_properties map must be + // between 1 and 255 characters, and must start with a letter and contain + // alphanumeric characters or underscores only. + map<string, google.protobuf.Value> source_properties = 7; + + // Output only. User specified security marks. These marks are entirely + // managed by the user and come from the SecurityMarks resource that belongs + // to the finding. + SecurityMarks security_marks = 8; + + // The time at which the event took place. For example, if the finding + // represents an open firewall it would capture the time the open firewall was + // detected. + google.protobuf.Timestamp event_time = 9; + + // The time at which the finding was created in Cloud SCC. + google.protobuf.Timestamp create_time = 10; +} diff --git a/google/cloud/securitycenter/v1/organization_settings.proto b/google/cloud/securitycenter/v1/organization_settings.proto new file mode 100644 index 000000000..05e24e28a --- /dev/null +++ b/google/cloud/securitycenter/v1/organization_settings.proto @@ -0,0 +1,78 @@ +// Copyright 2019 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.securitycenter.v1; + +import "google/api/annotations.proto"; + +option csharp_namespace = "Google.Cloud.SecurityCenter.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1"; +option php_namespace = "Google\\Cloud\\SecurityCenter\\V1"; + +// User specified settings that are attached to the Cloud Security Command +// Center (Cloud SCC) organization. +message OrganizationSettings { + // The configuration used for Asset Discovery runs. + message AssetDiscoveryConfig { + // The mode of inclusion when running Asset Discovery. + // Asset discovery can be limited by explicitly identifying projects to be + // included or excluded. If INCLUDE_ONLY is set, then only those projects + // within the organization and their children are discovered during asset + // discovery. If EXCLUDE is set, then projects that don't match those + // projects are discovered during asset discovery. If neither are set, then + // all projects within the organization are discovered during asset + // discovery. + enum InclusionMode { + // Unspecified. Setting the mode with this value will disable + // inclusion/exclusion filtering for Asset Discovery. + INCLUSION_MODE_UNSPECIFIED = 0; + + // Asset Discovery will capture only the resources within the projects + // specified. All other resources will be ignored. + INCLUDE_ONLY = 1; + + // Asset Discovery will ignore all resources under the projects specified. + // All other resources will be retrieved. + EXCLUDE = 2; + } + + // The project ids to use for filtering asset discovery. + repeated string project_ids = 1; + + // The mode to use for filtering asset discovery. + InclusionMode inclusion_mode = 2; + } + + // The relative resource name of the settings. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/organizationSettings". + string name = 1; + + // A flag that indicates if Asset Discovery should be enabled. If the flag is + // set to `true`, then discovery of assets will occur. If it is set to `false, + // all historical assets will remain, but discovery of future assets will not + // occur. + bool enable_asset_discovery = 2; + + // The configuration used for Asset Discovery runs. + AssetDiscoveryConfig asset_discovery_config = 3; + + reserved 4, 5; +} diff --git a/google/cloud/securitycenter/v1/security_marks.proto b/google/cloud/securitycenter/v1/security_marks.proto new file mode 100644 index 000000000..4ba82d974 --- /dev/null +++ b/google/cloud/securitycenter/v1/security_marks.proto @@ -0,0 +1,48 @@ +// Copyright 2019 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.securitycenter.v1; + +import "google/api/annotations.proto"; + +option csharp_namespace = "Google.Cloud.SecurityCenter.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1"; +option php_namespace = "Google\\Cloud\\SecurityCenter\\V1"; + +// User specified security marks that are attached to the parent Cloud Security +// Command Center (Cloud SCC) resource. Security marks are scoped within a Cloud +// SCC organization -- they can be modified and viewed by all users who have +// proper permissions on the organization. +message SecurityMarks { + // The relative resource name of the SecurityMarks. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Examples: + // "organizations/123/assets/456/securityMarks" + // "organizations/123/sources/456/findings/789/securityMarks". + string name = 1; + + // Mutable user specified security marks belonging to the parent resource. + // Constraints are as follows: + // - Keys and values are treated as case insensitive + // - Keys must be between 1 - 256 characters (inclusive) + // - Keys must be letters, numbers, underscores, or dashes + // - Values have leading and trailing whitespace trimmed, remaining + // characters must be between 1 - 4096 characters (inclusive) + map<string, string> marks = 2; +} diff --git a/google/cloud/securitycenter/v1/securitycenter_gapic.yaml b/google/cloud/securitycenter/v1/securitycenter_gapic.yaml new file mode 100644 index 000000000..fd39bf811 --- /dev/null +++ b/google/cloud/securitycenter/v1/securitycenter_gapic.yaml @@ -0,0 +1,466 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.securitycenter.v1 + python: + package_name: google.cloud.securitycenter_v1.gapic + go: + package_name: cloud.google.com/go/securitycenter/apiv1 + csharp: + package_name: Google.Cloud.SecurityCenter.V1 + ruby: + package_name: Google::Cloud::SecurityCenter::V1 + php: + package_name: Google\Cloud\SecurityCenter\V1 + nodejs: + package_name: security-center.v1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.securitycenter.v1.SecurityCenter + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: organizations/{organization} + entity_name: organization + - name_pattern: organizations/{organization}/assets/{asset}/securityMarks + entity_name: asset_security_marks + - name_pattern: organizations/{organization}/sources/{source}/findings/{finding}/securityMarks + entity_name: finding_security_marks + - name_pattern: organizations/{organization}/organizationSettings + entity_name: organization_settings + - name_pattern: organizations/{organization}/sources/- + entity_name: organization_sources + - name_pattern: organizations/{organization}/sources/{source} + entity_name: source + - name_pattern: organizations/{organization}/sources/{source}/findings/{finding} + entity_name: finding + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateSource + flattening: + groups: + - parameters: + - parent + - source + required_fields: + - parent + - source + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: CreateFinding + flattening: + groups: + - parameters: + - parent + - finding_id + - finding + required_fields: + - parent + - finding_id + - finding + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: source + timeout_millis: 60000 + - name: GetIamPolicy + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + resource: source + timeout_millis: 60000 + - name: GetOrganizationSettings + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: organization_settings + timeout_millis: 60000 + - name: GetSource + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: source + timeout_millis: 60000 + - name: GroupAssets + required_fields: + - parent + - group_by + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: group_by_results + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: GroupFindings + flattening: + groups: + - parameters: + - parent + - group_by + required_fields: + - parent + - group_by + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: group_by_results + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: source + timeout_millis: 60000 + - name: ListAssets + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: list_assets_results + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: ListFindings + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: list_findings_results + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: source + timeout_millis: 60000 + - name: ListSources + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: sources + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: RunAssetDiscovery + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + long_running: + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Empty + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 60000 + - name: SetFindingState + flattening: + groups: + - parameters: + - name + - state + - start_time + required_fields: + - name + - state + - start_time + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: finding + timeout_millis: 60000 + - name: SetIamPolicy + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + resource: source + timeout_millis: 60000 + - name: TestIamPermissions + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + resource: source + timeout_millis: 60000 + - name: UpdateFinding + flattening: + groups: + - parameters: + - finding + required_fields: + - finding + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + finding.name: finding + timeout_millis: 60000 + - name: UpdateOrganizationSettings + flattening: + groups: + - parameters: + - organization_settings + required_fields: + - organization_settings + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + organization_settings.name: organization_settings + timeout_millis: 60000 + - name: UpdateSource + flattening: + groups: + - parameters: + - source + required_fields: + - source + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + source.name: source + timeout_millis: 60000 + - name: UpdateSecurityMarks + flattening: + groups: + - parameters: + - security_marks + required_fields: + - security_marks + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + security_marks.name: securitymarks_oneof + timeout_millis: 60000 + +# Mappings for STATIC_TYPES +# See https://docs.google.com/document/d/1meVVWXYOGRApOH_fKQf48qjce4ewDv_ZiDRClmmCs2w/edit +# +collection_oneofs: + - oneof_name: securitymarks_oneof + collection_names: + - asset_security_marks + - finding_security_marks +resource_name_generation: +- message_name: CreateSourceRequest + field_entity_map: + parent: organization +- message_name: CreateFindingRequest + field_entity_map: + parent: source +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: GetOrganizationSettingsRequest + field_entity_map: + name: organization_settings +- message_name: GetSourceRequest + field_entity_map: + name: source +- message_name: GroupAssetsRequest + field_entity_map: + parent: organization +- message_name: GroupFindingsRequest + field_entity_map: + parent: source +- message_name: ListAssetsRequest + field_entity_map: + parent: organization +- message_name: ListFindingsRequest + field_entity_map: + parent: source +- message_name: ListSourcesRequest + field_entity_map: + parent: organization +- message_name: RunAssetDiscoveryRequest + field_entity_map: + parent: organization +- message_name: SetFindingStateRequest + field_entity_map: + name: finding +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: "*" +- message_name: UpdateFindingRequest + field_entity_map: + name: finding +- message_name: UpdateOrganizationSettingsRequest + field_entity_map: + name: organization_settings +- message_name: UpdateSourceRequest + field_entity_map: + name: source +- message_name: UpdateSecurityMarksRequest + field_entity_map: + name: securitymarks_oneof diff --git a/google/cloud/securitycenter/v1/securitycenter_service.proto b/google/cloud/securitycenter/v1/securitycenter_service.proto new file mode 100644 index 000000000..84e210376 --- /dev/null +++ b/google/cloud/securitycenter/v1/securitycenter_service.proto @@ -0,0 +1,951 @@ +// Copyright 2019 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.securitycenter.v1; + +import "google/api/annotations.proto"; +import "google/cloud/securitycenter/v1/asset.proto"; +import "google/cloud/securitycenter/v1/finding.proto"; +import "google/cloud/securitycenter/v1/organization_settings.proto"; +import "google/cloud/securitycenter/v1/security_marks.proto"; +import "google/cloud/securitycenter/v1/source.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/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.SecurityCenter.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1"; +option php_namespace = "Google\\Cloud\\SecurityCenter\\V1"; +option ruby_package = "Google::Cloud::SecurityCenter::V1"; + +// V1 APIs for Security Center service. +service SecurityCenter { + // Creates a source. + rpc CreateSource(CreateSourceRequest) returns (Source) { + option (google.api.http) = { + post: "/v1/{parent=organizations/*}/sources" + body: "source" + }; + } + + // Creates a finding. The corresponding source must exist for finding creation + // to succeed. + rpc CreateFinding(CreateFindingRequest) returns (Finding) { + option (google.api.http) = { + post: "/v1/{parent=organizations/*/sources/*}/findings" + body: "finding" + }; + } + + // Gets the access control policy on the specified Source. + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v1/{resource=organizations/*/sources/*}:getIamPolicy" + body: "*" + }; + } + + // Gets the settings for an organization. + rpc GetOrganizationSettings(GetOrganizationSettingsRequest) + returns (OrganizationSettings) { + option (google.api.http) = { + get: "/v1/{name=organizations/*/organizationSettings}" + }; + } + + // Gets a source. + rpc GetSource(GetSourceRequest) returns (Source) { + option (google.api.http) = { + get: "/v1/{name=organizations/*/sources/*}" + }; + } + + // Filters an organization's assets and groups them by their specified + // properties. + rpc GroupAssets(GroupAssetsRequest) returns (GroupAssetsResponse) { + option (google.api.http) = { + post: "/v1/{parent=organizations/*}/assets:group" + body: "*" + }; + } + + // Filters an organization or source's findings and groups them by their + // specified properties. + // + // To group across all sources provide a `-` as the source id. + // Example: /v1/organizations/123/sources/-/findings + rpc GroupFindings(GroupFindingsRequest) returns (GroupFindingsResponse) { + option (google.api.http) = { + post: "/v1/{parent=organizations/*/sources/*}/findings:group" + body: "*" + }; + } + + // Lists an organization's assets. + rpc ListAssets(ListAssetsRequest) returns (ListAssetsResponse) { + option (google.api.http) = { + get: "/v1/{parent=organizations/*}/assets" + }; + } + + // Lists an organization or source's findings. + // + // To list across all sources provide a `-` as the source id. + // Example: /v1/organizations/123/sources/-/findings + rpc ListFindings(ListFindingsRequest) returns (ListFindingsResponse) { + option (google.api.http) = { + get: "/v1/{parent=organizations/*/sources/*}/findings" + }; + } + + // Lists all sources belonging to an organization. + rpc ListSources(ListSourcesRequest) returns (ListSourcesResponse) { + option (google.api.http) = { + get: "/v1/{parent=organizations/*}/sources" + }; + } + + // Runs asset discovery. The discovery is tracked with a long-running + // operation. + // + // This API can only be called with limited frequency for an organization. If + // it is called too frequently the caller will receive a TOO_MANY_REQUESTS + // error. + rpc RunAssetDiscovery(RunAssetDiscoveryRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=organizations/*}/assets:runDiscovery" + body: "*" + }; + } + + // Updates the state of a finding. + rpc SetFindingState(SetFindingStateRequest) returns (Finding) { + option (google.api.http) = { + post: "/v1/{name=organizations/*/sources/*/findings/*}:setState" + body: "*" + }; + } + + // Sets the access control policy on the specified Source. + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v1/{resource=organizations/*/sources/*}:setIamPolicy" + body: "*" + }; + } + + // Returns the permissions that a caller has on the specified source. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) + returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v1/{resource=organizations/*/sources/*}:testIamPermissions" + body: "*" + }; + } + + // Creates or updates a finding. The corresponding source must exist for a + // finding creation to succeed. + rpc UpdateFinding(UpdateFindingRequest) returns (Finding) { + option (google.api.http) = { + patch: "/v1/{finding.name=organizations/*/sources/*/findings/*}" + body: "finding" + }; + } + + // Updates an organization's settings. + rpc UpdateOrganizationSettings(UpdateOrganizationSettingsRequest) + returns (OrganizationSettings) { + option (google.api.http) = { + patch: "/v1/{organization_settings.name=organizations/*/organizationSettings}" + body: "organization_settings" + }; + } + + // Updates a source. + rpc UpdateSource(UpdateSourceRequest) returns (Source) { + option (google.api.http) = { + patch: "/v1/{source.name=organizations/*/sources/*}" + body: "source" + }; + } + + // Updates security marks. + rpc UpdateSecurityMarks(UpdateSecurityMarksRequest) returns (SecurityMarks) { + option (google.api.http) = { + patch: "/v1/{security_marks.name=organizations/*/assets/*/securityMarks}" + body: "security_marks" + additional_bindings { + patch: "/v1/{security_marks.name=organizations/*/sources/*/findings/*/securityMarks}" + body: "security_marks" + } + }; + } +} + +// Request message for creating a finding. +message CreateFindingRequest { + // Resource name of the new finding's parent. Its format should be + // "organizations/[organization_id]/sources/[source_id]". + string parent = 1; + + // Unique identifier provided by the client within the parent scope. + // It must be alphanumeric and less than or equal to 32 characters and + // greater than 0 characters in length. + string finding_id = 2; + + // The Finding being created. The name and security_marks will be ignored as + // they are both output only fields on this resource. + Finding finding = 3; +} + +// Request message for creating a source. +message CreateSourceRequest { + // Resource name of the new source's parent. Its format should be + // "organizations/[organization_id]". + string parent = 1; + + // The Source being created, only the display_name and description will be + // used. All other fields will be ignored. + Source source = 2; +} + +// Request message for getting organization settings. +message GetOrganizationSettingsRequest { + // Name of the organization to get organization settings for. Its format is + // "organizations/[organization_id]/organizationSettings". + string name = 1; +} + +// Request message for getting a source. +message GetSourceRequest { + // Relative resource name of the source. Its format is + // "organizations/[organization_id]/source/[source_id]". + string name = 1; +} + +// Request message for grouping by assets. +message GroupAssetsRequest { + // Name of the organization to groupBy. Its format is + // "organizations/[organization_id]". + string parent = 1; + + // Expression that defines the filter to apply across assets. + // The expression is a list of zero or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. The fields map to those + // defined in the Asset resource. Examples include: + // + // * name + // * security_center_properties.resource_name + // * resource_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // The following field and operator combinations are supported: + // name | `=` + // update_time | `>`, `<`, `>=`, `<=` + // iam_policy.policy_blob | '=', ':' + // resource_properties | '=', ':', `>`, `<`, `>=`, `<=` + // security_marks | '=', ':' + // security_center_properties.resource_name | '=', ':' + // security_center_properties.resource_type | '=', ':' + // security_center_properties.resource_parent | '=', ':' + // security_center_properties.resource_project | '=', ':' + // security_center_properties.resource_owners | '=', ':' + // + // For example, `resource_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what assets fields to use for grouping. The string + // value should follow SQL syntax: comma separated list of fields. For + // example: + // "security_center_properties.resource_project,security_center_properties.project". + // + // The following fields are supported when compare_duration is not set: + // + // * security_center_properties.resource_project + // * security_center_properties.resource_type + // * security_center_properties.resource_parent + // + // The following fields are supported when compare_duration is set: + // + // * security_center_properties.resource_type + string group_by = 3; + + // When compare_duration is set, the GroupResult's "state_change" property is + // updated to indicate whether the asset was added, removed, or remained + // present during the compare_duration period of time that precedes the + // read_time. This is the time between (read_time - compare_duration) and + // read_time. + // + // The state change value is derived based on the presence of the asset at the + // two points in time. Intermediate state changes between the two times don't + // affect the result. For example, the results aren't affected if the asset is + // removed and re-created again. + // + // Possible "state_change" values when compare_duration is specified: + // + // * "ADDED": indicates that the asset was not present at the start of + // compare_duration, but present at reference_time. + // * "REMOVED": indicates that the asset was present at the start of + // compare_duration, but not present at reference_time. + // * "ACTIVE": indicates that the asset was present at both the + // start and the end of the time period defined by + // compare_duration and reference_time. + // + // If compare_duration is not specified, then the only possible state_change + // is "UNUSED", which will be the state_change set for all assets present at + // read_time. + // + // If this field is set then `state_change` must be a specified field in + // `group_by`. + google.protobuf.Duration compare_duration = 4; + + // Time used as a reference point when filtering assets. The filter is limited + // to assets existing at the supplied time and their values are those at that + // specific time. Absence of this field will default to the API's version of + // NOW. + google.protobuf.Timestamp read_time = 5; + + // The value returned by the last `GroupAssetsResponse`; indicates + // that this is a continuation of a prior `GroupAssets` call, and that the + // system should return the next page of data. + string page_token = 7; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 8; + + reserved 6; +} + +// Response message for grouping by assets. +message GroupAssetsResponse { + // Group results. There exists an element for each existing unique + // combination of property/values. The element contains a count for the number + // of times those specific property/values appear. + repeated GroupResult group_by_results = 1; + + // Time used for executing the groupBy request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; + + // The total number of results matching the query. + int32 total_size = 4; +} + +// Request message for grouping by findings. +message GroupFindingsRequest { + // Name of the source to groupBy. Its format is + // "organizations/[organization_id]/sources/[source_id]". To groupBy across + // all sources provide a source_id of `-`. For example: + // organizations/123/sources/- + string parent = 1; + + // Expression that defines the filter to apply across findings. + // The expression is a list of one or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. Examples include: + // + // * name + // * source_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // The following field and operator combinations are supported: + // name | `=` + // parent | '=', ':' + // resource_name | '=', ':' + // state | '=', ':' + // category | '=', ':' + // external_uri | '=', ':' + // event_time | `>`, `<`, `>=`, `<=` + // security_marks | '=', ':' + // source_properties | '=', ':', `>`, `<`, `>=`, `<=` + // + // For example, `source_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what assets fields to use for grouping (including + // `state_change`). The string value should follow SQL syntax: comma separated + // list of fields. For example: "parent,resource_name". + // + // The following fields are supported: + // + // * resource_name + // * category + // * state + // * parent + // + // The following fields are supported when compare_duration is set: + // + // * state_change + string group_by = 3; + + // Time used as a reference point when filtering findings. The filter is + // limited to findings existing at the supplied time and their values are + // those at that specific time. Absence of this field will default to the + // API's version of NOW. + google.protobuf.Timestamp read_time = 4; + + // When compare_duration is set, the GroupResult's "state_change" attribute is + // updated to indicate whether the finding had its state changed, the + // finding's state remained unchanged, or if the finding was added during the + // compare_duration period of time that precedes the read_time. This is the + // time between (read_time - compare_duration) and read_time. + // + // The state_change value is derived based on the presence and state of the + // finding at the two points in time. Intermediate state changes between the + // two times don't affect the result. For example, the results aren't affected + // if the finding is made inactive and then active again. + // + // Possible "state_change" values when compare_duration is specified: + // + // * "CHANGED": indicates that the finding was present at the start of + // compare_duration, but changed its state at read_time. + // * "UNCHANGED": indicates that the finding was present at the start of + // compare_duration and did not change state at read_time. + // * "ADDED": indicates that the finding was not present at the start + // of compare_duration, but was present at read_time. + // + // If compare_duration is not specified, then the only possible state_change + // is "UNUSED", which will be the state_change set for all findings present + // at read_time. + // + // If this field is set then `state_change` must be a specified field in + // `group_by`. + google.protobuf.Duration compare_duration = 5; + + // The value returned by the last `GroupFindingsResponse`; indicates + // that this is a continuation of a prior `GroupFindings` call, and + // that the system should return the next page of data. + string page_token = 7; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 8; + + reserved 6; +} + +// Response message for group by findings. +message GroupFindingsResponse { + // Group results. There exists an element for each existing unique + // combination of property/values. The element contains a count for the number + // of times those specific property/values appear. + repeated GroupResult group_by_results = 1; + + // Time used for executing the groupBy request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; + + // The total number of results matching the query. + int32 total_size = 4; +} + +// Result containing the properties and count of a groupBy request. +message GroupResult { + // Properties matching the groupBy fields in the request. + map<string, google.protobuf.Value> properties = 1; + + // Total count of resources for the given properties. + int64 count = 2; +} + +// Request message for listing sources. +message ListSourcesRequest { + // Resource name of the parent of sources to list. Its format should be + // "organizations/[organization_id]". + string parent = 1; + + // The value returned by the last `ListSourcesResponse`; indicates + // that this is a continuation of a prior `ListSources` call, and + // that the system should return the next page of data. + string page_token = 2; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 7; +} + +// Response message for listing sources. +message ListSourcesResponse { + // Sources belonging to the requested parent. + repeated Source sources = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 2; +} + +// Request message for listing assets. +message ListAssetsRequest { + // Name of the organization assets should belong to. Its format is + // "organizations/[organization_id]". + string parent = 1; + + // Expression that defines the filter to apply across assets. + // The expression is a list of zero or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. The fields map to those + // defined in the Asset resource. Examples include: + // + // * name + // * security_center_properties.resource_name + // * resource_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // The following are the allowed field and operator combinations: + // name | `=` + // update_time | `>`, `<`, `>=`, `<=` + // iam_policy.policy_blob | '=', ':' + // resource_properties | '=', ':', `>`, `<`, `>=`, `<=` + // security_marks | '=', ':' + // security_center_properties.resource_name | '=', ':' + // security_center_properties.resource_type | '=', ':' + // security_center_properties.resource_parent | '=', ':' + // security_center_properties.resource_project | '=', ':' + // security_center_properties.resource_owners | '=', ':' + // + // For example, `resource_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what fields and order to use for sorting. The + // string value should follow SQL syntax: comma separated list of fields. For + // example: "name,resource_properties.a_property". The default sorting order + // is ascending. To specify descending order for a field, a suffix " desc" + // should be appended to the field name. For example: "name + // desc,resource_properties.a_property". Redundant space characters in the + // syntax are insignificant. "name desc,resource_properties.a_property" and " + // name desc , resource_properties.a_property " are equivalent. + // + // The following fields are supported: + // name + // update_time + // resource_properties + // security_marks + // security_center_properties.resource_name + // security_center_properties.resource_parent + // security_center_properties.resource_project + // security_center_properties.resource_type + string order_by = 3; + + // Time used as a reference point when filtering assets. The filter is limited + // to assets existing at the supplied time and their values are those at that + // specific time. Absence of this field will default to the API's version of + // NOW. + google.protobuf.Timestamp read_time = 4; + + // When compare_duration is set, the ListAssetsResult's "state_change" + // attribute is updated to indicate whether the asset was added, removed, or + // remained present during the compare_duration period of time that precedes + // the read_time. This is the time between (read_time - compare_duration) and + // read_time. + // + // The state_change value is derived based on the presence of the asset at the + // two points in time. Intermediate state changes between the two times don't + // affect the result. For example, the results aren't affected if the asset is + // removed and re-created again. + // + // Possible "state_change" values when compare_duration is specified: + // + // * "ADDED": indicates that the asset was not present at the start of + // compare_duration, but present at read_time. + // * "REMOVED": indicates that the asset was present at the start of + // compare_duration, but not present at read_time. + // * "ACTIVE": indicates that the asset was present at both the + // start and the end of the time period defined by + // compare_duration and read_time. + // + // If compare_duration is not specified, then the only possible state_change + // is "UNUSED", which will be the state_change set for all assets present at + // read_time. + google.protobuf.Duration compare_duration = 5; + + // Optional. + // + // A field mask to specify the ListAssetsResult fields to be listed in the + // response. + // An empty field mask will list all fields. + google.protobuf.FieldMask field_mask = 7; + + // The value returned by the last `ListAssetsResponse`; indicates + // that this is a continuation of a prior `ListAssets` call, and + // that the system should return the next page of data. + string page_token = 8; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 9; + + reserved 6; +} + +// Response message for listing assets. +message ListAssetsResponse { + // Result containing the Asset and its State. + message ListAssetsResult { + // The change in state of the asset. + // + // When querying across two points in time this describes + // the change between the two points: ADDED, REMOVED, or ACTIVE. + // If there was no compare_duration supplied in the request the state change + // will be: UNUSED + enum StateChange { + // State change is unused, this is the canonical default for this enum. + UNUSED = 0; + + // Asset was added between the points in time. + ADDED = 1; + + // Asset was removed between the points in time. + REMOVED = 2; + + // Asset was present at both point(s) in time. + ACTIVE = 3; + } + + // Asset matching the search request. + Asset asset = 1; + + // State change of the asset between the points in time. + StateChange state_change = 2; + } + + // Assets matching the list request. + repeated ListAssetsResult list_assets_results = 1; + + // Time used for executing the list request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; + + // The total number of assets matching the query. + int32 total_size = 4; +} + +// Request message for listing findings. +message ListFindingsRequest { + // Name of the source the findings belong to. Its format is + // "organizations/[organization_id]/sources/[source_id]". To list across all + // sources provide a source_id of `-`. For example: + // organizations/123/sources/- + string parent = 1; + + // Expression that defines the filter to apply across findings. + // The expression is a list of one or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. Examples include: + // + // * name + // * source_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // The following field and operator combinations are supported: + // name | `=` + // parent | '=', ':' + // resource_name | '=', ':' + // state | '=', ':' + // category | '=', ':' + // external_uri | '=', ':' + // event_time | `>`, `<`, `>=`, `<=` + // security_marks | '=', ':' + // source_properties | '=', ':', `>`, `<`, `>=`, `<=` + // + // For example, `source_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what fields and order to use for sorting. The + // string value should follow SQL syntax: comma separated list of fields. For + // example: "name,resource_properties.a_property". The default sorting order + // is ascending. To specify descending order for a field, a suffix " desc" + // should be appended to the field name. For example: "name + // desc,source_properties.a_property". Redundant space characters in the + // syntax are insignificant. "name desc,source_properties.a_property" and " + // name desc , source_properties.a_property " are equivalent. + // + // The following fields are supported: + // name + // parent + // state + // category + // resource_name + // event_time + // source_properties + // security_marks + string order_by = 3; + + // Time used as a reference point when filtering findings. The filter is + // limited to findings existing at the supplied time and their values are + // those at that specific time. Absence of this field will default to the + // API's version of NOW. + google.protobuf.Timestamp read_time = 4; + + // When compare_duration is set, the ListFindingsResult's "state_change" + // attribute is updated to indicate whether the finding had its state changed, + // the finding's state remained unchanged, or if the finding was added in any + // state during the compare_duration period of time that precedes the + // read_time. This is the time between (read_time - compare_duration) and + // read_time. + // + // The state_change value is derived based on the presence and state of the + // finding at the two points in time. Intermediate state changes between the + // two times don't affect the result. For example, the results aren't affected + // if the finding is made inactive and then active again. + // + // Possible "state_change" values when compare_duration is specified: + // + // * "CHANGED": indicates that the finding was present at the start of + // compare_duration, but changed its state at read_time. + // * "UNCHANGED": indicates that the finding was present at the start of + // compare_duration and did not change state at read_time. + // * "ADDED": indicates that the finding was not present at the start + // of compare_duration, but was present at read_time. + // + // If compare_duration is not specified, then the only possible state_change + // is "UNUSED", which will be the state_change set for all findings present at + // read_time. + google.protobuf.Duration compare_duration = 5; + + // Optional. + // + // A field mask to specify the Finding fields to be listed in the response. + // An empty field mask will list all fields. + google.protobuf.FieldMask field_mask = 7; + + // The value returned by the last `ListFindingsResponse`; indicates + // that this is a continuation of a prior `ListFindings` call, and + // that the system should return the next page of data. + string page_token = 8; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 9; + + reserved 6; +} + +// Response message for listing findings. +message ListFindingsResponse { + // Result containing the Finding and its StateChange. + message ListFindingsResult { + // The change in state of the finding. + // + // When querying across two points in time this describes + // the change in the finding between the two points: CHANGED, UNCHANGED, + // ADDED, or REMOVED. Findings can not be deleted, so REMOVED implies that + // the finding at timestamp does not match the filter specified, but it did + // at timestamp - compare_duration. If there was no compare_duration + // supplied in the request the state change will be: UNUSED + enum StateChange { + // State change is unused, this is the canonical default for this enum. + UNUSED = 0; + + // The finding has changed state in some way between the points in time + // and existed at both points. + CHANGED = 1; + + // The finding has not changed state between the points in time and + // existed at both points. + UNCHANGED = 2; + + // The finding was created between the points in time. + ADDED = 3; + + // The finding at timestamp does not match the filter specified, but it + // did at timestamp - compare_duration. + REMOVED = 4; + } + + // Finding matching the search request. + Finding finding = 1; + + // State change of the finding between the points in time. + StateChange state_change = 2; + } + + // Findings matching the list request. + repeated ListFindingsResult list_findings_results = 1; + + // Time used for executing the list request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; + + // The total number of findings matching the query. + int32 total_size = 4; +} + +// Request message for updating a finding's state. +message SetFindingStateRequest { + // The relative resource name of the finding. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/sources/456/finding/789". + string name = 1; + + // The desired State of the finding. + Finding.State state = 2; + + // The time at which the updated state takes effect. + google.protobuf.Timestamp start_time = 3; +} + +// Request message for running asset discovery for an organization. +message RunAssetDiscoveryRequest { + // Name of the organization to run asset discovery for. Its format is + // "organizations/[organization_id]". + string parent = 1; +} + +// Request message for updating or creating a finding. +message UpdateFindingRequest { + // The finding resource to update or create if it does not already exist. + // parent, security_marks, and update_time will be ignored. + // + // In the case of creation, the finding id portion of the name must be + // alphanumeric and less than or equal to 32 characters and greater than 0 + // characters in length. + Finding finding = 1; + + // The FieldMask to use when updating the finding resource. This field should + // not be specified when creating a finding. + // + // When updating a finding, an empty mask is treated as updating all mutable + // fields and replacing source_properties. Individual source_properties can + // be added/updated by using "source_properties.<property key>" in the field + // mask. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for updating an organization's settings. +message UpdateOrganizationSettingsRequest { + // The organization settings resource to update. + OrganizationSettings organization_settings = 1; + + // The FieldMask to use when updating the settings resource. + // + // If empty all mutable fields will be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for updating a source. +message UpdateSourceRequest { + // The source resource to update. + Source source = 1; + + // The FieldMask to use when updating the source resource. + // + // If empty all mutable fields will be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for updating a SecurityMarks resource. +message UpdateSecurityMarksRequest { + // The security marks resource to update. + SecurityMarks security_marks = 1; + + // The FieldMask to use when updating the security marks resource. + // + // The field mask must not contain duplicate fields. + // If empty or set to "marks", all marks will be replaced. Individual + // marks can be updated using "marks.<mark_key>". + google.protobuf.FieldMask update_mask = 2; + + // The time at which the updated SecurityMarks take effect. + // If not set uses current server time. Updates will be applied to the + // SecurityMarks that are active immediately preceding this time. + google.protobuf.Timestamp start_time = 3; +} diff --git a/google/cloud/securitycenter/v1/source.proto b/google/cloud/securitycenter/v1/source.proto new file mode 100644 index 000000000..07f4c59b2 --- /dev/null +++ b/google/cloud/securitycenter/v1/source.proto @@ -0,0 +1,57 @@ +// Copyright 2019 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.securitycenter.v1; + +import "google/api/annotations.proto"; + +option csharp_namespace = "Google.Cloud.SecurityCenter.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1"; +option php_namespace = "Google\\Cloud\\SecurityCenter\\V1"; + +// Cloud Security Command Center's (Cloud SCC) finding source. A finding source +// is an entity or a mechanism that can produce a finding. A source is like a +// container of findings that come from the same scanner, logger, monitor, etc. +message Source { + // The relative resource name of this source. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/sources/456" + string name = 1; + + // The source’s display name. + // A source’s display name must be unique amongst its siblings, for example, + // two sources with the same parent can't share the same display name. + // The display name must start and end with a letter or digit, may contain + // letters, digits, spaces, hyphens, and underscores, and can be no longer + // than 32 characters. This is captured by the regular expression: + // [\p{L}\p{N}]({\p{L}\p{N}_- ]{0,30}[\p{L}\p{N}])?. + string display_name = 2; + + // The description of the source (max of 1024 characters). + // Example: + // "Cloud Security Scanner is a web security scanner for common + // vulnerabilities in App Engine applications. It can automatically + // scan and detect four common vulnerabilities, including cross-site-scripting + // (XSS), Flash injection, mixed content (HTTP in HTTPS), and + // outdated/insecure libraries." + string description = 3; + + reserved 4; +} diff --git a/google/cloud/securitycenter/v1beta1/BUILD.bazel b/google/cloud/securitycenter/v1beta1/BUILD.bazel new file mode 100644 index 000000000..89ab6cf58 --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/BUILD.bazel @@ -0,0 +1,158 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "securitycenter_proto", + srcs = [ + "asset.proto", + "finding.proto", + "organization_settings.proto", + "security_marks.proto", + "securitycenter_service.proto", + "source.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/iam/v1:iam_policy_proto", + "//google/iam/v1:policy_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:struct_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "securitycenter_proto_with_info", + deps = [":securitycenter_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", + "@com_google_api_grpc_proto_google_iam_v1//jar", +] + +java_proto_library( + name = "securitycenter_java_proto", + deps = [":securitycenter_proto"], +) + +java_grpc_library( + name = "securitycenter_java_grpc", + srcs = [":securitycenter_proto"], + deps = [":securitycenter_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "securitycenter_resource_name_java_proto", + gapic_yaml = "securitycenter_gapic.yaml", + deps = [":securitycenter_proto"], +) + +java_gapic_library( + name = "securitycenter_java_gapic", + src = ":securitycenter_proto_with_info", + gapic_yaml = "securitycenter_gapic.yaml", + service_yaml = "//google/cloud/securitycenter:securitycenter_v1beta1.yaml", + test_deps = [":securitycenter_java_grpc"], + deps = [ + ":securitycenter_java_proto", + "securitycenter_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":securitycenter_java_gapic_test"], +) for test_name in [ + "com.google.cloud.securitycenter.v1beta1.SecurityCenterClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-securitycenter-v1beta1-java", + client_deps = [":securitycenter_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":securitycenter_java_gapic_test"], + grpc_deps = [":securitycenter_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":securitycenter_java_proto", + ":securitycenter_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "securitycenter_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1", + protos = [":securitycenter_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/iam/v1:iam_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "securitycenter_go_gapic", + src = ":securitycenter_proto_with_info", + gapic_yaml = "securitycenter_gapic.yaml", + importpath = "cloud.google.com/go/securitycenter/apiv1beta1", + service_yaml = "//google/cloud/securitycenter:securitycenter_v1beta1.yaml", + deps = [ + ":securitycenter_go_proto", + "//google/iam/v1:iam_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "securitycenter_go_gapic_test", + srcs = [":securitycenter_go_gapic_srcjar_test"], + embed = [":securitycenter_go_gapic"], + importpath = "cloud.google.com/go/securitycenter/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-securitycenter-v1beta1-go", + deps = [ + ":securitycenter_go_gapic", + ":securitycenter_go_gapic_srcjar-smoke-test.srcjar", + ":securitycenter_go_gapic_srcjar-test.srcjar", + ":securitycenter_go_proto", + ], +) diff --git a/google/cloud/securitycenter/v1beta1/asset.proto b/google/cloud/securitycenter/v1beta1/asset.proto new file mode 100644 index 000000000..3dd5b3581 --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/asset.proto @@ -0,0 +1,86 @@ +// Copyright 2018 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.securitycenter.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/securitycenter/v1beta1/security_marks.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1beta1"; + +// Cloud Security Command Center's (Cloud SCC) representation of a Google Cloud +// Platform (GCP) resource. +// +// The Asset is a Cloud SCC resource that captures information about a single +// GCP resource. All modifications to an Asset are only within the context of +// Cloud SCC and don't affect the referenced GCP resource. +message Asset { + // Cloud SCC managed properties. These properties are managed by Cloud SCC and + // cannot be modified by the user. + message SecurityCenterProperties { + // The full resource name of the GCP resource this asset + // represents. This field is immutable after create time. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + string resource_name = 1; + + // The type of the GCP resource. Examples include: APPLICATION, + // PROJECT, and ORGANIZATION. This is a case insensitive field defined by + // Cloud SCC and/or the producer of the resource and is immutable + // after create time. + string resource_type = 2; + + // The full resource name of the immediate parent of the resource. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + string resource_parent = 3; + + // The full resource name of the project the resource belongs to. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + string resource_project = 4; + + // Owners of the Google Cloud resource. + repeated string resource_owners = 5; + } + + // The relative resource name of this asset. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/assets/456". + string name = 1; + + // Cloud SCC managed properties. These properties are managed by + // Cloud SCC and cannot be modified by the user. + SecurityCenterProperties security_center_properties = 2; + + // Resource managed properties. These properties are managed and defined by + // the GCP resource and cannot be modified by the user. + map<string, google.protobuf.Value> resource_properties = 7; + + // User specified security marks. These marks are entirely managed by the user + // and come from the SecurityMarks resource that belongs to the asset. + SecurityMarks security_marks = 8; + + // The time at which the asset was created in Cloud SCC. + google.protobuf.Timestamp create_time = 9; + + // The time at which the asset was last updated, added, or deleted in Cloud + // SCC. + google.protobuf.Timestamp update_time = 10; +} diff --git a/google/cloud/securitycenter/v1beta1/finding.proto b/google/cloud/securitycenter/v1beta1/finding.proto new file mode 100644 index 000000000..21dfdd561 --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/finding.proto @@ -0,0 +1,99 @@ +// Copyright 2018 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.securitycenter.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/securitycenter/v1beta1/security_marks.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1beta1"; + +// Cloud Security Command Center (Cloud SCC) finding. +// +// A finding is a record of assessment data (security, risk, health or privacy) +// ingested into Cloud SCC for presentation, notification, analysis, +// policy testing, and enforcement. For example, an XSS vulnerability in an +// App Engine application is a finding. +message Finding { + // The state of the finding. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The finding requires attention and has not been addressed yet. + ACTIVE = 1; + + // The finding has been fixed, triaged as a non-issue or otherwise addressed + // and is no longer active. + INACTIVE = 2; + } + + // The relative resource name of this finding. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/sources/456/findings/789" + string name = 1; + + // The relative resource name of the source the finding belongs to. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // This field is immutable after creation time. + // For example: + // "organizations/123/sources/456" + string parent = 2; + + // The full resource name of the Google Cloud Platform (GCP) resource this + // finding is for. See: + // https://cloud.google.com/apis/design/resource_names#full_resource_name + // This field is immutable after creation time. + string resource_name = 3; + + // The state of the finding. + State state = 4; + + // The additional taxonomy group within findings from a given source. + // This field is immutable after creation time. + // Example: "XSS_FLASH_INJECTION" + string category = 5; + + // The URI that, if available, points to a web page outside of Cloud SCC + // where additional information about the finding can be found. This field is + // guaranteed to be either empty or a well formed URL. + string external_uri = 6; + + // Source specific properties. These properties are managed by the source + // that writes the finding. The key names in the source_properties map must be + // between 1 and 255 characters, and must start with a letter and contain + // alphanumeric characters or underscores only. + map<string, google.protobuf.Value> source_properties = 7; + + // Output only. User specified security marks. These marks are entirely + // managed by the user and come from the SecurityMarks resource that belongs + // to the finding. + SecurityMarks security_marks = 8; + + // The time at which the event took place. For example, if the finding + // represents an open firewall it would capture the time the open firewall was + // detected. + google.protobuf.Timestamp event_time = 9; + + // The time at which the finding was created in Cloud SCC. + google.protobuf.Timestamp create_time = 10; +} diff --git a/google/cloud/securitycenter/v1beta1/organization_settings.proto b/google/cloud/securitycenter/v1beta1/organization_settings.proto new file mode 100644 index 000000000..ca9be1145 --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/organization_settings.proto @@ -0,0 +1,74 @@ +// Copyright 2018 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.securitycenter.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1beta1"; + +// User specified settings that are attached to the Cloud Security Command +// Center (Cloud SCC) organization. +message OrganizationSettings { + // The configuration used for Asset Discovery runs. + message AssetDiscoveryConfig { + // The mode of inclusion when running Asset Discovery. + // Asset discovery can be limited by explicitly identifying projects to be + // included or excluded. If INCLUDE_ONLY is set, then only those projects + // within the organization and their children are discovered during asset + // discovery. If EXCLUDE is set, then projects that don't match those + // projects are discovered during asset discovery. If neither are set, then + // all projects within the organization are discovered during asset + // discovery. + enum InclusionMode { + // Unspecified. Setting the mode with this value will disable + // inclusion/exclusion filtering for Asset Discovery. + INCLUSION_MODE_UNSPECIFIED = 0; + + // Asset Discovery will capture only the resources within the projects + // specified. All other resources will be ignored. + INCLUDE_ONLY = 1; + + // Asset Discovery will ignore all resources under the projects specified. + // All other resources will be retrieved. + EXCLUDE = 2; + } + + // The project ids to use for filtering asset discovery. + repeated string project_ids = 1; + + // The mode to use for filtering asset discovery. + InclusionMode inclusion_mode = 2; + } + + // The relative resource name of the settings. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/organizationSettings". + string name = 1; + + // A flag that indicates if Asset Discovery should be enabled. If the flag is + // set to `true`, then discovery of assets will occur. If it is set to `false, + // all historical assets will remain, but discovery of future assets will not + // occur. + bool enable_asset_discovery = 2; + + // The configuration used for Asset Discovery runs. + AssetDiscoveryConfig asset_discovery_config = 3; +} diff --git a/google/cloud/securitycenter/v1beta1/security_marks.proto b/google/cloud/securitycenter/v1beta1/security_marks.proto new file mode 100644 index 000000000..cfcb5f7dc --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/security_marks.proto @@ -0,0 +1,45 @@ +// Copyright 2018 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.securitycenter.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1beta1"; + +// User specified security marks that are attached to the parent Cloud Security +// Command Center (Cloud SCC) resource. Security marks are scoped within a Cloud +// SCC organization -- they can be modified and viewed by all users who have +// proper permissions on the organization. +message SecurityMarks { + // The relative resource name of the SecurityMarks. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Examples: + // "organizations/123/assets/456/securityMarks" + // "organizations/123/sources/456/findings/789/securityMarks". + string name = 1; + + // Mutable user specified security marks belonging to the parent resource. + // Constraints are as follows: + // - Keys and values are treated as case insensitive + // - Keys must be alphanumeric and between 1 - 256 characters (inclusive) + // - Values have leading and trailing whitespace trimmed, remaining + // characters must be between 1 - 4096 characters (inclusive) + map<string, string> marks = 2; +} diff --git a/google/cloud/securitycenter/v1beta1/securitycenter_gapic.yaml b/google/cloud/securitycenter/v1beta1/securitycenter_gapic.yaml new file mode 100644 index 000000000..b8d9230ce --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/securitycenter_gapic.yaml @@ -0,0 +1,460 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.securitycenter.v1beta1 + python: + package_name: google.cloud.securitycenter_v1beta1.gapic + go: + package_name: cloud.google.com/go/securitycenter/apiv1beta1 + csharp: + package_name: Google.Cloud.Securitycenter.V1beta1 + ruby: + package_name: Google::Cloud::Securitycenter::V1beta1 + php: + package_name: Google\Cloud\Securitycenter\V1beta1 + nodejs: + package_name: security-center.v1beta1 + domain_layer_location: google-cloud +# A list of resource collection configurations. +# Consists of a name_pattern and an entity_name. +# The name_pattern is a pattern to describe the names of the resources of this +# collection, using the platform's conventions for URI patterns. A generator +# may use this to generate methods to compose and decompose such names. The +# pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; +# those will be taken as hints for the parameter names of the generated +# methods. If empty, no name methods are generated. +# The entity_name is the name to be used as a basis for generated methods and +# classes. +collections: +- name_pattern: organizations/{organization} + entity_name: organization +- name_pattern: organizations/{organization}/assets/{asset}/securityMarks + entity_name: asset_security_marks +- name_pattern: organizations/{organization}/sources/{source}/findings/{finding}/securityMarks + entity_name: finding_security_marks +- name_pattern: organizations/{organization}/organizationSettings + entity_name: organization_settings +- name_pattern: organizations/{organization}/sources/{source} + entity_name: source +- name_pattern: organizations/{organization}/sources/{source}/findings/{finding} + entity_name: finding +collection_oneofs: +- oneof_name: securitymarks_oneof + collection_names: + - asset_security_marks + - finding_security_marks +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.securitycenter.v1beta1.SecurityCenter + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateSource + flattening: + groups: + - parameters: + - parent + - source + required_fields: + - parent + - source + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: CreateFinding + flattening: + groups: + - parameters: + - parent + - finding_id + - finding + required_fields: + - parent + - finding_id + - finding + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: source + timeout_millis: 60000 + - name: GetIamPolicy + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + resource: source + timeout_millis: 60000 + - name: GetOrganizationSettings + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: organization_settings + timeout_millis: 60000 + - name: GetSource + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: source + timeout_millis: 60000 + - name: GroupAssets + required_fields: + - parent + - group_by + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: group_by_results + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: GroupFindings + flattening: + groups: + - parameters: + - parent + - group_by + required_fields: + - parent + - group_by + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: group_by_results + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: source + timeout_millis: 60000 + - name: ListAssets + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: list_assets_results + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: ListFindings + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: findings + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: source + timeout_millis: 60000 + - name: ListSources + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: sources + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + timeout_millis: 60000 + - name: RunAssetDiscovery + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + parent: organization + long_running: + return_type: google.protobuf.Empty + metadata_type: google.protobuf.Empty + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 60000 + - name: SetFindingState + flattening: + groups: + - parameters: + - name + - state + - start_time + required_fields: + - name + - state + - start_time + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + name: finding + timeout_millis: 60000 + - name: SetIamPolicy + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + resource: source + timeout_millis: 60000 + - name: TestIamPermissions + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + retry_codes_name: idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + resource: source + timeout_millis: 60000 + - name: UpdateFinding + flattening: + groups: + - parameters: + - finding + required_fields: + - finding + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + finding.name: finding + timeout_millis: 60000 + - name: UpdateOrganizationSettings + flattening: + groups: + - parameters: + - organization_settings + required_fields: + - organization_settings + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + organization_settings.name: organization_settings + timeout_millis: 60000 + - name: UpdateSource + flattening: + groups: + - parameters: + - source + required_fields: + - source + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + source.name: source + timeout_millis: 60000 + - name: UpdateSecurityMarks + flattening: + groups: + - parameters: + - security_marks + required_fields: + - security_marks + retry_codes_name: non_idempotent + retry_params_name: default + resource_name_treatment: STATIC_TYPES + field_name_patterns: + security_marks.name: securitymarks_oneof + timeout_millis: 60000 +resource_name_generation: +- message_name: CreateSourceRequest + field_entity_map: + parent: organization +- message_name: CreateFindingRequest + field_entity_map: + parent: source +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: source +- message_name: GetOrganizationSettingsRequest + field_entity_map: + name: organization_settings +- message_name: GetSourceRequest + field_entity_map: + name: source +- message_name: GroupAssetsRequest + field_entity_map: + parent: organization +- message_name: GroupFindingsRequest + field_entity_map: + parent: source +- message_name: ListAssetsRequest + field_entity_map: + parent: organization +- message_name: ListFindingsRequest + field_entity_map: + parent: source +- message_name: ListSourcesRequest + field_entity_map: + parent: organization +- message_name: RunAssetDiscoveryRequest + field_entity_map: + parent: organization +- message_name: SetFindingStateRequest + field_entity_map: + name: finding +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: source +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: source +- message_name: UpdateFindingRequest + field_entity_map: + name: finding +- message_name: UpdateOrganizationSettingsRequest + field_entity_map: + name: organization_settings +- message_name: UpdateSourceRequest + field_entity_map: + name: source +- message_name: UpdateSecurityMarksRequest + field_entity_map: + name: securitymarks_oneof diff --git a/google/cloud/securitycenter/v1beta1/securitycenter_service.proto b/google/cloud/securitycenter/v1beta1/securitycenter_service.proto new file mode 100644 index 000000000..dafce562d --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/securitycenter_service.proto @@ -0,0 +1,755 @@ +// Copyright 2018 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.securitycenter.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/securitycenter/v1beta1/asset.proto"; +import "google/cloud/securitycenter/v1beta1/finding.proto"; +import "google/cloud/securitycenter/v1beta1/organization_settings.proto"; +import "google/cloud/securitycenter/v1beta1/security_marks.proto"; +import "google/cloud/securitycenter/v1beta1/source.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/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1beta1"; + +// V1 Beta APIs for Security Center service. +service SecurityCenter { + // Creates a source. + rpc CreateSource(CreateSourceRequest) returns (Source) { + option (google.api.http) = { + post: "/v1beta1/{parent=organizations/*}/sources" + body: "source" + }; + } + + // Creates a finding. The corresponding source must exist for finding creation + // to succeed. + rpc CreateFinding(CreateFindingRequest) returns (Finding) { + option (google.api.http) = { + post: "/v1beta1/{parent=organizations/*/sources/*}/findings" + body: "finding" + }; + } + + // Gets the access control policy on the specified Source. + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v1beta1/{resource=organizations/*/sources/*}:getIamPolicy" + body: "*" + }; + } + + // Gets the settings for an organization. + rpc GetOrganizationSettings(GetOrganizationSettingsRequest) + returns (OrganizationSettings) { + option (google.api.http) = { + get: "/v1beta1/{name=organizations/*/organizationSettings}" + }; + } + + // Gets a source. + rpc GetSource(GetSourceRequest) returns (Source) { + option (google.api.http) = { + get: "/v1beta1/{name=organizations/*/sources/*}" + }; + } + + // Filters an organization's assets and groups them by their specified + // properties. + rpc GroupAssets(GroupAssetsRequest) returns (GroupAssetsResponse) { + option (google.api.http) = { + post: "/v1beta1/{parent=organizations/*}/assets:group" + body: "*" + }; + } + + // Filters an organization or source's findings and groups them by their + // specified properties. + // + // To group across all sources provide a `-` as the source id. + // Example: /v1beta1/organizations/123/sources/-/findings + rpc GroupFindings(GroupFindingsRequest) returns (GroupFindingsResponse) { + option (google.api.http) = { + post: "/v1beta1/{parent=organizations/*/sources/*}/findings:group" + body: "*" + }; + } + + // Lists an organization's assets. + rpc ListAssets(ListAssetsRequest) returns (ListAssetsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=organizations/*}/assets" + }; + } + + // Lists an organization or source's findings. + // + // To list across all sources provide a `-` as the source id. + // Example: /v1beta1/organizations/123/sources/-/findings + rpc ListFindings(ListFindingsRequest) returns (ListFindingsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=organizations/*/sources/*}/findings" + }; + } + + // Lists all sources belonging to an organization. + rpc ListSources(ListSourcesRequest) returns (ListSourcesResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=organizations/*}/sources" + }; + } + + // Runs asset discovery. The discovery is tracked with a long-running + // operation. + // + // This API can only be called with limited frequency for an organization. If + // it is called too frequently the caller will receive a TOO_MANY_REQUESTS + // error. + rpc RunAssetDiscovery(RunAssetDiscoveryRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=organizations/*}/assets:runDiscovery" + body: "*" + }; + } + + // Updates the state of a finding. + rpc SetFindingState(SetFindingStateRequest) returns (Finding) { + option (google.api.http) = { + post: "/v1beta1/{name=organizations/*/sources/*/findings/*}:setState" + body: "*" + }; + } + + // Sets the access control policy on the specified Source. + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v1beta1/{resource=organizations/*/sources/*}:setIamPolicy" + body: "*" + }; + } + + // Returns the permissions that a caller has on the specified source. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) + returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v1beta1/{resource=organizations/*/sources/*}:testIamPermissions" + body: "*" + }; + } + + // Creates or updates a finding. The corresponding source must exist for a + // finding creation to succeed. + rpc UpdateFinding(UpdateFindingRequest) returns (Finding) { + option (google.api.http) = { + patch: "/v1beta1/{finding.name=organizations/*/sources/*/findings/*}" + body: "finding" + }; + } + + // Updates an organization's settings. + rpc UpdateOrganizationSettings(UpdateOrganizationSettingsRequest) + returns (OrganizationSettings) { + option (google.api.http) = { + patch: "/v1beta1/{organization_settings.name=organizations/*/organizationSettings}" + body: "organization_settings" + }; + } + + // Updates a source. + rpc UpdateSource(UpdateSourceRequest) returns (Source) { + option (google.api.http) = { + patch: "/v1beta1/{source.name=organizations/*/sources/*}" + body: "source" + }; + } + + // Updates security marks. + rpc UpdateSecurityMarks(UpdateSecurityMarksRequest) returns (SecurityMarks) { + option (google.api.http) = { + patch: "/v1beta1/{security_marks.name=organizations/*/assets/*/securityMarks}" + body: "security_marks" + additional_bindings { + patch: "/v1beta1/{security_marks.name=organizations/*/sources/*/findings/*/securityMarks}" + body: "security_marks" + } + }; + } +} + +// Request message for creating a finding. +message CreateFindingRequest { + // Resource name of the new finding's parent. Its format should be + // "organizations/[organization_id]/sources/[source_id]". + string parent = 1; + + // Unique identifier provided by the client within the parent scope. + // It must be alphanumeric and less than or equal to 32 characters and + // greater than 0 characters in length. + string finding_id = 2; + + // The Finding being created. The name and security_marks will be ignored as + // they are both output only fields on this resource. + Finding finding = 3; +} + +// Request message for creating a source. +message CreateSourceRequest { + // Resource name of the new source's parent. Its format should be + // "organizations/[organization_id]". + string parent = 1; + + // The Source being created, only the display_name and description will be + // used. All other fields will be ignored. + Source source = 2; +} + +// Request message for getting organization settings. +message GetOrganizationSettingsRequest { + // Name of the organization to get organization settings for. Its format is + // "organizations/[organization_id]/organizationSettings". + string name = 1; +} + +// Request message for getting a source. +message GetSourceRequest { + // Relative resource name of the source. Its format is + // "organizations/[organization_id]/source/[source_id]". + string name = 1; +} + +// Request message for grouping by assets. +message GroupAssetsRequest { + // Name of the organization to groupBy. Its format is + // "organizations/[organization_id]". + string parent = 1; + + // Expression that defines the filter to apply across assets. + // The expression is a list of zero or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are not supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. The fields map to those + // defined in the Asset resource. Examples include: + // + // * name + // * security_center_properties.resource_name + // * resource_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // For example, `resource_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what assets fields to use for grouping. The string + // value should follow SQL syntax: comma separated list of fields. For + // example: + // "security_center_properties.resource_project,security_center_properties.project". + // + // The following fields are supported when compare_duration is not set: + // + // * security_center_properties.resource_project + // * security_center_properties.resource_type + // * security_center_properties.resource_parent + // + // The following fields are supported when compare_duration is set: + // + // * security_center_properties.resource_type + string group_by = 3; + + // When compare_duration is set, the Asset's "state" property is updated to + // indicate whether the asset was added, removed, or remained present during + // the compare_duration period of time that precedes the read_time. This is + // the time between (read_time - compare_duration) and read_time. + // + // The state value is derived based on the presence of the asset at the two + // points in time. Intermediate state changes between the two times don't + // affect the result. For example, the results aren't affected if the asset is + // removed and re-created again. + // + // Possible "state" values when compare_duration is specified: + // + // * "ADDED": indicates that the asset was not present before + // compare_duration, but present at reference_time. + // * "REMOVED": indicates that the asset was present at the start of + // compare_duration, but not present at reference_time. + // * "ACTIVE": indicates that the asset was present at both the + // start and the end of the time period defined by + // compare_duration and reference_time. + // + // This field is ignored if `state` is not a field in `group_by`. + google.protobuf.Duration compare_duration = 4; + + // Time used as a reference point when filtering assets. The filter is limited + // to assets existing at the supplied time and their values are those at that + // specific time. Absence of this field will default to the API's version of + // NOW. + google.protobuf.Timestamp read_time = 5; + + // The value returned by the last `GroupAssetsResponse`; indicates + // that this is a continuation of a prior `GroupAssets` call, and that the + // system should return the next page of data. + string page_token = 7; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 8; +} + +// Response message for grouping by assets. +message GroupAssetsResponse { + // Group results. There exists an element for each existing unique + // combination of property/values. The element contains a count for the number + // of times those specific property/values appear. + repeated GroupResult group_by_results = 1; + + // Time used for executing the groupBy request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; +} + +// Request message for grouping by findings. +message GroupFindingsRequest { + // Name of the source to groupBy. Its format is + // "organizations/[organization_id]/sources/[source_id]". To groupBy across + // all sources provide a source_id of `-`. For example: + // organizations/123/sources/- + string parent = 1; + + // Expression that defines the filter to apply across findings. + // The expression is a list of one or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are not supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. Examples include: + // + // * name + // * source_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // For example, `source_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what assets fields to use for grouping (including + // `state`). The string value should follow SQL syntax: comma separated list + // of fields. For example: + // "parent,resource_name". + // + // The following fields are supported: + // + // * resource_name + // * category + // * state + // * parent + string group_by = 3; + + // Time used as a reference point when filtering findings. The filter is + // limited to findings existing at the supplied time and their values are + // those at that specific time. Absence of this field will default to the + // API's version of NOW. + google.protobuf.Timestamp read_time = 4; + + // The value returned by the last `GroupFindingsResponse`; indicates + // that this is a continuation of a prior `GroupFindings` call, and + // that the system should return the next page of data. + string page_token = 5; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 6; +} + +// Response message for group by findings. +message GroupFindingsResponse { + // Group results. There exists an element for each existing unique + // combination of property/values. The element contains a count for the number + // of times those specific property/values appear. + repeated GroupResult group_by_results = 1; + + // Time used for executing the groupBy request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; +} + +// Result containing the properties and count of a groupBy request. +message GroupResult { + // Properties matching the groupBy fields in the request. + map<string, google.protobuf.Value> properties = 1; + + // Total count of resources for the given properties. + int64 count = 2; +} + +// Request message for listing sources. +message ListSourcesRequest { + // Resource name of the parent of sources to list. Its format should be + // "organizations/[organization_id]". + string parent = 1; + + // The value returned by the last `ListSourcesResponse`; indicates + // that this is a continuation of a prior `ListSources` call, and + // that the system should return the next page of data. + string page_token = 2; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 7; +} + +// Response message for listing sources. +message ListSourcesResponse { + // Sources belonging to the requested parent. + repeated Source sources = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 2; +} + +// Request message for listing assets. +message ListAssetsRequest { + // Name of the organization assets should belong to. Its format is + // "organizations/[organization_id]". + string parent = 1; + + // Expression that defines the filter to apply across assets. + // The expression is a list of zero or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are not supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. The fields map to those + // defined in the Asset resource. Examples include: + // + // * name + // * security_center_properties.resource_name + // * resource_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // For example, `resource_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what fields and order to use for sorting. The + // string value should follow SQL syntax: comma separated list of fields. For + // example: "name,resource_properties.a_property". The default sorting order + // is ascending. To specify descending order for a field, a suffix " desc" + // should be appended to the field name. For example: "name + // desc,resource_properties.a_property". Redundant space characters in the + // syntax are insignificant. "name desc,resource_properties.a_property" and " + // name desc , resource_properties.a_property " are equivalent. + string order_by = 3; + + // Time used as a reference point when filtering assets. The filter is limited + // to assets existing at the supplied time and their values are those at that + // specific time. Absence of this field will default to the API's version of + // NOW. + google.protobuf.Timestamp read_time = 4; + + // When compare_duration is set, the ListAssetResult's "state" attribute is + // updated to indicate whether the asset was added, removed, or remained + // present during the compare_duration period of time that precedes the + // read_time. This is the time between (read_time - + // compare_duration) and read_time. + // + // The state value is derived based on the presence of the asset at the two + // points in time. Intermediate state changes between the two times don't + // affect the result. For example, the results aren't affected if the asset is + // removed and re-created again. + // + // Possible "state" values when compare_duration is specified: + // + // * "ADDED": indicates that the asset was not present before + // compare_duration, but present at read_time. + // * "REMOVED": indicates that the asset was present at the start of + // compare_duration, but not present at read_time. + // * "ACTIVE": indicates that the asset was present at both the + // start and the end of the time period defined by + // compare_duration and read_time. + // + // If compare_duration is not specified, then the only possible state is + // "UNUSED", which indicates that the asset is present at read_time. + google.protobuf.Duration compare_duration = 5; + + // Optional. + // + // A field mask to specify the ListAssetsResult fields to be listed in the + // response. + // An empty field mask will list all fields. + google.protobuf.FieldMask field_mask = 7; + + // The value returned by the last `ListAssetsResponse`; indicates + // that this is a continuation of a prior `ListAssets` call, and + // that the system should return the next page of data. + string page_token = 8; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 9; +} + +// Response message for listing assets. +message ListAssetsResponse { + // Result containing the Asset and its State. + message ListAssetsResult { + // State of the asset. + // + // When querying across two points in time this describes + // the change between the two points: ADDED, REMOVED, or ACTIVE. + // If there was no compare_duration supplied in the request the state should + // be: UNUSED + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // Request did not specify use of this field in the result. + UNUSED = 1; + + // Asset was added between the points in time. + ADDED = 2; + + // Asset was removed between the points in time. + REMOVED = 3; + + // Asset was active at both point(s) in time. + ACTIVE = 4; + } + + // Asset matching the search request. + Asset asset = 1; + + // State of the asset. + State state = 2; + } + + // Assets matching the list request. + repeated ListAssetsResult list_assets_results = 1; + + // Time used for executing the list request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; + + // The total number of assets matching the query. + int32 total_size = 4; +} + +// Request message for listing findings. +message ListFindingsRequest { + // Name of the source the findings belong to. Its format is + // "organizations/[organization_id]/sources/[source_id]". To list across all + // sources provide a source_id of `-`. For example: + // organizations/123/sources/- + string parent = 1; + + // Expression that defines the filter to apply across findings. + // The expression is a list of one or more restrictions combined via logical + // operators `AND` and `OR`. + // Parentheses are not supported, and `OR` has higher precedence than `AND`. + // + // Restrictions have the form `<field> <operator> <value>` and may have a `-` + // character in front of them to indicate negation. Examples include: + // + // * name + // * source_properties.a_property + // * security_marks.marks.marka + // + // The supported operators are: + // + // * `=` for all value types. + // * `>`, `<`, `>=`, `<=` for integer values. + // * `:`, meaning substring matching, for strings. + // + // The supported value types are: + // + // * string literals in quotes. + // * integer literals without quotes. + // * boolean literals `true` and `false` without quotes. + // + // For example, `source_properties.size = 100` is a valid filter string. + string filter = 2; + + // Expression that defines what fields and order to use for sorting. The + // string value should follow SQL syntax: comma separated list of fields. For + // example: "name,resource_properties.a_property". The default sorting order + // is ascending. To specify descending order for a field, a suffix " desc" + // should be appended to the field name. For example: "name + // desc,source_properties.a_property". Redundant space characters in the + // syntax are insignificant. "name desc,source_properties.a_property" and " + // name desc , source_properties.a_property " are equivalent. + string order_by = 3; + + // Time used as a reference point when filtering findings. The filter is + // limited to findings existing at the supplied time and their values are + // those at that specific time. Absence of this field will default to the + // API's version of NOW. + google.protobuf.Timestamp read_time = 4; + + // Optional. + // + // A field mask to specify the Finding fields to be listed in the response. + // An empty field mask will list all fields. + google.protobuf.FieldMask field_mask = 5; + + // The value returned by the last `ListFindingsResponse`; indicates + // that this is a continuation of a prior `ListFindings` call, and + // that the system should return the next page of data. + string page_token = 6; + + // The maximum number of results to return in a single response. Default is + // 10, minimum is 1, maximum is 1000. + int32 page_size = 7; +} + +// Response message for listing findings. +message ListFindingsResponse { + // Findings matching the list request. + repeated Finding findings = 1; + + // Time used for executing the list request. + google.protobuf.Timestamp read_time = 2; + + // Token to retrieve the next page of results, or empty if there are no more + // results. + string next_page_token = 3; + + // The total number of findings matching the query. + int32 total_size = 4; +} + +// Request message for updating a finding's state. +message SetFindingStateRequest { + // The relative resource name of the finding. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/sources/456/finding/789". + string name = 1; + + // The desired State of the finding. + Finding.State state = 2; + + // The time at which the updated state takes effect. + google.protobuf.Timestamp start_time = 3; +} + +// Request message for running asset discovery for an organization. +message RunAssetDiscoveryRequest { + // Name of the organization to run asset discovery for. Its format is + // "organizations/[organization_id]". + string parent = 1; +} + +// Request message for updating or creating a finding. +message UpdateFindingRequest { + // The finding resource to update or create if it does not already exist. + // parent, security_marks, and update_time will be ignored. + // + // In the case of creation, the finding id portion of the name must + // alphanumeric and less than or equal to 32 characters and greater than 0 + // characters in length. + Finding finding = 1; + + // The FieldMask to use when updating the finding resource. This field should + // not be specified when creating a finding. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for updating an organization's settings. +message UpdateOrganizationSettingsRequest { + // The organization settings resource to update. + OrganizationSettings organization_settings = 1; + + // The FieldMask to use when updating the settings resource. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for updating a source. +message UpdateSourceRequest { + // The source resource to update. + Source source = 1; + + // The FieldMask to use when updating the source resource. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for updating a SecurityMarks resource. +message UpdateSecurityMarksRequest { + // The security marks resource to update. + SecurityMarks security_marks = 1; + + // The FieldMask to use when updating the security marks resource. + google.protobuf.FieldMask update_mask = 2; + + // The time at which the updated SecurityMarks take effect. + google.protobuf.Timestamp start_time = 3; +} diff --git a/google/cloud/securitycenter/v1beta1/source.proto b/google/cloud/securitycenter/v1beta1/source.proto new file mode 100644 index 000000000..cc1fae6ea --- /dev/null +++ b/google/cloud/securitycenter/v1beta1/source.proto @@ -0,0 +1,53 @@ +// Copyright 2018 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.securitycenter.v1beta1; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1;securitycenter"; +option java_multiple_files = true; +option java_package = "com.google.cloud.securitycenter.v1beta1"; + +// Cloud Security Command Center's (Cloud SCC) finding source. A finding source +// is an entity or a mechanism that can produce a finding. A source is like a +// container of findings that come from the same scanner, logger, monitor, etc. +message Source { + // The relative resource name of this source. See: + // https://cloud.google.com/apis/design/resource_names#relative_resource_name + // Example: + // "organizations/123/sources/456" + string name = 1; + + // The source's display name. + // A source's display name must be unique amongst its siblings, for example, + // two sources with the same parent can't share the same display name. + // The display name must start and end with a letter or digit, may contain + // letters, digits, spaces, hyphens, and underscores, and can be no longer + // than 32 characters. This is captured by the regular expression: + // [\p{L}\p{N}]({\p{L}\p{N}_- ]{0,30}[\p{L}\p{N}])?. + string display_name = 2; + + // The description of the source (max of 1024 characters). + // Example: + // "Cloud Security Scanner is a web security scanner for common + // vulnerabilities in App Engine applications. It can automatically + // scan and detect four common vulnerabilities, including cross-site-scripting + // (XSS), Flash injection, mixed content (HTTP in HTTPS), and + // outdated/insecure libraries." + string description = 3; +} diff --git a/google/cloud/speech/BUILD.bazel b/google/cloud/speech/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/speech/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/speech/README.md b/google/cloud/speech/README.md new file mode 100644 index 000000000..c45f0f21a --- /dev/null +++ b/google/cloud/speech/README.md @@ -0,0 +1,3 @@ +# Introduction + +Google Cloud Speech API provides speech recognition as a service. diff --git a/google/cloud/speech/artman_speech_v1.yaml b/google/cloud/speech/artman_speech_v1.yaml new file mode 100644 index 000000000..c781940ea --- /dev/null +++ b/google/cloud/speech/artman_speech_v1.yaml @@ -0,0 +1,34 @@ +common: + api_name: speech + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: speech_v1.yaml + gapic_yaml: v1/speech_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/speech/artman_speech_v1p1beta1.yaml b/google/cloud/speech/artman_speech_v1p1beta1.yaml new file mode 100644 index 000000000..fa2685425 --- /dev/null +++ b/google/cloud/speech/artman_speech_v1p1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: speech + api_version: v1p1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1p1beta1 + service_yaml: speech_v1p1beta1.yaml + gapic_yaml: v1p1beta1/speech_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/speech/speech_v1.yaml b/google/cloud/speech/speech_v1.yaml new file mode 100644 index 000000000..4cb4b7b2c --- /dev/null +++ b/google/cloud/speech/speech_v1.yaml @@ -0,0 +1,65 @@ +type: google.api.Service +config_version: 3 +name: speech.googleapis.com +title: Cloud Speech API + +apis: +- name: google.cloud.speech.v1.Speech + +types: +- name: google.cloud.speech.v1.LongRunningRecognizeMetadata +- name: google.cloud.speech.v1.LongRunningRecognizeResponse + +documentation: + summary: Converts audio to text by applying powerful neural network models. + overview: |- + # Introduction + + Google Cloud Speech API provides speech recognition as a service. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 200.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 200.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 200.0 + - selector: google.cloud.speech.v1.Speech.Recognize + deadline: 200.0 + - selector: google.cloud.speech.v1.Speech.LongRunningRecognize + deadline: 200.0 + - selector: google.cloud.speech.v1.Speech.StreamingRecognize + deadline: 200.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: /v1/operations + additional_bindings: + - get: /v1beta1/operations + + - get: /v1p1beta1/operations + + - get: '/v1p1beta1/{name=projects/*/locations/*}/operations' + + - get: '/v1/{name=projects/*/locations/*}/operations' + + - selector: google.longrunning.Operations.GetOperation + get: '/v1/operations/{name=**}' + additional_bindings: + - get: '/v1beta1/operations/{name=**}' + + - get: '/v1p1beta1/operations/{name=**}' + + - get: '/v1/{name=projects/*/locations/*/operations/*}' + + - get: '/v1p1beta1/{name=projects/*/locations/*/operations/*}' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/speech/speech_v1p1beta1.yaml b/google/cloud/speech/speech_v1p1beta1.yaml new file mode 100644 index 000000000..8fefdf6ff --- /dev/null +++ b/google/cloud/speech/speech_v1p1beta1.yaml @@ -0,0 +1,50 @@ +type: google.api.Service +config_version: 3 +name: speech.googleapis.com +title: Cloud Speech API + +apis: +- name: google.cloud.speech.v1p1beta1.Speech + +documentation: + summary: Converts audio to text by applying powerful neural network models. + overview: |- + # Introduction + + Google Cloud Speech API provides speech recognition as a service. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 200.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 200.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 200.0 + - selector: google.cloud.speech.v1p1beta1.Speech.Recognize + deadline: 200.0 + - selector: google.cloud.speech.v1p1beta1.Speech.LongRunningRecognize + deadline: 200.0 + - selector: google.cloud.speech.v1p1beta1.Speech.StreamingRecognize + deadline: 905.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: /v1/operations + additional_bindings: + - get: /v1beta1/operations + - selector: google.longrunning.Operations.GetOperation + get: '/v1/operations/{name=*}' + additional_bindings: + - get: '/v1beta1/operations/{name=*}' + + - get: '/v1p1beta1/operations/{name=*}' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/speech/v1/BUILD.bazel b/google/cloud/speech/v1/BUILD.bazel new file mode 100644 index 000000000..b712d998f --- /dev/null +++ b/google/cloud/speech/v1/BUILD.bazel @@ -0,0 +1,150 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "speech_proto", + srcs = [ + "cloud_speech.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:any_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "speech_proto_with_info", + deps = [":speech_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "speech_java_proto", + deps = [":speech_proto"], +) + +java_grpc_library( + name = "speech_java_grpc", + srcs = [":speech_proto"], + deps = [":speech_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "speech_resource_name_java_proto", + gapic_yaml = "speech_gapic.yaml", + deps = [":speech_proto"], +) + +java_gapic_library( + name = "speech_java_gapic", + src = ":speech_proto_with_info", + gapic_yaml = "speech_gapic.yaml", + service_yaml = "//google/cloud/speech:speech_v1.yaml", + test_deps = [":speech_java_grpc"], + deps = [ + ":speech_java_proto", + ":speech_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":speech_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.speech.v1.SpeechClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-speech-v1-java", + client_deps = [":speech_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":speech_java_gapic_test"], + grpc_deps = [":speech_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":speech_java_proto", + ":speech_proto", + ":speech_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "speech_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/speech/v1", + protos = [":speech_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "speech_go_gapic", + src = ":speech_proto_with_info", + gapic_yaml = "speech_gapic.yaml", + importpath = "cloud.google.com/go/speech/apiv1", + service_yaml = "//google/cloud/speech:speech_v1.yaml", + deps = [ + ":speech_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "speech_go_gapic_test", + srcs = [":speech_go_gapic_srcjar_test"], + embed = [":speech_go_gapic"], + importpath = "cloud.google.com/go/speech/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-speech-v1-go", + deps = [ + ":speech_go_gapic", + ":speech_go_gapic_srcjar-smoke-test.srcjar", + ":speech_go_gapic_srcjar-test.srcjar", + ":speech_go_proto", + ], +) diff --git a/google/cloud/speech/v1/cloud_speech.proto b/google/cloud/speech/v1/cloud_speech.proto new file mode 100644 index 000000000..11bd981b8 --- /dev/null +++ b/google/cloud/speech/v1/cloud_speech.proto @@ -0,0 +1,567 @@ +// Copyright 2018 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.speech.v1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/speech/v1;speech"; +option java_multiple_files = true; +option java_outer_classname = "SpeechProto"; +option java_package = "com.google.cloud.speech.v1"; + +// Service that implements Google Cloud Speech API. +service Speech { + // Performs synchronous speech recognition: receive results after all audio + // has been sent and processed. + rpc Recognize(RecognizeRequest) returns (RecognizeResponse) { + option (google.api.http) = { + post: "/v1/speech:recognize" + body: "*" + }; + } + + // Performs asynchronous speech recognition: receive results via the + // google.longrunning.Operations interface. Returns either an + // `Operation.error` or an `Operation.response` which contains + // a `LongRunningRecognizeResponse` message. + rpc LongRunningRecognize(LongRunningRecognizeRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/speech:longrunningrecognize" + body: "*" + }; + } + + // Performs bidirectional streaming speech recognition: receive results while + // sending audio. This method is only available via the gRPC API (not REST). + rpc StreamingRecognize(stream StreamingRecognizeRequest) + returns (stream StreamingRecognizeResponse) {} +} + +// The top-level message sent by the client for the `Recognize` method. +message RecognizeRequest { + // *Required* Provides information to the recognizer that specifies how to + // process the request. + RecognitionConfig config = 1; + + // *Required* The audio data to be recognized. + RecognitionAudio audio = 2; +} + +// The top-level message sent by the client for the `LongRunningRecognize` +// method. +message LongRunningRecognizeRequest { + // *Required* Provides information to the recognizer that specifies how to + // process the request. + RecognitionConfig config = 1; + + // *Required* The audio data to be recognized. + RecognitionAudio audio = 2; +} + +// The top-level message sent by the client for the `StreamingRecognize` method. +// Multiple `StreamingRecognizeRequest` messages are sent. The first message +// must contain a `streaming_config` message and must not contain `audio` data. +// All subsequent messages must contain `audio` data and must not contain a +// `streaming_config` message. +message StreamingRecognizeRequest { + // The streaming request, which is either a streaming config or audio content. + oneof streaming_request { + // Provides information to the recognizer that specifies how to process the + // request. The first `StreamingRecognizeRequest` message must contain a + // `streaming_config` message. + StreamingRecognitionConfig streaming_config = 1; + + // The audio data to be recognized. Sequential chunks of audio data are sent + // in sequential `StreamingRecognizeRequest` messages. The first + // `StreamingRecognizeRequest` message must not contain `audio_content` data + // and all subsequent `StreamingRecognizeRequest` messages must contain + // `audio_content` data. The audio bytes must be encoded as specified in + // `RecognitionConfig`. Note: as with all bytes fields, protobuffers use a + // pure binary representation (not base64). See + // [content limits](/speech-to-text/quotas#content). + bytes audio_content = 2; + } +} + +// Provides information to the recognizer that specifies how to process the +// request. +message StreamingRecognitionConfig { + // *Required* Provides information to the recognizer that specifies how to + // process the request. + RecognitionConfig config = 1; + + // *Optional* If `false` or omitted, the recognizer will perform continuous + // recognition (continuing to wait for and process audio even if the user + // pauses speaking) until the client closes the input stream (gRPC API) or + // until the maximum time limit has been reached. May return multiple + // `StreamingRecognitionResult`s with the `is_final` flag set to `true`. + // + // If `true`, the recognizer will detect a single spoken utterance. When it + // detects that the user has paused or stopped speaking, it will return an + // `END_OF_SINGLE_UTTERANCE` event and cease recognition. It will return no + // more than one `StreamingRecognitionResult` with the `is_final` flag set to + // `true`. + bool single_utterance = 2; + + // *Optional* If `true`, interim results (tentative hypotheses) may be + // returned as they become available (these interim results are indicated with + // the `is_final=false` flag). + // If `false` or omitted, only `is_final=true` result(s) are returned. + bool interim_results = 3; +} + +// Provides information to the recognizer that specifies how to process the +// request. +message RecognitionConfig { + // The encoding of the audio data sent in the request. + // + // All encodings support only 1 channel (mono) audio. + // + // For best results, the audio source should be captured and transmitted using + // a lossless encoding (`FLAC` or `LINEAR16`). The accuracy of the speech + // recognition can be reduced if lossy codecs are used to capture or transmit + // audio, particularly if background noise is present. Lossy codecs include + // `MULAW`, `AMR`, `AMR_WB`, `OGG_OPUS`, and `SPEEX_WITH_HEADER_BYTE`. + // + // The `FLAC` and `WAV` audio file formats include a header that describes the + // included audio content. You can request recognition for `WAV` files that + // contain either `LINEAR16` or `MULAW` encoded audio. + // If you send `FLAC` or `WAV` audio file format in + // your request, you do not need to specify an `AudioEncoding`; the audio + // encoding format is determined from the file header. If you specify + // an `AudioEncoding` when you send send `FLAC` or `WAV` audio, the + // encoding configuration must match the encoding described in the audio + // header; otherwise the request returns an + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT] error + // code. + enum AudioEncoding { + // Not specified. + ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + LINEAR16 = 1; + + // `FLAC` (Free Lossless Audio + // Codec) is the recommended encoding because it is + // lossless--therefore recognition is not compromised--and + // requires only about half the bandwidth of `LINEAR16`. `FLAC` stream + // encoding supports 16-bit and 24-bit samples, however, not all fields in + // `STREAMINFO` are supported. + FLAC = 2; + + // 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law. + MULAW = 3; + + // Adaptive Multi-Rate Narrowband codec. `sample_rate_hertz` must be 8000. + AMR = 4; + + // Adaptive Multi-Rate Wideband codec. `sample_rate_hertz` must be 16000. + AMR_WB = 5; + + // Opus encoded audio frames in Ogg container + // ([OggOpus](https://wiki.xiph.org/OggOpus)). + // `sample_rate_hertz` must be one of 8000, 12000, 16000, 24000, or 48000. + OGG_OPUS = 6; + + // Although the use of lossy encodings is not recommended, if a very low + // bitrate encoding is required, `OGG_OPUS` is highly preferred over + // Speex encoding. The [Speex](https://speex.org/) encoding supported by + // Cloud Speech API has a header byte in each block, as in MIME type + // `audio/x-speex-with-header-byte`. + // It is a variant of the RTP Speex encoding defined in + // [RFC 5574](https://tools.ietf.org/html/rfc5574). + // The stream is a sequence of blocks, one block per RTP packet. Each block + // starts with a byte containing the length of the block, in bytes, followed + // by one or more frames of Speex data, padded to an integral number of + // bytes (octets) as specified in RFC 5574. In other words, each RTP header + // is replaced with a single byte containing the block length. Only Speex + // wideband is supported. `sample_rate_hertz` must be 16000. + SPEEX_WITH_HEADER_BYTE = 7; + } + + // Encoding of audio data sent in all `RecognitionAudio` messages. + // This field is optional for `FLAC` and `WAV` audio files and required + // for all other audio formats. For details, see + // [AudioEncoding][google.cloud.speech.v1.RecognitionConfig.AudioEncoding]. + AudioEncoding encoding = 1; + + // Sample rate in Hertz of the audio data sent in all + // `RecognitionAudio` messages. Valid values are: 8000-48000. + // 16000 is optimal. For best results, set the sampling rate of the audio + // source to 16000 Hz. If that's not possible, use the native sample rate of + // the audio source (instead of re-sampling). + // This field is optional for `FLAC` and `WAV` audio files and required + // for all other audio formats. For details, see + // [AudioEncoding][google.cloud.speech.v1.RecognitionConfig.AudioEncoding]. + int32 sample_rate_hertz = 2; + + // *Optional* The number of channels in the input audio data. + // ONLY set this for MULTI-CHANNEL recognition. + // Valid values for LINEAR16 and FLAC are `1`-`8`. + // Valid values for OGG_OPUS are '1'-'254'. + // Valid value for MULAW, AMR, AMR_WB and SPEEX_WITH_HEADER_BYTE is only `1`. + // If `0` or omitted, defaults to one channel (mono). + // Note: We only recognize the first channel by default. + // To perform independent recognition on each channel set + // `enable_separate_recognition_per_channel` to 'true'. + int32 audio_channel_count = 7; + + // This needs to be set to `true` explicitly and `audio_channel_count` > 1 + // to get each channel recognized separately. The recognition result will + // contain a `channel_tag` field to state which channel that result belongs + // to. If this is not true, we will only recognize the first channel. The + // request is billed cumulatively for all channels recognized: + // `audio_channel_count` multiplied by the length of the audio. + bool enable_separate_recognition_per_channel = 12; + + // *Required* The language of the supplied audio as a + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. + // Example: "en-US". + // See [Language Support](/speech-to-text/docs/languages) + // for a list of the currently supported language codes. + string language_code = 3; + + // *Optional* Maximum number of recognition hypotheses to be returned. + // Specifically, the maximum number of `SpeechRecognitionAlternative` messages + // within each `SpeechRecognitionResult`. + // The server may return fewer than `max_alternatives`. + // Valid values are `0`-`30`. A value of `0` or `1` will return a maximum of + // one. If omitted, will return a maximum of one. + int32 max_alternatives = 4; + + // *Optional* If set to `true`, the server will attempt to filter out + // profanities, replacing all but the initial character in each filtered word + // with asterisks, e.g. "f***". If set to `false` or omitted, profanities + // won't be filtered out. + bool profanity_filter = 5; + + // *Optional* array of [SpeechContext][google.cloud.speech.v1.SpeechContext]. + // A means to provide context to assist the speech recognition. For more + // information, see [Phrase Hints](/speech-to-text/docs/basics#phrase-hints). + repeated SpeechContext speech_contexts = 6; + + // *Optional* If `true`, the top result includes a list of words and + // the start and end time offsets (timestamps) for those words. If + // `false`, no word-level time offset information is returned. The default is + // `false`. + bool enable_word_time_offsets = 8; + + // *Optional* If 'true', adds punctuation to recognition result hypotheses. + // This feature is only available in select languages. Setting this for + // requests in other languages has no effect at all. + // The default 'false' value does not add punctuation to result hypotheses. + // Note: This is currently offered as an experimental service, complimentary + // to all users. In the future this may be exclusively available as a + // premium feature. + bool enable_automatic_punctuation = 11; + + // *Optional* Which model to select for the given request. Select the model + // best suited to your domain to get best results. If a model is not + // explicitly specified, then we auto-select a model based on the parameters + // in the RecognitionConfig. + // <table> + // <tr> + // <td><b>Model</b></td> + // <td><b>Description</b></td> + // </tr> + // <tr> + // <td><code>command_and_search</code></td> + // <td>Best for short queries such as voice commands or voice search.</td> + // </tr> + // <tr> + // <td><code>phone_call</code></td> + // <td>Best for audio that originated from a phone call (typically + // recorded at an 8khz sampling rate).</td> + // </tr> + // <tr> + // <td><code>video</code></td> + // <td>Best for audio that originated from from video or includes multiple + // speakers. Ideally the audio is recorded at a 16khz or greater + // sampling rate. This is a premium model that costs more than the + // standard rate.</td> + // </tr> + // <tr> + // <td><code>default</code></td> + // <td>Best for audio that is not one of the specific audio models. + // For example, long-form audio. Ideally the audio is high-fidelity, + // recorded at a 16khz or greater sampling rate.</td> + // </tr> + // </table> + string model = 13; + + // *Optional* Set to true to use an enhanced model for speech recognition. + // If `use_enhanced` is set to true and the `model` field is not set, then + // an appropriate enhanced model is chosen if: + // 1. project is eligible for requesting enhanced models + // 2. an enhanced model exists for the audio + // + // If `use_enhanced` is true and an enhanced version of the specified model + // does not exist, then the speech is recognized using the standard version + // of the specified model. + // + // Enhanced speech models require that you opt-in to data logging using + // instructions in the + // [documentation](/speech-to-text/docs/enable-data-logging). If you set + // `use_enhanced` to true and you have not enabled audio logging, then you + // will receive an error. + bool use_enhanced = 14; +} + +// Provides "hints" to the speech recognizer to favor specific words and phrases +// in the results. +message SpeechContext { + // *Optional* A list of strings containing words and phrases "hints" so that + // the speech recognition is more likely to recognize them. This can be used + // to improve the accuracy for specific words and phrases, for example, if + // specific commands are typically spoken by the user. This can also be used + // to add additional words to the vocabulary of the recognizer. See + // [usage limits](/speech-to-text/quotas#content). + repeated string phrases = 1; +} + +// Contains audio data in the encoding specified in the `RecognitionConfig`. +// Either `content` or `uri` must be supplied. Supplying both or neither +// returns [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]. +// See [content limits](/speech-to-text/quotas#content). +message RecognitionAudio { + // The audio source, which is either inline content or a Google Cloud + // Storage uri. + oneof audio_source { + // The audio data bytes encoded as specified in + // `RecognitionConfig`. Note: as with all bytes fields, protobuffers use a + // pure binary representation, whereas JSON representations use base64. + bytes content = 1; + + // URI that points to a file that contains audio data bytes as specified in + // `RecognitionConfig`. The file must not be compressed (for example, gzip). + // Currently, only Google Cloud Storage URIs are + // supported, which must be specified in the following format: + // `gs://bucket_name/object_name` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). + // For more information, see [Request + // URIs](https://cloud.google.com/storage/docs/reference-uris). + string uri = 2; + } +} + +// The only message returned to the client by the `Recognize` method. It +// contains the result as zero or more sequential `SpeechRecognitionResult` +// messages. +message RecognizeResponse { + // Output only. Sequential list of transcription results corresponding to + // sequential portions of audio. + repeated SpeechRecognitionResult results = 2; +} + +// The only message returned to the client by the `LongRunningRecognize` method. +// It contains the result as zero or more sequential `SpeechRecognitionResult` +// messages. It is included in the `result.response` field of the `Operation` +// returned by the `GetOperation` call of the `google::longrunning::Operations` +// service. +message LongRunningRecognizeResponse { + // Output only. Sequential list of transcription results corresponding to + // sequential portions of audio. + repeated SpeechRecognitionResult results = 2; +} + +// Describes the progress of a long-running `LongRunningRecognize` call. It is +// included in the `metadata` field of the `Operation` returned by the +// `GetOperation` call of the `google::longrunning::Operations` service. +message LongRunningRecognizeMetadata { + // Approximate percentage of audio processed thus far. Guaranteed to be 100 + // when the audio is fully processed and the results are available. + int32 progress_percent = 1; + + // Time when the request was received. + google.protobuf.Timestamp start_time = 2; + + // Time of the most recent processing update. + google.protobuf.Timestamp last_update_time = 3; +} + +// `StreamingRecognizeResponse` is the only message returned to the client by +// `StreamingRecognize`. A series of zero or more `StreamingRecognizeResponse` +// messages are streamed back to the client. If there is no recognizable +// audio, and `single_utterance` is set to false, then no messages are streamed +// back to the client. +// +// Here's an example of a series of ten `StreamingRecognizeResponse`s that might +// be returned while processing audio: +// +// 1. results { alternatives { transcript: "tube" } stability: 0.01 } +// +// 2. results { alternatives { transcript: "to be a" } stability: 0.01 } +// +// 3. results { alternatives { transcript: "to be" } stability: 0.9 } +// results { alternatives { transcript: " or not to be" } stability: 0.01 } +// +// 4. results { alternatives { transcript: "to be or not to be" +// confidence: 0.92 } +// alternatives { transcript: "to bee or not to bee" } +// is_final: true } +// +// 5. results { alternatives { transcript: " that's" } stability: 0.01 } +// +// 6. results { alternatives { transcript: " that is" } stability: 0.9 } +// results { alternatives { transcript: " the question" } stability: 0.01 } +// +// 7. results { alternatives { transcript: " that is the question" +// confidence: 0.98 } +// alternatives { transcript: " that was the question" } +// is_final: true } +// +// Notes: +// +// - Only two of the above responses #4 and #7 contain final results; they are +// indicated by `is_final: true`. Concatenating these together generates the +// full transcript: "to be or not to be that is the question". +// +// - The others contain interim `results`. #3 and #6 contain two interim +// `results`: the first portion has a high stability and is less likely to +// change; the second portion has a low stability and is very likely to +// change. A UI designer might choose to show only high stability `results`. +// +// - The specific `stability` and `confidence` values shown above are only for +// illustrative purposes. Actual values may vary. +// +// - In each response, only one of these fields will be set: +// `error`, +// `speech_event_type`, or +// one or more (repeated) `results`. +message StreamingRecognizeResponse { + // Indicates the type of speech event. + enum SpeechEventType { + // No speech event specified. + SPEECH_EVENT_UNSPECIFIED = 0; + + // This event indicates that the server has detected the end of the user's + // speech utterance and expects no additional speech. Therefore, the server + // will not process additional audio (although it may subsequently return + // additional results). The client should stop sending additional audio + // data, half-close the gRPC connection, and wait for any additional results + // until the server closes the gRPC connection. This event is only sent if + // `single_utterance` was set to `true`, and is not used otherwise. + END_OF_SINGLE_UTTERANCE = 1; + } + + // Output only. If set, returns a [google.rpc.Status][google.rpc.Status] + // message that specifies the error for the operation. + google.rpc.Status error = 1; + + // Output only. This repeated list contains zero or more results that + // correspond to consecutive portions of the audio currently being processed. + // It contains zero or one `is_final=true` result (the newly settled portion), + // followed by zero or more `is_final=false` results (the interim results). + repeated StreamingRecognitionResult results = 2; + + // Output only. Indicates the type of speech event. + SpeechEventType speech_event_type = 4; +} + +// A streaming speech recognition result corresponding to a portion of the audio +// that is currently being processed. +message StreamingRecognitionResult { + // Output only. May contain one or more recognition hypotheses (up to the + // maximum specified in `max_alternatives`). + // These alternatives are ordered in terms of accuracy, with the top (first) + // alternative being the most probable, as ranked by the recognizer. + repeated SpeechRecognitionAlternative alternatives = 1; + + // Output only. If `false`, this `StreamingRecognitionResult` represents an + // interim result that may change. If `true`, this is the final time the + // speech service will return this particular `StreamingRecognitionResult`, + // the recognizer will not return any further hypotheses for this portion of + // the transcript and corresponding audio. + bool is_final = 2; + + // Output only. An estimate of the likelihood that the recognizer will not + // change its guess about this interim result. Values range from 0.0 + // (completely unstable) to 1.0 (completely stable). + // This field is only provided for interim results (`is_final=false`). + // The default of 0.0 is a sentinel value indicating `stability` was not set. + float stability = 3; + + // For multi-channel audio, this is the channel number corresponding to the + // recognized result for the audio from that channel. + // For audio_channel_count = N, its output values can range from '1' to 'N'. + int32 channel_tag = 5; +} + +// A speech recognition result corresponding to a portion of the audio. +message SpeechRecognitionResult { + // Output only. May contain one or more recognition hypotheses (up to the + // maximum specified in `max_alternatives`). + // These alternatives are ordered in terms of accuracy, with the top (first) + // alternative being the most probable, as ranked by the recognizer. + repeated SpeechRecognitionAlternative alternatives = 1; + + // For multi-channel audio, this is the channel number corresponding to the + // recognized result for the audio from that channel. + // For audio_channel_count = N, its output values can range from '1' to 'N'. + int32 channel_tag = 2; +} + +// Alternative hypotheses (a.k.a. n-best list). +message SpeechRecognitionAlternative { + // Output only. Transcript text representing the words that the user spoke. + string transcript = 1; + + // Output only. The confidence estimate between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. This field is set only for the top alternative of a non-streaming + // result or, of a streaming result where `is_final=true`. + // This field is not guaranteed to be accurate and users should not rely on it + // to be always provided. + // The default of 0.0 is a sentinel value indicating `confidence` was not set. + float confidence = 2; + + // Output only. A list of word-specific information for each recognized word. + // Note: When `enable_speaker_diarization` is true, you will see all the words + // from the beginning of the audio. + repeated WordInfo words = 3; +} + +// Word-specific information for recognized words. +message WordInfo { + // Output only. Time offset relative to the beginning of the audio, + // and corresponding to the start of the spoken word. + // This field is only set if `enable_word_time_offsets=true` and only + // in the top hypothesis. + // This is an experimental feature and the accuracy of the time offset can + // vary. + google.protobuf.Duration start_time = 1; + + // Output only. Time offset relative to the beginning of the audio, + // and corresponding to the end of the spoken word. + // This field is only set if `enable_word_time_offsets=true` and only + // in the top hypothesis. + // This is an experimental feature and the accuracy of the time offset can + // vary. + google.protobuf.Duration end_time = 2; + + // Output only. The word corresponding to this set of information. + string word = 3; +} diff --git a/google/cloud/speech/v1/speech_gapic.yaml b/google/cloud/speech/v1/speech_gapic.yaml new file mode 100644 index 000000000..1e2d456c0 --- /dev/null +++ b/google/cloud/speech/v1/speech_gapic.yaml @@ -0,0 +1,92 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.speech.v1 + python: + package_name: google.cloud.speech_v1.gapic + go: + package_name: cloud.google.com/go/speech/apiv1 + release_level: GA + csharp: + package_name: Google.Cloud.Speech.V1 + release_level: GA + ruby: + package_name: Google::Cloud::Speech::V1 + php: + package_name: Google\Cloud\Speech\V1 + nodejs: + package_name: speech.v1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.speech.v1.Speech + smoke_test: + method: Recognize + init_fields: + - config.language_code="en-US" + - config.sample_rate_hertz=44100 + - config.encoding=FLAC + - audio.uri="gs://gapic-toolkit/hello.flac" + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 1000000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 1000000 + total_timeout_millis: 5000000 + methods: + - name: Recognize + flattening: + groups: + - parameters: + - config + - audio + required_fields: + - config + - audio + sample_code_init_fields: + - config.encoding=FLAC + - config.sample_rate_hertz=44100 + - config.language_code="en-US" + - audio.uri=gs://bucket_name/file_name.flac + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 1000000 + - name: LongRunningRecognize + flattening: + groups: + - parameters: + - config + - audio + required_fields: + - config + - audio + sample_code_init_fields: + - config.encoding=FLAC + - config.sample_rate_hertz=44100 + - config.language_code="en-US" + - audio.uri=gs://bucket_name/file_name.flac + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + long_running: + return_type: google.cloud.speech.v1.LongRunningRecognizeResponse + metadata_type: google.cloud.speech.v1.LongRunningRecognizeMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + - name: StreamingRecognize + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 1000000 diff --git a/google/cloud/speech/v1p1beta1/BUILD.bazel b/google/cloud/speech/v1p1beta1/BUILD.bazel new file mode 100644 index 000000000..c11ea8b70 --- /dev/null +++ b/google/cloud/speech/v1p1beta1/BUILD.bazel @@ -0,0 +1,150 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "speech_proto", + srcs = [ + "cloud_speech.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:any_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "speech_proto_with_info", + deps = [":speech_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "speech_java_proto", + deps = [":speech_proto"], +) + +java_grpc_library( + name = "speech_java_grpc", + srcs = [":speech_proto"], + deps = [":speech_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "speech_resource_name_java_proto", + gapic_yaml = "speech_gapic.yaml", + deps = [":speech_proto"], +) + +java_gapic_library( + name = "speech_java_gapic", + src = ":speech_proto_with_info", + gapic_yaml = "speech_gapic.yaml", + service_yaml = "//google/cloud/speech:speech_v1p1beta1.yaml", + test_deps = [":speech_java_grpc"], + deps = [ + ":speech_java_proto", + ":speech_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":speech_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.speech.v1p1beta1.SpeechClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-speech-v1p1beta1-java", + client_deps = [":speech_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":speech_java_gapic_test"], + grpc_deps = [":speech_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":speech_java_proto", + ":speech_proto", + ":speech_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "speech_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/speech/v1p1beta1", + protos = [":speech_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "speech_go_gapic", + src = ":speech_proto_with_info", + gapic_yaml = "speech_gapic.yaml", + importpath = "cloud.google.com/go/speech/apiv1p1beta1", + service_yaml = "//google/cloud/speech:speech_v1p1beta1.yaml", + deps = [ + ":speech_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "speech_go_gapic_test", + srcs = [":speech_go_gapic_srcjar_test"], + embed = [":speech_go_gapic"], + importpath = "cloud.google.com/go/speech/apiv1p1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-speech-v1p1beta1-go", + deps = [ + ":speech_go_gapic", + ":speech_go_gapic_srcjar-smoke-test.srcjar", + ":speech_go_gapic_srcjar-test.srcjar", + ":speech_go_proto", + ], +) diff --git a/google/cloud/speech/v1p1beta1/cloud_speech.proto b/google/cloud/speech/v1p1beta1/cloud_speech.proto new file mode 100644 index 000000000..d603d97dd --- /dev/null +++ b/google/cloud/speech/v1p1beta1/cloud_speech.proto @@ -0,0 +1,770 @@ +// Copyright 2018 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.speech.v1p1beta1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/speech/v1p1beta1;speech"; +option java_multiple_files = true; +option java_outer_classname = "SpeechProto"; +option java_package = "com.google.cloud.speech.v1p1beta1"; + +// Service that implements Google Cloud Speech API. +service Speech { + // Performs synchronous speech recognition: receive results after all audio + // has been sent and processed. + rpc Recognize(RecognizeRequest) returns (RecognizeResponse) { + option (google.api.http) = { + post: "/v1p1beta1/speech:recognize" + body: "*" + }; + } + + // Performs asynchronous speech recognition: receive results via the + // google.longrunning.Operations interface. Returns either an + // `Operation.error` or an `Operation.response` which contains + // a `LongRunningRecognizeResponse` message. + rpc LongRunningRecognize(LongRunningRecognizeRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p1beta1/speech:longrunningrecognize" + body: "*" + }; + } + + // Performs bidirectional streaming speech recognition: receive results while + // sending audio. This method is only available via the gRPC API (not REST). + rpc StreamingRecognize(stream StreamingRecognizeRequest) + returns (stream StreamingRecognizeResponse) {} +} + +// The top-level message sent by the client for the `Recognize` method. +message RecognizeRequest { + // *Required* Provides information to the recognizer that specifies how to + // process the request. + RecognitionConfig config = 1; + + // *Required* The audio data to be recognized. + RecognitionAudio audio = 2; +} + +// The top-level message sent by the client for the `LongRunningRecognize` +// method. +message LongRunningRecognizeRequest { + // *Required* Provides information to the recognizer that specifies how to + // process the request. + RecognitionConfig config = 1; + + // *Required* The audio data to be recognized. + RecognitionAudio audio = 2; +} + +// The top-level message sent by the client for the `StreamingRecognize` method. +// Multiple `StreamingRecognizeRequest` messages are sent. The first message +// must contain a `streaming_config` message and must not contain `audio` data. +// All subsequent messages must contain `audio` data and must not contain a +// `streaming_config` message. +message StreamingRecognizeRequest { + // The streaming request, which is either a streaming config or audio content. + oneof streaming_request { + // Provides information to the recognizer that specifies how to process the + // request. The first `StreamingRecognizeRequest` message must contain a + // `streaming_config` message. + StreamingRecognitionConfig streaming_config = 1; + + // The audio data to be recognized. Sequential chunks of audio data are sent + // in sequential `StreamingRecognizeRequest` messages. The first + // `StreamingRecognizeRequest` message must not contain `audio_content` data + // and all subsequent `StreamingRecognizeRequest` messages must contain + // `audio_content` data. The audio bytes must be encoded as specified in + // `RecognitionConfig`. Note: as with all bytes fields, protobuffers use a + // pure binary representation (not base64). See + // [content limits](/speech-to-text/quotas#content). + bytes audio_content = 2; + } +} + +// Provides information to the recognizer that specifies how to process the +// request. +message StreamingRecognitionConfig { + // *Required* Provides information to the recognizer that specifies how to + // process the request. + RecognitionConfig config = 1; + + // *Optional* If `false` or omitted, the recognizer will perform continuous + // recognition (continuing to wait for and process audio even if the user + // pauses speaking) until the client closes the input stream (gRPC API) or + // until the maximum time limit has been reached. May return multiple + // `StreamingRecognitionResult`s with the `is_final` flag set to `true`. + // + // If `true`, the recognizer will detect a single spoken utterance. When it + // detects that the user has paused or stopped speaking, it will return an + // `END_OF_SINGLE_UTTERANCE` event and cease recognition. It will return no + // more than one `StreamingRecognitionResult` with the `is_final` flag set to + // `true`. + bool single_utterance = 2; + + // *Optional* If `true`, interim results (tentative hypotheses) may be + // returned as they become available (these interim results are indicated with + // the `is_final=false` flag). + // If `false` or omitted, only `is_final=true` result(s) are returned. + bool interim_results = 3; +} + +// Provides information to the recognizer that specifies how to process the +// request. +message RecognitionConfig { + // The encoding of the audio data sent in the request. + // + // All encodings support only 1 channel (mono) audio. + // + // For best results, the audio source should be captured and transmitted using + // a lossless encoding (`FLAC` or `LINEAR16`). The accuracy of the speech + // recognition can be reduced if lossy codecs are used to capture or transmit + // audio, particularly if background noise is present. Lossy codecs include + // `MULAW`, `AMR`, `AMR_WB`, `OGG_OPUS`, and `SPEEX_WITH_HEADER_BYTE`. + // + // The `FLAC` and `WAV` audio file formats include a header that describes the + // included audio content. You can request recognition for `WAV` files that + // contain either `LINEAR16` or `MULAW` encoded audio. + // If you send `FLAC` or `WAV` audio file format in + // your request, you do not need to specify an `AudioEncoding`; the audio + // encoding format is determined from the file header. If you specify + // an `AudioEncoding` when you send send `FLAC` or `WAV` audio, the + // encoding configuration must match the encoding described in the audio + // header; otherwise the request returns an + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT] error + // code. + enum AudioEncoding { + // Not specified. + ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + LINEAR16 = 1; + + // `FLAC` (Free Lossless Audio + // Codec) is the recommended encoding because it is + // lossless--therefore recognition is not compromised--and + // requires only about half the bandwidth of `LINEAR16`. `FLAC` stream + // encoding supports 16-bit and 24-bit samples, however, not all fields in + // `STREAMINFO` are supported. + FLAC = 2; + + // 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law. + MULAW = 3; + + // Adaptive Multi-Rate Narrowband codec. `sample_rate_hertz` must be 8000. + AMR = 4; + + // Adaptive Multi-Rate Wideband codec. `sample_rate_hertz` must be 16000. + AMR_WB = 5; + + // Opus encoded audio frames in Ogg container + // ([OggOpus](https://wiki.xiph.org/OggOpus)). + // `sample_rate_hertz` must be one of 8000, 12000, 16000, 24000, or 48000. + OGG_OPUS = 6; + + // Although the use of lossy encodings is not recommended, if a very low + // bitrate encoding is required, `OGG_OPUS` is highly preferred over + // Speex encoding. The [Speex](https://speex.org/) encoding supported by + // Cloud Speech API has a header byte in each block, as in MIME type + // `audio/x-speex-with-header-byte`. + // It is a variant of the RTP Speex encoding defined in + // [RFC 5574](https://tools.ietf.org/html/rfc5574). + // The stream is a sequence of blocks, one block per RTP packet. Each block + // starts with a byte containing the length of the block, in bytes, followed + // by one or more frames of Speex data, padded to an integral number of + // bytes (octets) as specified in RFC 5574. In other words, each RTP header + // is replaced with a single byte containing the block length. Only Speex + // wideband is supported. `sample_rate_hertz` must be 16000. + SPEEX_WITH_HEADER_BYTE = 7; + } + + // Encoding of audio data sent in all `RecognitionAudio` messages. + // This field is optional for `FLAC` and `WAV` audio files and required + // for all other audio formats. For details, see + // [AudioEncoding][google.cloud.speech.v1p1beta1.RecognitionConfig.AudioEncoding]. + AudioEncoding encoding = 1; + + // Sample rate in Hertz of the audio data sent in all + // `RecognitionAudio` messages. Valid values are: 8000-48000. + // 16000 is optimal. For best results, set the sampling rate of the audio + // source to 16000 Hz. If that's not possible, use the native sample rate of + // the audio source (instead of re-sampling). + // This field is optional for `FLAC` and `WAV` audio files and required + // for all other audio formats. For details, see + // [AudioEncoding][google.cloud.speech.v1p1beta1.RecognitionConfig.AudioEncoding]. + int32 sample_rate_hertz = 2; + + // *Optional* The number of channels in the input audio data. + // ONLY set this for MULTI-CHANNEL recognition. + // Valid values for LINEAR16 and FLAC are `1`-`8`. + // Valid values for OGG_OPUS are '1'-'254'. + // Valid value for MULAW, AMR, AMR_WB and SPEEX_WITH_HEADER_BYTE is only `1`. + // If `0` or omitted, defaults to one channel (mono). + // Note: We only recognize the first channel by default. + // To perform independent recognition on each channel set + // `enable_separate_recognition_per_channel` to 'true'. + int32 audio_channel_count = 7; + + // This needs to be set to ‘true’ explicitly and `audio_channel_count` > 1 + // to get each channel recognized separately. The recognition result will + // contain a `channel_tag` field to state which channel that result belongs + // to. If this is not true, we will only recognize the first channel. The + // request is billed cumulatively for all channels recognized: + // `audio_channel_count` multiplied by the length of the audio. + bool enable_separate_recognition_per_channel = 12; + + // *Required* The language of the supplied audio as a + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. + // Example: "en-US". + // See [Language Support](/speech-to-text/docs/languages) + // for a list of the currently supported language codes. + string language_code = 3; + + // *Optional* A list of up to 3 additional + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tags, + // listing possible alternative languages of the supplied audio. + // See [Language Support](/speech-to-text/docs/languages) + // for a list of the currently supported language codes. + // If alternative languages are listed, recognition result will contain + // recognition in the most likely language detected including the main + // language_code. The recognition result will include the language tag + // of the language detected in the audio. + // Note: This feature is only supported for Voice Command and Voice Search + // use cases and performance may vary for other use cases (e.g., phone call + // transcription). + repeated string alternative_language_codes = 18; + + // *Optional* Maximum number of recognition hypotheses to be returned. + // Specifically, the maximum number of `SpeechRecognitionAlternative` messages + // within each `SpeechRecognitionResult`. + // The server may return fewer than `max_alternatives`. + // Valid values are `0`-`30`. A value of `0` or `1` will return a maximum of + // one. If omitted, will return a maximum of one. + int32 max_alternatives = 4; + + // *Optional* If set to `true`, the server will attempt to filter out + // profanities, replacing all but the initial character in each filtered word + // with asterisks, e.g. "f***". If set to `false` or omitted, profanities + // won't be filtered out. + bool profanity_filter = 5; + + // *Optional* array of + // [SpeechContext][google.cloud.speech.v1p1beta1.SpeechContext]. A means to + // provide context to assist the speech recognition. For more information, see + // [Phrase Hints](/speech-to-text/docs/basics#phrase-hints). + repeated SpeechContext speech_contexts = 6; + + // *Optional* If `true`, the top result includes a list of words and + // the start and end time offsets (timestamps) for those words. If + // `false`, no word-level time offset information is returned. The default is + // `false`. + bool enable_word_time_offsets = 8; + + // *Optional* If `true`, the top result includes a list of words and the + // confidence for those words. If `false`, no word-level confidence + // information is returned. The default is `false`. + bool enable_word_confidence = 15; + + // *Optional* If 'true', adds punctuation to recognition result hypotheses. + // This feature is only available in select languages. Setting this for + // requests in other languages has no effect at all. + // The default 'false' value does not add punctuation to result hypotheses. + // Note: This is currently offered as an experimental service, complimentary + // to all users. In the future this may be exclusively available as a + // premium feature. + bool enable_automatic_punctuation = 11; + + // *Optional* If 'true', enables speaker detection for each recognized word in + // the top alternative of the recognition result using a speaker_tag provided + // in the WordInfo. + // Note: When this is true, we send all the words from the beginning of the + // audio for the top alternative in every consecutive STREAMING responses. + // This is done in order to improve our speaker tags as our models learn to + // identify the speakers in the conversation over time. + // For non-streaming requests, the diarization results will be provided only + // in the top alternative of the FINAL SpeechRecognitionResult. + bool enable_speaker_diarization = 16; + + // *Optional* + // If set, specifies the estimated number of speakers in the conversation. + // If not set, defaults to '2'. + // Ignored unless enable_speaker_diarization is set to true." + int32 diarization_speaker_count = 17; + + // *Optional* Metadata regarding this request. + RecognitionMetadata metadata = 9; + + // *Optional* Which model to select for the given request. Select the model + // best suited to your domain to get best results. If a model is not + // explicitly specified, then we auto-select a model based on the parameters + // in the RecognitionConfig. + // <table> + // <tr> + // <td><b>Model</b></td> + // <td><b>Description</b></td> + // </tr> + // <tr> + // <td><code>command_and_search</code></td> + // <td>Best for short queries such as voice commands or voice search.</td> + // </tr> + // <tr> + // <td><code>phone_call</code></td> + // <td>Best for audio that originated from a phone call (typically + // recorded at an 8khz sampling rate).</td> + // </tr> + // <tr> + // <td><code>video</code></td> + // <td>Best for audio that originated from from video or includes multiple + // speakers. Ideally the audio is recorded at a 16khz or greater + // sampling rate. This is a premium model that costs more than the + // standard rate.</td> + // </tr> + // <tr> + // <td><code>default</code></td> + // <td>Best for audio that is not one of the specific audio models. + // For example, long-form audio. Ideally the audio is high-fidelity, + // recorded at a 16khz or greater sampling rate.</td> + // </tr> + // </table> + string model = 13; + + // *Optional* Set to true to use an enhanced model for speech recognition. + // If `use_enhanced` is set to true and the `model` field is not set, then + // an appropriate enhanced model is chosen if: + // 1. project is eligible for requesting enhanced models + // 2. an enhanced model exists for the audio + // + // If `use_enhanced` is true and an enhanced version of the specified model + // does not exist, then the speech is recognized using the standard version + // of the specified model. + // + // Enhanced speech models require that you opt-in to data logging using + // instructions in the + // [documentation](/speech-to-text/docs/enable-data-logging). If you set + // `use_enhanced` to true and you have not enabled audio logging, then you + // will receive an error. + bool use_enhanced = 14; +} + +// Description of audio data to be recognized. +message RecognitionMetadata { + // Use case categories that the audio recognition request can be described + // by. + enum InteractionType { + // Use case is either unknown or is something other than one of the other + // values below. + INTERACTION_TYPE_UNSPECIFIED = 0; + + // Multiple people in a conversation or discussion. For example in a + // meeting with two or more people actively participating. Typically + // all the primary people speaking would be in the same room (if not, + // see PHONE_CALL) + DISCUSSION = 1; + + // One or more persons lecturing or presenting to others, mostly + // uninterrupted. + PRESENTATION = 2; + + // A phone-call or video-conference in which two or more people, who are + // not in the same room, are actively participating. + PHONE_CALL = 3; + + // A recorded message intended for another person to listen to. + VOICEMAIL = 4; + + // Professionally produced audio (eg. TV Show, Podcast). + PROFESSIONALLY_PRODUCED = 5; + + // Transcribe spoken questions and queries into text. + VOICE_SEARCH = 6; + + // Transcribe voice commands, such as for controlling a device. + VOICE_COMMAND = 7; + + // Transcribe speech to text to create a written document, such as a + // text-message, email or report. + DICTATION = 8; + } + + // Enumerates the types of capture settings describing an audio file. + enum MicrophoneDistance { + // Audio type is not known. + MICROPHONE_DISTANCE_UNSPECIFIED = 0; + + // The audio was captured from a closely placed microphone. Eg. phone, + // dictaphone, or handheld microphone. Generally if there speaker is within + // 1 meter of the microphone. + NEARFIELD = 1; + + // The speaker if within 3 meters of the microphone. + MIDFIELD = 2; + + // The speaker is more than 3 meters away from the microphone. + FARFIELD = 3; + } + + // The original media the speech was recorded on. + enum OriginalMediaType { + // Unknown original media type. + ORIGINAL_MEDIA_TYPE_UNSPECIFIED = 0; + + // The speech data is an audio recording. + AUDIO = 1; + + // The speech data originally recorded on a video. + VIDEO = 2; + } + + // The type of device the speech was recorded with. + enum RecordingDeviceType { + // The recording device is unknown. + RECORDING_DEVICE_TYPE_UNSPECIFIED = 0; + + // Speech was recorded on a smartphone. + SMARTPHONE = 1; + + // Speech was recorded using a personal computer or tablet. + PC = 2; + + // Speech was recorded over a phone line. + PHONE_LINE = 3; + + // Speech was recorded in a vehicle. + VEHICLE = 4; + + // Speech was recorded outdoors. + OTHER_OUTDOOR_DEVICE = 5; + + // Speech was recorded indoors. + OTHER_INDOOR_DEVICE = 6; + } + + // The use case most closely describing the audio content to be recognized. + InteractionType interaction_type = 1; + + // The industry vertical to which this speech recognition request most + // closely applies. This is most indicative of the topics contained + // in the audio. Use the 6-digit NAICS code to identify the industry + // vertical - see https://www.naics.com/search/. + uint32 industry_naics_code_of_audio = 3; + + // The audio type that most closely describes the audio being recognized. + MicrophoneDistance microphone_distance = 4; + + // The original media the speech was recorded on. + OriginalMediaType original_media_type = 5; + + // The type of device the speech was recorded with. + RecordingDeviceType recording_device_type = 6; + + // The device used to make the recording. Examples 'Nexus 5X' or + // 'Polycom SoundStation IP 6000' or 'POTS' or 'VoIP' or + // 'Cardioid Microphone'. + string recording_device_name = 7; + + // Mime type of the original audio file. For example `audio/m4a`, + // `audio/x-alaw-basic`, `audio/mp3`, `audio/3gpp`. + // A list of possible audio mime types is maintained at + // http://www.iana.org/assignments/media-types/media-types.xhtml#audio + string original_mime_type = 8; + + // Obfuscated (privacy-protected) ID of the user, to identify number of + // unique users using the service. + int64 obfuscated_id = 9; + + // Description of the content. Eg. "Recordings of federal supreme court + // hearings from 2012". + string audio_topic = 10; +} + +// Provides "hints" to the speech recognizer to favor specific words and phrases +// in the results. +message SpeechContext { + // *Optional* A list of strings containing words and phrases "hints" so that + // the speech recognition is more likely to recognize them. This can be used + // to improve the accuracy for specific words and phrases, for example, if + // specific commands are typically spoken by the user. This can also be used + // to add additional words to the vocabulary of the recognizer. See + // [usage limits](/speech-to-text/quotas#content). + repeated string phrases = 1; +} + +// Contains audio data in the encoding specified in the `RecognitionConfig`. +// Either `content` or `uri` must be supplied. Supplying both or neither +// returns [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]. +// See [content limits](/speech-to-text/quotas#content). +message RecognitionAudio { + // The audio source, which is either inline content or a Google Cloud + // Storage uri. + oneof audio_source { + // The audio data bytes encoded as specified in + // `RecognitionConfig`. Note: as with all bytes fields, protobuffers use a + // pure binary representation, whereas JSON representations use base64. + bytes content = 1; + + // URI that points to a file that contains audio data bytes as specified in + // `RecognitionConfig`. The file must not be compressed (for example, gzip). + // Currently, only Google Cloud Storage URIs are + // supported, which must be specified in the following format: + // `gs://bucket_name/object_name` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). + // For more information, see [Request + // URIs](https://cloud.google.com/storage/docs/reference-uris). + string uri = 2; + } +} + +// The only message returned to the client by the `Recognize` method. It +// contains the result as zero or more sequential `SpeechRecognitionResult` +// messages. +message RecognizeResponse { + // Output only. Sequential list of transcription results corresponding to + // sequential portions of audio. + repeated SpeechRecognitionResult results = 2; +} + +// The only message returned to the client by the `LongRunningRecognize` method. +// It contains the result as zero or more sequential `SpeechRecognitionResult` +// messages. It is included in the `result.response` field of the `Operation` +// returned by the `GetOperation` call of the `google::longrunning::Operations` +// service. +message LongRunningRecognizeResponse { + // Output only. Sequential list of transcription results corresponding to + // sequential portions of audio. + repeated SpeechRecognitionResult results = 2; +} + +// Describes the progress of a long-running `LongRunningRecognize` call. It is +// included in the `metadata` field of the `Operation` returned by the +// `GetOperation` call of the `google::longrunning::Operations` service. +message LongRunningRecognizeMetadata { + // Approximate percentage of audio processed thus far. Guaranteed to be 100 + // when the audio is fully processed and the results are available. + int32 progress_percent = 1; + + // Time when the request was received. + google.protobuf.Timestamp start_time = 2; + + // Time of the most recent processing update. + google.protobuf.Timestamp last_update_time = 3; +} + +// `StreamingRecognizeResponse` is the only message returned to the client by +// `StreamingRecognize`. A series of zero or more `StreamingRecognizeResponse` +// messages are streamed back to the client. If there is no recognizable +// audio, and `single_utterance` is set to false, then no messages are streamed +// back to the client. +// +// Here's an example of a series of ten `StreamingRecognizeResponse`s that might +// be returned while processing audio: +// +// 1. results { alternatives { transcript: "tube" } stability: 0.01 } +// +// 2. results { alternatives { transcript: "to be a" } stability: 0.01 } +// +// 3. results { alternatives { transcript: "to be" } stability: 0.9 } +// results { alternatives { transcript: " or not to be" } stability: 0.01 } +// +// 4. results { alternatives { transcript: "to be or not to be" +// confidence: 0.92 } +// alternatives { transcript: "to bee or not to bee" } +// is_final: true } +// +// 5. results { alternatives { transcript: " that's" } stability: 0.01 } +// +// 6. results { alternatives { transcript: " that is" } stability: 0.9 } +// results { alternatives { transcript: " the question" } stability: 0.01 } +// +// 7. results { alternatives { transcript: " that is the question" +// confidence: 0.98 } +// alternatives { transcript: " that was the question" } +// is_final: true } +// +// Notes: +// +// - Only two of the above responses #4 and #7 contain final results; they are +// indicated by `is_final: true`. Concatenating these together generates the +// full transcript: "to be or not to be that is the question". +// +// - The others contain interim `results`. #3 and #6 contain two interim +// `results`: the first portion has a high stability and is less likely to +// change; the second portion has a low stability and is very likely to +// change. A UI designer might choose to show only high stability `results`. +// +// - The specific `stability` and `confidence` values shown above are only for +// illustrative purposes. Actual values may vary. +// +// - In each response, only one of these fields will be set: +// `error`, +// `speech_event_type`, or +// one or more (repeated) `results`. +message StreamingRecognizeResponse { + // Indicates the type of speech event. + enum SpeechEventType { + // No speech event specified. + SPEECH_EVENT_UNSPECIFIED = 0; + + // This event indicates that the server has detected the end of the user's + // speech utterance and expects no additional speech. Therefore, the server + // will not process additional audio (although it may subsequently return + // additional results). The client should stop sending additional audio + // data, half-close the gRPC connection, and wait for any additional results + // until the server closes the gRPC connection. This event is only sent if + // `single_utterance` was set to `true`, and is not used otherwise. + END_OF_SINGLE_UTTERANCE = 1; + } + + // Output only. If set, returns a [google.rpc.Status][google.rpc.Status] + // message that specifies the error for the operation. + google.rpc.Status error = 1; + + // Output only. This repeated list contains zero or more results that + // correspond to consecutive portions of the audio currently being processed. + // It contains zero or one `is_final=true` result (the newly settled portion), + // followed by zero or more `is_final=false` results (the interim results). + repeated StreamingRecognitionResult results = 2; + + // Output only. Indicates the type of speech event. + SpeechEventType speech_event_type = 4; +} + +// A streaming speech recognition result corresponding to a portion of the audio +// that is currently being processed. +message StreamingRecognitionResult { + // Output only. May contain one or more recognition hypotheses (up to the + // maximum specified in `max_alternatives`). + // These alternatives are ordered in terms of accuracy, with the top (first) + // alternative being the most probable, as ranked by the recognizer. + repeated SpeechRecognitionAlternative alternatives = 1; + + // Output only. If `false`, this `StreamingRecognitionResult` represents an + // interim result that may change. If `true`, this is the final time the + // speech service will return this particular `StreamingRecognitionResult`, + // the recognizer will not return any further hypotheses for this portion of + // the transcript and corresponding audio. + bool is_final = 2; + + // Output only. An estimate of the likelihood that the recognizer will not + // change its guess about this interim result. Values range from 0.0 + // (completely unstable) to 1.0 (completely stable). + // This field is only provided for interim results (`is_final=false`). + // The default of 0.0 is a sentinel value indicating `stability` was not set. + float stability = 3; + + // Output only. Time offset of the end of this result relative to the + // beginning of the audio. + google.protobuf.Duration result_end_time = 4; + + // For multi-channel audio, this is the channel number corresponding to the + // recognized result for the audio from that channel. + // For audio_channel_count = N, its output values can range from '1' to 'N'. + int32 channel_tag = 5; + + // Output only. The + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag of the + // language in this result. This language code was detected to have the most + // likelihood of being spoken in the audio. + string language_code = 6; +} + +// A speech recognition result corresponding to a portion of the audio. +message SpeechRecognitionResult { + // Output only. May contain one or more recognition hypotheses (up to the + // maximum specified in `max_alternatives`). + // These alternatives are ordered in terms of accuracy, with the top (first) + // alternative being the most probable, as ranked by the recognizer. + repeated SpeechRecognitionAlternative alternatives = 1; + + // For multi-channel audio, this is the channel number corresponding to the + // recognized result for the audio from that channel. + // For audio_channel_count = N, its output values can range from '1' to 'N'. + int32 channel_tag = 2; + + // Output only. The + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag of the + // language in this result. This language code was detected to have the most + // likelihood of being spoken in the audio. + string language_code = 5; +} + +// Alternative hypotheses (a.k.a. n-best list). +message SpeechRecognitionAlternative { + // Output only. Transcript text representing the words that the user spoke. + string transcript = 1; + + // Output only. The confidence estimate between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. This field is set only for the top alternative of a non-streaming + // result or, of a streaming result where `is_final=true`. + // This field is not guaranteed to be accurate and users should not rely on it + // to be always provided. + // The default of 0.0 is a sentinel value indicating `confidence` was not set. + float confidence = 2; + + // Output only. A list of word-specific information for each recognized word. + // Note: When `enable_speaker_diarization` is true, you will see all the words + // from the beginning of the audio. + repeated WordInfo words = 3; +} + +// Word-specific information for recognized words. +message WordInfo { + // Output only. Time offset relative to the beginning of the audio, + // and corresponding to the start of the spoken word. + // This field is only set if `enable_word_time_offsets=true` and only + // in the top hypothesis. + // This is an experimental feature and the accuracy of the time offset can + // vary. + google.protobuf.Duration start_time = 1; + + // Output only. Time offset relative to the beginning of the audio, + // and corresponding to the end of the spoken word. + // This field is only set if `enable_word_time_offsets=true` and only + // in the top hypothesis. + // This is an experimental feature and the accuracy of the time offset can + // vary. + google.protobuf.Duration end_time = 2; + + // Output only. The word corresponding to this set of information. + string word = 3; + + // Output only. The confidence estimate between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. This field is set only for the top alternative of a non-streaming + // result or, of a streaming result where `is_final=true`. + // This field is not guaranteed to be accurate and users should not rely on it + // to be always provided. + // The default of 0.0 is a sentinel value indicating `confidence` was not set. + float confidence = 4; + + // Output only. A distinct integer value is assigned for every speaker within + // the audio. This field specifies which one of those speakers was detected to + // have spoken this word. Value ranges from '1' to diarization_speaker_count. + // speaker_tag is set if enable_speaker_diarization = 'true' and only in the + // top alternative. + int32 speaker_tag = 5; +} diff --git a/google/cloud/speech/v1p1beta1/speech_gapic.yaml b/google/cloud/speech/v1p1beta1/speech_gapic.yaml new file mode 100644 index 000000000..e01424be2 --- /dev/null +++ b/google/cloud/speech/v1p1beta1/speech_gapic.yaml @@ -0,0 +1,159 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.speech.v1p1beta1 + python: + package_name: google.cloud.speech_v1p1beta1.gapic + go: + package_name: cloud.google.com/go/speech/apiv1p1beta1 + csharp: + package_name: Google.Cloud.Speech.V1P1Beta1 + ruby: + package_name: Google::Cloud::Speech::V1p1beta1 + php: + package_name: Google\Cloud\Speech\V1p1beta1 + nodejs: + package_name: speech.v1p1beta1 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.speech.v1p1beta1.Speech + smoke_test: + method: Recognize + init_fields: + - config.language_code="en-US" + - config.sample_rate_hertz=44100 + - config.encoding=FLAC + - audio.uri="gs://gapic-toolkit/hello.flac" + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 1000000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 1000000 + total_timeout_millis: 5000000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: Recognize + flattening: + groups: + - parameters: + - config + - audio + required_fields: + - config + - audio + sample_code_init_fields: + - config.encoding=FLAC + - config.sample_rate_hertz=44100 + - config.language_code="en-US" + - audio.uri=gs://bucket_name/file_name.flac + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 1000000 + - name: LongRunningRecognize + flattening: + groups: + - parameters: + - config + - audio + required_fields: + - config + - audio + sample_code_init_fields: + - config.encoding=FLAC + - config.sample_rate_hertz=44100 + - config.language_code="en-US" + - audio.uri=gs://bucket_name/file_name.flac + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + long_running: + return_type: google.cloud.speech.v1p1beta1.LongRunningRecognizeResponse + metadata_type: google.cloud.speech.v1p1beta1.LongRunningRecognizeMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + - name: StreamingRecognize + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 1000000 + diff --git a/google/cloud/support/common.proto b/google/cloud/support/common.proto new file mode 100644 index 000000000..3b667e6fb --- /dev/null +++ b/google/cloud/support/common.proto @@ -0,0 +1,333 @@ +// 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.support.common; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/support/common;common"; +option java_outer_classname = "CloudSupportProto"; +option java_package = "com.google.cloud.support.common"; + +// A Google Cloud Platform account that identifies support eligibility for a +// Cloud resource. Currently the Cloud resource can only be an Organization +// but this might change in future. +message SupportAccount { + // The current state of this SupportAccount. + enum State { + // Account is in an unknown state. + STATE_UNSPECIFIED = 0; + + // Account is in an active state. + ACTIVE = 1; + + // Account has been created but is being provisioned in support systems. + PENDING = 2; + + // Account deletion has been requested by the user. + PENDING_DELETION = 3; + } + + // Pricing model applicable to this support account. + enum PricingModel { + // This account is subscribed to an unknown pricing model. + PRICING_MODEL_UNKNOWN = 0; + + // Package based pricing (Platinum, Gold, Silver, Bronze). + PACKAGES = 1; + + // Support charges are calculated based on user seats a.k.a, + // "Pick Your Team" model. + USER_ROLES = 2; + } + + // The resource name for a support account in format + // `supportAccounts/{account_id}`. + // Output only. + string name = 1; + + // Identifier for this entity that gets persisted in storage system. The + // resource name is populated using this field in format + // `supportAccounts/{account_id}`. + string account_id = 2; + + // The Cloud resource with which this support account is associated. + string cloud_resource = 3; + + // A user friendly display name assigned to this support account. + string display_name = 4; + + // Indicates the current state of an account. + State state = 5; + + // Time when this account was created. + // Output only. + google.protobuf.Timestamp create_time = 6; + + // The resource name of a billing account associated with this support + // account. For example, `billingAccounts/ABCDEF-012345-567890`. + string billing_account_name = 7; + + string unify_account_id = 8; + + // The PricingModel applicable to this support account. + PricingModel pricing_model = 9; +} + +// A support case created by the user. +message Case { + // The case priority with P0 being the most urgent and P4 the least. + enum Priority { + // Priority is undefined or has not been set yet. + PRIORITY_UNSPECIFIED = 0; + + // Extreme impact on a production service - Service is hard down. + P0 = 1; + + // Critical impact on a production service - Service is currently unusable. + P1 = 2; + + // Severe impact on a production service - Service is usable but greatly + // impaired. + P2 = 3; + + // Medium impact on a production service - Service is available, but + // moderately impaired. + P3 = 4; + + // General questions or minor issues - Production service is fully + // available. + P4 = 5; + } + + // The state of a case. + enum State { + // Case is in an unknown state. + STATE_UNSPECIFIED = 0; + + // Case has been created but no one is assigned to work on it yet. + NEW = 1; + + // Case has been assigned to a support agent. + ASSIGNED = 2; + + // A support agent is currently investigating the case. + IN_PROGRESS_GOOGLE_SUPPORT = 3; + + // Case has been forwarded to product team for further investigation. + IN_PROGRESS_GOOGLE_ENG = 4; + + // Case is under investigation and relates to a known issue. + IN_PROGRESS_KNOWN_ISSUE = 5; + + // Case is waiting for a response from the customer. + WAITING_FOR_CUSTOMER_RESPONSE = 6; + + // A solution has been offered for the case but it isn't closed yet. + SOLUTION_OFFERED = 7; + + // Cases has been fully resolved and is in a closed state. + CLOSED = 8; + } + + // The resource name for the Case in format + // `supportAccounts/{account_id}/cases/{case_id}` + string name = 1; + + // The short summary of the issue reported in this case. + string display_name = 2; + + // The board description of issue provided with initial summary. + string description = 3; + + // The product component for which this Case is reported. + string component = 4; + + // The product subcomponent for which this Case is reported. + string subcomponent = 5; + + // Timezone the client sending this request is in. + // It should be in a format IANA recognizes: https://www.iana.org/time-zone + // There is no additional validation done by the API. + string client_timezone = 6; + + // The email addresses that can be copied to receive updates on this case. + // Users can specify a maximum of 10 email addresses. + repeated string cc_addresses = 7; + + // The Google Cloud Platform project ID for which this case is created. + string project_id = 8; + + // List of customer issues associated with this case. + repeated CustomerIssue issues = 10; + + // The current priority of this case. + Priority priority = 11; + + // The current state of this case. + State state = 12; + + // Time when this case was created. + // Output only. + google.protobuf.Timestamp create_time = 13; + + // Time when this case was last updated. + // Output only. + google.protobuf.Timestamp update_time = 14; + + // Email address of user who created this case. + // Output only. It is inferred from credentials supplied during case creation. + string creator_email = 15; + + // The issue category applicable to this case. + string category = 16; +} + +// Reference to a Google internal ticket used for investigating a support case. +// Not every support case will have an internal ticket associated with it. +// A support case can have multiple tickets linked to it. +message CustomerIssue { + // The status of a customer issue. + enum IssueState { + // Issue in an unknown state. + ISSUE_STATE_UNSPECIFIED = 0; + + // Issue is currently open but the work on it has not been started. + OPEN = 1; + + // Issue is currently being worked on. + IN_PROGRESS = 2; + + // Issue is fixed. + FIXED = 3; + + // Issue has been marked as invalid. + WONT_FIX = 4; + + // Issue verified and in production. + VERIFIED = 5; + } + + // Unique identifier for the internal issue. + // Output only. + string issue_id = 1; + + // Represents current status of the internal ticket. + // Output only. + IssueState state = 2; + + // Time when the internal issue was created. + // Output only. + google.protobuf.Timestamp create_time = 3; + + // Time when the internal issue was marked as resolved. + // Output only. + google.protobuf.Timestamp resolve_time = 4; + + // Time when the internal issue was last updated. + // Output only. + google.protobuf.Timestamp update_time = 5; +} + +// A message that contains mapping of a user and their role under a support +// account. +message SupportRole { + // A role which determines the support resources and features a user might + // get access to. + enum Role { + // An unknown role. + ROLE_UNSPECIFIED = 0; + + // The basic support role. + BASIC = 1; + + // The developer role. + DEVELOPER = 2; + + // The operation role. + OPERATION = 3; + + // The site reliability role. + SITE_RELIABILITY = 4; + } + + // Email address of user being added through this Role. + string email = 1; + + // The type of role assigned to user. + Role role = 2; +} + +// The comment text associated with a `Case`. +message Comment { + // Text containing a maximum of 3000 characters. + string text = 1; + + // Time when this update was created. + // Output only. + google.protobuf.Timestamp create_time = 2; + + // The email address/name of user who created this comment. + // Output only. + string author = 3; + + // The resource name for this comment in format + // `supportAccounts/{account_id}/cases/{case_id}/{comment_id}`. + // Output only. + string name = 4; +} + +// Represents the product component taxonomy that is to be used while creating +// or updating a `Case`. A client should obtain the list of issue categories, +// component/subcomponent from this object and specify it in `Case.category`, +// `Case.component` and `Case.subcomponent` fields respectively. +message IssueTaxonomy { + // The representation of a product component. It is composed of a canonical + // name for the product (e.g., Google App Engine), languages in which a + // support ticket can be created under this component, a template that + // provides hints on important details to be filled out before submitting a + // case. It also contains an embedded list of product subcomponents that have + // similar attributes as top-level components. + // (e.g., Google App Engine > Memcache). + message Component { + // User friendly name of this component. + string display_name = 1; + + // List of languages in which a support case can be created under this + // component. Represented by language codes in ISO_639-1 standard. + repeated string languages = 2; + + // Template to be used while filling the description of a support case. + string template = 3; + + // List of subcomponents under this component. + repeated Component subcomponents = 4; + } + + // Represents the category of issue (Technical or Non-Technical) + // reported through a support case. + message Category { + // User friendly name of this category. + string display_name = 1; + + // Map of product components under this category. + map<string, Component> components = 2; + } + + // Map of available categories. + map<string, Category> categories = 1; +} diff --git a/google/cloud/support/v1alpha1/cloud_support.proto b/google/cloud/support/v1alpha1/cloud_support.proto new file mode 100644 index 000000000..c81bb03f1 --- /dev/null +++ b/google/cloud/support/v1alpha1/cloud_support.proto @@ -0,0 +1,222 @@ +// 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.support.v1alpha1; + +import "google/api/annotations.proto"; +import "google/cloud/support/common.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/support/v1alpha1;support"; +option java_outer_classname = "CloudSupportProto"; +option java_package = "com.google.cloud.support.v1alpha1"; + +// Retrieves the list of Google Cloud Platform Support accounts and manages +// support cases associated with them. +service CloudSupport { + // Retrieves the support account details given an account identifier. + // The authenticated user calling this method must be the account owner. + rpc GetSupportAccount(GetSupportAccountRequest) + returns (google.cloud.support.common.SupportAccount) { + option (google.api.http) = { + get: "/v1alpha1/{name=supportAccounts/*}" + }; + } + + // Retrieves the list of accounts the current authenticated user has access + // to. + rpc ListSupportAccounts(ListSupportAccountsRequest) + returns (ListSupportAccountsResponse) { + option (google.api.http) = { + get: "/v1alpha1/supportAccounts" + }; + } + + // Retrieves the details for a support case. The current authenticated user + // calling this method must have permissions to view this case. + rpc GetCase(GetCaseRequest) returns (google.cloud.support.common.Case) { + option (google.api.http) = { + get: "/v1alpha1/{name=supportAccounts/*/cases/*}" + }; + } + + // Retrieves the list of support cases associated with an account. The current + // authenticated user must have the permission to list and view these cases. + rpc ListCases(ListCasesRequest) returns (ListCasesResponse) { + option (google.api.http) = { + get: "/v1alpha1/{name=supportAccounts/*}/cases" + }; + } + + // Lists all comments from a case. + rpc ListComments(ListCommentsRequest) returns (ListCommentsResponse) { + option (google.api.http) = { + get: "/v1alpha1/{name=supportAccounts/*/cases/*}/comments" + }; + } + + // Creates a case and associates it with a + // [SupportAccount][google.cloud.support.v1alpha2.SupportAcccount]. The + // authenticated user attempting this action must have permissions to create a + // `Case` under that [SupportAccount]. + rpc CreateCase(CreateCaseRequest) returns (google.cloud.support.common.Case) { + option (google.api.http) = { + post: "/v1alpha1/{parent=supportAccounts/*}/cases" + body: "case" + }; + } + + // Updates a support case. Only a small set of details (priority, subject and + // cc_address) can be update after a case is created. + rpc UpdateCase(UpdateCaseRequest) returns (google.cloud.support.common.Case) { + option (google.api.http) = { + patch: "/v1alpha1/{case.name=supportAccounts/*/cases/*}" + body: "case" + }; + } + + // Adds a new comment to a case. + rpc CreateComment(CreateCommentRequest) + returns (google.cloud.support.common.Comment) { + option (google.api.http) = { + post: "/v1alpha1/{name=supportAccounts/*/cases/*}/comments" + body: "comment" + }; + } + + // Retrieves the taxonomy of product categories and components to be used + // while creating a support case. + rpc GetIssueTaxonomy(GetIssueTaxonomyRequest) + returns (google.cloud.support.common.IssueTaxonomy) { + option (google.api.http) = { + get: "/v1alpha1:getIssueTaxonomy" + }; + } +} + +// The request message for `GetSupportAccount`. +message GetSupportAccountRequest { + // The resource name of the support accounts. For example: + // `supportAccounts/accountA`. + string name = 1; +} + +// The request message for `ListSupportAccount`. +message ListSupportAccountsRequest { + // The filter applied to search results. It only supports filtering a support + // account list by a cloud_resource. For example, to filter results by support + // accounts associated with an Organization, its value should be: + // "cloud_resource:organizations/<organization_id>" + string filter = 1; + + // Maximum number of accounts fetched with each request. + int64 page_size = 2; + + // A token identifying the page of results to return. If unspecified, the + // first page is retrieved. + string page_token = 3; +} + +// The response message for `ListSupportAccount`. +message ListSupportAccountsResponse { + // A list of support accounts. + repeated google.cloud.support.common.SupportAccount accounts = 1; + + // A token to retrieve the next page of results. This should be passed on in + // `page_token` field of `ListSupportAccountRequest` for next request. If + // unspecified, there are no more results to retrieve. + string next_page_token = 2; +} + +// The request message for `GetCase` method. +message GetCaseRequest { + // Name of case resource requested. + // For example: "supportAccounts/accountA/cases/123" + string name = 1; +} + +// The request message for `ListCase` method. +message ListCasesRequest { + // Name of the account resource for which cases are requested. For example: + // "supportAccounts/accountA" + string name = 1; + + // The filter applied to the search results. Currently it only accepts "OPEN" + // or "CLOSED" strings, filtering out cases that are open or resolved. + string filter = 2; + + // Maximum number of cases fetched with each request. + int64 page_size = 3; + + // A token identifying the page of results to return. If unspecified, the + // first page is retrieved. + string page_token = 4; +} + +// The response message for `ListCase` method. +message ListCasesResponse { + // A list of cases. + repeated google.cloud.support.common.Case cases = 1; + + // A token to retrieve the next page of results. This should be passed on in + // `page_token` field of `ListCaseRequest` for next request. If unspecified, + // there are no more results to retrieve. + string next_page_token = 2; +} + +// The request message for `ListComments` method. +message ListCommentsRequest { + // The resource name of case for which comments should be listed. + string name = 1; +} + +// The response message for `ListComments` method. +message ListCommentsResponse { + // A list of comments. + repeated google.cloud.support.common.Comment comments = 1; +} + +// The request message for `CreateCase` method. +message CreateCaseRequest { + // The resource name for `SupportAccount` under which this case is created. + string parent = 1; + + // The case resource to create. + google.cloud.support.common.Case case = 2; +} + +// The request message for `UpdateCase` method. +message UpdateCaseRequest { + // The case resource to update. + google.cloud.support.common.Case case = 1; + + // A field that represents attributes of a Case object that should be updated + // as part of this request. + google.protobuf.FieldMask update_mask = 2; +} + +// The request message for `CreateComment` method. +message CreateCommentRequest { + // The resource name of case to which this comment should be added. + string name = 1; + + // The `Comment` to be added to this case. + google.cloud.support.common.Comment comment = 2; +} + +// The request message for `GetIssueTaxonomy` method. +message GetIssueTaxonomyRequest {} diff --git a/google/cloud/talent/artman_talent_v4beta1.yaml b/google/cloud/talent/artman_talent_v4beta1.yaml new file mode 100644 index 000000000..5cdcce085 --- /dev/null +++ b/google/cloud/talent/artman_talent_v4beta1.yaml @@ -0,0 +1,36 @@ +# The API producer can manually edit it. Remove all the FIXMEs +# before sending this file out for review. +common: + api_name: talent + api_version: v4beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v4beta1 + service_yaml: talent_v4beta1.yaml + gapic_yaml: v4beta1/talent_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/talent/talent_v4beta1.yaml b/google/cloud/talent/talent_v4beta1.yaml new file mode 100644 index 000000000..e91deb907 --- /dev/null +++ b/google/cloud/talent/talent_v4beta1.yaml @@ -0,0 +1,147 @@ +type: google.api.Service +config_version: 3 +name: jobs.googleapis.com +title: Cloud Talent Solution API + +apis: +- name: google.cloud.talent.v4beta1.ApplicationService +- name: google.cloud.talent.v4beta1.CompanyService +- name: google.cloud.talent.v4beta1.Completion +- name: google.cloud.talent.v4beta1.EventService +- name: google.cloud.talent.v4beta1.JobService +- name: google.cloud.talent.v4beta1.ProfileService +- name: google.cloud.talent.v4beta1.TenantService + +documentation: + summary: |- + Cloud Talent Solution provides the capability to create, read, update, and + delete job postings, as well as search jobs based on keywords and filters. + overview: |- + # Introduction + + Cloud Talent Solution provides hiring companies and job distributors with + the capability to create and manage job postings and organizational + information, and perform job search using field based queries. This site + contains all of the information you need to integrate Cloud Talent Solution, + create company entities that represent employers with intended access + control, post and manage jobs on Garage Jobs on behalf of employers, and + search jobs where access control permits. For a full list of supported API + methods, refer to the [Reference](rest/) section. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 30.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 30.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 30.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 30.0 + - selector: google.longrunning.Operations.WaitOperation + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ApplicationService.CreateApplication + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ApplicationService.GetApplication + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ApplicationService.UpdateApplication + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ApplicationService.DeleteApplication + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ApplicationService.ListApplications + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.CompanyService.CreateCompany + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.CompanyService.GetCompany + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.CompanyService.UpdateCompany + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.CompanyService.DeleteCompany + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.CompanyService.ListCompanies + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.Completion.CompleteQuery + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.EventService.CreateClientEvent + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.CreateJob + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.GetJob + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.UpdateJob + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.DeleteJob + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.ListJobs + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.BatchDeleteJobs + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.SearchJobs + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.JobService.SearchJobsForAlert + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ProfileService.ListProfiles + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ProfileService.CreateProfile + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ProfileService.GetProfile + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ProfileService.UpdateProfile + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ProfileService.DeleteProfile + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.ProfileService.SearchProfiles + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.TenantService.CreateTenant + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.TenantService.GetTenant + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.TenantService.UpdateTenant + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.TenantService.DeleteTenant + deadline: 30.0 + - selector: google.cloud.talent.v4beta1.TenantService.ListTenants + deadline: 30.0 + +authentication: + rules: + - selector: 'google.cloud.talent.v4beta1.ApplicationService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs + - selector: 'google.cloud.talent.v4beta1.CompanyService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs + - selector: google.cloud.talent.v4beta1.Completion.CompleteQuery + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs + - selector: google.cloud.talent.v4beta1.EventService.CreateClientEvent + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs + - selector: 'google.cloud.talent.v4beta1.JobService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs + - selector: 'google.cloud.talent.v4beta1.ProfileService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs + - selector: 'google.cloud.talent.v4beta1.TenantService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs + - selector: 'google.longrunning.Operations.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/jobs diff --git a/google/cloud/talent/v4beta1/application.proto b/google/cloud/talent/v4beta1/application.proto new file mode 100644 index 000000000..330afe82d --- /dev/null +++ b/google/cloud/talent/v4beta1/application.proto @@ -0,0 +1,198 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/cloud/talent/v4beta1/common.proto"; +import "google/cloud/talent/v4beta1/job.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "google/type/date.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "ApplicationResourceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// Resource that represents a job application record of a candidate. +message Application { + // Enum that represents the application status. + enum ApplicationState { + // Default value. + APPLICATION_STATE_UNSPECIFIED = 0; + + // The current stage is in progress or pending, for example, interviews in + // progress. + IN_PROGRESS = 1; + + // The current stage was terminated by a candidate decision. + CANDIDATE_WITHDREW = 2; + + // The current stage was terminated by an employer or agency decision. + EMPLOYER_WITHDREW = 3; + + // The current stage is successfully completed, but the next stage (if + // applicable) has not begun. + COMPLETED = 4; + + // The current stage was closed without an exception, or terminated for + // reasons unrealated to the candidate. + CLOSED = 5; + } + + // The stage of the application. + enum ApplicationStage { + // Default value. + APPLICATION_STAGE_UNSPECIFIED = 0; + + // Candidate has applied or a recruiter put candidate into consideration but + // candidate is not yet screened / no decision has been made to move or not + // move the candidate to the next stage. + NEW = 1; + + // A recruiter decided to screen the candidate for this role. + SCREEN = 2; + + // Candidate is being / was sent to the customer / hiring manager for + // detailed review. + HIRING_MANAGER_REVIEW = 3; + + // Candidate was approved by the client / hiring manager and is being / was + // interviewed for the role. + INTERVIEW = 4; + + // Candidate will be / has been given an offer of employment. + OFFER_EXTENDED = 5; + + // Candidate has accepted their offer of employment. + OFFER_ACCEPTED = 6; + + // Candidate has begun (or completed) their employment or assignment with + // the employer. + STARTED = 7; + } + + // Required during application update. + // + // Resource name assigned to an application by the API. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}/applications/{application_id}", + // for example, + // "projects/api-test-project/tenants/foo/profiles/bar/applications/baz". + string name = 1; + + // Required. + // + // Client side application identifier, used to uniquely identify the + // recruiter. + // + // The maximum number of allowed characters is 255. + string external_id = 31; + + // Required. + // + // Resource name of the candidate of this application. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}", + // for example, "projects/api-test-project/tenants/foo/profiles/bar". + string profile = 2; + + // One of either a job or a company is required. + // + // Resource name of the job which the candidate applied for. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/jobs/{job_id}", + // for example, "projects/api-test-project/tenants/foo/jobs/bar". + string job = 4; + + // One of either a job or a company is required. + // + // Resource name of the company which the candidate applied for. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", + // for example, "projects/api-test-project/tenants/foo/companies/bar". + string company = 5; + + // Optional. + // + // The application date. + google.type.Date application_date = 7; + + // Required. + // + // What is the most recent stage of the application (that is, new, screen, + // send cv, hired, finished work)? This field is intentionally not + // comprehensive of every possible status, but instead, represents statuses + // that would be used to indicate to the ML models good / bad matches. + ApplicationStage stage = 11; + + // Optional. + // + // The application state. + ApplicationState state = 13; + + // Optional. + // + // All interviews (screen, onsite, and so on) conducted as part of this + // application (includes details such as user conducting the interview, + // timestamp, feedback, and so on). + repeated Interview interviews = 16; + + // Optional. + // + // If the candidate is referred by a employee. + google.protobuf.BoolValue referral = 18; + + // Required. + // + // Reflects the time that the application was created. + google.protobuf.Timestamp create_time = 19; + + // Optional. + // + // The last update timestamp. + google.protobuf.Timestamp update_time = 20; + + // Optional. + // + // Free text reason behind the recruitement outcome (for example, reason for + // withdraw / reject, reason for an unsuccessful finish, and so on). + // + // Number of characters allowed is 100. + string outcome_notes = 21; + + // Optional. + // + // Outcome positiveness shows how positive the outcome is. + Outcome outcome = 22; + + // Output only. Indicates whether this job application is a match to + // application related filters. This value is only applicable in profile + // search response. + google.protobuf.BoolValue is_match = 28; + + // Output only. Job title snippet shows how the job title is related to a + // search query. It's empty if the job title isn't related to the search + // query. + string job_title_snippet = 29; +} diff --git a/google/cloud/talent/v4beta1/application_service.proto b/google/cloud/talent/v4beta1/application_service.proto new file mode 100644 index 000000000..4ff4a026f --- /dev/null +++ b/google/cloud/talent/v4beta1/application_service.proto @@ -0,0 +1,170 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/application.proto"; +import "google/cloud/talent/v4beta1/common.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "ApplicationServiceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A service that handles application management, including CRUD and +// enumeration. +service ApplicationService { + // Creates a new application entity. + rpc CreateApplication(CreateApplicationRequest) returns (Application) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*/profiles/*}/applications" + body: "*" + }; + } + + // Retrieves specified application. + rpc GetApplication(GetApplicationRequest) returns (Application) { + option (google.api.http) = { + get: "/v4beta1/{name=projects/*/tenants/*/profiles/*/applications/*}" + }; + } + + // Updates specified application. + rpc UpdateApplication(UpdateApplicationRequest) returns (Application) { + option (google.api.http) = { + patch: "/v4beta1/{application.name=projects/*/tenants/*/profiles/*/applications/*}" + body: "*" + }; + } + + // Deletes specified application. + rpc DeleteApplication(DeleteApplicationRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v4beta1/{name=projects/*/tenants/*/profiles/*/applications/*}" + }; + } + + // Lists all applications associated with the profile. + rpc ListApplications(ListApplicationsRequest) returns (ListApplicationsResponse) { + option (google.api.http) = { + get: "/v4beta1/{parent=projects/*/tenants/*/profiles/*}/applications" + }; + } +} + +// The Request of the CreateApplication method. +message CreateApplicationRequest { + // Required. + // + // Resource name of the profile under which the application is created. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}", for + // example, "projects/test-project/tenants/test-tenant/profiles/test-profile". + string parent = 1; + + // Required. + // + // The application to be created. + Application application = 2; +} + +// Request for getting a application by name. +message GetApplicationRequest { + // Required. + // + // The resource name of the application to be retrieved. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}/applications/{application_id}", + // for example, + // "projects/test-project/tenants/test-tenant/profiles/test-profile/applications/test-application". + string name = 1; +} + +// Request for updating a specified application. +message UpdateApplicationRequest { + // Required. + // + // The application resource to replace the current resource in the system. + Application application = 1; + + // Optional but strongly recommended for the best service + // experience. + // + // If [update_mask][google.cloud.talent.v4beta1.UpdateApplicationRequest.update_mask] is provided, only the specified fields in + // [application][google.cloud.talent.v4beta1.UpdateApplicationRequest.application] are updated. Otherwise all the fields are updated. + // + // A field mask to specify the application fields to be updated. Only + // top level fields of [Application][google.cloud.talent.v4beta1.Application] are supported. + google.protobuf.FieldMask update_mask = 2; +} + +// Request to delete a application. +message DeleteApplicationRequest { + // Required. + // + // The resource name of the application to be deleted. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}/applications/{application_id}", + // for example, + // "projects/test-project/tenants/test-tenant/profiles/test-profile/applications/test-application". + string name = 1; +} + +// List applications for which the client has ACL visibility. +message ListApplicationsRequest { + // Required. + // + // Resource name of the profile under which the application is created. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}", for + // example, "projects/test-project/tenants/test-tenant/profiles/test-profile". + string parent = 1; + + // Optional. + // + // The starting indicator from which to return results. + string page_token = 2; + + // Optional. + // + // The maximum number of applications to be returned, at most 100. + // Default is 100 if a non-positive number is provided. + int32 page_size = 3; +} + +// Output only. +// +// The List applications response object. +message ListApplicationsResponse { + // Applications for the current client. + repeated Application applications = 1; + + // A token to retrieve the next page of results. + string next_page_token = 2; + + // Additional information for the API invocation, such as the request + // tracking id. + ResponseMetadata metadata = 3; +} diff --git a/google/cloud/talent/v4beta1/batch.proto b/google/cloud/talent/v4beta1/batch.proto new file mode 100644 index 000000000..fcfe2bed0 --- /dev/null +++ b/google/cloud/talent/v4beta1/batch.proto @@ -0,0 +1,29 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/job.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "BatchProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; diff --git a/google/cloud/talent/v4beta1/common.proto b/google/cloud/talent/v4beta1/common.proto new file mode 100644 index 000000000..370438862 --- /dev/null +++ b/google/cloud/talent/v4beta1/common.proto @@ -0,0 +1,1001 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "google/type/date.proto"; +import "google/type/latlng.proto"; +import "google/type/money.proto"; +import "google/type/postal_address.proto"; +import "google/type/timeofday.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "CommonProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// Message representing a period of time between two timestamps. +message TimestampRange { + // Begin of the period (inclusive). + google.protobuf.Timestamp start_time = 1; + + // End of the period (exclusive). + google.protobuf.Timestamp end_time = 2; +} + +// Output only. +// +// A resource that represents a location with full geographic information. +message Location { + // An enum which represents the type of a location. + enum LocationType { + // Default value if the type isn't specified. + LOCATION_TYPE_UNSPECIFIED = 0; + + // A country level location. + COUNTRY = 1; + + // A state or equivalent level location. + ADMINISTRATIVE_AREA = 2; + + // A county or equivalent level location. + SUB_ADMINISTRATIVE_AREA = 3; + + // A city or equivalent level location. + LOCALITY = 4; + + // A postal code level location. + POSTAL_CODE = 5; + + // A sublocality is a subdivision of a locality, for example a city borough, + // ward, or arrondissement. Sublocalities are usually recognized by a local + // political authority. For example, Manhattan and Brooklyn are recognized + // as boroughs by the City of New York, and are therefore modeled as + // sublocalities. + SUB_LOCALITY = 6; + + // A district or equivalent level location. + SUB_LOCALITY_1 = 7; + + // A smaller district or equivalent level display. + SUB_LOCALITY_2 = 8; + + // A neighborhood level location. + NEIGHBORHOOD = 9; + + // A street address level location. + STREET_ADDRESS = 10; + } + + // The type of a location, which corresponds to the address lines field of + // [PostalAddress][]. For example, "Downtown, Atlanta, GA, USA" has a type of + // [LocationType#NEIGHBORHOOD][], and "Kansas City, KS, USA" has a type of + // [LocationType#LOCALITY][]. + LocationType location_type = 1; + + // Postal address of the location that includes human readable information, + // such as postal delivery and payments addresses. Given a postal address, + // a postal service can deliver items to a premises, P.O. Box, or other + // delivery location. + google.type.PostalAddress postal_address = 2; + + // An object representing a latitude/longitude pair. + google.type.LatLng lat_lng = 3; + + // Radius in miles of the job location. This value is derived from the + // location bounding box in which a circle with the specified radius + // centered from [LatLng][] covers the area associated with the job location. + // For example, currently, "Mountain View, CA, USA" has a radius of + // 6.17 miles. + double radius_miles = 4; +} + +// An enum that represents the size of the company. +enum CompanySize { + // Default value if the size isn't specified. + COMPANY_SIZE_UNSPECIFIED = 0; + + // The company has less than 50 employees. + MINI = 1; + + // The company has between 50 and 99 employees. + SMALL = 2; + + // The company has between 100 and 499 employees. + SMEDIUM = 3; + + // The company has between 500 and 999 employees. + MEDIUM = 4; + + // The company has between 1,000 and 4,999 employees. + BIG = 5; + + // The company has between 5,000 and 9,999 employees. + BIGGER = 6; + + // The company has 10,000 or more employees. + GIANT = 7; +} + +// An enum that represents employee benefits included with the job. +enum JobBenefit { + // Default value if the type isn't specified. + JOB_BENEFIT_UNSPECIFIED = 0; + + // The job includes access to programs that support child care, such + // as daycare. + CHILD_CARE = 1; + + // The job includes dental services covered by a dental + // insurance plan. + DENTAL = 2; + + // The job offers specific benefits to domestic partners. + DOMESTIC_PARTNER = 3; + + // The job allows for a flexible work schedule. + FLEXIBLE_HOURS = 4; + + // The job includes health services covered by a medical insurance plan. + MEDICAL = 5; + + // The job includes a life insurance plan provided by the employer or + // available for purchase by the employee. + LIFE_INSURANCE = 6; + + // The job allows for a leave of absence to a parent to care for a newborn + // child. + PARENTAL_LEAVE = 7; + + // The job includes a workplace retirement plan provided by the + // employer or available for purchase by the employee. + RETIREMENT_PLAN = 8; + + // The job allows for paid time off due to illness. + SICK_DAYS = 9; + + // The job includes paid time off for vacation. + VACATION = 10; + + // The job includes vision services covered by a vision + // insurance plan. + VISION = 11; +} + +// Educational degree level defined in International Standard Classification +// of Education (ISCED). +enum DegreeType { + // Default value. Represents no degree, or early childhood education. + // Maps to ISCED code 0. + // Ex) Kindergarten + DEGREE_TYPE_UNSPECIFIED = 0; + + // Primary education which is typically the first stage of compulsory + // education. ISCED code 1. + // Ex) Elementary school + PRIMARY_EDUCATION = 1; + + // Lower secondary education; First stage of secondary education building on + // primary education, typically with a more subject-oriented curriculum. + // ISCED code 2. + // Ex) Middle school + LOWER_SECONDARY_EDUCATION = 2; + + // Middle education; Second/final stage of secondary education preparing for + // tertiary education and/or providing skills relevant to employment. + // Usually with an increased range of subject options and streams. ISCED + // code 3. + // Ex) High school + UPPER_SECONDARY_EDUCATION = 3; + + // Adult Remedial Education; Programmes providing learning experiences that + // build on secondary education and prepare for labour market entry and/or + // tertiary education. The content is broader than secondary but not as + // complex as tertiary education. ISCED code 4. + ADULT_REMEDIAL_EDUCATION = 4; + + // Associate's or equivalent; Short first tertiary programmes that are + // typically practically-based, occupationally-specific and prepare for + // labour market entry. These programmes may also provide a pathway to other + // tertiary programmes. ISCED code 5. + ASSOCIATES_OR_EQUIVALENT = 5; + + // Bachelor's or equivalent; Programmes designed to provide intermediate + // academic and/or professional knowledge, skills and competencies leading + // to a first tertiary degree or equivalent qualification. ISCED code 6. + BACHELORS_OR_EQUIVALENT = 6; + + // Master's or equivalent; Programmes designed to provide advanced academic + // and/or professional knowledge, skills and competencies leading to a + // second tertiary degree or equivalent qualification. ISCED code 7. + MASTERS_OR_EQUIVALENT = 7; + + // Doctoral or equivalent; Programmes designed primarily to lead to an + // advanced research qualification, usually concluding with the submission + // and defense of a substantive dissertation of publishable quality based on + // original research. ISCED code 8. + DOCTORAL_OR_EQUIVALENT = 8; +} + +// An enum that represents the employment type of a job. +enum EmploymentType { + // The default value if the employment type isn't specified. + EMPLOYMENT_TYPE_UNSPECIFIED = 0; + + // The job requires working a number of hours that constitute full + // time employment, typically 40 or more hours per week. + FULL_TIME = 1; + + // The job entails working fewer hours than a full time job, + // typically less than 40 hours a week. + PART_TIME = 2; + + // The job is offered as a contracted, as opposed to a salaried employee, + // position. + CONTRACTOR = 3; + + // The job is offered as a contracted position with the understanding + // that it's converted into a full-time position at the end of the + // contract. Jobs of this type are also returned by a search for + // [EmploymentType.CONTRACTOR][google.cloud.talent.v4beta1.EmploymentType.CONTRACTOR] jobs. + CONTRACT_TO_HIRE = 4; + + // The job is offered as a temporary employment opportunity, usually + // a short-term engagement. + TEMPORARY = 5; + + // The job is a fixed-term opportunity for students or entry-level job + // seekers to obtain on-the-job training, typically offered as a summer + // position. + INTERN = 6; + + // The is an opportunity for an individual to volunteer, where there's no + // expectation of compensation for the provided services. + VOLUNTEER = 7; + + // The job requires an employee to work on an as-needed basis with a + // flexible schedule. + PER_DIEM = 8; + + // The job involves employing people in remote areas and flying them + // temporarily to the work site instead of relocating employees and their + // families permanently. + FLY_IN_FLY_OUT = 9; + + // The job does not fit any of the other listed types. + OTHER_EMPLOYMENT_TYPE = 10; +} + +// An enum that represents the required experience level required for the job. +enum JobLevel { + // The default value if the level isn't specified. + JOB_LEVEL_UNSPECIFIED = 0; + + // Entry-level individual contributors, typically with less than 2 years of + // experience in a similar role. Includes interns. + ENTRY_LEVEL = 1; + + // Experienced individual contributors, typically with 2+ years of + // experience in a similar role. + EXPERIENCED = 2; + + // Entry- to mid-level managers responsible for managing a team of people. + MANAGER = 3; + + // Senior-level managers responsible for managing teams of managers. + DIRECTOR = 4; + + // Executive-level managers and above, including C-level positions. + EXECUTIVE = 5; +} + +// An enum that represents the categorization or primary focus of specific +// role. This value is different than the "industry" associated with a role, +// which is related to the categorization of the company listing the job. +enum JobCategory { + // The default value if the category isn't specified. + JOB_CATEGORY_UNSPECIFIED = 0; + + // An accounting and finance job, such as an Accountant. + ACCOUNTING_AND_FINANCE = 1; + + // An administrative and office job, such as an Administrative Assistant. + ADMINISTRATIVE_AND_OFFICE = 2; + + // An advertising and marketing job, such as Marketing Manager. + ADVERTISING_AND_MARKETING = 3; + + // An animal care job, such as Veterinarian. + ANIMAL_CARE = 4; + + // An art, fashion, or design job, such as Designer. + ART_FASHION_AND_DESIGN = 5; + + // A business operations job, such as Business Operations Manager. + BUSINESS_OPERATIONS = 6; + + // A cleaning and facilities job, such as Custodial Staff. + CLEANING_AND_FACILITIES = 7; + + // A computer and IT job, such as Systems Administrator. + COMPUTER_AND_IT = 8; + + // A construction job, such as General Laborer. + CONSTRUCTION = 9; + + // A customer service job, such s Cashier. + CUSTOMER_SERVICE = 10; + + // An education job, such as School Teacher. + EDUCATION = 11; + + // An entertainment and travel job, such as Flight Attendant. + ENTERTAINMENT_AND_TRAVEL = 12; + + // A farming or outdoor job, such as Park Ranger. + FARMING_AND_OUTDOORS = 13; + + // A healthcare job, such as Registered Nurse. + HEALTHCARE = 14; + + // A human resources job, such as Human Resources Director. + HUMAN_RESOURCES = 15; + + // An installation, maintenance, or repair job, such as Electrician. + INSTALLATION_MAINTENANCE_AND_REPAIR = 16; + + // A legal job, such as Law Clerk. + LEGAL = 17; + + // A management job, often used in conjunction with another category, + // such as Store Manager. + MANAGEMENT = 18; + + // A manufacturing or warehouse job, such as Assembly Technician. + MANUFACTURING_AND_WAREHOUSE = 19; + + // A media, communications, or writing job, such as Media Relations. + MEDIA_COMMUNICATIONS_AND_WRITING = 20; + + // An oil, gas or mining job, such as Offshore Driller. + OIL_GAS_AND_MINING = 21; + + // A personal care and services job, such as Hair Stylist. + PERSONAL_CARE_AND_SERVICES = 22; + + // A protective services job, such as Security Guard. + PROTECTIVE_SERVICES = 23; + + // A real estate job, such as Buyer's Agent. + REAL_ESTATE = 24; + + // A restaurant and hospitality job, such as Restaurant Server. + RESTAURANT_AND_HOSPITALITY = 25; + + // A sales and/or retail job, such Sales Associate. + SALES_AND_RETAIL = 26; + + // A science and engineering job, such as Lab Technician. + SCIENCE_AND_ENGINEERING = 27; + + // A social services or non-profit job, such as Case Worker. + SOCIAL_SERVICES_AND_NON_PROFIT = 28; + + // A sports, fitness, or recreation job, such as Personal Trainer. + SPORTS_FITNESS_AND_RECREATION = 29; + + // A transportation or logistics job, such as Truck Driver. + TRANSPORTATION_AND_LOGISTICS = 30; +} + +// An enum that represents the job posting region. In most cases, job postings +// don't need to specify a region. If a region is given, jobs are +// eligible for searches in the specified region. +enum PostingRegion { + // If the region is unspecified, the job is only returned if it + // matches the [LocationFilter][google.cloud.talent.v4beta1.LocationFilter]. + POSTING_REGION_UNSPECIFIED = 0; + + // In addition to exact location matching, job posting is returned when the + // [LocationFilter][google.cloud.talent.v4beta1.LocationFilter] in the search query is in the same administrative area + // as the returned job posting. For example, if a `ADMINISTRATIVE_AREA` job + // is posted in "CA, USA", it's returned if [LocationFilter][google.cloud.talent.v4beta1.LocationFilter] has + // "Mountain View". + // + // Administrative area refers to top-level administrative subdivision of this + // country. For example, US state, IT region, UK constituent nation and + // JP prefecture. + ADMINISTRATIVE_AREA = 1; + + // In addition to exact location matching, job is returned when + // [LocationFilter][google.cloud.talent.v4beta1.LocationFilter] in search query is in the same country as this job. + // For example, if a `NATION_WIDE` job is posted in "USA", it's + // returned if [LocationFilter][google.cloud.talent.v4beta1.LocationFilter] has 'Mountain View'. + NATION = 2; + + // Job allows employees to work remotely (telecommute). + // If [locations][] are provided with this value, the job is + // considered as having a location, but telecommuting is allowed. + TELECOMMUTE = 3; +} + +// An enum that represents who has view access to the resource. +enum Visibility { + // Default value. + VISIBILITY_UNSPECIFIED = 0; + + // The resource is only visible to the GCP account who owns it. + ACCOUNT_ONLY = 1; + + // The resource is visible to the owner and may be visible to other + // applications and processes at Google. + SHARED_WITH_GOOGLE = 2; + + // The resource is visible to the owner and may be visible to all other API + // clients. + SHARED_WITH_PUBLIC = 3; +} + +// Enum that represents the usage of the contact information. +enum ContactInfoUsage { + // Default value. + CONTACT_INFO_USAGE_UNSPECIFIED = 0; + + // Personal use. + PERSONAL = 1; + + // Work use. + WORK = 2; + + // School use. + SCHOOL = 3; +} + +// Input only. +// +// Option for HTML content sanitization on user input fields, for example, job +// description. By setting this option, user can determine whether and how +// sanitization is performed on these fields. +enum HtmlSanitization { + // Default value. + HTML_SANITIZATION_UNSPECIFIED = 0; + + // Disables sanitization on HTML input. + HTML_SANITIZATION_DISABLED = 1; + + // Sanitizes HTML input, only accepts bold, italic, ordered list, and + // unordered list markup tags. + SIMPLE_FORMATTING_ONLY = 2; +} + +// Method for commute. +enum CommuteMethod { + // Commute method isn't specified. + COMMUTE_METHOD_UNSPECIFIED = 0; + + // Commute time is calculated based on driving time. + DRIVING = 1; + + // Commute time is calculated based on public transit including bus, metro, + // subway, and so on. + TRANSIT = 2; + + // Commute time is calculated based on walking time. + WALKING = 3; + + // Commute time is calculated based on biking time. + CYCLING = 4; +} + +// Input only. +// +// Meta information related to the job searcher or entity +// conducting the job search. This information is used to improve the +// performance of the service. +message RequestMetadata { + // Required if [allow_missing_ids][google.cloud.talent.v4beta1.RequestMetadata.allow_missing_ids] is unset or `false`. + // + // The client-defined scope or source of the service call, which typically + // is the domain on + // which the service has been implemented and is currently being run. + // + // For example, if the service is being run by client <em>Foo, Inc.</em>, on + // job board www.foo.com and career site www.bar.com, then this field is + // set to "foo.com" for use on the job board, and "bar.com" for use on the + // career site. + // + // Note that any improvements to the model for a particular tenant site rely + // on this field being set correctly to a unique domain. + // + // The maximum number of allowed characters is 255. + string domain = 1; + + // Required if [allow_missing_ids][google.cloud.talent.v4beta1.RequestMetadata.allow_missing_ids] is unset or `false`. + // + // A unique session identification string. A session is defined as the + // duration of an end user's interaction with the service over a certain + // period. + // Obfuscate this field for privacy concerns before + // providing it to the service. + // + // Note that any improvements to the model for a particular tenant site rely + // on this field being set correctly to a unique session ID. + // + // The maximum number of allowed characters is 255. + string session_id = 2; + + // Required if [allow_missing_ids][google.cloud.talent.v4beta1.RequestMetadata.allow_missing_ids] is unset or `false`. + // + // A unique user identification string, as determined by the client. + // To have the strongest positive impact on search quality + // make sure the client-level is unique. + // Obfuscate this field for privacy concerns before + // providing it to the service. + // + // Note that any improvements to the model for a particular tenant site rely + // on this field being set correctly to a unique user ID. + // + // The maximum number of allowed characters is 255. + string user_id = 3; + + // Optional. + // + // If set to `true`, [domain][google.cloud.talent.v4beta1.RequestMetadata.domain], [session_id][google.cloud.talent.v4beta1.RequestMetadata.session_id] and [user_id][google.cloud.talent.v4beta1.RequestMetadata.user_id] are optional. + // Only set when any of these fields isn't available for some reason. It + // is highly recommended not to set this field and provide accurate + // [domain][google.cloud.talent.v4beta1.RequestMetadata.domain], [session_id][google.cloud.talent.v4beta1.RequestMetadata.session_id] and [user_id][google.cloud.talent.v4beta1.RequestMetadata.user_id] for the best service experience. + bool allow_missing_ids = 4; + + // Optional. + // + // The type of device used by the job seeker at the time of the call to the + // service. + DeviceInfo device_info = 5; +} + +// Output only. +// +// Additional information returned to client, such as debugging information. +message ResponseMetadata { + // A unique id associated with this call. + // This id is logged for tracking purposes. + string request_id = 1; +} + +// Device information collected from the job seeker, candidate, or +// other entity conducting the job search. Providing this information improves +// the quality of the search results across devices. +message DeviceInfo { + // An enumeration describing an API access portal and exposure mechanism. + enum DeviceType { + // The device type isn't specified. + DEVICE_TYPE_UNSPECIFIED = 0; + + // A desktop web browser, such as, Chrome, Firefox, Safari, or Internet + // Explorer) + WEB = 1; + + // A mobile device web browser, such as a phone or tablet with a Chrome + // browser. + MOBILE_WEB = 2; + + // An Android device native application. + ANDROID = 3; + + // An iOS device native application. + IOS = 4; + + // A bot, as opposed to a device operated by human beings, such as a web + // crawler. + BOT = 5; + + // Other devices types. + OTHER = 6; + } + + // Optional. + // + // Type of the device. + DeviceType device_type = 1; + + // Optional. + // + // A device-specific ID. The ID must be a unique identifier that + // distinguishes the device from other devices. + string id = 2; +} + +// Custom attribute values that are either filterable or non-filterable. +message CustomAttribute { + // Optional but exactly one of [string_values][google.cloud.talent.v4beta1.CustomAttribute.string_values] or [long_values][google.cloud.talent.v4beta1.CustomAttribute.long_values] must + // be specified. + // + // This field is used to perform a string match (`CASE_SENSITIVE_MATCH` or + // `CASE_INSENSITIVE_MATCH`) search. + // For filterable `string_value`s, a maximum total number of 200 values + // is allowed, with each `string_value` has a byte size of no more than + // 255B. For unfilterable `string_values`, the maximum total byte size of + // unfilterable `string_values` is 50KB. + // + // Empty string isn't allowed. + repeated string string_values = 1; + + // Optional but exactly one of [string_values][google.cloud.talent.v4beta1.CustomAttribute.string_values] or [long_values][google.cloud.talent.v4beta1.CustomAttribute.long_values] must + // be specified. + // + // This field is used to perform number range search. + // (`EQ`, `GT`, `GE`, `LE`, `LT`) over filterable `long_value`. + // + // Currently at most 1 [long_values][google.cloud.talent.v4beta1.CustomAttribute.long_values] is supported. + repeated int64 long_values = 2; + + // Optional. + // + // If the `filterable` flag is true, custom field values are searchable. + // If false, values are not searchable. + // + // Default is false. + bool filterable = 3; +} + +// Output only. +// +// Spell check result. +message SpellingCorrection { + // Indicates if the query was corrected by the spell checker. + bool corrected = 1; + + // Correction output consisting of the corrected keyword string. + string corrected_text = 2; + + // Corrected output with html tags to highlight the corrected words. + // Corrected words are called out with the "<b><i>...</i></b>" html tags. + // + // For example, the user input query is "software enginear", where the second + // word, "enginear," is incorrect. It should be "engineer". When spelling + // correction is enabled, this value is + // "software <b><i>engineer</i></b>". + string corrected_html = 3; +} + +// Job compensation details. +message CompensationInfo { + // A compensation entry that represents one component of compensation, such + // as base pay, bonus, or other compensation type. + // + // Annualization: One compensation entry can be annualized if + // - it contains valid [amount][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.amount] or [range][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.range]. + // - and its [expected_units_per_year][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.expected_units_per_year] is set or can be derived. + // Its annualized range is determined as ([amount][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.amount] or [range][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.range]) times + // [expected_units_per_year][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.expected_units_per_year]. + message CompensationEntry { + // Optional. + // + // Compensation type. + // + // Default is [CompensationUnit.OTHER_COMPENSATION_TYPE][]. + CompensationType type = 1; + + // Optional. + // + // Frequency of the specified amount. + // + // Default is [CompensationUnit.OTHER_COMPENSATION_UNIT][google.cloud.talent.v4beta1.CompensationInfo.CompensationUnit.OTHER_COMPENSATION_UNIT]. + CompensationUnit unit = 2; + + // Optional. + // + // Compensation amount. It could be a fixed amount or a floating range. + oneof compensation_amount { + // Optional. + // + // Compensation amount. + google.type.Money amount = 3; + + // Optional. + // + // Compensation range. + CompensationRange range = 4; + } + + // Optional. + // + // Compensation description. For example, could + // indicate equity terms or provide additional context to an estimated + // bonus. + string description = 5; + + // Optional. + // + // Expected number of units paid each year. If not specified, when + // [Job.employment_types][google.cloud.talent.v4beta1.Job.employment_types] is FULLTIME, a default value is inferred + // based on [unit][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.unit]. Default values: + // - HOURLY: 2080 + // - DAILY: 260 + // - WEEKLY: 52 + // - MONTHLY: 12 + // - ANNUAL: 1 + google.protobuf.DoubleValue expected_units_per_year = 6; + } + + // Compensation range. + message CompensationRange { + // Optional. + // + // The maximum amount of compensation. If left empty, the value is set + // to a maximal compensation value and the currency code is set to + // match the [currency code][google.type.Money.currency_code] of + // min_compensation. + google.type.Money max_compensation = 2; + + // Optional. + // + // The minimum amount of compensation. If left empty, the value is set + // to zero and the currency code is set to match the + // [currency code][google.type.Money.currency_code] of max_compensation. + google.type.Money min_compensation = 1; + } + + // The type of compensation. + // + // For compensation amounts specified in non-monetary amounts, + // describe the compensation scheme in the [CompensationEntry.description][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.description]. + // + // For example, tipping format is described in + // [CompensationEntry.description][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.description] (for example, "expect 15-20% tips based + // on customer bill.") and an estimate of the tips provided in + // [CompensationEntry.amount][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.amount] or [CompensationEntry.range][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.range] ($10 per hour). + // + // For example, equity is described in [CompensationEntry.description][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.description] + // (for example, "1% - 2% equity vesting over 4 years, 1 year cliff") and + // value estimated in [CompensationEntry.amount][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.amount] or + // [CompensationEntry.range][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.range]. If no value estimate is possible, units are + // [CompensationUnit.COMPENSATION_UNIT_UNSPECIFIED][google.cloud.talent.v4beta1.CompensationInfo.CompensationUnit.COMPENSATION_UNIT_UNSPECIFIED] and then further + // clarified in [CompensationEntry.description][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.description] field. + enum CompensationType { + // Default value. + COMPENSATION_TYPE_UNSPECIFIED = 0; + + // Base compensation: Refers to the fixed amount of money paid to an + // employee by an employer in return for work performed. Base compensation + // does not include benefits, bonuses or any other potential compensation + // from an employer. + BASE = 1; + + // Bonus. + BONUS = 2; + + // Signing bonus. + SIGNING_BONUS = 3; + + // Equity. + EQUITY = 4; + + // Profit sharing. + PROFIT_SHARING = 5; + + // Commission. + COMMISSIONS = 6; + + // Tips. + TIPS = 7; + + // Other compensation type. + OTHER_COMPENSATION_TYPE = 8; + } + + // Pay frequency. + enum CompensationUnit { + // Default value. + COMPENSATION_UNIT_UNSPECIFIED = 0; + + // Hourly. + HOURLY = 1; + + // Daily. + DAILY = 2; + + // Weekly + WEEKLY = 3; + + // Monthly. + MONTHLY = 4; + + // Yearly. + YEARLY = 5; + + // One time. + ONE_TIME = 6; + + // Other compensation units. + OTHER_COMPENSATION_UNIT = 7; + } + + // Optional. + // + // Job compensation information. + // + // At most one entry can be of type + // [CompensationInfo.CompensationType.BASE][google.cloud.talent.v4beta1.CompensationInfo.CompensationType.BASE], which is + // referred as ** base compensation entry ** for the job. + repeated CompensationEntry entries = 1; + + // Output only. Annualized base compensation range. Computed as + // base compensation entry's [CompensationEntry.compensation][] times + // [CompensationEntry.expected_units_per_year][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.expected_units_per_year]. + // + // See [CompensationEntry][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry] for explanation on compensation annualization. + CompensationRange annualized_base_compensation_range = 2; + + // Output only. Annualized total compensation range. Computed as + // all compensation entries' [CompensationEntry.compensation][] times + // [CompensationEntry.expected_units_per_year][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry.expected_units_per_year]. + // + // See [CompensationEntry][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry] for explanation on compensation annualization. + CompensationRange annualized_total_compensation_range = 3; +} + +// Resource that represents a license or certification. +message Certification { + // Optional. + // + // Name of license or certification. + // + // Number of characters allowed is 100. + string display_name = 1; + + // Optional. + // + // Acquisition date or effective date of license or certification. + google.type.Date acquire_date = 2; + + // Optional. + // + // Expiration date of license of certification. + google.type.Date expire_date = 3; + + // Optional. + // + // Authority of license, such as government. + // + // Number of characters allowed is 100. + string authority = 4; + + // Optional. + // + // Description of license or certification. + // + // Number of characters allowed is 100,000. + string description = 5; +} + +// Resource that represents a skill of a candidate. +message Skill { + // Optional. + // + // Skill display name. + // + // For example, "Java", "Python". + // + // Number of characters allowed is 100. + string display_name = 1; + + // Optional. + // + // The last time this skill was used. + google.type.Date last_used_date = 2; + + // Optional. + // + // Skill proficiency level which indicates how proficient the candidate is at + // this skill. + SkillProficiencyLevel level = 3; + + // Optional. + // + // A paragraph describes context of this skill. + // + // Number of characters allowed is 100,000. + string context = 4; + + // Output only. Skill name snippet shows how the [display_name][google.cloud.talent.v4beta1.Skill.display_name] is related + // to a search query. It's empty if the [display_name][google.cloud.talent.v4beta1.Skill.display_name] isn't related to the + // search query. + string skill_name_snippet = 5; +} + +// Details of an interview. +message Interview { + // Optional. + // + // The rating on this interview. + Rating rating = 6; + + // Required. + // + // The overall decision resulting from this interview (positive, negative, + // nuetral). + Outcome outcome = 7; +} + +// The details of the score received for an assessment or interview. +message Rating { + // Overall score. + double overall = 1; + + // The minimum value for the score. + double min = 2; + + // The maximum value for the score. + double max = 3; + + // The steps within the score (for example, interval = 1 max = 5 + // min = 1 indicates that the score can be 1, 2, 3, 4, or 5) + double interval = 4; +} + +// Enum that represents the skill proficiency level. +enum SkillProficiencyLevel { + // Default value. + SKILL_PROFICIENCY_LEVEL_UNSPECIFIED = 0; + + // Have a common knowledge or an understanding of basic techniques and + // concepts. + FUNDAMENTAL_AWARENESS = 1; + + // Have the level of experience gained in a classroom and/or experimental + // scenarios or as a trainee on-the-job. + NOVICE = 2; + + // Be able to successfully complete tasks in this skill as requested. Help + // from an expert may be required from time to time, but can usually perform + // skill independently. + INTERMEDIATE = 3; + + // Can perform the actions associated with this skill without assistance. + ADVANCED = 4; + + // Known as an expert in this area. + EXPERT = 5; +} + +// The overall outcome /decision / result indicator. +enum Outcome { + // Default value. + OUTCOME_UNSPECIFIED = 0; + + // A positive outcome / passing indicator (for example, candidate was + // recommended for hiring or to be moved forward in the hiring process, + // candidate passed a test). + POSITIVE = 1; + + // A neutral outcome / no clear indicator (for example, no strong + // reccommendation either to move forward / not move forward, neutral score). + NEUTRAL = 2; + + // A negative outcome / failing indicator (for example, candidate was + // recommended to NOT move forward in the hiring process, failed a test). + NEGATIVE = 3; + + // The assessment outcome is not available or otherwise unknown (for example, + // candidate did not complete assessment). + OUTCOME_NOT_AVAILABLE = 4; +} diff --git a/google/cloud/talent/v4beta1/company.proto b/google/cloud/talent/v4beta1/company.proto new file mode 100644 index 000000000..199df88b3 --- /dev/null +++ b/google/cloud/talent/v4beta1/company.proto @@ -0,0 +1,132 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/cloud/talent/v4beta1/common.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "CompanyResourceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A Company resource represents a company in the service. A company is the +// entity that owns job postings, that is, the hiring entity responsible for +// employing applicants for the job position. +message Company { + // Derived details about the company. + message DerivedInfo { + // A structured headquarters location of the company, resolved from + // [Company.hq_location][] if provided. + Location headquarters_location = 1; + } + + // Required during company update. + // + // The resource name for a company. This is generated by the service when a + // company is created. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for + // example, "projects/api-test-project/tenants/foo/companies/bar". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/companies/bar". + string name = 1; + + // Required. + // + // The display name of the company, for example, "Google, LLC". + string display_name = 2; + + // Required. + // + // Client side company identifier, used to uniquely identify the + // company. + // + // The maximum number of allowed characters is 255. + string external_id = 3; + + // Optional. + // + // The employer's company size. + CompanySize size = 4; + + // Optional. + // + // The street address of the company's main headquarters, which may be + // different from the job location. The service attempts + // to geolocate the provided address, and populates a more specific + // location wherever possible in [DerivedInfo.headquarters_location][google.cloud.talent.v4beta1.Company.DerivedInfo.headquarters_location]. + string headquarters_address = 5; + + // Optional. + // + // Set to true if it is the hiring agency that post jobs for other + // employers. + // + // Defaults to false if not provided. + bool hiring_agency = 6; + + // Optional. + // + // Equal Employment Opportunity legal disclaimer text to be + // associated with all jobs, and typically to be displayed in all + // roles. + // + // The maximum number of allowed characters is 500. + string eeo_text = 7; + + // Optional. + // + // The URI representing the company's primary web site or home page, + // for example, "https://www.google.com". + // + // The maximum number of allowed characters is 255. + string website_uri = 8; + + // Optional. + // + // The URI to employer's career site or careers page on the employer's web + // site, for example, "https://careers.google.com". + string career_site_uri = 9; + + // Optional. + // + // A URI that hosts the employer's company logo. + string image_uri = 10; + + // Optional. + // + // A list of keys of filterable [Job.custom_attributes][google.cloud.talent.v4beta1.Job.custom_attributes], whose + // corresponding `string_values` are used in keyword searches. Jobs with + // `string_values` under these specified field keys are returned if any + // of the values match the search keyword. Custom field values with + // parenthesis, brackets and special symbols are not searchable as-is, + // and those keyword queries must be surrounded by quotes. + repeated string keyword_searchable_job_custom_attributes = 11; + + // Output only. Derived details about the company. + DerivedInfo derived_info = 12; + + // Output only. Indicates whether a company is flagged to be suspended from + // public availability by the service when job content appears suspicious, + // abusive, or spammy. + bool suspended = 13; +} diff --git a/google/cloud/talent/v4beta1/company_service.proto b/google/cloud/talent/v4beta1/company_service.proto new file mode 100644 index 000000000..8af4b9ad4 --- /dev/null +++ b/google/cloud/talent/v4beta1/company_service.proto @@ -0,0 +1,205 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/common.proto"; +import "google/cloud/talent/v4beta1/company.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "CompanyServiceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A service that handles company management, including CRUD and enumeration. +service CompanyService { + // Creates a new company entity. + rpc CreateCompany(CreateCompanyRequest) returns (Company) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}/companies" + body: "*" + additional_bindings { + post: "/v4beta1/{parent=projects/*}/companies" + body: "*" + } + }; + } + + // Retrieves specified company. + rpc GetCompany(GetCompanyRequest) returns (Company) { + option (google.api.http) = { + get: "/v4beta1/{name=projects/*/tenants/*/companies/*}" + additional_bindings { + get: "/v4beta1/{name=projects/*/companies/*}" + } + }; + } + + // Updates specified company. + rpc UpdateCompany(UpdateCompanyRequest) returns (Company) { + option (google.api.http) = { + patch: "/v4beta1/{company.name=projects/*/tenants/*/companies/*}" + body: "*" + additional_bindings { + patch: "/v4beta1/{company.name=projects/*/companies/*}" + body: "*" + } + }; + } + + // Deletes specified company. + // Prerequisite: The company has no jobs associated with it. + rpc DeleteCompany(DeleteCompanyRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v4beta1/{name=projects/*/tenants/*/companies/*}" + additional_bindings { + delete: "/v4beta1/{name=projects/*/companies/*}" + } + }; + } + + // Lists all companies associated with the project. + rpc ListCompanies(ListCompaniesRequest) returns (ListCompaniesResponse) { + option (google.api.http) = { + get: "/v4beta1/{parent=projects/*/tenants/*}/companies" + additional_bindings { + get: "/v4beta1/{parent=projects/*}/companies" + } + }; + } +} + +// The Request of the CreateCompany method. +message CreateCompanyRequest { + // Required. + // + // Resource name of the tenant under which the company is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and a default tenant is created if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Required. + // + // The company to be created. + Company company = 2; +} + +// Request for getting a company by name. +message GetCompanyRequest { + // Required. + // + // The resource name of the company to be retrieved. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for + // example, "projects/api-test-project/tenants/foo/companies/bar". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/companies/bar". + string name = 1; +} + +// Request for updating a specified company. +message UpdateCompanyRequest { + // Required. + // + // The company resource to replace the current resource in the system. + Company company = 1; + + // Optional but strongly recommended for the best service + // experience. + // + // If [update_mask][google.cloud.talent.v4beta1.UpdateCompanyRequest.update_mask] is provided, only the specified fields in + // [company][google.cloud.talent.v4beta1.UpdateCompanyRequest.company] are updated. Otherwise all the fields are updated. + // + // A field mask to specify the company fields to be updated. Only + // top level fields of [Company][google.cloud.talent.v4beta1.Company] are supported. + google.protobuf.FieldMask update_mask = 2; +} + +// Request to delete a company. +message DeleteCompanyRequest { + // Required. + // + // The resource name of the company to be deleted. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for + // example, "projects/api-test-project/tenants/foo/companies/bar". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/companies/bar". + string name = 1; +} + +// List companies for which the client has ACL visibility. +message ListCompaniesRequest { + // Required. + // + // Resource name of the tenant under which the company is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Optional. + // + // The starting indicator from which to return results. + string page_token = 2; + + // Optional. + // + // The maximum number of companies to be returned, at most 100. + // Default is 100 if a non-positive number is provided. + int32 page_size = 3; + + // Optional. + // + // Set to true if the companies requested must have open jobs. + // + // Defaults to false. + // + // If true, at most [page_size][google.cloud.talent.v4beta1.ListCompaniesRequest.page_size] of companies are fetched, among which + // only those with open jobs are returned. + bool require_open_jobs = 4; +} + +// Output only. +// +// The List companies response object. +message ListCompaniesResponse { + // Companies for the current client. + repeated Company companies = 1; + + // A token to retrieve the next page of results. + string next_page_token = 2; + + // Additional information for the API invocation, such as the request + // tracking id. + ResponseMetadata metadata = 3; +} diff --git a/google/cloud/talent/v4beta1/completion_service.proto b/google/cloud/talent/v4beta1/completion_service.proto new file mode 100644 index 000000000..139e1e8ee --- /dev/null +++ b/google/cloud/talent/v4beta1/completion_service.proto @@ -0,0 +1,168 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/common.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "CompletionServiceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A service handles auto completion. +service Completion { + // Completes the specified prefix with keyword suggestions. + // Intended for use by a job search auto-complete search box. + rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) { + option (google.api.http) = { + get: "/v4beta1/{parent=projects/*/tenants/*}:complete" + additional_bindings { + get: "/v4beta1/{parent=projects/*}:complete" + } + }; + } +} + +// Input only. +// +// Auto-complete parameters. +message CompleteQueryRequest { + // Enum to specify the scope of completion. + enum CompletionScope { + // Default value. + COMPLETION_SCOPE_UNSPECIFIED = 0; + + // Suggestions are based only on the data provided by the client. + TENANT = 1; + + // Suggestions are based on all jobs data in the system that's visible to + // the client + PUBLIC = 2; + } + + // Enum to specify auto-completion topics. + enum CompletionType { + // Default value. + COMPLETION_TYPE_UNSPECIFIED = 0; + + // Only suggest job titles. + JOB_TITLE = 1; + + // Only suggest company names. + COMPANY_NAME = 2; + + // Suggest both job titles and company names. + COMBINED = 3; + } + + // Required. + // + // Resource name of tenant the completion is performed within. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Required. + // + // The query used to generate suggestions. + // + // The maximum number of allowed characters is 255. + string query = 2; + + // Optional. + // + // The list of languages of the query. This is + // the BCP-47 language code, such as "en-US" or "sr-Latn". + // For more information, see + // [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47). + // + // For [CompletionType.JOB_TITLE][google.cloud.talent.v4beta1.CompleteQueryRequest.CompletionType.JOB_TITLE] type, only open jobs with the same + // [language_codes][google.cloud.talent.v4beta1.CompleteQueryRequest.language_codes] are returned. + // + // For [CompletionType.COMPANY_NAME][google.cloud.talent.v4beta1.CompleteQueryRequest.CompletionType.COMPANY_NAME] type, + // only companies having open jobs with the same [language_codes][google.cloud.talent.v4beta1.CompleteQueryRequest.language_codes] are + // returned. + // + // For [CompletionType.COMBINED][google.cloud.talent.v4beta1.CompleteQueryRequest.CompletionType.COMBINED] type, only open jobs with the same + // [language_codes][google.cloud.talent.v4beta1.CompleteQueryRequest.language_codes] or companies having open jobs with the same + // [language_codes][google.cloud.talent.v4beta1.CompleteQueryRequest.language_codes] are returned. + // + // The maximum number of allowed characters is 255. + repeated string language_codes = 3; + + // Required. + // + // Completion result count. + // + // The maximum allowed page size is 10. + int32 page_size = 4; + + // Optional. + // + // If provided, restricts completion to specified company. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for + // example, "projects/api-test-project/tenants/foo/companies/bar". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/companies/bar". + string company = 5; + + // Optional. + // + // The scope of the completion. The defaults is [CompletionScope.PUBLIC][google.cloud.talent.v4beta1.CompleteQueryRequest.CompletionScope.PUBLIC]. + CompletionScope scope = 6; + + // Optional. + // + // The completion topic. The default is [CompletionType.COMBINED][google.cloud.talent.v4beta1.CompleteQueryRequest.CompletionType.COMBINED]. + CompletionType type = 7; +} + +// Output only. +// +// Response of auto-complete query. +message CompleteQueryResponse { + // Output only. + // + // Resource that represents completion results. + message CompletionResult { + // The suggestion for the query. + string suggestion = 1; + + // The completion topic. + CompleteQueryRequest.CompletionType type = 2; + + // The URI of the company image for [CompletionType.COMPANY_NAME][]. + string image_uri = 3; + } + + // Results of the matching job/company candidates. + repeated CompletionResult completion_results = 1; + + // Additional information for the API invocation, such as the request + // tracking id. + ResponseMetadata metadata = 2; +} diff --git a/google/cloud/talent/v4beta1/event.proto b/google/cloud/talent/v4beta1/event.proto new file mode 100644 index 000000000..74df4336c --- /dev/null +++ b/google/cloud/talent/v4beta1/event.proto @@ -0,0 +1,223 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "EventProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// An event issued when an end user interacts with the application that +// implements Cloud Talent Solution. Providing this information improves the +// quality of search and recommendation for the API clients, enabling the +// service to perform optimally. The number of events sent must be consistent +// with other calls, such as job searches, issued to the service by the client. +message ClientEvent { + // Required. + // + // A unique ID generated in the API responses. It can be found in + // [ResponseMetadata.request_id][google.cloud.talent.v4beta1.ResponseMetadata.request_id]. + string request_id = 1; + + // Required. + // + // A unique identifier, generated by the client application. + string event_id = 2; + + // Required. + // + // The timestamp of the event. + google.protobuf.Timestamp create_time = 4; + + // Required. + // + // The detail information of a specific event type. + oneof event { + // An event issued when a job seeker interacts with the application that + // implements Cloud Talent Solution. + JobEvent job_event = 5; + + // An event issued when a profile searcher interacts with the application + // that implements Cloud Talent Solution. + ProfileEvent profile_event = 6; + } + + // Optional. + // + // Notes about the event provided by recruiters or other users, for example, + // feedback on why a profile was bookmarked. + string event_notes = 9; +} + +// An event issued when a job seeker interacts with the application that +// implements Cloud Talent Solution. +message JobEvent { + // An enumeration of an event attributed to the behavior of the end user, + // such as a job seeker. + enum JobEventType { + // The event is unspecified by other provided values. + JOB_EVENT_TYPE_UNSPECIFIED = 0; + + // The job seeker or other entity interacting with the service has + // had a job rendered in their view, such as in a list of search results in + // a compressed or clipped format. This event is typically associated with + // the viewing of a jobs list on a single page by a job seeker. + IMPRESSION = 1; + + // The job seeker, or other entity interacting with the service, has + // viewed the details of a job, including the full description. This + // event doesn't apply to the viewing a snippet of a job appearing as a + // part of the job search results. Viewing a snippet is associated with an + // [impression][google.cloud.talent.v4beta1.JobEvent.JobEventType.IMPRESSION]). + VIEW = 2; + + // The job seeker or other entity interacting with the service + // performed an action to view a job and was redirected to a different + // website for job. + VIEW_REDIRECT = 3; + + // The job seeker or other entity interacting with the service + // began the process or demonstrated the intention of applying for a job. + APPLICATION_START = 4; + + // The job seeker or other entity interacting with the service + // submitted an application for a job. + APPLICATION_FINISH = 5; + + // The job seeker or other entity interacting with the service + // submitted an application for a job with a single click without + // entering information. If a job seeker performs this action, send only + // this event to the service. Do not also send + // [JobEventType.APPLICATION_START][google.cloud.talent.v4beta1.JobEvent.JobEventType.APPLICATION_START] or [JobEventType.APPLICATION_FINISH][google.cloud.talent.v4beta1.JobEvent.JobEventType.APPLICATION_FINISH] + // events. + APPLICATION_QUICK_SUBMISSION = 6; + + // The job seeker or other entity interacting with the service + // performed an action to apply to a job and was redirected to a different + // website to complete the application. + APPLICATION_REDIRECT = 7; + + // The job seeker or other entity interacting with the service began the + // process or demonstrated the intention of applying for a job from the + // search results page without viewing the details of the job posting. + // If sending this event, JobEventType.VIEW event shouldn't be sent. + APPLICATION_START_FROM_SEARCH = 8; + + // The job seeker, or other entity interacting with the service, performs an + // action with a single click from the search results page to apply to a job + // (without viewing the details of the job posting), and is redirected + // to a different website to complete the application. If a candidate + // performs this action, send only this event to the service. Do not also + // send [JobEventType.APPLICATION_START][google.cloud.talent.v4beta1.JobEvent.JobEventType.APPLICATION_START], + // [JobEventType.APPLICATION_FINISH][google.cloud.talent.v4beta1.JobEvent.JobEventType.APPLICATION_FINISH] or [JobEventType.VIEW][google.cloud.talent.v4beta1.JobEvent.JobEventType.VIEW] events. + APPLICATION_REDIRECT_FROM_SEARCH = 9; + + // This event should be used when a company submits an application + // on behalf of a job seeker. This event is intended for use by staffing + // agencies attempting to place candidates. + APPLICATION_COMPANY_SUBMIT = 10; + + // The job seeker or other entity interacting with the service demonstrated + // an interest in a job by bookmarking or saving it. + BOOKMARK = 11; + + // The job seeker or other entity interacting with the service was + // sent a notification, such as an email alert or device notification, + // containing one or more jobs listings generated by the service. + NOTIFICATION = 12; + + // The job seeker or other entity interacting with the service was + // employed by the hiring entity (employer). Send this event + // only if the job seeker was hired through an application that was + // initiated by a search conducted through the Cloud Talent Solution + // service. + HIRED = 13; + + // A recruiter or staffing agency submitted an application on behalf of the + // candidate after interacting with the service to identify a suitable job + // posting. + SENT_CV = 14; + + // The entity interacting with the service (for example, the job seeker), + // was granted an initial interview by the hiring entity (employer). This + // event should only be sent if the job seeker was granted an interview as + // part of an application that was initiated by a search conducted through / + // recommendation provided by the Cloud Talent Solution service. + INTERVIEW_GRANTED = 15; + + // The job seeker or other entity interacting with the service showed + // no interest in the job. + NOT_INTERESTED = 16; + } + + // Required. + // + // The type of the event (see [JobEventType][google.cloud.talent.v4beta1.JobEvent.JobEventType]). + JobEventType type = 1; + + // Required. + // + // The [job name(s)][google.cloud.talent.v4beta1.Job.name] associated with this event. + // For example, if this is an [impression][google.cloud.talent.v4beta1.JobEvent.JobEventType.IMPRESSION] event, + // this field contains the identifiers of all jobs shown to the job seeker. + // If this was a [view][google.cloud.talent.v4beta1.JobEvent.JobEventType.VIEW] event, this field contains the + // identifier of the viewed job. + repeated string jobs = 2; +} + +// An event issued when a profile searcher interacts with the application +// that implements Cloud Talent Solution. +message ProfileEvent { + // The enum represents types of client events for a candidate profile. + enum ProfileEventType { + // Default value. + PROFILE_EVENT_TYPE_UNSPECIFIED = 0; + + // The profile is displayed. + IMPRESSION = 1; + + // The profile is viewed. + VIEW = 2; + + // The profile is bookmarked. + BOOKMARK = 3; + } + + // Required. + // + // Type of event. + ProfileEventType type = 1; + + // Required. + // + // The [profile name(s)][google.cloud.talent.v4beta1.Profile.name] associated with this client event. + repeated string profiles = 2; + + // Optional. + // + // The job ID associated with this client event if there is one. Leave it + // empty if the event isn't associated with a job. + // + // The job ID should be consistent with the + // [JobApplication.job.requisition_id][] in the profile. + repeated string jobs = 6; +} diff --git a/google/cloud/talent/v4beta1/event_service.proto b/google/cloud/talent/v4beta1/event_service.proto new file mode 100644 index 000000000..d456336d9 --- /dev/null +++ b/google/cloud/talent/v4beta1/event_service.proto @@ -0,0 +1,68 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/event.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "EventServiceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A service handles client event report. +service EventService { + // Report events issued when end user interacts with customer's application + // that uses Cloud Talent Solution. You may inspect the created events in + // [self service + // tools](https://console.cloud.google.com/talent-solution/overview). + // [Learn + // more](https://cloud.google.com/talent-solution/docs/management-tools) + // about self service tools. + rpc CreateClientEvent(CreateClientEventRequest) returns (ClientEvent) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}/clientEvents" + body: "*" + additional_bindings { + post: "/v4beta1/{parent=projects/*}/clientEvents" + body: "*" + } + }; + } +} + +// The report event request. +message CreateClientEventRequest { + // Required. + // + // Resource name of the tenant under which the event is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and a default tenant is created if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Required. + // + // Events issued when end user interacts with customer's application that + // uses Cloud Talent Solution. + ClientEvent client_event = 2; +} diff --git a/google/cloud/talent/v4beta1/filters.proto b/google/cloud/talent/v4beta1/filters.proto new file mode 100644 index 000000000..4a8ae540d --- /dev/null +++ b/google/cloud/talent/v4beta1/filters.proto @@ -0,0 +1,782 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/cloud/talent/v4beta1/application.proto"; +import "google/cloud/talent/v4beta1/common.proto"; +import "google/cloud/talent/v4beta1/job.proto"; +import "google/cloud/talent/v4beta1/profile.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "google/type/date.proto"; +import "google/type/latlng.proto"; +import "google/type/timeofday.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "FiltersProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// Input only. +// +// The query required to perform a search query. +message JobQuery { + // Optional. + // + // The query string that matches against the job title, description, and + // location fields. + // + // The maximum number of allowed characters is 255. + string query = 1; + + // Optional. + // + // This filter specifies the company entities to search against. + // + // If a value isn't specified, jobs are searched for against all + // companies. + // + // If multiple values are specified, jobs are searched against the + // companies specified. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for + // example, "projects/api-test-project/tenants/foo/companies/bar". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/companies/bar". + // + // At most 20 company filters are allowed. + repeated string companies = 2; + + // Optional. + // + // The location filter specifies geo-regions containing the jobs to + // search against. See [LocationFilter][google.cloud.talent.v4beta1.LocationFilter] for more information. + // + // If a location value isn't specified, jobs fitting the other search + // criteria are retrieved regardless of where they're located. + // + // If multiple values are specified, jobs are retrieved from any of the + // specified locations. If different values are specified for the + // [LocationFilter.distance_in_miles][google.cloud.talent.v4beta1.LocationFilter.distance_in_miles] parameter, the maximum provided + // distance is used for all locations. + // + // At most 5 location filters are allowed. + repeated LocationFilter location_filters = 3; + + // Optional. + // + // The category filter specifies the categories of jobs to search against. + // See [Category][] for more information. + // + // If a value isn't specified, jobs from any category are searched against. + // + // If multiple values are specified, jobs from any of the specified + // categories are searched against. + repeated JobCategory job_categories = 4; + + // Optional. + // + // Allows filtering jobs by commute time with different travel methods (for + // example, driving or public transit). Note: This only works with [COMMUTE + // MODE][Mode#COMMUTE]. When specified, [JobQuery.location_filters] is + // ignored. + // + // Currently we don't support sorting by commute time. + CommuteFilter commute_filter = 5; + + // Optional. + // + // This filter specifies the exact [company display + // name][Company.display_name] of the jobs to search against. + // + // If a value isn't specified, jobs within the search results are + // associated with any company. + // + // If multiple values are specified, jobs within the search results may be + // associated with any of the specified companies. + // + // At most 20 company display name filters are allowed. + repeated string company_display_names = 6; + + // Optional. + // + // This search filter is applied only to + // [Job.compensation_info][google.cloud.talent.v4beta1.Job.compensation_info]. For example, if the filter is specified + // as "Hourly job with per-hour compensation > $15", only jobs meeting + // these criteria are searched. If a filter isn't defined, all open jobs + // are searched. + CompensationFilter compensation_filter = 7; + + // Optional. + // + // This filter specifies a structured syntax to match against the + // [Job.custom_attributes][google.cloud.talent.v4beta1.Job.custom_attributes] marked as `filterable`. + // + // The syntax for this expression is a subset of SQL syntax. + // + // Supported operators are: `=`, `!=`, `<`, `<=`, `>`, and `>=` where the + // left of the operator is a custom field key and the right of the operator + // is a number or a quoted string. You must escape backslash (\\) and + // quote (\") characters. + // + // Supported functions are `LOWER([field_name])` to + // perform a case insensitive match and `EMPTY([field_name])` to filter on the + // existence of a key. + // + // Boolean expressions (AND/OR/NOT) are supported up to 3 levels of + // nesting (for example, "((A AND B AND C) OR NOT D) AND E"), a maximum of 100 + // comparisons or functions are allowed in the expression. The expression + // must be < 3000 bytes in length. + // + // Sample Query: + // `(LOWER(driving_license)="class \"a\"" OR EMPTY(driving_license)) AND + // driving_years > 10` + string custom_attribute_filter = 8; + + // Optional. + // + // This flag controls the spell-check feature. If false, the + // service attempts to correct a misspelled query, + // for example, "enginee" is corrected to "engineer". + // + // Defaults to false: a spell check is performed. + bool disable_spell_check = 9; + + // Optional. + // + // The employment type filter specifies the employment type of jobs to + // search against, such as [EmploymentType.FULL_TIME][google.cloud.talent.v4beta1.EmploymentType.FULL_TIME]. + // + // If a value isn't specified, jobs in the search results includes any + // employment type. + // + // If multiple values are specified, jobs in the search results include + // any of the specified employment types. + repeated EmploymentType employment_types = 10; + + // Optional. + // + // This filter specifies the locale of jobs to search against, + // for example, "en-US". + // + // If a value isn't specified, the search results can contain jobs in any + // locale. + // + // + // Language codes should be in BCP-47 format, such as "en-US" or "sr-Latn". + // For more information, see + // [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47). + // + // At most 10 language code filters are allowed. + repeated string language_codes = 11; + + // Optional. + // + // Jobs published within a range specified by this filter are searched + // against. + TimestampRange publish_time_range = 12; + + // Optional. + // + // This filter specifies a list of job names to be excluded during search. + // + // At most 200 excluded job names are allowed. + repeated string excluded_jobs = 13; +} + +// Filters to apply when performing the search query. +message ProfileQuery { + // Optional. + // + // Keywords to match any text fields of profiles. + // + // For example, "software engineer in Palo Alto". + string query = 1; + + // Optional. + // + // The location filter specifies geo-regions containing the profiles to + // search against. + // + // If a location filter isn't specified, profiles fitting the other search + // criteria are retrieved regardless of where they're located. + // + // If [LocationFilter.negated][google.cloud.talent.v4beta1.LocationFilter.negated] is specified, the result doesn't contain + // profiles from that location. + // + // For example, search for profiles with addresses in "New York City". + repeated LocationFilter location_filters = 2; + + // Optional. + // + // Job title filter specifies job titles of profiles to match on. + // + // If a job title isn't specified, profiles with any titles are retrieved. + // + // If multiple values are specified, profiles are retrieved with any of the + // specified job titles. + // + // If [JobTitleFilter.negated][google.cloud.talent.v4beta1.JobTitleFilter.negated] is specified, the result won't contain + // profiles with the job titles. + // + // For example, search for profiles with a job title "Product Manager". + repeated JobTitleFilter job_title_filters = 3; + + // Optional. + // + // Employer filter specifies employers of profiles to match on. + // + // If an employer filter isn't specified, profiles with any employers are + // retrieved. + // + // If multiple employer filters are specified, profiles with any matching + // employers are retrieved. + // + // If [EmployerFilter.negated][google.cloud.talent.v4beta1.EmployerFilter.negated] is specified, the result won't contain + // profiles that match the employers. + // + // For example, search for profiles that have working experience at "Google + // LLC". + repeated EmployerFilter employer_filters = 4; + + // Optional. + // + // Education filter specifies education of profiles to match on. + // + // If an education filter isn't specified, profiles with any education are + // retrieved. + // + // If multiple education filters are specified, profiles that match any + // education filters are retrieved. + // + // If [EducationFilter.negated][google.cloud.talent.v4beta1.EducationFilter.negated] is specified, the result won't contain + // profiles that match the educations. + // + // For example, search for profiles with a master degree. + repeated EducationFilter education_filters = 5; + + // Optional. + // + // Skill filter specifies skill of profiles to match on. + // + // If a skill filter isn't specified, profiles with any skills are retrieved. + // + // If multiple skill filters are specified, profiles that match any skill + // filters are retrieved. + // + // If [SkillFilter.negated][google.cloud.talent.v4beta1.SkillFilter.negated] is specified, the result won't contain profiles + // that match the skills. + // + // For example, search for profiles that have "Java" and "Python" in skill + // list. + repeated SkillFilter skill_filters = 6; + + // Optional. + // + // Work experience filter specifies the total working experience of profiles + // to match on. + // + // If a work experience filter isn't specified, profiles with any + // professional experience are retrieved. + // + // If multiple work experience filters are specified, profiles that match any + // work experience filters are retrieved. + // + // For example, search for profiles with 10 years of work experience. + repeated WorkExperienceFilter work_experience_filter = 7; + + // Optional. + // + // Time filter specifies the create/update timestamp of the profiles to match + // on. + // + // For example, search for profiles created since "2018-1-1". + repeated TimeFilter time_filters = 8; + + // Optional. + // + // The hirable filter specifies the profile's hirable status to match on. + google.protobuf.BoolValue hirable_filter = 9; + + // Optional. + // + // The application date filters specify application date ranges to match on. + repeated ApplicationDateFilter application_date_filters = 10; + + // Optional. + // + // The application outcome notes filters specify the notes for the outcome of + // the job application. + repeated ApplicationOutcomeNotesFilter application_outcome_notes_filters = 11; + + // Optional. + // + // The application job filters specify the job applied for in the application. + repeated ApplicationJobFilter application_job_filters = 13; + + // Optional. + // + // This filter specifies a structured syntax to match against the + // [Profile.custom_attributes][google.cloud.talent.v4beta1.Profile.custom_attributes] that are marked as `filterable`. + // + // The syntax for this expression is a subset of Google SQL syntax. + // + // String custom attributes: supported operators are =, != where the left of + // the operator is a custom field key and the right of the operator is a + // string (surrounded by quotes) value. + // + // Numeric custom attributes: Supported operators are '>', '<' or '=' + // operators where the left of the operator is a custom field key and the + // right of the operator is a numeric value. + // + // Supported functions are LOWER(<field_name>) to + // perform case insensitive match and EMPTY(<field_name>) to filter on the + // existence of a key. + // + // Boolean expressions (AND/OR/NOT) are supported up to 3 levels of + // nesting (for example "((A AND B AND C) OR NOT D) AND E"), and there can be + // a maximum of 50 comparisons/functions in the expression. The expression + // must be < 2000 characters in length. + // + // Sample Query: + // (key1 = "TEST" OR LOWER(key1)="test" OR NOT EMPTY(key1)) + string custom_attribute_filter = 15; +} + +// Input only. +// +// Geographic region of the search. +message LocationFilter { + // Specify whether including telecommute jobs. + enum TelecommutePreference { + // Default value if the telecommute preference isn't specified. + TELECOMMUTE_PREFERENCE_UNSPECIFIED = 0; + + // Exclude telecommute jobs. + TELECOMMUTE_EXCLUDED = 1; + + // Allow telecommute jobs. + TELECOMMUTE_ALLOWED = 2; + } + + // Optional. + // + // The address name, such as "Mountain View" or "Bay Area". + string address = 1; + + // Optional. + // + // CLDR region code of the country/region of the address. This is used + // to address ambiguity of the user-input location, for example, "Liverpool" + // against "Liverpool, NY, US" or "Liverpool, UK". + // + // Set this field if all the jobs to search against are from a same region, + // or jobs are world-wide, but the job seeker is from a specific region. + // + // See http://cldr.unicode.org/ and + // http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html + // for details. Example: "CH" for Switzerland. + string region_code = 2; + + // Optional. + // + // The latitude and longitude of the geographic center from which to + // search. This field's ignored if `address` is provided. + google.type.LatLng lat_lng = 3; + + // Optional. + // + // + // The distance_in_miles is applied when the location being searched for is + // identified as a city or smaller. When the location being searched for is a + // state or larger, this field is ignored. + double distance_in_miles = 4; + + // Optional. + // + // Allows the client to return jobs without a + // set location, specifically, telecommuting jobs (telecomuting is considered + // by the service as a special location. + // [Job.posting_region][google.cloud.talent.v4beta1.Job.posting_region] indicates if a job permits telecommuting. + // If this field is set to [TelecommutePreference.TELECOMMUTE_ALLOWED][google.cloud.talent.v4beta1.LocationFilter.TelecommutePreference.TELECOMMUTE_ALLOWED], + // telecommuting jobs are searched, and [address][google.cloud.talent.v4beta1.LocationFilter.address] and [lat_lng][google.cloud.talent.v4beta1.LocationFilter.lat_lng] are + // ignored. If not set or set to + // [TelecommutePreference.TELECOMMUTE_EXCLUDED][google.cloud.talent.v4beta1.LocationFilter.TelecommutePreference.TELECOMMUTE_EXCLUDED], telecommute job are not + // searched. + // + // This filter can be used by itself to search exclusively for telecommuting + // jobs, or it can be combined with another location + // filter to search for a combination of job locations, + // such as "Mountain View" or "telecommuting" jobs. However, when used in + // combination with other location filters, telecommuting jobs can be + // treated as less relevant than other jobs in the search response. + TelecommutePreference telecommute_preference = 5; + + // Optional. + // + // Whether to apply negation to the filter so profiles matching the filter + // are excluded. + // + // Currently only supported in profile search. + bool negated = 6; +} + +// Input only. +// +// Filter on job compensation type and amount. +message CompensationFilter { + // Specify the type of filtering. + enum FilterType { + // Filter type unspecified. Position holder, INVALID, should never be used. + FILTER_TYPE_UNSPECIFIED = 0; + + // Filter by `base compensation entry's` unit. A job is a match if and + // only if the job contains a base CompensationEntry and the base + // CompensationEntry's unit matches provided [units][google.cloud.talent.v4beta1.CompensationFilter.units]. + // Populate one or more [units][google.cloud.talent.v4beta1.CompensationFilter.units]. + // + // See [CompensationInfo.CompensationEntry][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry] for definition of + // base compensation entry. + UNIT_ONLY = 1; + + // Filter by `base compensation entry's` unit and amount / range. A job + // is a match if and only if the job contains a base CompensationEntry, and + // the base entry's unit matches provided [compensation_units][] and amount + // or range overlaps with provided [compensation_range][]. + // + // See [CompensationInfo.CompensationEntry][google.cloud.talent.v4beta1.CompensationInfo.CompensationEntry] for definition of + // base compensation entry. + // + // Set exactly one [units][google.cloud.talent.v4beta1.CompensationFilter.units] and populate [range][google.cloud.talent.v4beta1.CompensationFilter.range]. + UNIT_AND_AMOUNT = 2; + + // Filter by annualized base compensation amount and `base compensation + // entry's` unit. Populate [range][google.cloud.talent.v4beta1.CompensationFilter.range] and zero or more [units][google.cloud.talent.v4beta1.CompensationFilter.units]. + ANNUALIZED_BASE_AMOUNT = 3; + + // Filter by annualized total compensation amount and `base compensation + // entry's` unit . Populate [range][google.cloud.talent.v4beta1.CompensationFilter.range] and zero or more [units][google.cloud.talent.v4beta1.CompensationFilter.units]. + ANNUALIZED_TOTAL_AMOUNT = 4; + } + + // Required. + // + // Type of filter. + FilterType type = 1; + + // Required. + // + // Specify desired `base compensation entry's` + // [CompensationInfo.CompensationUnit][google.cloud.talent.v4beta1.CompensationInfo.CompensationUnit]. + repeated CompensationInfo.CompensationUnit units = 2; + + // Optional. + // + // Compensation range. + CompensationInfo.CompensationRange range = 3; + + // Optional. + // + // Whether to include jobs whose compensation range is unspecified. + bool include_jobs_with_unspecified_compensation_range = 4; +} + +// Input only. +// +// Parameters needed for commute search. +message CommuteFilter { + // The traffic density to use when calculating commute time. + enum RoadTraffic { + // Road traffic situation isn't specified. + ROAD_TRAFFIC_UNSPECIFIED = 0; + + // Optimal commute time without considering any traffic impact. + TRAFFIC_FREE = 1; + + // Commute time calculation takes in account the peak traffic impact. + BUSY_HOUR = 2; + } + + // Required. + // + // The method of transportation for which to calculate the commute time. + CommuteMethod commute_method = 1; + + // Required. + // + // The latitude and longitude of the location from which to calculate the + // commute time. + google.type.LatLng start_coordinates = 2; + + // Required. + // + // The maximum travel time in seconds. The maximum allowed value is `3600s` + // (one hour). Format is `123s`. + google.protobuf.Duration travel_duration = 3; + + // Optional. + // If `true`, jobs without street level addresses may also be returned. + // For city level addresses, the city center is used. For state and coarser + // level addresses, text matching is used. + // If this field is set to `false` or isn't specified, only jobs that include + // street level addresses will be returned by commute search. + bool allow_imprecise_addresses = 4; + + // Optional. + // + // Traffic factor to take into account while searching by commute. + oneof traffic_option { + // Optional. + // + // Specifies the traffic density to use when calculating commute time. + RoadTraffic road_traffic = 5; + + // Optional. + // + // The departure time used to calculate traffic impact, represented as + // [google.type.TimeOfDay][google.type.TimeOfDay] in local time zone. + // + // Currently traffic model is restricted to hour level resolution. + google.type.TimeOfDay departure_time = 6; + } +} + +// Input only. +// +// Job title of the search. +message JobTitleFilter { + // Required. + // + // The job title, for example, "Software engineer", or "Product manager". + string job_title = 1; + + // Optional. + // + // Whether to apply negation to the filter so profiles matching the filter + // are excluded. + bool negated = 2; +} + +// Input only. +// +// Skill filter of the search. +message SkillFilter { + // Required. + // + // The skill name. For example, "java", "j2ee", and so on. + string skill = 1; + + // Optional. + // + // Whether to apply negation to the filter so profiles matching the filter + // are excluded. + bool negated = 2; +} + +// Input only. +// +// Employer filter of the search. +message EmployerFilter { + // Enum indicating which set of [Profile.employment_records][google.cloud.talent.v4beta1.Profile.employment_records] to search + // against. + enum EmployerFilterMode { + // Default value. + EMPLOYER_FILTER_MODE_UNSPECIFIED = 0; + + // Apply to all employers in [Profile.employment_records][google.cloud.talent.v4beta1.Profile.employment_records]. + ALL_EMPLOYMENT_RECORDS = 1; + + // Apply only to current employer in [Profile.employment_records][google.cloud.talent.v4beta1.Profile.employment_records]. + CURRENT_EMPLOYMENT_RECORDS_ONLY = 2; + + // Apply only to past (not current) employers in + // [Profile.employment_records][google.cloud.talent.v4beta1.Profile.employment_records]. + PAST_EMPLOYMENT_RECORDS_ONLY = 3; + } + + // Required. + // + // The name of the employer, for example "Google", "Alphabet". + string employer = 1; + + // Optional. + // + // Define set of [EmploymentRecord][google.cloud.talent.v4beta1.EmploymentRecord]s to search against. + // + // Defaults to [EmployerFilterMode.ALL_EMPLOYMENT_RECORDS][google.cloud.talent.v4beta1.EmployerFilter.EmployerFilterMode.ALL_EMPLOYMENT_RECORDS]. + EmployerFilterMode mode = 2; + + // Optional. + // + // Whether to apply negation to the filter so profiles matching the filter + // is excluded. + bool negated = 3; +} + +// Input only. +// +// Education filter of the search. +message EducationFilter { + // Optional. + // + // The school name. For example "MIT", "University of California, Berkeley". + string school = 1; + + // Optional. + // + // The field of study. This is to search against value provided in + // [Degree.fields_of_study][google.cloud.talent.v4beta1.Degree.fields_of_study]. + // For example "Computer Science", "Mathematics". + string field_of_study = 2; + + // Optional. + // + // Education degree in ISCED code. Each value in degree covers a specific + // level of education, without any expansion to upper nor lower levels of + // education degree. + DegreeType degree_type = 3; + + // Optional. + // + // Whether to apply negation to the filter so profiles matching the filter + // is excluded. + bool negated = 6; +} + +// Input only. +// +// Work experience filter. +// +// This filter is used to search for profiles with working experience length +// between [min_experience][google.cloud.talent.v4beta1.WorkExperienceFilter.min_experience] and [max_experience][google.cloud.talent.v4beta1.WorkExperienceFilter.max_experience]. +message WorkExperienceFilter { + // Optional. + // + // The minimum duration of the work experience (inclusive). + google.protobuf.Duration min_experience = 1; + + // Optional. + // + // The maximum duration of the work experience (exclusive). + google.protobuf.Duration max_experience = 2; +} + +// Input only. +// +// Application Date Range Filter. +// +// The API matches profiles with [Application.application_date][google.cloud.talent.v4beta1.Application.application_date] between +// start date and end date (both boundaries are inclusive). The filter is +// ignored if both [start_date][google.cloud.talent.v4beta1.ApplicationDateFilter.start_date] and [end_date][google.cloud.talent.v4beta1.ApplicationDateFilter.end_date] are missing. +message ApplicationDateFilter { + // Optional. + // + // Start date. If it's missing, The API matches profiles with application date + // not after the end date. + google.type.Date start_date = 1; + + // Optional. + // + // End date. If it's missing, The API matches profiles with application date + // not before the start date. + google.type.Date end_date = 2; +} + +// Input only. +// +// Outcome Notes Filter. +message ApplicationOutcomeNotesFilter { + // Required. + // + // User entered or selected outcome reason. The API does an exact match on the + // [Application.outcome_notes][google.cloud.talent.v4beta1.Application.outcome_notes] in profiles. + string outcome_notes = 1; + + // Optional. + // + // If true, The API excludes all candidates with any + // [Application.outcome_notes][google.cloud.talent.v4beta1.Application.outcome_notes] matching the outcome reason specified in + // the filter. + bool negated = 2; +} + +// Input only. +// +// Filter on the job information of Application. +message ApplicationJobFilter { + // Optional. + // + // The job requisition id in the application. The API does an exact match on + // the [Job.requisistion_id][] of [Application.job][google.cloud.talent.v4beta1.Application.job] in profiles. + string job_requisition_id = 2; + + // Optional. + // + // The job title in the application. The API does an exact match on the + // [Job.title][google.cloud.talent.v4beta1.Job.title] of [Application.job][google.cloud.talent.v4beta1.Application.job] in profiles. + string job_title = 3; + + // Optional. + // + // If true, the API excludes all profiles with any [Application.job][google.cloud.talent.v4beta1.Application.job] + // matching the filters. + bool negated = 4; +} + +// Input only. +// +// Filter on create timestamp or update timestamp of profiles. +message TimeFilter { + // Time fields can be used in TimeFilter. + enum TimeField { + // Default value. + TIME_FIELD_UNSPECIFIED = 0; + + // Earliest profile create time. + CREATE_TIME = 1; + + // Latest profile update time. + UPDATE_TIME = 2; + } + + // Optional. + // + // Start timestamp, matching profiles with the start time. If this field + // missing, The API matches profiles with create / update timestamp before the + // end timestamp. + google.protobuf.Timestamp start_time = 1; + + // Optional. + // + // End timestamp, matching profiles with the end time. If this field + // missing, The API matches profiles with create / update timestamp after the + // start timestamp. + google.protobuf.Timestamp end_time = 2; + + // Optional. + // + // Specifies which time field to filter profiles. + // + // Defaults to [TimeField.CREATE_TIME][google.cloud.talent.v4beta1.TimeFilter.TimeField.CREATE_TIME]. + TimeField time_field = 3; +} diff --git a/google/cloud/talent/v4beta1/histogram.proto b/google/cloud/talent/v4beta1/histogram.proto new file mode 100644 index 000000000..a8caf39a0 --- /dev/null +++ b/google/cloud/talent/v4beta1/histogram.proto @@ -0,0 +1,58 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/protobuf/wrappers.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "HistogramProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// Input Only. +// +// The histogram request. +message HistogramQuery { + // An expression specifies a histogram request against matching resources + // (for example, jobs, profiles) for searches. + // + // See [SearchJobsRequest.histogram_queries][google.cloud.talent.v4beta1.SearchJobsRequest.histogram_queries] and + // [SearchProfilesRequest.histogram_queries][google.cloud.talent.v4beta1.SearchProfilesRequest.histogram_queries] for details about syntax. + string histogram_query = 1; +} + +// Output only. +// +// Histogram result that matches [HistogramSpec][] specified in searches. +message HistogramQueryResult { + // Requested histogram expression. + string histogram_query = 1; + + // A map from the values of the facet associated with distinct values to the + // number of matching entries with corresponding value. + // + // The key format is: + // * (for string histogram) string values stored in the field. + // * (for named numeric bucket) name specified in `bucket()` function, like + // for `bucket(0, MAX, "non-negative")`, the key will be `non-negative`. + // * (for anonymous numeric bucket) range formatted as `<low>-<high>`, for + // example, `0-1000`, `MIN-0`, and `0-MAX`. + map<string, int64> histogram = 2; +} diff --git a/google/cloud/talent/v4beta1/job.proto b/google/cloud/talent/v4beta1/job.proto new file mode 100644 index 000000000..053634a9a --- /dev/null +++ b/google/cloud/talent/v4beta1/job.proto @@ -0,0 +1,388 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/cloud/talent/v4beta1/common.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "JobResourceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A Job resource represents a job posting (also referred to as a "job listing" +// or "job requisition"). A job belongs to a [Company][google.cloud.talent.v4beta1.Company], which is the hiring +// entity responsible for the job. +message Job { + // Application related details of a job posting. + message ApplicationInfo { + // Optional. + // + // Use this field to specify email address(es) to which resumes or + // applications can be sent. + // + // The maximum number of allowed characters for each entry is 255. + repeated string emails = 1; + + // Optional. + // + // Use this field to provide instructions, such as "Mail your application + // to ...", that a candidate can follow to apply for the job. + // + // This field accepts and sanitizes HTML input, and also accepts + // bold, italic, ordered list, and unordered list markup tags. + // + // The maximum number of allowed characters is 3,000. + string instruction = 2; + + // Optional. + // + // Use this URI field to direct an applicant to a website, for example to + // link to an online application form. + // + // The maximum number of allowed characters for each entry is 2,000. + repeated string uris = 3; + } + + // Output only. + // + // Derived details about the job posting. + message DerivedInfo { + // Structured locations of the job, resolved from [Job.addresses][google.cloud.talent.v4beta1.Job.addresses]. + // + // [locations][google.cloud.talent.v4beta1.Job.DerivedInfo.locations] are exactly matched to [Job.addresses][google.cloud.talent.v4beta1.Job.addresses] in the same + // order. + repeated Location locations = 1; + + // Job categories derived from [Job.title][google.cloud.talent.v4beta1.Job.title] and [Job.description][google.cloud.talent.v4beta1.Job.description]. + repeated JobCategory job_categories = 3; + } + + // Input only. + // + // Options for job processing. + message ProcessingOptions { + // Optional. + // + // If set to `true`, the service does not attempt to resolve a + // more precise address for the job. + bool disable_street_address_resolution = 1; + + // Optional. + // + // Option for job HTML content sanitization. Applied fields are: + // + // * description + // * applicationInfo.instruction + // * incentives + // * qualifications + // * responsibilities + // + // HTML tags in these fields may be stripped if sanitiazation isn't + // disabled. + // + // Defaults to [HtmlSanitization.SIMPLE_FORMATTING_ONLY][google.cloud.talent.v4beta1.HtmlSanitization.SIMPLE_FORMATTING_ONLY]. + HtmlSanitization html_sanitization = 2; + } + + // Required during job update. + // + // The resource name for the job. This is generated by the service when a + // job is created. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/jobs/{job_id}", for + // example, "projects/api-test-project/tenants/foo/jobs/1234". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/jobs/1234". + // + // Use of this field in job queries and API calls is preferred over the use of + // [requisition_id][google.cloud.talent.v4beta1.Job.requisition_id] since this value is unique. + string name = 1; + + // Required. + // + // The resource name of the company listing the job. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for + // example, "projects/api-test-project/tenants/foo/companies/bar". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/companies/bar". + string company = 2; + + // Required. + // + // The requisition ID, also referred to as the posting ID, is assigned by the + // client to identify a job. This field is intended to be used by clients + // for client identification and tracking of postings. A job isn't allowed + // to be created if there is another job with the same [company][google.cloud.talent.v4beta1.Job.name], + // [language_code][google.cloud.talent.v4beta1.Job.language_code] and [requisition_id][google.cloud.talent.v4beta1.Job.requisition_id]. + // + // The maximum number of allowed characters is 255. + string requisition_id = 3; + + // Required. + // + // The title of the job, such as "Software Engineer" + // + // The maximum number of allowed characters is 500. + string title = 4; + + // Required. + // + // The description of the job, which typically includes a multi-paragraph + // description of the company and related information. Separate fields are + // provided on the job object for [responsibilities][google.cloud.talent.v4beta1.Job.responsibilities], + // [qualifications][google.cloud.talent.v4beta1.Job.qualifications], and other job characteristics. Use of + // these separate job fields is recommended. + // + // This field accepts and sanitizes HTML input, and also accepts + // bold, italic, ordered list, and unordered list markup tags. + // + // The maximum number of allowed characters is 100,000. + string description = 5; + + // Optional but strongly recommended for the best service experience. + // + // Location(s) where the employer is looking to hire for this job posting. + // + // Specifying the full street address(es) of the hiring location enables + // better API results, especially job searches by commute time. + // + // At most 50 locations are allowed for best search performance. If a job has + // more locations, it is suggested to split it into multiple jobs with unique + // [requisition_id][google.cloud.talent.v4beta1.Job.requisition_id]s (e.g. 'ReqA' becomes 'ReqA-1', 'ReqA-2', and so on.) as + // multiple jobs with the same [company][google.cloud.talent.v4beta1.Job.name][], [language_code][] and + // [requisition_id][google.cloud.talent.v4beta1.Job.requisition_id] are not allowed. If the original [requisition_id][google.cloud.talent.v4beta1.Job.requisition_id] must + // be preserved, a custom field should be used for storage. It is also + // suggested to group the locations that close to each other in the same job + // for better search experience. + // + // The maximum number of allowed characters is 500. + repeated string addresses = 6; + + // Optional. + // + // Job application information. + ApplicationInfo application_info = 7; + + // Optional. + // + // The benefits included with the job. + repeated JobBenefit job_benefits = 8; + + // Optional. + // + // Job compensation information (a.k.a. "pay rate") i.e., the compensation + // that will paid to the employee. + CompensationInfo compensation_info = 9; + + // Optional. + // + // A map of fields to hold both filterable and non-filterable custom job + // attributes that are not covered by the provided structured fields. + // + // The keys of the map are strings up to 64 bytes and must match the + // pattern: [a-zA-Z][a-zA-Z0-9_]*. For example, key0LikeThis or + // KEY_1_LIKE_THIS. + // + // At most 100 filterable and at most 100 unfilterable keys are supported. + // For filterable `string_values`, across all keys at most 200 values are + // allowed, with each string no more than 255 characters. For unfilterable + // `string_values`, the maximum total size of `string_values` across all keys + // is 50KB. + map<string, CustomAttribute> custom_attributes = 10; + + // Optional. + // + // The desired education degrees for the job, such as Bachelors, Masters. + repeated DegreeType degree_types = 11; + + // Optional. + // + // The department or functional area within the company with the open + // position. + // + // The maximum number of allowed characters is 255. + string department = 12; + + // Optional. + // + // The employment type(s) of a job, for example, + // [full time][google.cloud.talent.v4beta1.EmploymentType.FULL_TIME] or + // [part time][google.cloud.talent.v4beta1.EmploymentType.PART_TIME]. + repeated EmploymentType employment_types = 13; + + // Optional. + // + // A description of bonus, commission, and other compensation + // incentives associated with the job not including salary or pay. + // + // The maximum number of allowed characters is 10,000. + string incentives = 14; + + // Optional. + // + // The language of the posting. This field is distinct from + // any requirements for fluency that are associated with the job. + // + // Language codes must be in BCP-47 format, such as "en-US" or "sr-Latn". + // For more information, see + // [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47){: + // class="external" target="_blank" }. + // + // If this field is unspecified and [Job.description][google.cloud.talent.v4beta1.Job.description] is present, detected + // language code based on [Job.description][google.cloud.talent.v4beta1.Job.description] is assigned, otherwise + // defaults to 'en_US'. + string language_code = 15; + + // Optional. + // + // The experience level associated with the job, such as "Entry Level". + JobLevel job_level = 16; + + // Optional. + // + // A promotion value of the job, as determined by the client. + // The value determines the sort order of the jobs returned when searching for + // jobs using the featured jobs search call, with higher promotional values + // being returned first and ties being resolved by relevance sort. Only the + // jobs with a promotionValue >0 are returned in a FEATURED_JOB_SEARCH. + // + // Default value is 0, and negative values are treated as 0. + int32 promotion_value = 17; + + // Optional. + // + // A description of the qualifications required to perform the + // job. The use of this field is recommended + // as an alternative to using the more general [description][google.cloud.talent.v4beta1.Job.description] field. + // + // This field accepts and sanitizes HTML input, and also accepts + // bold, italic, ordered list, and unordered list markup tags. + // + // The maximum number of allowed characters is 10,000. + string qualifications = 18; + + // Optional. + // + // A description of job responsibilities. The use of this field is + // recommended as an alternative to using the more general [description][google.cloud.talent.v4beta1.Job.description] + // field. + // + // This field accepts and sanitizes HTML input, and also accepts + // bold, italic, ordered list, and unordered list markup tags. + // + // The maximum number of allowed characters is 10,000. + string responsibilities = 19; + + // Optional. + // + // The job [PostingRegion][google.cloud.talent.v4beta1.PostingRegion] (for example, state, country) throughout + // which the job is available. If this field is set, a [LocationFilter][google.cloud.talent.v4beta1.LocationFilter] + // in a search query within the job region finds this job posting if an + // exact location match isn't specified. If this field is set to + // [PostingRegion.NATION][google.cloud.talent.v4beta1.PostingRegion.NATION] or [PostingRegion.ADMINISTRATIVE_AREA][google.cloud.talent.v4beta1.PostingRegion.ADMINISTRATIVE_AREA], + // setting job [Job.addresses][google.cloud.talent.v4beta1.Job.addresses] to the same location level as this field + // is strongly recommended. + PostingRegion posting_region = 20; + + // Optional. + // + // The visibility of the job. + // + // Defaults to [Visibility.ACCOUNT_ONLY][google.cloud.talent.v4beta1.Visibility.ACCOUNT_ONLY] if not specified. + Visibility visibility = 21; + + // Optional. + // + // The start timestamp of the job in UTC time zone. Typically this field + // is used for contracting engagements. Invalid timestamps are ignored. + google.protobuf.Timestamp job_start_time = 22; + + // Optional. + // + // The end timestamp of the job. Typically this field is used for contracting + // engagements. Invalid timestamps are ignored. + google.protobuf.Timestamp job_end_time = 23; + + // Optional. + // + // The timestamp this job posting was most recently published. The default + // value is the time the request arrives at the server. Invalid timestamps are + // ignored. + google.protobuf.Timestamp posting_publish_time = 24; + + // Optional but strongly recommended for the best service + // experience. + // + // The expiration timestamp of the job. After this timestamp, the + // job is marked as expired, and it no longer appears in search results. The + // expired job can't be deleted or listed by the [DeleteJob][] and + // [ListJobs][] APIs, but it can be retrieved with the [GetJob][] API or + // updated with the [UpdateJob][] API. An expired job can be updated and + // opened again by using a future expiration timestamp. Updating an expired + // job fails if there is another existing open job with same + // [company][google.cloud.talent.v4beta1.Job.name][], [language_code][] and [requisition_id][google.cloud.talent.v4beta1.Job.requisition_id]. + // + // The expired jobs are retained in our system for 90 days. However, the + // overall expired job count cannot exceed 3 times the maximum of open jobs + // count over the past week, otherwise jobs with earlier expire time are + // cleaned first. Expired jobs are no longer accessible after they are cleaned + // out. + // + // Invalid timestamps are ignored, and treated as expire time not provided. + // + // Timestamp before the instant request is made is considered valid, the job + // will be treated as expired immediately. + // + // If this value isn't provided at the time of job creation or is invalid, + // the job posting expires after 30 days from the job's creation time. For + // example, if the job was created on 2017/01/01 13:00AM UTC with an + // unspecified expiration date, the job expires after 2017/01/31 13:00AM UTC. + // + // If this value isn't provided on job update, it depends on the field masks + // set by [UpdateJobRequest.update_mask][google.cloud.talent.v4beta1.UpdateJobRequest.update_mask]. If the field masks include + // [expiry_time][], or the masks are empty meaning that every field is + // updated, the job posting expires after 30 days from the job's last + // update time. Otherwise the expiration date isn't updated. + google.protobuf.Timestamp posting_expire_time = 25; + + // Output only. The timestamp when this job posting was created. + google.protobuf.Timestamp posting_create_time = 26; + + // Output only. The timestamp when this job posting was last updated. + google.protobuf.Timestamp posting_update_time = 27; + + // Output only. Display name of the company listing the job. + string company_display_name = 28; + + // Output only. Derived details about the job posting. + DerivedInfo derived_info = 29; + + // Optional. + // + // Options for job processing. + ProcessingOptions processing_options = 30; +} diff --git a/google/cloud/talent/v4beta1/job_service.proto b/google/cloud/talent/v4beta1/job_service.proto new file mode 100644 index 000000000..314ac1298 --- /dev/null +++ b/google/cloud/talent/v4beta1/job_service.proto @@ -0,0 +1,831 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/common.proto"; +import "google/cloud/talent/v4beta1/filters.proto"; +import "google/cloud/talent/v4beta1/histogram.proto"; +import "google/cloud/talent/v4beta1/job.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "JobServiceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A service handles job management, including job CRUD, enumeration and search. +service JobService { + // Creates a new job. + // + // Typically, the job becomes searchable within 10 seconds, but it may take + // up to 5 minutes. + rpc CreateJob(CreateJobRequest) returns (Job) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}/jobs" + body: "*" + additional_bindings { + post: "/v4beta1/{parent=projects/*}/jobs" + body: "*" + } + }; + } + + // Retrieves the specified job, whose status is OPEN or recently EXPIRED + // within the last 90 days. + rpc GetJob(GetJobRequest) returns (Job) { + option (google.api.http) = { + get: "/v4beta1/{name=projects/*/tenants/*/jobs/*}" + additional_bindings { + get: "/v4beta1/{name=projects/*/jobs/*}" + } + }; + } + + // Updates specified job. + // + // Typically, updated contents become visible in search results within 10 + // seconds, but it may take up to 5 minutes. + rpc UpdateJob(UpdateJobRequest) returns (Job) { + option (google.api.http) = { + patch: "/v4beta1/{job.name=projects/*/tenants/*/jobs/*}" + body: "*" + additional_bindings { + patch: "/v4beta1/{job.name=projects/*/jobs/*}" + body: "*" + } + }; + } + + // Deletes the specified job. + // + // Typically, the job becomes unsearchable within 10 seconds, but it may take + // up to 5 minutes. + rpc DeleteJob(DeleteJobRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v4beta1/{name=projects/*/tenants/*/jobs/*}" + additional_bindings { + delete: "/v4beta1/{name=projects/*/jobs/*}" + } + }; + } + + // Lists jobs by filter. + rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) { + option (google.api.http) = { + get: "/v4beta1/{parent=projects/*/tenants/*}/jobs" + additional_bindings { + get: "/v4beta1/{parent=projects/*}/jobs" + } + }; + } + + // Deletes a list of [Job][google.cloud.talent.v4beta1.Job]s by filter. + rpc BatchDeleteJobs(BatchDeleteJobsRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}/jobs:batchDelete" + body: "*" + additional_bindings { + post: "/v4beta1/{parent=projects/*}/jobs:batchDelete" + } + }; + } + + // Searches for jobs using the provided [SearchJobsRequest][google.cloud.talent.v4beta1.SearchJobsRequest]. + // + // This call constrains the [visibility][google.cloud.talent.v4beta1.Job.visibility] of jobs + // present in the database, and only returns jobs that the caller has + // permission to search against. + rpc SearchJobs(SearchJobsRequest) returns (SearchJobsResponse) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}/jobs:search" + body: "*" + additional_bindings { + post: "/v4beta1/{parent=projects/*}/jobs:search" + body: "*" + } + }; + } + + // Searches for jobs using the provided [SearchJobsRequest][google.cloud.talent.v4beta1.SearchJobsRequest]. + // + // This API call is intended for the use case of targeting passive job + // seekers (for example, job seekers who have signed up to receive email + // alerts about potential job opportunities), and has different algorithmic + // adjustments that are targeted to passive job seekers. + // + // This call constrains the [visibility][google.cloud.talent.v4beta1.Job.visibility] of jobs + // present in the database, and only returns jobs the caller has + // permission to search against. + rpc SearchJobsForAlert(SearchJobsRequest) returns (SearchJobsResponse) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}/jobs:searchForAlert" + body: "*" + additional_bindings { + post: "/v4beta1/{parent=projects/*}/jobs:searchForAlert" + body: "*" + } + }; + } +} + +// Input only. +// +// Create job request. +message CreateJobRequest { + // Required. + // + // The resource name of the tenant under which the job is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and a default tenant is created if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Required. + // + // The Job to be created. + Job job = 2; +} + +// Input only. +// +// Get job request. +message GetJobRequest { + // Required. + // + // The resource name of the job to retrieve. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/jobs/{job_id}", for + // example, "projects/api-test-project/tenants/foo/jobs/1234". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/jobs/1234". + string name = 1; +} + +// Input only. +// +// Update job request. +message UpdateJobRequest { + // Required. + // + // The Job to be updated. + Job job = 1; + + // Optional but strongly recommended to be provided for the best service + // experience. + // + // If [update_mask][google.cloud.talent.v4beta1.UpdateJobRequest.update_mask] is provided, only the specified fields in + // [job][google.cloud.talent.v4beta1.UpdateJobRequest.job] are updated. Otherwise all the fields are updated. + // + // A field mask to restrict the fields that are updated. Only + // top level fields of [Job][google.cloud.talent.v4beta1.Job] are supported. + google.protobuf.FieldMask update_mask = 2; +} + +// Input only. +// +// Delete job request. +message DeleteJobRequest { + // Required. + // + // The resource name of the job to be deleted. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/jobs/{job_id}", for + // example, "projects/api-test-project/tenants/foo/jobs/1234". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project/jobs/1234". + string name = 1; +} + +// Input only. +// +// Batch delete jobs request. +message BatchDeleteJobsRequest { + // Required. + // + // The resource name of the tenant under which the job is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Required. + // + // The filter string specifies the jobs to be deleted. + // + // Supported operator: =, AND + // + // The fields eligible for filtering are: + // + // * `companyName` (Required) + // * `requisitionId` (Required) + // + // Sample Query: companyName = "projects/api-test-project/companies/123" AND + // requisitionId = "req-1" + string filter = 2; +} + +// Input only. +// +// List jobs request. +message ListJobsRequest { + // Required. + // + // The resource name of the tenant under which the job is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Required. + // + // The filter string specifies the jobs to be enumerated. + // + // Supported operator: =, AND + // + // The fields eligible for filtering are: + // + // * `companyName` (Required) + // * `requisitionId` (Optional) + // * `status` (Optional) Available values: OPEN, EXPIRED, ALL. Defaults to + // OPEN if no value is specified. + // + // Sample Query: + // + // * companyName = "projects/api-test-project/tenants/foo/companies/bar" + // * companyName = "projects/api-test-project/tenants/foo/companies/bar" AND + // requisitionId = "req-1" + // * companyName = "projects/api-test-project/tenants/foo/companies/bar" AND + // status = "EXPIRED" + string filter = 2; + + // Optional. + // + // The starting point of a query result. + string page_token = 3; + + // Optional. + // + // The maximum number of jobs to be returned per page of results. + // + // If [job_view][google.cloud.talent.v4beta1.ListJobsRequest.job_view] is set to [JobView.JOB_VIEW_ID_ONLY][google.cloud.talent.v4beta1.JobView.JOB_VIEW_ID_ONLY], the maximum allowed + // page size is 1000. Otherwise, the maximum allowed page size is 100. + // + // Default is 100 if empty or a number < 1 is specified. + int32 page_size = 4; + + // Optional. + // + // The desired job attributes returned for jobs in the + // search response. Defaults to [JobView.JOB_VIEW_FULL][google.cloud.talent.v4beta1.JobView.JOB_VIEW_FULL] if no value is + // specified. + JobView job_view = 5; +} + +// An enum that specifies the job attributes that are returned in the +// [MatchingJob.Job][] in [SearchJobsResponse][google.cloud.talent.v4beta1.SearchJobsResponse] or [Job][google.cloud.talent.v4beta1.Job] objects in +// [ListJobsResponse][google.cloud.talent.v4beta1.ListJobsResponse]. +enum JobView { + // Default value. + JOB_VIEW_UNSPECIFIED = 0; + + // A ID only view of job, with following attributes: + // [Job.name][google.cloud.talent.v4beta1.Job.name], [Job.requisition_id][google.cloud.talent.v4beta1.Job.requisition_id], [Job.language_code][google.cloud.talent.v4beta1.Job.language_code]. + JOB_VIEW_ID_ONLY = 1; + + // A minimal view of the job, with the following attributes: + // [Job.name][google.cloud.talent.v4beta1.Job.name], [Job.requisition_id][google.cloud.talent.v4beta1.Job.requisition_id], [Job.job_title][], + // [Job.company][google.cloud.talent.v4beta1.Job.company], [Job.DerivedInfo.locations][google.cloud.talent.v4beta1.Job.DerivedInfo.locations], [Job.language_code][google.cloud.talent.v4beta1.Job.language_code]. + JOB_VIEW_MINIMAL = 2; + + // A small view of the job, with the following attributes in the search + // results: [Job.name][google.cloud.talent.v4beta1.Job.name], [Job.requisition_id][google.cloud.talent.v4beta1.Job.requisition_id], [Job.job_title][], + // [Job.company][google.cloud.talent.v4beta1.Job.company], [Job.DerivedInfo.locations][google.cloud.talent.v4beta1.Job.DerivedInfo.locations], [Job.visibility][google.cloud.talent.v4beta1.Job.visibility], + // [Job.language_code][google.cloud.talent.v4beta1.Job.language_code], [Job.description][google.cloud.talent.v4beta1.Job.description]. + JOB_VIEW_SMALL = 3; + + // All available attributes are included in the search results. + JOB_VIEW_FULL = 4; +} + +// Output only. +// +// List jobs response. +message ListJobsResponse { + // The Jobs for a given company. + // + // The maximum number of items returned is based on the limit field + // provided in the request. + repeated Job jobs = 1; + + // A token to retrieve the next page of results. + string next_page_token = 2; + + // Additional information for the API invocation, such as the request + // tracking id. + ResponseMetadata metadata = 3; +} + +// Input only. +// +// The Request body of the `SearchJobs` call. +message SearchJobsRequest { + // Input only. + // + // Custom ranking information for [SearchJobsRequest][google.cloud.talent.v4beta1.SearchJobsRequest]. + message CustomRankingInfo { + // The importance level for [CustomRankingInfo.ranking_expression][google.cloud.talent.v4beta1.SearchJobsRequest.CustomRankingInfo.ranking_expression]. + enum ImportanceLevel { + // Default value if the importance level isn't specified. + IMPORTANCE_LEVEL_UNSPECIFIED = 0; + + // The given ranking expression is of None importance, existing relevance + // score (determined by API algorithm) dominates job's final ranking + // position. + NONE = 1; + + // The given ranking expression is of Low importance in terms of job's + // final ranking position compared to existing relevance + // score (determined by API algorithm). + LOW = 2; + + // The given ranking expression is of Mild importance in terms of job's + // final ranking position compared to existing relevance + // score (determined by API algorithm). + MILD = 3; + + // The given ranking expression is of Medium importance in terms of job's + // final ranking position compared to existing relevance + // score (determined by API algorithm). + MEDIUM = 4; + + // The given ranking expression is of High importance in terms of job's + // final ranking position compared to existing relevance + // score (determined by API algorithm). + HIGH = 5; + + // The given ranking expression is of Extreme importance, and dominates + // job's final ranking position with existing relevance + // score (determined by API algorithm) ignored. + EXTREME = 6; + } + + // Required. + // + // Controls over how important the score of + // [CustomRankingInfo.ranking_expression][google.cloud.talent.v4beta1.SearchJobsRequest.CustomRankingInfo.ranking_expression] gets applied to job's final + // ranking position. + // + // An error is thrown if not specified. + ImportanceLevel importance_level = 1; + + // Required. + // + // Controls over how job documents get ranked on top of existing relevance + // score (determined by API algorithm). The product of ranking expression + // and relevance score is used to determine job's final ranking position. + // + // The syntax for this expression is a subset of Google SQL syntax. + // + // Supported operators are: +, -, *, /, where the left and right side of + // the operator is either a numeric [Job.custom_attributes][google.cloud.talent.v4beta1.Job.custom_attributes] key, + // integer/double value or an expression that can be evaluated to a number. + // + // Parenthesis are supported to adjust calculation precedence. The + // expression must be < 100 characters in length. + // + // Sample ranking expression + // (year + 25) * 0.25 - (freshness / 0.5) + string ranking_expression = 2; + } + + // A string-represented enumeration of the job search mode. The service + // operate differently for different modes of service. + enum SearchMode { + // The mode of the search method isn't specified. + SEARCH_MODE_UNSPECIFIED = 0; + + // The job search matches against all jobs, and featured jobs + // (jobs with promotionValue > 0) are not specially handled. + JOB_SEARCH = 1; + + // The job search matches only against featured jobs (jobs with a + // promotionValue > 0). This method doesn't return any jobs having a + // promotionValue <= 0. The search results order is determined by the + // promotionValue (jobs with a higher promotionValue are returned higher up + // in the search results), with relevance being used as a tiebreaker. + FEATURED_JOB_SEARCH = 2; + } + + // Controls whether highly similar jobs are returned next to each other in + // the search results. Jobs are identified as highly similar based on + // their titles, job categories, and locations. Highly similar results are + // clustered so that only one representative job of the cluster is + // displayed to the job seeker higher up in the results, with the other jobs + // being displayed lower down in the results. + enum DiversificationLevel { + // The diversification level isn't specified. + DIVERSIFICATION_LEVEL_UNSPECIFIED = 0; + + // Disables diversification. Jobs that would normally be pushed to the last + // page would not have their positions altered. This may result in highly + // similar jobs appearing in sequence in the search results. + DISABLED = 1; + + // Default diversifying behavior. The result list is ordered so that + // highly similar results are pushed to the end of the last page of search + // results. + SIMPLE = 2; + } + + // Required. + // + // The resource name of the tenant to search within. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenant/foo". + // + // Tenant id is optional and the default tenant is used if unspecified, for + // example, "projects/api-test-project". + string parent = 1; + + // Optional. + // + // Mode of a search. + // + // Defaults to [SearchMode.JOB_SEARCH][google.cloud.talent.v4beta1.SearchJobsRequest.SearchMode.JOB_SEARCH]. + SearchMode search_mode = 2; + + // Required. + // + // The meta information collected about the job searcher, used to improve the + // search quality of the service.. The identifiers, (such as `user_id`) are + // provided by users, and must be unique and consistent. + RequestMetadata request_metadata = 3; + + // Optional. + // + // Query used to search against jobs, such as keyword, location filters, etc. + JobQuery job_query = 4; + + // Optional. + // + // Controls whether to broaden the search when it produces sparse results. + // Broadened queries append results to the end of the matching results + // list. + // + // Defaults to false. + bool enable_broadening = 5; + + // Optional. + // + // Controls if the search job request requires the return of a precise + // count of the first 300 results. Setting this to `true` ensures + // consistency in the number of results per page. Best practice is to set this + // value to true if a client allows users to jump directly to a + // non-sequential search results page. + // + // Enabling this flag may adversely impact performance. + // + // Defaults to false. + bool require_precise_result_size = 6; + + // Optional. + // + // An expression specifies a histogram request against matching jobs. + // + // Expression syntax is an aggregation function call with histogram facets and + // other options. + // + // Available aggregation function calls are: + // * `count(string_histogram_facet)`: Count the number of matching entities, + // for each distinct attribute value. + // * `count(numeric_histogram_facet, list of buckets)`: Count the number of + // matching entities within each bucket. + // + // Data types: + // + // * Histogram facet: facet names with format [a-zA-Z][a-zA-Z0-9_]+. + // * String: string like "any string with backslash escape for quote(\")." + // * Number: whole number and floating point number like 10, -1 and -0.01. + // * List: list of elements with comma(,) separator surrounded by square + // brackets, for example, [1, 2, 3] and ["one", "two", "three"]. + // + // Built-in constants: + // + // * MIN (minimum number similar to java Double.MIN_VALUE) + // * MAX (maximum number similar to java Double.MAX_VALUE) + // + // Built-in functions: + // + // * bucket(start, end[, label]): bucket built-in function creates a bucket + // with range of [start, end). Note that the end is exclusive, for example, + // bucket(1, MAX, "positive number") or bucket(1, 10). + // + // Job histogram facets: + // + // * company_id: histogram by [Job.distributor_company_id][]. + // * company_display_name: histogram by [Job.company_display_name][google.cloud.talent.v4beta1.Job.company_display_name]. + // * employment_type: histogram by [Job.employment_types][google.cloud.talent.v4beta1.Job.employment_types], for example, + // "FULL_TIME", "PART_TIME". + // * company_size: histogram by [CompanySize][google.cloud.talent.v4beta1.CompanySize], for example, "SMALL", + // "MEDIUM", "BIG". + // * publish_time_in_month: histogram by the [Job.publish_time][] in months. + // Must specify list of numeric buckets in spec. + // * publish_time_in_year: histogram by the [Job.publish_time][] in years. + // Must specify list of numeric buckets in spec. + // * degree_type: histogram by the [Job.degree_type][], for example, + // "Bachelors", "Masters". + // * job_level: histogram by the [Job.job_level][google.cloud.talent.v4beta1.Job.job_level], for example, "Entry + // Level". + // * country: histogram by the country code of jobs, for example, "US", "FR". + // * admin1: histogram by the admin1 code of jobs, which is a global + // placeholder referring to the state, province, or the particular term a + // country uses to define the geographic structure below the country level, + // for example, "CA", "IL". + // * city: histogram by a combination of the "city name, admin1 code". For + // example, "Mountain View, CA", "New York, NY". + // * admin1_country: histogram by a combination of the "admin1 code, country", + // for example, "CA, US", "IL, US". + // * city_coordinate: histogram by the city center's GPS coordinates (latitude + // and longitude), for example, 37.4038522,-122.0987765. Since the coordinates + // of a city center can change, customers may need to refresh them + // periodically. + // * locale: histogram by the [Job.language_code][google.cloud.talent.v4beta1.Job.language_code], for example, "en-US", + // "fr-FR". + // * language: histogram by the language subtag of the [Job.language_code][google.cloud.talent.v4beta1.Job.language_code], + // for example, "en", "fr". + // * category: histogram by the [JobCategory][google.cloud.talent.v4beta1.JobCategory], for example, + // "COMPUTER_AND_IT", "HEALTHCARE". + // * base_compensation_unit: histogram by the [CompensationUnit][] of base + // salary, for example, "WEEKLY", "MONTHLY". + // * base_compensation: histogram by the base salary. Must specify list of + // numeric buckets to group results by. + // * annualized_base_compensation: histogram by the base annualized salary. + // Must specify list of numeric buckets to group results by. + // * annualized_total_compensation: histogram by the total annualized salary. + // Must specify list of numeric buckets to group results by. + // * string_custom_attribute: histogram by string [Job.custom_attributes][google.cloud.talent.v4beta1.Job.custom_attributes]. + // Values can be accessed via square bracket notations like + // string_custom_attribute["key1"]. + // * numeric_custom_attribute: histogram by numeric [Job.custom_attributes][google.cloud.talent.v4beta1.Job.custom_attributes]. + // Values can be accessed via square bracket notations like + // numeric_custom_attribute["key1"]. Must specify list of numeric buckets to + // group results by. + // + // Example expressions: + // * count(admin1) + // * count(base_compensation, [bucket(1000, 10000), bucket(10000, 100000), + // bucket(100000, MAX)]) + // * count(string_custom_attribute["some-string-custom-attribute"]) + // * count(numeric_custom_attribute["some-numeric-custom-attribute"], + // [bucket(MIN, 0, "negative"), bucket(0, MAX, "non-negative"]) + repeated HistogramQuery histogram_queries = 7; + + // Optional. + // + // The desired job attributes returned for jobs in the + // search response. Defaults to [JobView.SMALL][] if no value is specified. + JobView job_view = 8; + + // Optional. + // + // An integer that specifies the current offset (that is, starting result + // location, amongst the jobs deemed by the API as relevant) in search + // results. This field is only considered if [page_token][google.cloud.talent.v4beta1.SearchJobsRequest.page_token] is unset. + // + // For example, 0 means to return results starting from the first matching + // job, and 10 means to return from the 11th job. This can be used for + // pagination, (for example, pageSize = 10 and offset = 10 means to return + // from the second page). + int32 offset = 9; + + // Optional. + // + // A limit on the number of jobs returned in the search results. + // Increasing this value above the default value of 10 can increase search + // response time. The value can be between 1 and 100. + int32 page_size = 10; + + // Optional. + // + // The token specifying the current offset within + // search results. See [SearchJobsResponse.next_page_token][google.cloud.talent.v4beta1.SearchJobsResponse.next_page_token] for + // an explanation of how to obtain the next set of query results. + string page_token = 11; + + // Optional. + // + // The criteria determining how search results are sorted. Default is + // "relevance desc". + // + // Supported options are: + // + // * "relevance desc": By relevance descending, as determined by the API + // algorithms. Relevance thresholding of query results is only available + // with this ordering. + // * "posting`_`publish`_`time desc": By [Job.posting_publish_time][google.cloud.talent.v4beta1.Job.posting_publish_time] + // descending. + // * "posting`_`update`_`time desc": By [Job.posting_update_time][google.cloud.talent.v4beta1.Job.posting_update_time] + // descending. + // * "title": By [Job.title][google.cloud.talent.v4beta1.Job.title] ascending. + // * "title desc": By [Job.title][google.cloud.talent.v4beta1.Job.title] descending. + // * "annualized`_`base`_`compensation": By job's + // [CompensationInfo.annualized_base_compensation_range][google.cloud.talent.v4beta1.CompensationInfo.annualized_base_compensation_range] ascending. Jobs + // whose annualized base compensation is unspecified are put at the end of + // search results. + // * "annualized`_`base`_`compensation desc": By job's + // [CompensationInfo.annualized_base_compensation_range][google.cloud.talent.v4beta1.CompensationInfo.annualized_base_compensation_range] descending. Jobs + // whose annualized base compensation is unspecified are put at the end of + // search results. + // * "annualized`_`total`_`compensation": By job's + // [CompensationInfo.annualized_total_compensation_range][google.cloud.talent.v4beta1.CompensationInfo.annualized_total_compensation_range] ascending. Jobs + // whose annualized base compensation is unspecified are put at the end of + // search results. + // * "annualized`_`total`_`compensation desc": By job's + // [CompensationInfo.annualized_total_compensation_range][google.cloud.talent.v4beta1.CompensationInfo.annualized_total_compensation_range] descending. Jobs + // whose annualized base compensation is unspecified are put at the end of + // search results. + // * "custom`_`ranking desc": By the relevance score adjusted to the + // [SearchJobsRequest.custom_ranking_info.ranking_expression][] with weight + // factor assigned by + // [SearchJobsRequest.custom_ranking_info.importance_level][] in descending + // order. + // * "location`_`distance": By the distance between the location on jobs and + // locations specified in the + // [SearchJobsRequest.job_query.location_filters][]. + // When this order is selected, the + // [SearchJobsRequest.job_query.location_filters][] must not be empty. When + // a job has multiple locations, the location closest to one of the locations + // specified in the location filter will be used to calculate location + // distance. Distance is calculated by the distance between two lat/long + // coordinates, with a precision of 10e-4 degrees (11.3 meters). + // Jobs that don't have locations specified will be ranked below jobs having + // locations. + // Diversification strategy is still applied unless explicitly disabled in + // [SearchJobsRequest.diversification_level][google.cloud.talent.v4beta1.SearchJobsRequest.diversification_level]. + string order_by = 12; + + // Optional. + // + // Controls whether highly similar jobs are returned next to each other in + // the search results. Jobs are identified as highly similar based on + // their titles, job categories, and locations. Highly similar results are + // clustered so that only one representative job of the cluster is + // displayed to the job seeker higher up in the results, with the other jobs + // being displayed lower down in the results. + // + // Defaults to [DiversificationLevel.SIMPLE][google.cloud.talent.v4beta1.SearchJobsRequest.DiversificationLevel.SIMPLE] if no value + // is specified. + DiversificationLevel diversification_level = 13; + + // Optional. + // + // Controls over how job documents get ranked on top of existing relevance + // score (determined by API algorithm). + CustomRankingInfo custom_ranking_info = 14; + + // Optional. + // + // Controls whether to disable exact keyword match on [Job.job_title][], + // [Job.description][google.cloud.talent.v4beta1.Job.description], [Job.company_display_name][google.cloud.talent.v4beta1.Job.company_display_name], [Job.locations][0], + // [Job.qualifications][google.cloud.talent.v4beta1.Job.qualifications]. When disable keyword match is turned off, a + // keyword match returns jobs that do not match given category filters when + // there are matching keywords. For example, for the query "program manager," + // a result is returned even if the job posting has the title "software + // developer," which doesn't fall into "program manager" ontology, but does + // have "program manager" appearing in its description. + // + // For queries like "cloud" that don't contain title or + // location specific ontology, jobs with "cloud" keyword matches are returned + // regardless of this flag's value. + // + // Please use [Company.keyword_searchable_custom_fields][] or + // [Company.keyword_searchable_custom_attributes][] if company specific + // globally matched custom field/attribute string values is needed. Enabling + // keyword match improves recall of subsequent search requests. + // + // Defaults to false. + bool disable_keyword_match = 16; +} + +// Output only. +// +// Response for SearchJob method. +message SearchJobsResponse { + // Output only. + // + // Job entry with metadata inside [SearchJobsResponse][google.cloud.talent.v4beta1.SearchJobsResponse]. + message MatchingJob { + // Job resource that matches the specified [SearchJobsRequest][google.cloud.talent.v4beta1.SearchJobsRequest]. + Job job = 1; + + // A summary of the job with core information that's displayed on the search + // results listing page. + string job_summary = 2; + + // Contains snippets of text from the [Job.job_title][] field most + // closely matching a search query's keywords, if available. The matching + // query keywords are enclosed in HTML bold tags. + string job_title_snippet = 3; + + // Contains snippets of text from the [Job.description][google.cloud.talent.v4beta1.Job.description] and similar + // fields that most closely match a search query's keywords, if available. + // All HTML tags in the original fields are stripped when returned in this + // field, and matching query keywords are enclosed in HTML bold tags. + string search_text_snippet = 4; + + // Commute information which is generated based on specified + // [CommuteFilter][google.cloud.talent.v4beta1.CommuteFilter]. + CommuteInfo commute_info = 5; + } + + // Output only. + // + // Commute details related to this job. + message CommuteInfo { + // Location used as the destination in the commute calculation. + Location job_location = 1; + + // The number of seconds required to travel to the job location from the + // query location. A duration of 0 seconds indicates that the job isn't + // reachable within the requested duration, but was returned as part of an + // expanded query. + google.protobuf.Duration travel_duration = 2; + } + + // The Job entities that match the specified [SearchJobsRequest][google.cloud.talent.v4beta1.SearchJobsRequest]. + repeated MatchingJob matching_jobs = 1; + + // The histogram results that match with specified + // [SearchJobsRequest.histogram_queries][google.cloud.talent.v4beta1.SearchJobsRequest.histogram_queries]. + repeated HistogramQueryResult histogram_query_results = 2; + + // The token that specifies the starting position of the next page of results. + // This field is empty if there are no more results. + string next_page_token = 3; + + // The location filters that the service applied to the specified query. If + // any filters are lat-lng based, the [JobLocation.location_type][] is + // [JobLocation.LocationType#LOCATION_TYPE_UNSPECIFIED][]. + repeated Location location_filters = 4; + + // An estimation of the number of jobs that match the specified query. + // + // This number isn't guaranteed to be accurate. For accurate results, + // see [enable_precise_result_size][]. + int32 estimated_total_size = 5; + + // The precise result count, which is available only if the client set + // [enable_precise_result_size][] to `true`, or if the response + // is the last page of results. Otherwise, the value is `-1`. + int32 total_size = 6; + + // Additional information for the API invocation, such as the request + // tracking id. + ResponseMetadata metadata = 7; + + // If query broadening is enabled, we may append additional results from the + // broadened query. This number indicates how many of the jobs returned in the + // jobs field are from the broadened query. These results are always at the + // end of the jobs list. In particular, a value of 0, or if the field isn't + // set, all the jobs in the jobs list are from the original + // (without broadening) query. If this field is non-zero, subsequent requests + // with offset after this result set should contain all broadened results. + int32 broadened_query_jobs_count = 8; + + // The spell checking result, and correction. + SpellingCorrection spell_correction = 9; +} diff --git a/google/cloud/talent/v4beta1/profile.proto b/google/cloud/talent/v4beta1/profile.proto new file mode 100644 index 000000000..58a69c1d4 --- /dev/null +++ b/google/cloud/talent/v4beta1/profile.proto @@ -0,0 +1,852 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/common.proto"; +import "google/cloud/talent/v4beta1/job.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "google/type/date.proto"; +import "google/type/postal_address.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "ProfileResourceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// Cloud Profile Discovery API definition + +// A resource that represents the profile for a job candidate (also referred to +// as a "single-source profile"). A profile belongs to a [Company][google.cloud.talent.v4beta1.Company], which is +// the company/organization that owns the profile. +message Profile { + // Required during profile update. + // + // Resource name assigned to a profile by the API. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}", + // for example, "projects/api-test-project/tenants/foo/profiles/bar". + string name = 1; + + // Optional. + // + // Profile's id in client system if available. + // + // The maximum number of bytes allowed is 100. + string external_id = 2; + + // Optional. + // + // The source description indicating where the profile is acquired. + // + // For example, if a candidate profile is acquired from a resume, the user can + // input "resume" here to indicate the source. + // + // The maximum number of bytes allowed is 100. + string source = 3; + + // Optional. + // + // The URI set by clients that links to this profile's client-side copy. + // + // The maximum number of bytes allowed is 4000. + string uri = 4; + + // Optional. + // + // The cluster id of the profile to associate with other profile(s) for the + // same candidate. + // + // A random UUID is assigned if [group_id][google.cloud.talent.v4beta1.Profile.group_id] isn't provided. To ensure + // global uniqueness, customized [group_id][google.cloud.talent.v4beta1.Profile.group_id] isn't supported. If + // [group_id][google.cloud.talent.v4beta1.Profile.group_id] is set, there must be at least one other profile with the + // same system generated [group_id][google.cloud.talent.v4beta1.Profile.group_id], otherwise an error is thrown. + // + // This is used to link multiple profiles to the same candidate. For example, + // a client has a candidate with two profiles, where one was created recently + // and the other one was created 5 years ago. These two profiles may be very + // different. The clients can create the first profile and get a generated + // [group_id][google.cloud.talent.v4beta1.Profile.group_id], and assign it when the second profile is created, + // indicating these two profiles are referring to the same candidate. + string group_id = 5; + + // Optional. + // + // Indicates the hirable status of the candidate. + google.protobuf.BoolValue is_hirable = 6; + + // Optional. + // + // The timestamp when the profile was first created at this source. + google.protobuf.Timestamp create_time = 7; + + // Optional. + // + // The timestamp when the profile was last updated at this source. + google.protobuf.Timestamp update_time = 8; + + // Optional. + // + // The profile contents in HR-XML format. + // See http://schemas.liquid-technologies.com/hr-xml/2007-04-15/ for more + // information about Human Resources XML. + // + // Users can create a profile with only [resume_hrxml][google.cloud.talent.v4beta1.Profile.resume_hrxml] field. For example, + // the API parses the [resume_hrxml][google.cloud.talent.v4beta1.Profile.resume_hrxml] and creates a profile with all + // structured fields populated, for example. [EmploymentRecord][google.cloud.talent.v4beta1.EmploymentRecord], + // [EducationRecord][google.cloud.talent.v4beta1.EducationRecord], and so on. An error is thrown if the [resume_hrxml][google.cloud.talent.v4beta1.Profile.resume_hrxml] + // can't be parsed. + // + // If the [resume_hrxml][google.cloud.talent.v4beta1.Profile.resume_hrxml] is provided during profile creation or update, + // any other structured data provided in the profile is ignored. The + // API populates these fields by parsing the HR-XML. + string resume_hrxml = 10; + + // Optional. + // + // The names of the candidate this profile references. + // + // Currently only one person name is supported. + repeated PersonName person_names = 11; + + // Optional. + // + // The candidate's postal addresses. + repeated Address addresses = 12; + + // Optional. + // + // The candidate's email addresses. + repeated Email email_addresses = 13; + + // Optional. + // + // The candidate's phone number(s). + repeated Phone phone_numbers = 14; + + // Optional. + // + // The candidate's personal URIs. + repeated PersonalUri personal_uris = 15; + + // Optional. + // + // Available contact information besides [addresses][google.cloud.talent.v4beta1.Profile.addresses], [email_addresses][google.cloud.talent.v4beta1.Profile.email_addresses], + // [phone_numbers][google.cloud.talent.v4beta1.Profile.phone_numbers] and [personal_uris][google.cloud.talent.v4beta1.Profile.personal_uris]. For example, Hang-out, Skype. + repeated AdditionalContactInfo additional_contact_info = 16; + + // Optional. + // + // The employment history records of the candidate. It's highly recommended + // to input this information as accurately as possible to help improve search + // quality. Here are some recommendations: + // + // * Specify the start and end dates of the employment records. + // * List different employment types separately, no matter how minor the + // change is. + // For example, only job title is changed from "software engineer" to "senior + // software engineer". + // * Provide [EmploymentRecord.is_current][google.cloud.talent.v4beta1.EmploymentRecord.is_current] for the current employment if + // possible. If not, it's inferred from user inputs. + repeated EmploymentRecord employment_records = 17; + + // Optional. + // + // The education history record of the candidate. It's highly recommended to + // input this information as accurately as possible to help improve search + // quality. Here are some recommendations: + // + // * Specify the start and end dates of the education records. + // * List each education type separately, no matter how minor the change is. + // For example, the profile contains the education experience from the same + // school but different degrees. + // * Provide [EducationRecord.is_current][google.cloud.talent.v4beta1.EducationRecord.is_current] for the current education if + // possible. If not, it's inferred from user inputs. + repeated EducationRecord education_records = 18; + + // Optional. + // + // The skill set of the candidate. It's highly recommended to provide as + // much information as possible to help improve the search quality. + repeated Skill skills = 19; + + // Optional. + // + // The individual or collaborative activities which the candidate has + // participated in, for example, open-source projects, class assignments that + // aren't listed in [employment_records][google.cloud.talent.v4beta1.Profile.employment_records]. + repeated Activity activities = 20; + + // Optional. + // + // The publications published by the candidate. + repeated Publication publications = 21; + + // Optional. + // + // The patents acquired by the candidate. + repeated Patent patents = 22; + + // Optional. + // + // The certifications acquired by the candidate. + repeated Certification certifications = 23; + + // Output only. The resource names of the candidate's applications. + repeated string applications = 47; + + // Output only. The resource names of the candidate's assignments. + repeated string assignments = 48; + + // Optional. + // + // A map of fields to hold both filterable and non-filterable custom profile + // attributes that aren't covered by the provided structured fields. See + // [CustomAttribute][google.cloud.talent.v4beta1.CustomAttribute] for more details. + // + // At most 100 filterable and at most 100 unfilterable keys are supported. If + // limit is exceeded, an error is thrown. Custom attributes are `unfilterable` + // by default. These are filterable when the `filterable` flag is set to + // `true`. + // + // Numeric custom attributes: each key can only map to one numeric value, + // otherwise an error is thrown. Client can also filter on numeric custom + // attributes using '>', '<' or '=' operators. + // + // String custom attributes: each key can map up to 50 string values. For + // filterable string value, each value has a byte size of no more than 256B. + // For unfilterable string values, the maximum byte size of a single key is + // 64B. An error is thrown for any request exceeding the limit. + // The maximum total byte size is 10KB. + map<string, CustomAttribute> custom_attributes = 26; + + // Output only. Indicates if the profile is fully processed and searchable. + bool processed = 27; + + // Output only. Keyword snippet shows how the search result is related to a + // search query. + string keyword_snippet = 28; +} + +// Resource that represents the name of a person. +message PersonName { + // Resource that represents a person's structured name. + message PersonStructuredName { + // Optional. + // + // Given/first name. + // + // It's derived from [formatted_name][google.cloud.talent.v4beta1.PersonName.formatted_name] if not provided. + // + // Number of characters allowed is 100. + string given_name = 1; + + // Optional. + // + // Middle initial. + // + // It's derived from [formatted_name][google.cloud.talent.v4beta1.PersonName.formatted_name] if not provided. + // + // Number of characters allowed is 20. + string middle_initial = 2; + + // Optional. + // + // Family/last name. + // + // It's derived from [formatted_name][google.cloud.talent.v4beta1.PersonName.formatted_name] if not provided. + // + // Number of characters allowed is 100. + string family_name = 3; + + // Optional. + // + // Suffixes. + // + // Number of characters allowed is 20. + repeated string suffixes = 4; + + // Optional. + // + // Prefixes. + // + // Number of characters allowed is 20. + repeated string prefixes = 5; + } + + // The name of a person. It can be one of [formatted_name][] or + // [structured_name][]. + oneof person_name { + // Optional. + // + // A string represents a person's full name. For example, "Dr. John Smith". + // + // Number of characters allowed is 100. + string formatted_name = 1; + + // Optional. + // + // A person's name in a structured way (last name, first name, suffix, and + // so on.) + PersonStructuredName structured_name = 2; + } + + // Optional. + // + // Preferred name for the person. + string preferred_name = 3; +} + +// Resource that represents a address. +message Address { + // Optional. + // + // The usage of the address. For example, SCHOOL, WORK, PERSONAL. + ContactInfoUsage usage = 1; + + // The address of a person. It can be one of [unstructured_address][] or + // [structured_address][]. + oneof address { + // Optional. + // + // Unstructured address. + // + // For example, "1600 Amphitheatre Pkwy, Mountain View, CA 94043", + // "Sunnyvale, California". + // + // Number of characters allowed is 100. + string unstructured_address = 2; + + // Optional. + // + // Structured address that contains street address, city, state, country, + // and so on. + google.type.PostalAddress structured_address = 3; + } + + // Optional. + // + // Indicates if it's the person's current address. + google.protobuf.BoolValue current = 4; +} + +// Resource that represents a person's email address. +message Email { + // Optional. + // + // The usage of the email address. For example, SCHOOL, WORK, PERSONAL. + ContactInfoUsage usage = 1; + + // Optional. + // + // Email address. + // + // Number of characters allowed is 4,000. + string email_address = 2; +} + +// Resource that represents a person's telephone number. +message Phone { + // Enum that represents the type of the telephone. + enum PhoneType { + // Default value. + PHONE_TYPE_UNSPECIFIED = 0; + + // A landline. + LANDLINE = 1; + + // A mobile. + MOBILE = 2; + + // A fax. + FAX = 3; + + // A pager. + PAGER = 4; + + // A TTY (test telephone) or TDD (telecommunication device for the deaf). + TTY_OR_TDD = 5; + + // A voicemail. + VOICEMAIL = 6; + + // A virtual telephone number is a number that can be routed to another + // number and managed by the user via Web, SMS, IVR, and so on. It is + // associated with a particular person, and may be routed to either a MOBILE + // or LANDLINE number. The phone usage (see ContactInfoUsage above) should + // be set to PERSONAL for these phone types. Some more information can be + // found here: http://en.wikipedia.org/wiki/Personal_Numbers + VIRTUAL = 7; + + // Voice over IP numbers. This includes TSoIP (Telephony Service over IP). + VOIP = 8; + + // In some regions (e.g. the USA), it is impossible to distinguish between + // fixed-line and mobile numbers by looking at the phone number itself. + MOBILE_OR_LANDLINE = 9; + } + + // Optional. + // + // The usage of the phone. For example, SCHOOL, WORK, PERSONAL. + ContactInfoUsage usage = 1; + + // Optional. + // + // The phone type. For example, LANDLINE, MOBILE, FAX. + PhoneType type = 2; + + // Optional. + // + // Phone number. + // + // Any phone formats are supported and only exact matches are performed on + // searches. For example, if a phone number in profile is provided in the + // format of "(xxx)xxx-xxxx", in profile searches the same phone format + // has to be provided. + // + // Number of characters allowed is 20. + string number = 3; + + // Optional. + // + // When this number is available. Any descriptive string is expected. + // + // Number of characters allowed is 100. + string when_available = 4; +} + +// Resource that represents a valid URI for a personal use. +message PersonalUri { + // Optional. + // + // The personal URI. + // + // Number of characters allowed is 4,000. + string uri = 1; +} + +// Resource that represents contact information other than phone, email, +// URI and addresses. +message AdditionalContactInfo { + // Optional. + // + // The usage of this contact method. For example, SCHOOL, WORK, PERSONAL. + ContactInfoUsage usage = 1; + + // Optional. + // + // The name of the contact method. + // + // For example, "hangout", "skype". + // + // Number of characters allowed is 100. + string name = 2; + + // Optional. + // + // The contact id. + // + // Number of characters allowed is 100. + string contact_id = 3; +} + +// Resource that represents an employment record of a candidate. +message EmploymentRecord { + // Optional. + // + // Start date of the employment. + // + // It can be a partial date (only year, or only year and month), but must be + // valid. Otherwise an error is thrown. + // + // Examples: + // {"year": 2017, "month": 2, "day": 28} is valid. + // {"year": 2020, "month": 1, "date": 31} is valid. + // {"year": 2018, "month": 12} is valid (partial date). + // {"year": 2018} is valid (partial date). + // {"year": 2015, "day": 21} is not valid (month is missing but day is + // presented). + // {"year": 2018, "month": 13} is not valid (invalid month). + // {"year": 2017, "month": 1, "day": 32} is not valid (invalid day). + google.type.Date start_date = 1; + + // Optional. + // + // End date of the employment. + google.type.Date end_date = 2; + + // Optional. + // + // The name of the employer company/organization. + // + // For example, "Google", "Alphabet", and so on. + // + // Number of characters allowed is 100. + string employer_name = 3; + + // Optional. + // + // The division name of the employment. + // + // For example, division, department, client, and so on. + // + // Number of characters allowed is 100. + string division_name = 4; + + // Optional. + // + // The physical address of the employer. + Address address = 5; + + // Optional. + // + // The job title of the employment. + // + // For example, "Software Engineer", "Data Scientist", and so on. + // + // Number of characters allowed is 100. + string job_title = 6; + + // Optional. + // + // The description of job content. + // + // Number of characters allowed is 100,000. + string job_description = 7; + + // Optional. + // + // If the jobs is a supervisor position. + google.protobuf.BoolValue is_supervisor = 8; + + // Optional. + // + // If this employment is self-employed. + google.protobuf.BoolValue is_self_employed = 9; + + // Optional. + // + // If this employment is current. + google.protobuf.BoolValue is_current = 10; + + // Output only. The job title snippet shows how the [job_title][google.cloud.talent.v4beta1.EmploymentRecord.job_title] is related + // to a search query. It's empty if the [job_title][google.cloud.talent.v4beta1.EmploymentRecord.job_title] isn't related to the + // search query. + string job_title_snippet = 11; + + // Output only. The job description snippet shows how the [job_description][google.cloud.talent.v4beta1.EmploymentRecord.job_description] + // is related to a search query. It's empty if the [job_description][google.cloud.talent.v4beta1.EmploymentRecord.job_description] isn't + // related to the search query. + string job_description_snippet = 12; + + // Output only. The employer name snippet shows how the [employer_name][google.cloud.talent.v4beta1.EmploymentRecord.employer_name] is + // related to a search query. It's empty if the [employer_name][google.cloud.talent.v4beta1.EmploymentRecord.employer_name] isn't + // related to the search query. + string employer_name_snippet = 13; +} + +// Resource that represents an education record of a candidate. +message EducationRecord { + // Optional. + // + // The start date of the education. + google.type.Date start_date = 1; + + // Optional. + // + // The end date of the education. + google.type.Date end_date = 2; + + // Optional. + // + // The expected graduation date if currently pursuing a degree. + google.type.Date expected_graduation_date = 3; + + // Optional. + // + // The name of the school or institution. + // + // For example, "Stanford University", "UC Berkeley", and so on. + // + // Number of characters allowed is 100. + string school_name = 4; + + // Optional. + // + // The physical address of the education institution. + Address address = 5; + + // The degree information. It can be one of [degree_description][] or + // [structured_degree][]. + oneof degree { + // Optional. + // + // The full description of the degree. + // + // For example, "Master of Science in Computer Science", "B.S in Math". + // + // Number of characters allowed is 100. + string degree_description = 6; + + // Optional. + // + // The structured notation of the degree. + Degree structured_degree = 7; + } + + // Optional. + // + // The description of the education. + // + // Number of characters allowed is 100,000. + string description = 8; + + // Optional. + // + // If this education is current. + google.protobuf.BoolValue is_current = 9; + + // Output only. The school name snippet shows how the [school_name][google.cloud.talent.v4beta1.EducationRecord.school_name] is + // related to a search query in search result. It's empty if the + // [school_name][google.cloud.talent.v4beta1.EducationRecord.school_name] isn't related to the search query. + string school_name_snippet = 10; + + // Output only. The job description snippet shows how the [degree][google.cloud.talent.v4beta1.degree] is + // related to a search query in search result. It's empty if the [degree][google.cloud.talent.v4beta1.degree] + // isn't related to the search query. + string degree_snippet = 11; +} + +// Resource that represents a degree pursuing or acquired by a candidate. +message Degree { + // Optional. + // + // ISCED degree type. + DegreeType degree_type = 1; + + // Optional. + // + // Full Degree name. + // + // For example, "B.S.", "Master of Arts", and so on. + // + // Number of characters allowed is 100. + string degree_name = 2; + + // Optional. + // + // Fields of study for the degree. + // + // For example, "Computer science", "engineering". + // + // Number of characters allowed is 100. + repeated string fields_of_study = 3; +} + +// Resource that represents an individual or collaborative activity participated +// in by a candidate, for example, an open-source project, a class assignment, +// and so on. +message Activity { + // Optional. + // + // Activity display name. + // + // Number of characters allowed is 100. + string display_name = 1; + + // Optional. + // + // Activity description. + // + // Number of characters allowed is 100,000. + string description = 2; + + // Optional. + // + // Activity URI. + // + // Number of characters allowed is 4,000. + string uri = 3; + + // Optional. + // + // The first creation date of the activity. + google.type.Date create_date = 4; + + // Optional. + // + // The last update date of the activity. + google.type.Date update_date = 5; + + // Optional. + // + // A list of team members involved in this activity. + // + // Number of characters allowed is 100. + repeated string team_members = 6; + + // Optional. + // + // A list of skills used in this activity. + repeated Skill skills_used = 7; + + // Output only. Activity name snippet shows how the [display_name][google.cloud.talent.v4beta1.Activity.display_name] is + // related to a search query. It's empty if the [display_name][google.cloud.talent.v4beta1.Activity.display_name] isn't related + // to the search query. + string activity_name_snippet = 8; + + // Output only. Activity description snippet shows how the + // [description][google.cloud.talent.v4beta1.Activity.description] is related to a search query. It's empty if the + // [description][google.cloud.talent.v4beta1.Activity.description] isn't related to the search query. + string activity_description_snippet = 9; + + // Output only. Skill used snippet shows how the corresponding + // [skills_used][google.cloud.talent.v4beta1.Activity.skills_used] are related to a search query. It's empty if the + // corresponding [skills_used][google.cloud.talent.v4beta1.Activity.skills_used] are not related to the search query. + repeated string skills_used_snippet = 10; +} + +// Resource that represents a publication resource of a candidate. +message Publication { + // Optional. + // + // A list of author names. + // + // Number of characters allowed is 100. + repeated string authors = 1; + + // Optional. + // + // The title of the publication. + // + // Number of characters allowed is 100. + string title = 2; + + // Optional. + // + // The description of the publication. + // + // Number of characters allowed is 100,000. + string description = 3; + + // Optional. + // + // The journal name of the publication. + // + // Number of characters allowed is 100. + string journal = 4; + + // Optional. + // + // Volume number. + // + // Number of characters allowed is 100. + string volume = 5; + + // Optional. + // + // The publisher of the journal. + // + // Number of characters allowed is 100. + string publisher = 6; + + // Optional. + // + // The publication date. + google.type.Date publication_date = 7; + + // Optional. + // + // The publication type. + // + // Number of characters allowed is 100. + string publication_type = 8; + + // Optional. + // + // ISBN number. + // + // Number of characters allowed is 100. + string isbn = 9; +} + +// Resource that represents the patent acquired by a candidate. +message Patent { + // Optional. + // + // Name of the patent. + // + // Number of characters allowed is 100. + string display_name = 1; + + // Optional. + // + // A list of inventors' names. + // + // Number of characters allowed for each is 100. + repeated string inventors = 2; + + // Optional. + // + // The status of the patent. + // + // Number of characters allowed is 100. + string patent_status = 3; + + // Optional. + // + // The date the last time the status of the patent was checked. + google.type.Date patent_status_date = 4; + + // Optional. + // + // The date that the patent was filed. + google.type.Date patent_filing_date = 5; + + // Optional. + // + // The name of the patent office. + // + // Number of characters allowed is 100. + string patent_office = 6; + + // Optional. + // + // The number of the patent. + // + // Number of characters allowed is 100. + string patent_number = 7; + + // Optional. + // + // The description of the patent. + // + // Number of characters allowed is 100,000. + string patent_description = 8; + + // Optional. + // + // The skills used in this patent. + repeated Skill skills_used = 9; +} diff --git a/google/cloud/talent/v4beta1/profile_service.proto b/google/cloud/talent/v4beta1/profile_service.proto new file mode 100644 index 000000000..c692df46d --- /dev/null +++ b/google/cloud/talent/v4beta1/profile_service.proto @@ -0,0 +1,441 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/common.proto"; +import "google/cloud/talent/v4beta1/filters.proto"; +import "google/cloud/talent/v4beta1/histogram.proto"; +import "google/cloud/talent/v4beta1/profile.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "ProfileServiceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A service that handles profile management, including profile CRUD, +// enumeration and search. +service ProfileService { + // Lists profiles by filter. The order is unspecified. + rpc ListProfiles(ListProfilesRequest) returns (ListProfilesResponse) { + option (google.api.http) = { + get: "/v4beta1/{parent=projects/*/tenants/*}/profiles" + }; + } + + // Creates and returns a new profile. + rpc CreateProfile(CreateProfileRequest) returns (Profile) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}/profiles" + body: "*" + }; + } + + // Gets the specified profile. + rpc GetProfile(GetProfileRequest) returns (Profile) { + option (google.api.http) = { + get: "/v4beta1/{name=projects/*/tenants/*/profiles/*}" + }; + } + + // Updates the specified profile and returns the updated result. + rpc UpdateProfile(UpdateProfileRequest) returns (Profile) { + option (google.api.http) = { + patch: "/v4beta1/{profile.name=projects/*/tenants/*/profiles/*}" + body: "*" + }; + } + + // Deletes the specified profile. + // Prerequisite: The profile has no associated applications or assignments + // associated. + rpc DeleteProfile(DeleteProfileRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v4beta1/{name=projects/*/tenants/*/profiles/*}" + }; + } + + // Searches for profiles within a tenant. + // + // For example, search by raw queries "software engineer in Mountain View" or + // search by structured filters (location filter, education filter, etc.). + // + // See [SearchProfilesRequest][google.cloud.talent.v4beta1.SearchProfilesRequest] for more information. + rpc SearchProfiles(SearchProfilesRequest) returns (SearchProfilesResponse) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*/tenants/*}:search" + body: "*" + }; + } +} + +// List profiles request. +message ListProfilesRequest { + // Required. + // + // The resource name of the tenant under which the job is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenants/foo". + string parent = 1; + + // Optional. + // + // The token that specifies the current offset (that is, starting result). + // + // Please set the value to [ListProfilesResponse.next_page_token][google.cloud.talent.v4beta1.ListProfilesResponse.next_page_token] to + // continue the list. + string page_token = 2; + + // Optional. + // + // The maximum number of profiles to be returned, at most 100. + // + // Default is 100 unless a positive number smaller than 100 is specified. + int32 page_size = 3; + + // Optional. + // + // A field mask to specify the profile fields to be listed in response. + // All fields are listed if it is unset. + // + // Valid values are: + // + // * name + google.protobuf.FieldMask read_mask = 4; +} + +// The List profiles response object. +message ListProfilesResponse { + // Profiles for the specific tenant. + repeated Profile profiles = 1; + + // A token to retrieve the next page of results. This is empty if there are no + // more results. + string next_page_token = 2; +} + +// Create profile request. +message CreateProfileRequest { + // Required. + // + // The name of the tenant this profile belongs to. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenants/foo". + string parent = 1; + + // Required. + // + // The profile to be created. + Profile profile = 2; +} + +// Get profile request. +message GetProfileRequest { + // Required. + // + // Resource name of the profile to get. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}", + // for example, "projects/api-test-project/tenants/foo/profiles/bar". + string name = 1; +} + +// Update profile request +message UpdateProfileRequest { + // Required. + // + // Profile to be updated. + Profile profile = 1; + + // Optional. + // + // A field mask to specify the profile fields to update. + // + // A full update is performed if it is unset. + // + // Valid values are: + // + // * externalId + // * source + // * uri + // * isHirable + // * createTime + // * updateTime + // * resumeHrxml + // * personNames + // * addresses + // * emailAddresses + // * phoneNumbers + // * personalUris + // * additionalContactInfo + // * employmentRecords + // * educationRecords + // * skills + // * projects + // * publications + // * patents + // * certifications + // * recruitingNotes + // * customAttributes + // * groupId + google.protobuf.FieldMask update_mask = 2; +} + +// Delete profile request. +message DeleteProfileRequest { + // Required. + // + // Resource name of the profile to be deleted. + // + // The format is + // "projects/{project_id}/tenants/{tenant_id}/profiles/{profile_id}", + // for example, "projects/api-test-project/tenants/foo/profiles/bar". + string name = 1; +} + +// The request body of the `SearchProfiles` call. +message SearchProfilesRequest { + // Required. + // + // The resource name of the tenant to search within. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenants/foo". + string parent = 1; + + // Required. + // + // The meta information collected about the profile search user. This is used + // to improve the search quality of the service. These values are provided by + // users, and must be precise and consistent. + RequestMetadata request_metadata = 2; + + // Optional. + // + // Search query to execute. See [ProfileQuery][google.cloud.talent.v4beta1.ProfileQuery] for more details. + ProfileQuery profile_query = 3; + + // Optional. + // + // A limit on the number of profiles returned in the search results. + // A value above the default value 10 can increase search response time. + // + // The maximum value allowed is 100. Otherwise an error is thrown. + int32 page_size = 4; + + // Optional. + // + // The pageToken, similar to offset enables users of the API to paginate + // through the search results. To retrieve the first page of results, set the + // pageToken to empty. The search response includes a + // [nextPageToken][google.cloud.talent.v4beta1.SearchProfilesResponse.next_page_token] field that can be + // used to populate the pageToken field for the next page of results. Using + // pageToken instead of offset increases the performance of the API, + // especially compared to larger offset values. + string page_token = 5; + + // Optional. + // + // An integer that specifies the current offset (that is, starting result) in + // search results. This field is only considered if [page_token][google.cloud.talent.v4beta1.SearchProfilesRequest.page_token] is unset. + // + // The maximum allowed value is 5000. Otherwise an error is thrown. + // + // For example, 0 means to search from the first profile, and 10 means to + // search from the 11th profile. This can be used for pagination, for example + // pageSize = 10 and offset = 10 means to search from the second page. + int32 offset = 6; + + // Optional. + // + // This flag controls the spell-check feature. If `false`, the + // service attempts to correct a misspelled query. + // + // For example, "enginee" is corrected to "engineer". + bool disable_spell_check = 7; + + // Optional. + // + // The criteria that determines how search results are sorted. + // Defaults is "relevance desc" if no value is specified. + // + // Supported options are: + // + // * "relevance desc": By descending relevance, as determined by the API + // algorithms. + // * "update_date desc": Sort by [Profile.update_date][] in descending order + // (recently updated profiles first). + // * "create_date desc": Sort by [Profile.create_date][] in descending order + // (recently created profiles first). + // * "first_name": Sort by [PersonStrcuturedName.given_name][] in ascending + // order. + // * "first_name desc": Sort by [PersonStrcuturedName.given_name][] in + // descending order. + // * "last_name": Sort by [PersonStrcuturedName.family_name][] in ascending + // order. + // * "last_name desc": Sort by [PersonStrcuturedName.family_name][] in + // ascending order. + string order_by = 8; + + // Optional. + // + // When sort by field is based on alphabetical order, sort values case + // sensitively (based on ASCII) when the value is set to true. Default value + // is case in-sensitive sort (false). + bool case_sensitive_sort = 9; + + // Optional. + // + // A list of expressions specifies histogram requests against matching + // profiles for [SearchProfilesRequest][google.cloud.talent.v4beta1.SearchProfilesRequest]. + // + // The expression syntax looks like a function definition with optional + // parameters. + // + // Function syntax: function_name(histogram_facet[, list of buckets]) + // + // Data types: + // + // * Histogram facet: facet names with format [a-zA-Z][a-zA-Z0-9_]+. + // * String: string like "any string with backslash escape for quote(\")." + // * Number: whole number and floating point number like 10, -1 and -0.01. + // * List: list of elements with comma(,) separator surrounded by square + // brackets. For example, [1, 2, 3] and ["one", "two", "three"]. + // + // Built-in constants: + // + // * MIN (minimum number similar to java Double.MIN_VALUE) + // * MAX (maximum number similar to java Double.MAX_VALUE) + // + // Built-in functions: + // + // * bucket(start, end[, label]) + // Bucket build-in function creates a bucket with range of [start, end). Note + // that the end is exclusive. + // For example, bucket(1, MAX, "positive number") or bucket(1, 10). + // + // Histogram Facets: + // + // * admin1: Admin1 is a global placeholder for referring to state, province, + // or the particular term a country uses to define the geographic structure + // below the country level. Examples include states codes such as "CA", "IL", + // "NY", and provinces, such as "BC". + // * locality: Locality is a global placeholder for referring to city, town, + // or the particular term a country uses to define the geographic structure + // below the admin1 level. Examples include city names such as + // "Mountain View" and "New York". + // * extended_locality: Extended locality is concatenated version of admin1 + // and locality with comma separator. For example, "Mountain View, CA" and + // "New York, NY". + // * postal_code: Postal code of profile which follows locale code. + // * country: Country code (ISO-3166-1 alpha-2 code) of profile, such as US, + // JP, GB. + // * job_title: Normalized job titles specified in EmploymentHistory. + // * company_name: Normalized company name of profiles to match on. + // * institution: The school name. For example, "MIT", + // "University of California, Berkeley" + // * degree: Highest education degree in ISCED code. Each value in degree + // covers a specific level of education, without any expansion to upper nor + // lower levels of education degree. + // * experience_in_months: experience in months. 0 means 0 month to 1 month + // (exclusive). + // * application_date: The application date specifies application start dates. + // See [ApplicationDateFilter][google.cloud.talent.v4beta1.ApplicationDateFilter] for more details. + // * application_outcome_notes: The application outcome reason specifies the + // reasons behind the outcome of the job application. + // See [ApplicationOutcomeNotesFilter][google.cloud.talent.v4beta1.ApplicationOutcomeNotesFilter] for more details. + // * application_last_stage: The application last stage specifies the last + // stage of job application. + // See [ApplicationLastStageFilter][] for more details. + // * application_job_title: The application job title specifies the job + // applied for in the application. + // See [ApplicationJobFilter][google.cloud.talent.v4beta1.ApplicationJobFilter] for more details. + // * application_status: The application status specifies the status of job + // application. + // See [ApplicationStatusFilter][] for more details. + // * hirable_status: Hirable status specifies the profile's hirable status. + // * string_custom_attribute: String custom attributes. Values can be accessed + // via square bracket notation like string_custom_attribute["key1"]. + // * numeric_custom_attribute: Numeric custom attributes. Values can be + // accessed via square bracket notation like numeric_custom_attribute["key1"]. + // + // Example expressions: + // + // * count(admin1) + // * count(experience_in_months, [bucket(0, 12, "1 year"), + // bucket(12, 36, "1-3 years"), bucket(36, MAX, "3+ years")]) + // * count(string_custom_attribute["assigned_recruiter"]) + // * count(numeric_custom_attribute["favorite_number"], + // [bucket(MIN, 0, "negative"), bucket(0, MAX, "non-negative")]) + repeated HistogramQuery histogram_queries = 10; +} + +// Response of SearchProfiles method. +message SearchProfilesResponse { + // An estimation of the number of profiles that match the specified query. + // + // This number isn't guaranteed to be accurate. + int64 estimated_total_size = 1; + + // The spell checking result, and correction. + SpellingCorrection spell_correction = 2; + + // Additional information for the API invocation, such as the request + // tracking id. + ResponseMetadata metadata = 3; + + // A token to retrieve the next page of results. This is empty if there are no + // more results. + string next_page_token = 4; + + // The histogram results that match with specified + // [SearchProfilesRequest.histogram_queries][google.cloud.talent.v4beta1.SearchProfilesRequest.histogram_queries]. + repeated HistogramQueryResult histogram_query_results = 5; + + // The profile entities that match the specified [SearchProfilesRequest][google.cloud.talent.v4beta1.SearchProfilesRequest]. + repeated SummarizedProfile summarized_profiles = 6; +} + +// Output only. +// +// Profile entry with metadata inside [SearchProfilesResponse][google.cloud.talent.v4beta1.SearchProfilesResponse]. +message SummarizedProfile { + // A list of profiles that are linked by [Profile.cluster_id][]. + repeated Profile profiles = 1; + + // A profile summary shows the profile summary and how the profile matches the + // search query. + // + // In profile summary, the profiles with the same [Profile.cluster_id][] are + // merged together. Among profiles, same education/employment records may be + // slightly different but they are merged into one with best efforts. + // + // For example, in one profile the school name is "UC Berkeley" and the field + // study is "Computer Science" and in another one the school name is + // "University of California at Berkeley" and the field study is "CS". The API + // merges these two inputs into one and selects one value for each field. For + // example, the school name in summary is set to "University of California at + // Berkeley" and the field of study is set to "Computer Science". + Profile summary = 2; +} diff --git a/google/cloud/talent/v4beta1/talent_gapic.yaml b/google/cloud/talent/v4beta1/talent_gapic.yaml new file mode 100644 index 000000000..c90b98d39 --- /dev/null +++ b/google/cloud/talent/v4beta1/talent_gapic.yaml @@ -0,0 +1,1150 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.talent.v4beta1 + python: + package_name: google.cloud.talent_v4beta1.gapic + go: + package_name: cloud.google.com/go/talent/apiv4beta1 + csharp: + package_name: Google.Cloud.Talent.V4Beta1 + ruby: + package_name: Google::Cloud::Talent::V4beta1 + php: + package_name: Google\Cloud\Talent\V4beta1 + nodejs: + package_name: talent.v4beta1 + domain_layer_location: google-cloud +# A list of resource collection configurations. +# Consists of a name_pattern and an entity_name. +# The name_pattern is a pattern to describe the names of the resources of this +# collection, using the platform's conventions for URI patterns. A generator +# may use this to generate methods to compose and decompose such names. The +# pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; +# those will be taken as hints for the parameter names of the generated +# methods. If empty, no name methods are generated. +# The entity_name is the name to be used as a basis for generated methods and +# classes. +collections: +- name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName +- name_pattern: projects/{project}/companies/{company} + entity_name: company_old +- name_pattern: projects/{project}/tenants/{tenant}/companies/{company} + entity_name: company_new +- name_pattern: projects/{project}/jobs/{jobs} + entity_name: job_old +- name_pattern: projects/{project}/tenants/{tenant}/jobs/{jobs} + entity_name: job_new +- name_pattern: projects/{project}/tenants/{tenant}/profiles/{profile} + entity_name: profile +- name_pattern: projects/{project}/tenants/{tenant}/profiles/{profile}/applications/{application} + entity_name: application +- name_pattern: projects/{project}/tenants/{tenant} + entity_name: tenant + +collection_oneofs: +- oneof_name: company_oneof + collection_names: + - company_old + - company_new +- oneof_name: job_oneof + collection_names: + - job_old + - job_new +- oneof_name: tenant_or_project + collection_names: + - tenant + - project + +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.talent.v4beta1.ApplicationService + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateApplication + flattening: + groups: + - parameters: + - parent + - application + required_fields: + - parent + - application + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: profile + timeout_millis: 30000 + - name: GetApplication + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: application + timeout_millis: 30000 + - name: UpdateApplication + flattening: + groups: + - parameters: + - application + required_fields: + - application + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + application.name: application + timeout_millis: 30000 + - name: DeleteApplication + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: application + timeout_millis: 30000 + - name: ListApplications + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: applications + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: profile + timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.talent.v4beta1.CompanyService + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateCompany + flattening: + groups: + - parameters: + - parent + - company + required_fields: + - parent + - company + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + timeout_millis: 30000 + - name: GetCompany + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: company_oneof + timeout_millis: 30000 + - name: UpdateCompany + flattening: + groups: + - parameters: + - company + required_fields: + - company + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + company.name: company_oneof + timeout_millis: 30000 + - name: DeleteCompany + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: company_oneof + timeout_millis: 30000 + - name: ListCompanies + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: companies + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.talent.v4beta1.Completion + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CompleteQuery + required_fields: + - parent + - query + - page_size + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + company: company_oneof + timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.talent.v4beta1.EventService + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateClientEvent + flattening: + groups: + - parameters: + - parent + - client_event + required_fields: + - parent + - client_event + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.talent.v4beta1.JobService + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateJob + flattening: + groups: + - parameters: + - parent + - job + required_fields: + - parent + - job + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + job.company: company_oneof + timeout_millis: 30000 + - name: GetJob + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job_oneof + timeout_millis: 30000 + - name: UpdateJob + flattening: + groups: + - parameters: + - job + required_fields: + - job + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + job.name: job_oneof + job.company: company_oneof + timeout_millis: 30000 + - name: DeleteJob + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: job_oneof + timeout_millis: 30000 + - name: ListJobs + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + - filter + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: jobs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + timeout_millis: 30000 + - name: BatchDeleteJobs + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + - filter + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + timeout_millis: 30000 + - name: SearchJobs + required_fields: + - parent + - request_metadata + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: matching_jobs + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + timeout_millis: 30000 + - name: SearchJobsForAlert + required_fields: + - parent + - request_metadata + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: matching_jobs + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant_or_project + timeout_millis: 30000 + # The fully qualified name of the API interface. +- name: google.cloud.talent.v4beta1.ProfileService + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListProfiles + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: profiles + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: tenant + timeout_millis: 30000 + - name: CreateProfile + flattening: + groups: + - parameters: + - parent + - profile + required_fields: + - parent + - profile + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant + timeout_millis: 30000 + - name: GetProfile + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: profile + timeout_millis: 30000 + - name: UpdateProfile + flattening: + groups: + - parameters: + - profile + required_fields: + - profile + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + profile.name: profile + timeout_millis: 30000 + - name: DeleteProfile + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: profile + timeout_millis: 30000 + - name: SearchProfiles + required_fields: + - parent + - request_metadata + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: histogram_query_results + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: tenant + timeout_millis: 30000 +# The fully qualified name of the API interface. +- name: google.cloud.talent.v4beta1.TenantService + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateTenant + flattening: + groups: + - parameters: + - parent + - tenant + required_fields: + - parent + - tenant + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 30000 + - name: GetTenant + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: tenant + timeout_millis: 30000 + - name: UpdateTenant + flattening: + groups: + - parameters: + - tenant + required_fields: + - tenant + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + tenant.name: tenant + timeout_millis: 30000 + - name: DeleteTenant + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: tenant + timeout_millis: 30000 + - name: ListTenants + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: tenants + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 30000 +resource_name_generation: +- message_name: Application + field_entity_map: + name: application +- message_name: CreateApplicationRequest + field_entity_map: + parent: profile +- message_name: GetApplicationRequest + field_entity_map: + name: application +- message_name: DeleteApplicationRequest + field_entity_map: + name: application +- message_name: ListApplicationsRequest + field_entity_map: + parent: profile +- message_name: Company + field_entity_map: + name: company_oneof +- message_name: CreateCompanyRequest + field_entity_map: + parent: tenant_or_project +- message_name: GetCompanyRequest + field_entity_map: + name: company_oneof +- message_name: DeleteCompanyRequest + field_entity_map: + name: company_oneof +- message_name: ListCompaniesRequest + field_entity_map: + parent: tenant_or_project +- message_name: CompleteQueryRequest + field_entity_map: + parent: tenant_or_project + company: company_oneof +- message_name: CreateClientEventRequest + field_entity_map: + parent: tenant_or_project +- message_name: Job + field_entity_map: + name: job_oneof + company: company_oneof +- message_name: CreateJobRequest + field_entity_map: + parent: tenant_or_project + job.company: company_oneof +- message_name: GetJobRequest + field_entity_map: + name: job_oneof +- message_name: DeleteJobRequest + field_entity_map: + name: job_oneof +- message_name: ListJobsRequest + field_entity_map: + parent: tenant_or_project +- message_name: BatchDeleteJobsRequest + field_entity_map: + parent: tenant_or_project +- message_name: SearchJobsRequest + field_entity_map: + parent: tenant_or_project +- message_name: SearchJobsForAlertRequest + field_entity_map: + parent: tenant_or_project +- message_name: Profile + field_entity_map: + name: profile +- message_name: CreateProfileRequest + field_entity_map: + parent: tenant +- message_name: GetProfileRequest + field_entity_map: + name: profile +- message_name: DeleteProfileRequest + field_entity_map: + name: profile +- message_name: ListProfilesRequest + field_entity_map: + parent: tenant +- message_name: SearchProfilesRequest + field_entity_map: + parent: tenant +- message_name: Tenant + field_entity_map: + name: tenant +- message_name: CreateTenantRequest + field_entity_map: + parent: project +- message_name: GetTenantRequest + field_entity_map: + name: tenant +- message_name: DeleteTenantRequest + field_entity_map: + name: tenant +- message_name: ListTenantsRequest + field_entity_map: + parent: project diff --git a/google/cloud/talent/v4beta1/tenant.proto b/google/cloud/talent/v4beta1/tenant.proto new file mode 100644 index 000000000..52104c440 --- /dev/null +++ b/google/cloud/talent/v4beta1/tenant.proto @@ -0,0 +1,71 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/cloud/talent/v4beta1/common.proto"; +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "TenantResourceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A Tenant resource represents a tenant in the service. A tenant is a group or +// entity that shares common access with specific privileges for resources like +// profiles. Customer may create multiple tenants to provide data isolation for +// different groups. +message Tenant { + // Enum that represents how user data owned by the tenant is used. + enum DataUsageType { + // Default value. + DATA_USAGE_TYPE_UNSPECIFIED = 0; + + // Data owned by this tenant is used to improve search/recommendation + // quality across tenants. + AGGREGATED = 1; + + // Data owned by this tenant is used to improve search/recommendation + // quality for this tenant only. + ISOLATED = 2; + } + + // Required during tenant update. + // + // The resource name for a tenant. This is generated by the service when a + // tenant is created. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenants/foo". + string name = 1; + + // Required. + // + // Client side tenant identifier, used to uniquely identify the tenant. + // + // The maximum number of allowed characters is 255. + string external_id = 2; + + // Optional. + // + // Indicates whether data owned by this tenant may be used to provide product + // improvements across other tenants. + // + // Defaults behavior is [DataUsageType.ISOLATED][google.cloud.talent.v4beta1.Tenant.DataUsageType.ISOLATED] if it's unset. + DataUsageType usage_type = 3; +} diff --git a/google/cloud/talent/v4beta1/tenant_service.proto b/google/cloud/talent/v4beta1/tenant_service.proto new file mode 100644 index 000000000..5af4fd8c5 --- /dev/null +++ b/google/cloud/talent/v4beta1/tenant_service.proto @@ -0,0 +1,163 @@ +// Copyright 2019 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.talent.v4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/talent/v4beta1/common.proto"; +import "google/cloud/talent/v4beta1/tenant.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent"; +option java_multiple_files = true; +option java_outer_classname = "TenantServiceProto"; +option java_package = "com.google.cloud.talent.v4beta1"; +option objc_class_prefix = "CTS"; + +// A service that handles tenant management, including CRUD and enumeration. +service TenantService { + // Creates a new tenant entity. + rpc CreateTenant(CreateTenantRequest) returns (Tenant) { + option (google.api.http) = { + post: "/v4beta1/{parent=projects/*}/tenants" + body: "*" + }; + } + + // Retrieves specified tenant. + rpc GetTenant(GetTenantRequest) returns (Tenant) { + option (google.api.http) = { + get: "/v4beta1/{name=projects/*/tenants/*}" + }; + } + + // Updates specified tenant. + rpc UpdateTenant(UpdateTenantRequest) returns (Tenant) { + option (google.api.http) = { + patch: "/v4beta1/{tenant.name=projects/*/tenants/*}" + body: "*" + }; + } + + // Deletes specified tenant. + rpc DeleteTenant(DeleteTenantRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v4beta1/{name=projects/*/tenants/*}" + }; + } + + // Lists all tenants associated with the project. + rpc ListTenants(ListTenantsRequest) returns (ListTenantsResponse) { + option (google.api.http) = { + get: "/v4beta1/{parent=projects/*}/tenants" + }; + } +} + +// The Request of the CreateTenant method. +message CreateTenantRequest { + // Required. + // + // Resource name of the project under which the tenant is created. + // + // The format is "projects/{project_id}", for example, + // "projects/api-test-project". + string parent = 1; + + // Required. + // + // The tenant to be created. + Tenant tenant = 2; +} + +// Request for getting a tenant by name. +message GetTenantRequest { + // Required. + // + // The resource name of the tenant to be retrieved. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenants/foo". + string name = 1; +} + +// Request for updating a specified tenant. +message UpdateTenantRequest { + // Required. + // + // The tenant resource to replace the current resource in the system. + Tenant tenant = 1; + + // Optional but strongly recommended for the best service + // experience. + // + // If [update_mask][google.cloud.talent.v4beta1.UpdateTenantRequest.update_mask] is provided, only the specified fields in + // [tenant][google.cloud.talent.v4beta1.UpdateTenantRequest.tenant] are updated. Otherwise all the fields are updated. + // + // A field mask to specify the tenant fields to be updated. Only + // top level fields of [Tenant][google.cloud.talent.v4beta1.Tenant] are supported. + google.protobuf.FieldMask update_mask = 2; +} + +// Request to delete a tenant. +message DeleteTenantRequest { + // Required. + // + // The resource name of the tenant to be deleted. + // + // The format is "projects/{project_id}/tenants/{tenant_id}", for example, + // "projects/api-test-project/tenants/foo". + string name = 1; +} + +// List tenants for which the client has ACL visibility. +message ListTenantsRequest { + // Required. + // + // Resource name of the project under which the tenant is created. + // + // The format is "projects/{project_id}", for example, + // "projects/api-test-project". + string parent = 1; + + // Optional. + // + // The starting indicator from which to return results. + string page_token = 2; + + // Optional. + // + // The maximum number of tenants to be returned, at most 100. + // Default is 100 if a non-positive number is provided. + int32 page_size = 3; +} + +// Output only. +// +// The List tenants response object. +message ListTenantsResponse { + // Tenants for the current client. + repeated Tenant tenants = 1; + + // A token to retrieve the next page of results. + string next_page_token = 2; + + // Additional information for the API invocation, such as the request + // tracking id. + ResponseMetadata metadata = 3; +} diff --git a/google/cloud/tasks/BUILD.bazel b/google/cloud/tasks/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/tasks/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/tasks/artman_cloudtasks_v2.yaml b/google/cloud/tasks/artman_cloudtasks_v2.yaml new file mode 100644 index 000000000..f3af7e6d4 --- /dev/null +++ b/google/cloud/tasks/artman_cloudtasks_v2.yaml @@ -0,0 +1,36 @@ +common: + api_name: tasks + api_version: v2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + - name: google-iam-v1 + proto_path: google/iam/v1 + src_proto_paths: + - v2 + service_yaml: cloudtasks_v2.yaml + gapic_yaml: v2/cloudtasks_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/tasks/artman_cloudtasks_v2beta2.yaml b/google/cloud/tasks/artman_cloudtasks_v2beta2.yaml new file mode 100644 index 000000000..f19712010 --- /dev/null +++ b/google/cloud/tasks/artman_cloudtasks_v2beta2.yaml @@ -0,0 +1,34 @@ +common: + api_name: tasks + api_version: v2beta2 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v2beta2 + service_yaml: cloudtasks_v2beta2.yaml + gapic_yaml: v2beta2/cloudtasks_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/tasks/artman_cloudtasks_v2beta3.yaml b/google/cloud/tasks/artman_cloudtasks_v2beta3.yaml new file mode 100644 index 000000000..d72d92d8f --- /dev/null +++ b/google/cloud/tasks/artman_cloudtasks_v2beta3.yaml @@ -0,0 +1,36 @@ +common: + api_name: tasks + api_version: v2beta3 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + - name: google-iam-v1 + proto_path: google/iam/v1 + src_proto_paths: + - v2beta3 + service_yaml: cloudtasks_v2beta3.yaml + gapic_yaml: v2beta3/cloudtasks_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/tasks/cloudtasks_v2.yaml b/google/cloud/tasks/cloudtasks_v2.yaml new file mode 100644 index 000000000..ba53c17f7 --- /dev/null +++ b/google/cloud/tasks/cloudtasks_v2.yaml @@ -0,0 +1,56 @@ +type: google.api.Service +config_version: 3 +name: cloudtasks.googleapis.com +title: Cloud Tasks API + +apis: + - name: google.cloud.tasks.v2.CloudTasks + +documentation: + summary: Manages the execution of large numbers of distributed requests. + overview: |- + Cloud Tasks manages the execution of large numbers of distributed requests. + + For more information, see https://cloud.google.com/tasks/. + +backend: + rules: + - selector: google.cloud.tasks.v2.CloudTasks.ListQueues + deadline: 15.0 + - selector: google.cloud.tasks.v2.CloudTasks.GetQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.CreateQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.UpdateQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.DeleteQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.PurgeQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.PauseQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.ResumeQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.GetIamPolicy + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.SetIamPolicy + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.TestIamPermissions + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.ListTasks + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.GetTask + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.CreateTask + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.DeleteTask + deadline: 10.0 + - selector: google.cloud.tasks.v2.CloudTasks.RunTask + deadline: 10.0 + +authentication: + rules: + - selector: 'google.cloud.tasks.v2.CloudTasks.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/tasks/cloudtasks_v2beta2.yaml b/google/cloud/tasks/cloudtasks_v2beta2.yaml new file mode 100644 index 000000000..65a96d45c --- /dev/null +++ b/google/cloud/tasks/cloudtasks_v2beta2.yaml @@ -0,0 +1,71 @@ +type: google.api.Service +config_version: 3 +name: cloudtasks.googleapis.com +title: Cloud Tasks API + +apis: +- name: google.cloud.tasks.v2beta2.CloudTasks + +enums: +- name: google.rpc.Code + +documentation: + summary: Manages the execution of large numbers of distributed requests. + overview: |- + Cloud Tasks manages the execution of large numbers of distributed requests. + + For more information, see https://cloud.google.com/tasks/. + +backend: + rules: + - selector: google.cloud.location.Locations.ListLocations + deadline: 10.0 + - selector: google.cloud.location.Locations.GetLocation + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.ListQueues + deadline: 15.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.GetQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.CreateQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.DeleteQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.PurgeQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.PauseQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.ResumeQueue + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.GetIamPolicy + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.SetIamPolicy + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.TestIamPermissions + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.ListTasks + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.GetTask + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.CreateTask + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.DeleteTask + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.AcknowledgeTask + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.RenewLease + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.CancelLease + deadline: 10.0 + - selector: google.cloud.tasks.v2beta2.CloudTasks.RunTask + deadline: 10.0 + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/tasks/cloudtasks_v2beta3.yaml b/google/cloud/tasks/cloudtasks_v2beta3.yaml new file mode 100644 index 000000000..53e5c4ef8 --- /dev/null +++ b/google/cloud/tasks/cloudtasks_v2beta3.yaml @@ -0,0 +1,29 @@ +type: google.api.Service +config_version: 3 +name: cloudtasks.googleapis.com +title: Cloud Tasks API + +apis: +- name: google.cloud.tasks.v2beta3.CloudTasks + +documentation: + summary: Manages the execution of large numbers of distributed requests. + overview: |- + Cloud Tasks manages the execution of large numbers of distributed + requests. + + For more information, see https://cloud.google.com/tasks/. + +backend: + rules: + - selector: 'google.cloud.tasks.v2beta3.CloudTasks.*' + deadline: 10.0 + - selector: google.cloud.tasks.v2beta3.CloudTasks.ListQueues + deadline: 15.0 + +authentication: + rules: + - selector: 'google.cloud.tasks.v2beta3.CloudTasks.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/tasks/v2/cloudtasks.proto b/google/cloud/tasks/v2/cloudtasks.proto new file mode 100644 index 000000000..dfad1f91e --- /dev/null +++ b/google/cloud/tasks/v2/cloudtasks.proto @@ -0,0 +1,601 @@ +// Copyright 2019 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.tasks.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/cloud/tasks/v2/task.proto"; +import "google/cloud/tasks/v2/queue.proto"; +import "google/iam/v1/iam_policy.proto"; +import "google/iam/v1/policy.proto"; +import "google/rpc/code.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "CloudTasksProto"; +option java_package = "com.google.cloud.tasks.v2"; +option objc_class_prefix = "TASKS"; + + +// Cloud Tasks allows developers to manage the execution of background +// work in their applications. +service CloudTasks { + // Lists queues. + // + // Queues are returned in lexicographical order. + rpc ListQueues(ListQueuesRequest) returns (ListQueuesResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/locations/*}/queues" + }; + } + + // Gets a queue. + rpc GetQueue(GetQueueRequest) returns (Queue) { + option (google.api.http) = { + get: "/v2/{name=projects/*/locations/*/queues/*}" + }; + } + + // Creates a queue. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of whether + // it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc CreateQueue(CreateQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/locations/*}/queues" + body: "queue" + }; + } + + // Updates a queue. + // + // This method creates the queue if it does not exist and updates + // the queue if it does exist. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of whether + // it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc UpdateQueue(UpdateQueueRequest) returns (Queue) { + option (google.api.http) = { + patch: "/v2/{queue.name=projects/*/locations/*/queues/*}" + body: "queue" + }; + } + + // Deletes a queue. + // + // This command will delete the queue even if it has tasks in it. + // + // Note: If you delete a queue, a queue with the same name can't be created + // for 7 days. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc DeleteQueue(DeleteQueueRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/locations/*/queues/*}" + }; + } + + // Purges a queue by deleting all of its tasks. + // + // All tasks created before this method is called are permanently deleted. + // + // Purge operations can take up to one minute to take effect. Tasks + // might be dispatched before the purge takes effect. A purge is irreversible. + rpc PurgeQueue(PurgeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*}:purge" + body: "*" + }; + } + + // Pauses the queue. + // + // If a queue is paused then the system will stop dispatching tasks + // until the queue is resumed via + // [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue]. Tasks can still be added + // when the queue is paused. A queue is paused if its + // [state][google.cloud.tasks.v2.Queue.state] is [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED]. + rpc PauseQueue(PauseQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*}:pause" + body: "*" + }; + } + + // Resume a queue. + // + // This method resumes a queue after it has been + // [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED] or + // [DISABLED][google.cloud.tasks.v2.Queue.State.DISABLED]. The state of a queue is stored + // in the queue's [state][google.cloud.tasks.v2.Queue.state]; after calling this method it + // will be set to [RUNNING][google.cloud.tasks.v2.Queue.State.RUNNING]. + // + // WARNING: Resuming many high-QPS queues at the same time can + // lead to target overloading. If you are resuming high-QPS + // queues, follow the 500/50/5 pattern described in + // [Managing Cloud Tasks Scaling Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling). + rpc ResumeQueue(ResumeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*}:resume" + body: "*" + }; + } + + // Gets the access control policy for a [Queue][google.cloud.tasks.v2.Queue]. + // Returns an empty policy if the resource exists and does not have a policy + // set. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.getIamPolicy` + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2/{resource=projects/*/locations/*/queues/*}:getIamPolicy" + body: "*" + }; + } + + // Sets the access control policy for a [Queue][google.cloud.tasks.v2.Queue]. Replaces any existing + // policy. + // + // Note: The Cloud Console does not check queue-level IAM permissions yet. + // Project-level permissions are required to use the Cloud Console. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.setIamPolicy` + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2/{resource=projects/*/locations/*/queues/*}:setIamPolicy" + body: "*" + }; + } + + // Returns permissions that a caller has on a [Queue][google.cloud.tasks.v2.Queue]. + // If the resource does not exist, this will return an empty set of + // permissions, not a [NOT_FOUND][google.rpc.Code.NOT_FOUND] error. + // + // Note: This operation is designed to be used for building permission-aware + // UIs and command-line tools, not for authorization checking. This operation + // may "fail open" without warning. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v2/{resource=projects/*/locations/*/queues/*}:testIamPermissions" + body: "*" + }; + } + + // Lists the tasks in a queue. + // + // By default, only the [BASIC][google.cloud.tasks.v2.Task.View.BASIC] view is retrieved + // due to performance considerations; + // [response_view][google.cloud.tasks.v2.ListTasksRequest.response_view] controls the + // subset of information which is returned. + // + // The tasks may be returned in any order. The ordering may change at any + // time. + rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) { + option (google.api.http) = { + get: "/v2/{parent=projects/*/locations/*/queues/*}/tasks" + }; + } + + // Gets a task. + rpc GetTask(GetTaskRequest) returns (Task) { + option (google.api.http) = { + get: "/v2/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Creates a task and adds it to a queue. + // + // Tasks cannot be updated after creation; there is no UpdateTask command. + // + // * For [App Engine queues][google.cloud.tasks.v2.AppEngineHttpQueue], the maximum task size is + // 100KB. + rpc CreateTask(CreateTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2/{parent=projects/*/locations/*/queues/*}/tasks" + body: "*" + }; + } + + // Deletes a task. + // + // A task can be deleted if it is scheduled or dispatched. A task + // cannot be deleted if it has executed successfully or permanently + // failed. + rpc DeleteTask(DeleteTaskRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Forces a task to run now. + // + // When this method is called, Cloud Tasks will dispatch the task, even if + // the task is already running, the queue has reached its [RateLimits][google.cloud.tasks.v2.RateLimits] or + // is [PAUSED][google.cloud.tasks.v2.Queue.State.PAUSED]. + // + // This command is meant to be used for manual debugging. For + // example, [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] can be used to retry a failed + // task after a fix has been made or to manually force a task to be + // dispatched now. + // + // The dispatched task is returned. That is, the task that is returned + // contains the [status][Task.status] after the task is dispatched but + // before the task is received by its target. + // + // If Cloud Tasks receives a successful response from the task's + // target, then the task will be deleted; otherwise the task's + // [schedule_time][google.cloud.tasks.v2.Task.schedule_time] will be reset to the time that + // [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] was called plus the retry delay specified + // in the queue's [RetryConfig][google.cloud.tasks.v2.RetryConfig]. + // + // [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask] returns + // [NOT_FOUND][google.rpc.Code.NOT_FOUND] when it is called on a + // task that has already succeeded or permanently failed. + rpc RunTask(RunTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2/{name=projects/*/locations/*/queues/*/tasks/*}:run" + body: "*" + }; + } +} + +// Request message for [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues]. +message ListQueuesRequest { + // Required. + // + // The location name. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + string parent = 1; + + // `filter` can be used to specify a subset of queues. Any [Queue][google.cloud.tasks.v2.Queue] + // field can be used as a filter and several operators as supported. + // For example: `<=, <, >=, >, !=, =, :`. The filter syntax is the same as + // described in + // [Stackdriver's Advanced Logs Filters](https://cloud.google.com/logging/docs/view/advanced_filters). + // + // Sample filter "state: PAUSED". + // + // Note that using filters might cause fewer queues than the + // requested page_size to be returned. + string filter = 2; + + // Requested page size. + // + // The maximum page size is 9800. If unspecified, the page size will + // be the maximum. Fewer queues than requested might be returned, + // even if more queues exist; use the + // [next_page_token][google.cloud.tasks.v2.ListQueuesResponse.next_page_token] in the + // response to determine if more queues exist. + int32 page_size = 3; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2.ListQueuesResponse.next_page_token] returned + // from the previous call to [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues] + // method. It is an error to switch the value of the + // [filter][google.cloud.tasks.v2.ListQueuesRequest.filter] while iterating through pages. + string page_token = 4; +} + +// Response message for [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues]. +message ListQueuesResponse { + // The list of queues. + repeated Queue queues = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListQueues][google.cloud.tasks.v2.CloudTasks.ListQueues] with this value as the + // [page_token][google.cloud.tasks.v2.ListQueuesRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + // + // The page token is valid for only 2 hours. + string next_page_token = 2; +} + +// Request message for [GetQueue][google.cloud.tasks.v2.CloudTasks.GetQueue]. +message GetQueueRequest { + // Required. + // + // The resource name of the queue. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [CreateQueue][google.cloud.tasks.v2.CloudTasks.CreateQueue]. +message CreateQueueRequest { + // Required. + // + // The location name in which the queue will be created. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + // + // The list of allowed locations can be obtained by calling Cloud + // Tasks' implementation of + // [ListLocations][google.cloud.location.Locations.ListLocations]. + string parent = 1; + + // Required. + // + // The queue to create. + // + // [Queue's name][google.cloud.tasks.v2.Queue.name] cannot be the same as an existing queue. + Queue queue = 2; +} + +// Request message for [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue]. +message UpdateQueueRequest { + // Required. + // + // The queue to create or update. + // + // The queue's [name][google.cloud.tasks.v2.Queue.name] must be specified. + // + // Output only fields cannot be modified using UpdateQueue. + // Any value specified for an output only field will be ignored. + // The queue's [name][google.cloud.tasks.v2.Queue.name] cannot be changed. + Queue queue = 1; + + // A mask used to specify which fields of the queue are being updated. + // + // If empty, then all fields will be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for [DeleteQueue][google.cloud.tasks.v2.CloudTasks.DeleteQueue]. +message DeleteQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [PurgeQueue][google.cloud.tasks.v2.CloudTasks.PurgeQueue]. +message PurgeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [PauseQueue][google.cloud.tasks.v2.CloudTasks.PauseQueue]. +message PauseQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue]. +message ResumeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for listing tasks using [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks]. +message ListTasksRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string parent = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 2; + + // Requested page size. Fewer tasks than requested might be returned. + // + // The maximum page size is 1000. If unspecified, the page size will + // be the maximum. Fewer tasks than requested might be returned, + // even if more tasks exist; use + // [next_page_token][google.cloud.tasks.v2.ListTasksResponse.next_page_token] in the + // response to determine if more tasks exist. + int32 page_size = 3; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2.ListTasksResponse.next_page_token] returned + // from the previous call to [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks] + // method. + // + // The page token is valid for only 2 hours. + string page_token = 4; +} + +// Response message for listing tasks using [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks]. +message ListTasksResponse { + // The list of tasks. + repeated Task tasks = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListTasks][google.cloud.tasks.v2.CloudTasks.ListTasks] with this value as the + // [page_token][google.cloud.tasks.v2.ListTasksRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + string next_page_token = 2; +} + +// Request message for getting a task using [GetTask][google.cloud.tasks.v2.CloudTasks.GetTask]. +message GetTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 2; +} + +// Request message for [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask]. +message CreateTaskRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // The queue must already exist. + string parent = 1; + + // Required. + // + // The task to add. + // + // Task names have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID`. + // The user can optionally specify a task [name][google.cloud.tasks.v2.Task.name]. If a + // name is not specified then the system will generate a random + // unique task id, which will be set in the task returned in the + // [response][google.cloud.tasks.v2.Task.name]. + // + // If [schedule_time][google.cloud.tasks.v2.Task.schedule_time] is not set or is in the + // past then Cloud Tasks will set it to the current time. + // + // Task De-duplication: + // + // Explicitly specifying a task ID enables task de-duplication. If + // a task's ID is identical to that of an existing task or a task + // that was deleted or executed recently then the call will fail + // with [ALREADY_EXISTS][google.rpc.Code.ALREADY_EXISTS]. + // If the task's queue was created using Cloud Tasks, then another task with + // the same name can't be created for ~1hour after the original task was + // deleted or executed. If the task's queue was created using queue.yaml or + // queue.xml, then another task with the same name can't be created + // for ~9days after the original task was deleted or executed. + // + // Because there is an extra lookup cost to identify duplicate task + // names, these [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask] calls have significantly + // increased latency. Using hashed strings for the task id or for + // the prefix of the task id is recommended. Choosing task ids that + // are sequential or have sequential prefixes, for example using a + // timestamp, causes an increase in latency and error rates in all + // task commands. The infrastructure relies on an approximately + // uniform distribution of task ids to store and serve tasks + // efficiently. + Task task = 2; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 3; +} + +// Request message for deleting a task using +// [DeleteTask][google.cloud.tasks.v2.CloudTasks.DeleteTask]. +message DeleteTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; +} + +// Request message for forcing a task to run now using +// [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask]. +message RunTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2.Task] resource. + Task.View response_view = 2; +} diff --git a/google/cloud/tasks/v2/cloudtasks_gapic.yaml b/google/cloud/tasks/v2/cloudtasks_gapic.yaml new file mode 100644 index 000000000..45bf5dc7a --- /dev/null +++ b/google/cloud/tasks/v2/cloudtasks_gapic.yaml @@ -0,0 +1,435 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.tasks.v2 + python: + package_name: google.cloud.tasks_v2.gapic + go: + package_name: cloud.google.com/go/cloudtasks/apiv2 + csharp: + package_name: Google.Cloud.Tasks.V2 + ruby: + package_name: Google::Cloud::Tasks::V2 + php: + package_name: Google\Cloud\Tasks\V2 + nodejs: + package_name: tasks.v2 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.tasks.v2.CloudTasks + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/queues/{queue} + entity_name: queue + - name_pattern: projects/{project}/locations/{location}/queues/{queue}/tasks/{task} + entity_name: task + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListQueues + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: queues + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: GetQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: CreateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - queue + required_fields: + - parent + - queue + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: UpdateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - queue + - update_mask + required_fields: + - queue + header_request_params: + - queue.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + queue.name: queue + timeout_millis: 10000 + - name: DeleteQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PurgeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PauseQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: ResumeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: GetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: SetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + header_request_params: + - resource + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: TestIamPermissions + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: ListTasks + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: tasks + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: GetTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: CreateTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - task + required_fields: + - parent + - task + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: DeleteTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: RunTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 +resource_name_generation: +- message_name: Queue + field_entity_map: + name: queue +- message_name: Task + field_entity_map: + name: task +- message_name: ListQueuesRequest + field_entity_map: + parent: location +- message_name: GetQueueRequest + field_entity_map: + name: queue +- message_name: CreateQueueRequest + field_entity_map: + parent: location +- message_name: UpdateQueueRequest + field_entity_map: + queue.name: queue +- message_name: DeleteQueueRequest + field_entity_map: + name: queue +- message_name: PurgeQueueRequest + field_entity_map: + name: queue +- message_name: PauseQueueRequest + field_entity_map: + name: queue +- message_name: ResumeQueueRequest + field_entity_map: + name: queue +- message_name: ListTasksRequest + field_entity_map: + parent: queue +- message_name: GetTaskRequest + field_entity_map: + name: task +- message_name: CreateTaskRequest + field_entity_map: + parent: queue +- message_name: DeleteTaskRequest + field_entity_map: + name: task +- message_name: RunTaskRequest + field_entity_map: + name: task +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: "*" diff --git a/google/cloud/tasks/v2/queue.proto b/google/cloud/tasks/v2/queue.proto new file mode 100644 index 000000000..b38b61415 --- /dev/null +++ b/google/cloud/tasks/v2/queue.proto @@ -0,0 +1,342 @@ +// Copyright 2019 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.tasks.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/tasks/v2/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "QueueProto"; +option java_package = "com.google.cloud.tasks.v2"; + + +// A queue is a container of related tasks. Queues are configured to manage +// how those tasks are dispatched. Configurable properties include rate limits, +// retry options, queue types, and others. +message Queue { + // State of the queue. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The queue is running. Tasks can be dispatched. + // + // If the queue was created using Cloud Tasks and the queue has + // had no activity (method calls or task dispatches) for 30 days, + // the queue may take a few minutes to re-activate. Some method + // calls may return [NOT_FOUND][google.rpc.Code.NOT_FOUND] and + // tasks may not be dispatched for a few minutes until the queue + // has been re-activated. + RUNNING = 1; + + // Tasks are paused by the user. If the queue is paused then Cloud + // Tasks will stop delivering tasks from it, but more tasks can + // still be added to it by the user. + PAUSED = 2; + + // The queue is disabled. + // + // A queue becomes `DISABLED` when + // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref) + // or + // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref) + // is uploaded which does not contain the queue. You cannot directly disable + // a queue. + // + // When a queue is disabled, tasks can still be added to a queue + // but the tasks are not dispatched. + // + // To permanently delete this queue and all of its tasks, call + // [DeleteQueue][google.cloud.tasks.v2.CloudTasks.DeleteQueue]. + DISABLED = 3; + } + + // Caller-specified and required in [CreateQueue][google.cloud.tasks.v2.CloudTasks.CreateQueue], + // after which it becomes output only. + // + // The queue name. + // + // The queue name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the queue's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + string name = 1; + + // Overrides for + // [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. + // These settings apply only to + // [App Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in this queue. + // + // If set, `app_engine_routing_override` is used for all + // [App Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in the queue, no matter what the + // setting is for the + // [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing_override = 2; + + // Rate limits for task dispatches. + // + // [rate_limits][google.cloud.tasks.v2.Queue.rate_limits] and [retry_config][google.cloud.tasks.v2.Queue.retry_config] are + // related because they both control task attempts. However they control task + // attempts in different ways: + // + // * [rate_limits][google.cloud.tasks.v2.Queue.rate_limits] controls the total rate of + // dispatches from a queue (i.e. all traffic dispatched from the + // queue, regardless of whether the dispatch is from a first + // attempt or a retry). + // * [retry_config][google.cloud.tasks.v2.Queue.retry_config] controls what happens to + // particular a task after its first attempt fails. That is, + // [retry_config][google.cloud.tasks.v2.Queue.retry_config] controls task retries (the + // second attempt, third attempt, etc). + // + // The queue's actual dispatch rate is the result of: + // + // * Number of tasks in the queue + // * User-specified throttling: [rate_limits][google.cloud.tasks.v2.Queue.rate_limits], + // [retry_config][google.cloud.tasks.v2.Queue.retry_config], and the + // [queue's state][google.cloud.tasks.v2.Queue.state]. + // * System throttling due to `429` (Too Many Requests) or `503` (Service + // Unavailable) responses from the worker, high error rates, or to smooth + // sudden large traffic spikes. + RateLimits rate_limits = 3; + + // Settings that determine the retry behavior. + // + // * For tasks created using Cloud Tasks: the queue-level retry settings + // apply to all tasks in the queue that were created using Cloud Tasks. + // Retry settings cannot be set on individual tasks. + // * For tasks created using the App Engine SDK: the queue-level retry + // settings apply to all tasks in the queue which do not have retry settings + // explicitly set on the task and were created by the App Engine SDK. See + // [App Engine + // documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks). + RetryConfig retry_config = 4; + + // Output only. The state of the queue. + // + // `state` can only be changed by called + // [PauseQueue][google.cloud.tasks.v2.CloudTasks.PauseQueue], + // [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue], or uploading + // [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref). + // [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue] cannot be used to change `state`. + State state = 5; + + // Output only. The last time this queue was purged. + // + // All tasks that were [created][google.cloud.tasks.v2.Task.create_time] before this time + // were purged. + // + // A queue can be purged using [PurgeQueue][google.cloud.tasks.v2.CloudTasks.PurgeQueue], the + // [App Engine Task Queue SDK, or the Cloud + // Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue). + // + // Purge time will be truncated to the nearest microsecond. Purge + // time will be unset if the queue has never been purged. + google.protobuf.Timestamp purge_time = 6; +} + +// Rate limits. +// +// This message determines the maximum rate that tasks can be dispatched by a +// queue, regardless of whether the dispatch is a first task attempt or a retry. +// +// Note: The debugging command, [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask], will run a task +// even if the queue has reached its [RateLimits][google.cloud.tasks.v2.RateLimits]. +message RateLimits { + // The maximum rate at which tasks are dispatched from this queue. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // * For [App Engine queues][google.cloud.tasks.v2.AppEngineHttpQueue], the maximum allowed value + // is 500. + // + // + // This field has the same meaning as + // [rate in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate). + double max_dispatches_per_second = 1; + + // Output only. The max burst size. + // + // Max burst size limits how fast tasks in queue are processed when + // many tasks are in the queue and the rate is high. This field + // allows the queue to have a high rate so processing starts shortly + // after a task is enqueued, but still limits resource usage when + // many tasks are enqueued in a short period of time. + // + // The [token bucket](https://wikipedia.org/wiki/Token_Bucket) + // algorithm is used to control the rate of task dispatches. Each + // queue has a token bucket that holds tokens, up to the maximum + // specified by `max_burst_size`. Each time a task is dispatched, a + // token is removed from the bucket. Tasks will be dispatched until + // the queue's bucket runs out of tokens. The bucket will be + // continuously refilled with new tokens based on + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second]. + // + // Cloud Tasks will pick the value of `max_burst_size` based on the + // value of + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second]. + // + // For App Engine queues that were created or updated using + // `queue.yaml/xml`, `max_burst_size` is equal to + // [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size). + // Since `max_burst_size` is output only, if + // [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue] is called on a queue + // created by `queue.yaml/xml`, `max_burst_size` will be reset based + // on the value of + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second], + // regardless of whether + // [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second] + // is updated. + // + int32 max_burst_size = 2; + + // The maximum number of concurrent tasks that Cloud Tasks allows + // to be dispatched for this queue. After this threshold has been + // reached, Cloud Tasks stops dispatching tasks until the number of + // concurrent requests decreases. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // The maximum allowed value is 5,000. + // + // + // This field has the same meaning as + // [max_concurrent_requests in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests). + int32 max_concurrent_dispatches = 3; +} + +// Retry config. +// +// These settings determine when a failed task attempt is retried. +message RetryConfig { + // Number of attempts per task. + // + // Cloud Tasks will attempt the task `max_attempts` times (that is, if the + // first attempt fails, then there will be `max_attempts - 1` retries). Must + // be >= -1. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // -1 indicates unlimited attempts. + // + // This field has the same meaning as + // [task_retry_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + int32 max_attempts = 1; + + // If positive, `max_retry_duration` specifies the time limit for + // retrying a failed task, measured from when the task was first + // attempted. Once `max_retry_duration` time has passed *and* the + // task has been attempted [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts] + // times, no further attempts will be made and the task will be + // deleted. + // + // If zero, then the task age is unlimited. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `max_retry_duration` will be truncated to the nearest second. + // + // This field has the same meaning as + // [task_age_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_retry_duration = 2; + + // A task will be [scheduled][google.cloud.tasks.v2.Task.schedule_time] for retry between + // [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] duration after it fails, + // if the queue's [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies that the task should be + // retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `min_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [min_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration min_backoff = 3; + + // A task will be [scheduled][google.cloud.tasks.v2.Task.schedule_time] for retry between + // [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] duration after it fails, + // if the queue's [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies that the task should be + // retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `max_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [max_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_backoff = 4; + + // The time between retries will double `max_doublings` times. + // + // A task's retry interval starts at + // [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff], then doubles + // `max_doublings` times, then increases linearly, and finally + // retries retries at intervals of + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] up to + // [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts] times. + // + // For example, if [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff] is 10s, + // [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] is 300s, and + // `max_doublings` is 3, then the a task will first be retried in + // 10s. The retry interval will double three times, and then + // increase linearly by 2^3 * 10s. Finally, the task will retry at + // intervals of [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff] until the + // task has been attempted [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts] + // times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, + // 240s, 300s, 300s, .... + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // This field has the same meaning as + // [max_doublings in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + int32 max_doublings = 5; +} diff --git a/google/cloud/tasks/v2/target.proto b/google/cloud/tasks/v2/target.proto new file mode 100644 index 000000000..8cf991e97 --- /dev/null +++ b/google/cloud/tasks/v2/target.proto @@ -0,0 +1,274 @@ +// Copyright 2019 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.tasks.v2; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TargetProto"; +option java_package = "com.google.cloud.tasks.v2"; + + +// App Engine HTTP request. +// +// The message defines the HTTP request that is sent to an App Engine app when +// the task is dispatched. +// +// This proto can only be used for tasks in a queue which has +// [app_engine_http_queue][Queue.app_engine_http_queue] set. +// +// Using [AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest] requires +// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) +// Google IAM permission for the project +// and the following scope: +// +// `https://www.googleapis.com/auth/cloud-platform` +// +// The task will be delivered to the App Engine app which belongs to the same +// project as the queue. For more information, see +// [How Requests are +// Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) +// and how routing is affected by +// [dispatch +// files](https://cloud.google.com/appengine/docs/python/config/dispatchref). +// Traffic is encrypted during transport and never leaves Google datacenters. +// Because this traffic is carried over a communication mechanism internal to +// Google, you cannot explicitly set the protocol (for example, HTTP or HTTPS). +// The request to the handler, however, will appear to have used the HTTP +// protocol. +// +// The [AppEngineRouting][google.cloud.tasks.v2.AppEngineRouting] used to construct the URL that the task is +// delivered to can be set at the queue-level or task-level: +// +// * If set, +// [app_engine_routing_override][google.cloud.tasks.v2.AppEngineHttpQueue.app_engine_routing_override] +// is used for all tasks in the queue, no matter what the setting +// is for the +// [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. +// +// +// The `url` that the task will be sent to is: +// +// * `url =` [host][google.cloud.tasks.v2.AppEngineRouting.host] `+` +// [relative_uri][google.cloud.tasks.v2.AppEngineHttpRequest.relative_uri] +// +// Tasks can be dispatched to secure app handlers, unsecure app handlers, and +// URIs restricted with +// [`login: +// admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref). +// Because tasks are not run as any user, they cannot be dispatched to URIs +// restricted with +// [`login: +// required`](https://cloud.google.com/appengine/docs/standard/python/config/appref) +// Task dispatches also do not follow redirects. +// +// The task attempt has succeeded if the app's request handler returns +// an HTTP response code in the range [`200` - `299`]. `503` is +// considered an App Engine system error instead of an application +// error. Requests returning error `503` will be retried regardless of +// retry configuration and not counted against retry counts. +// Any other response code or a failure to receive a response before the +// deadline is a failed attempt. +message AppEngineHttpRequest { + // The HTTP method to use for the request. The default is POST. + // + // The app's request handler for the task's target URL must be able to handle + // HTTP requests with this http_method, otherwise the task attempt will fail + // with error code 405 (Method Not Allowed). See + // [Writing a push task request + // handler](https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler) + // and the documentation for the request handlers in the language your app is + // written in e.g. + // [Python Request + // Handler](https://cloud.google.com/appengine/docs/python/tools/webapp/requesthandlerclass). + HttpMethod http_method = 1; + + // Task-level setting for App Engine routing. + // + // If set, + // [app_engine_routing_override][google.cloud.tasks.v2.AppEngineHttpQueue.app_engine_routing_override] + // is used for all tasks in the queue, no matter what the setting is for the + // [task-level app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing = 2; + + // The relative URI. + // + // The relative URI must begin with "/" and must be a valid HTTP relative URI. + // It can contain a path and query string arguments. + // If the relative URI is empty, then the root path "/" will be used. + // No spaces are allowed, and the maximum length allowed is 2083 characters. + string relative_uri = 3; + + // HTTP request headers. + // + // This map contains the header field names and values. + // Headers can be set when the + // [task is created][google.cloud.tasks.v2.CloudTasks.CreateTask]. + // Repeated headers are not supported but a header value can contain commas. + // + // Cloud Tasks sets some headers to default values: + // + // * `User-Agent`: By default, this header is + // `"AppEngine-Google; (+http://code.google.com/appengine)"`. + // This header can be modified, but Cloud Tasks will append + // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the + // modified `User-Agent`. + // + // If the task has a [body][google.cloud.tasks.v2.AppEngineHttpRequest.body], Cloud + // Tasks sets the following headers: + // + // * `Content-Type`: By default, the `Content-Type` header is set to + // `"application/octet-stream"`. The default can be overridden by explicitly + // setting `Content-Type` to a particular media type when the + // [task is created][google.cloud.tasks.v2.CloudTasks.CreateTask]. + // For example, `Content-Type` can be set to `"application/json"`. + // * `Content-Length`: This is computed by Cloud Tasks. This value is + // output only. It cannot be changed. + // + // The headers below cannot be set or overridden: + // + // * `Host` + // * `X-Google-*` + // * `X-AppEngine-*` + // + // In addition, Cloud Tasks sets some headers when the task is dispatched, + // such as headers containing information about the task; see + // [request + // headers](https://cloud.google.com/appengine/docs/python/taskqueue/push/creating-handlers#reading_request_headers). + // These headers are set only when the task is dispatched, so they are not + // visible when the task is returned in a Cloud Tasks response. + // + // Although there is no specific limit for the maximum number of headers or + // the size, there is a limit on the maximum size of the [Task][google.cloud.tasks.v2.Task]. For more + // information, see the [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask] documentation. + map<string, string> headers = 4; + + // HTTP request body. + // + // A request body is allowed only if the HTTP method is POST or PUT. It is + // an error to set a body on a task with an incompatible [HttpMethod][google.cloud.tasks.v2.HttpMethod]. + bytes body = 5; +} + +// App Engine Routing. +// +// Defines routing characteristics specific to App Engine - service, version, +// and instance. +// +// For more information about services, versions, and instances see +// [An Overview of App +// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), +// [Microservices Architecture on Google App +// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), +// [App Engine Standard request +// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), +// and [App Engine Flex request +// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). +message AppEngineRouting { + // App service. + // + // By default, the task is sent to the service which is the default + // service when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable + // into [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance]. For example, some tasks + // which were created using the App Engine SDK use a custom domain + // name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable, then + // [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance] are the empty string. + string service = 1; + + // App version. + // + // By default, the task is sent to the version which is the default + // version when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable + // into [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance]. For example, some tasks + // which were created using the App Engine SDK use a custom domain + // name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2.AppEngineRouting.host] is not parsable, then + // [service][google.cloud.tasks.v2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2.AppEngineRouting.instance] are the empty string. + string version = 2; + + // App instance. + // + // By default, the task is sent to an instance which is available when + // the task is attempted. + // + // Requests can only be sent to a specific instance if + // [manual scaling is used in App Engine + // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). + // App Engine Flex does not support instances. For more information, see + // [App Engine Standard request + // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) + // and [App Engine Flex request + // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). + string instance = 3; + + // Output only. The host that the task is sent to. + // + // The host is constructed from the domain name of the app associated with + // the queue's project ID (for example <app-id>.appspot.com), and the + // [service][google.cloud.tasks.v2.AppEngineRouting.service], [version][google.cloud.tasks.v2.AppEngineRouting.version], + // and [instance][google.cloud.tasks.v2.AppEngineRouting.instance]. Tasks which were created using + // the App Engine SDK might have a custom domain name. + // + // For more information, see + // [How Requests are + // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). + string host = 4; +} + +// The HTTP method used to deliver the task. +enum HttpMethod { + // HTTP method unspecified + HTTP_METHOD_UNSPECIFIED = 0; + + // HTTP POST + POST = 1; + + // HTTP GET + GET = 2; + + // HTTP HEAD + HEAD = 3; + + // HTTP PUT + PUT = 4; + + // HTTP DELETE + DELETE = 5; + + // HTTP PATCH + PATCH = 6; + + // HTTP OPTIONS + OPTIONS = 7; +} diff --git a/google/cloud/tasks/v2/task.proto b/google/cloud/tasks/v2/task.proto new file mode 100644 index 000000000..11be05c46 --- /dev/null +++ b/google/cloud/tasks/v2/task.proto @@ -0,0 +1,182 @@ +// Copyright 2019 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.tasks.v2; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/tasks/v2/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TaskProto"; +option java_package = "com.google.cloud.tasks.v2"; + + +// A unit of scheduled work. +message Task { + // The view specifies a subset of [Task][google.cloud.tasks.v2.Task] data. + // + // When a task is returned in a response, not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + enum View { + // Unspecified. Defaults to BASIC. + VIEW_UNSPECIFIED = 0; + + // The basic view omits fields which can be large or can contain + // sensitive data. + // + // This view does not include the + // [body in AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest.body]. + // Bodies are desirable to return only when needed, because they + // can be large and because of the sensitivity of the data that you + // choose to store in it. + BASIC = 1; + + // All information is returned. + // + // Authorization for [FULL][google.cloud.tasks.v2.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Queue][google.cloud.tasks.v2.Queue] resource. + FULL = 2; + } + + // Optionally caller-specified in [CreateTask][google.cloud.tasks.v2.CloudTasks.CreateTask]. + // + // The task name. + // + // The task name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the task's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + // * `TASK_ID` can contain only letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), or underscores (_). The maximum length is 500 characters. + string name = 1; + + // Required. The message to send to the worker. + oneof message_type { + // HTTP request that is sent to the App Engine app handler. + // + // An App Engine task is a task that has [AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest] set. + AppEngineHttpRequest app_engine_http_request = 2; + } + + // The time when the task is scheduled to be attempted. + // + // For App Engine queues, this is when the task will be attempted or retried. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 4; + + // Output only. The time that the task was created. + // + // `create_time` will be truncated to the nearest second. + google.protobuf.Timestamp create_time = 5; + + // The deadline for requests sent to the worker. If the worker does not + // respond by this deadline then the request is cancelled and the attempt + // is marked as a `DEADLINE_EXCEEDED` failure. Cloud Tasks will retry the + // task according to the [RetryConfig][google.cloud.tasks.v2.RetryConfig]. + // + // Note that when the request is cancelled, Cloud Tasks will stop listing for + // the response, but whether the worker stops processing depends on the + // worker. For example, if the worker is stuck, it may not react to cancelled + // requests. + // + // The default and maximum values depend on the type of request: + // + // + // * For [App Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest], 0 indicates that the + // request has the default deadline. The default deadline depends on the + // [scaling + // type](https://cloud.google.com/appengine/docs/standard/go/how-instances-are-managed#instance_scaling) + // of the service: 10 minutes for standard apps with automatic scaling, 24 + // hours for standard apps with manual and basic scaling, and 60 minutes for + // flex apps. If the request deadline is set, it must be in the interval [15 + // seconds, 24 hours 15 seconds]. Regardless of the task's + // `dispatch_deadline`, the app handler will not run for longer than than + // the service's timeout. We recommend setting the `dispatch_deadline` to + // at most a few seconds more than the app handler's timeout. For more + // information see + // [Timeouts](https://cloud.google.com/tasks/docs/creating-appengine-handlers#timeouts). + // + // `dispatch_deadline` will be truncated to the nearest millisecond. The + // deadline is an approximate deadline. + google.protobuf.Duration dispatch_deadline = 6; + + // Output only. The number of attempts dispatched. + // + // This count includes attempts which have been dispatched but haven't + // received a response. + int32 dispatch_count = 7; + + // Output only. The number of attempts which have received a response. + int32 response_count = 8; + + // Output only. The status of the task's first attempt. + // + // Only [dispatch_time][google.cloud.tasks.v2.Attempt.dispatch_time] will be set. + // The other [Attempt][google.cloud.tasks.v2.Attempt] information is not retained by Cloud Tasks. + Attempt first_attempt = 9; + + // Output only. The status of the task's last attempt. + Attempt last_attempt = 10; + + // Output only. The view specifies which subset of the [Task][google.cloud.tasks.v2.Task] has + // been returned. + View view = 11; +} + +// The status of a task attempt. +message Attempt { + // Output only. The time that this attempt was scheduled. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 1; + + // Output only. The time that this attempt was dispatched. + // + // `dispatch_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp dispatch_time = 2; + + // Output only. The time that this attempt response was received. + // + // `response_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp response_time = 3; + + // Output only. The response from the worker for this attempt. + // + // If `response_time` is unset, then the task has not been attempted or is + // currently running and the `response_status` field is meaningless. + google.rpc.Status response_status = 4; +} diff --git a/google/cloud/tasks/v2beta2/BUILD.bazel b/google/cloud/tasks/v2beta2/BUILD.bazel new file mode 100644 index 000000000..024ddd076 --- /dev/null +++ b/google/cloud/tasks/v2beta2/BUILD.bazel @@ -0,0 +1,156 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "tasks_proto", + srcs = [ + "cloudtasks.proto", + "queue.proto", + "target.proto", + "task.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/iam/v1:iam_policy_proto", + "//google/iam/v1:policy_proto", + "//google/rpc:code_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "tasks_proto_with_info", + deps = [":tasks_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", + "@com_google_api_grpc_proto_google_iam_v1//jar", +] + +java_proto_library( + name = "tasks_java_proto", + deps = [":tasks_proto"], +) + +java_grpc_library( + name = "tasks_java_grpc", + srcs = [":tasks_proto"], + deps = [":tasks_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "tasks_resource_name_java_proto", + gapic_yaml = "cloudtasks_gapic.yaml", + deps = [":tasks_proto"], +) + +java_gapic_library( + name = "tasks_java_gapic", + src = ":tasks_proto_with_info", + gapic_yaml = "cloudtasks_gapic.yaml", + service_yaml = "//google/cloud/tasks:cloudtasks_v2beta2.yaml", + test_deps = [":tasks_java_grpc"], + deps = [ + ":tasks_java_proto", + ":tasks_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":tasks_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.tasks.v2beta2.CloudTasksClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-tasks-v2beta2-java", + client_deps = [":tasks_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":tasks_java_gapic_test"], + grpc_deps = [":tasks_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":tasks_java_proto", + ":tasks_proto", + ":tasks_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "tasks_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta2", + protos = [":tasks_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/iam/v1:iam_go_proto", + "//google/rpc:code_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "tasks_go_gapic", + src = ":tasks_proto_with_info", + gapic_yaml = "cloudtasks_gapic.yaml", + importpath = "cloud.google.com/go/cloudtasks/apiv2beta2", + service_yaml = "//google/cloud/tasks:cloudtasks_v2beta2.yaml", + deps = [ + ":tasks_go_proto", + "//google/iam/v1:iam_go_proto", + "@io_bazel_rules_go//proto/wkt:duration_go_proto", + ], +) + +go_test( + name = "tasks_go_gapic_test", + srcs = [":tasks_go_gapic_srcjar_test"], + embed = [":tasks_go_gapic"], + importpath = "cloud.google.com/go/cloudtasks/apiv2beta2", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-tasks-v2beta2-go", + deps = [ + ":tasks_go_gapic", + ":tasks_go_gapic_srcjar-smoke-test.srcjar", + ":tasks_go_gapic_srcjar-test.srcjar", + ":tasks_go_proto", + ], +) diff --git a/google/cloud/tasks/v2beta2/cloudtasks.proto b/google/cloud/tasks/v2beta2/cloudtasks.proto new file mode 100644 index 000000000..61a6ecdc9 --- /dev/null +++ b/google/cloud/tasks/v2beta2/cloudtasks.proto @@ -0,0 +1,903 @@ +// Copyright 2018 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.tasks.v2beta2; + +import "google/api/annotations.proto"; +import "google/cloud/tasks/v2beta2/queue.proto"; +import "google/cloud/tasks/v2beta2/task.proto"; +import "google/iam/v1/iam_policy.proto"; +import "google/iam/v1/policy.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/code.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "CloudTasksProto"; +option java_package = "com.google.cloud.tasks.v2beta2"; +option objc_class_prefix = "TASKS"; + +// Cloud Tasks allows developers to manage the execution of background +// work in their applications. +service CloudTasks { + // Lists queues. + // + // Queues are returned in lexicographical order. + rpc ListQueues(ListQueuesRequest) returns (ListQueuesResponse) { + option (google.api.http) = { + get: "/v2beta2/{parent=projects/*/locations/*}/queues" + }; + } + + // Gets a queue. + rpc GetQueue(GetQueueRequest) returns (Queue) { + option (google.api.http) = { + get: "/v2beta2/{name=projects/*/locations/*/queues/*}" + }; + } + + // Creates a queue. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of + // whether it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and + // queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using + // this method. + rpc CreateQueue(CreateQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta2/{parent=projects/*/locations/*}/queues" + body: "queue" + }; + } + + // Updates a queue. + // + // This method creates the queue if it does not exist and updates + // the queue if it does exist. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of + // whether it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and + // queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using + // this method. + rpc UpdateQueue(UpdateQueueRequest) returns (Queue) { + option (google.api.http) = { + patch: "/v2beta2/{queue.name=projects/*/locations/*/queues/*}" + body: "queue" + }; + } + + // Deletes a queue. + // + // This command will delete the queue even if it has tasks in it. + // + // Note: If you delete a queue, a queue with the same name can't be created + // for 7 days. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and + // queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) before using + // this method. + rpc DeleteQueue(DeleteQueueRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta2/{name=projects/*/locations/*/queues/*}" + }; + } + + // Purges a queue by deleting all of its tasks. + // + // All tasks created before this method is called are permanently deleted. + // + // Purge operations can take up to one minute to take effect. Tasks + // might be dispatched before the purge takes effect. A purge is irreversible. + rpc PurgeQueue(PurgeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta2/{name=projects/*/locations/*/queues/*}:purge" + body: "*" + }; + } + + // Pauses the queue. + // + // If a queue is paused then the system will stop dispatching tasks + // until the queue is resumed via + // [ResumeQueue][google.cloud.tasks.v2beta2.CloudTasks.ResumeQueue]. Tasks can + // still be added when the queue is paused. A queue is paused if its + // [state][google.cloud.tasks.v2beta2.Queue.state] is + // [PAUSED][google.cloud.tasks.v2beta2.Queue.State.PAUSED]. + rpc PauseQueue(PauseQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta2/{name=projects/*/locations/*/queues/*}:pause" + body: "*" + }; + } + + // Resume a queue. + // + // This method resumes a queue after it has been + // [PAUSED][google.cloud.tasks.v2beta2.Queue.State.PAUSED] or + // [DISABLED][google.cloud.tasks.v2beta2.Queue.State.DISABLED]. The state of a + // queue is stored in the queue's + // [state][google.cloud.tasks.v2beta2.Queue.state]; after calling this method + // it will be set to + // [RUNNING][google.cloud.tasks.v2beta2.Queue.State.RUNNING]. + // + // WARNING: Resuming many high-QPS queues at the same time can + // lead to target overloading. If you are resuming high-QPS + // queues, follow the 500/50/5 pattern described in + // [Managing Cloud Tasks Scaling + // Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling). + rpc ResumeQueue(ResumeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta2/{name=projects/*/locations/*/queues/*}:resume" + body: "*" + }; + } + + // Gets the access control policy for a + // [Queue][google.cloud.tasks.v2beta2.Queue]. Returns an empty policy if the + // resource exists and does not have a policy set. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.getIamPolicy` + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2beta2/{resource=projects/*/locations/*/queues/*}:getIamPolicy" + body: "*" + }; + } + + // Sets the access control policy for a + // [Queue][google.cloud.tasks.v2beta2.Queue]. Replaces any existing policy. + // + // Note: The Cloud Console does not check queue-level IAM permissions yet. + // Project-level permissions are required to use the Cloud Console. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.setIamPolicy` + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) + returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2beta2/{resource=projects/*/locations/*/queues/*}:setIamPolicy" + body: "*" + }; + } + + // Returns permissions that a caller has on a + // [Queue][google.cloud.tasks.v2beta2.Queue]. If the resource does not exist, + // this will return an empty set of permissions, not a + // [NOT_FOUND][google.rpc.Code.NOT_FOUND] error. + // + // Note: This operation is designed to be used for building permission-aware + // UIs and command-line tools, not for authorization checking. This operation + // may "fail open" without warning. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) + returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v2beta2/{resource=projects/*/locations/*/queues/*}:testIamPermissions" + body: "*" + }; + } + + // Lists the tasks in a queue. + // + // By default, only the [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC] + // view is retrieved due to performance considerations; + // [response_view][google.cloud.tasks.v2beta2.ListTasksRequest.response_view] + // controls the subset of information which is returned. + // + // The tasks may be returned in any order. The ordering may change at any + // time. + rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) { + option (google.api.http) = { + get: "/v2beta2/{parent=projects/*/locations/*/queues/*}/tasks" + }; + } + + // Gets a task. + rpc GetTask(GetTaskRequest) returns (Task) { + option (google.api.http) = { + get: "/v2beta2/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Creates a task and adds it to a queue. + // + // Tasks cannot be updated after creation; there is no UpdateTask command. + // + // * For [App Engine queues][google.cloud.tasks.v2beta2.AppEngineHttpTarget], + // the maximum task size is + // 100KB. + // * For [pull queues][google.cloud.tasks.v2beta2.PullTarget], the maximum + // task size is 1MB. + rpc CreateTask(CreateTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2beta2/{parent=projects/*/locations/*/queues/*}/tasks" + body: "*" + }; + } + + // Deletes a task. + // + // A task can be deleted if it is scheduled or dispatched. A task + // cannot be deleted if it has completed successfully or permanently + // failed. + rpc DeleteTask(DeleteTaskRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta2/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Leases tasks from a pull queue for + // [lease_duration][google.cloud.tasks.v2beta2.LeaseTasksRequest.lease_duration]. + // + // This method is invoked by the worker to obtain a lease. The + // worker must acknowledge the task via + // [AcknowledgeTask][google.cloud.tasks.v2beta2.CloudTasks.AcknowledgeTask] + // after they have performed the work associated with the task. + // + // The [payload][google.cloud.tasks.v2beta2.PullMessage.payload] is intended + // to store data that the worker needs to perform the work associated with the + // task. To return the payloads in the + // [response][google.cloud.tasks.v2beta2.LeaseTasksResponse], set + // [response_view][google.cloud.tasks.v2beta2.LeaseTasksRequest.response_view] + // to [FULL][google.cloud.tasks.v2beta2.Task.View.FULL]. + // + // A maximum of 10 qps of + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] requests are + // allowed per queue. [RESOURCE_EXHAUSTED][google.rpc.Code.RESOURCE_EXHAUSTED] + // is returned when this limit is + // exceeded. [RESOURCE_EXHAUSTED][google.rpc.Code.RESOURCE_EXHAUSTED] + // is also returned when + // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second] + // is exceeded. + rpc LeaseTasks(LeaseTasksRequest) returns (LeaseTasksResponse) { + option (google.api.http) = { + post: "/v2beta2/{parent=projects/*/locations/*/queues/*}/tasks:lease" + body: "*" + }; + } + + // Acknowledges a pull task. + // + // The worker, that is, the entity that + // [leased][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] this task must + // call this method to indicate that the work associated with the task has + // finished. + // + // The worker must acknowledge a task within the + // [lease_duration][google.cloud.tasks.v2beta2.LeaseTasksRequest.lease_duration] + // or the lease will expire and the task will become available to be leased + // again. After the task is acknowledged, it will not be returned + // by a later [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks], + // [GetTask][google.cloud.tasks.v2beta2.CloudTasks.GetTask], or + // [ListTasks][google.cloud.tasks.v2beta2.CloudTasks.ListTasks]. + rpc AcknowledgeTask(AcknowledgeTaskRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v2beta2/{name=projects/*/locations/*/queues/*/tasks/*}:acknowledge" + body: "*" + }; + } + + // Renew the current lease of a pull task. + // + // The worker can use this method to extend the lease by a new + // duration, starting from now. The new task lease will be + // returned in the task's + // [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time]. + rpc RenewLease(RenewLeaseRequest) returns (Task) { + option (google.api.http) = { + post: "/v2beta2/{name=projects/*/locations/*/queues/*/tasks/*}:renewLease" + body: "*" + }; + } + + // Cancel a pull task's lease. + // + // The worker can use this method to cancel a task's lease by + // setting its [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time] + // to now. This will make the task available to be leased to the next caller + // of [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks]. + rpc CancelLease(CancelLeaseRequest) returns (Task) { + option (google.api.http) = { + post: "/v2beta2/{name=projects/*/locations/*/queues/*/tasks/*}:cancelLease" + body: "*" + }; + } + + // Forces a task to run now. + // + // When this method is called, Cloud Tasks will dispatch the task, even if + // the task is already running, the queue has reached its + // [RateLimits][google.cloud.tasks.v2beta2.RateLimits] or is + // [PAUSED][google.cloud.tasks.v2beta2.Queue.State.PAUSED]. + // + // This command is meant to be used for manual debugging. For + // example, [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask] can be + // used to retry a failed task after a fix has been made or to manually force + // a task to be dispatched now. + // + // The dispatched task is returned. That is, the task that is returned + // contains the [status][google.cloud.tasks.v2beta2.Task.status] after the + // task is dispatched but before the task is received by its target. + // + // If Cloud Tasks receives a successful response from the task's + // target, then the task will be deleted; otherwise the task's + // [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time] will be + // reset to the time that + // [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask] was called plus + // the retry delay specified in the queue's + // [RetryConfig][google.cloud.tasks.v2beta2.RetryConfig]. + // + // [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask] returns + // [NOT_FOUND][google.rpc.Code.NOT_FOUND] when it is called on a + // task that has already succeeded or permanently failed. + // + // [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask] cannot be called + // on a [pull task][google.cloud.tasks.v2beta2.PullMessage]. + rpc RunTask(RunTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2beta2/{name=projects/*/locations/*/queues/*/tasks/*}:run" + body: "*" + }; + } +} + +// Request message for +// [ListQueues][google.cloud.tasks.v2beta2.CloudTasks.ListQueues]. +message ListQueuesRequest { + // Required. + // + // The location name. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + string parent = 1; + + // `filter` can be used to specify a subset of queues. Any + // [Queue][google.cloud.tasks.v2beta2.Queue] field can be used as a filter and + // several operators as supported. For example: `<=, <, >=, >, !=, =, :`. The + // filter syntax is the same as described in [Stackdriver's Advanced Logs + // Filters](https://cloud.google.com/logging/docs/view/advanced_filters). + // + // Sample filter "app_engine_http_target: *". + // + // Note that using filters might cause fewer queues than the + // requested_page size to be returned. + string filter = 2; + + // Requested page size. + // + // The maximum page size is 9800. If unspecified, the page size will + // be the maximum. Fewer queues than requested might be returned, + // even if more queues exist; use the + // [next_page_token][google.cloud.tasks.v2beta2.ListQueuesResponse.next_page_token] + // in the response to determine if more queues exist. + int32 page_size = 3; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2beta2.ListQueuesResponse.next_page_token] + // returned from the previous call to + // [ListQueues][google.cloud.tasks.v2beta2.CloudTasks.ListQueues] method. It + // is an error to switch the value of the + // [filter][google.cloud.tasks.v2beta2.ListQueuesRequest.filter] while + // iterating through pages. + string page_token = 4; +} + +// Response message for +// [ListQueues][google.cloud.tasks.v2beta2.CloudTasks.ListQueues]. +message ListQueuesResponse { + // The list of queues. + repeated Queue queues = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListQueues][google.cloud.tasks.v2beta2.CloudTasks.ListQueues] with this + // value as the + // [page_token][google.cloud.tasks.v2beta2.ListQueuesRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + // + // The page token is valid for only 2 hours. + string next_page_token = 2; +} + +// Request message for +// [GetQueue][google.cloud.tasks.v2beta2.CloudTasks.GetQueue]. +message GetQueueRequest { + // Required. + // + // The resource name of the queue. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for +// [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue]. +message CreateQueueRequest { + // Required. + // + // The location name in which the queue will be created. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + // + // The list of allowed locations can be obtained by calling Cloud + // Tasks' implementation of + // [ListLocations][google.cloud.location.Locations.ListLocations]. + string parent = 1; + + // Required. + // + // The queue to create. + // + // [Queue's name][google.cloud.tasks.v2beta2.Queue.name] cannot be the same as + // an existing queue. + Queue queue = 2; +} + +// Request message for +// [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue]. +message UpdateQueueRequest { + // Required. + // + // The queue to create or update. + // + // The queue's [name][google.cloud.tasks.v2beta2.Queue.name] must be + // specified. + // + // Output only fields cannot be modified using UpdateQueue. + // Any value specified for an output only field will be ignored. + // The queue's [name][google.cloud.tasks.v2beta2.Queue.name] cannot be + // changed. + Queue queue = 1; + + // A mask used to specify which fields of the queue are being updated. + // + // If empty, then all fields will be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for +// [DeleteQueue][google.cloud.tasks.v2beta2.CloudTasks.DeleteQueue]. +message DeleteQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for +// [PurgeQueue][google.cloud.tasks.v2beta2.CloudTasks.PurgeQueue]. +message PurgeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for +// [PauseQueue][google.cloud.tasks.v2beta2.CloudTasks.PauseQueue]. +message PauseQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for +// [ResumeQueue][google.cloud.tasks.v2beta2.CloudTasks.ResumeQueue]. +message ResumeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for listing tasks using +// [ListTasks][google.cloud.tasks.v2beta2.CloudTasks.ListTasks]. +message ListTasksRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string parent = 1; + + // The response_view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] will be returned. + // + // By default response_view is + // [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC]; not all information is + // retrieved by default because some data, such as payloads, might be + // desirable to return only when needed because of its large size or because + // of the sensitivity of data that it contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Task][google.cloud.tasks.v2beta2.Task] resource. + Task.View response_view = 2; + + // Requested page size. Fewer tasks than requested might be returned. + // + // The maximum page size is 1000. If unspecified, the page size will + // be the maximum. Fewer tasks than requested might be returned, + // even if more tasks exist; use + // [next_page_token][google.cloud.tasks.v2beta2.ListTasksResponse.next_page_token] + // in the response to determine if more tasks exist. + int32 page_size = 4; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2beta2.ListTasksResponse.next_page_token] + // returned from the previous call to + // [ListTasks][google.cloud.tasks.v2beta2.CloudTasks.ListTasks] method. + // + // The page token is valid for only 2 hours. + string page_token = 5; +} + +// Response message for listing tasks using +// [ListTasks][google.cloud.tasks.v2beta2.CloudTasks.ListTasks]. +message ListTasksResponse { + // The list of tasks. + repeated Task tasks = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListTasks][google.cloud.tasks.v2beta2.CloudTasks.ListTasks] with this + // value as the + // [page_token][google.cloud.tasks.v2beta2.ListTasksRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + string next_page_token = 2; +} + +// Request message for getting a task using +// [GetTask][google.cloud.tasks.v2beta2.CloudTasks.GetTask]. +message GetTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] will be returned. + // + // By default response_view is + // [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC]; not all information is + // retrieved by default because some data, such as payloads, might be + // desirable to return only when needed because of its large size or because + // of the sensitivity of data that it contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Task][google.cloud.tasks.v2beta2.Task] resource. + Task.View response_view = 2; +} + +// Request message for +// [CreateTask][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. +message CreateTaskRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // The queue must already exist. + string parent = 1; + + // Required. + // + // The task to add. + // + // Task names have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID`. + // The user can optionally specify a task + // [name][google.cloud.tasks.v2beta2.Task.name]. If a name is not specified + // then the system will generate a random unique task id, which will be set in + // the task returned in the [response][google.cloud.tasks.v2beta2.Task.name]. + // + // If [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time] is not + // set or is in the past then Cloud Tasks will set it to the current time. + // + // Task De-duplication: + // + // Explicitly specifying a task ID enables task de-duplication. If + // a task's ID is identical to that of an existing task or a task + // that was deleted or completed recently then the call will fail + // with [ALREADY_EXISTS][google.rpc.Code.ALREADY_EXISTS]. + // If the task's queue was created using Cloud Tasks, then another task with + // the same name can't be created for ~1hour after the original task was + // deleted or completed. If the task's queue was created using queue.yaml or + // queue.xml, then another task with the same name can't be created + // for ~9days after the original task was deleted or completed. + // + // Because there is an extra lookup cost to identify duplicate task + // names, these [CreateTask][google.cloud.tasks.v2beta2.CloudTasks.CreateTask] + // calls have significantly increased latency. Using hashed strings for the + // task id or for the prefix of the task id is recommended. Choosing task ids + // that are sequential or have sequential prefixes, for example using a + // timestamp, causes an increase in latency and error rates in all + // task commands. The infrastructure relies on an approximately + // uniform distribution of task ids to store and serve tasks + // efficiently. + Task task = 2; + + // The response_view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] will be returned. + // + // By default response_view is + // [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC]; not all information is + // retrieved by default because some data, such as payloads, might be + // desirable to return only when needed because of its large size or because + // of the sensitivity of data that it contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Task][google.cloud.tasks.v2beta2.Task] resource. + Task.View response_view = 3; +} + +// Request message for deleting a task using +// [DeleteTask][google.cloud.tasks.v2beta2.CloudTasks.DeleteTask]. +message DeleteTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; +} + +// Request message for leasing tasks using +// [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks]. +message LeaseTasksRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string parent = 1; + + // The maximum number of tasks to lease. + // + // The system will make a best effort to return as close to as + // `max_tasks` as possible. + // + // The largest that `max_tasks` can be is 1000. + int32 max_tasks = 2; + + // + // After the worker has successfully finished the work associated + // with the task, the worker must call via + // [AcknowledgeTask][google.cloud.tasks.v2beta2.CloudTasks.AcknowledgeTask] + // before the [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time]. + // Otherwise the task will be returned to a later + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] call so that + // another worker can retry it. + // + // The maximum lease duration is 1 week. + // `lease_duration` will be truncated to the nearest second. + google.protobuf.Duration lease_duration = 3; + + // The response_view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] will be returned. + // + // By default response_view is + // [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC]; not all information is + // retrieved by default because some data, such as payloads, might be + // desirable to return only when needed because of its large size or because + // of the sensitivity of data that it contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Task][google.cloud.tasks.v2beta2.Task] resource. + Task.View response_view = 4; + + // `filter` can be used to specify a subset of tasks to lease. + // + // When `filter` is set to `tag=<my-tag>` then the + // [response][google.cloud.tasks.v2beta2.LeaseTasksResponse] will contain only + // tasks whose [tag][google.cloud.tasks.v2beta2.PullMessage.tag] is equal to + // `<my-tag>`. `<my-tag>` must be less than 500 characters. + // + // When `filter` is set to `tag_function=oldest_tag()`, only tasks which have + // the same tag as the task with the oldest + // [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time] will be + // returned. + // + // Grammar Syntax: + // + // * `filter = "tag=" tag | "tag_function=" function` + // + // * `tag = string` + // + // * `function = "oldest_tag()"` + // + // The `oldest_tag()` function returns tasks which have the same tag as the + // oldest task (ordered by schedule time). + // + // SDK compatibility: Although the SDK allows tags to be either + // string or + // [bytes](https://cloud.google.com/appengine/docs/standard/java/javadoc/com/google/appengine/api/taskqueue/TaskOptions.html#tag-byte:A-), + // only UTF-8 encoded tags can be used in Cloud Tasks. Tag which + // aren't UTF-8 encoded can't be used in the + // [filter][google.cloud.tasks.v2beta2.LeaseTasksRequest.filter] and the + // task's [tag][google.cloud.tasks.v2beta2.PullMessage.tag] will be displayed + // as empty in Cloud Tasks. + string filter = 5; +} + +// Response message for leasing tasks using +// [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks]. +message LeaseTasksResponse { + // The leased tasks. + repeated Task tasks = 1; +} + +// Request message for acknowledging a task using +// [AcknowledgeTask][google.cloud.tasks.v2beta2.CloudTasks.AcknowledgeTask]. +message AcknowledgeTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // Required. + // + // The task's current schedule time, available in the + // [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time] returned by + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] response or + // [RenewLease][google.cloud.tasks.v2beta2.CloudTasks.RenewLease] response. + // This restriction is to ensure that your worker currently holds the lease. + google.protobuf.Timestamp schedule_time = 2; +} + +// Request message for renewing a lease using +// [RenewLease][google.cloud.tasks.v2beta2.CloudTasks.RenewLease]. +message RenewLeaseRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // Required. + // + // The task's current schedule time, available in the + // [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time] returned by + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] response or + // [RenewLease][google.cloud.tasks.v2beta2.CloudTasks.RenewLease] response. + // This restriction is to ensure that your worker currently holds the lease. + google.protobuf.Timestamp schedule_time = 2; + + // Required. + // + // The desired new lease duration, starting from now. + // + // + // The maximum lease duration is 1 week. + // `lease_duration` will be truncated to the nearest second. + google.protobuf.Duration lease_duration = 3; + + // The response_view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] will be returned. + // + // By default response_view is + // [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC]; not all information is + // retrieved by default because some data, such as payloads, might be + // desirable to return only when needed because of its large size or because + // of the sensitivity of data that it contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Task][google.cloud.tasks.v2beta2.Task] resource. + Task.View response_view = 4; +} + +// Request message for canceling a lease using +// [CancelLease][google.cloud.tasks.v2beta2.CloudTasks.CancelLease]. +message CancelLeaseRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // Required. + // + // The task's current schedule time, available in the + // [schedule_time][google.cloud.tasks.v2beta2.Task.schedule_time] returned by + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] response or + // [RenewLease][google.cloud.tasks.v2beta2.CloudTasks.RenewLease] response. + // This restriction is to ensure that your worker currently holds the lease. + google.protobuf.Timestamp schedule_time = 2; + + // The response_view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] will be returned. + // + // By default response_view is + // [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC]; not all information is + // retrieved by default because some data, such as payloads, might be + // desirable to return only when needed because of its large size or because + // of the sensitivity of data that it contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Task][google.cloud.tasks.v2beta2.Task] resource. + Task.View response_view = 3; +} + +// Request message for forcing a task to run now using +// [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask]. +message RunTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] will be returned. + // + // By default response_view is + // [BASIC][google.cloud.tasks.v2beta2.Task.View.BASIC]; not all information is + // retrieved by default because some data, such as payloads, might be + // desirable to return only when needed because of its large size or because + // of the sensitivity of data that it contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Task][google.cloud.tasks.v2beta2.Task] resource. + Task.View response_view = 2; +} diff --git a/google/cloud/tasks/v2beta2/cloudtasks_gapic.yaml b/google/cloud/tasks/v2beta2/cloudtasks_gapic.yaml new file mode 100644 index 000000000..d0693fe5f --- /dev/null +++ b/google/cloud/tasks/v2beta2/cloudtasks_gapic.yaml @@ -0,0 +1,512 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.tasks.v2beta2 + python: + package_name: google.cloud.tasks_v2beta2.gapic + go: + package_name: cloud.google.com/go/cloudtasks/apiv2beta2 + csharp: + package_name: Google.Cloud.Tasks.V2Beta2 + ruby: + package_name: Google::Cloud::Tasks::V2beta2 + php: + package_name: Google\Cloud\Tasks\V2beta2 + nodejs: + package_name: tasks.v2beta2 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.tasks.v2beta2.CloudTasks + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/queues/{queue} + entity_name: queue + - name_pattern: projects/{project}/locations/{location}/queues/{queue}/tasks/{task} + entity_name: task + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListQueues + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: queues + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: GetQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: CreateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - queue + required_fields: + - parent + - queue + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: UpdateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - queue + - update_mask + required_fields: + - queue + header_request_params: + - queue.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + queue.name: queue + timeout_millis: 10000 + - name: DeleteQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PurgeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PauseQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: ResumeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: GetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: SetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + header_request_params: + - resource + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: TestIamPermissions + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: ListTasks + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: tasks + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: GetTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: CreateTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - task + required_fields: + - parent + - task + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: DeleteTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: LeaseTasks + resource_name_treatment: STATIC_TYPES + required_fields: + - parent + - lease_duration + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: AcknowledgeTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + - schedule_time + required_fields: + - name + - schedule_time + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: RenewLease + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + - schedule_time + - lease_duration + required_fields: + - name + - schedule_time + - lease_duration + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: CancelLease + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + - schedule_time + required_fields: + - name + - schedule_time + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: RunTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 +resource_name_generation: +- message_name: Queue + field_entity_map: + name: queue +- message_name: Task + field_entity_map: + name: task +- message_name: ListQueuesRequest + field_entity_map: + parent: location +- message_name: GetQueueRequest + field_entity_map: + name: queue +- message_name: CreateQueueRequest + field_entity_map: + parent: location +- message_name: UpdateQueueRequest + field_entity_map: + queue.name: queue +- message_name: DeleteQueueRequest + field_entity_map: + name: queue +- message_name: PurgeQueueRequest + field_entity_map: + name: queue +- message_name: PauseQueueRequest + field_entity_map: + name: queue +- message_name: ResumeQueueRequest + field_entity_map: + name: queue +- message_name: ListTasksRequest + field_entity_map: + parent: queue +- message_name: GetTaskRequest + field_entity_map: + name: task +- message_name: CreateTaskRequest + field_entity_map: + parent: queue +- message_name: DeleteTaskRequest + field_entity_map: + name: task +- message_name: LeaseTasksRequest + field_entity_map: + parent: queue +- message_name: AcknowledgeTaskRequest + field_entity_map: + name: task +- message_name: RenewLeaseRequest + field_entity_map: + name: task +- message_name: CancelLeaseRequest + field_entity_map: + name: task +- message_name: RunTaskRequest + field_entity_map: + name: task +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: "*" diff --git a/google/cloud/tasks/v2beta2/queue.proto b/google/cloud/tasks/v2beta2/queue.proto new file mode 100644 index 000000000..3aa4b80b3 --- /dev/null +++ b/google/cloud/tasks/v2beta2/queue.proto @@ -0,0 +1,388 @@ +// Copyright 2018 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.tasks.v2beta2; + +import "google/api/annotations.proto"; +import "google/cloud/tasks/v2beta2/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "QueueProto"; +option java_package = "com.google.cloud.tasks.v2beta2"; + +// A queue is a container of related tasks. Queues are configured to manage +// how those tasks are dispatched. Configurable properties include rate limits, +// retry options, target types, and others. +message Queue { + // State of the queue. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The queue is running. Tasks can be dispatched. + // + // If the queue was created using Cloud Tasks and the queue has + // had no activity (method calls or task dispatches) for 30 days, + // the queue may take a few minutes to re-activate. Some method + // calls may return [NOT_FOUND][google.rpc.Code.NOT_FOUND] and + // tasks may not be dispatched for a few minutes until the queue + // has been re-activated. + RUNNING = 1; + + // Tasks are paused by the user. If the queue is paused then Cloud + // Tasks will stop delivering tasks from it, but more tasks can + // still be added to it by the user. When a pull queue is paused, + // all [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] calls + // will return a [FAILED_PRECONDITION][google.rpc.Code.FAILED_PRECONDITION]. + PAUSED = 2; + + // The queue is disabled. + // + // A queue becomes `DISABLED` when + // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref) + // or + // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref) + // is uploaded which does not contain the queue. You cannot directly disable + // a queue. + // + // When a queue is disabled, tasks can still be added to a queue + // but the tasks are not dispatched and + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] calls + // return a `FAILED_PRECONDITION` error. + // + // To permanently delete this queue and all of its tasks, call + // [DeleteQueue][google.cloud.tasks.v2beta2.CloudTasks.DeleteQueue]. + DISABLED = 3; + } + + // Caller-specified and required in + // [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue], after + // which it becomes output only. + // + // The queue name. + // + // The queue name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the queue's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + string name = 1; + + // Caller-specified and required in + // [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue][], after + // which the queue config type becomes output only, though fields within the + // config are mutable. + // + // The queue's target. + // + // The target applies to all tasks in the queue. + oneof target_type { + // App Engine HTTP target. + // + // An App Engine queue is a queue that has an + // [AppEngineHttpTarget][google.cloud.tasks.v2beta2.AppEngineHttpTarget]. + AppEngineHttpTarget app_engine_http_target = 3; + + // Pull target. + // + // A pull queue is a queue that has a + // [PullTarget][google.cloud.tasks.v2beta2.PullTarget]. + PullTarget pull_target = 4; + } + + // Rate limits for task dispatches. + // + // [rate_limits][google.cloud.tasks.v2beta2.Queue.rate_limits] and + // [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] are related + // because they both control task attempts however they control how tasks are + // attempted in different ways: + // + // * [rate_limits][google.cloud.tasks.v2beta2.Queue.rate_limits] controls the + // total rate of + // dispatches from a queue (i.e. all traffic dispatched from the + // queue, regardless of whether the dispatch is from a first + // attempt or a retry). + // * [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] controls + // what happens to + // particular a task after its first attempt fails. That is, + // [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] controls + // task retries (the second attempt, third attempt, etc). + RateLimits rate_limits = 5; + + // Settings that determine the retry behavior. + // + // * For tasks created using Cloud Tasks: the queue-level retry settings + // apply to all tasks in the queue that were created using Cloud Tasks. + // Retry settings cannot be set on individual tasks. + // * For tasks created using the App Engine SDK: the queue-level retry + // settings apply to all tasks in the queue which do not have retry settings + // explicitly set on the task and were created by the App Engine SDK. See + // [App Engine + // documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks). + RetryConfig retry_config = 6; + + // Output only. The state of the queue. + // + // `state` can only be changed by called + // [PauseQueue][google.cloud.tasks.v2beta2.CloudTasks.PauseQueue], + // [ResumeQueue][google.cloud.tasks.v2beta2.CloudTasks.ResumeQueue], or + // uploading + // [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref). + // [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue] cannot be + // used to change `state`. + State state = 7; + + // Output only. The last time this queue was purged. + // + // All tasks that were [created][google.cloud.tasks.v2beta2.Task.create_time] + // before this time were purged. + // + // A queue can be purged using + // [PurgeQueue][google.cloud.tasks.v2beta2.CloudTasks.PurgeQueue], the [App + // Engine Task Queue SDK, or the Cloud + // Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue). + // + // Purge time will be truncated to the nearest microsecond. Purge + // time will be unset if the queue has never been purged. + google.protobuf.Timestamp purge_time = 8; +} + +// Rate limits. +// +// This message determines the maximum rate that tasks can be dispatched by a +// queue, regardless of whether the dispatch is a first task attempt or a retry. +// +// Note: The debugging command, +// [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask], will run a task +// even if the queue has reached its +// [RateLimits][google.cloud.tasks.v2beta2.RateLimits]. +message RateLimits { + // The maximum rate at which tasks are dispatched from this queue. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // * For [App Engine queues][google.cloud.tasks.v2beta2.AppEngineHttpTarget], + // the maximum allowed value + // is 500. + // * This field is output only for [pull + // queues][google.cloud.tasks.v2beta2.PullTarget]. In addition to the + // `max_tasks_dispatched_per_second` limit, a maximum of 10 QPS of + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] requests + // are allowed per pull queue. + // + // + // This field has the same meaning as + // [rate in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate). + double max_tasks_dispatched_per_second = 1; + + // Output only. The max burst size. + // + // Max burst size limits how fast tasks in queue are processed when + // many tasks are in the queue and the rate is high. This field + // allows the queue to have a high rate so processing starts shortly + // after a task is enqueued, but still limits resource usage when + // many tasks are enqueued in a short period of time. + // + // The [token bucket](https://wikipedia.org/wiki/Token_Bucket) + // algorithm is used to control the rate of task dispatches. Each + // queue has a token bucket that holds tokens, up to the maximum + // specified by `max_burst_size`. Each time a task is dispatched, a + // token is removed from the bucket. Tasks will be dispatched until + // the queue's bucket runs out of tokens. The bucket will be + // continuously refilled with new tokens based on + // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second]. + // + // Cloud Tasks will pick the value of `max_burst_size` based on the + // value of + // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second]. + // + // For App Engine queues that were created or updated using + // `queue.yaml/xml`, `max_burst_size` is equal to + // [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size). + // Since `max_burst_size` is output only, if + // [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue] is called + // on a queue created by `queue.yaml/xml`, `max_burst_size` will be reset + // based on the value of + // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second], + // regardless of whether + // [max_tasks_dispatched_per_second][google.cloud.tasks.v2beta2.RateLimits.max_tasks_dispatched_per_second] + // is updated. + // + int32 max_burst_size = 2; + + // The maximum number of concurrent tasks that Cloud Tasks allows + // to be dispatched for this queue. After this threshold has been + // reached, Cloud Tasks stops dispatching tasks until the number of + // concurrent requests decreases. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // The maximum allowed value is 5,000. + // + // This field is output only for + // [pull queues][google.cloud.tasks.v2beta2.PullTarget] and always -1, which + // indicates no limit. No other queue types can have `max_concurrent_tasks` + // set to -1. + // + // + // This field has the same meaning as + // [max_concurrent_requests in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests). + int32 max_concurrent_tasks = 3; +} + +// Retry config. +// +// These settings determine how a failed task attempt is retried. +message RetryConfig { + // Number of attempts per task. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // + // This field has the same meaning as + // [task_retry_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + oneof num_attempts { + // The maximum number of attempts for a task. + // + // Cloud Tasks will attempt the task `max_attempts` times (that + // is, if the first attempt fails, then there will be + // `max_attempts - 1` retries). Must be > 0. + int32 max_attempts = 1; + + // If true, then the number of attempts is unlimited. + bool unlimited_attempts = 2; + } + + // If positive, `max_retry_duration` specifies the time limit for + // retrying a failed task, measured from when the task was first + // attempted. Once `max_retry_duration` time has passed *and* the + // task has been attempted + // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times, + // no further attempts will be made and the task will be deleted. + // + // If zero, then the task age is unlimited. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // This field is output only for [pull + // queues][google.cloud.tasks.v2beta2.PullTarget]. + // + // + // `max_retry_duration` will be truncated to the nearest second. + // + // This field has the same meaning as + // [task_age_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_retry_duration = 3; + + // A task will be [scheduled][google.cloud.tasks.v2beta2.Task.schedule_time] + // for retry between + // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] duration + // after it fails, if the queue's + // [RetryConfig][google.cloud.tasks.v2beta2.RetryConfig] specifies that the + // task should be retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // This field is output only for [pull + // queues][google.cloud.tasks.v2beta2.PullTarget]. + // + // + // `min_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [min_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration min_backoff = 4; + + // A task will be [scheduled][google.cloud.tasks.v2beta2.Task.schedule_time] + // for retry between + // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] duration + // after it fails, if the queue's + // [RetryConfig][google.cloud.tasks.v2beta2.RetryConfig] specifies that the + // task should be retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // This field is output only for [pull + // queues][google.cloud.tasks.v2beta2.PullTarget]. + // + // + // `max_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [max_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_backoff = 5; + + // The time between retries will double `max_doublings` times. + // + // A task's retry interval starts at + // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff], then + // doubles `max_doublings` times, then increases linearly, and finally retries + // retries at intervals of + // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] up to + // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times. + // + // For example, if + // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] is 10s, + // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] is 300s, + // and `max_doublings` is 3, then the a task will first be retried in 10s. The + // retry interval will double three times, and then increase linearly by 2^3 * + // 10s. Finally, the task will retry at intervals of + // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] until the + // task has been attempted + // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times. + // Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s, + // 300s, .... + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // This field is output only for [pull + // queues][google.cloud.tasks.v2beta2.PullTarget]. + // + // + // This field has the same meaning as + // [max_doublings in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + int32 max_doublings = 6; +} diff --git a/google/cloud/tasks/v2beta2/target.proto b/google/cloud/tasks/v2beta2/target.proto new file mode 100644 index 000000000..ae1b5555d --- /dev/null +++ b/google/cloud/tasks/v2beta2/target.proto @@ -0,0 +1,383 @@ +// Copyright 2018 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.tasks.v2beta2; + +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TargetProto"; +option java_package = "com.google.cloud.tasks.v2beta2"; + +// Pull target. +message PullTarget {} + +// The pull message contains data that can be used by the caller of +// [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] to process the +// task. +// +// This proto can only be used for tasks in a queue which has +// [pull_target][google.cloud.tasks.v2beta2.Queue.pull_target] set. +message PullMessage { + // A data payload consumed by the worker to execute the task. + bytes payload = 1; + + // The task's tag. + // + // Tags allow similar tasks to be processed in a batch. If you label + // tasks with a tag, your worker can + // [lease tasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] with the + // same tag using + // [filter][google.cloud.tasks.v2beta2.LeaseTasksRequest.filter]. For example, + // if you want to aggregate the events associated with a specific user once a + // day, you could tag tasks with the user ID. + // + // The task's tag can only be set when the + // [task is created][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. + // + // The tag must be less than 500 characters. + // + // SDK compatibility: Although the SDK allows tags to be either + // string or + // [bytes](https://cloud.google.com/appengine/docs/standard/java/javadoc/com/google/appengine/api/taskqueue/TaskOptions.html#tag-byte:A-), + // only UTF-8 encoded tags can be used in Cloud Tasks. If a tag isn't UTF-8 + // encoded, the tag will be empty when the task is returned by Cloud Tasks. + string tag = 2; +} + +// App Engine HTTP target. +// +// The task will be delivered to the App Engine application hostname +// specified by its +// [AppEngineHttpTarget][google.cloud.tasks.v2beta2.AppEngineHttpTarget] and +// [AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest]. The +// documentation for +// [AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest] +// explains how the task's host URL is constructed. +// +// Using [AppEngineHttpTarget][google.cloud.tasks.v2beta2.AppEngineHttpTarget] +// requires +// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) +// Google IAM permission for the project +// and the following scope: +// +// `https://www.googleapis.com/auth/cloud-platform` +message AppEngineHttpTarget { + // Overrides for the + // [task-level + // app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. + // + // If set, `app_engine_routing_override` is used for all tasks in + // the queue, no matter what the setting is for the + // [task-level + // app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing_override = 1; +} + +// App Engine HTTP request. +// +// The message defines the HTTP request that is sent to an App Engine app when +// the task is dispatched. +// +// This proto can only be used for tasks in a queue which has +// [app_engine_http_target][google.cloud.tasks.v2beta2.Queue.app_engine_http_target] +// set. +// +// Using [AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest] +// requires +// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) +// Google IAM permission for the project +// and the following scope: +// +// `https://www.googleapis.com/auth/cloud-platform` +// +// The task will be delivered to the App Engine app which belongs to the same +// project as the queue. For more information, see +// [How Requests are +// Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) +// and how routing is affected by +// [dispatch +// files](https://cloud.google.com/appengine/docs/python/config/dispatchref). +// +// The [AppEngineRouting][google.cloud.tasks.v2beta2.AppEngineRouting] used to +// construct the URL that the task is delivered to can be set at the queue-level +// or task-level: +// +// * If set, +// [app_engine_routing_override][google.cloud.tasks.v2beta2.AppEngineHttpTarget.app_engine_routing_override] +// is used for all tasks in the queue, no matter what the setting +// is for the +// [task-level +// app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. +// +// +// The `url` that the task will be sent to is: +// +// * `url =` [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] `+` +// [relative_url][google.cloud.tasks.v2beta2.AppEngineHttpRequest.relative_url] +// +// The task attempt has succeeded if the app's request handler returns +// an HTTP response code in the range [`200` - `299`]. `503` is +// considered an App Engine system error instead of an application +// error. Requests returning error `503` will be retried regardless of +// retry configuration and not counted against retry counts. +// Any other response code or a failure to receive a response before the +// deadline is a failed attempt. +message AppEngineHttpRequest { + // The HTTP method to use for the request. The default is POST. + // + // The app's request handler for the task's target URL must be able to handle + // HTTP requests with this http_method, otherwise the task attempt will fail + // with error code 405 (Method Not Allowed). See + // [Writing a push task request + // handler](https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler) + // and the documentation for the request handlers in the language your app is + // written in e.g. + // [Python Request + // Handler](https://cloud.google.com/appengine/docs/python/tools/webapp/requesthandlerclass). + HttpMethod http_method = 1; + + // Task-level setting for App Engine routing. + // + // If set, + // [app_engine_routing_override][google.cloud.tasks.v2beta2.AppEngineHttpTarget.app_engine_routing_override] + // is used for all tasks in the queue, no matter what the setting is for the + // [task-level + // app_engine_routing][google.cloud.tasks.v2beta2.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing = 2; + + // The relative URL. + // + // The relative URL must begin with "/" and must be a valid HTTP relative URL. + // It can contain a path and query string arguments. + // If the relative URL is empty, then the root path "/" will be used. + // No spaces are allowed, and the maximum length allowed is 2083 characters. + string relative_url = 3; + + // HTTP request headers. + // + // This map contains the header field names and values. + // Headers can be set when the + // [task is created][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. + // Repeated headers are not supported but a header value can contain commas. + // + // Cloud Tasks sets some headers to default values: + // + // * `User-Agent`: By default, this header is + // `"AppEngine-Google; (+http://code.google.com/appengine)"`. + // This header can be modified, but Cloud Tasks will append + // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the + // modified `User-Agent`. + // + // If the task has a + // [payload][google.cloud.tasks.v2beta2.AppEngineHttpRequest.payload], Cloud + // Tasks sets the following headers: + // + // * `Content-Type`: By default, the `Content-Type` header is set to + // `"application/octet-stream"`. The default can be overridden by explicitly + // setting `Content-Type` to a particular media type when the + // [task is created][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. + // For example, `Content-Type` can be set to `"application/json"`. + // * `Content-Length`: This is computed by Cloud Tasks. This value is + // output only. It cannot be changed. + // + // The headers below cannot be set or overridden: + // + // * `Host` + // * `X-Google-*` + // * `X-AppEngine-*` + // + // In addition, Cloud Tasks sets some headers when the task is dispatched, + // such as headers containing information about the task; see + // [request + // headers](https://cloud.google.com/appengine/docs/python/taskqueue/push/creating-handlers#reading_request_headers). + // These headers are set only when the task is dispatched, so they are not + // visible when the task is returned in a Cloud Tasks response. + // + // Although there is no specific limit for the maximum number of headers or + // the size, there is a limit on the maximum size of the + // [Task][google.cloud.tasks.v2beta2.Task]. For more information, see the + // [CreateTask][google.cloud.tasks.v2beta2.CloudTasks.CreateTask] + // documentation. + map<string, string> headers = 4; + + // Payload. + // + // The payload will be sent as the HTTP message body. A message + // body, and thus a payload, is allowed only if the HTTP method is + // POST or PUT. It is an error to set a data payload on a task with + // an incompatible [HttpMethod][google.cloud.tasks.v2beta2.HttpMethod]. + bytes payload = 5; +} + +// App Engine Routing. +// +// For more information about services, versions, and instances see +// [An Overview of App +// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), +// [Microservices Architecture on Google App +// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), +// [App Engine Standard request +// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), +// and [App Engine Flex request +// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). +message AppEngineRouting { + // App service. + // + // By default, the task is sent to the service which is the default + // service when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is + // not parsable into + // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance]. For + // example, some tasks which were created using the App Engine SDK use a + // custom domain name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is not parsable, + // then [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] are the + // empty string. + string service = 1; + + // App version. + // + // By default, the task is sent to the version which is the default + // version when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is + // not parsable into + // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance]. For + // example, some tasks which were created using the App Engine SDK use a + // custom domain name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is not parsable, + // then [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] are the + // empty string. + string version = 2; + + // App instance. + // + // By default, the task is sent to an instance which is available when + // the task is attempted. + // + // Requests can only be sent to a specific instance if + // [manual scaling is used in App Engine + // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). + // App Engine Flex does not support instances. For more information, see + // [App Engine Standard request + // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) + // and [App Engine Flex request + // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). + string instance = 3; + + // Output only. The host that the task is sent to. + // + // For more information, see + // [How Requests are + // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). + // + // The host is constructed as: + // + // + // * `host = [application_domain_name]`</br> + // `| [service] + '.' + [application_domain_name]`</br> + // `| [version] + '.' + [application_domain_name]`</br> + // `| [version_dot_service]+ '.' + [application_domain_name]`</br> + // `| [instance] + '.' + [application_domain_name]`</br> + // `| [instance_dot_service] + '.' + [application_domain_name]`</br> + // `| [instance_dot_version] + '.' + [application_domain_name]`</br> + // `| [instance_dot_version_dot_service] + '.' + [application_domain_name]` + // + // * `application_domain_name` = The domain name of the app, for + // example <app-id>.appspot.com, which is associated with the + // queue's project ID. Some tasks which were created using the App Engine + // SDK use a custom domain name. + // + // * `service =` + // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] + // + // * `version =` + // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] + // + // * `version_dot_service =` + // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] `+ '.' +` + // [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] + // + // * `instance =` + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] + // + // * `instance_dot_service =` + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] `+ '.' + // +` [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] + // + // * `instance_dot_version =` + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] `+ '.' + // +` [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] + // + // * `instance_dot_version_dot_service =` + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] `+ '.' + // +` [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] `+ '.' + // +` [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] + // + // If [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] is empty, + // then the task will be sent to the service which is the default service when + // the task is attempted. + // + // If [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] is empty, + // then the task will be sent to the version which is the default version when + // the task is attempted. + // + // If [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] is + // empty, then the task will be sent to an instance which is available when + // the task is attempted. + // + // If [service][google.cloud.tasks.v2beta2.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta2.AppEngineRouting.version], or + // [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] is + // invalid, then the task will be sent to the default version of the default + // service when the task is attempted. + string host = 4; +} + +// The HTTP method used to execute the task. +enum HttpMethod { + // HTTP method unspecified + HTTP_METHOD_UNSPECIFIED = 0; + + // HTTP POST + POST = 1; + + // HTTP GET + GET = 2; + + // HTTP HEAD + HEAD = 3; + + // HTTP PUT + PUT = 4; + + // HTTP DELETE + DELETE = 5; +} diff --git a/google/cloud/tasks/v2beta2/task.proto b/google/cloud/tasks/v2beta2/task.proto new file mode 100644 index 000000000..f9e18be49 --- /dev/null +++ b/google/cloud/tasks/v2beta2/task.proto @@ -0,0 +1,194 @@ +// Copyright 2018 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.tasks.v2beta2; + +import "google/api/annotations.proto"; +import "google/cloud/tasks/v2beta2/target.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta2;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TaskProto"; +option java_package = "com.google.cloud.tasks.v2beta2"; + +// A unit of scheduled work. +message Task { + // The view specifies a subset of [Task][google.cloud.tasks.v2beta2.Task] + // data. + // + // When a task is returned in a response, not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + enum View { + // Unspecified. Defaults to BASIC. + VIEW_UNSPECIFIED = 0; + + // The basic view omits fields which can be large or can contain + // sensitive data. + // + // This view does not include the + // ([payload in + // AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest] + // and [payload in + // PullMessage][google.cloud.tasks.v2beta2.PullMessage.payload]). These + // payloads are desirable to return only when needed, because they can be + // large and because of the sensitivity of the data that you choose to store + // in it. + BASIC = 1; + + // All information is returned. + // + // Authorization for [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] + // requires `cloudtasks.tasks.fullView` [Google + // IAM](https://cloud.google.com/iam/) permission on the + // [Queue][google.cloud.tasks.v2beta2.Queue] resource. + FULL = 2; + } + + // Optionally caller-specified in + // [CreateTask][google.cloud.tasks.v2beta2.CloudTasks.CreateTask]. + // + // The task name. + // + // The task name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the task's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + // * `TASK_ID` can contain only letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), or underscores (_). The maximum length is 500 characters. + string name = 1; + + // Required. + // + // The task's payload is used by the task's target to process the task. + // A payload is valid only if it is compatible with the queue's target. + oneof payload_type { + // App Engine HTTP request that is sent to the task's target. Can + // be set only if + // [app_engine_http_target][google.cloud.tasks.v2beta2.Queue.app_engine_http_target] + // is set on the queue. + // + // An App Engine task is a task that has + // [AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest] + // set. + AppEngineHttpRequest app_engine_http_request = 3; + + // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] to process + // the task. Can be set only if + // [pull_target][google.cloud.tasks.v2beta2.Queue.pull_target] is set on the + // queue. + // + // A pull task is a task that has + // [PullMessage][google.cloud.tasks.v2beta2.PullMessage] set. + PullMessage pull_message = 4; + } + + // The time when the task is scheduled to be attempted. + // + // For App Engine queues, this is when the task will be attempted or retried. + // + // For pull queues, this is the time when the task is available to + // be leased; if a task is currently leased, this is the time when + // the current lease expires, that is, the time that the task was + // leased plus the + // [lease_duration][google.cloud.tasks.v2beta2.LeaseTasksRequest.lease_duration]. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 5; + + // Output only. The time that the task was created. + // + // `create_time` will be truncated to the nearest second. + google.protobuf.Timestamp create_time = 6; + + // Output only. The task status. + TaskStatus status = 7; + + // Output only. The view specifies which subset of the + // [Task][google.cloud.tasks.v2beta2.Task] has been returned. + View view = 8; +} + +// Status of the task. +message TaskStatus { + // Output only. The number of attempts dispatched. + // + // This count includes tasks which have been dispatched but haven't + // received a response. + int32 attempt_dispatch_count = 1; + + // Output only. The number of attempts which have received a response. + // + // This field is not calculated for [pull + // tasks][google.cloud.tasks.v2beta2.PullMessage]. + int32 attempt_response_count = 2; + + // Output only. The status of the task's first attempt. + // + // Only + // [dispatch_time][google.cloud.tasks.v2beta2.AttemptStatus.dispatch_time] + // will be set. The other + // [AttemptStatus][google.cloud.tasks.v2beta2.AttemptStatus] information is + // not retained by Cloud Tasks. + // + // This field is not calculated for [pull + // tasks][google.cloud.tasks.v2beta2.PullMessage]. + AttemptStatus first_attempt_status = 3; + + // Output only. The status of the task's last attempt. + // + // This field is not calculated for [pull + // tasks][google.cloud.tasks.v2beta2.PullMessage]. + AttemptStatus last_attempt_status = 4; +} + +// The status of a task attempt. +message AttemptStatus { + // Output only. The time that this attempt was scheduled. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 1; + + // Output only. The time that this attempt was dispatched. + // + // `dispatch_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp dispatch_time = 2; + + // Output only. The time that this attempt response was received. + // + // `response_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp response_time = 3; + + // Output only. The response from the target for this attempt. + // + // If the task has not been attempted or the task is currently running + // then the response status is unset. + google.rpc.Status response_status = 4; +} diff --git a/google/cloud/tasks/v2beta3/BUILD.bazel b/google/cloud/tasks/v2beta3/BUILD.bazel new file mode 100644 index 000000000..6b313d42c --- /dev/null +++ b/google/cloud/tasks/v2beta3/BUILD.bazel @@ -0,0 +1,156 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "tasks_proto", + srcs = [ + "cloudtasks.proto", + "queue.proto", + "target.proto", + "task.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/iam/v1:iam_policy_proto", + "//google/iam/v1:policy_proto", + "//google/rpc:code_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "tasks_proto_with_info", + deps = [":tasks_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", + "@com_google_api_grpc_proto_google_iam_v1//jar", +] + +java_proto_library( + name = "tasks_java_proto", + deps = [":tasks_proto"], +) + +java_grpc_library( + name = "tasks_java_grpc", + srcs = [":tasks_proto"], + deps = [":tasks_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "tasks_resource_name_java_proto", + gapic_yaml = "cloudtasks_gapic.yaml", + deps = [":tasks_proto"], +) + +java_gapic_library( + name = "tasks_java_gapic", + src = ":tasks_proto_with_info", + gapic_yaml = "cloudtasks_gapic.yaml", + service_yaml = "//google/cloud/tasks:cloudtasks_v2beta3.yaml", + test_deps = [":tasks_java_grpc"], + deps = [ + ":tasks_java_proto", + ":tasks_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":tasks_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.tasks.v2beta3.CloudTasksClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-tasks-v2beta3-java", + client_deps = [":tasks_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":tasks_java_gapic_test"], + grpc_deps = [":tasks_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":tasks_java_proto", + ":tasks_proto", + ":tasks_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "tasks_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta3", + protos = [":tasks_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/iam/v1:iam_go_proto", + "//google/rpc:code_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "tasks_go_gapic", + src = ":tasks_proto_with_info", + gapic_yaml = "cloudtasks_gapic.yaml", + importpath = "cloud.google.com/go/cloudtasks/apiv2beta3", + service_yaml = "//google/cloud/tasks:cloudtasks_v2beta3.yaml", + deps = [ + ":tasks_go_proto", + "//google/iam/v1:iam_go_proto", + "@io_bazel_rules_go//proto/wkt:duration_go_proto", + ], +) + +go_test( + name = "tasks_go_gapic_test", + srcs = [":tasks_go_gapic_srcjar_test"], + embed = [":tasks_go_gapic"], + importpath = "cloud.google.com/go/cloudtasks/apiv2beta3", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-tasks-v2beta3-go", + deps = [ + ":tasks_go_gapic", + ":tasks_go_gapic_srcjar-smoke-test.srcjar", + ":tasks_go_gapic_srcjar-test.srcjar", + ":tasks_go_proto", + ], +) diff --git a/google/cloud/tasks/v2beta3/cloudtasks.proto b/google/cloud/tasks/v2beta3/cloudtasks.proto new file mode 100644 index 000000000..8868a0b33 --- /dev/null +++ b/google/cloud/tasks/v2beta3/cloudtasks.proto @@ -0,0 +1,600 @@ +// Copyright 2019 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.tasks.v2beta3; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/cloud/tasks/v2beta3/task.proto"; +import "google/cloud/tasks/v2beta3/queue.proto"; +import "google/iam/v1/iam_policy.proto"; +import "google/iam/v1/policy.proto"; +import "google/rpc/code.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta3;tasks"; +option java_multiple_files = true; +option java_outer_classname = "CloudTasksProto"; +option java_package = "com.google.cloud.tasks.v2beta3"; +option objc_class_prefix = "TASKS"; + +// Cloud Tasks allows developers to manage the execution of background +// work in their applications. +service CloudTasks { + // Lists queues. + // + // Queues are returned in lexicographical order. + rpc ListQueues(ListQueuesRequest) returns (ListQueuesResponse) { + option (google.api.http) = { + get: "/v2beta3/{parent=projects/*/locations/*}/queues" + }; + } + + // Gets a queue. + rpc GetQueue(GetQueueRequest) returns (Queue) { + option (google.api.http) = { + get: "/v2beta3/{name=projects/*/locations/*/queues/*}" + }; + } + + // Creates a queue. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of whether + // it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc CreateQueue(CreateQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta3/{parent=projects/*/locations/*}/queues" + body: "queue" + }; + } + + // Updates a queue. + // + // This method creates the queue if it does not exist and updates + // the queue if it does exist. + // + // Queues created with this method allow tasks to live for a maximum of 31 + // days. After a task is 31 days old, the task will be deleted regardless of whether + // it was dispatched or not. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc UpdateQueue(UpdateQueueRequest) returns (Queue) { + option (google.api.http) = { + patch: "/v2beta3/{queue.name=projects/*/locations/*/queues/*}" + body: "queue" + }; + } + + // Deletes a queue. + // + // This command will delete the queue even if it has tasks in it. + // + // Note: If you delete a queue, a queue with the same name can't be created + // for 7 days. + // + // WARNING: Using this method may have unintended side effects if you are + // using an App Engine `queue.yaml` or `queue.xml` file to manage your queues. + // Read + // [Overview of Queue Management and queue.yaml](https://cloud.google.com/tasks/docs/queue-yaml) + // before using this method. + rpc DeleteQueue(DeleteQueueRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta3/{name=projects/*/locations/*/queues/*}" + }; + } + + // Purges a queue by deleting all of its tasks. + // + // All tasks created before this method is called are permanently deleted. + // + // Purge operations can take up to one minute to take effect. Tasks + // might be dispatched before the purge takes effect. A purge is irreversible. + rpc PurgeQueue(PurgeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta3/{name=projects/*/locations/*/queues/*}:purge" + body: "*" + }; + } + + // Pauses the queue. + // + // If a queue is paused then the system will stop dispatching tasks + // until the queue is resumed via + // [ResumeQueue][google.cloud.tasks.v2beta3.CloudTasks.ResumeQueue]. Tasks can still be added + // when the queue is paused. A queue is paused if its + // [state][google.cloud.tasks.v2beta3.Queue.state] is [PAUSED][google.cloud.tasks.v2beta3.Queue.State.PAUSED]. + rpc PauseQueue(PauseQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta3/{name=projects/*/locations/*/queues/*}:pause" + body: "*" + }; + } + + // Resume a queue. + // + // This method resumes a queue after it has been + // [PAUSED][google.cloud.tasks.v2beta3.Queue.State.PAUSED] or + // [DISABLED][google.cloud.tasks.v2beta3.Queue.State.DISABLED]. The state of a queue is stored + // in the queue's [state][google.cloud.tasks.v2beta3.Queue.state]; after calling this method it + // will be set to [RUNNING][google.cloud.tasks.v2beta3.Queue.State.RUNNING]. + // + // WARNING: Resuming many high-QPS queues at the same time can + // lead to target overloading. If you are resuming high-QPS + // queues, follow the 500/50/5 pattern described in + // [Managing Cloud Tasks Scaling Risks](https://cloud.google.com/tasks/docs/manage-cloud-task-scaling). + rpc ResumeQueue(ResumeQueueRequest) returns (Queue) { + option (google.api.http) = { + post: "/v2beta3/{name=projects/*/locations/*/queues/*}:resume" + body: "*" + }; + } + + // Gets the access control policy for a [Queue][google.cloud.tasks.v2beta3.Queue]. + // Returns an empty policy if the resource exists and does not have a policy + // set. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.getIamPolicy` + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2beta3/{resource=projects/*/locations/*/queues/*}:getIamPolicy" + body: "*" + }; + } + + // Sets the access control policy for a [Queue][google.cloud.tasks.v2beta3.Queue]. Replaces any existing + // policy. + // + // Note: The Cloud Console does not check queue-level IAM permissions yet. + // Project-level permissions are required to use the Cloud Console. + // + // Authorization requires the following + // [Google IAM](https://cloud.google.com/iam) permission on the specified + // resource parent: + // + // * `cloudtasks.queues.setIamPolicy` + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { + option (google.api.http) = { + post: "/v2beta3/{resource=projects/*/locations/*/queues/*}:setIamPolicy" + body: "*" + }; + } + + // Returns permissions that a caller has on a [Queue][google.cloud.tasks.v2beta3.Queue]. + // If the resource does not exist, this will return an empty set of + // permissions, not a [NOT_FOUND][google.rpc.Code.NOT_FOUND] error. + // + // Note: This operation is designed to be used for building permission-aware + // UIs and command-line tools, not for authorization checking. This operation + // may "fail open" without warning. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { + option (google.api.http) = { + post: "/v2beta3/{resource=projects/*/locations/*/queues/*}:testIamPermissions" + body: "*" + }; + } + + // Lists the tasks in a queue. + // + // By default, only the [BASIC][google.cloud.tasks.v2beta3.Task.View.BASIC] view is retrieved + // due to performance considerations; + // [response_view][google.cloud.tasks.v2beta3.ListTasksRequest.response_view] controls the + // subset of information which is returned. + // + // The tasks may be returned in any order. The ordering may change at any + // time. + rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) { + option (google.api.http) = { + get: "/v2beta3/{parent=projects/*/locations/*/queues/*}/tasks" + }; + } + + // Gets a task. + rpc GetTask(GetTaskRequest) returns (Task) { + option (google.api.http) = { + get: "/v2beta3/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Creates a task and adds it to a queue. + // + // Tasks cannot be updated after creation; there is no UpdateTask command. + // + // * For [App Engine queues][google.cloud.tasks.v2beta3.AppEngineHttpQueue], the maximum task size is + // 100KB. + rpc CreateTask(CreateTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2beta3/{parent=projects/*/locations/*/queues/*}/tasks" + body: "*" + }; + } + + // Deletes a task. + // + // A task can be deleted if it is scheduled or dispatched. A task + // cannot be deleted if it has executed successfully or permanently + // failed. + rpc DeleteTask(DeleteTaskRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v2beta3/{name=projects/*/locations/*/queues/*/tasks/*}" + }; + } + + // Forces a task to run now. + // + // When this method is called, Cloud Tasks will dispatch the task, even if + // the task is already running, the queue has reached its [RateLimits][google.cloud.tasks.v2beta3.RateLimits] or + // is [PAUSED][google.cloud.tasks.v2beta3.Queue.State.PAUSED]. + // + // This command is meant to be used for manual debugging. For + // example, [RunTask][google.cloud.tasks.v2beta3.CloudTasks.RunTask] can be used to retry a failed + // task after a fix has been made or to manually force a task to be + // dispatched now. + // + // The dispatched task is returned. That is, the task that is returned + // contains the [status][Task.status] after the task is dispatched but + // before the task is received by its target. + // + // If Cloud Tasks receives a successful response from the task's + // target, then the task will be deleted; otherwise the task's + // [schedule_time][google.cloud.tasks.v2beta3.Task.schedule_time] will be reset to the time that + // [RunTask][google.cloud.tasks.v2beta3.CloudTasks.RunTask] was called plus the retry delay specified + // in the queue's [RetryConfig][google.cloud.tasks.v2beta3.RetryConfig]. + // + // [RunTask][google.cloud.tasks.v2beta3.CloudTasks.RunTask] returns + // [NOT_FOUND][google.rpc.Code.NOT_FOUND] when it is called on a + // task that has already succeeded or permanently failed. + rpc RunTask(RunTaskRequest) returns (Task) { + option (google.api.http) = { + post: "/v2beta3/{name=projects/*/locations/*/queues/*/tasks/*}:run" + body: "*" + }; + } +} + +// Request message for [ListQueues][google.cloud.tasks.v2beta3.CloudTasks.ListQueues]. +message ListQueuesRequest { + // Required. + // + // The location name. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + string parent = 1; + + // `filter` can be used to specify a subset of queues. Any [Queue][google.cloud.tasks.v2beta3.Queue] + // field can be used as a filter and several operators as supported. + // For example: `<=, <, >=, >, !=, =, :`. The filter syntax is the same as + // described in + // [Stackdriver's Advanced Logs Filters](https://cloud.google.com/logging/docs/view/advanced_filters). + // + // Sample filter "state: PAUSED". + // + // Note that using filters might cause fewer queues than the + // requested page_size to be returned. + string filter = 2; + + // Requested page size. + // + // The maximum page size is 9800. If unspecified, the page size will + // be the maximum. Fewer queues than requested might be returned, + // even if more queues exist; use the + // [next_page_token][google.cloud.tasks.v2beta3.ListQueuesResponse.next_page_token] in the + // response to determine if more queues exist. + int32 page_size = 3; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2beta3.ListQueuesResponse.next_page_token] returned + // from the previous call to [ListQueues][google.cloud.tasks.v2beta3.CloudTasks.ListQueues] + // method. It is an error to switch the value of the + // [filter][google.cloud.tasks.v2beta3.ListQueuesRequest.filter] while iterating through pages. + string page_token = 4; +} + +// Response message for [ListQueues][google.cloud.tasks.v2beta3.CloudTasks.ListQueues]. +message ListQueuesResponse { + // The list of queues. + repeated Queue queues = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListQueues][google.cloud.tasks.v2beta3.CloudTasks.ListQueues] with this value as the + // [page_token][google.cloud.tasks.v2beta3.ListQueuesRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + // + // The page token is valid for only 2 hours. + string next_page_token = 2; +} + +// Request message for [GetQueue][google.cloud.tasks.v2beta3.CloudTasks.GetQueue]. +message GetQueueRequest { + // Required. + // + // The resource name of the queue. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [CreateQueue][google.cloud.tasks.v2beta3.CloudTasks.CreateQueue]. +message CreateQueueRequest { + // Required. + // + // The location name in which the queue will be created. + // For example: `projects/PROJECT_ID/locations/LOCATION_ID` + // + // The list of allowed locations can be obtained by calling Cloud + // Tasks' implementation of + // [ListLocations][google.cloud.location.Locations.ListLocations]. + string parent = 1; + + // Required. + // + // The queue to create. + // + // [Queue's name][google.cloud.tasks.v2beta3.Queue.name] cannot be the same as an existing queue. + Queue queue = 2; +} + +// Request message for [UpdateQueue][google.cloud.tasks.v2beta3.CloudTasks.UpdateQueue]. +message UpdateQueueRequest { + // Required. + // + // The queue to create or update. + // + // The queue's [name][google.cloud.tasks.v2beta3.Queue.name] must be specified. + // + // Output only fields cannot be modified using UpdateQueue. + // Any value specified for an output only field will be ignored. + // The queue's [name][google.cloud.tasks.v2beta3.Queue.name] cannot be changed. + Queue queue = 1; + + // A mask used to specify which fields of the queue are being updated. + // + // If empty, then all fields will be updated. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for [DeleteQueue][google.cloud.tasks.v2beta3.CloudTasks.DeleteQueue]. +message DeleteQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [PurgeQueue][google.cloud.tasks.v2beta3.CloudTasks.PurgeQueue]. +message PurgeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [PauseQueue][google.cloud.tasks.v2beta3.CloudTasks.PauseQueue]. +message PauseQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for [ResumeQueue][google.cloud.tasks.v2beta3.CloudTasks.ResumeQueue]. +message ResumeQueueRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID` + string name = 1; +} + +// Request message for listing tasks using [ListTasks][google.cloud.tasks.v2beta3.CloudTasks.ListTasks]. +message ListTasksRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + string parent = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2beta3.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2beta3.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta3.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2beta3.Task] resource. + Task.View response_view = 2; + + // Requested page size. Fewer tasks than requested might be returned. + // + // The maximum page size is 1000. If unspecified, the page size will + // be the maximum. Fewer tasks than requested might be returned, + // even if more tasks exist; use + // [next_page_token][google.cloud.tasks.v2beta3.ListTasksResponse.next_page_token] in the + // response to determine if more tasks exist. + int32 page_size = 3; + + // A token identifying the page of results to return. + // + // To request the first page results, page_token must be empty. To + // request the next page of results, page_token must be the value of + // [next_page_token][google.cloud.tasks.v2beta3.ListTasksResponse.next_page_token] returned + // from the previous call to [ListTasks][google.cloud.tasks.v2beta3.CloudTasks.ListTasks] + // method. + // + // The page token is valid for only 2 hours. + string page_token = 4; +} + +// Response message for listing tasks using [ListTasks][google.cloud.tasks.v2beta3.CloudTasks.ListTasks]. +message ListTasksResponse { + // The list of tasks. + repeated Task tasks = 1; + + // A token to retrieve next page of results. + // + // To return the next page of results, call + // [ListTasks][google.cloud.tasks.v2beta3.CloudTasks.ListTasks] with this value as the + // [page_token][google.cloud.tasks.v2beta3.ListTasksRequest.page_token]. + // + // If the next_page_token is empty, there are no more results. + string next_page_token = 2; +} + +// Request message for getting a task using [GetTask][google.cloud.tasks.v2beta3.CloudTasks.GetTask]. +message GetTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2beta3.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2beta3.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta3.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2beta3.Task] resource. + Task.View response_view = 2; +} + +// Request message for [CreateTask][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. +message CreateTaskRequest { + // Required. + // + // The queue name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // The queue must already exist. + string parent = 1; + + // Required. + // + // The task to add. + // + // Task names have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID`. + // The user can optionally specify a task [name][google.cloud.tasks.v2beta3.Task.name]. If a + // name is not specified then the system will generate a random + // unique task id, which will be set in the task returned in the + // [response][google.cloud.tasks.v2beta3.Task.name]. + // + // If [schedule_time][google.cloud.tasks.v2beta3.Task.schedule_time] is not set or is in the + // past then Cloud Tasks will set it to the current time. + // + // Task De-duplication: + // + // Explicitly specifying a task ID enables task de-duplication. If + // a task's ID is identical to that of an existing task or a task + // that was deleted or executed recently then the call will fail + // with [ALREADY_EXISTS][google.rpc.Code.ALREADY_EXISTS]. + // If the task's queue was created using Cloud Tasks, then another task with + // the same name can't be created for ~1hour after the original task was + // deleted or executed. If the task's queue was created using queue.yaml or + // queue.xml, then another task with the same name can't be created + // for ~9days after the original task was deleted or executed. + // + // Because there is an extra lookup cost to identify duplicate task + // names, these [CreateTask][google.cloud.tasks.v2beta3.CloudTasks.CreateTask] calls have significantly + // increased latency. Using hashed strings for the task id or for + // the prefix of the task id is recommended. Choosing task ids that + // are sequential or have sequential prefixes, for example using a + // timestamp, causes an increase in latency and error rates in all + // task commands. The infrastructure relies on an approximately + // uniform distribution of task ids to store and serve tasks + // efficiently. + Task task = 2; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2beta3.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2beta3.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta3.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2beta3.Task] resource. + Task.View response_view = 3; +} + +// Request message for deleting a task using +// [DeleteTask][google.cloud.tasks.v2beta3.CloudTasks.DeleteTask]. +message DeleteTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; +} + +// Request message for forcing a task to run now using +// [RunTask][google.cloud.tasks.v2beta3.CloudTasks.RunTask]. +message RunTaskRequest { + // Required. + // + // The task name. For example: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + string name = 1; + + // The response_view specifies which subset of the [Task][google.cloud.tasks.v2beta3.Task] will be + // returned. + // + // By default response_view is [BASIC][google.cloud.tasks.v2beta3.Task.View.BASIC]; not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + // + // Authorization for [FULL][google.cloud.tasks.v2beta3.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Task][google.cloud.tasks.v2beta3.Task] resource. + Task.View response_view = 2; +} diff --git a/google/cloud/tasks/v2beta3/cloudtasks_gapic.yaml b/google/cloud/tasks/v2beta3/cloudtasks_gapic.yaml new file mode 100644 index 000000000..eb88c15fe --- /dev/null +++ b/google/cloud/tasks/v2beta3/cloudtasks_gapic.yaml @@ -0,0 +1,435 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.tasks.v2beta3 + python: + package_name: google.cloud.tasks_v2beta3.gapic + go: + package_name: cloud.google.com/go/cloudtasks/apiv2beta3 + csharp: + package_name: Google.Cloud.Tasks.V2Beta3 + ruby: + package_name: Google::Cloud::Tasks::V2beta3 + php: + package_name: Google\Cloud\Tasks\V2beta3 + nodejs: + package_name: tasks.v2beta3 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.tasks.v2beta3.CloudTasks + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/queues/{queue} + entity_name: queue + - name_pattern: projects/{project}/locations/{location}/queues/{queue}/tasks/{task} + entity_name: task + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListQueues + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: queues + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: GetQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: CreateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - queue + required_fields: + - parent + - queue + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 10000 + - name: UpdateQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - queue + - update_mask + required_fields: + - queue + header_request_params: + - queue.name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + queue.name: queue + timeout_millis: 10000 + - name: DeleteQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PurgeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: PauseQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: ResumeQueue + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: queue + timeout_millis: 10000 + - name: GetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + required_fields: + - resource + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: SetIamPolicy + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - policy + required_fields: + - resource + - policy + header_request_params: + - resource + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: TestIamPermissions + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - resource + - permissions + required_fields: + - resource + - permissions + header_request_params: + - resource + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + resource: queue + timeout_millis: 10000 + - name: ListTasks + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + header_request_params: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: tasks + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: GetTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: CreateTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - parent + - task + required_fields: + - parent + - task + header_request_params: + - parent + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: queue + timeout_millis: 10000 + - name: DeleteTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 + - name: RunTask + resource_name_treatment: STATIC_TYPES + flattening: + groups: + - parameters: + - name + required_fields: + - name + header_request_params: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: task + timeout_millis: 10000 +resource_name_generation: +- message_name: Queue + field_entity_map: + name: queue +- message_name: Task + field_entity_map: + name: task +- message_name: ListQueuesRequest + field_entity_map: + parent: location +- message_name: GetQueueRequest + field_entity_map: + name: queue +- message_name: CreateQueueRequest + field_entity_map: + parent: location +- message_name: UpdateQueueRequest + field_entity_map: + queue.name: queue +- message_name: DeleteQueueRequest + field_entity_map: + name: queue +- message_name: PurgeQueueRequest + field_entity_map: + name: queue +- message_name: PauseQueueRequest + field_entity_map: + name: queue +- message_name: ResumeQueueRequest + field_entity_map: + name: queue +- message_name: ListTasksRequest + field_entity_map: + parent: queue +- message_name: GetTaskRequest + field_entity_map: + name: task +- message_name: CreateTaskRequest + field_entity_map: + parent: queue +- message_name: DeleteTaskRequest + field_entity_map: + name: task +- message_name: RunTaskRequest + field_entity_map: + name: task +- message_name: google.iam.v1.GetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.SetIamPolicyRequest + field_entity_map: + resource: "*" +- message_name: google.iam.v1.TestIamPermissionsRequest + field_entity_map: + resource: "*" diff --git a/google/cloud/tasks/v2beta3/queue.proto b/google/cloud/tasks/v2beta3/queue.proto new file mode 100644 index 000000000..a1e586230 --- /dev/null +++ b/google/cloud/tasks/v2beta3/queue.proto @@ -0,0 +1,343 @@ +// Copyright 2019 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.tasks.v2beta3; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/tasks/v2beta3/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta3;tasks"; +option java_multiple_files = true; +option java_outer_classname = "QueueProto"; +option java_package = "com.google.cloud.tasks.v2beta3"; + +// A queue is a container of related tasks. Queues are configured to manage +// how those tasks are dispatched. Configurable properties include rate limits, +// retry options, queue types, and others. +message Queue { + // State of the queue. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // The queue is running. Tasks can be dispatched. + // + // If the queue was created using Cloud Tasks and the queue has + // had no activity (method calls or task dispatches) for 30 days, + // the queue may take a few minutes to re-activate. Some method + // calls may return [NOT_FOUND][google.rpc.Code.NOT_FOUND] and + // tasks may not be dispatched for a few minutes until the queue + // has been re-activated. + RUNNING = 1; + + // Tasks are paused by the user. If the queue is paused then Cloud + // Tasks will stop delivering tasks from it, but more tasks can + // still be added to it by the user. + PAUSED = 2; + + // The queue is disabled. + // + // A queue becomes `DISABLED` when + // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref) + // or + // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref) + // is uploaded which does not contain the queue. You cannot directly disable + // a queue. + // + // When a queue is disabled, tasks can still be added to a queue + // but the tasks are not dispatched. + // + // To permanently delete this queue and all of its tasks, call + // [DeleteQueue][google.cloud.tasks.v2beta3.CloudTasks.DeleteQueue]. + DISABLED = 3; + } + + // Caller-specified and required in [CreateQueue][google.cloud.tasks.v2beta3.CloudTasks.CreateQueue], + // after which it becomes output only. + // + // The queue name. + // + // The queue name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the queue's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + string name = 1; + + oneof queue_type { + // [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] settings apply only to + // [App Engine tasks][google.cloud.tasks.v2beta3.AppEngineHttpRequest] in this queue. + // [Http tasks][google.cloud.tasks.v2beta3.HttpRequest] are not affected by this proto. + AppEngineHttpQueue app_engine_http_queue = 3; + } + + // Rate limits for task dispatches. + // + // [rate_limits][google.cloud.tasks.v2beta3.Queue.rate_limits] and [retry_config][google.cloud.tasks.v2beta3.Queue.retry_config] are + // related because they both control task attempts. However they control task + // attempts in different ways: + // + // * [rate_limits][google.cloud.tasks.v2beta3.Queue.rate_limits] controls the total rate of + // dispatches from a queue (i.e. all traffic dispatched from the + // queue, regardless of whether the dispatch is from a first + // attempt or a retry). + // * [retry_config][google.cloud.tasks.v2beta3.Queue.retry_config] controls what happens to + // particular a task after its first attempt fails. That is, + // [retry_config][google.cloud.tasks.v2beta3.Queue.retry_config] controls task retries (the + // second attempt, third attempt, etc). + // + // The queue's actual dispatch rate is the result of: + // + // * Number of tasks in the queue + // * User-specified throttling: [rate_limits][google.cloud.tasks.v2beta3.Queue.rate_limits], + // [retry_config][google.cloud.tasks.v2beta3.Queue.retry_config], and the + // [queue's state][google.cloud.tasks.v2beta3.Queue.state]. + // * System throttling due to `429` (Too Many Requests) or `503` (Service + // Unavailable) responses from the worker, high error rates, or to smooth + // sudden large traffic spikes. + RateLimits rate_limits = 4; + + // Settings that determine the retry behavior. + // + // * For tasks created using Cloud Tasks: the queue-level retry settings + // apply to all tasks in the queue that were created using Cloud Tasks. + // Retry settings cannot be set on individual tasks. + // * For tasks created using the App Engine SDK: the queue-level retry + // settings apply to all tasks in the queue which do not have retry settings + // explicitly set on the task and were created by the App Engine SDK. See + // [App Engine + // documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks). + RetryConfig retry_config = 5; + + // Output only. The state of the queue. + // + // `state` can only be changed by called + // [PauseQueue][google.cloud.tasks.v2beta3.CloudTasks.PauseQueue], + // [ResumeQueue][google.cloud.tasks.v2beta3.CloudTasks.ResumeQueue], or uploading + // [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref). + // [UpdateQueue][google.cloud.tasks.v2beta3.CloudTasks.UpdateQueue] cannot be used to change `state`. + State state = 6; + + // Output only. The last time this queue was purged. + // + // All tasks that were [created][google.cloud.tasks.v2beta3.Task.create_time] before this time + // were purged. + // + // A queue can be purged using [PurgeQueue][google.cloud.tasks.v2beta3.CloudTasks.PurgeQueue], the + // [App Engine Task Queue SDK, or the Cloud + // Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue). + // + // Purge time will be truncated to the nearest microsecond. Purge + // time will be unset if the queue has never been purged. + google.protobuf.Timestamp purge_time = 7; + + // Specifies the fraction of operations to write to + // [Stackdriver Logging](https://cloud.google.com/logging/docs/). + // This field may contain any value between 0.0 and 1.0, inclusive. + // 0.0 is the default and means that no operations are logged. + double log_sampling_ratio = 10; +} + +// Rate limits. +// +// This message determines the maximum rate that tasks can be dispatched by a +// queue, regardless of whether the dispatch is a first task attempt or a retry. +// +// Note: The debugging command, [RunTask][google.cloud.tasks.v2beta3.CloudTasks.RunTask], will run a task +// even if the queue has reached its [RateLimits][google.cloud.tasks.v2beta3.RateLimits]. +message RateLimits { + // The maximum rate at which tasks are dispatched from this queue. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // * For [App Engine queues][google.cloud.tasks.v2beta3.AppEngineHttpQueue], the maximum allowed value + // is 500. + // + // + // This field has the same meaning as + // [rate in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate). + double max_dispatches_per_second = 1; + + // Output only. The max burst size. + // + // Max burst size limits how fast tasks in queue are processed when + // many tasks are in the queue and the rate is high. This field + // allows the queue to have a high rate so processing starts shortly + // after a task is enqueued, but still limits resource usage when + // many tasks are enqueued in a short period of time. + // + // The [token bucket](https://wikipedia.org/wiki/Token_Bucket) + // algorithm is used to control the rate of task dispatches. Each + // queue has a token bucket that holds tokens, up to the maximum + // specified by `max_burst_size`. Each time a task is dispatched, a + // token is removed from the bucket. Tasks will be dispatched until + // the queue's bucket runs out of tokens. The bucket will be + // continuously refilled with new tokens based on + // [max_dispatches_per_second][google.cloud.tasks.v2beta3.RateLimits.max_dispatches_per_second]. + // + // Cloud Tasks will pick the value of `max_burst_size` based on the + // value of + // [max_dispatches_per_second][google.cloud.tasks.v2beta3.RateLimits.max_dispatches_per_second]. + // + // For App Engine queues that were created or updated using + // `queue.yaml/xml`, `max_burst_size` is equal to + // [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size). + // Since `max_burst_size` is output only, if + // [UpdateQueue][google.cloud.tasks.v2beta3.CloudTasks.UpdateQueue] is called on a queue + // created by `queue.yaml/xml`, `max_burst_size` will be reset based + // on the value of + // [max_dispatches_per_second][google.cloud.tasks.v2beta3.RateLimits.max_dispatches_per_second], + // regardless of whether + // [max_dispatches_per_second][google.cloud.tasks.v2beta3.RateLimits.max_dispatches_per_second] + // is updated. + // + int32 max_burst_size = 2; + + // The maximum number of concurrent tasks that Cloud Tasks allows + // to be dispatched for this queue. After this threshold has been + // reached, Cloud Tasks stops dispatching tasks until the number of + // concurrent requests decreases. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // The maximum allowed value is 5,000. + // + // + // This field has the same meaning as + // [max_concurrent_requests in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests). + int32 max_concurrent_dispatches = 3; +} + +// Retry config. +// +// These settings determine when a failed task attempt is retried. +message RetryConfig { + // Number of attempts per task. + // + // Cloud Tasks will attempt the task `max_attempts` times (that is, if the + // first attempt fails, then there will be `max_attempts - 1` retries). Must + // be >= -1. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // -1 indicates unlimited attempts. + // + // This field has the same meaning as + // [task_retry_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + int32 max_attempts = 1; + + // If positive, `max_retry_duration` specifies the time limit for + // retrying a failed task, measured from when the task was first + // attempted. Once `max_retry_duration` time has passed *and* the + // task has been attempted [max_attempts][google.cloud.tasks.v2beta3.RetryConfig.max_attempts] + // times, no further attempts will be made and the task will be + // deleted. + // + // If zero, then the task age is unlimited. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `max_retry_duration` will be truncated to the nearest second. + // + // This field has the same meaning as + // [task_age_limit in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_retry_duration = 2; + + // A task will be [scheduled][google.cloud.tasks.v2beta3.Task.schedule_time] for retry between + // [min_backoff][google.cloud.tasks.v2beta3.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2beta3.RetryConfig.max_backoff] duration after it fails, + // if the queue's [RetryConfig][google.cloud.tasks.v2beta3.RetryConfig] specifies that the task should be + // retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `min_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [min_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration min_backoff = 3; + + // A task will be [scheduled][google.cloud.tasks.v2beta3.Task.schedule_time] for retry between + // [min_backoff][google.cloud.tasks.v2beta3.RetryConfig.min_backoff] and + // [max_backoff][google.cloud.tasks.v2beta3.RetryConfig.max_backoff] duration after it fails, + // if the queue's [RetryConfig][google.cloud.tasks.v2beta3.RetryConfig] specifies that the task should be + // retried. + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // `max_backoff` will be truncated to the nearest second. + // + // This field has the same meaning as + // [max_backoff_seconds in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + google.protobuf.Duration max_backoff = 4; + + // The time between retries will double `max_doublings` times. + // + // A task's retry interval starts at + // [min_backoff][google.cloud.tasks.v2beta3.RetryConfig.min_backoff], then doubles + // `max_doublings` times, then increases linearly, and finally + // retries retries at intervals of + // [max_backoff][google.cloud.tasks.v2beta3.RetryConfig.max_backoff] up to + // [max_attempts][google.cloud.tasks.v2beta3.RetryConfig.max_attempts] times. + // + // For example, if [min_backoff][google.cloud.tasks.v2beta3.RetryConfig.min_backoff] is 10s, + // [max_backoff][google.cloud.tasks.v2beta3.RetryConfig.max_backoff] is 300s, and + // `max_doublings` is 3, then the a task will first be retried in + // 10s. The retry interval will double three times, and then + // increase linearly by 2^3 * 10s. Finally, the task will retry at + // intervals of [max_backoff][google.cloud.tasks.v2beta3.RetryConfig.max_backoff] until the + // task has been attempted [max_attempts][google.cloud.tasks.v2beta3.RetryConfig.max_attempts] + // times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, + // 240s, 300s, 300s, .... + // + // If unspecified when the queue is created, Cloud Tasks will pick the + // default. + // + // + // This field has the same meaning as + // [max_doublings in + // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). + int32 max_doublings = 5; +} diff --git a/google/cloud/tasks/v2beta3/target.proto b/google/cloud/tasks/v2beta3/target.proto new file mode 100644 index 000000000..b1a8d4056 --- /dev/null +++ b/google/cloud/tasks/v2beta3/target.proto @@ -0,0 +1,441 @@ +// Copyright 2019 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.tasks.v2beta3; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta3;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TargetProto"; +option java_package = "com.google.cloud.tasks.v2beta3"; + +// HTTP request. +// +// Warning: This is an [alpha](https://cloud.google.com/terms/launch-stages) +// feature. If you haven't already joined, you can [use this form to sign +// up](https://docs.google.com/forms/d/e/1FAIpQLSfc4uEy9CBHKYUSdnY1hdhKDCX7julVZHy3imOiR-XrU7bUNQ/viewform). +// +// The task will be pushed to the worker as an HTTP request. If the worker +// or the redirected worker acknowledges the task by returning a successful HTTP +// response code ([`200` - `299`]), the task will removed from the queue. If +// any other HTTP response code is returned or no response is received, the +// task will be retried according to the following: +// +// * User-specified throttling: [retry configuration][Queue.RetryConfig], +// [rate limits][Queue.RateLimits], and the [queue's state][google.cloud.tasks.v2beta3.Queue.state]. +// +// * System throttling: To prevent the worker from overloading, Cloud Tasks may +// temporarily reduce the queue's effective rate. User-specified settings +// will not be changed. +// +// System throttling happens because: +// +// * Cloud Tasks backoffs on all errors. Normally the backoff specified in +// [rate limits][Queue.RateLimits] will be used. But if the worker returns +// `429` (Too Many Requests), `503` (Service Unavailable), or the rate of +// errors is high, Cloud Tasks will use a higher backoff rate. The retry +// specified in the `Retry-After` HTTP response header is considered. +// +// * To prevent traffic spikes and to smooth sudden large traffic spikes, +// dispatches ramp up slowly when the queue is newly created or idle and +// if large numbers of tasks suddenly become available to dispatch (due to +// spikes in create task rates, the queue being unpaused, or many tasks +// that are scheduled at the same time). +message HttpRequest { + // Required. The full url path that the request will be sent to. + // + // This string must begin with either "http://" or "https://". Some examples + // are: `http://acme.com` and `https://acme.com/sales:8080`. Cloud Tasks will + // encode some characters for safety and compatibility. The maximum allowed + // URL length is 2083 characters after encoding. + // + // The `Location` header response from a redirect response [`300` - `399`] + // may be followed. The redirect is not counted as a separate attempt. + string url = 1; + + // The HTTP method to use for the request. The default is POST. + HttpMethod http_method = 2; + + // HTTP request headers. + // + // This map contains the header field names and values. + // Headers can be set when the + // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. + // + // These headers represent a subset of the headers that will accompany the + // task's HTTP request. Some HTTP request headers will be ignored or replaced. + // + // A partial list of headers that will be ignored or replaced is: + // + // * Host: This will be computed by Cloud Tasks and derived from + // [HttpRequest.url][google.cloud.tasks.v2beta3.HttpRequest.url]. + // * Content-Length: This will be computed by Cloud Tasks. + // * User-Agent: This will be set to `"Google-Cloud-Tasks"`. + // * X-Google-*: Google use only. + // * X-AppEngine-*: Google use only. + // + // `Content-Type` won't be set by Cloud Tasks. You can explicitly set + // `Content-Type` to a media type when the + // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. + // For example, `Content-Type` can be set to `"application/octet-stream"` or + // `"application/json"`. + // + // Headers which can have multiple values (according to RFC2616) can be + // specified using comma-separated values. + // + // The size of the headers must be less than 80KB. + map<string, string> headers = 3; + + // HTTP request body. + // + // A request body is allowed only if the + // [HTTP method][google.cloud.tasks.v2beta3.HttpRequest.http_method] is POST, PUT, or PATCH. It is an + // error to set body on a task with an incompatible [HttpMethod][google.cloud.tasks.v2beta3.HttpMethod]. + bytes body = 4; + + // The mode for generating an `Authorization` header for HTTP requests. + // + // If specified, all `Authorization` headers in the [HttpTarget.headers][] + // field will be overridden. + oneof authorization_header { + // If specified, an + // [OAuth token](https://developers.google.com/identity/protocols/OAuth2) + // will be generated and attached as an `Authorization` header in the HTTP + // request. + // + // This type of authorization should be used when sending requests to a GCP + // endpoint. + OAuthToken oauth_token = 5; + + // If specified, an + // [OIDC](https://developers.google.com/identity/protocols/OpenIDConnect) + // token will be generated and attached as an `Authorization` header in the + // HTTP request. + // + // This type of authorization should be used when sending requests to third + // party endpoints. + OidcToken oidc_token = 6; + } +} + +// App Engine HTTP queue. +// +// The task will be delivered to the App Engine application hostname +// specified by its [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] and [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest]. +// The documentation for [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest] explains how the +// task's host URL is constructed. +// +// Using [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] requires +// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) +// Google IAM permission for the project +// and the following scope: +// +// `https://www.googleapis.com/auth/cloud-platform` +message AppEngineHttpQueue { + // Overrides for the + // [task-level app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. + // + // If set, `app_engine_routing_override` is used for all tasks in + // the queue, no matter what the setting is for the + // [task-level app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing_override = 1; +} + +// App Engine HTTP request. +// +// The message defines the HTTP request that is sent to an App Engine app when +// the task is dispatched. +// +// This proto can only be used for tasks in a queue which has +// [app_engine_http_queue][google.cloud.tasks.v2beta3.Queue.app_engine_http_queue] set. +// +// Using [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest] requires +// [`appengine.applications.get`](https://cloud.google.com/appengine/docs/admin-api/access-control) +// Google IAM permission for the project +// and the following scope: +// +// `https://www.googleapis.com/auth/cloud-platform` +// +// The task will be delivered to the App Engine app which belongs to the same +// project as the queue. For more information, see +// [How Requests are +// Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) +// and how routing is affected by +// [dispatch +// files](https://cloud.google.com/appengine/docs/python/config/dispatchref). +// Traffic is encrypted during transport and never leaves Google datacenters. +// Because this traffic is carried over a communication mechanism internal to +// Google, you cannot explicitly set the protocol (for example, HTTP or HTTPS). +// The request to the handler, however, will appear to have used the HTTP +// protocol. +// +// The [AppEngineRouting][google.cloud.tasks.v2beta3.AppEngineRouting] used to construct the URL that the task is +// delivered to can be set at the queue-level or task-level: +// +// * If set, +// [app_engine_routing_override][google.cloud.tasks.v2beta3.AppEngineHttpQueue.app_engine_routing_override] +// is used for all tasks in the queue, no matter what the setting +// is for the +// [task-level app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. +// +// +// The `url` that the task will be sent to is: +// +// * `url =` [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] `+` +// [relative_uri][google.cloud.tasks.v2beta3.AppEngineHttpRequest.relative_uri] +// +// Tasks can be dispatched to secure app handlers, unsecure app handlers, and +// URIs restricted with +// [`login: +// admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref). +// Because tasks are not run as any user, they cannot be dispatched to URIs +// restricted with +// [`login: +// required`](https://cloud.google.com/appengine/docs/standard/python/config/appref) +// Task dispatches also do not follow redirects. +// +// The task attempt has succeeded if the app's request handler returns +// an HTTP response code in the range [`200` - `299`]. `503` is +// considered an App Engine system error instead of an application +// error. Requests returning error `503` will be retried regardless of +// retry configuration and not counted against retry counts. +// Any other response code or a failure to receive a response before the +// deadline is a failed attempt. +message AppEngineHttpRequest { + // The HTTP method to use for the request. The default is POST. + // + // The app's request handler for the task's target URL must be able to handle + // HTTP requests with this http_method, otherwise the task attempt will fail + // with error code 405 (Method Not Allowed). See + // [Writing a push task request + // handler](https://cloud.google.com/appengine/docs/java/taskqueue/push/creating-handlers#writing_a_push_task_request_handler) + // and the documentation for the request handlers in the language your app is + // written in e.g. + // [Python Request + // Handler](https://cloud.google.com/appengine/docs/python/tools/webapp/requesthandlerclass). + HttpMethod http_method = 1; + + // Task-level setting for App Engine routing. + // + // If set, + // [app_engine_routing_override][google.cloud.tasks.v2beta3.AppEngineHttpQueue.app_engine_routing_override] + // is used for all tasks in the queue, no matter what the setting is for the + // [task-level app_engine_routing][google.cloud.tasks.v2beta3.AppEngineHttpRequest.app_engine_routing]. + AppEngineRouting app_engine_routing = 2; + + // The relative URI. + // + // The relative URI must begin with "/" and must be a valid HTTP relative URI. + // It can contain a path and query string arguments. + // If the relative URI is empty, then the root path "/" will be used. + // No spaces are allowed, and the maximum length allowed is 2083 characters. + string relative_uri = 3; + + // HTTP request headers. + // + // This map contains the header field names and values. + // Headers can be set when the + // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. + // Repeated headers are not supported but a header value can contain commas. + // + // Cloud Tasks sets some headers to default values: + // + // * `User-Agent`: By default, this header is + // `"AppEngine-Google; (+http://code.google.com/appengine)"`. + // This header can be modified, but Cloud Tasks will append + // `"AppEngine-Google; (+http://code.google.com/appengine)"` to the + // modified `User-Agent`. + // + // If the task has a [body][google.cloud.tasks.v2beta3.AppEngineHttpRequest.body], Cloud + // Tasks sets the following headers: + // + // * `Content-Type`: By default, the `Content-Type` header is set to + // `"application/octet-stream"`. The default can be overridden by explicitly + // setting `Content-Type` to a particular media type when the + // [task is created][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. + // For example, `Content-Type` can be set to `"application/json"`. + // * `Content-Length`: This is computed by Cloud Tasks. This value is + // output only. It cannot be changed. + // + // The headers below cannot be set or overridden: + // + // * `Host` + // * `X-Google-*` + // * `X-AppEngine-*` + // + // In addition, Cloud Tasks sets some headers when the task is dispatched, + // such as headers containing information about the task; see + // [request + // headers](https://cloud.google.com/appengine/docs/python/taskqueue/push/creating-handlers#reading_request_headers). + // These headers are set only when the task is dispatched, so they are not + // visible when the task is returned in a Cloud Tasks response. + // + // Although there is no specific limit for the maximum number of headers or + // the size, there is a limit on the maximum size of the [Task][google.cloud.tasks.v2beta3.Task]. For more + // information, see the [CreateTask][google.cloud.tasks.v2beta3.CloudTasks.CreateTask] documentation. + map<string, string> headers = 4; + + // HTTP request body. + // + // A request body is allowed only if the HTTP method is POST or PUT. It is + // an error to set a body on a task with an incompatible [HttpMethod][google.cloud.tasks.v2beta3.HttpMethod]. + bytes body = 5; +} + +// App Engine Routing. +// +// Defines routing characteristics specific to App Engine - service, version, +// and instance. +// +// For more information about services, versions, and instances see +// [An Overview of App +// Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine), +// [Microservices Architecture on Google App +// Engine](https://cloud.google.com/appengine/docs/python/microservices-on-app-engine), +// [App Engine Standard request +// routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed), +// and [App Engine Flex request +// routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). +message AppEngineRouting { + // App service. + // + // By default, the task is sent to the service which is the default + // service when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable + // into [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. For example, some tasks + // which were created using the App Engine SDK use a custom domain + // name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable, then + // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance] are the empty string. + string service = 1; + + // App version. + // + // By default, the task is sent to the version which is the default + // version when the task is attempted. + // + // For some queues or tasks which were created using the App Engine + // Task Queue API, [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable + // into [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. For example, some tasks + // which were created using the App Engine SDK use a custom domain + // name; custom domains are not parsed by Cloud Tasks. If + // [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] is not parsable, then + // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], + // [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], and + // [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance] are the empty string. + string version = 2; + + // App instance. + // + // By default, the task is sent to an instance which is available when + // the task is attempted. + // + // Requests can only be sent to a specific instance if + // [manual scaling is used in App Engine + // Standard](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine?hl=en_US#scaling_types_and_instance_classes). + // App Engine Flex does not support instances. For more information, see + // [App Engine Standard request + // routing](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed) + // and [App Engine Flex request + // routing](https://cloud.google.com/appengine/docs/flexible/python/how-requests-are-routed). + string instance = 3; + + // Output only. The host that the task is sent to. + // + // The host is constructed from the domain name of the app associated with + // the queue's project ID (for example <app-id>.appspot.com), and the + // [service][google.cloud.tasks.v2beta3.AppEngineRouting.service], [version][google.cloud.tasks.v2beta3.AppEngineRouting.version], + // and [instance][google.cloud.tasks.v2beta3.AppEngineRouting.instance]. Tasks which were created using + // the App Engine SDK might have a custom domain name. + // + // For more information, see + // [How Requests are + // Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed). + string host = 4; +} + +// The HTTP method used to execute the task. +enum HttpMethod { + // HTTP method unspecified + HTTP_METHOD_UNSPECIFIED = 0; + + // HTTP POST + POST = 1; + + // HTTP GET + GET = 2; + + // HTTP HEAD + HEAD = 3; + + // HTTP PUT + PUT = 4; + + // HTTP DELETE + DELETE = 5; + + // HTTP PATCH + PATCH = 6; + + // HTTP OPTIONS + OPTIONS = 7; +} + +// Contains information needed for generating an +// [OAuth token](https://developers.google.com/identity/protocols/OAuth2). +// This type of authorization should be used when sending requests to a GCP +// endpoint. +message OAuthToken { + // [Service account email](https://cloud.google.com/iam/docs/service-accounts) + // to be used for generating OAuth token. + // The service account must be within the same project as the queue. The + // caller must have iam.serviceAccounts.actAs permission for the service + // account. + string service_account_email = 1; + + // OAuth scope to be used for generating OAuth access token. + // If not specified, "https://www.googleapis.com/auth/cloud-platform" + // will be used. + string scope = 2; +} + +// Contains information needed for generating an +// [OpenID Connect +// token](https://developers.google.com/identity/protocols/OpenIDConnect). This +// type of authorization should be used when sending requests to third party +// endpoints. +message OidcToken { + // [Service account email](https://cloud.google.com/iam/docs/service-accounts) + // to be used for generating OIDC token. + // The service account must be within the same project as the queue. The + // caller must have iam.serviceAccounts.actAs permission for the service + // account. + string service_account_email = 1; + + // Audience to be used when generating OIDC token. If not specified, the URI + // specified in target will be used. + string audience = 2; +} diff --git a/google/cloud/tasks/v2beta3/task.proto b/google/cloud/tasks/v2beta3/task.proto new file mode 100644 index 000000000..6d1d9c28b --- /dev/null +++ b/google/cloud/tasks/v2beta3/task.proto @@ -0,0 +1,192 @@ +// Copyright 2019 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.tasks.v2beta3; + +import "google/api/annotations.proto"; +import "google/api/resource.proto"; +import "google/cloud/tasks/v2beta3/target.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/tasks/v2beta3;tasks"; +option java_multiple_files = true; +option java_outer_classname = "TaskProto"; +option java_package = "com.google.cloud.tasks.v2beta3"; + +// A unit of scheduled work. +message Task { + // The view specifies a subset of [Task][google.cloud.tasks.v2beta3.Task] data. + // + // When a task is returned in a response, not all + // information is retrieved by default because some data, such as + // payloads, might be desirable to return only when needed because + // of its large size or because of the sensitivity of data that it + // contains. + enum View { + // Unspecified. Defaults to BASIC. + VIEW_UNSPECIFIED = 0; + + // The basic view omits fields which can be large or can contain + // sensitive data. + // + // This view does not include the + // [body in AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest.body]. + // Bodies are desirable to return only when needed, because they + // can be large and because of the sensitivity of the data that you + // choose to store in it. + BASIC = 1; + + // All information is returned. + // + // Authorization for [FULL][google.cloud.tasks.v2beta3.Task.View.FULL] requires + // `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) + // permission on the [Queue][google.cloud.tasks.v2beta3.Queue] resource. + FULL = 2; + } + + // Optionally caller-specified in [CreateTask][google.cloud.tasks.v2beta3.CloudTasks.CreateTask]. + // + // The task name. + // + // The task name must have the following format: + // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID` + // + // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), colons (:), or periods (.). + // For more information, see + // [Identifying + // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + // * `LOCATION_ID` is the canonical ID for the task's location. + // The list of available locations can be obtained by calling + // [ListLocations][google.cloud.location.Locations.ListLocations]. + // For more information, see https://cloud.google.com/about/locations/. + // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or + // hyphens (-). The maximum length is 100 characters. + // * `TASK_ID` can contain only letters ([A-Za-z]), numbers ([0-9]), + // hyphens (-), or underscores (_). The maximum length is 500 characters. + string name = 1; + + // Required. The message to send to the worker. + oneof payload_type { + // HTTP request that is sent to the App Engine app handler. + // + // An App Engine task is a task that has [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest] set. + AppEngineHttpRequest app_engine_http_request = 3; + + // HTTP request that is sent to the task's target. + // + // Warning: This is an [alpha](https://cloud.google.com/terms/launch-stages) + // feature. If you haven't already joined, you can [use this form to sign + // up](https://docs.google.com/forms/d/e/1FAIpQLSfc4uEy9CBHKYUSdnY1hdhKDCX7julVZHy3imOiR-XrU7bUNQ/viewform). + // + // An HTTP task is a task that has [HttpRequest][google.cloud.tasks.v2beta3.HttpRequest] set. + HttpRequest http_request = 11; + } + + // The time when the task is scheduled to be attempted. + // + // For App Engine queues, this is when the task will be attempted or retried. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 4; + + // Output only. The time that the task was created. + // + // `create_time` will be truncated to the nearest second. + google.protobuf.Timestamp create_time = 5; + + // The deadline for requests sent to the worker. If the worker does not + // respond by this deadline then the request is cancelled and the attempt + // is marked as a `DEADLINE_EXCEEDED` failure. Cloud Tasks will retry the + // task according to the [RetryConfig][google.cloud.tasks.v2beta3.RetryConfig]. + // + // Note that when the request is cancelled, Cloud Tasks will stop listing for + // the response, but whether the worker stops processing depends on the + // worker. For example, if the worker is stuck, it may not react to cancelled + // requests. + // + // The default and maximum values depend on the type of request: + // + // * For [HTTP tasks][google.cloud.tasks.v2beta3.HttpRequest], the default is 10 minutes. The deadline + // must be in the interval [15 seconds, 30 minutes]. + // + // * For [App Engine tasks][google.cloud.tasks.v2beta3.AppEngineHttpRequest], 0 indicates that the + // request has the default deadline. The default deadline depends on the + // [scaling + // type](https://cloud.google.com/appengine/docs/standard/go/how-instances-are-managed#instance_scaling) + // of the service: 10 minutes for standard apps with automatic scaling, 24 + // hours for standard apps with manual and basic scaling, and 60 minutes for + // flex apps. If the request deadline is set, it must be in the interval [15 + // seconds, 24 hours 15 seconds]. Regardless of the task's + // `dispatch_deadline`, the app handler will not run for longer than than + // the service's timeout. We recommend setting the `dispatch_deadline` to + // at most a few seconds more than the app handler's timeout. For more + // information see + // [Timeouts](https://cloud.google.com/tasks/docs/creating-appengine-handlers#timeouts). + // + // `dispatch_deadline` will be truncated to the nearest millisecond. The + // deadline is an approximate deadline. + google.protobuf.Duration dispatch_deadline = 12; + + // Output only. The number of attempts dispatched. + // + // This count includes attempts which have been dispatched but haven't + // received a response. + int32 dispatch_count = 6; + + // Output only. The number of attempts which have received a response. + int32 response_count = 7; + + // Output only. The status of the task's first attempt. + // + // Only [dispatch_time][google.cloud.tasks.v2beta3.Attempt.dispatch_time] will be set. + // The other [Attempt][google.cloud.tasks.v2beta3.Attempt] information is not retained by Cloud Tasks. + Attempt first_attempt = 8; + + // Output only. The status of the task's last attempt. + Attempt last_attempt = 9; + + // Output only. The view specifies which subset of the [Task][google.cloud.tasks.v2beta3.Task] has + // been returned. + View view = 10; +} + +// The status of a task attempt. +message Attempt { + // Output only. The time that this attempt was scheduled. + // + // `schedule_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp schedule_time = 1; + + // Output only. The time that this attempt was dispatched. + // + // `dispatch_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp dispatch_time = 2; + + // Output only. The time that this attempt response was received. + // + // `response_time` will be truncated to the nearest microsecond. + google.protobuf.Timestamp response_time = 3; + + // Output only. The response from the worker for this attempt. + // + // If `response_time` is unset, then the task has not been attempted or is + // currently running and the `response_status` field is meaningless. + google.rpc.Status response_status = 4; +} diff --git a/google/cloud/texttospeech/BUILD.bazel b/google/cloud/texttospeech/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/texttospeech/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/texttospeech/artman_texttospeech.yaml b/google/cloud/texttospeech/artman_texttospeech.yaml new file mode 100644 index 000000000..83b8d2fd2 --- /dev/null +++ b/google/cloud/texttospeech/artman_texttospeech.yaml @@ -0,0 +1,34 @@ +common: + api_name: texttospeech + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: tts.yaml + gapic_yaml: v1beta1/texttospeech_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/texttospeech/artman_texttospeech_v1.yaml b/google/cloud/texttospeech/artman_texttospeech_v1.yaml new file mode 100644 index 000000000..b5f3d6d28 --- /dev/null +++ b/google/cloud/texttospeech/artman_texttospeech_v1.yaml @@ -0,0 +1,34 @@ +common: + api_name: texttospeech + api_version: v1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1 + service_yaml: tts_v1.yaml + gapic_yaml: v1/texttospeech_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/texttospeech/artman_texttospeech_v1beta1.yaml b/google/cloud/texttospeech/artman_texttospeech_v1beta1.yaml new file mode 100644 index 000000000..91280d64e --- /dev/null +++ b/google/cloud/texttospeech/artman_texttospeech_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: texttospeech + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: tts_v1beta1.yaml + gapic_yaml: v1beta1/texttospeech_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/texttospeech/tts.yaml b/google/cloud/texttospeech/tts.yaml new file mode 100644 index 000000000..77251f5d2 --- /dev/null +++ b/google/cloud/texttospeech/tts.yaml @@ -0,0 +1,21 @@ +type: google.api.Service +config_version: 3 +name: texttospeech.googleapis.com +title: Cloud Text-to-Speech API + +apis: +- name: google.cloud.texttospeech.v1beta1.TextToSpeech + +documentation: + summary: 'Cloud Text-to-Speech API.' + overview: |- + # Introduction + + Google Cloud Text-to-Speech API provides speech synthesis as a service. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/texttospeech/tts_v1.yaml b/google/cloud/texttospeech/tts_v1.yaml new file mode 100644 index 000000000..b025a16ce --- /dev/null +++ b/google/cloud/texttospeech/tts_v1.yaml @@ -0,0 +1,23 @@ +type: google.api.Service +config_version: 3 +name: texttospeech.googleapis.com +title: Cloud Text-to-Speech API + +apis: +- name: google.cloud.texttospeech.v1.TextToSpeech + +documentation: + summary: |- + Synthesizes natural-sounding speech by applying powerful neural network + models. + overview: |- + # Introduction + + Google Cloud Text-to-Speech API provides speech synthesis as a service. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/texttospeech/tts_v1beta1.yaml b/google/cloud/texttospeech/tts_v1beta1.yaml new file mode 100644 index 000000000..fbff3e849 --- /dev/null +++ b/google/cloud/texttospeech/tts_v1beta1.yaml @@ -0,0 +1,23 @@ +type: google.api.Service +config_version: 3 +name: texttospeech.googleapis.com +title: Cloud Text-to-Speech API + +apis: +- name: google.cloud.texttospeech.v1beta1.TextToSpeech + +documentation: + summary: |- + Synthesizes natural-sounding speech by applying powerful neural network + models. + overview: |- + # Introduction + + Google Cloud Text-to-Speech API provides speech synthesis as a service. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/texttospeech/v1/BUILD.bazel b/google/cloud/texttospeech/v1/BUILD.bazel new file mode 100644 index 000000000..4ba066821 --- /dev/null +++ b/google/cloud/texttospeech/v1/BUILD.bazel @@ -0,0 +1,119 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "texttospeech_proto", + srcs = [ + "cloud_tts.proto", + ], + deps = [ + "//google/api:annotations_proto", + ], +) + +proto_library_with_info( + name = "texttospeech_proto_with_info", + deps = [":texttospeech_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", "java_gapic_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "texttospeech_java_proto", + deps = [":texttospeech_proto"], +) + +java_grpc_library( + name = "texttospeech_java_grpc", + srcs = [":texttospeech_proto"], + deps = [":texttospeech_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_gapic_library( + name = "texttospeech_java_gapic", + src = ":texttospeech_proto_with_info", + gapic_yaml = "texttospeech_gapic.yaml", + service_yaml = "//google/cloud/texttospeech:tts_v1.yaml", + test_deps = [":texttospeech_java_grpc"], + deps = [":texttospeech_java_proto"] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":texttospeech_java_gapic_test"], +) for test_name in [ + "com.google.cloud.texttospeech.v1.TextToSpeechClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-texttospeech-v1-java", + client_deps = [":texttospeech_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":texttospeech_java_gapic_test"], + grpc_deps = [":texttospeech_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":texttospeech_java_proto", + ":texttospeech_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "texttospeech_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/texttospeech/v1", + protos = [":texttospeech_proto_with_info"], + deps = ["//google/api:annotations_go_proto"], +) + +go_gapic_library( + name = "texttospeech_go_gapic", + src = ":texttospeech_proto_with_info", + gapic_yaml = "texttospeech_gapic.yaml", + importpath = "cloud.google.com/go/texttospeech/apiv1", + service_yaml = "//google/cloud/texttospeech:tts_v1.yaml", + deps = [":texttospeech_go_proto"], +) + +go_test( + name = "texttospeech_go_gapic_test", + srcs = [":texttospeech_go_gapic_srcjar_test"], + embed = [":texttospeech_go_gapic"], + importpath = "cloud.google.com/go/texttospeech/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-texttospeech-v1-go", + deps = [ + ":texttospeech_go_gapic", + ":texttospeech_go_gapic_srcjar-smoke-test.srcjar", + ":texttospeech_go_gapic_srcjar-test.srcjar", + ":texttospeech_go_proto", + ], +) diff --git a/google/cloud/texttospeech/v1/cloud_tts.proto b/google/cloud/texttospeech/v1/cloud_tts.proto new file mode 100644 index 000000000..dd9fa6ce2 --- /dev/null +++ b/google/cloud/texttospeech/v1/cloud_tts.proto @@ -0,0 +1,235 @@ +// Copyright 2018 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.texttospeech.v1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.TextToSpeech.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/texttospeech/v1;texttospeech"; +option java_multiple_files = true; +option java_outer_classname = "TextToSpeechProto"; +option java_package = "com.google.cloud.texttospeech.v1"; +option php_namespace = "Google\\Cloud\\TextToSpeech\\V1"; + +// Service that implements Google Cloud Text-to-Speech API. +service TextToSpeech { + // Returns a list of Voice supported for synthesis. + rpc ListVoices(ListVoicesRequest) returns (ListVoicesResponse) { + option (google.api.http) = { + get: "/v1/voices" + }; + } + + // Synthesizes speech synchronously: receive results after all text input + // has been processed. + rpc SynthesizeSpeech(SynthesizeSpeechRequest) + returns (SynthesizeSpeechResponse) { + option (google.api.http) = { + post: "/v1/text:synthesize" + body: "*" + }; + } +} + +// The top-level message sent by the client for the `ListVoices` method. +message ListVoicesRequest { + // Optional (but recommended) + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. If + // specified, the ListVoices call will only return voices that can be used to + // synthesize this language_code. E.g. when specifying "en-NZ", you will get + // supported "en-*" voices; when specifying "no", you will get supported + // "no-*" (Norwegian) and "nb-*" (Norwegian Bokmal) voices; specifying "zh" + // will also get supported "cmn-*" voices; specifying "zh-hk" will also get + // supported "yue-*" voices. + string language_code = 1; +} + +// The message returned to the client by the `ListVoices` method. +message ListVoicesResponse { + // The list of voices. + repeated Voice voices = 1; +} + +// Description of a voice supported by the TTS service. +message Voice { + // The languages that this voice supports, expressed as + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tags (e.g. + // "en-US", "es-419", "cmn-tw"). + repeated string language_codes = 1; + + // The name of this voice. Each distinct voice has a unique name. + string name = 2; + + // The gender of this voice. + SsmlVoiceGender ssml_gender = 3; + + // The natural sample rate (in hertz) for this voice. + int32 natural_sample_rate_hertz = 4; +} + +// The top-level message sent by the client for the `SynthesizeSpeech` method. +message SynthesizeSpeechRequest { + // Required. The Synthesizer requires either plain text or SSML as input. + SynthesisInput input = 1; + + // Required. The desired voice of the synthesized audio. + VoiceSelectionParams voice = 2; + + // Required. The configuration of the synthesized audio. + AudioConfig audio_config = 3; +} + +// Contains text input to be synthesized. Either `text` or `ssml` must be +// supplied. Supplying both or neither returns +// [google.rpc.Code.INVALID_ARGUMENT][]. The input size is limited to 5000 +// characters. +message SynthesisInput { + // The input source, which is either plain text or SSML. + oneof input_source { + // The raw text to be synthesized. + string text = 1; + + // The SSML document to be synthesized. The SSML document must be valid + // and well-formed. Otherwise the RPC will fail and return + // [google.rpc.Code.INVALID_ARGUMENT][]. For more information, see + // [SSML](/speech/text-to-speech/docs/ssml). + string ssml = 2; + } +} + +// Description of which voice to use for a synthesis request. +message VoiceSelectionParams { + // The language (and optionally also the region) of the voice expressed as a + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag, e.g. + // "en-US". Required. This should not include a script tag (e.g. use + // "cmn-cn" rather than "cmn-Hant-cn"), because the script will be inferred + // from the input provided in the SynthesisInput. The TTS service + // will use this parameter to help choose an appropriate voice. Note that + // the TTS service may choose a voice with a slightly different language code + // than the one selected; it may substitute a different region + // (e.g. using en-US rather than en-CA if there isn't a Canadian voice + // available), or even a different language, e.g. using "nb" (Norwegian + // Bokmal) instead of "no" (Norwegian)". + string language_code = 1; + + // The name of the voice. Optional; if not set, the service will choose a + // voice based on the other parameters such as language_code and gender. + string name = 2; + + // The preferred gender of the voice. Optional; if not set, the service will + // choose a voice based on the other parameters such as language_code and + // name. Note that this is only a preference, not requirement; if a + // voice of the appropriate gender is not available, the synthesizer should + // substitute a voice with a different gender rather than failing the request. + SsmlVoiceGender ssml_gender = 3; +} + +// Description of audio data to be synthesized. +message AudioConfig { + // Required. The format of the requested audio byte stream. + AudioEncoding audio_encoding = 1; + + // Optional speaking rate/speed, in the range [0.25, 4.0]. 1.0 is the normal + // native speed supported by the specific voice. 2.0 is twice as fast, and + // 0.5 is half as fast. If unset(0.0), defaults to the native 1.0 speed. Any + // other values < 0.25 or > 4.0 will return an error. + double speaking_rate = 2; + + // Optional speaking pitch, in the range [-20.0, 20.0]. 20 means increase 20 + // semitones from the original pitch. -20 means decrease 20 semitones from the + // original pitch. + double pitch = 3; + + // Optional volume gain (in dB) of the normal native volume supported by the + // specific voice, in the range [-96.0, 16.0]. If unset, or set to a value of + // 0.0 (dB), will play at normal native signal amplitude. A value of -6.0 (dB) + // will play at approximately half the amplitude of the normal native signal + // amplitude. A value of +6.0 (dB) will play at approximately twice the + // amplitude of the normal native signal amplitude. Strongly recommend not to + // exceed +10 (dB) as there's usually no effective increase in loudness for + // any value greater than that. + double volume_gain_db = 4; + + // The synthesis sample rate (in hertz) for this audio. Optional. If this is + // different from the voice's natural sample rate, then the synthesizer will + // honor this request by converting to the desired sample rate (which might + // result in worse audio quality), unless the specified sample rate is not + // supported for the encoding chosen, in which case it will fail the request + // and return [google.rpc.Code.INVALID_ARGUMENT][]. + int32 sample_rate_hertz = 5; + + // An identifier which selects 'audio effects' profiles that are applied on + // (post synthesized) text to speech. + // Effects are applied on top of each other in the order they are given. + // See + // + // [audio-profiles](https: + // //cloud.google.com/text-to-speech/docs/audio-profiles) + // for current supported profile ids. + repeated string effects_profile_id = 6; +} + +// The message returned to the client by the `SynthesizeSpeech` method. +message SynthesizeSpeechResponse { + // The audio data bytes encoded as specified in the request, including the + // header (For LINEAR16 audio, we include the WAV header). Note: as + // with all bytes fields, protobuffers use a pure binary representation, + // whereas JSON representations use base64. + bytes audio_content = 1; +} + +// Gender of the voice as described in +// [SSML voice element](https://www.w3.org/TR/speech-synthesis11/#edef_voice). +enum SsmlVoiceGender { + // An unspecified gender. + // In VoiceSelectionParams, this means that the client doesn't care which + // gender the selected voice will have. In the Voice field of + // ListVoicesResponse, this may mean that the voice doesn't fit any of the + // other categories in this enum, or that the gender of the voice isn't known. + SSML_VOICE_GENDER_UNSPECIFIED = 0; + + // A male voice. + MALE = 1; + + // A female voice. + FEMALE = 2; + + // A gender-neutral voice. + NEUTRAL = 3; +} + +// Configuration to set up audio encoder. The encoding determines the output +// audio format that we'd like. +enum AudioEncoding { + // Not specified. Will return result [google.rpc.Code.INVALID_ARGUMENT][]. + AUDIO_ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + // Audio content returned as LINEAR16 also contains a WAV header. + LINEAR16 = 1; + + // MP3 audio. + MP3 = 2; + + // Opus encoded audio wrapped in an ogg container. The result will be a + // file which can be played natively on Android, and in browsers (at least + // Chrome and Firefox). The quality of the encoding is considerably higher + // than MP3 while using approximately the same bitrate. + OGG_OPUS = 3; +} diff --git a/google/cloud/texttospeech/v1/texttospeech_gapic.yaml b/google/cloud/texttospeech/v1/texttospeech_gapic.yaml new file mode 100644 index 000000000..5f35fcdd4 --- /dev/null +++ b/google/cloud/texttospeech/v1/texttospeech_gapic.yaml @@ -0,0 +1,135 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.texttospeech.v1 + python: + package_name: google.cloud.texttospeech_v1.gapic + go: + package_name: cloud.google.com/go/texttospeech/apiv1 + csharp: + package_name: Google.Cloud.TextToSpeech.V1 + ruby: + package_name: Google::Cloud::TextToSpeech::V1 + php: + package_name: Google\Cloud\TextToSpeech\V1 + nodejs: + package_name: text-to-speech.v1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.texttospeech.v1.TextToSpeech + smoke_test: + method: SynthesizeSpeech + init_fields: + - input.text="test" + - voice.language_code="en-US" + - audio_config.audio_encoding=MP3 + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListVoices + flattening: + groups: + - parameters: + - language_code + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: SynthesizeSpeech + flattening: + groups: + - parameters: + - input + - voice + - audio_config + required_fields: + - input + - voice + - audio_config + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/texttospeech/v1beta1/BUILD.bazel b/google/cloud/texttospeech/v1beta1/BUILD.bazel new file mode 100644 index 000000000..15e70107e --- /dev/null +++ b/google/cloud/texttospeech/v1beta1/BUILD.bazel @@ -0,0 +1,119 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "texttospeech_proto", + srcs = [ + "cloud_tts.proto", + ], + deps = [ + "//google/api:annotations_proto", + ], +) + +proto_library_with_info( + name = "texttospeech_proto_with_info", + deps = [":texttospeech_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", "java_gapic_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "texttospeech_java_proto", + deps = [":texttospeech_proto"], +) + +java_grpc_library( + name = "texttospeech_java_grpc", + srcs = [":texttospeech_proto"], + deps = [":texttospeech_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_gapic_library( + name = "texttospeech_java_gapic", + src = ":texttospeech_proto_with_info", + gapic_yaml = "texttospeech_gapic.yaml", + service_yaml = "//google/cloud/texttospeech:tts_v1beta1.yaml", + test_deps = [":texttospeech_java_grpc"], + deps = [":texttospeech_java_proto"] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":texttospeech_java_gapic_test"], +) for test_name in [ + "com.google.cloud.texttospeech.v1beta1.TextToSpeechClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-texttospeech-v1beta1-java", + client_deps = [":texttospeech_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":texttospeech_java_gapic_test"], + grpc_deps = [":texttospeech_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":texttospeech_java_proto", + ":texttospeech_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "texttospeech_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/texttospeech/v1beta1", + protos = [":texttospeech_proto_with_info"], + deps = ["//google/api:annotations_go_proto"], +) + +go_gapic_library( + name = "texttospeech_go_gapic", + src = ":texttospeech_proto_with_info", + gapic_yaml = "texttospeech_gapic.yaml", + importpath = "cloud.google.com/go/texttospeech/apiv1beta1", + service_yaml = "//google/cloud/texttospeech:tts_v1beta1.yaml", + deps = [":texttospeech_go_proto"], +) + +go_test( + name = "texttospeech_go_gapic_test", + srcs = [":texttospeech_go_gapic_srcjar_test"], + embed = [":texttospeech_go_gapic"], + importpath = "cloud.google.com/go/texttospeech/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-texttospeech-v1beta1-go", + deps = [ + ":texttospeech_go_gapic", + ":texttospeech_go_gapic_srcjar-smoke-test.srcjar", + ":texttospeech_go_gapic_srcjar-test.srcjar", + ":texttospeech_go_proto", + ], +) diff --git a/google/cloud/texttospeech/v1beta1/cloud_tts.proto b/google/cloud/texttospeech/v1beta1/cloud_tts.proto new file mode 100644 index 000000000..791499c4d --- /dev/null +++ b/google/cloud/texttospeech/v1beta1/cloud_tts.proto @@ -0,0 +1,228 @@ +// Copyright 2018 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.texttospeech.v1beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/texttospeech/v1beta1;texttospeech"; +option java_multiple_files = true; +option java_outer_classname = "TextToSpeechProto"; +option java_package = "com.google.cloud.texttospeech.v1beta1"; + +// Service that implements Google Cloud Text-to-Speech API. +service TextToSpeech { + // Returns a list of [Voice][google.cloud.texttospeech.v1beta1.Voice] + // supported for synthesis. + rpc ListVoices(ListVoicesRequest) returns (ListVoicesResponse) { + option (google.api.http) = { + get: "/v1beta1/voices" + }; + } + + // Synthesizes speech synchronously: receive results after all text input + // has been processed. + rpc SynthesizeSpeech(SynthesizeSpeechRequest) + returns (SynthesizeSpeechResponse) { + option (google.api.http) = { + post: "/v1beta1/text:synthesize" + body: "*" + }; + } +} + +// The top-level message sent by the client for the `ListVoices` method. +message ListVoicesRequest { + // Optional (but recommended) + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. If + // specified, the ListVoices call will only return voices that can be used to + // synthesize this language_code. E.g. when specifying "en-NZ", you will get + // supported "en-*" voices; when specifying "no", you will get supported + // "no-*" (Norwegian) and "nb-*" (Norwegian Bokmal) voices; specifying "zh" + // will also get supported "cmn-*" voices; specifying "zh-hk" will also get + // supported "yue-*" voices. + string language_code = 1; +} + +// The message returned to the client by the `ListVoices` method. +message ListVoicesResponse { + // The list of voices. + repeated Voice voices = 1; +} + +// Description of a voice supported by the TTS service. +message Voice { + // The languages that this voice supports, expressed as + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tags (e.g. + // "en-US", "es-419", "cmn-tw"). + repeated string language_codes = 1; + + // The name of this voice. Each distinct voice has a unique name. + string name = 2; + + // The gender of this voice. + SsmlVoiceGender ssml_gender = 3; + + // The natural sample rate (in hertz) for this voice. + int32 natural_sample_rate_hertz = 4; +} + +// The top-level message sent by the client for the `SynthesizeSpeech` method. +message SynthesizeSpeechRequest { + // Required. The Synthesizer requires either plain text or SSML as input. + SynthesisInput input = 1; + + // Required. The desired voice of the synthesized audio. + VoiceSelectionParams voice = 2; + + // Required. The configuration of the synthesized audio. + AudioConfig audio_config = 3; +} + +// Contains text input to be synthesized. Either `text` or `ssml` must be +// supplied. Supplying both or neither returns +// [google.rpc.Code.INVALID_ARGUMENT][]. The input size is limited to 5000 +// characters. +message SynthesisInput { + // The input source, which is either plain text or SSML. + oneof input_source { + // The raw text to be synthesized. + string text = 1; + + // The SSML document to be synthesized. The SSML document must be valid + // and well-formed. Otherwise the RPC will fail and return + // [google.rpc.Code.INVALID_ARGUMENT][]. For more information, see + // [SSML](/speech/text-to-speech/docs/ssml). + string ssml = 2; + } +} + +// Description of which voice to use for a synthesis request. +message VoiceSelectionParams { + // The language (and optionally also the region) of the voice expressed as a + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag, e.g. + // "en-US". Required. This should not include a script tag (e.g. use + // "cmn-cn" rather than "cmn-Hant-cn"), because the script will be inferred + // from the input provided in the SynthesisInput. The TTS service + // will use this parameter to help choose an appropriate voice. Note that + // the TTS service may choose a voice with a slightly different language code + // than the one selected; it may substitute a different region + // (e.g. using en-US rather than en-CA if there isn't a Canadian voice + // available), or even a different language, e.g. using "nb" (Norwegian + // Bokmal) instead of "no" (Norwegian)". + string language_code = 1; + + // The name of the voice. Optional; if not set, the service will choose a + // voice based on the other parameters such as language_code and gender. + string name = 2; + + // The preferred gender of the voice. Optional; if not set, the service will + // choose a voice based on the other parameters such as language_code and + // name. Note that this is only a preference, not requirement; if a + // voice of the appropriate gender is not available, the synthesizer should + // substitute a voice with a different gender rather than failing the request. + SsmlVoiceGender ssml_gender = 3; +} + +// Description of audio data to be synthesized. +message AudioConfig { + // Required. The format of the requested audio byte stream. + AudioEncoding audio_encoding = 1; + + // Optional speaking rate/speed, in the range [0.25, 4.0]. 1.0 is the normal + // native speed supported by the specific voice. 2.0 is twice as fast, and + // 0.5 is half as fast. If unset(0.0), defaults to the native 1.0 speed. Any + // other values < 0.25 or > 4.0 will return an error. + double speaking_rate = 2; + + // Optional speaking pitch, in the range [-20.0, 20.0]. 20 means increase 20 + // semitones from the original pitch. -20 means decrease 20 semitones from the + // original pitch. + double pitch = 3; + + // Optional volume gain (in dB) of the normal native volume supported by the + // specific voice, in the range [-96.0, 16.0]. If unset, or set to a value of + // 0.0 (dB), will play at normal native signal amplitude. A value of -6.0 (dB) + // will play at approximately half the amplitude of the normal native signal + // amplitude. A value of +6.0 (dB) will play at approximately twice the + // amplitude of the normal native signal amplitude. Strongly recommend not to + // exceed +10 (dB) as there's usually no effective increase in loudness for + // any value greater than that. + double volume_gain_db = 4; + + // The synthesis sample rate (in hertz) for this audio. Optional. If this is + // different from the voice's natural sample rate, then the synthesizer will + // honor this request by converting to the desired sample rate (which might + // result in worse audio quality), unless the specified sample rate is not + // supported for the encoding chosen, in which case it will fail the request + // and return [google.rpc.Code.INVALID_ARGUMENT][]. + int32 sample_rate_hertz = 5; + + // An identifier which selects 'audio effects' profiles that are applied on + // (post synthesized) text to speech. + // Effects are applied on top of each other in the order they are given. + repeated string effects_profile_id = 6; +} + +// The message returned to the client by the `SynthesizeSpeech` method. +message SynthesizeSpeechResponse { + // The audio data bytes encoded as specified in the request, including the + // header (For LINEAR16 audio, we include the WAV header). Note: as + // with all bytes fields, protobuffers use a pure binary representation, + // whereas JSON representations use base64. + bytes audio_content = 1; +} + +// Gender of the voice as described in +// [SSML voice element](https://www.w3.org/TR/speech-synthesis11/#edef_voice). +enum SsmlVoiceGender { + // An unspecified gender. + // In VoiceSelectionParams, this means that the client doesn't care which + // gender the selected voice will have. In the Voice field of + // ListVoicesResponse, this may mean that the voice doesn't fit any of the + // other categories in this enum, or that the gender of the voice isn't known. + SSML_VOICE_GENDER_UNSPECIFIED = 0; + + // A male voice. + MALE = 1; + + // A female voice. + FEMALE = 2; + + // A gender-neutral voice. + NEUTRAL = 3; +} + +// Configuration to set up audio encoder. The encoding determines the output +// audio format that we'd like. +enum AudioEncoding { + // Not specified. Will return result [google.rpc.Code.INVALID_ARGUMENT][]. + AUDIO_ENCODING_UNSPECIFIED = 0; + + // Uncompressed 16-bit signed little-endian samples (Linear PCM). + // Audio content returned as LINEAR16 also contains a WAV header. + LINEAR16 = 1; + + // MP3 audio. + MP3 = 2; + + // Opus encoded audio wrapped in an ogg container. The result will be a + // file which can be played natively on Android, and in browsers (at least + // Chrome and Firefox). The quality of the encoding is considerably higher + // than MP3 while using approximately the same bitrate. + OGG_OPUS = 3; +} diff --git a/google/cloud/texttospeech/v1beta1/texttospeech_gapic.yaml b/google/cloud/texttospeech/v1beta1/texttospeech_gapic.yaml new file mode 100644 index 000000000..276f9ed83 --- /dev/null +++ b/google/cloud/texttospeech/v1beta1/texttospeech_gapic.yaml @@ -0,0 +1,135 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.texttospeech.v1beta1 + python: + package_name: google.cloud.texttospeech_v1beta1.gapic + go: + package_name: cloud.google.com/go/texttospeech/apiv1beta1 + csharp: + package_name: Google.Cloud.TextToSpeech.V1Beta1 + ruby: + package_name: Google::Cloud::TextToSpeech::V1beta1 + php: + package_name: Google\Cloud\TextToSpeech\V1beta1 + nodejs: + package_name: text-to-speech.v1beta1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.texttospeech.v1beta1.TextToSpeech + smoke_test: + method: SynthesizeSpeech + init_fields: + - input.text="test" + - voice.language_code="en-US" + - audio_config.audio_encoding=MP3 + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListVoices + flattening: + groups: + - parameters: + - language_code + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 30000 + - name: SynthesizeSpeech + flattening: + groups: + - parameters: + - input + - voice + - audio_config + required_fields: + - input + - voice + - audio_config + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/translate/artman_translate_v3beta1.yaml b/google/cloud/translate/artman_translate_v3beta1.yaml new file mode 100644 index 000000000..5b5e1b8c7 --- /dev/null +++ b/google/cloud/translate/artman_translate_v3beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: translate + api_version: v3beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v3beta1 + service_yaml: translate_v3beta1.yaml + gapic_yaml: v3beta1/translate_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/translate/translate_v3beta1.yaml b/google/cloud/translate/translate_v3beta1.yaml new file mode 100644 index 000000000..2df789463 --- /dev/null +++ b/google/cloud/translate/translate_v3beta1.yaml @@ -0,0 +1,68 @@ +type: google.api.Service +config_version: 3 +name: translate.googleapis.com +title: Cloud Translation API + +apis: +- name: google.cloud.translation.v3beta1.TranslationService + +documentation: + summary: Integrates text translation into your website or application. + +http: + rules: + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + get: '/v3beta1/{resource=projects/*/locations/*}:getIamPolicy' + additional_bindings: + - get: '/v3beta1/{resource=projects/*/locations/*/glossaries/*}:getIamPolicy' + - get: '/v3beta1/{resource=projects/*/locations/*/models/*}:getIamPolicy' + - get: '/v3beta1/{resource=projects/*/locations/*/models/general/*}:getIamPolicy' + - get: '/v3beta1/{resource=projects/*/locations/*/models/language-detection/*}:getIamPolicy' + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + post: '/v3beta1/{resource=projects/*/locations/*}:setIamPolicy' + body: '*' + additional_bindings: + - post: '/v3beta1/{resource=projects/*/locations/*/glossaries/*}:setIamPolicy' + body: '*' + - post: '/v3beta1/{resource=projects/*/locations/*/models/*}:setIamPolicy' + body: '*' + - post: '/v3beta1/{resource=projects/*/locations/*/models/general/*}:setIamPolicy' + body: '*' + - post: '/v3beta1/{resource=projects/*/locations/*/models/language-detection/*}:setIamPolicy' + body: '*' + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + post: '/v3beta1/{resource=projects/*/locations/*/**}:testIamPermissions' + body: '*' + - selector: google.longrunning.Operations.CancelOperation + post: '/v3beta1/{name=projects/*/locations/*/operations/*}:cancel' + body: '*' + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v3beta1/{name=projects/*/locations/*/operations/*}' + - selector: google.longrunning.Operations.GetOperation + get: '/v3beta1/{name=projects/*/locations/*/operations/*}' + - selector: google.longrunning.Operations.ListOperations + get: '/v3beta1/{name=projects/*/locations/*/operations}' + - selector: google.longrunning.Operations.WaitOperation + post: '/v3beta1/{name=projects/*/locations/*/operations/*}:wait' + body: '*' + +authentication: + rules: + - selector: 'google.cloud.translation.v3beta1.TranslationService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-translation + - selector: google.cloud.translation.v3beta1.TranslationService.BatchTranslateText + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: google.cloud.translation.v3beta1.TranslationService.CreateGlossary + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: 'google.longrunning.Operations.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-translation diff --git a/google/cloud/translate/v3beta1/translate_gapic.yaml b/google/cloud/translate/v3beta1/translate_gapic.yaml new file mode 100644 index 000000000..5a4e25638 --- /dev/null +++ b/google/cloud/translate/v3beta1/translate_gapic.yaml @@ -0,0 +1,235 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.translate.v3beta1 + python: + package_name: google.cloud.translate_v3beta1.gapic + go: + package_name: cloud.google.com/go/translate/apiv3beta1 + csharp: + package_name: Google.Cloud.Translate.V3Beta1 + ruby: + package_name: Google::Cloud::Translate::V3beta1 + php: + package_name: Google\Cloud\Translate\V3beta1 + nodejs: + package_name: translate.v3beta1 + domain_layer_location: google-cloud +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.translation.v3beta1.TranslationService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/glossaries/{glossary} + entity_name: glossary + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: TranslateText + required_fields: + - contents + - target_language_code + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: DetectLanguage + flattening: + groups: + - parameters: + - parent + - model + - mime_type + required_fields: + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetSupportedLanguages + flattening: + groups: + - parameters: + - parent + - display_language_code + - model + required_fields: + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: BatchTranslateText + required_fields: + - source_language_code + - target_language_codes + - input_configs + - output_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + long_running: + return_type: google.cloud.translation.v3beta1.BatchTranslateResponse + metadata_type: google.cloud.translation.v3beta1.BatchTranslateMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 60000 + - name: CreateGlossary + flattening: + groups: + - parameters: + - parent + - glossary + required_fields: + - parent + - glossary + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + long_running: + return_type: google.cloud.translation.v3beta1.Glossary + metadata_type: google.cloud.translation.v3beta1.CreateGlossaryMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 60000 + - name: ListGlossaries + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: glossaries + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetGlossary + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: glossary + timeout_millis: 60000 + - name: DeleteGlossary + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: glossary + long_running: + return_type: google.cloud.translation.v3beta1.DeleteGlossaryResponse + metadata_type: google.cloud.translation.v3beta1.DeleteGlossaryMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 60000 diff --git a/google/cloud/translate/v3beta1/translation_service.proto b/google/cloud/translate/v3beta1/translation_service.proto new file mode 100644 index 000000000..e9e65baa3 --- /dev/null +++ b/google/cloud/translate/v3beta1/translation_service.proto @@ -0,0 +1,740 @@ +// Copyright 2019 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.translation.v3beta1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Cloud.Translate.V3Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/translate/v3beta1;translate"; +option java_multiple_files = true; +option java_outer_classname = "TranslationServiceProto"; +option java_package = "com.google.cloud.translate.v3beta1"; +option php_namespace = "Google\\Cloud\\Translate\\V3beta1"; +option ruby_package = "Google::Cloud::Translate::V3beta1"; + +// Proto file for the Cloud Translation API (v3beta1). + +// Provides natural language translation operations. +service TranslationService { + // Translates input text and returns translated text. + rpc TranslateText(TranslateTextRequest) returns (TranslateTextResponse) { + option (google.api.http) = { + post: "/v3beta1/{parent=projects/*/locations/*}:translateText" + body: "*" + }; + } + + // Detects the language of text within a request. + rpc DetectLanguage(DetectLanguageRequest) returns (DetectLanguageResponse) { + option (google.api.http) = { + post: "/v3beta1/{parent=projects/*/locations/*}:detectLanguage" + body: "*" + }; + } + + // Returns a list of supported languages for translation. + rpc GetSupportedLanguages(GetSupportedLanguagesRequest) returns (SupportedLanguages) { + option (google.api.http) = { + get: "/v3beta1/{parent=projects/*/locations/*}/supportedLanguages" + }; + } + + // Translates a large volume of text in asynchronous batch mode. + // This function provides real-time output as the inputs are being processed. + // If caller cancels a request, the partial results (for an input file, it's + // all or nothing) may still be available on the specified output location. + // + // This call returns immediately and you can + // use google.longrunning.Operation.name to poll the status of the call. + rpc BatchTranslateText(BatchTranslateTextRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v3beta1/{parent=projects/*/locations/*}:batchTranslateText" + body: "*" + }; + } + + // Creates a glossary and returns the long-running operation. Returns + // NOT_FOUND, if the project doesn't exist. + rpc CreateGlossary(CreateGlossaryRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v3beta1/{parent=projects/*/locations/*}/glossaries" + body: "glossary" + }; + } + + // Lists glossaries in a project. Returns NOT_FOUND, if the project doesn't + // exist. + rpc ListGlossaries(ListGlossariesRequest) returns (ListGlossariesResponse) { + option (google.api.http) = { + get: "/v3beta1/{parent=projects/*/locations/*}/glossaries" + }; + } + + // Gets a glossary. Returns NOT_FOUND, if the glossary doesn't + // exist. + rpc GetGlossary(GetGlossaryRequest) returns (Glossary) { + option (google.api.http) = { + get: "/v3beta1/{name=projects/*/locations/*/glossaries/*}" + }; + } + + // Deletes a glossary, or cancels glossary construction + // if the glossary isn't created yet. + // Returns NOT_FOUND, if the glossary doesn't exist. + rpc DeleteGlossary(DeleteGlossaryRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v3beta1/{name=projects/*/locations/*/glossaries/*}" + }; + } +} + +// Configures which glossary should be used for a specific target language, +// and defines options for applying that glossary. +message TranslateTextGlossaryConfig { + // Required. Specifies the glossary used for this translation. Use + // this format: projects/*/locations/*/glossaries/* + string glossary = 1; + + // Optional. Indicates whether we should do a case-insensitive match. + // Default value is false if missing. + bool ignore_case = 2; +} + +// The request message for synchronous translation. +message TranslateTextRequest { + // Required. The content of the input in string format. + // We recommend the total contents to be less than 30k codepoints. + // Please use BatchTranslateText for larger text. + repeated string contents = 1; + + // Optional. The format of the source text, for example, "text/html", + // "text/plain". If left blank, the MIME type is assumed to be "text/html". + string mime_type = 3; + + // Optional. The BCP-47 language code of the input text if + // known, for example, "en-US" or "sr-Latn". Supported language codes are + // listed in Language Support. If the source language isn't specified, the API + // attempts to identify the source language automatically and returns the + // the source language within the response. + string source_language_code = 4; + + // Required. The BCP-47 language code to use for translation of the input + // text, set to one of the language codes listed in Language Support. + string target_language_code = 5; + + // Optional. Only used when making regionalized call. + // Format: + // projects/{project-id}/locations/{location-id}. + // + // Only custom model/glossary within the same location-id can be used. + // Otherwise 400 is returned. + string parent = 8; + + // Optional. The `model` type requested for this translation. + // + // The format depends on model type: + // 1. Custom models: + // projects/{project-id}/locations/{location-id}/models/{model-id}. + // 2. General (built-in) models: + // projects/{project-id}/locations/{location-id}/models/general/nmt + // projects/{project-id}/locations/{location-id}/models/general/base + // + // For global (non-regionalized) requests, use {location-id} 'global'. + // For example, + // projects/{project-id}/locations/global/models/general/nmt + // + // If missing, the system decides which google base model to use. + string model = 6; + + // Optional. Glossary to be applied. The glossary needs to be in the same + // region as the model, otherwise an INVALID_ARGUMENT error is returned. + TranslateTextGlossaryConfig glossary_config = 7; +} + +// The main language translation response message. +message TranslateTextResponse { + // Text translation responses with no glossary applied. + // This field has the same length as `contents` in TranslateTextRequest. + repeated Translation translations = 1; + + // Text translation responses if a glossary is provided in the request. + // This could be the same as 'translation' above if no terms apply. + // This field has the same length as `contents` in TranslateTextRequest. + repeated Translation glossary_translations = 3; +} + +// A single translation response. +message Translation { + // Text translated into the target language. + string translated_text = 1; + + // Only present when `model` is present in the request. + // This is same as `model` provided in the request. + string model = 2; + + // The BCP-47 language code of source text in the initial request, detected + // automatically, if no source language was passed within the initial + // request. If the source language was passed, auto-detection of the language + // does not occur and this field will be empty. + string detected_language_code = 4; + + // The `glossary_config` used for this translation. + TranslateTextGlossaryConfig glossary_config = 3; +} + +// The request message for language detection. +message DetectLanguageRequest { + // Optional. Only used when making regionalized call. + // Format: + // projects/{project-id}/locations/{location-id}. + // + // Only custom model within the same location-id can be used. + // Otherwise 400 is returned. + string parent = 5; + + // Optional. The language detection model to be used. + // projects/{project-id}/locations/{location-id}/models/language-detection/{model-id} + // If not specified, default will be used. + string model = 4; + + // Required. The source of the document from which to detect the language. + oneof source { + // The content of the input stored as a string. + string content = 1; + } + + // Optional. The format of the source text, for example, "text/html", + // "text/plain". If left blank, the MIME type is assumed to be "text/html". + string mime_type = 3; +} + +// The response message for language detection. +message DetectedLanguage { + // The BCP-47 language code of source content in the request, detected + // automatically. + string language_code = 1; + + // The confidence of the detection result for this language. + float confidence = 2; +} + +// The response message for language detection. +message DetectLanguageResponse { + // A list of detected languages sorted by detection confidence in descending + // order. The most probable language first. + repeated DetectedLanguage languages = 1; +} + +// The request message for discovering supported languages. +message GetSupportedLanguagesRequest { + // Optional. Used for making regionalized calls. + // Format: projects/{project-id}/locations/{location-id}. + // For global calls, use projects/{project-id}/locations/global. + // If missing, the call is treated as a global call. + // + // Only custom model within the same location-id can be used. + // Otherwise 400 is returned. + string parent = 3; + + // Optional. The language to use to return localized, human readable names + // of supported languages. If missing, default language is ENGLISH. + string display_language_code = 1; + + // Optional. Get supported languages of this model. + // The format depends on model type: + // 1. Custom models: + // projects/{project-id}/locations/{location-id}/models/{model-id}. + // 2. General (built-in) models: + // projects/{project-id}/locations/{location-id}/models/general/nmt + // projects/{project-id}/locations/{location-id}/models/general/base + // Returns languages supported by the specified model. + // If missing, we get supported languages of Google general NMT model. + string model = 2; +} + +// The response message for discovering supported languages. +message SupportedLanguages { + // A list of supported language responses. This list contains an entry + // for each language the Translation API supports. + repeated SupportedLanguage languages = 1; +} + +// A single supported language response corresponds to information related +// to one supported language. +message SupportedLanguage { + // Supported language code, generally consisting of its ISO 639-1 + // identifier, for example, 'en', 'ja'. In certain cases, BCP-47 codes + // including language and region identifiers are returned (for example, + // 'zh-TW' and 'zh-CN') + string language_code = 1; + + // Human readable name of the language localized in the display language + // specified in the request. + string display_name = 2; + + // Can be used as source language. + bool support_source = 3; + + // Can be used as target language. + bool support_target = 4; +} + +// The GCS location for the input content. +message GcsSource { + // Required. Source data URI. For example, `gs://my_bucket/my_object`. + string input_uri = 1; +} + +// Input configuration. +message InputConfig { + // Optional. Can be "text/plain" or "text/html". + // For `.tsv`, "text/html" is used if mime_type is missing. + // For `.html`, this field must be "text/html" or empty. + // For `.txt`, this field must be "text/plain" or empty. + string mime_type = 1; + + // Required. Specify the input. + oneof source { + // Required. Google Cloud Storage location for the source input. + // This can be a single file (for example, + // `gs://translation-test/input.tsv`) or a wildcard (for example, + // `gs://translation-test/*`). If a file extension is `.tsv`, it can + // contain either one or two columns. The first column (optional) is the id + // of the text request. If the first column is missing, we use the row + // number (0-based) from the input file as the ID in the output file. The + // second column is the actual text to be + // translated. We recommend each row be <= 10K Unicode codepoints, + // otherwise an error might be returned. + // + // The other supported file extensions are `.txt` or `.html`, which is + // treated as a single large chunk of text. + GcsSource gcs_source = 2; + } +} + +// The GCS location for the output content +message GcsDestination { + // Required. There must be no files under 'output_uri_prefix'. + // 'output_uri_prefix' must end with "/". Otherwise error 400 is returned. + string output_uri_prefix = 1; +} + +// Output configuration. +message OutputConfig { + // Required. The destination of output. + oneof destination { + // Google Cloud Storage destination for output content. + // For every single input file (for example, gs://a/b/c.[extension]), we + // generate at most 2 * n output files. (n is the # of target_language_codes + // in the BatchTranslateTextRequest). + // + // Output files (tsv) generated are compliant with RFC 4180 except that + // record delimiters are '\n' instead of '\r\n'. We don't provide any way to + // change record delimiters. + // + // While the input files are being processed, we write/update an index file + // 'index.csv' under 'output_uri_prefix' (for example, + // gs://translation-test/index.csv) The index file is generated/updated as + // new files are being translated. The format is: + // + // input_file,target_language_code,translations_file,errors_file, + // glossary_translations_file,glossary_errors_file + // + // input_file is one file we matched using gcs_source.input_uri. + // target_language_code is provided in the request. + // translations_file contains the translations. (details provided below) + // errors_file contains the errors during processing of the file. (details + // below). Both translations_file and errors_file could be empty + // strings if we have no content to output. + // glossary_translations_file,glossary_errors_file are always empty string + // if input_file is tsv. They could also be empty if we have no content to + // output. + // + // Once a row is present in index.csv, the input/output matching never + // changes. Callers should also expect all the content in input_file are + // processed and ready to be consumed (that is, No partial output file is + // written). + // + // The format of translations_file (for target language code 'trg') is: + // gs://translation_test/a_b_c_'trg'_translations.[extension] + // + // If the input file extension is tsv, the output has the following + // columns: + // Column 1: ID of the request provided in the input, if it's not + // provided in the input, then the input row number is used (0-based). + // Column 2: source sentence. + // Column 3: translation without applying a glossary. Empty string if there + // is an error. + // Column 4 (only present if a glossary is provided in the request): + // translation after applying the glossary. Empty string if there is an + // error applying the glossary. Could be same string as column 3 if there is + // no glossary applied. + // + // If input file extension is a txt or html, the translation is directly + // written to the output file. If glossary is requested, a separate + // glossary_translations_file has format of + // gs://translation_test/a_b_c_'trg'_glossary_translations.[extension] + // + // The format of errors file (for target language code 'trg') is: + // gs://translation_test/a_b_c_'trg'_errors.[extension] + // + // If the input file extension is tsv, errors_file has the + // following Column 1: ID of the request provided in the input, if it's not + // provided in the input, then the input row number is used (0-based). + // Column 2: source sentence. + // Column 3: Error detail for the translation. Could be empty. + // Column 4 (only present if a glossary is provided in the request): + // Error when applying the glossary. + // + // If the input file extension is txt or html, glossary_error_file will be + // generated that contains error details. glossary_error_file has format of + // gs://translation_test/a_b_c_'trg'_glossary_errors.[extension] + GcsDestination gcs_destination = 1; + } +} + +// The batch translation request. +message BatchTranslateTextRequest { + // Optional. Only used when making regionalized call. + // Format: + // projects/{project-id}/locations/{location-id}. + // + // Only custom models/glossaries within the same location-id can be used. + // Otherwise 400 is returned. + string parent = 1; + + // Required. Source language code. + string source_language_code = 2; + + // Required. Specify up to 10 language codes here. + repeated string target_language_codes = 3; + + // Optional. The models to use for translation. Map's key is target language + // code. Map's value is model name. Value can be a built-in general model, + // or a custom model built by AutoML. + // + // The value format depends on model type: + // 1. Custom models: + // projects/{project-id}/locations/{location-id}/models/{model-id}. + // 2. General (built-in) models: + // projects/{project-id}/locations/{location-id}/models/general/nmt + // projects/{project-id}/locations/{location-id}/models/general/base + // + // If the map is empty or a specific model is + // not requested for a language pair, then default google model is used. + map<string, string> models = 4; + + // Required. Input configurations. + // The total number of files matched should be <= 1000. + // The total content size should be <= 100M Unicode codepoints. + // The files must use UTF-8 encoding. + repeated InputConfig input_configs = 5; + + // Required. Output configuration. + // If 2 input configs match to the same file (that is, same input path), + // we don't generate output for duplicate inputs. + OutputConfig output_config = 6; + + // Optional. Glossaries to be applied for translation. + // It's keyed by target language code. + map<string, TranslateTextGlossaryConfig> glossaries = 7; +} + +// State metadata for the batch translation operation. +message BatchTranslateMetadata { + // State of the job. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is being processed. + RUNNING = 1; + + // The batch is processed, and at least one item has been successfully + // processed. + SUCCEEDED = 2; + + // The batch is done and no item has been successfully processed. + FAILED = 3; + + // Request is in the process of being canceled after caller invoked + // longrunning.Operations.CancelOperation on the request id. + CANCELLING = 4; + + // The batch is done after the user has called the + // longrunning.Operations.CancelOperation. Any records processed before the + // cancel command are output as specified in the request. + CANCELLED = 5; + } + + // The state of the operation. + State state = 1; + + // Number of successfully translated characters so far (Unicode codepoints). + int64 translated_characters = 2; + + // Number of characters that have failed to process so far (Unicode + // codepoints). + int64 failed_characters = 3; + + // Total number of characters (Unicode codepoints). + // This is the total number of codepoints from input files times the number of + // target languages. It appears here shortly after the call is submitted. + int64 total_characters = 4; + + // Time when the operation was submitted. + google.protobuf.Timestamp submit_time = 5; +} + +// Stored in the [google.longrunning.Operation.response][google.longrunning.Operation.response] field returned by +// BatchTranslateText if at least one sentence is translated successfully. +message BatchTranslateResponse { + // Total number of characters (Unicode codepoints). + int64 total_characters = 1; + + // Number of successfully translated characters (Unicode codepoints). + int64 translated_characters = 2; + + // Number of characters that have failed to process (Unicode codepoints). + int64 failed_characters = 3; + + // Time when the operation was submitted. + google.protobuf.Timestamp submit_time = 4; + + // The time when the operation is finished and + // [google.longrunning.Operation.done][google.longrunning.Operation.done] is set to true. + google.protobuf.Timestamp end_time = 5; +} + +// Input configuration for glossaries. +message GlossaryInputConfig { + // Required. Specify the input. + oneof source { + // Required. Google Cloud Storage location of glossary data. + // File format is determined based on file name extension. API returns + // [google.rpc.Code.INVALID_ARGUMENT] for unsupported URI-s and file + // formats. Wildcards are not allowed. This must be a single file in one of + // the following formats: + // + // For `UNIDIRECTIONAL` glossaries: + // + // - TSV/CSV (`.tsv`/`.csv`): 2 column file, tab- or comma-separated. + // The first column is source text. The second column is target text. + // The file must not contain headers. That is, the first row is data, not + // column names. + // + // - TMX (`.tmx`): TMX file with parallel data defining source/target term + // pairs. + // + // For `EQUIVALENT_TERMS_SET` glossaries: + // + // - CSV (`.csv`): Multi-column CSV file defining equivalent glossary terms + // in multiple languages. The format is defined for Google Translation + // Toolkit and documented here: + // `https://support.google.com/translatortoolkit/answer/6306379?hl=en`. + GcsSource gcs_source = 1; + } +} + +// Represents a glossary built from user provided data. +message Glossary { + // Used with UNIDIRECTIONAL. + message LanguageCodePair { + // Required. The BCP-47 language code of the input text, for example, + // "en-US". Expected to be an exact match for GlossaryTerm.language_code. + string source_language_code = 1; + + // Required. The BCP-47 language code for translation output, for example, + // "zh-CN". Expected to be an exact match for GlossaryTerm.language_code. + string target_language_code = 2; + } + + // Used with EQUIVALENT_TERMS_SET. + message LanguageCodesSet { + // The BCP-47 language code(s) for terms defined in the glossary. + // All entries are unique. The list contains at least two entries. + // Expected to be an exact match for GlossaryTerm.language_code. + repeated string language_codes = 1; + } + + // Required. The resource name of the glossary. Glossary names have the form + // `projects/{project-id}/locations/{location-id}/glossaries/{glossary-id}`. + string name = 1; + + // Languages supported by the glossary. + oneof languages { + // Used with UNIDIRECTIONAL. + LanguageCodePair language_pair = 3; + + // Used with EQUIVALENT_TERMS_SET. + LanguageCodesSet language_codes_set = 4; + } + + // Required. Provides examples to build the glossary from. + // Total glossary must not exceed 10M Unicode codepoints. + GlossaryInputConfig input_config = 5; + + // Output only. The number of entries defined in the glossary. + int32 entry_count = 6; + + // Output only. When CreateGlossary was called. + google.protobuf.Timestamp submit_time = 7; + + // Output only. When the glossary creation was finished. + google.protobuf.Timestamp end_time = 8; +} + +// Request message for CreateGlossary. +message CreateGlossaryRequest { + // Required. The project name. + string parent = 1; + + // Required. The glossary to create. + Glossary glossary = 2; +} + +// Request message for GetGlossary. +message GetGlossaryRequest { + // Required. The name of the glossary to retrieve. + string name = 1; +} + +// Request message for DeleteGlossary. +message DeleteGlossaryRequest { + // Required. The name of the glossary to delete. + string name = 1; +} + +// Request message for ListGlossaries. +message ListGlossariesRequest { + // Required. The name of the project from which to list all of the glossaries. + string parent = 1; + + // Optional. Requested page size. The server may return fewer glossaries than + // requested. If unspecified, the server picks an appropriate default. + int32 page_size = 2; + + // Optional. A token identifying a page of results the server should return. + // Typically, this is the value of [ListGlossariesResponse.next_page_token] + // returned from the previous call to `ListGlossaries` method. + // The first page is returned if `page_token`is empty or missing. + string page_token = 3; + + // Optional. Filter specifying constraints of a list operation. + // For example, `tags.glossary_name="products*"`. + // If missing, no filtering is performed. + string filter = 4; +} + +// Response message for ListGlossaries. +message ListGlossariesResponse { + // The list of glossaries for a project. + repeated Glossary glossaries = 1; + + // A token to retrieve a page of results. Pass this value in the + // [ListGlossariesRequest.page_token] field in the subsequent call to + // `ListGlossaries` method to retrieve the next page of results. + string next_page_token = 2; +} + +// Stored in the [google.longrunning.Operation.metadata][google.longrunning.Operation.metadata] field returned by +// CreateGlossary. +message CreateGlossaryMetadata { + // Enumerates the possible states that the creation request can be in. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is being processed. + RUNNING = 1; + + // The glossary has been successfully created. + SUCCEEDED = 2; + + // Failed to create the glossary. + FAILED = 3; + + // Request is in the process of being canceled after caller invoked + // longrunning.Operations.CancelOperation on the request id. + CANCELLING = 4; + + // The glossary creation request has been successfully canceled. + CANCELLED = 5; + } + + // The name of the glossary that is being created. + string name = 1; + + // The current state of the glossary creation operation. + State state = 2; + + // The time when the operation was submitted to the server. + google.protobuf.Timestamp submit_time = 3; +} + +// Stored in the [google.longrunning.Operation.metadata][google.longrunning.Operation.metadata] field returned by +// DeleteGlossary. +message DeleteGlossaryMetadata { + // Enumerates the possible states that the creation request can be in. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is being processed. + RUNNING = 1; + + // The glossary was successfully deleted. + SUCCEEDED = 2; + + // Failed to delete the glossary. + FAILED = 3; + + // Request is in the process of being canceled after caller invoked + // longrunning.Operations.CancelOperation on the request id. + CANCELLING = 4; + + // The glossary deletion request has been successfully canceled. + CANCELLED = 5; + } + + // The name of the glossary that is being deleted. + string name = 1; + + // The current state of the glossary deletion operation. + State state = 2; + + // The time when the operation was submitted to the server. + google.protobuf.Timestamp submit_time = 3; +} + +// Stored in the [google.longrunning.Operation.response][google.longrunning.Operation.response] field returned by +// DeleteGlossary. +message DeleteGlossaryResponse { + // The name of the deleted glossary. + string name = 1; + + // The time when the operation was submitted to the server. + google.protobuf.Timestamp submit_time = 2; + + // The time when the glossary deletion is finished and + // [google.longrunning.Operation.done][google.longrunning.Operation.done] is set to true. + google.protobuf.Timestamp end_time = 3; +} diff --git a/google/cloud/videointelligence/BUILD.bazel b/google/cloud/videointelligence/BUILD.bazel new file mode 100644 index 000000000..a87c57fec --- /dev/null +++ b/google/cloud/videointelligence/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"])) diff --git a/google/cloud/videointelligence/artman_videointelligence_v1.yaml b/google/cloud/videointelligence/artman_videointelligence_v1.yaml new file mode 100644 index 000000000..7f9520ad5 --- /dev/null +++ b/google/cloud/videointelligence/artman_videointelligence_v1.yaml @@ -0,0 +1,35 @@ +common: + api_name: video-intelligence + api_version: v1 + organization_name: google-cloud + service_yaml: videointelligence_v1.yaml + gapic_yaml: v1/videointelligence_gapic.yaml + src_proto_paths: + - v1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/videointelligence/artman_videointelligence_v1beta1.yaml b/google/cloud/videointelligence/artman_videointelligence_v1beta1.yaml new file mode 100644 index 000000000..2f1f114a6 --- /dev/null +++ b/google/cloud/videointelligence/artman_videointelligence_v1beta1.yaml @@ -0,0 +1,35 @@ +common: + api_name: video-intelligence + api_version: v1beta1 + organization_name: google-cloud + service_yaml: videointelligence_v1beta1.yaml + gapic_yaml: v1beta1/videointelligence_gapic.yaml + src_proto_paths: + - v1beta1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/videointelligence/artman_videointelligence_v1beta2.yaml b/google/cloud/videointelligence/artman_videointelligence_v1beta2.yaml new file mode 100644 index 000000000..32c5a7dba --- /dev/null +++ b/google/cloud/videointelligence/artman_videointelligence_v1beta2.yaml @@ -0,0 +1,35 @@ +common: + api_name: video-intelligence + api_version: v1beta2 + organization_name: google-cloud + service_yaml: videointelligence_v1beta2.yaml + gapic_yaml: v1beta2/videointelligence_gapic.yaml + src_proto_paths: + - v1beta2 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/videointelligence/artman_videointelligence_v1p1beta1.yaml b/google/cloud/videointelligence/artman_videointelligence_v1p1beta1.yaml new file mode 100644 index 000000000..5679b612c --- /dev/null +++ b/google/cloud/videointelligence/artman_videointelligence_v1p1beta1.yaml @@ -0,0 +1,35 @@ +common: + api_name: video-intelligence + api_version: v1p1beta1 + organization_name: google-cloud + service_yaml: videointelligence_v1p1beta1.yaml + gapic_yaml: v1p1beta1/videointelligence_gapic.yaml + src_proto_paths: + - v1p1beta1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/videointelligence/artman_videointelligence_v1p2beta1.yaml b/google/cloud/videointelligence/artman_videointelligence_v1p2beta1.yaml new file mode 100644 index 000000000..3e62e85e3 --- /dev/null +++ b/google/cloud/videointelligence/artman_videointelligence_v1p2beta1.yaml @@ -0,0 +1,35 @@ +common: + api_name: video-intelligence + api_version: v1p2beta1 + organization_name: google-cloud + service_yaml: videointelligence_v1p2beta1.yaml + gapic_yaml: v1p2beta1/videointelligence_gapic.yaml + src_proto_paths: + - v1p2beta1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/videointelligence/artman_videointelligence_v1p3beta1.yaml b/google/cloud/videointelligence/artman_videointelligence_v1p3beta1.yaml new file mode 100644 index 000000000..5a8a2a5bc --- /dev/null +++ b/google/cloud/videointelligence/artman_videointelligence_v1p3beta1.yaml @@ -0,0 +1,35 @@ +common: + api_name: video-intelligence + api_version: v1p3beta1 + organization_name: google-cloud + service_yaml: videointelligence_v1p3beta1.yaml + gapic_yaml: v1p3beta1/videointelligence_gapic.yaml + src_proto_paths: + - v1p3beta1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/videointelligence/v1/BUILD.bazel b/google/cloud/videointelligence/v1/BUILD.bazel new file mode 100644 index 000000000..048f1ed19 --- /dev/null +++ b/google/cloud/videointelligence/v1/BUILD.bazel @@ -0,0 +1,148 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "video_intelligence_proto", + srcs = [ + "video_intelligence.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "video_intelligence_proto_with_info", + deps = [":video_intelligence_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "video_intelligence_java_proto", + deps = [":video_intelligence_proto"], +) + +java_grpc_library( + name = "video_intelligence_java_grpc", + srcs = [":video_intelligence_proto"], + deps = [":video_intelligence_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "video_intelligence_resource_name_java_proto", + gapic_yaml = "videointelligence_gapic.yaml", + deps = [":video_intelligence_proto"], +) + +java_gapic_library( + name = "video_intelligence_java_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1.yaml", + test_deps = [":video_intelligence_java_grpc"], + deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":video_intelligence_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.videointelligence.v1.VideoIntelligenceServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-video-intelligence-v1-java", + client_deps = [":video_intelligence_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":video_intelligence_java_gapic_test"], + grpc_deps = [":video_intelligence_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "video_intelligence_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1", + protos = [":video_intelligence_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "video_intelligence_go_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + importpath = "cloud.google.com/go/videointelligence/apiv1", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1.yaml", + deps = [ + ":video_intelligence_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "video_intelligence_go_gapic_test", + srcs = [":video_intelligence_go_gapic_srcjar_test"], + embed = [":video_intelligence_go_gapic"], + importpath = "cloud.google.com/go/videointelligence/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-video-intelligence-v1-go", + deps = [ + ":video_intelligence_go_gapic", + ":video_intelligence_go_gapic_srcjar-smoke-test.srcjar", + ":video_intelligence_go_gapic_srcjar-test.srcjar", + ":video_intelligence_go_proto", + ], +) diff --git a/google/cloud/videointelligence/v1/video_intelligence.proto b/google/cloud/videointelligence/v1/video_intelligence.proto new file mode 100644 index 000000000..09b51f5d0 --- /dev/null +++ b/google/cloud/videointelligence/v1/video_intelligence.proto @@ -0,0 +1,677 @@ +// Copyright 2018 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.videointelligence.v1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.VideoIntelligence.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1;videointelligence"; +option java_multiple_files = true; +option java_outer_classname = "VideoIntelligenceServiceProto"; +option java_package = "com.google.cloud.videointelligence.v1"; +option php_namespace = "Google\\Cloud\\VideoIntelligence\\V1"; + +// Service that implements Google Cloud Video Intelligence API. +service VideoIntelligenceService { + // Performs asynchronous video annotation. Progress and results can be + // retrieved through the `google.longrunning.Operations` interface. + // `Operation.metadata` contains `AnnotateVideoProgress` (progress). + // `Operation.response` contains `AnnotateVideoResponse` (results). + rpc AnnotateVideo(AnnotateVideoRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/videos:annotate" + body: "*" + }; + } +} + +// Video annotation request. +message AnnotateVideoRequest { + // Input video location. Currently, only + // [Google Cloud Storage](https://cloud.google.com/storage/) URIs are + // supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). A video + // URI may include wildcards in `object-id`, and thus identify multiple + // videos. Supported wildcards: '*' to match 0 or more characters; + // '?' to match 1 character. If unset, the input video should be embedded + // in the request as `input_content`. If set, `input_content` should be unset. + string input_uri = 1; + + // The video data bytes. + // If unset, the input video(s) should be specified via `input_uri`. + // If set, `input_uri` should be unset. + bytes input_content = 6; + + // Requested video annotation features. + repeated Feature features = 2; + + // Additional video context and/or feature-specific parameters. + VideoContext video_context = 3; + + // Optional location where the output (in JSON format) should be stored. + // Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) + // URIs are supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). + string output_uri = 4; + + // Optional cloud region where annotation should take place. Supported cloud + // regions: `us-east1`, `us-west1`, `europe-west1`, `asia-east1`. If no region + // is specified, a region will be determined based on video file location. + string location_id = 5; +} + +// Video context and/or feature-specific parameters. +message VideoContext { + // Video segments to annotate. The segments may overlap and are not required + // to be contiguous or span the whole video. If unspecified, each video is + // treated as a single segment. + repeated VideoSegment segments = 1; + + // Config for LABEL_DETECTION. + LabelDetectionConfig label_detection_config = 2; + + // Config for SHOT_CHANGE_DETECTION. + ShotChangeDetectionConfig shot_change_detection_config = 3; + + // Config for EXPLICIT_CONTENT_DETECTION. + ExplicitContentDetectionConfig explicit_content_detection_config = 4; + + // Config for FACE_DETECTION. + FaceDetectionConfig face_detection_config = 5; + + // Config for SPEECH_TRANSCRIPTION. + SpeechTranscriptionConfig speech_transcription_config = 6; + + // Config for TEXT_DETECTION. + TextDetectionConfig text_detection_config = 8; +} + +// Config for LABEL_DETECTION. +message LabelDetectionConfig { + // What labels should be detected with LABEL_DETECTION, in addition to + // video-level labels or segment-level labels. + // If unspecified, defaults to `SHOT_MODE`. + LabelDetectionMode label_detection_mode = 1; + + // Whether the video has been shot from a stationary (i.e. non-moving) camera. + // When set to true, might improve detection accuracy for moving objects. + // Should be used with `SHOT_AND_FRAME_MODE` enabled. + bool stationary_camera = 2; + + // Model to use for label detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// Config for SHOT_CHANGE_DETECTION. +message ShotChangeDetectionConfig { + // Model to use for shot change detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for EXPLICIT_CONTENT_DETECTION. +message ExplicitContentDetectionConfig { + // Model to use for explicit content detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for FACE_DETECTION. +message FaceDetectionConfig { + // Model to use for face detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; + + // Whether bounding boxes be included in the face annotation output. + bool include_bounding_boxes = 2; +} + +// Config for TEXT_DETECTION. +message TextDetectionConfig { + // Language hint can be specified if the language to be detected is known a + // priori. It can increase the accuracy of the detection. Language hint must + // be language code in BCP-47 format. + // + // Automatic language detection is performed if no hint is provided. + repeated string language_hints = 1; +} + +// Video segment. +message VideoSegment { + // Time-offset, relative to the beginning of the video, + // corresponding to the start of the segment (inclusive). + google.protobuf.Duration start_time_offset = 1; + + // Time-offset, relative to the beginning of the video, + // corresponding to the end of the segment (inclusive). + google.protobuf.Duration end_time_offset = 2; +} + +// Video segment level annotation results for label detection. +message LabelSegment { + // Video segment where a label was detected. + VideoSegment segment = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Video frame level annotation results for label detection. +message LabelFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Detected entity from video analysis. +message Entity { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string entity_id = 1; + + // Textual description, e.g. `Fixed-gear bicycle`. + string description = 2; + + // Language code for `description` in BCP-47 format. + string language_code = 3; +} + +// Label annotation. +message LabelAnnotation { + // Detected entity. + Entity entity = 1; + + // Common categories for the detected entity. + // E.g. when the label is `Terrier` the category is likely `dog`. And in some + // cases there might be more than one categories e.g. `Terrier` could also be + // a `pet`. + repeated Entity category_entities = 2; + + // All video segments where a label was detected. + repeated LabelSegment segments = 3; + + // All video frames where a label was detected. + repeated LabelFrame frames = 4; +} + +// Video frame level annotation results for explicit content. +message ExplicitContentFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Likelihood of the pornography content.. + Likelihood pornography_likelihood = 2; +} + +// Explicit content annotation (based on per-frame visual signals only). +// If no explicit content has been detected in a frame, no annotations are +// present for that frame. +message ExplicitContentAnnotation { + // All video frames where explicit content was detected. + repeated ExplicitContentFrame frames = 1; +} + +// Normalized bounding box. +// The normalized vertex coordinates are relative to the original image. +// Range: [0, 1]. +message NormalizedBoundingBox { + // Left X coordinate. + float left = 1; + + // Top Y coordinate. + float top = 2; + + // Right X coordinate. + float right = 3; + + // Bottom Y coordinate. + float bottom = 4; +} + +// Video segment level annotation results for face detection. +message FaceSegment { + // Video segment where a face was detected. + VideoSegment segment = 1; +} + +// Video frame level annotation results for face detection. +message FaceFrame { + // Normalized Bounding boxes in a frame. + // There can be more than one boxes if the same face is detected in multiple + // locations within the current frame. + repeated NormalizedBoundingBox normalized_bounding_boxes = 1; + + // Time-offset, relative to the beginning of the video, + // corresponding to the video frame for this location. + google.protobuf.Duration time_offset = 2; +} + +// Face annotation. +message FaceAnnotation { + // Thumbnail of a representative face view (in JPEG format). + bytes thumbnail = 1; + + // All video segments where a face was detected. + repeated FaceSegment segments = 2; + + // All video frames where a face was detected. + repeated FaceFrame frames = 3; +} + +// Annotation results for a single video. +message VideoAnnotationResults { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Label annotations on video level or user specified segment level. + // There is exactly one element for each unique label. + repeated LabelAnnotation segment_label_annotations = 2; + + // Label annotations on shot level. + // There is exactly one element for each unique label. + repeated LabelAnnotation shot_label_annotations = 3; + + // Label annotations on frame level. + // There is exactly one element for each unique label. + repeated LabelAnnotation frame_label_annotations = 4; + + // Face annotations. There is exactly one element for each unique face. + repeated FaceAnnotation face_annotations = 5; + + // Shot annotations. Each shot is represented as a video segment. + repeated VideoSegment shot_annotations = 6; + + // Explicit content annotation. + ExplicitContentAnnotation explicit_annotation = 7; + + // Speech transcription. + repeated SpeechTranscription speech_transcriptions = 11; + + // OCR text detection and tracking. + // Annotations for list of detected text snippets. Each will have list of + // frame information associated with it. + repeated TextAnnotation text_annotations = 12; + + // Annotations for list of objects detected and tracked in video. + repeated ObjectTrackingAnnotation object_annotations = 14; + + // If set, indicates an error. Note that for a single `AnnotateVideoRequest` + // some videos may succeed and some may fail. + google.rpc.Status error = 9; +} + +// Video annotation response. Included in the `response` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoResponse { + // Annotation results for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationResults annotation_results = 1; +} + +// Annotation progress for a single video. +message VideoAnnotationProgress { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Approximate percentage processed thus far. Guaranteed to be + // 100 when fully processed. + int32 progress_percent = 2; + + // Time when the request was received. + google.protobuf.Timestamp start_time = 3; + + // Time of the most recent update. + google.protobuf.Timestamp update_time = 4; +} + +// Video annotation progress. Included in the `metadata` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoProgress { + // Progress metadata for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationProgress annotation_progress = 1; +} + +// Config for SPEECH_TRANSCRIPTION. +message SpeechTranscriptionConfig { + // *Required* The language of the supplied audio as a + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. + // Example: "en-US". + // See [Language Support](https://cloud.google.com/speech/docs/languages) + // for a list of the currently supported language codes. + string language_code = 1; + + // *Optional* Maximum number of recognition hypotheses to be returned. + // Specifically, the maximum number of `SpeechRecognitionAlternative` messages + // within each `SpeechTranscription`. The server may return fewer than + // `max_alternatives`. Valid values are `0`-`30`. A value of `0` or `1` will + // return a maximum of one. If omitted, will return a maximum of one. + int32 max_alternatives = 2; + + // *Optional* If set to `true`, the server will attempt to filter out + // profanities, replacing all but the initial character in each filtered word + // with asterisks, e.g. "f***". If set to `false` or omitted, profanities + // won't be filtered out. + bool filter_profanity = 3; + + // *Optional* A means to provide context to assist the speech recognition. + repeated SpeechContext speech_contexts = 4; + + // *Optional* If 'true', adds punctuation to recognition result hypotheses. + // This feature is only available in select languages. Setting this for + // requests in other languages has no effect at all. The default 'false' value + // does not add punctuation to result hypotheses. NOTE: "This is currently + // offered as an experimental service, complimentary to all users. In the + // future this may be exclusively available as a premium feature." + bool enable_automatic_punctuation = 5; + + // *Optional* For file formats, such as MXF or MKV, supporting multiple audio + // tracks, specify up to two tracks. Default: track 0. + repeated int32 audio_tracks = 6; + + // *Optional* If 'true', enables speaker detection for each recognized word in + // the top alternative of the recognition result using a speaker_tag provided + // in the WordInfo. + // Note: When this is true, we send all the words from the beginning of the + // audio for the top alternative in every consecutive responses. + // This is done in order to improve our speaker tags as our models learn to + // identify the speakers in the conversation over time. + bool enable_speaker_diarization = 7; + + // *Optional* + // If set, specifies the estimated number of speakers in the conversation. + // If not set, defaults to '2'. + // Ignored unless enable_speaker_diarization is set to true. + int32 diarization_speaker_count = 8; + + // *Optional* If `true`, the top result includes a list of words and the + // confidence for those words. If `false`, no word-level confidence + // information is returned. The default is `false`. + bool enable_word_confidence = 9; +} + +// Provides "hints" to the speech recognizer to favor specific words and phrases +// in the results. +message SpeechContext { + // *Optional* A list of strings containing words and phrases "hints" so that + // the speech recognition is more likely to recognize them. This can be used + // to improve the accuracy for specific words and phrases, for example, if + // specific commands are typically spoken by the user. This can also be used + // to add additional words to the vocabulary of the recognizer. See + // [usage limits](https://cloud.google.com/speech/limits#content). + repeated string phrases = 1; +} + +// A speech recognition result corresponding to a portion of the audio. +message SpeechTranscription { + // May contain one or more recognition hypotheses (up to the maximum specified + // in `max_alternatives`). These alternatives are ordered in terms of + // accuracy, with the top (first) alternative being the most probable, as + // ranked by the recognizer. + repeated SpeechRecognitionAlternative alternatives = 1; + + // Output only. The + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag of the + // language in this result. This language code was detected to have the most + // likelihood of being spoken in the audio. + string language_code = 2; +} + +// Alternative hypotheses (a.k.a. n-best list). +message SpeechRecognitionAlternative { + // Transcript text representing the words that the user spoke. + string transcript = 1; + + // The confidence estimate between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. This field is typically provided only for the top hypothesis, and + // only for `is_final=true` results. Clients should not rely on the + // `confidence` field as it is not guaranteed to be accurate or consistent. + // The default of 0.0 is a sentinel value indicating `confidence` was not set. + float confidence = 2; + + // A list of word-specific information for each recognized word. + repeated WordInfo words = 3; +} + +// Word-specific information for recognized words. Word information is only +// included in the response when certain request parameters are set, such +// as `enable_word_time_offsets`. +message WordInfo { + // Time offset relative to the beginning of the audio, and + // corresponding to the start of the spoken word. This field is only set if + // `enable_word_time_offsets=true` and only in the top hypothesis. This is an + // experimental feature and the accuracy of the time offset can vary. + google.protobuf.Duration start_time = 1; + + // Time offset relative to the beginning of the audio, and + // corresponding to the end of the spoken word. This field is only set if + // `enable_word_time_offsets=true` and only in the top hypothesis. This is an + // experimental feature and the accuracy of the time offset can vary. + google.protobuf.Duration end_time = 2; + + // The word corresponding to this set of information. + string word = 3; + + // Output only. The confidence estimate between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. This field is set only for the top alternative. + // This field is not guaranteed to be accurate and users should not rely on it + // to be always provided. + // The default of 0.0 is a sentinel value indicating `confidence` was not set. + float confidence = 4; + + // Output only. A distinct integer value is assigned for every speaker within + // the audio. This field specifies which one of those speakers was detected to + // have spoken this word. Value ranges from 1 up to diarization_speaker_count, + // and is only set if speaker diarization is enabled. + int32 speaker_tag = 5; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// Normalized bounding polygon for text (that might not be aligned with axis). +// Contains list of the corner points in clockwise order starting from +// top-left corner. For example, for a rectangular bounding box: +// When the text is horizontal it might look like: +// 0----1 +// | | +// 3----2 +// +// When it's clockwise rotated 180 degrees around the top-left corner it +// becomes: +// 2----3 +// | | +// 1----0 +// +// and the vertex order will still be (0, 1, 2, 3). Note that values can be less +// than 0, or greater than 1 due to trignometric calculations for location of +// the box. +message NormalizedBoundingPoly { + // Normalized vertices of the bounding polygon. + repeated NormalizedVertex vertices = 1; +} + +// Video segment level annotation results for text detection. +message TextSegment { + // Video segment where a text snippet was detected. + VideoSegment segment = 1; + + // Confidence for the track of detected text. It is calculated as the highest + // over all frames where OCR detected text appears. + float confidence = 2; + + // Information related to the frames where OCR detected text appears. + repeated TextFrame frames = 3; +} + +// Video frame level annotation results for text annotation (OCR). +// Contains information regarding timestamp and bounding box locations for the +// frames containing detected OCR text snippets. +message TextFrame { + // Bounding polygon of the detected text for this frame. + NormalizedBoundingPoly rotated_bounding_box = 1; + + // Timestamp of this frame. + google.protobuf.Duration time_offset = 2; +} + +// Annotations related to one detected OCR text snippet. This will contain the +// corresponding text, confidence value, and frame level information for each +// detection. +message TextAnnotation { + // The detected text. + string text = 1; + + // All video segments where OCR detected text appears. + repeated TextSegment segments = 2; +} + +// Video frame level annotations for object detection and tracking. This field +// stores per frame location, time offset, and confidence. +message ObjectTrackingFrame { + // The normalized bounding box location of this object track for the frame. + NormalizedBoundingBox normalized_bounding_box = 1; + + // The timestamp of the frame in microseconds. + google.protobuf.Duration time_offset = 2; +} + +// Annotations corresponding to one tracked object. +message ObjectTrackingAnnotation { + // Different representation of tracking info in non-streaming batch + // and streaming modes. + oneof track_info { + // Non-streaming batch mode ONLY. + // Each object track corresponds to one video segment where it appears. + VideoSegment segment = 3; + + // Streaming mode ONLY. + // In streaming mode, we do not know the end time of a tracked object + // before it is completed. Hence, there is no VideoSegment info returned. + // Instead, we provide a unique identifiable integer track_id so that + // the customers can correlate the results of the ongoing + // ObjectTrackAnnotation of the same track_id over time. + int64 track_id = 5; + } + + // Entity to specify the object category that this track is labeled as. + Entity entity = 1; + + // Object category's labeling confidence of this track. + float confidence = 4; + + // Information corresponding to all frames where this object track appears. + // Non-streaming batch mode: it may be one or multiple ObjectTrackingFrame + // messages in frames. + // Streaming mode: it can only be one ObjectTrackingFrame message in frames. + repeated ObjectTrackingFrame frames = 2; +} + +// Video annotation feature. +enum Feature { + // Unspecified. + FEATURE_UNSPECIFIED = 0; + + // Label detection. Detect objects, such as dog or flower. + LABEL_DETECTION = 1; + + // Shot change detection. + SHOT_CHANGE_DETECTION = 2; + + // Explicit content detection. + EXPLICIT_CONTENT_DETECTION = 3; + + // Human face detection and tracking. + FACE_DETECTION = 4; + + // Speech transcription. + SPEECH_TRANSCRIPTION = 6; + + // OCR text detection and tracking. + TEXT_DETECTION = 7; + + // Object detection and tracking. + OBJECT_TRACKING = 9; +} + +// Label detection mode. +enum LabelDetectionMode { + // Unspecified. + LABEL_DETECTION_MODE_UNSPECIFIED = 0; + + // Detect shot-level labels. + SHOT_MODE = 1; + + // Detect frame-level labels. + FRAME_MODE = 2; + + // Detect both shot-level and frame-level labels. + SHOT_AND_FRAME_MODE = 3; +} + +// Bucketized representation of likelihood. +enum Likelihood { + // Unspecified likelihood. + LIKELIHOOD_UNSPECIFIED = 0; + + // Very unlikely. + VERY_UNLIKELY = 1; + + // Unlikely. + UNLIKELY = 2; + + // Possible. + POSSIBLE = 3; + + // Likely. + LIKELY = 4; + + // Very likely. + VERY_LIKELY = 5; +} diff --git a/google/cloud/videointelligence/v1/videointelligence_gapic.yaml b/google/cloud/videointelligence/v1/videointelligence_gapic.yaml new file mode 100644 index 000000000..9dd80e2ee --- /dev/null +++ b/google/cloud/videointelligence/v1/videointelligence_gapic.yaml @@ -0,0 +1,63 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.videointelligence.v1 + python: + package_name: google.cloud.videointelligence_v1.gapic + go: + package_name: cloud.google.com/go/videointelligence/apiv1 + csharp: + package_name: Google.Cloud.VideoIntelligence.V1 + ruby: + package_name: Google::Cloud::VideoIntelligence::V1 + release_level: GA + php: + package_name: Google\Cloud\VideoIntelligence\V1 + nodejs: + package_name: video-intelligence.v1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.videointelligence.v1.VideoIntelligenceService + smoke_test: + method: AnnotateVideo + init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 1000 + retry_delay_multiplier: 2.5 + max_retry_delay_millis: 120000 + initial_rpc_timeout_millis: 120000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 120000 + total_timeout_millis: 600000 + methods: + - name: AnnotateVideo + flattening: + groups: + - parameters: + - input_uri + - features + long_running: + return_type: google.cloud.videointelligence.v1.AnnotateVideoResponse + metadata_type: google.cloud.videointelligence.v1.AnnotateVideoProgress + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + sample_code_init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION diff --git a/google/cloud/videointelligence/v1beta1/BUILD.bazel b/google/cloud/videointelligence/v1beta1/BUILD.bazel new file mode 100644 index 000000000..245b86eeb --- /dev/null +++ b/google/cloud/videointelligence/v1beta1/BUILD.bazel @@ -0,0 +1,147 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "video_intelligence_proto", + srcs = [ + "video_intelligence.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "video_intelligence_proto_with_info", + deps = [":video_intelligence_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "video_intelligence_java_proto", + deps = [":video_intelligence_proto"], +) + +java_grpc_library( + name = "video_intelligence_java_grpc", + srcs = [":video_intelligence_proto"], + deps = [":video_intelligence_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "video_intelligence_resource_name_java_proto", + gapic_yaml = "videointelligence_gapic.yaml", + deps = [":video_intelligence_proto"], +) + +java_gapic_library( + name = "video_intelligence_java_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1beta1.yaml", + test_deps = [":video_intelligence_java_grpc"], + deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":video_intelligence_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.videointelligence.v1beta1.VideoIntelligenceServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-video-intelligence-v1beta1-java", + client_deps = [":video_intelligence_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":video_intelligence_java_gapic_test"], + grpc_deps = [":video_intelligence_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "video_intelligence_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1beta1", + protos = [":video_intelligence_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "video_intelligence_go_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + importpath = "cloud.google.com/go/videointelligence/apiv1beta1", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1beta1.yaml", + deps = [ + ":video_intelligence_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "video_intelligence_go_gapic_test", + srcs = [":video_intelligence_go_gapic_srcjar_test"], + embed = [":video_intelligence_go_gapic"], + importpath = "cloud.google.com/go/videointelligence/apiv1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-video-intelligence-v1beta1-go", + deps = [ + ":video_intelligence_go_gapic", + ":video_intelligence_go_gapic_srcjar-smoke-test.srcjar", + ":video_intelligence_go_gapic_srcjar-test.srcjar", + ":video_intelligence_go_proto", + ], +) diff --git a/google/cloud/videointelligence/v1beta1/video_intelligence.proto b/google/cloud/videointelligence/v1beta1/video_intelligence.proto new file mode 100644 index 000000000..86b5b800c --- /dev/null +++ b/google/cloud/videointelligence/v1beta1/video_intelligence.proto @@ -0,0 +1,344 @@ +// 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.videointelligence.v1beta1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.VideoIntelligence.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1beta1;videointelligence"; +option java_multiple_files = true; +option java_outer_classname = "VideoIntelligenceServiceProto"; +option java_package = "com.google.cloud.videointelligence.v1beta1"; +option php_namespace = "Google\\Cloud\\VideoIntelligence\\V1beta1"; + +// Service that implements Google Cloud Video Intelligence API. +service VideoIntelligenceService { + // Performs asynchronous video annotation. Progress and results can be + // retrieved through the `google.longrunning.Operations` interface. + // `Operation.metadata` contains `AnnotateVideoProgress` (progress). + // `Operation.response` contains `AnnotateVideoResponse` (results). + rpc AnnotateVideo(AnnotateVideoRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/videos:annotate" + body: "*" + }; + } +} + +// Video annotation request. +message AnnotateVideoRequest { + // Input video location. Currently, only + // [Google Cloud Storage](https://cloud.google.com/storage/) URIs are + // supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). A video + // URI may include wildcards in `object-id`, and thus identify multiple + // videos. Supported wildcards: '*' to match 0 or more characters; + // '?' to match 1 character. If unset, the input video should be embedded + // in the request as `input_content`. If set, `input_content` should be unset. + string input_uri = 1; + + // The video data bytes. Encoding: base64. If unset, the input video(s) + // should be specified via `input_uri`. If set, `input_uri` should be unset. + string input_content = 6; + + // Requested video annotation features. + repeated Feature features = 2; + + // Additional video context and/or feature-specific parameters. + VideoContext video_context = 3; + + // Optional location where the output (in JSON format) should be stored. + // Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) + // URIs are supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). + string output_uri = 4; + + // Optional cloud region where annotation should take place. Supported cloud + // regions: `us-east1`, `us-west1`, `europe-west1`, `asia-east1`. If no region + // is specified, a region will be determined based on video file location. + string location_id = 5; +} + +// Video context and/or feature-specific parameters. +message VideoContext { + // Video segments to annotate. The segments may overlap and are not required + // to be contiguous or span the whole video. If unspecified, each video + // is treated as a single segment. + repeated VideoSegment segments = 1; + + // If label detection has been requested, what labels should be detected + // in addition to video-level labels or segment-level labels. If unspecified, + // defaults to `SHOT_MODE`. + LabelDetectionMode label_detection_mode = 2; + + // Whether the video has been shot from a stationary (i.e. non-moving) camera. + // When set to true, might improve detection accuracy for moving objects. + bool stationary_camera = 3; + + // Model to use for label detection. + // Supported values: "latest" and "stable" (the default). + string label_detection_model = 4; + + // Model to use for face detection. + // Supported values: "latest" and "stable" (the default). + string face_detection_model = 5; + + // Model to use for shot change detection. + // Supported values: "latest" and "stable" (the default). + string shot_change_detection_model = 6; + + // Model to use for safe search detection. + // Supported values: "latest" and "stable" (the default). + string safe_search_detection_model = 7; +} + +// Video segment. +message VideoSegment { + // Start offset in microseconds (inclusive). Unset means 0. + int64 start_time_offset = 1; + + // End offset in microseconds (inclusive). Unset means 0. + int64 end_time_offset = 2; +} + +// Label location. +message LabelLocation { + // Video segment. Set to [-1, -1] for video-level labels. + // Set to [timestamp, timestamp] for frame-level labels. + // Otherwise, corresponds to one of `AnnotateSpec.segments` + // (if specified) or to shot boundaries (if requested). + VideoSegment segment = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; + + // Label level. + LabelLevel level = 3; +} + +// Label annotation. +message LabelAnnotation { + // Textual description, e.g. `Fixed-gear bicycle`. + string description = 1; + + // Language code for `description` in BCP-47 format. + string language_code = 2; + + // Where the label was detected and with what confidence. + repeated LabelLocation locations = 3; +} + +// Safe search annotation (based on per-frame visual signals only). +// If no unsafe content has been detected in a frame, no annotations +// are present for that frame. If only some types of unsafe content +// have been detected in a frame, the likelihood is set to `UNKNOWN` +// for all other types of unsafe content. +message SafeSearchAnnotation { + // Likelihood of adult content. + Likelihood adult = 1; + + // Likelihood that an obvious modification was made to the original + // version to make it appear funny or offensive. + Likelihood spoof = 2; + + // Likelihood of medical content. + Likelihood medical = 3; + + // Likelihood of violent content. + Likelihood violent = 4; + + // Likelihood of racy content. + Likelihood racy = 5; + + // Video time offset in microseconds. + int64 time_offset = 6; +} + +// Bounding box. +message BoundingBox { + // Left X coordinate. + int32 left = 1; + + // Right X coordinate. + int32 right = 2; + + // Bottom Y coordinate. + int32 bottom = 3; + + // Top Y coordinate. + int32 top = 4; +} + +// Face location. +message FaceLocation { + // Bounding box in a frame. + BoundingBox bounding_box = 1; + + // Video time offset in microseconds. + int64 time_offset = 2; +} + +// Face annotation. +message FaceAnnotation { + // Thumbnail of a representative face view (in JPEG format). Encoding: base64. + string thumbnail = 1; + + // All locations where a face was detected. + // Faces are detected and tracked on a per-video basis + // (as opposed to across multiple videos). + repeated VideoSegment segments = 2; + + // Face locations at one frame per second. + repeated FaceLocation locations = 3; +} + +// Annotation results for a single video. +message VideoAnnotationResults { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Label annotations. There is exactly one element for each unique label. + repeated LabelAnnotation label_annotations = 2; + + // Face annotations. There is exactly one element for each unique face. + repeated FaceAnnotation face_annotations = 3; + + // Shot annotations. Each shot is represented as a video segment. + repeated VideoSegment shot_annotations = 4; + + // Safe search annotations. + repeated SafeSearchAnnotation safe_search_annotations = 6; + + // If set, indicates an error. Note that for a single `AnnotateVideoRequest` + // some videos may succeed and some may fail. + google.rpc.Status error = 5; +} + +// Video annotation response. Included in the `response` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoResponse { + // Annotation results for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationResults annotation_results = 1; +} + +// Annotation progress for a single video. +message VideoAnnotationProgress { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Approximate percentage processed thus far. + // Guaranteed to be 100 when fully processed. + int32 progress_percent = 2; + + // Time when the request was received. + google.protobuf.Timestamp start_time = 3; + + // Time of the most recent update. + google.protobuf.Timestamp update_time = 4; +} + +// Video annotation progress. Included in the `metadata` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoProgress { + // Progress metadata for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationProgress annotation_progress = 1; +} + +// Video annotation feature. +enum Feature { + // Unspecified. + FEATURE_UNSPECIFIED = 0; + + // Label detection. Detect objects, such as dog or flower. + LABEL_DETECTION = 1; + + // Human face detection and tracking. + FACE_DETECTION = 2; + + // Shot change detection. + SHOT_CHANGE_DETECTION = 3; + + // Safe search detection. + SAFE_SEARCH_DETECTION = 4; +} + +// Label level (scope). +enum LabelLevel { + // Unspecified. + LABEL_LEVEL_UNSPECIFIED = 0; + + // Video-level. Corresponds to the whole video. + VIDEO_LEVEL = 1; + + // Segment-level. Corresponds to one of `AnnotateSpec.segments`. + SEGMENT_LEVEL = 2; + + // Shot-level. Corresponds to a single shot (i.e. a series of frames + // without a major camera position or background change). + SHOT_LEVEL = 3; + + // Frame-level. Corresponds to a single video frame. + FRAME_LEVEL = 4; +} + +// Label detection mode. +enum LabelDetectionMode { + // Unspecified. + LABEL_DETECTION_MODE_UNSPECIFIED = 0; + + // Detect shot-level labels. + SHOT_MODE = 1; + + // Detect frame-level labels. + FRAME_MODE = 2; + + // Detect both shot-level and frame-level labels. + SHOT_AND_FRAME_MODE = 3; +} + +// Bucketized representation of likelihood. +enum Likelihood { + // Unknown likelihood. + UNKNOWN = 0; + + // Very unlikely. + VERY_UNLIKELY = 1; + + // Unlikely. + UNLIKELY = 2; + + // Possible. + POSSIBLE = 3; + + // Likely. + LIKELY = 4; + + // Very likely. + VERY_LIKELY = 5; +} diff --git a/google/cloud/videointelligence/v1beta1/videointelligence_gapic.yaml b/google/cloud/videointelligence/v1beta1/videointelligence_gapic.yaml new file mode 100644 index 000000000..5c8fd9b32 --- /dev/null +++ b/google/cloud/videointelligence/v1beta1/videointelligence_gapic.yaml @@ -0,0 +1,61 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.videointelligence.v1beta1 + python: + package_name: google.cloud.videointelligence_v1beta1.gapic + go: + package_name: cloud.google.com/go/videointelligence/apiv1beta1 + csharp: + package_name: Google.Cloud.VideoIntelligence.V1Beta1 + ruby: + package_name: Google::Cloud::VideoIntelligence::V1beta1 + release_level: GA + php: + package_name: Google\Cloud\VideoIntelligence\V1beta1 + nodejs: + package_name: videointelligence.v1beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.videointelligence.v1beta1.VideoIntelligenceService + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 1000 + retry_delay_multiplier: 2.5 + max_retry_delay_millis: 120000 + initial_rpc_timeout_millis: 120000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 120000 + total_timeout_millis: 600000 + methods: + - name: AnnotateVideo + flattening: + groups: + - parameters: + - input_uri + - features + long_running: + return_type: google.cloud.videointelligence.v1beta1.AnnotateVideoResponse + metadata_type: google.cloud.videointelligence.v1beta1.AnnotateVideoProgress + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + required_fields: + - input_uri + - features + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + sample_code_init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION diff --git a/google/cloud/videointelligence/v1beta2/BUILD.bazel b/google/cloud/videointelligence/v1beta2/BUILD.bazel new file mode 100644 index 000000000..e664da090 --- /dev/null +++ b/google/cloud/videointelligence/v1beta2/BUILD.bazel @@ -0,0 +1,148 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "video_intelligence_proto", + srcs = [ + "video_intelligence.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "video_intelligence_proto_with_info", + deps = [":video_intelligence_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "video_intelligence_java_proto", + deps = [":video_intelligence_proto"], +) + +java_grpc_library( + name = "video_intelligence_java_grpc", + srcs = [":video_intelligence_proto"], + deps = [":video_intelligence_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "video_intelligence_resource_name_java_proto", + gapic_yaml = "videointelligence_gapic.yaml", + deps = [":video_intelligence_proto"], +) + +java_gapic_library( + name = "video_intelligence_java_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1beta2.yaml", + test_deps = [":video_intelligence_java_grpc"], + deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":video_intelligence_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.videointelligence.v1beta2.VideoIntelligenceServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-video-intelligence-v1beta2-java", + client_deps = [":video_intelligence_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":video_intelligence_java_gapic_test"], + grpc_deps = [":video_intelligence_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "video_intelligence_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1beta2", + protos = [":video_intelligence_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "video_intelligence_go_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + importpath = "cloud.google.com/go/videointelligence/apiv1beta2", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1beta2.yaml", + deps = [ + ":video_intelligence_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "video_intelligence_go_gapic_test", + srcs = [":video_intelligence_go_gapic_srcjar_test"], + embed = [":video_intelligence_go_gapic"], + importpath = "cloud.google.com/go/videointelligence/apiv1beta2", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-video-intelligence-v1beta2-go", + deps = [ + ":video_intelligence_go_gapic", + ":video_intelligence_go_gapic_srcjar-smoke-test.srcjar", + ":video_intelligence_go_gapic_srcjar-test.srcjar", + ":video_intelligence_go_proto", + ], +) diff --git a/google/cloud/videointelligence/v1beta2/video_intelligence.proto b/google/cloud/videointelligence/v1beta2/video_intelligence.proto new file mode 100644 index 000000000..b86664784 --- /dev/null +++ b/google/cloud/videointelligence/v1beta2/video_intelligence.proto @@ -0,0 +1,395 @@ +// 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.videointelligence.v1beta2; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.VideoIntelligence.V1Beta2"; +option go_package = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1beta2;videointelligence"; +option java_multiple_files = true; +option java_outer_classname = "VideoIntelligenceServiceProto"; +option java_package = "com.google.cloud.videointelligence.v1beta2"; +option php_namespace = "Google\\Cloud\\VideoIntelligence\\V1beta2"; + +// Service that implements Google Cloud Video Intelligence API. +service VideoIntelligenceService { + // Performs asynchronous video annotation. Progress and results can be + // retrieved through the `google.longrunning.Operations` interface. + // `Operation.metadata` contains `AnnotateVideoProgress` (progress). + // `Operation.response` contains `AnnotateVideoResponse` (results). + rpc AnnotateVideo(AnnotateVideoRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta2/videos:annotate" + body: "*" + }; + } +} + +// Video annotation request. +message AnnotateVideoRequest { + // Input video location. Currently, only + // [Google Cloud Storage](https://cloud.google.com/storage/) URIs are + // supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). A video + // URI may include wildcards in `object-id`, and thus identify multiple + // videos. Supported wildcards: '*' to match 0 or more characters; + // '?' to match 1 character. If unset, the input video should be embedded + // in the request as `input_content`. If set, `input_content` should be unset. + string input_uri = 1; + + // The video data bytes. + // If unset, the input video(s) should be specified via `input_uri`. + // If set, `input_uri` should be unset. + bytes input_content = 6; + + // Requested video annotation features. + repeated Feature features = 2; + + // Additional video context and/or feature-specific parameters. + VideoContext video_context = 3; + + // Optional location where the output (in JSON format) should be stored. + // Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) + // URIs are supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). + string output_uri = 4; + + // Optional cloud region where annotation should take place. Supported cloud + // regions: `us-east1`, `us-west1`, `europe-west1`, `asia-east1`. If no region + // is specified, a region will be determined based on video file location. + string location_id = 5; +} + +// Video context and/or feature-specific parameters. +message VideoContext { + // Video segments to annotate. The segments may overlap and are not required + // to be contiguous or span the whole video. If unspecified, each video + // is treated as a single segment. + repeated VideoSegment segments = 1; + + // Config for LABEL_DETECTION. + LabelDetectionConfig label_detection_config = 2; + + // Config for SHOT_CHANGE_DETECTION. + ShotChangeDetectionConfig shot_change_detection_config = 3; + + // Config for EXPLICIT_CONTENT_DETECTION. + ExplicitContentDetectionConfig explicit_content_detection_config = 4; + + // Config for FACE_DETECTION. + FaceDetectionConfig face_detection_config = 5; +} + +// Config for LABEL_DETECTION. +message LabelDetectionConfig { + // What labels should be detected with LABEL_DETECTION, in addition to + // video-level labels or segment-level labels. + // If unspecified, defaults to `SHOT_MODE`. + LabelDetectionMode label_detection_mode = 1; + + // Whether the video has been shot from a stationary (i.e. non-moving) camera. + // When set to true, might improve detection accuracy for moving objects. + // Should be used with `SHOT_AND_FRAME_MODE` enabled. + bool stationary_camera = 2; + + // Model to use for label detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// Config for SHOT_CHANGE_DETECTION. +message ShotChangeDetectionConfig { + // Model to use for shot change detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for EXPLICIT_CONTENT_DETECTION. +message ExplicitContentDetectionConfig { + // Model to use for explicit content detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for FACE_DETECTION. +message FaceDetectionConfig { + // Model to use for face detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; + + // Whether bounding boxes be included in the face annotation output. + bool include_bounding_boxes = 2; +} + +// Video segment. +message VideoSegment { + // Time-offset, relative to the beginning of the video, + // corresponding to the start of the segment (inclusive). + google.protobuf.Duration start_time_offset = 1; + + // Time-offset, relative to the beginning of the video, + // corresponding to the end of the segment (inclusive). + google.protobuf.Duration end_time_offset = 2; +} + +// Video segment level annotation results for label detection. +message LabelSegment { + // Video segment where a label was detected. + VideoSegment segment = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Video frame level annotation results for label detection. +message LabelFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Detected entity from video analysis. +message Entity { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string entity_id = 1; + + // Textual description, e.g. `Fixed-gear bicycle`. + string description = 2; + + // Language code for `description` in BCP-47 format. + string language_code = 3; +} + +// Label annotation. +message LabelAnnotation { + // Detected entity. + Entity entity = 1; + + // Common categories for the detected entity. + // E.g. when the label is `Terrier` the category is likely `dog`. And in some + // cases there might be more than one categories e.g. `Terrier` could also be + // a `pet`. + repeated Entity category_entities = 2; + + // All video segments where a label was detected. + repeated LabelSegment segments = 3; + + // All video frames where a label was detected. + repeated LabelFrame frames = 4; +} + +// Video frame level annotation results for explicit content. +message ExplicitContentFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Likelihood of the pornography content.. + Likelihood pornography_likelihood = 2; +} + +// Explicit content annotation (based on per-frame visual signals only). +// If no explicit content has been detected in a frame, no annotations are +// present for that frame. +message ExplicitContentAnnotation { + // All video frames where explicit content was detected. + repeated ExplicitContentFrame frames = 1; +} + +// Normalized bounding box. +// The normalized vertex coordinates are relative to the original image. +// Range: [0, 1]. +message NormalizedBoundingBox { + // Left X coordinate. + float left = 1; + + // Top Y coordinate. + float top = 2; + + // Right X coordinate. + float right = 3; + + // Bottom Y coordinate. + float bottom = 4; +} + +// Video segment level annotation results for face detection. +message FaceSegment { + // Video segment where a face was detected. + VideoSegment segment = 1; +} + +// Video frame level annotation results for face detection. +message FaceFrame { + // Normalized Bounding boxes in a frame. + // There can be more than one boxes if the same face is detected in multiple + // locations within the current frame. + repeated NormalizedBoundingBox normalized_bounding_boxes = 1; + + // Time-offset, relative to the beginning of the video, + // corresponding to the video frame for this location. + google.protobuf.Duration time_offset = 2; +} + +// Face annotation. +message FaceAnnotation { + // Thumbnail of a representative face view (in JPEG format). + bytes thumbnail = 1; + + // All video segments where a face was detected. + repeated FaceSegment segments = 2; + + // All video frames where a face was detected. + repeated FaceFrame frames = 3; +} + +// Annotation results for a single video. +message VideoAnnotationResults { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Label annotations on video level or user specified segment level. + // There is exactly one element for each unique label. + repeated LabelAnnotation segment_label_annotations = 2; + + // Label annotations on shot level. + // There is exactly one element for each unique label. + repeated LabelAnnotation shot_label_annotations = 3; + + // Label annotations on frame level. + // There is exactly one element for each unique label. + repeated LabelAnnotation frame_label_annotations = 4; + + // Face annotations. There is exactly one element for each unique face. + repeated FaceAnnotation face_annotations = 5; + + // Shot annotations. Each shot is represented as a video segment. + repeated VideoSegment shot_annotations = 6; + + // Explicit content annotation. + ExplicitContentAnnotation explicit_annotation = 7; + + // If set, indicates an error. Note that for a single `AnnotateVideoRequest` + // some videos may succeed and some may fail. + google.rpc.Status error = 9; +} + +// Video annotation response. Included in the `response` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoResponse { + // Annotation results for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationResults annotation_results = 1; +} + +// Annotation progress for a single video. +message VideoAnnotationProgress { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Approximate percentage processed thus far. + // Guaranteed to be 100 when fully processed. + int32 progress_percent = 2; + + // Time when the request was received. + google.protobuf.Timestamp start_time = 3; + + // Time of the most recent update. + google.protobuf.Timestamp update_time = 4; +} + +// Video annotation progress. Included in the `metadata` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoProgress { + // Progress metadata for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationProgress annotation_progress = 1; +} + +// Video annotation feature. +enum Feature { + // Unspecified. + FEATURE_UNSPECIFIED = 0; + + // Label detection. Detect objects, such as dog or flower. + LABEL_DETECTION = 1; + + // Shot change detection. + SHOT_CHANGE_DETECTION = 2; + + // Explicit content detection. + EXPLICIT_CONTENT_DETECTION = 3; + + // Human face detection and tracking. + FACE_DETECTION = 4; +} + +// Label detection mode. +enum LabelDetectionMode { + // Unspecified. + LABEL_DETECTION_MODE_UNSPECIFIED = 0; + + // Detect shot-level labels. + SHOT_MODE = 1; + + // Detect frame-level labels. + FRAME_MODE = 2; + + // Detect both shot-level and frame-level labels. + SHOT_AND_FRAME_MODE = 3; +} + +// Bucketized representation of likelihood. +enum Likelihood { + // Unspecified likelihood. + LIKELIHOOD_UNSPECIFIED = 0; + + // Very unlikely. + VERY_UNLIKELY = 1; + + // Unlikely. + UNLIKELY = 2; + + // Possible. + POSSIBLE = 3; + + // Likely. + LIKELY = 4; + + // Very likely. + VERY_LIKELY = 5; +} diff --git a/google/cloud/videointelligence/v1beta2/videointelligence_gapic.yaml b/google/cloud/videointelligence/v1beta2/videointelligence_gapic.yaml new file mode 100644 index 000000000..4ebcbe4d1 --- /dev/null +++ b/google/cloud/videointelligence/v1beta2/videointelligence_gapic.yaml @@ -0,0 +1,58 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.videointelligence.v1beta2 + python: + package_name: google.cloud.videointelligence_v1beta2.gapic + go: + package_name: cloud.google.com/go/videointelligence/apiv1beta2 + csharp: + package_name: Google.Cloud.VideoIntelligence.V1Beta2 + ruby: + package_name: Google::Cloud::VideoIntelligence::V1beta2 + release_level: GA + php: + package_name: Google\Cloud\VideoIntelligence\V1beta2 + nodejs: + package_name: video-intelligence.v1beta2 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.videointelligence.v1beta2.VideoIntelligenceService + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 1000 + retry_delay_multiplier: 2.5 + max_retry_delay_millis: 120000 + initial_rpc_timeout_millis: 120000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 120000 + total_timeout_millis: 600000 + methods: + - name: AnnotateVideo + flattening: + groups: + - parameters: + - input_uri + - features + long_running: + return_type: google.cloud.videointelligence.v1beta2.AnnotateVideoResponse + metadata_type: google.cloud.videointelligence.v1beta2.AnnotateVideoProgress + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + sample_code_init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION diff --git a/google/cloud/videointelligence/v1p1beta1/BUILD.bazel b/google/cloud/videointelligence/v1p1beta1/BUILD.bazel new file mode 100644 index 000000000..8e29f7b04 --- /dev/null +++ b/google/cloud/videointelligence/v1p1beta1/BUILD.bazel @@ -0,0 +1,148 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "video_intelligence_proto", + srcs = [ + "video_intelligence.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "video_intelligence_proto_with_info", + deps = [":video_intelligence_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "video_intelligence_java_proto", + deps = [":video_intelligence_proto"], +) + +java_grpc_library( + name = "video_intelligence_java_grpc", + srcs = [":video_intelligence_proto"], + deps = [":video_intelligence_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "video_intelligence_resource_name_java_proto", + gapic_yaml = "videointelligence_gapic.yaml", + deps = [":video_intelligence_proto"], +) + +java_gapic_library( + name = "video_intelligence_java_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1p1beta1.yaml", + test_deps = [":video_intelligence_java_grpc"], + deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":video_intelligence_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.videointelligence.v1p1beta1.VideoIntelligenceServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-video-intelligence-v1p1beta1-java", + client_deps = [":video_intelligence_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":video_intelligence_java_gapic_test"], + grpc_deps = [":video_intelligence_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "video_intelligence_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1p1beta1", + protos = [":video_intelligence_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "video_intelligence_go_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + importpath = "cloud.google.com/go/videointelligence/apiv1p1beta1", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1p1beta1.yaml", + deps = [ + ":video_intelligence_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "video_intelligence_go_gapic_test", + srcs = [":video_intelligence_go_gapic_srcjar_test"], + embed = [":video_intelligence_go_gapic"], + importpath = "cloud.google.com/go/videointelligence/apiv1p1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-video-intelligence-v1p1beta1-go", + deps = [ + ":video_intelligence_go_gapic", + ":video_intelligence_go_gapic_srcjar-smoke-test.srcjar", + ":video_intelligence_go_gapic_srcjar-test.srcjar", + ":video_intelligence_go_proto", + ], +) diff --git a/google/cloud/videointelligence/v1p1beta1/video_intelligence.proto b/google/cloud/videointelligence/v1p1beta1/video_intelligence.proto new file mode 100644 index 000000000..626cc35b8 --- /dev/null +++ b/google/cloud/videointelligence/v1p1beta1/video_intelligence.proto @@ -0,0 +1,433 @@ +// Copyright 2018 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.videointelligence.v1p1beta1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.VideoIntelligence.V1P1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1p1beta1;videointelligence"; +option java_multiple_files = true; +option java_outer_classname = "VideoIntelligenceServiceProto"; +option java_package = "com.google.cloud.videointelligence.v1p1beta1"; +option php_namespace = "Google\\Cloud\\VideoIntelligence\\V1p1beta1"; + +// Service that implements Google Cloud Video Intelligence API. +service VideoIntelligenceService { + // Performs asynchronous video annotation. Progress and results can be + // retrieved through the `google.longrunning.Operations` interface. + // `Operation.metadata` contains `AnnotateVideoProgress` (progress). + // `Operation.response` contains `AnnotateVideoResponse` (results). + rpc AnnotateVideo(AnnotateVideoRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p1beta1/videos:annotate" + body: "*" + }; + } +} + +// Video annotation request. +message AnnotateVideoRequest { + // Input video location. Currently, only + // [Google Cloud Storage](https://cloud.google.com/storage/) URIs are + // supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). A video + // URI may include wildcards in `object-id`, and thus identify multiple + // videos. Supported wildcards: '*' to match 0 or more characters; + // '?' to match 1 character. If unset, the input video should be embedded + // in the request as `input_content`. If set, `input_content` should be unset. + string input_uri = 1; + + // The video data bytes. + // If unset, the input video(s) should be specified via `input_uri`. + // If set, `input_uri` should be unset. + bytes input_content = 6; + + // Requested video annotation features. + repeated Feature features = 2; + + // Additional video context and/or feature-specific parameters. + VideoContext video_context = 3; + + // Optional location where the output (in JSON format) should be stored. + // Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) + // URIs are supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). + string output_uri = 4; + + // Optional cloud region where annotation should take place. Supported cloud + // regions: `us-east1`, `us-west1`, `europe-west1`, `asia-east1`. If no region + // is specified, a region will be determined based on video file location. + string location_id = 5; +} + +// Video context and/or feature-specific parameters. +message VideoContext { + // Video segments to annotate. The segments may overlap and are not required + // to be contiguous or span the whole video. If unspecified, each video is + // treated as a single segment. + repeated VideoSegment segments = 1; + + // Config for LABEL_DETECTION. + LabelDetectionConfig label_detection_config = 2; + + // Config for SHOT_CHANGE_DETECTION. + ShotChangeDetectionConfig shot_change_detection_config = 3; + + // Config for EXPLICIT_CONTENT_DETECTION. + ExplicitContentDetectionConfig explicit_content_detection_config = 4; + + // Config for SPEECH_TRANSCRIPTION. + SpeechTranscriptionConfig speech_transcription_config = 6; +} + +// Config for LABEL_DETECTION. +message LabelDetectionConfig { + // What labels should be detected with LABEL_DETECTION, in addition to + // video-level labels or segment-level labels. + // If unspecified, defaults to `SHOT_MODE`. + LabelDetectionMode label_detection_mode = 1; + + // Whether the video has been shot from a stationary (i.e. non-moving) camera. + // When set to true, might improve detection accuracy for moving objects. + // Should be used with `SHOT_AND_FRAME_MODE` enabled. + bool stationary_camera = 2; + + // Model to use for label detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// Config for SHOT_CHANGE_DETECTION. +message ShotChangeDetectionConfig { + // Model to use for shot change detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for EXPLICIT_CONTENT_DETECTION. +message ExplicitContentDetectionConfig { + // Model to use for explicit content detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Video segment. +message VideoSegment { + // Time-offset, relative to the beginning of the video, + // corresponding to the start of the segment (inclusive). + google.protobuf.Duration start_time_offset = 1; + + // Time-offset, relative to the beginning of the video, + // corresponding to the end of the segment (inclusive). + google.protobuf.Duration end_time_offset = 2; +} + +// Video segment level annotation results for label detection. +message LabelSegment { + // Video segment where a label was detected. + VideoSegment segment = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Video frame level annotation results for label detection. +message LabelFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Detected entity from video analysis. +message Entity { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string entity_id = 1; + + // Textual description, e.g. `Fixed-gear bicycle`. + string description = 2; + + // Language code for `description` in BCP-47 format. + string language_code = 3; +} + +// Label annotation. +message LabelAnnotation { + // Detected entity. + Entity entity = 1; + + // Common categories for the detected entity. + // E.g. when the label is `Terrier` the category is likely `dog`. And in some + // cases there might be more than one categories e.g. `Terrier` could also be + // a `pet`. + repeated Entity category_entities = 2; + + // All video segments where a label was detected. + repeated LabelSegment segments = 3; + + // All video frames where a label was detected. + repeated LabelFrame frames = 4; +} + +// Video frame level annotation results for explicit content. +message ExplicitContentFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Likelihood of the pornography content.. + Likelihood pornography_likelihood = 2; +} + +// Explicit content annotation (based on per-frame visual signals only). +// If no explicit content has been detected in a frame, no annotations are +// present for that frame. +message ExplicitContentAnnotation { + // All video frames where explicit content was detected. + repeated ExplicitContentFrame frames = 1; +} + +// Annotation results for a single video. +message VideoAnnotationResults { + // Output only. Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Label annotations on video level or user specified segment level. + // There is exactly one element for each unique label. + repeated LabelAnnotation segment_label_annotations = 2; + + // Label annotations on shot level. + // There is exactly one element for each unique label. + repeated LabelAnnotation shot_label_annotations = 3; + + // Label annotations on frame level. + // There is exactly one element for each unique label. + repeated LabelAnnotation frame_label_annotations = 4; + + // Shot annotations. Each shot is represented as a video segment. + repeated VideoSegment shot_annotations = 6; + + // Explicit content annotation. + ExplicitContentAnnotation explicit_annotation = 7; + + // Speech transcription. + repeated SpeechTranscription speech_transcriptions = 11; + + // Output only. If set, indicates an error. Note that for a single + // `AnnotateVideoRequest` some videos may succeed and some may fail. + google.rpc.Status error = 9; +} + +// Video annotation response. Included in the `response` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoResponse { + // Annotation results for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationResults annotation_results = 1; +} + +// Annotation progress for a single video. +message VideoAnnotationProgress { + // Output only. Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Output only. Approximate percentage processed thus far. Guaranteed to be + // 100 when fully processed. + int32 progress_percent = 2; + + // Output only. Time when the request was received. + google.protobuf.Timestamp start_time = 3; + + // Output only. Time of the most recent update. + google.protobuf.Timestamp update_time = 4; +} + +// Video annotation progress. Included in the `metadata` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoProgress { + // Progress metadata for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationProgress annotation_progress = 1; +} + +// Config for SPEECH_TRANSCRIPTION. +message SpeechTranscriptionConfig { + // *Required* The language of the supplied audio as a + // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. + // Example: "en-US". + // See [Language Support](https://cloud.google.com/speech/docs/languages) + // for a list of the currently supported language codes. + string language_code = 1; + + // *Optional* Maximum number of recognition hypotheses to be returned. + // Specifically, the maximum number of `SpeechRecognitionAlternative` messages + // within each `SpeechRecognitionResult`. The server may return fewer than + // `max_alternatives`. Valid values are `0`-`30`. A value of `0` or `1` will + // return a maximum of one. If omitted, will return a maximum of one. + int32 max_alternatives = 2; + + // *Optional* If set to `true`, the server will attempt to filter out + // profanities, replacing all but the initial character in each filtered word + // with asterisks, e.g. "f***". If set to `false` or omitted, profanities + // won't be filtered out. + bool filter_profanity = 3; + + // *Optional* A means to provide context to assist the speech recognition. + repeated SpeechContext speech_contexts = 4; + + // *Optional* If 'true', adds punctuation to recognition result hypotheses. + // This feature is only available in select languages. Setting this for + // requests in other languages has no effect at all. The default 'false' value + // does not add punctuation to result hypotheses. NOTE: "This is currently + // offered as an experimental service, complimentary to all users. In the + // future this may be exclusively available as a premium feature." + bool enable_automatic_punctuation = 5; + + // *Optional* For file formats, such as MXF or MKV, supporting multiple audio + // tracks, specify up to two tracks. Default: track 0. + repeated int32 audio_tracks = 6; +} + +// Provides "hints" to the speech recognizer to favor specific words and phrases +// in the results. +message SpeechContext { + // *Optional* A list of strings containing words and phrases "hints" so that + // the speech recognition is more likely to recognize them. This can be used + // to improve the accuracy for specific words and phrases, for example, if + // specific commands are typically spoken by the user. This can also be used + // to add additional words to the vocabulary of the recognizer. See + // [usage limits](https://cloud.google.com/speech/limits#content). + repeated string phrases = 1; +} + +// A speech recognition result corresponding to a portion of the audio. +message SpeechTranscription { + // Output only. May contain one or more recognition hypotheses (up to the + // maximum specified in `max_alternatives`). + // These alternatives are ordered in terms of accuracy, with the top (first) + // alternative being the most probable, as ranked by the recognizer. + repeated SpeechRecognitionAlternative alternatives = 1; +} + +// Alternative hypotheses (a.k.a. n-best list). +message SpeechRecognitionAlternative { + // Output only. Transcript text representing the words that the user spoke. + string transcript = 1; + + // Output only. The confidence estimate between 0.0 and 1.0. A higher number + // indicates an estimated greater likelihood that the recognized words are + // correct. This field is typically provided only for the top hypothesis, and + // only for `is_final=true` results. Clients should not rely on the + // `confidence` field as it is not guaranteed to be accurate or consistent. + // The default of 0.0 is a sentinel value indicating `confidence` was not set. + float confidence = 2; + + // Output only. A list of word-specific information for each recognized word. + repeated WordInfo words = 3; +} + +// Word-specific information for recognized words. Word information is only +// included in the response when certain request parameters are set, such +// as `enable_word_time_offsets`. +message WordInfo { + // Output only. Time offset relative to the beginning of the audio, and + // corresponding to the start of the spoken word. This field is only set if + // `enable_word_time_offsets=true` and only in the top hypothesis. This is an + // experimental feature and the accuracy of the time offset can vary. + google.protobuf.Duration start_time = 1; + + // Output only. Time offset relative to the beginning of the audio, and + // corresponding to the end of the spoken word. This field is only set if + // `enable_word_time_offsets=true` and only in the top hypothesis. This is an + // experimental feature and the accuracy of the time offset can vary. + google.protobuf.Duration end_time = 2; + + // Output only. The word corresponding to this set of information. + string word = 3; +} + +// Video annotation feature. +enum Feature { + // Unspecified. + FEATURE_UNSPECIFIED = 0; + + // Label detection. Detect objects, such as dog or flower. + LABEL_DETECTION = 1; + + // Shot change detection. + SHOT_CHANGE_DETECTION = 2; + + // Explicit content detection. + EXPLICIT_CONTENT_DETECTION = 3; + + // Speech transcription. + SPEECH_TRANSCRIPTION = 6; +} + +// Label detection mode. +enum LabelDetectionMode { + // Unspecified. + LABEL_DETECTION_MODE_UNSPECIFIED = 0; + + // Detect shot-level labels. + SHOT_MODE = 1; + + // Detect frame-level labels. + FRAME_MODE = 2; + + // Detect both shot-level and frame-level labels. + SHOT_AND_FRAME_MODE = 3; +} + +// Bucketized representation of likelihood. +enum Likelihood { + // Unspecified likelihood. + LIKELIHOOD_UNSPECIFIED = 0; + + // Very unlikely. + VERY_UNLIKELY = 1; + + // Unlikely. + UNLIKELY = 2; + + // Possible. + POSSIBLE = 3; + + // Likely. + LIKELY = 4; + + // Very likely. + VERY_LIKELY = 5; +} diff --git a/google/cloud/videointelligence/v1p1beta1/videointelligence_gapic.yaml b/google/cloud/videointelligence/v1p1beta1/videointelligence_gapic.yaml new file mode 100644 index 000000000..8c7498eb5 --- /dev/null +++ b/google/cloud/videointelligence/v1p1beta1/videointelligence_gapic.yaml @@ -0,0 +1,63 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.videointelligence.v1p1beta1 + python: + package_name: google.cloud.videointelligence_v1p1beta1.gapic + go: + package_name: cloud.google.com/go/videointelligence/apiv1p1beta1 + csharp: + package_name: Google.Cloud.VideoIntelligence.V1P1Beta1 + ruby: + package_name: Google::Cloud::VideoIntelligence::V1p1beta1 + release_level: BETA + php: + package_name: Google\Cloud\VideoIntelligence\V1p1beta1 + nodejs: + package_name: video-intelligence.v1p1beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.videointelligence.v1p1beta1.VideoIntelligenceService + smoke_test: + method: AnnotateVideo + init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 1000 + retry_delay_multiplier: 2.5 + max_retry_delay_millis: 120000 + initial_rpc_timeout_millis: 120000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 120000 + total_timeout_millis: 600000 + methods: + - name: AnnotateVideo + flattening: + groups: + - parameters: + - input_uri + - features + long_running: + return_type: google.cloud.videointelligence.v1p1beta1.AnnotateVideoResponse + metadata_type: google.cloud.videointelligence.v1p1beta1.AnnotateVideoProgress + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + sample_code_init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION diff --git a/google/cloud/videointelligence/v1p2beta1/BUILD.bazel b/google/cloud/videointelligence/v1p2beta1/BUILD.bazel new file mode 100644 index 000000000..39e66417b --- /dev/null +++ b/google/cloud/videointelligence/v1p2beta1/BUILD.bazel @@ -0,0 +1,148 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "video_intelligence_proto", + srcs = [ + "video_intelligence.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "video_intelligence_proto_with_info", + deps = [":video_intelligence_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "video_intelligence_java_proto", + deps = [":video_intelligence_proto"], +) + +java_grpc_library( + name = "video_intelligence_java_grpc", + srcs = [":video_intelligence_proto"], + deps = [":video_intelligence_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "video_intelligence_resource_name_java_proto", + gapic_yaml = "videointelligence_gapic.yaml", + deps = [":video_intelligence_proto"], +) + +java_gapic_library( + name = "video_intelligence_java_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1p2beta1.yaml", + test_deps = [":video_intelligence_java_grpc"], + deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":video_intelligence_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.videointelligence.v1p2beta1.VideoIntelligenceServiceClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-video-intelligence-v1p2beta1-java", + client_deps = [":video_intelligence_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":video_intelligence_java_gapic_test"], + grpc_deps = [":video_intelligence_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":video_intelligence_java_proto", + ":video_intelligence_proto", + ":video_intelligence_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "video_intelligence_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1p2beta1", + protos = [":video_intelligence_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "video_intelligence_go_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + importpath = "cloud.google.com/go/videointelligence/apiv1p2beta1", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1p2beta1.yaml", + deps = [ + ":video_intelligence_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "video_intelligence_go_gapic_test", + srcs = [":video_intelligence_go_gapic_srcjar_test"], + embed = [":video_intelligence_go_gapic"], + importpath = "cloud.google.com/go/videointelligence/apiv1p2beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-video-intelligence-v1p2beta1-go", + deps = [ + ":video_intelligence_go_gapic", + ":video_intelligence_go_gapic_srcjar-smoke-test.srcjar", + ":video_intelligence_go_gapic_srcjar-test.srcjar", + ":video_intelligence_go_proto", + ], +) diff --git a/google/cloud/videointelligence/v1p2beta1/video_intelligence.proto b/google/cloud/videointelligence/v1p2beta1/video_intelligence.proto new file mode 100644 index 000000000..b1318167e --- /dev/null +++ b/google/cloud/videointelligence/v1p2beta1/video_intelligence.proto @@ -0,0 +1,466 @@ +// Copyright 2018 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.videointelligence.v1p2beta1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.VideoIntelligence.V1P2Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1p2beta1;videointelligence"; +option java_multiple_files = true; +option java_outer_classname = "VideoIntelligenceServiceProto"; +option java_package = "com.google.cloud.videointelligence.v1p2beta1"; +option php_namespace = "Google\\Cloud\\VideoIntelligence\\V1p2beta1"; + +// Service that implements Google Cloud Video Intelligence API. +service VideoIntelligenceService { + // Performs asynchronous video annotation. Progress and results can be + // retrieved through the `google.longrunning.Operations` interface. + // `Operation.metadata` contains `AnnotateVideoProgress` (progress). + // `Operation.response` contains `AnnotateVideoResponse` (results). + rpc AnnotateVideo(AnnotateVideoRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p2beta1/videos:annotate" + body: "*" + }; + } +} + +// Video annotation request. +message AnnotateVideoRequest { + // Input video location. Currently, only + // [Google Cloud Storage](https://cloud.google.com/storage/) URIs are + // supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). A video + // URI may include wildcards in `object-id`, and thus identify multiple + // videos. Supported wildcards: '*' to match 0 or more characters; + // '?' to match 1 character. If unset, the input video should be embedded + // in the request as `input_content`. If set, `input_content` should be unset. + string input_uri = 1; + + // The video data bytes. + // If unset, the input video(s) should be specified via `input_uri`. + // If set, `input_uri` should be unset. + bytes input_content = 6; + + // Requested video annotation features. + repeated Feature features = 2; + + // Additional video context and/or feature-specific parameters. + VideoContext video_context = 3; + + // Optional location where the output (in JSON format) should be stored. + // Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) + // URIs are supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). + string output_uri = 4; + + // Optional cloud region where annotation should take place. Supported cloud + // regions: `us-east1`, `us-west1`, `europe-west1`, `asia-east1`. If no region + // is specified, a region will be determined based on video file location. + string location_id = 5; +} + +// Video context and/or feature-specific parameters. +message VideoContext { + // Video segments to annotate. The segments may overlap and are not required + // to be contiguous or span the whole video. If unspecified, each video is + // treated as a single segment. + repeated VideoSegment segments = 1; + + // Config for LABEL_DETECTION. + LabelDetectionConfig label_detection_config = 2; + + // Config for SHOT_CHANGE_DETECTION. + ShotChangeDetectionConfig shot_change_detection_config = 3; + + // Config for EXPLICIT_CONTENT_DETECTION. + ExplicitContentDetectionConfig explicit_content_detection_config = 4; + + // Config for TEXT_DETECTION. + TextDetectionConfig text_detection_config = 8; +} + +// Config for LABEL_DETECTION. +message LabelDetectionConfig { + // What labels should be detected with LABEL_DETECTION, in addition to + // video-level labels or segment-level labels. + // If unspecified, defaults to `SHOT_MODE`. + LabelDetectionMode label_detection_mode = 1; + + // Whether the video has been shot from a stationary (i.e. non-moving) camera. + // When set to true, might improve detection accuracy for moving objects. + // Should be used with `SHOT_AND_FRAME_MODE` enabled. + bool stationary_camera = 2; + + // Model to use for label detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// Config for SHOT_CHANGE_DETECTION. +message ShotChangeDetectionConfig { + // Model to use for shot change detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for EXPLICIT_CONTENT_DETECTION. +message ExplicitContentDetectionConfig { + // Model to use for explicit content detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for TEXT_DETECTION. +message TextDetectionConfig { + // Language hint can be specified if the language to be detected is known a + // priori. It can increase the accuracy of the detection. Language hint must + // be language code in BCP-47 format. + // + // Automatic language detection is performed if no hint is provided. + repeated string language_hints = 1; +} + +// Video segment. +message VideoSegment { + // Time-offset, relative to the beginning of the video, + // corresponding to the start of the segment (inclusive). + google.protobuf.Duration start_time_offset = 1; + + // Time-offset, relative to the beginning of the video, + // corresponding to the end of the segment (inclusive). + google.protobuf.Duration end_time_offset = 2; +} + +// Video segment level annotation results for label detection. +message LabelSegment { + // Video segment where a label was detected. + VideoSegment segment = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Video frame level annotation results for label detection. +message LabelFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Detected entity from video analysis. +message Entity { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string entity_id = 1; + + // Textual description, e.g. `Fixed-gear bicycle`. + string description = 2; + + // Language code for `description` in BCP-47 format. + string language_code = 3; +} + +// Label annotation. +message LabelAnnotation { + // Detected entity. + Entity entity = 1; + + // Common categories for the detected entity. + // E.g. when the label is `Terrier` the category is likely `dog`. And in some + // cases there might be more than one categories e.g. `Terrier` could also be + // a `pet`. + repeated Entity category_entities = 2; + + // All video segments where a label was detected. + repeated LabelSegment segments = 3; + + // All video frames where a label was detected. + repeated LabelFrame frames = 4; +} + +// Video frame level annotation results for explicit content. +message ExplicitContentFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Likelihood of the pornography content.. + Likelihood pornography_likelihood = 2; +} + +// Explicit content annotation (based on per-frame visual signals only). +// If no explicit content has been detected in a frame, no annotations are +// present for that frame. +message ExplicitContentAnnotation { + // All video frames where explicit content was detected. + repeated ExplicitContentFrame frames = 1; +} + +// Normalized bounding box. +// The normalized vertex coordinates are relative to the original image. +// Range: [0, 1]. +message NormalizedBoundingBox { + // Left X coordinate. + float left = 1; + + // Top Y coordinate. + float top = 2; + + // Right X coordinate. + float right = 3; + + // Bottom Y coordinate. + float bottom = 4; +} + +// Annotation results for a single video. +message VideoAnnotationResults { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Label annotations on video level or user specified segment level. + // There is exactly one element for each unique label. + repeated LabelAnnotation segment_label_annotations = 2; + + // Label annotations on shot level. + // There is exactly one element for each unique label. + repeated LabelAnnotation shot_label_annotations = 3; + + // Label annotations on frame level. + // There is exactly one element for each unique label. + repeated LabelAnnotation frame_label_annotations = 4; + + // Shot annotations. Each shot is represented as a video segment. + repeated VideoSegment shot_annotations = 6; + + // Explicit content annotation. + ExplicitContentAnnotation explicit_annotation = 7; + + // OCR text detection and tracking. + // Annotations for list of detected text snippets. Each will have list of + // frame information associated with it. + repeated TextAnnotation text_annotations = 12; + + // Annotations for list of objects detected and tracked in video. + repeated ObjectTrackingAnnotation object_annotations = 14; + + // If set, indicates an error. Note that for a single `AnnotateVideoRequest` + // some videos may succeed and some may fail. + google.rpc.Status error = 9; +} + +// Video annotation response. Included in the `response` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoResponse { + // Annotation results for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationResults annotation_results = 1; +} + +// Annotation progress for a single video. +message VideoAnnotationProgress { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Approximate percentage processed thus far. Guaranteed to be + // 100 when fully processed. + int32 progress_percent = 2; + + // Time when the request was received. + google.protobuf.Timestamp start_time = 3; + + // Time of the most recent update. + google.protobuf.Timestamp update_time = 4; +} + +// Video annotation progress. Included in the `metadata` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoProgress { + // Progress metadata for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationProgress annotation_progress = 1; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// Normalized bounding polygon for text (that might not be aligned with axis). +// Contains list of the corner points in clockwise order starting from +// top-left corner. For example, for a rectangular bounding box: +// When the text is horizontal it might look like: +// 0----1 +// | | +// 3----2 +// +// When it's clockwise rotated 180 degrees around the top-left corner it +// becomes: +// 2----3 +// | | +// 1----0 +// +// and the vertex order will still be (0, 1, 2, 3). Note that values can be less +// than 0, or greater than 1 due to trignometric calculations for location of +// the box. +message NormalizedBoundingPoly { + // Normalized vertices of the bounding polygon. + repeated NormalizedVertex vertices = 1; +} + +// Video segment level annotation results for text detection. +message TextSegment { + // Video segment where a text snippet was detected. + VideoSegment segment = 1; + + // Confidence for the track of detected text. It is calculated as the highest + // over all frames where OCR detected text appears. + float confidence = 2; + + // Information related to the frames where OCR detected text appears. + repeated TextFrame frames = 3; +} + +// Video frame level annotation results for text annotation (OCR). +// Contains information regarding timestamp and bounding box locations for the +// frames containing detected OCR text snippets. +message TextFrame { + // Bounding polygon of the detected text for this frame. + NormalizedBoundingPoly rotated_bounding_box = 1; + + // Timestamp of this frame. + google.protobuf.Duration time_offset = 2; +} + +// Annotations related to one detected OCR text snippet. This will contain the +// corresponding text, confidence value, and frame level information for each +// detection. +message TextAnnotation { + // The detected text. + string text = 1; + + // All video segments where OCR detected text appears. + repeated TextSegment segments = 2; +} + +// Video frame level annotations for object detection and tracking. This field +// stores per frame location, time offset, and confidence. +message ObjectTrackingFrame { + // The normalized bounding box location of this object track for the frame. + NormalizedBoundingBox normalized_bounding_box = 1; + + // The timestamp of the frame in microseconds. + google.protobuf.Duration time_offset = 2; +} + +// Annotations corresponding to one tracked object. +message ObjectTrackingAnnotation { + // Entity to specify the object category that this track is labeled as. + Entity entity = 1; + + // Object category's labeling confidence of this track. + float confidence = 4; + + // Information corresponding to all frames where this object track appears. + repeated ObjectTrackingFrame frames = 2; + + // Each object track corresponds to one video segment where it appears. + VideoSegment segment = 3; +} + +// Video annotation feature. +enum Feature { + // Unspecified. + FEATURE_UNSPECIFIED = 0; + + // Label detection. Detect objects, such as dog or flower. + LABEL_DETECTION = 1; + + // Shot change detection. + SHOT_CHANGE_DETECTION = 2; + + // Explicit content detection. + EXPLICIT_CONTENT_DETECTION = 3; + + // OCR text detection and tracking. + TEXT_DETECTION = 7; + + // Object detection and tracking. + OBJECT_TRACKING = 9; +} + +// Label detection mode. +enum LabelDetectionMode { + // Unspecified. + LABEL_DETECTION_MODE_UNSPECIFIED = 0; + + // Detect shot-level labels. + SHOT_MODE = 1; + + // Detect frame-level labels. + FRAME_MODE = 2; + + // Detect both shot-level and frame-level labels. + SHOT_AND_FRAME_MODE = 3; +} + +// Bucketized representation of likelihood. +enum Likelihood { + // Unspecified likelihood. + LIKELIHOOD_UNSPECIFIED = 0; + + // Very unlikely. + VERY_UNLIKELY = 1; + + // Unlikely. + UNLIKELY = 2; + + // Possible. + POSSIBLE = 3; + + // Likely. + LIKELY = 4; + + // Very likely. + VERY_LIKELY = 5; +} diff --git a/google/cloud/videointelligence/v1p2beta1/videointelligence_gapic.yaml b/google/cloud/videointelligence/v1p2beta1/videointelligence_gapic.yaml new file mode 100644 index 000000000..37ddb03c1 --- /dev/null +++ b/google/cloud/videointelligence/v1p2beta1/videointelligence_gapic.yaml @@ -0,0 +1,63 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.videointelligence.v1p2beta1 + python: + package_name: google.cloud.videointelligence_v1p2beta1.gapic + go: + package_name: cloud.google.com/go/videointelligence/apiv1p2beta1 + csharp: + package_name: Google.Cloud.VideoIntelligence.V1P2Beta1 + ruby: + package_name: Google::Cloud::VideoIntelligence::V1p2beta1 + release_level: BETA + php: + package_name: Google\Cloud\VideoIntelligence\V1p2beta1 + nodejs: + package_name: video-intelligence.v1p2beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.videointelligence.v1p2beta1.VideoIntelligenceService + smoke_test: + method: AnnotateVideo + init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 1000 + retry_delay_multiplier: 2.5 + max_retry_delay_millis: 120000 + initial_rpc_timeout_millis: 120000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 120000 + total_timeout_millis: 600000 + methods: + - name: AnnotateVideo + flattening: + groups: + - parameters: + - input_uri + - features + long_running: + return_type: google.cloud.videointelligence.v1p2beta1.AnnotateVideoResponse + metadata_type: google.cloud.videointelligence.v1p2beta1.AnnotateVideoProgress + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + sample_code_init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION diff --git a/google/cloud/videointelligence/v1p3beta1/BUILD.bazel b/google/cloud/videointelligence/v1p3beta1/BUILD.bazel new file mode 100644 index 000000000..881665f94 --- /dev/null +++ b/google/cloud/videointelligence/v1p3beta1/BUILD.bazel @@ -0,0 +1,149 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "video_intelligence_proto", + srcs = [ + "video_intelligence.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "video_intelligence_proto_with_info", + deps = [":video_intelligence_proto"], +) + +# TODO: uncomment once https://github.com/googleapis/gapic-generator/issues/1149 is fixed +############################################################################## +# Java +############################################################################## +#load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +#load( +# "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", +# "java_gapic_library", +# "java_resource_name_proto_library", +#) +#load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") +# +#_JAVA_GRPC_DEPS = [ +# "@com_google_api_grpc_proto_google_common_protos//jar", +#] +# +#java_proto_library( +# name = "video_intelligence_java_proto", +# deps = [":video_intelligence_proto"], +#) +# +#java_grpc_library( +# name = "video_intelligence_java_grpc", +# srcs = [":video_intelligence_proto"], +# deps = [":video_intelligence_java_proto"] + _JAVA_GRPC_DEPS, +#) +# +#java_resource_name_proto_library( +# name = "video_intelligence_resource_name_java_proto", +# gapic_yaml = "videointelligence_gapic.yaml", +# deps = [":video_intelligence_proto"], +#) +# +#java_gapic_library( +# name = "video_intelligence_java_gapic", +# src = ":video_intelligence_proto_with_info", +# gapic_yaml = "videointelligence_gapic.yaml", +# service_yaml = "//google/cloud/videointelligence:videointelligence_v1p3beta1.yaml", +# test_deps = [":video_intelligence_java_grpc"], +# deps = [ +# ":video_intelligence_java_proto", +# ":video_intelligence_resource_name_java_proto", +# ] + _JAVA_GRPC_DEPS, +#) +# +#[java_test( +# name = test_name, +# test_class = test_name, +# runtime_deps = [ +# ":video_intelligence_java_gapic_test", +# ], +#) for test_name in [ +# "com.google.cloud.videointelligence.v1p3beta1.VideoIntelligenceServiceClientTest", +#]] + +## Opensource Packages +#java_gapic_assembly_gradle_pkg( +# name = "google-cloud-video-intelligence-v1p3beta1-java", +# client_deps = [":video_intelligence_java_gapic"], +# client_group = "com.google.cloud", +# client_test_deps = [":video_intelligence_java_gapic_test"], +# grpc_deps = [":video_intelligence_java_grpc"], +# grpc_group = "com.google.api.grpc", +# proto_deps = [ +# ":video_intelligence_java_proto", +# ":video_intelligence_proto", +# ":video_intelligence_resource_name_java_proto", +# ] + _JAVA_GRPC_DEPS, +# version = "0.0.0-SNAPSHOT", +#) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "video_intelligence_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1p3beta1", + protos = [":video_intelligence_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + ], +) + +go_gapic_library( + name = "video_intelligence_go_gapic", + src = ":video_intelligence_proto_with_info", + gapic_yaml = "videointelligence_gapic.yaml", + importpath = "cloud.google.com/go/videointelligence/apiv1p3beta1", + service_yaml = "//google/cloud/videointelligence:videointelligence_v1p3beta1.yaml", + deps = [ + ":video_intelligence_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "video_intelligence_go_gapic_test", + srcs = [":video_intelligence_go_gapic_srcjar_test"], + embed = [":video_intelligence_go_gapic"], + importpath = "cloud.google.com/go/videointelligence/apiv1p3beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-video-intelligence-v1p3beta1-go", + deps = [ + ":video_intelligence_go_gapic", + ":video_intelligence_go_gapic_srcjar-smoke-test.srcjar", + ":video_intelligence_go_gapic_srcjar-test.srcjar", + ":video_intelligence_go_proto", + ], +) diff --git a/google/cloud/videointelligence/v1p3beta1/video_intelligence.proto b/google/cloud/videointelligence/v1p3beta1/video_intelligence.proto new file mode 100644 index 000000000..dc65a651e --- /dev/null +++ b/google/cloud/videointelligence/v1p3beta1/video_intelligence.proto @@ -0,0 +1,627 @@ +// Copyright 2018 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.videointelligence.v1p3beta1; + +import "google/api/annotations.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.VideoIntelligence.V1P3Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/videointelligence/v1p3beta1;videointelligence"; +option java_multiple_files = true; +option java_outer_classname = "VideoIntelligenceServiceProto"; +option java_package = "com.google.cloud.videointelligence.v1p3beta1"; +option php_namespace = "Google\\Cloud\\VideoIntelligence\\V1p3beta1"; + +// Service that implements Google Cloud Video Intelligence API. +service VideoIntelligenceService { + // Performs asynchronous video annotation. Progress and results can be + // retrieved through the `google.longrunning.Operations` interface. + // `Operation.metadata` contains `AnnotateVideoProgress` (progress). + // `Operation.response` contains `AnnotateVideoResponse` (results). + rpc AnnotateVideo(AnnotateVideoRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p3beta1/videos:annotate" + body: "*" + }; + } +} + +// Service that implements Google Cloud Video Intelligence Streaming API. +service StreamingVideoIntelligenceService { + // Performs video annotation with bidirectional streaming: emitting results + // while sending video/audio bytes. + // This method is only available via the gRPC API (not REST). + rpc StreamingAnnotateVideo(stream StreamingAnnotateVideoRequest) + returns (stream StreamingAnnotateVideoResponse); +} + +// Video annotation request. +message AnnotateVideoRequest { + // Input video location. Currently, only + // [Google Cloud Storage](https://cloud.google.com/storage/) URIs are + // supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). A video + // URI may include wildcards in `object-id`, and thus identify multiple + // videos. Supported wildcards: '*' to match 0 or more characters; + // '?' to match 1 character. If unset, the input video should be embedded + // in the request as `input_content`. If set, `input_content` should be unset. + string input_uri = 1; + + // The video data bytes. + // If unset, the input video(s) should be specified via `input_uri`. + // If set, `input_uri` should be unset. + bytes input_content = 6; + + // Requested video annotation features. + repeated Feature features = 2; + + // Additional video context and/or feature-specific parameters. + VideoContext video_context = 3; + + // Optional location where the output (in JSON format) should be stored. + // Currently, only [Google Cloud Storage](https://cloud.google.com/storage/) + // URIs are supported, which must be specified in the following format: + // `gs://bucket-id/object-id` (other URI formats return + // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For + // more information, see [Request URIs](/storage/docs/reference-uris). + string output_uri = 4; + + // Optional cloud region where annotation should take place. Supported cloud + // regions: `us-east1`, `us-west1`, `europe-west1`, `asia-east1`. If no region + // is specified, a region will be determined based on video file location. + string location_id = 5; +} + +// Video context and/or feature-specific parameters. +message VideoContext { + // Video segments to annotate. The segments may overlap and are not required + // to be contiguous or span the whole video. If unspecified, each video is + // treated as a single segment. + repeated VideoSegment segments = 1; + + // Config for LABEL_DETECTION. + LabelDetectionConfig label_detection_config = 2; + + // Config for SHOT_CHANGE_DETECTION. + ShotChangeDetectionConfig shot_change_detection_config = 3; + + // Config for EXPLICIT_CONTENT_DETECTION. + ExplicitContentDetectionConfig explicit_content_detection_config = 4; + + // Config for TEXT_DETECTION. + TextDetectionConfig text_detection_config = 8; +} + +// Config for LABEL_DETECTION. +message LabelDetectionConfig { + // What labels should be detected with LABEL_DETECTION, in addition to + // video-level labels or segment-level labels. + // If unspecified, defaults to `SHOT_MODE`. + LabelDetectionMode label_detection_mode = 1; + + // Whether the video has been shot from a stationary (i.e. non-moving) camera. + // When set to true, might improve detection accuracy for moving objects. + // Should be used with `SHOT_AND_FRAME_MODE` enabled. + bool stationary_camera = 2; + + // Model to use for label detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// Config for SHOT_CHANGE_DETECTION. +message ShotChangeDetectionConfig { + // Model to use for shot change detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for EXPLICIT_CONTENT_DETECTION. +message ExplicitContentDetectionConfig { + // Model to use for explicit content detection. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 1; +} + +// Config for TEXT_DETECTION. +message TextDetectionConfig { + // Language hint can be specified if the language to be detected is known a + // priori. It can increase the accuracy of the detection. Language hint must + // be language code in BCP-47 format. + // + // Automatic language detection is performed if no hint is provided. + repeated string language_hints = 1; +} + +// Video segment. +message VideoSegment { + // Time-offset, relative to the beginning of the video, + // corresponding to the start of the segment (inclusive). + google.protobuf.Duration start_time_offset = 1; + + // Time-offset, relative to the beginning of the video, + // corresponding to the end of the segment (inclusive). + google.protobuf.Duration end_time_offset = 2; +} + +// Video segment level annotation results for label detection. +message LabelSegment { + // Video segment where a label was detected. + VideoSegment segment = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Video frame level annotation results for label detection. +message LabelFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Confidence that the label is accurate. Range: [0, 1]. + float confidence = 2; +} + +// Detected entity from video analysis. +message Entity { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string entity_id = 1; + + // Textual description, e.g. `Fixed-gear bicycle`. + string description = 2; + + // Language code for `description` in BCP-47 format. + string language_code = 3; +} + +// Label annotation. +message LabelAnnotation { + // Detected entity. + Entity entity = 1; + + // Common categories for the detected entity. + // E.g. when the label is `Terrier` the category is likely `dog`. And in some + // cases there might be more than one categories e.g. `Terrier` could also be + // a `pet`. + repeated Entity category_entities = 2; + + // All video segments where a label was detected. + repeated LabelSegment segments = 3; + + // All video frames where a label was detected. + repeated LabelFrame frames = 4; +} + +// Video frame level annotation results for explicit content. +message ExplicitContentFrame { + // Time-offset, relative to the beginning of the video, corresponding to the + // video frame for this location. + google.protobuf.Duration time_offset = 1; + + // Likelihood of the pornography content.. + Likelihood pornography_likelihood = 2; +} + +// Explicit content annotation (based on per-frame visual signals only). +// If no explicit content has been detected in a frame, no annotations are +// present for that frame. +message ExplicitContentAnnotation { + // All video frames where explicit content was detected. + repeated ExplicitContentFrame frames = 1; +} + +// Normalized bounding box. +// The normalized vertex coordinates are relative to the original image. +// Range: [0, 1]. +message NormalizedBoundingBox { + // Left X coordinate. + float left = 1; + + // Top Y coordinate. + float top = 2; + + // Right X coordinate. + float right = 3; + + // Bottom Y coordinate. + float bottom = 4; +} + +// Annotation results for a single video. +message VideoAnnotationResults { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Label annotations on video level or user specified segment level. + // There is exactly one element for each unique label. + repeated LabelAnnotation segment_label_annotations = 2; + + // Label annotations on shot level. + // There is exactly one element for each unique label. + repeated LabelAnnotation shot_label_annotations = 3; + + // Label annotations on frame level. + // There is exactly one element for each unique label. + repeated LabelAnnotation frame_label_annotations = 4; + + // Shot annotations. Each shot is represented as a video segment. + repeated VideoSegment shot_annotations = 6; + + // Explicit content annotation. + ExplicitContentAnnotation explicit_annotation = 7; + + // OCR text detection and tracking. + // Annotations for list of detected text snippets. Each will have list of + // frame information associated with it. + repeated TextAnnotation text_annotations = 12; + + // Annotations for list of objects detected and tracked in video. + repeated ObjectTrackingAnnotation object_annotations = 14; + + // If set, indicates an error. Note that for a single `AnnotateVideoRequest` + // some videos may succeed and some may fail. + google.rpc.Status error = 9; +} + +// Video annotation response. Included in the `response` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoResponse { + // Annotation results for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationResults annotation_results = 1; +} + +// Annotation progress for a single video. +message VideoAnnotationProgress { + // Video file location in + // [Google Cloud Storage](https://cloud.google.com/storage/). + string input_uri = 1; + + // Approximate percentage processed thus far. Guaranteed to be + // 100 when fully processed. + int32 progress_percent = 2; + + // Time when the request was received. + google.protobuf.Timestamp start_time = 3; + + // Time of the most recent update. + google.protobuf.Timestamp update_time = 4; +} + +// Video annotation progress. Included in the `metadata` +// field of the `Operation` returned by the `GetOperation` +// call of the `google::longrunning::Operations` service. +message AnnotateVideoProgress { + // Progress metadata for all videos specified in `AnnotateVideoRequest`. + repeated VideoAnnotationProgress annotation_progress = 1; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// Normalized bounding polygon for text (that might not be aligned with axis). +// Contains list of the corner points in clockwise order starting from +// top-left corner. For example, for a rectangular bounding box: +// When the text is horizontal it might look like: +// 0----1 +// | | +// 3----2 +// +// When it's clockwise rotated 180 degrees around the top-left corner it +// becomes: +// 2----3 +// | | +// 1----0 +// +// and the vertex order will still be (0, 1, 2, 3). Note that values can be less +// than 0, or greater than 1 due to trignometric calculations for location of +// the box. +message NormalizedBoundingPoly { + // Normalized vertices of the bounding polygon. + repeated NormalizedVertex vertices = 1; +} + +// Video segment level annotation results for text detection. +message TextSegment { + // Video segment where a text snippet was detected. + VideoSegment segment = 1; + + // Confidence for the track of detected text. It is calculated as the highest + // over all frames where OCR detected text appears. + float confidence = 2; + + // Information related to the frames where OCR detected text appears. + repeated TextFrame frames = 3; +} + +// Video frame level annotation results for text annotation (OCR). +// Contains information regarding timestamp and bounding box locations for the +// frames containing detected OCR text snippets. +message TextFrame { + // Bounding polygon of the detected text for this frame. + NormalizedBoundingPoly rotated_bounding_box = 1; + + // Timestamp of this frame. + google.protobuf.Duration time_offset = 2; +} + +// Annotations related to one detected OCR text snippet. This will contain the +// corresponding text, confidence value, and frame level information for each +// detection. +message TextAnnotation { + // The detected text. + string text = 1; + + // All video segments where OCR detected text appears. + repeated TextSegment segments = 2; +} + +// Video frame level annotations for object detection and tracking. This field +// stores per frame location, time offset, and confidence. +message ObjectTrackingFrame { + // The normalized bounding box location of this object track for the frame. + NormalizedBoundingBox normalized_bounding_box = 1; + + // The timestamp of the frame in microseconds. + google.protobuf.Duration time_offset = 2; +} + +// Annotations corresponding to one tracked object. +message ObjectTrackingAnnotation { + // Entity to specify the object category that this track is labeled as. + Entity entity = 1; + + // Object category's labeling confidence of this track. + float confidence = 4; + + // Information corresponding to all frames where this object track appears. + // Non-streaming batch mode: it may be one or multiple ObjectTrackingFrame + // messages in frames. + // Streaming mode: it can only be one ObjectTrackingFrame message in frames. + repeated ObjectTrackingFrame frames = 2; + + // Different representation of tracking info in non-streaming batch + // and streaming modes. + oneof track_info { + // Non-streaming batch mode ONLY. + // Each object track corresponds to one video segment where it appears. + VideoSegment segment = 3; + // Streaming mode ONLY. + // In streaming mode, we do not know the end time of a tracked object + // before it is completed. Hence, there is no VideoSegment info returned. + // Instead, we provide a unique identifiable integer track_id so that + // the customers can correlate the results of the ongoing + // ObjectTrackAnnotation of the same track_id over time. + int64 track_id = 5; + } +} + +// The top-level message sent by the client for the `StreamingAnnotateVideo` +// method. Multiple `StreamingAnnotateVideoRequest` messages are sent. +// The first message must only contain a `StreamingVideoConfig` message. +// All subsequent messages must only contain `input_content` data. +message StreamingAnnotateVideoRequest { + // *Required* The streaming request, which is either a streaming config or + // video content. + oneof streaming_request { + // Provides information to the annotator, specifing how to process the + // request. The first `AnnotateStreamingVideoRequest` message must only + // contain a `video_config` message. + StreamingVideoConfig video_config = 1; + + // The video data to be annotated. Chunks of video data are sequentially + // sent in `StreamingAnnotateVideoRequest` messages. Except the initial + // `StreamingAnnotateVideoRequest` message containing only + // `video_config`, all subsequent `AnnotateStreamingVideoRequest` + // messages must only contain `input_content` field. + bytes input_content = 2; + } +} + +// `StreamingAnnotateVideoResponse` is the only message returned to the client +// by `StreamingAnnotateVideo`. A series of zero or more +// `StreamingAnnotateVideoResponse` messages are streamed back to the client. +message StreamingAnnotateVideoResponse { + // If set, returns a [google.rpc.Status][] message that + // specifies the error for the operation. + google.rpc.Status error = 1; + + // Streaming annotation results. + StreamingVideoAnnotationResults annotation_results = 2; + + // GCS URI that stores annotation results of one streaming session. + // It is a directory that can hold multiple files in JSON format. + // Example uri format: + // gs://bucket_id/object_id/cloud_project_name-session_id + string annotation_results_uri = 3; +} + +// Config for EXPLICIT_CONTENT_DETECTION in streaming mode. +message StreamingExplicitContentDetectionConfig { + // No customized config support. +} + +// Config for LABEL_DETECTION in streaming mode. +message StreamingLabelDetectionConfig { + // Whether the video has been captured from a stationary (i.e. non-moving) + // camera. When set to true, might improve detection accuracy for moving + // objects. Default: false. + bool stationary_camera = 1; +} + +// Config for STREAMING_OBJECT_TRACKING. +message StreamingObjectTrackingConfig { + // No customized config support. +} + +// Config for SHOT_CHANGE_DETECTION in streaming mode. +message StreamingShotChangeDetectionConfig { + // No customized config support. +} + +// Config for streaming storage option. +message StreamingStorageConfig { + // Enable streaming storage. Default: false. + bool enable_storage_annotation_result = 1; + + // GCS URI to store all annotation results for one client. Client should + // specify this field as the top-level storage directory. Annotation results + // of different sessions will be put into different sub-directories denoted + // by project_name and session_id. All sub-directories will be auto generated + // by program and will be made accessible to client in response proto. + // URIs must be specified in the following format: `gs://bucket-id/object-id` + // `bucket-id` should be a valid GCS bucket created by client and bucket + // permission shall also be configured properly. `object-id` can be arbitrary + // string that make sense to client. Other URI formats will return error and + // cause GCS write failure. + string annotation_result_storage_directory = 3; +} + +// Streaming annotation results corresponding to a portion of the video +// that is currently being processed. +message StreamingVideoAnnotationResults { + // Shot annotation results. Each shot is represented as a video segment. + repeated VideoSegment shot_annotations = 1; + + // Label annotation results. + repeated LabelAnnotation label_annotations = 2; + + // Explicit content detection results. + ExplicitContentAnnotation explicit_annotation = 3; + + // Object tracking results. + repeated ObjectTrackingAnnotation object_annotations = 4; +} + +// Provides information to the annotator that specifies how to process the +// request. +message StreamingVideoConfig { + // Requested annotation feature. + StreamingFeature feature = 1; + + // Config for requested annotation feature. + oneof streaming_config { + // Config for SHOT_CHANGE_DETECTION. + StreamingShotChangeDetectionConfig shot_change_detection_config = 2; + + // Config for LABEL_DETECTION. + StreamingLabelDetectionConfig label_detection_config = 3; + + // Config for STREAMING_EXPLICIT_CONTENT_DETECTION. + StreamingExplicitContentDetectionConfig explicit_content_detection_config = + 4; + + // Config for STREAMING_OBJECT_TRACKING. + StreamingObjectTrackingConfig object_tracking_config = 5; + } + + // Streaming storage option. By default: storage is disabled. + StreamingStorageConfig storage_config = 30; +} + +// Video annotation feature. +enum Feature { + // Unspecified. + FEATURE_UNSPECIFIED = 0; + + // Label detection. Detect objects, such as dog or flower. + LABEL_DETECTION = 1; + + // Shot change detection. + SHOT_CHANGE_DETECTION = 2; + + // Explicit content detection. + EXPLICIT_CONTENT_DETECTION = 3; + + // OCR text detection and tracking. + TEXT_DETECTION = 7; + + // Object detection and tracking. + OBJECT_TRACKING = 9; +} + +// Label detection mode. +enum LabelDetectionMode { + // Unspecified. + LABEL_DETECTION_MODE_UNSPECIFIED = 0; + + // Detect shot-level labels. + SHOT_MODE = 1; + + // Detect frame-level labels. + FRAME_MODE = 2; + + // Detect both shot-level and frame-level labels. + SHOT_AND_FRAME_MODE = 3; +} + +// Bucketized representation of likelihood. +enum Likelihood { + // Unspecified likelihood. + LIKELIHOOD_UNSPECIFIED = 0; + + // Very unlikely. + VERY_UNLIKELY = 1; + + // Unlikely. + UNLIKELY = 2; + + // Possible. + POSSIBLE = 3; + + // Likely. + LIKELY = 4; + + // Very likely. + VERY_LIKELY = 5; +} + +// Streaming video annotation feature. +enum StreamingFeature { + // Unspecified. + STREAMING_FEATURE_UNSPECIFIED = 0; + // Label detection. Detect objects, such as dog or flower. + STREAMING_LABEL_DETECTION = 1; + // Shot change detection. + STREAMING_SHOT_CHANGE_DETECTION = 2; + // Explicit content detection. + STREAMING_EXPLICIT_CONTENT_DETECTION = 3; + // Object detection and tracking. + STREAMING_OBJECT_TRACKING = 4; +} diff --git a/google/cloud/videointelligence/v1p3beta1/videointelligence_gapic.yaml b/google/cloud/videointelligence/v1p3beta1/videointelligence_gapic.yaml new file mode 100644 index 000000000..c3d95af40 --- /dev/null +++ b/google/cloud/videointelligence/v1p3beta1/videointelligence_gapic.yaml @@ -0,0 +1,91 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.videointelligence.v1p3beta1 + python: + package_name: google.cloud.videointelligence_v1p3beta1.gapic + go: + package_name: cloud.google.com/go/videointelligence/apiv1p3beta1 + csharp: + package_name: Google.Cloud.VideoIntelligence.V1P3Beta1 + ruby: + package_name: Google::Cloud::VideoIntelligence::V1p3beta1 + release_level: BETA + php: + package_name: Google\Cloud\VideoIntelligence\V1p3beta1 + nodejs: + package_name: video-intelligence.v1p3beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.videointelligence.v1p3beta1.VideoIntelligenceService + smoke_test: + method: AnnotateVideo + init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 1000 + retry_delay_multiplier: 2.5 + max_retry_delay_millis: 120000 + initial_rpc_timeout_millis: 120000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 120000 + total_timeout_millis: 600000 + methods: + - name: AnnotateVideo + flattening: + groups: + - parameters: + - input_uri + - features + long_running: + return_type: google.cloud.videointelligence.v1p3beta1.AnnotateVideoResponse + metadata_type: google.cloud.videointelligence.v1p3beta1.AnnotateVideoProgress + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + sample_code_init_fields: + - input_uri=gs://demomaker/cat.mp4 + - features[0]=LABEL_DETECTION +# TODO: This config is currently broken: +# https://github.com/googleapis/gapic-generator/issues/1057 +# https://github.com/googleapis/gapic-generator/issues/1149 +- name: google.cloud.videointelligence.v1p3beta1.StreamingVideoIntelligenceService + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 10800000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 10800000 + total_timeout_millis: 10800000 + methods: + - name: StreamingAnnotateVideo + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 10800000 diff --git a/google/cloud/videointelligence/videointelligence_v1.yaml b/google/cloud/videointelligence/videointelligence_v1.yaml new file mode 100644 index 000000000..4de2fb6ad --- /dev/null +++ b/google/cloud/videointelligence/videointelligence_v1.yaml @@ -0,0 +1,52 @@ +type: google.api.Service +config_version: 3 +name: videointelligence.googleapis.com +title: Cloud Video Intelligence API + +apis: +- name: google.cloud.videointelligence.v1.VideoIntelligenceService + +types: +- name: google.cloud.videointelligence.v1.AnnotateVideoResponse +- name: google.cloud.videointelligence.v1.AnnotateVideoProgress +- name: google.cloud.videointelligence.v1.VideoSegment +- name: google.rpc.Status + +documentation: + summary: Cloud Video Intelligence API. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 600.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 600.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 600.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 600.0 + - selector: google.cloud.videointelligence.v1.VideoIntelligenceService.AnnotateVideo + deadline: 600.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: /v1/operations + + - selector: google.longrunning.Operations.GetOperation + get: '/v1/operations/{name=*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/operations/{name=*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/operations/{name=*}:cancel' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/videointelligence/videointelligence_v1beta1.yaml b/google/cloud/videointelligence/videointelligence_v1beta1.yaml new file mode 100644 index 000000000..62e1227a9 --- /dev/null +++ b/google/cloud/videointelligence/videointelligence_v1beta1.yaml @@ -0,0 +1,35 @@ +type: google.api.Service +config_version: 3 +name: videointelligence.googleapis.com +title: Google Cloud Video Intelligence API + +apis: +- name: google.cloud.videointelligence.v1beta1.VideoIntelligenceService + +documentation: + summary: + Google Cloud Video Intelligence API. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: https://www.googleapis.com/auth/cloud-platform + +types: +- name: google.cloud.videointelligence.v1beta1.AnnotateVideoResponse +- name: google.cloud.videointelligence.v1beta1.AnnotateVideoProgress +- name: google.cloud.videointelligence.v1beta1.VideoSegment +- name: google.rpc.Status + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1/operations/{name=*}' + - selector: google.longrunning.Operations.ListOperations + get: '/v1/operations' + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/operations/{name=*}:cancel' + body: '*' + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/operations/{name=*}' diff --git a/google/cloud/videointelligence/videointelligence_v1beta2.yaml b/google/cloud/videointelligence/videointelligence_v1beta2.yaml new file mode 100644 index 000000000..37918a95f --- /dev/null +++ b/google/cloud/videointelligence/videointelligence_v1beta2.yaml @@ -0,0 +1,37 @@ +type: google.api.Service +config_version: 3 +name: videointelligence.googleapis.com +title: Google Cloud Video Intelligence API + +apis: +- name: google.cloud.videointelligence.v1beta2.VideoIntelligenceService + +documentation: + summary: + Google Cloud Video Intelligence API. + +authentication: + rules: + - selector: '*' + allow_without_credential: true + oauth: + canonical_scopes: https://www.googleapis.com/auth/cloud-platform + +types: +- name: google.cloud.videointelligence.v1beta2.AnnotateVideoResponse +- name: google.cloud.videointelligence.v1beta2.AnnotateVideoProgress +- name: google.cloud.videointelligence.v1beta2.VideoSegment +- name: google.rpc.Status + +# HTTP overrides. +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1/operations/{name=*}' + - selector: google.longrunning.Operations.ListOperations + get: '/v1/operations' + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/operations/{name=*}:cancel' + body: '*' + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/operations/{name=*}' diff --git a/google/cloud/videointelligence/videointelligence_v1p1beta1.yaml b/google/cloud/videointelligence/videointelligence_v1p1beta1.yaml new file mode 100644 index 000000000..1e0caadbb --- /dev/null +++ b/google/cloud/videointelligence/videointelligence_v1p1beta1.yaml @@ -0,0 +1,52 @@ +type: google.api.Service +config_version: 3 +name: videointelligence.googleapis.com +title: Cloud Video Intelligence API + +apis: +- name: google.cloud.videointelligence.v1p1beta1.VideoIntelligenceService + +types: +- name: google.cloud.videointelligence.v1p1beta1.AnnotateVideoResponse +- name: google.cloud.videointelligence.v1p1beta1.AnnotateVideoProgress +- name: google.cloud.videointelligence.v1p1beta1.VideoSegment +- name: google.rpc.Status + +documentation: + summary: Cloud Video Intelligence API. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 600.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 600.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 600.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 600.0 + - selector: google.cloud.videointelligence.v1p1beta1.VideoIntelligenceService.AnnotateVideo + deadline: 600.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: /v1p1beta1/operations + + - selector: google.longrunning.Operations.GetOperation + get: '/v1p1beta1/operations/{name=*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1p1beta1/operations/{name=*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1p1beta1/operations/{name=*}:cancel' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/videointelligence/videointelligence_v1p2beta1.yaml b/google/cloud/videointelligence/videointelligence_v1p2beta1.yaml new file mode 100644 index 000000000..df5da4297 --- /dev/null +++ b/google/cloud/videointelligence/videointelligence_v1p2beta1.yaml @@ -0,0 +1,52 @@ +type: google.api.Service +config_version: 3 +name: videointelligence.googleapis.com +title: Cloud Video Intelligence API + +apis: +- name: google.cloud.videointelligence.v1p2beta1.VideoIntelligenceService + +types: +- name: google.cloud.videointelligence.v1p2beta1.AnnotateVideoResponse +- name: google.cloud.videointelligence.v1p2beta1.AnnotateVideoProgress +- name: google.cloud.videointelligence.v1p2beta1.VideoSegment +- name: google.rpc.Status + +documentation: + summary: Cloud Video Intelligence API. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 600.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 600.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 600.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 600.0 + - selector: google.cloud.videointelligence.v1p2beta1.VideoIntelligenceService.AnnotateVideo + deadline: 600.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: /v1p2beta1/operations + + - selector: google.longrunning.Operations.GetOperation + get: '/v1p2beta1/operations/{name=*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1p2beta1/operations/{name=*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1p2beta1/operations/{name=*}:cancel' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/videointelligence/videointelligence_v1p3beta1.yaml b/google/cloud/videointelligence/videointelligence_v1p3beta1.yaml new file mode 100644 index 000000000..6d33be286 --- /dev/null +++ b/google/cloud/videointelligence/videointelligence_v1p3beta1.yaml @@ -0,0 +1,55 @@ +type: google.api.Service +config_version: 3 +name: videointelligence.googleapis.com +title: Cloud Video Intelligence API + +apis: +- name: google.cloud.videointelligence.v1p3beta1.VideoIntelligenceService +- name: google.cloud.videointelligence.v1p3beta1.StreamingVideoIntelligenceService + +types: +- name: google.cloud.videointelligence.v1p3beta1.AnnotateVideoResponse +- name: google.cloud.videointelligence.v1p3beta1.AnnotateVideoProgress +- name: google.cloud.videointelligence.v1p3beta1.VideoSegment +- name: google.rpc.Status + +documentation: + summary: Cloud Video Intelligence API. + +backend: + rules: + - selector: google.longrunning.Operations.ListOperations + deadline: 600.0 + - selector: google.longrunning.Operations.GetOperation + deadline: 600.0 + - selector: google.longrunning.Operations.DeleteOperation + deadline: 600.0 + - selector: google.longrunning.Operations.CancelOperation + deadline: 600.0 + - selector: google.cloud.videointelligence.v1p3beta1.VideoIntelligenceService.AnnotateVideo + deadline: 600.0 + - selector: google.cloud.videointelligence.v1p3beta1.StreamingVideoIntelligenceService.AnnotateVideo + deadline: 900.0 + +http: + rules: + - selector: google.longrunning.Operations.ListOperations + get: /v1p3beta1/operations + + - selector: google.longrunning.Operations.GetOperation + get: '/v1p3beta1/operations/{name=*}' + + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1p3beta1/operations/{name=*}' + + - selector: google.longrunning.Operations.CancelOperation + post: '/v1p3beta1/operations/{name=*}:cancel' + body: '*' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/vision/BUILD.bazel b/google/cloud/vision/BUILD.bazel new file mode 100644 index 000000000..a87c57fec --- /dev/null +++ b/google/cloud/vision/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"])) diff --git a/google/cloud/vision/artman_vision_v1.yaml b/google/cloud/vision/artman_vision_v1.yaml new file mode 100644 index 000000000..6b037447e --- /dev/null +++ b/google/cloud/vision/artman_vision_v1.yaml @@ -0,0 +1,37 @@ +common: + api_name: vision + api_version: v1 + organization_name: google-cloud + service_yaml: vision_v1.yaml + gapic_yaml: v1/vision_gapic.yaml + src_proto_paths: + - v1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA + release_level: GA +- name: python_gapic + type: GAPIC + language: PYTHON + release_level: BETA +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/vision/artman_vision_v1p1beta1.yaml b/google/cloud/vision/artman_vision_v1p1beta1.yaml new file mode 100644 index 000000000..c1c6a3f86 --- /dev/null +++ b/google/cloud/vision/artman_vision_v1p1beta1.yaml @@ -0,0 +1,36 @@ +common: + api_name: vision + api_version: v1p1beta1 + organization_name: google-cloud + service_yaml: vision_v1p1beta1.yaml + gapic_yaml: v1p1beta1/vision_gapic.yaml + src_proto_paths: + - v1p1beta1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON + release_level: BETA +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/vision/artman_vision_v1p2beta1.yaml b/google/cloud/vision/artman_vision_v1p2beta1.yaml new file mode 100644 index 000000000..02967283c --- /dev/null +++ b/google/cloud/vision/artman_vision_v1p2beta1.yaml @@ -0,0 +1,36 @@ +common: + api_name: vision + api_version: v1p2beta1 + organization_name: google-cloud + service_yaml: vision_v1p2beta1.yaml + gapic_yaml: v1p2beta1/vision_gapic.yaml + src_proto_paths: + - v1p2beta1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON + release_level: BETA +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/vision/artman_vision_v1p3beta1.yaml b/google/cloud/vision/artman_vision_v1p3beta1.yaml new file mode 100644 index 000000000..be0c34b0f --- /dev/null +++ b/google/cloud/vision/artman_vision_v1p3beta1.yaml @@ -0,0 +1,41 @@ +common: + api_name: vision + api_version: v1p3beta1 + organization_name: google-cloud + service_yaml: vision_v1p3beta1.yaml + gapic_yaml: v1p3beta1/vision_gapic.yaml + src_proto_paths: + - v1p3beta1 + proto_deps: + - name: google-common-protos +artifacts: +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON + release_level: BETA + package_version: + grpc_dep_lower_bound: 0.90.3 + grpc_dep_upper_bound: 0.91dev +- name: php_gapic + type: GAPIC + language: PHP +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: go_gapic + type: GAPIC + language: GO +- name: csharp_gapic + type: GAPIC + language: CSHARP +- name: nodejs_gapic + type: GAPIC + language: NODEJS + release_level: BETA + package_version: + grpc_dep_lower_bound: 0.12.0 +- name: gapic_config + type: GAPIC_CONFIG diff --git a/google/cloud/vision/artman_vision_v1p4beta1.yaml b/google/cloud/vision/artman_vision_v1p4beta1.yaml new file mode 100644 index 000000000..b7e00b3a0 --- /dev/null +++ b/google/cloud/vision/artman_vision_v1p4beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: vision + api_version: v1p4beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1p4beta1 + service_yaml: vision_v1p4beta1.yaml + gapic_yaml: v1p4beta1/vision_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/vision/v1/BUILD.bazel b/google/cloud/vision/v1/BUILD.bazel new file mode 100644 index 000000000..01ec43694 --- /dev/null +++ b/google/cloud/vision/v1/BUILD.bazel @@ -0,0 +1,158 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "vision_proto", + srcs = [ + "geometry.proto", + "image_annotator.proto", + "product_search.proto", + "product_search_service.proto", + "text_annotation.proto", + "web_detection.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "//google/type:color_proto", + "//google/type:latlng_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "vision_proto_with_info", + deps = [":vision_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "vision_java_proto", + deps = [":vision_proto"], +) + +java_grpc_library( + name = "vision_java_grpc", + srcs = [":vision_proto"], + deps = [":vision_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "vision_resource_name_java_proto", + gapic_yaml = "vision_gapic.yaml", + deps = [":vision_proto"], +) + +java_gapic_library( + name = "vision_java_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + service_yaml = "//google/cloud/vision:vision_v1.yaml", + test_deps = [":vision_java_grpc"], + deps = [ + ":vision_java_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":vision_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.vision.v1.ImageAnnotatorClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-vision-v1-java", + client_deps = [":vision_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":vision_java_gapic_test"], + grpc_deps = [":vision_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":vision_java_proto", + ":vision_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "vision_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/vision/v1", + protos = [":vision_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + "//google/type:color_go_proto", + "//google/type:latlng_go_proto", + ], +) + +go_gapic_library( + name = "vision_go_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + importpath = "cloud.google.com/go/vision/apiv1", + service_yaml = "//google/cloud/vision:vision_v1.yaml", + deps = [ + ":vision_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "vision_go_gapic_test", + srcs = [":vision_go_gapic_srcjar_test"], + embed = [":vision_go_gapic"], + importpath = "cloud.google.com/go/vision/apiv1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-vision-v1-go", + deps = [ + ":vision_go_gapic", + ":vision_go_gapic_srcjar-smoke-test.srcjar", + ":vision_go_gapic_srcjar-test.srcjar", + ":vision_go_proto", + ], +) diff --git a/google/cloud/vision/v1/geometry.proto b/google/cloud/vision/v1/geometry.proto new file mode 100644 index 000000000..f3ba8b773 --- /dev/null +++ b/google/cloud/vision/v1/geometry.proto @@ -0,0 +1,71 @@ +// Copyright 2018 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.vision.v1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1;vision"; +option java_multiple_files = true; +option java_outer_classname = "GeometryProto"; +option java_package = "com.google.cloud.vision.v1"; +option objc_class_prefix = "GCVN"; + +// A vertex represents a 2D point in the image. +// NOTE: the vertex coordinates are in the same scale as the original image. +message Vertex { + // X coordinate. + int32 x = 1; + + // Y coordinate. + int32 y = 2; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// A bounding polygon for the detected image annotation. +message BoundingPoly { + // The bounding polygon vertices. + repeated Vertex vertices = 1; + + // The bounding polygon normalized vertices. + repeated NormalizedVertex normalized_vertices = 2; +} + +// A 3D position in the image, used primarily for Face detection landmarks. +// A valid Position must have both x and y coordinates. +// The position coordinates are in the same scale as the original image. +message Position { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; + + // Z coordinate (or depth). + float z = 3; +} diff --git a/google/cloud/vision/v1/image_annotator.proto b/google/cloud/vision/v1/image_annotator.proto new file mode 100644 index 000000000..abaf1bd75 --- /dev/null +++ b/google/cloud/vision/v1/image_annotator.proto @@ -0,0 +1,806 @@ +// Copyright 2018 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.vision.v1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1/geometry.proto"; +import "google/cloud/vision/v1/product_search.proto"; +import "google/cloud/vision/v1/text_annotation.proto"; +import "google/cloud/vision/v1/web_detection.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; +import "google/type/color.proto"; +import "google/type/latlng.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ImageAnnotatorProto"; +option java_package = "com.google.cloud.vision.v1"; +option objc_class_prefix = "GCVN"; + +// Service that performs Google Cloud Vision API detection tasks over client +// images, such as face, landmark, logo, label, and text detection. The +// ImageAnnotator service returns detected entities from the images. +service ImageAnnotator { + // Run image detection and annotation for a batch of images. + rpc BatchAnnotateImages(BatchAnnotateImagesRequest) + returns (BatchAnnotateImagesResponse) { + option (google.api.http) = { + post: "/v1/images:annotate" + body: "*" + }; + } + + // Run asynchronous image detection and annotation for a list of generic + // files, such as PDF files, which may contain multiple pages and multiple + // images per page. Progress and results can be retrieved through the + // `google.longrunning.Operations` interface. + // `Operation.metadata` contains `OperationMetadata` (metadata). + // `Operation.response` contains `AsyncBatchAnnotateFilesResponse` (results). + rpc AsyncBatchAnnotateFiles(AsyncBatchAnnotateFilesRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/files:asyncBatchAnnotate" + body: "*" + }; + } +} + +// The type of Google Cloud Vision API detection to perform, and the maximum +// number of results to return for that type. Multiple `Feature` objects can +// be specified in the `features` list. +message Feature { + // Type of Google Cloud Vision API feature to be extracted. + enum Type { + // Unspecified feature type. + TYPE_UNSPECIFIED = 0; + + // Run face detection. + FACE_DETECTION = 1; + + // Run landmark detection. + LANDMARK_DETECTION = 2; + + // Run logo detection. + LOGO_DETECTION = 3; + + // Run label detection. + LABEL_DETECTION = 4; + + // Run text detection / optical character recognition (OCR). Text detection + // is optimized for areas of text within a larger image; if the image is + // a document, use `DOCUMENT_TEXT_DETECTION` instead. + TEXT_DETECTION = 5; + + // Run dense text document OCR. Takes precedence when both + // `DOCUMENT_TEXT_DETECTION` and `TEXT_DETECTION` are present. + DOCUMENT_TEXT_DETECTION = 11; + + // Run Safe Search to detect potentially unsafe + // or undesirable content. + SAFE_SEARCH_DETECTION = 6; + + // Compute a set of image properties, such as the + // image's dominant colors. + IMAGE_PROPERTIES = 7; + + // Run crop hints. + CROP_HINTS = 9; + + // Run web detection. + WEB_DETECTION = 10; + + // Run Product Search. + PRODUCT_SEARCH = 12; + + // Run localizer for object detection. + OBJECT_LOCALIZATION = 19; + } + + // The feature type. + Type type = 1; + + // Maximum number of results of this type. Does not apply to + // `TEXT_DETECTION`, `DOCUMENT_TEXT_DETECTION`, or `CROP_HINTS`. + int32 max_results = 2; + + // Model to use for the feature. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// External image source (Google Cloud Storage or web URL image location). +message ImageSource { + // **Use `image_uri` instead.** + // + // The Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more info. + string gcs_image_uri = 1; + + // The URI of the source image. Can be either: + // + // 1. A Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more + // info. + // + // 2. A publicly-accessible image HTTP/HTTPS URL. When fetching images from + // HTTP/HTTPS URLs, Google cannot guarantee that the request will be + // completed. Your request may fail if the specified host denies the + // request (e.g. due to request throttling or DOS prevention), or if Google + // throttles requests to the site for abuse prevention. You should not + // depend on externally-hosted images for production applications. + // + // When both `gcs_image_uri` and `image_uri` are specified, `image_uri` takes + // precedence. + string image_uri = 2; +} + +// Client image to perform Google Cloud Vision API tasks over. +message Image { + // Image content, represented as a stream of bytes. + // Note: As with all `bytes` fields, protobuffers use a pure binary + // representation, whereas JSON representations use base64. + bytes content = 1; + + // Google Cloud Storage image location, or publicly-accessible image + // URL. If both `content` and `source` are provided for an image, `content` + // takes precedence and is used to perform the image annotation request. + ImageSource source = 2; +} + +// A face annotation object contains the results of face detection. +message FaceAnnotation { + // A face-specific landmark (for example, a face feature). + message Landmark { + // Face landmark (feature) type. + // Left and right are defined from the vantage of the viewer of the image + // without considering mirror projections typical of photos. So, `LEFT_EYE`, + // typically, is the person's right eye. + enum Type { + // Unknown face landmark detected. Should not be filled. + UNKNOWN_LANDMARK = 0; + + // Left eye. + LEFT_EYE = 1; + + // Right eye. + RIGHT_EYE = 2; + + // Left of left eyebrow. + LEFT_OF_LEFT_EYEBROW = 3; + + // Right of left eyebrow. + RIGHT_OF_LEFT_EYEBROW = 4; + + // Left of right eyebrow. + LEFT_OF_RIGHT_EYEBROW = 5; + + // Right of right eyebrow. + RIGHT_OF_RIGHT_EYEBROW = 6; + + // Midpoint between eyes. + MIDPOINT_BETWEEN_EYES = 7; + + // Nose tip. + NOSE_TIP = 8; + + // Upper lip. + UPPER_LIP = 9; + + // Lower lip. + LOWER_LIP = 10; + + // Mouth left. + MOUTH_LEFT = 11; + + // Mouth right. + MOUTH_RIGHT = 12; + + // Mouth center. + MOUTH_CENTER = 13; + + // Nose, bottom right. + NOSE_BOTTOM_RIGHT = 14; + + // Nose, bottom left. + NOSE_BOTTOM_LEFT = 15; + + // Nose, bottom center. + NOSE_BOTTOM_CENTER = 16; + + // Left eye, top boundary. + LEFT_EYE_TOP_BOUNDARY = 17; + + // Left eye, right corner. + LEFT_EYE_RIGHT_CORNER = 18; + + // Left eye, bottom boundary. + LEFT_EYE_BOTTOM_BOUNDARY = 19; + + // Left eye, left corner. + LEFT_EYE_LEFT_CORNER = 20; + + // Right eye, top boundary. + RIGHT_EYE_TOP_BOUNDARY = 21; + + // Right eye, right corner. + RIGHT_EYE_RIGHT_CORNER = 22; + + // Right eye, bottom boundary. + RIGHT_EYE_BOTTOM_BOUNDARY = 23; + + // Right eye, left corner. + RIGHT_EYE_LEFT_CORNER = 24; + + // Left eyebrow, upper midpoint. + LEFT_EYEBROW_UPPER_MIDPOINT = 25; + + // Right eyebrow, upper midpoint. + RIGHT_EYEBROW_UPPER_MIDPOINT = 26; + + // Left ear tragion. + LEFT_EAR_TRAGION = 27; + + // Right ear tragion. + RIGHT_EAR_TRAGION = 28; + + // Left eye pupil. + LEFT_EYE_PUPIL = 29; + + // Right eye pupil. + RIGHT_EYE_PUPIL = 30; + + // Forehead glabella. + FOREHEAD_GLABELLA = 31; + + // Chin gnathion. + CHIN_GNATHION = 32; + + // Chin left gonion. + CHIN_LEFT_GONION = 33; + + // Chin right gonion. + CHIN_RIGHT_GONION = 34; + } + + // Face landmark type. + Type type = 3; + + // Face landmark position. + Position position = 4; + } + + // The bounding polygon around the face. The coordinates of the bounding box + // are in the original image's scale, as returned in `ImageParams`. + // The bounding box is computed to "frame" the face in accordance with human + // expectations. It is based on the landmarker results. + // Note that one or more x and/or y coordinates may not be generated in the + // `BoundingPoly` (the polygon will be unbounded) if only a partial face + // appears in the image to be annotated. + BoundingPoly bounding_poly = 1; + + // The `fd_bounding_poly` bounding polygon is tighter than the + // `boundingPoly`, and encloses only the skin part of the face. Typically, it + // is used to eliminate the face from any image analysis that detects the + // "amount of skin" visible in an image. It is not based on the + // landmarker results, only on the initial face detection, hence + // the <code>fd</code> (face detection) prefix. + BoundingPoly fd_bounding_poly = 2; + + // Detected face landmarks. + repeated Landmark landmarks = 3; + + // Roll angle, which indicates the amount of clockwise/anti-clockwise rotation + // of the face relative to the image vertical about the axis perpendicular to + // the face. Range [-180,180]. + float roll_angle = 4; + + // Yaw angle, which indicates the leftward/rightward angle that the face is + // pointing relative to the vertical plane perpendicular to the image. Range + // [-180,180]. + float pan_angle = 5; + + // Pitch angle, which indicates the upwards/downwards angle that the face is + // pointing relative to the image's horizontal plane. Range [-180,180]. + float tilt_angle = 6; + + // Detection confidence. Range [0, 1]. + float detection_confidence = 7; + + // Face landmarking confidence. Range [0, 1]. + float landmarking_confidence = 8; + + // Joy likelihood. + Likelihood joy_likelihood = 9; + + // Sorrow likelihood. + Likelihood sorrow_likelihood = 10; + + // Anger likelihood. + Likelihood anger_likelihood = 11; + + // Surprise likelihood. + Likelihood surprise_likelihood = 12; + + // Under-exposed likelihood. + Likelihood under_exposed_likelihood = 13; + + // Blurred likelihood. + Likelihood blurred_likelihood = 14; + + // Headwear likelihood. + Likelihood headwear_likelihood = 15; +} + +// Detected entity location information. +message LocationInfo { + // lat/long location coordinates. + google.type.LatLng lat_lng = 1; +} + +// A `Property` consists of a user-supplied name/value pair. +message Property { + // Name of the property. + string name = 1; + + // Value of the property. + string value = 2; + + // Value of numeric properties. + uint64 uint64_value = 3; +} + +// Set of detected entity features. +message EntityAnnotation { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string mid = 1; + + // The language code for the locale in which the entity textual + // `description` is expressed. + string locale = 2; + + // Entity textual description, expressed in its `locale` language. + string description = 3; + + // Overall score of the result. Range [0, 1]. + float score = 4; + + // **Deprecated. Use `score` instead.** + // The accuracy of the entity detection in an image. + // For example, for an image in which the "Eiffel Tower" entity is detected, + // this field represents the confidence that there is a tower in the query + // image. Range [0, 1]. + float confidence = 5 [deprecated = true]; + + // The relevancy of the ICA (Image Content Annotation) label to the + // image. For example, the relevancy of "tower" is likely higher to an image + // containing the detected "Eiffel Tower" than to an image containing a + // detected distant towering building, even though the confidence that + // there is a tower in each image may be the same. Range [0, 1]. + float topicality = 6; + + // Image region to which this entity belongs. Not produced + // for `LABEL_DETECTION` features. + BoundingPoly bounding_poly = 7; + + // The location information for the detected entity. Multiple + // `LocationInfo` elements can be present because one location may + // indicate the location of the scene in the image, and another location + // may indicate the location of the place where the image was taken. + // Location information is usually present for landmarks. + repeated LocationInfo locations = 8; + + // Some entities may have optional user-supplied `Property` (name/value) + // fields, such a score or string that qualifies the entity. + repeated Property properties = 9; +} + +// Set of detected objects with bounding boxes. +message LocalizedObjectAnnotation { + // Object ID that should align with EntityAnnotation mid. + string mid = 1; + + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + + // Object name, expressed in its `language_code` language. + string name = 3; + + // Score of the result. Range [0, 1]. + float score = 4; + + // Image region to which this object belongs. This must be populated. + BoundingPoly bounding_poly = 5; +} + +// Set of features pertaining to the image, computed by computer vision +// methods over safe-search verticals (for example, adult, spoof, medical, +// violence). +message SafeSearchAnnotation { + // Represents the adult content likelihood for the image. Adult content may + // contain elements such as nudity, pornographic images or cartoons, or + // sexual activities. + Likelihood adult = 1; + + // Spoof likelihood. The likelihood that an modification + // was made to the image's canonical version to make it appear + // funny or offensive. + Likelihood spoof = 2; + + // Likelihood that this is a medical image. + Likelihood medical = 3; + + // Likelihood that this image contains violent content. + Likelihood violence = 4; + + // Likelihood that the request image contains racy content. Racy content may + // include (but is not limited to) skimpy or sheer clothing, strategically + // covered nudity, lewd or provocative poses, or close-ups of sensitive + // body areas. + Likelihood racy = 9; +} + +// Rectangle determined by min and max `LatLng` pairs. +message LatLongRect { + // Min lat/long pair. + google.type.LatLng min_lat_lng = 1; + + // Max lat/long pair. + google.type.LatLng max_lat_lng = 2; +} + +// Color information consists of RGB channels, score, and the fraction of +// the image that the color occupies in the image. +message ColorInfo { + // RGB components of the color. + google.type.Color color = 1; + + // Image-specific score for this color. Value in range [0, 1]. + float score = 2; + + // The fraction of pixels the color occupies in the image. + // Value in range [0, 1]. + float pixel_fraction = 3; +} + +// Set of dominant colors and their corresponding scores. +message DominantColorsAnnotation { + // RGB color values with their score and pixel fraction. + repeated ColorInfo colors = 1; +} + +// Stores image properties, such as dominant colors. +message ImageProperties { + // If present, dominant colors completed successfully. + DominantColorsAnnotation dominant_colors = 1; +} + +// Single crop hint that is used to generate a new crop when serving an image. +message CropHint { + // The bounding polygon for the crop region. The coordinates of the bounding + // box are in the original image's scale, as returned in `ImageParams`. + BoundingPoly bounding_poly = 1; + + // Confidence of this being a salient region. Range [0, 1]. + float confidence = 2; + + // Fraction of importance of this salient region with respect to the original + // image. + float importance_fraction = 3; +} + +// Set of crop hints that are used to generate new crops when serving images. +message CropHintsAnnotation { + // Crop hint results. + repeated CropHint crop_hints = 1; +} + +// Parameters for crop hints annotation request. +message CropHintsParams { + // Aspect ratios in floats, representing the ratio of the width to the height + // of the image. For example, if the desired aspect ratio is 4/3, the + // corresponding float value should be 1.33333. If not specified, the + // best possible crop is returned. The number of provided aspect ratios is + // limited to a maximum of 16; any aspect ratios provided after the 16th are + // ignored. + repeated float aspect_ratios = 1; +} + +// Parameters for web detection request. +message WebDetectionParams { + // Whether to include results derived from the geo information in the image. + bool include_geo_results = 2; +} + +// Image context and/or feature-specific parameters. +message ImageContext { + // Not used. + LatLongRect lat_long_rect = 1; + + // List of languages to use for TEXT_DETECTION. In most cases, an empty value + // yields the best results since it enables automatic language detection. For + // languages based on the Latin alphabet, setting `language_hints` is not + // needed. In rare cases, when the language of the text in the image is known, + // setting a hint will help get better results (although it will be a + // significant hindrance if the hint is wrong). Text detection returns an + // error if one or more of the specified languages is not one of the + // [supported languages](/vision/docs/languages). + repeated string language_hints = 2; + + // Parameters for crop hints annotation request. + CropHintsParams crop_hints_params = 4; + + // Parameters for product search. + ProductSearchParams product_search_params = 5; + + // Parameters for web detection. + WebDetectionParams web_detection_params = 6; +} + +// Request for performing Google Cloud Vision API tasks over a user-provided +// image, with user-requested features. +message AnnotateImageRequest { + // The image to be processed. + Image image = 1; + + // Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image. + ImageContext image_context = 3; +} + +// If an image was produced from a file (e.g. a PDF), this message gives +// information about the source of that image. +message ImageAnnotationContext { + // The URI of the file used to produce the image. + string uri = 1; + + // If the file was a PDF or TIFF, this field gives the page number within + // the file used to produce the image. + int32 page_number = 2; +} + +// Response to an image annotation request. +message AnnotateImageResponse { + // If present, face detection has completed successfully. + repeated FaceAnnotation face_annotations = 1; + + // If present, landmark detection has completed successfully. + repeated EntityAnnotation landmark_annotations = 2; + + // If present, logo detection has completed successfully. + repeated EntityAnnotation logo_annotations = 3; + + // If present, label detection has completed successfully. + repeated EntityAnnotation label_annotations = 4; + + // If present, localized object detection has completed successfully. + // This will be sorted descending by confidence score. + repeated LocalizedObjectAnnotation localized_object_annotations = 22; + + // If present, text (OCR) detection has completed successfully. + repeated EntityAnnotation text_annotations = 5; + + // If present, text (OCR) detection or document (OCR) text detection has + // completed successfully. + // This annotation provides the structural hierarchy for the OCR detected + // text. + TextAnnotation full_text_annotation = 12; + + // If present, safe-search annotation has completed successfully. + SafeSearchAnnotation safe_search_annotation = 6; + + // If present, image properties were extracted successfully. + ImageProperties image_properties_annotation = 8; + + // If present, crop hints have completed successfully. + CropHintsAnnotation crop_hints_annotation = 11; + + // If present, web detection has completed successfully. + WebDetection web_detection = 13; + + // If present, product search has completed successfully. + ProductSearchResults product_search_results = 14; + + // If set, represents the error message for the operation. + // Note that filled-in image annotations are guaranteed to be + // correct, even when `error` is set. + google.rpc.Status error = 9; + + // If present, contextual information is needed to understand where this image + // comes from. + ImageAnnotationContext context = 21; +} + +// Response to a single file annotation request. A file may contain one or more +// images, which individually have their own responses. +message AnnotateFileResponse { + // Information about the file for which this response is generated. + InputConfig input_config = 1; + + // Individual responses to images found within the file. + repeated AnnotateImageResponse responses = 2; +} + +// Multiple image annotation requests are batched into a single service call. +message BatchAnnotateImagesRequest { + // Individual image annotation requests for this batch. + repeated AnnotateImageRequest requests = 1; +} + +// Response to a batch image annotation request. +message BatchAnnotateImagesResponse { + // Individual responses to image annotation requests within the batch. + repeated AnnotateImageResponse responses = 1; +} + +// An offline file annotation request. +message AsyncAnnotateFileRequest { + // Required. Information about the input file. + InputConfig input_config = 1; + + // Required. Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image(s) in the file. + ImageContext image_context = 3; + + // Required. The desired output location and metadata (e.g. format). + OutputConfig output_config = 4; +} + +// The response for a single offline file annotation request. +message AsyncAnnotateFileResponse { + // The output location and metadata from AsyncAnnotateFileRequest. + OutputConfig output_config = 1; +} + +// Multiple async file annotation requests are batched into a single service +// call. +message AsyncBatchAnnotateFilesRequest { + // Individual async file annotation requests for this batch. + repeated AsyncAnnotateFileRequest requests = 1; +} + +// Response to an async batch file annotation request. +message AsyncBatchAnnotateFilesResponse { + // The list of file annotation responses, one for each request in + // AsyncBatchAnnotateFilesRequest. + repeated AsyncAnnotateFileResponse responses = 1; +} + +// The desired input location and metadata. +message InputConfig { + // The Google Cloud Storage location to read the input from. + GcsSource gcs_source = 1; + + // The type of the file. Currently only "application/pdf" and "image/tiff" + // are supported. Wildcards are not supported. + string mime_type = 2; +} + +// The desired output location and metadata. +message OutputConfig { + // The Google Cloud Storage location to write the output(s) to. + GcsDestination gcs_destination = 1; + + // The max number of response protos to put into each output JSON file on + // Google Cloud Storage. + // The valid range is [1, 100]. If not specified, the default value is 20. + // + // For example, for one pdf file with 100 pages, 100 response protos will + // be generated. If `batch_size` = 20, then 5 json files each + // containing 20 response protos will be written under the prefix + // `gcs_destination`.`uri`. + // + // Currently, batch_size only applies to GcsDestination, with potential future + // support for other output configurations. + int32 batch_size = 2; +} + +// The Google Cloud Storage location where the input will be read from. +message GcsSource { + // Google Cloud Storage URI for the input file. This must only be a + // Google Cloud Storage object. Wildcards are not currently supported. + string uri = 1; +} + +// The Google Cloud Storage location where the output will be written to. +message GcsDestination { + // Google Cloud Storage URI where the results will be stored. Results will + // be in JSON format and preceded by its corresponding input URI. This field + // can either represent a single file, or a prefix for multiple outputs. + // Prefixes must end in a `/`. + // + // Examples: + // + // * File: gs://bucket-name/filename.json + // * Prefix: gs://bucket-name/prefix/here/ + // * File: gs://bucket-name/prefix/here + // + // If multiple outputs, each response is still AnnotateFileResponse, each of + // which contains some subset of the full list of AnnotateImageResponse. + // Multiple outputs can happen if, for example, the output JSON is too large + // and overflows into multiple sharded files. + string uri = 1; +} + +// Contains metadata for the BatchAnnotateImages operation. +message OperationMetadata { + // Batch operation states. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is received. + CREATED = 1; + + // Request is actively being processed. + RUNNING = 2; + + // The batch processing is done. + DONE = 3; + + // The batch processing was cancelled. + CANCELLED = 4; + } + + // Current state of the batch operation. + State state = 1; + + // The time when the batch request was received. + google.protobuf.Timestamp create_time = 5; + + // The time when the operation result was last updated. + google.protobuf.Timestamp update_time = 6; +} + +// A bucketized representation of likelihood, which is intended to give clients +// highly stable results across model upgrades. +enum Likelihood { + // Unknown likelihood. + UNKNOWN = 0; + + // It is very unlikely that the image belongs to the specified vertical. + VERY_UNLIKELY = 1; + + // It is unlikely that the image belongs to the specified vertical. + UNLIKELY = 2; + + // It is possible that the image belongs to the specified vertical. + POSSIBLE = 3; + + // It is likely that the image belongs to the specified vertical. + LIKELY = 4; + + // It is very likely that the image belongs to the specified vertical. + VERY_LIKELY = 5; +} diff --git a/google/cloud/vision/v1/product_search.proto b/google/cloud/vision/v1/product_search.proto new file mode 100644 index 000000000..2b895bdbd --- /dev/null +++ b/google/cloud/vision/v1/product_search.proto @@ -0,0 +1,97 @@ +// Copyright 2018 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.vision.v1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1/geometry.proto"; +import "google/cloud/vision/v1/product_search_service.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ProductSearchProto"; +option java_package = "com.google.cloud.vision.v1"; +option objc_class_prefix = "GCVN"; + +// Parameters for a product search request. +message ProductSearchParams { + // The bounding polygon around the area of interest in the image. + // Optional. If it is not specified, system discretion will be applied. + BoundingPoly bounding_poly = 9; + + // The resource name of a [ProductSet][google.cloud.vision.v1.ProductSet] to + // be searched for similar images. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`. + string product_set = 6; + + // The list of product categories to search in. Currently, we only consider + // the first category, and either "homegoods", "apparel", or "toys" should be + // specified. + repeated string product_categories = 7; + + // The filtering expression. This can be used to restrict search results based + // on Product labels. We currently support an AND of OR of key-value + // expressions, where each expression within an OR must have the same key. + // + // For example, "(color = red OR color = blue) AND brand = Google" is + // acceptable, but not "(color = red OR brand = Google)" or "color: red". + string filter = 8; +} + +// Results for a product search request. +message ProductSearchResults { + // Information about a product. + message Result { + // The Product. + Product product = 1; + + // A confidence level on the match, ranging from 0 (no confidence) to + // 1 (full confidence). + float score = 2; + + // The resource name of the image from the product that is the closest match + // to the query. + string image = 3; + } + + // Information about the products similar to a single product in a query + // image. + message GroupedResult { + // The bounding polygon around the product detected in the query image. + BoundingPoly bounding_poly = 1; + + // List of results, one for each product match. + repeated Result results = 2; + } + + // Timestamp of the index which provided these results. Changes made after + // this time are not reflected in the current results. + google.protobuf.Timestamp index_time = 2; + + // List of results, one for each product match. + repeated Result results = 5; + + // List of results grouped by products detected in the query image. Each entry + // corresponds to one bounding polygon in the query image, and contains the + // matching products specific to that region. There may be duplicate product + // matches in the union of all the per-product results. + repeated GroupedResult product_grouped_results = 6; +} diff --git a/google/cloud/vision/v1/product_search_service.proto b/google/cloud/vision/v1/product_search_service.proto new file mode 100644 index 000000000..5bbfebfb5 --- /dev/null +++ b/google/cloud/vision/v1/product_search_service.proto @@ -0,0 +1,849 @@ +// Copyright 2018 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.vision.v1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1/geometry.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ProductSearchServiceProto"; +option java_package = "com.google.cloud.vision.v1"; +option objc_class_prefix = "GCVN"; + +// Manages Products and ProductSets of reference images for use in product +// search. It uses the following resource model: +// +// - The API has a collection of [ProductSet][google.cloud.vision.v1.ProductSet] +// resources, named `projects/*/locations/*/productSets/*`, which acts as a way +// to put different products into groups to limit identification. +// +// In parallel, +// +// - The API has a collection of [Product][google.cloud.vision.v1.Product] +// resources, named +// `projects/*/locations/*/products/*` +// +// - Each [Product][google.cloud.vision.v1.Product] has a collection of +// [ReferenceImage][google.cloud.vision.v1.ReferenceImage] resources, named +// `projects/*/locations/*/products/*/referenceImages/*` +service ProductSearch { + // Creates and returns a new ProductSet resource. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if display_name is missing, or is longer than + // 4096 characters. + rpc CreateProductSet(CreateProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/productSets" + body: "product_set" + }; + } + + // Lists ProductSets in an unspecified order. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100, or less + // than 1. + rpc ListProductSets(ListProductSetsRequest) + returns (ListProductSetsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/productSets" + }; + } + + // Gets information associated with a ProductSet. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + rpc GetProductSet(GetProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/productSets/*}" + }; + } + + // Makes changes to a ProductSet resource. + // Only display_name can be updated currently. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + // * Returns INVALID_ARGUMENT if display_name is present in update_mask but + // missing from the request or longer than 4096 characters. + rpc UpdateProductSet(UpdateProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + patch: "/v1/{product_set.name=projects/*/locations/*/productSets/*}" + body: "product_set" + }; + } + + // Permanently deletes a ProductSet. Products and ReferenceImages in the + // ProductSet are not deleted. + // + // The actual image files are not deleted from Google Cloud Storage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + rpc DeleteProductSet(DeleteProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/productSets/*}" + }; + } + + // Creates and returns a new product resource. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if display_name is missing or longer than 4096 + // characters. + // * Returns INVALID_ARGUMENT if description is longer than 4096 characters. + // * Returns INVALID_ARGUMENT if product_category is missing or invalid. + rpc CreateProduct(CreateProductRequest) returns (Product) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/products" + body: "product" + }; + } + + // Lists products in an unspecified order. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1. + rpc ListProducts(ListProductsRequest) returns (ListProductsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*}/products" + }; + } + + // Gets information associated with a Product. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product does not exist. + rpc GetProduct(GetProductRequest) returns (Product) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/products/*}" + }; + } + + // Makes changes to a Product resource. + // Only the `display_name`, `description`, and `labels` fields can be updated + // right now. + // + // If labels are updated, the change will not be reflected in queries until + // the next index time. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product does not exist. + // * Returns INVALID_ARGUMENT if display_name is present in update_mask but is + // missing from the request or longer than 4096 characters. + // * Returns INVALID_ARGUMENT if description is present in update_mask but is + // longer than 4096 characters. + // * Returns INVALID_ARGUMENT if product_category is present in update_mask. + rpc UpdateProduct(UpdateProductRequest) returns (Product) { + option (google.api.http) = { + patch: "/v1/{product.name=projects/*/locations/*/products/*}" + body: "product" + }; + } + + // Permanently deletes a product and its reference images. + // + // Metadata of the product and all its images will be deleted right away, but + // search queries against ProductSets containing the product may still work + // until all related caches are refreshed. + // + // Possible errors: + // + // * Returns NOT_FOUND if the product does not exist. + rpc DeleteProduct(DeleteProductRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/products/*}" + }; + } + + // Creates and returns a new ReferenceImage resource. + // + // The `bounding_poly` field is optional. If `bounding_poly` is not specified, + // the system will try to detect regions of interest in the image that are + // compatible with the product_category on the parent product. If it is + // specified, detection is ALWAYS skipped. The system converts polygons into + // non-rotated rectangles. + // + // Note that the pipeline will resize the image if the image resolution is too + // large to process (above 50MP). + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if the image_uri is missing or longer than 4096 + // characters. + // * Returns INVALID_ARGUMENT if the product does not exist. + // * Returns INVALID_ARGUMENT if bounding_poly is not provided, and nothing + // compatible with the parent product's product_category is detected. + // * Returns INVALID_ARGUMENT if bounding_poly contains more than 10 polygons. + rpc CreateReferenceImage(CreateReferenceImageRequest) + returns (ReferenceImage) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*/products/*}/referenceImages" + body: "reference_image" + }; + } + + // Permanently deletes a reference image. + // + // The image metadata will be deleted right away, but search queries + // against ProductSets containing the image may still work until all related + // caches are refreshed. + // + // The actual image files are not deleted from Google Cloud Storage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the reference image does not exist. + rpc DeleteReferenceImage(DeleteReferenceImageRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=projects/*/locations/*/products/*/referenceImages/*}" + }; + } + + // Lists reference images. + // + // Possible errors: + // + // * Returns NOT_FOUND if the parent product does not exist. + // * Returns INVALID_ARGUMENT if the page_size is greater than 100, or less + // than 1. + rpc ListReferenceImages(ListReferenceImagesRequest) + returns (ListReferenceImagesResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*/products/*}/referenceImages" + }; + } + + // Gets information associated with a ReferenceImage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the specified image does not exist. + rpc GetReferenceImage(GetReferenceImageRequest) returns (ReferenceImage) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/products/*/referenceImages/*}" + }; + } + + // Adds a Product to the specified ProductSet. If the Product is already + // present, no change is made. + // + // One Product can be added to at most 100 ProductSets. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product or the ProductSet doesn't exist. + rpc AddProductToProductSet(AddProductToProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/productSets/*}:addProduct" + body: "*" + }; + } + + // Removes a Product from the specified ProductSet. + // + // Possible errors: + // + // * Returns NOT_FOUND If the Product is not found under the ProductSet. + rpc RemoveProductFromProductSet(RemoveProductFromProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/productSets/*}:removeProduct" + body: "*" + }; + } + + // Lists the Products in a ProductSet, in an unspecified order. If the + // ProductSet does not exist, the products field of the response will be + // empty. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1. + rpc ListProductsInProductSet(ListProductsInProductSetRequest) + returns (ListProductsInProductSetResponse) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/productSets/*}/products" + }; + } + + // Asynchronous API that imports a list of reference images to specified + // product sets based on a list of image information. + // + // The [google.longrunning.Operation][google.longrunning.Operation] API can be + // used to keep track of the progress and results of the request. + // `Operation.metadata` contains `BatchOperationMetadata`. (progress) + // `Operation.response` contains `ImportProductSetsResponse`. (results) + // + // The input source of this method is a csv file on Google Cloud Storage. + // For the format of the csv file please see + // [ImportProductSetsGcsSource.csv_file_uri][google.cloud.vision.v1.ImportProductSetsGcsSource.csv_file_uri]. + rpc ImportProductSets(ImportProductSetsRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*/locations/*}/productSets:import" + body: "*" + }; + } +} + +// A Product contains ReferenceImages. +message Product { + // A product label represented as a key-value pair. + message KeyValue { + // The key of the label attached to the product. Cannot be empty and cannot + // exceed 128 bytes. + string key = 1; + + // The value of the label attached to the product. Cannot be empty and + // cannot exceed 128 bytes. + string value = 2; + } + + // The resource name of the product. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + // + // This field is ignored when creating a product. + string name = 1; + + // The user-provided name for this Product. Must not be empty. Must be at most + // 4096 characters long. + string display_name = 2; + + // User-provided metadata to be stored with this product. Must be at most 4096 + // characters long. + string description = 3; + + // The category for the product identified by the reference image. This should + // be either "homegoods", "apparel", or "toys". + // + // This field is immutable. + string product_category = 4; + + // Key-value pairs that can be attached to a product. At query time, + // constraints can be specified based on the product_labels. + // + // Note that integer values can be provided as strings, e.g. "1199". Only + // strings with integer values can match a range-based restriction which is + // to be supported soon. + // + // Multiple values can be assigned to the same key. One product may have up to + // 100 product_labels. + repeated KeyValue product_labels = 5; +} + +// A ProductSet contains Products. A ProductSet can contain a maximum of 1 +// million reference images. If the limit is exceeded, periodic indexing will +// fail. +message ProductSet { + // The resource name of the ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`. + // + // This field is ignored when creating a ProductSet. + string name = 1; + + // The user-provided name for this ProductSet. Must not be empty. Must be at + // most 4096 characters long. + string display_name = 2; + + // Output only. The time at which this ProductSet was last indexed. Query + // results will reflect all updates before this time. If this ProductSet has + // never been indexed, this field is 0. + // + // This field is ignored when creating a ProductSet. + google.protobuf.Timestamp index_time = 3; + + // Output only. If there was an error with indexing the product set, the field + // is populated. + // + // This field is ignored when creating a ProductSet. + google.rpc.Status index_error = 4; +} + +// A `ReferenceImage` represents a product image and its associated metadata, +// such as bounding boxes. +message ReferenceImage { + // The resource name of the reference image. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID`. + // + // This field is ignored when creating a reference image. + string name = 1; + + // The Google Cloud Storage URI of the reference image. + // + // The URI must start with `gs://`. + // + // Required. + string uri = 2; + + // Bounding polygons around the areas of interest in the reference image. + // Optional. If this field is empty, the system will try to detect regions of + // interest. At most 10 bounding polygons will be used. + // + // The provided shape is converted into a non-rotated rectangle. Once + // converted, the small edge of the rectangle must be greater than or equal + // to 300 pixels. The aspect ratio must be 1:4 or less (i.e. 1:3 is ok; 1:5 + // is not). + repeated BoundingPoly bounding_polys = 3; +} + +// Request message for the `CreateProduct` method. +message CreateProductRequest { + // The project in which the Product should be created. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The product to create. + Product product = 2; + + // A user-supplied resource id for this Product. If set, the server will + // attempt to use this value as the resource id. If it is already in use, an + // error is returned with code ALREADY_EXISTS. Must be at most 128 characters + // long. It cannot contain the character `/`. + string product_id = 3; +} + +// Request message for the `ListProducts` method. +message ListProductsRequest { + // The project OR ProductSet from which Products should be listed. + // + // Format: + // `projects/PROJECT_ID/locations/LOC_ID` + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProducts` method. +message ListProductsResponse { + // List of products. + repeated Product products = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// Request message for the `GetProduct` method. +message GetProductRequest { + // Resource name of the Product to get. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string name = 1; +} + +// Request message for the `UpdateProduct` method. +message UpdateProductRequest { + // The Product resource which replaces the one on the server. + // product.name is immutable. + Product product = 1; + + // The [FieldMask][google.protobuf.FieldMask] that specifies which fields + // to update. + // If update_mask isn't specified, all mutable fields are to be updated. + // Valid mask paths include `product_labels`, `display_name`, and + // `description`. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for the `DeleteProduct` method. +message DeleteProductRequest { + // Resource name of product to delete. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string name = 1; +} + +// Request message for the `CreateProductSet` method. +message CreateProductSetRequest { + // The project in which the ProductSet should be created. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The ProductSet to create. + ProductSet product_set = 2; + + // A user-supplied resource id for this ProductSet. If set, the server will + // attempt to use this value as the resource id. If it is already in use, an + // error is returned with code ALREADY_EXISTS. Must be at most 128 characters + // long. It cannot contain the character `/`. + string product_set_id = 3; +} + +// Request message for the `ListProductSets` method. +message ListProductSetsRequest { + // The project from which ProductSets should be listed. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProductSets` method. +message ListProductSetsResponse { + // List of ProductSets. + repeated ProductSet product_sets = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// Request message for the `GetProductSet` method. +message GetProductSetRequest { + // Resource name of the ProductSet to get. + // + // Format is: + // `projects/PROJECT_ID/locations/LOG_ID/productSets/PRODUCT_SET_ID` + string name = 1; +} + +// Request message for the `UpdateProductSet` method. +message UpdateProductSetRequest { + // The ProductSet resource which replaces the one on the server. + ProductSet product_set = 1; + + // The [FieldMask][google.protobuf.FieldMask] that specifies which fields to + // update. + // If update_mask isn't specified, all mutable fields are to be updated. + // Valid mask path is `display_name`. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for the `DeleteProductSet` method. +message DeleteProductSetRequest { + // Resource name of the ProductSet to delete. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; +} + +// Request message for the `CreateReferenceImage` method. +message CreateReferenceImageRequest { + // Resource name of the product in which to create the reference image. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + string parent = 1; + + // The reference image to create. + // If an image ID is specified, it is ignored. + ReferenceImage reference_image = 2; + + // A user-supplied resource id for the ReferenceImage to be added. If set, + // the server will attempt to use this value as the resource id. If it is + // already in use, an error is returned with code ALREADY_EXISTS. Must be at + // most 128 characters long. It cannot contain the character `/`. + string reference_image_id = 3; +} + +// Request message for the `ListReferenceImages` method. +message ListReferenceImagesRequest { + // Resource name of the product containing the reference images. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // A token identifying a page of results to be returned. This is the value + // of `nextPageToken` returned in a previous reference image list request. + // + // Defaults to the first page if not specified. + string page_token = 3; +} + +// Response message for the `ListReferenceImages` method. +message ListReferenceImagesResponse { + // The list of reference images. + repeated ReferenceImage reference_images = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string next_page_token = 3; +} + +// Request message for the `GetReferenceImage` method. +message GetReferenceImageRequest { + // The resource name of the ReferenceImage to get. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID`. + string name = 1; +} + +// Request message for the `DeleteReferenceImage` method. +message DeleteReferenceImageRequest { + // The resource name of the reference image to delete. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID` + string name = 1; +} + +// Request message for the `AddProductToProductSet` method. +message AddProductToProductSetRequest { + // The resource name for the ProductSet to modify. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The resource name for the Product to be added to this ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string product = 2; +} + +// Request message for the `RemoveProductFromProductSet` method. +message RemoveProductFromProductSetRequest { + // The resource name for the ProductSet to modify. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The resource name for the Product to be removed from this ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string product = 2; +} + +// Request message for the `ListProductsInProductSet` method. +message ListProductsInProductSetRequest { + // The ProductSet resource for which to retrieve Products. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProductsInProductSet` method. +message ListProductsInProductSetResponse { + // The list of Products. + repeated Product products = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// The Google Cloud Storage location for a csv file which preserves a list of +// ImportProductSetRequests in each line. +message ImportProductSetsGcsSource { + // The Google Cloud Storage URI of the input csv file. + // + // The URI must start with `gs://`. + // + // The format of the input csv file should be one image per line. + // In each line, there are 8 columns. + // + // 1. image-uri + // 2. image-id + // 3. product-set-id + // 4. product-id + // 5. product-category + // 6. product-display-name + // 7. labels + // 8. bounding-poly + // + // The `image-uri`, `product-set-id`, `product-id`, and `product-category` + // columns are required. All other columns are optional. + // + // If the `ProductSet` or `Product` specified by the `product-set-id` and + // `product-id` values does not exist, then the system will create a new + // `ProductSet` or `Product` for the image. In this case, the + // `product-display-name` column refers to + // [display_name][google.cloud.vision.v1.Product.display_name], the + // `product-category` column refers to + // [product_category][google.cloud.vision.v1.Product.product_category], and + // the `labels` column refers to + // [product_labels][google.cloud.vision.v1.Product.product_labels]. + // + // The `image-id` column is optional but must be unique if provided. If it is + // empty, the system will automatically assign a unique id to the image. + // + // The `product-display-name` column is optional. If it is empty, the system + // sets the [display_name][google.cloud.vision.v1.Product.display_name] field + // for the product to a space (" "). You can update the `display_name` later + // by using the API. + // + // If a `Product` with the specified `product-id` already exists, then the + // system ignores the `product-display-name`, `product-category`, and `labels` + // columns. + // + // The `labels` column (optional) is a line containing a list of + // comma-separated key-value pairs, in the following format: + // + // "key_1=value_1,key_2=value_2,...,key_n=value_n" + // + // The `bounding-poly` column (optional) identifies one region of + // interest from the image in the same manner as `CreateReferenceImage`. If + // you do not specify the `bounding-poly` column, then the system will try to + // detect regions of interest automatically. + // + // At most one `bounding-poly` column is allowed per line. If the image + // contains multiple regions of interest, add a line to the CSV file that + // includes the same product information, and the `bounding-poly` values for + // each region of interest. + // + // The `bounding-poly` column must contain an even number of comma-separated + // numbers, in the format "p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y". Use + // non-negative integers for absolute bounding polygons, and float values + // in [0, 1] for normalized bounding polygons. + // + // The system will resize the image if the image resolution is too + // large to process (larger than 20MP). + string csv_file_uri = 1; +} + +// The input content for the `ImportProductSets` method. +message ImportProductSetsInputConfig { + // The source of the input. + oneof source { + // The Google Cloud Storage location for a csv file which preserves a list + // of ImportProductSetRequests in each line. + ImportProductSetsGcsSource gcs_source = 1; + } +} + +// Request message for the `ImportProductSets` method. +message ImportProductSetsRequest { + // The project in which the ProductSets should be imported. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The input content for the list of requests. + ImportProductSetsInputConfig input_config = 2; +} + +// Response message for the `ImportProductSets` method. +// +// This message is returned by the +// [google.longrunning.Operations.GetOperation][google.longrunning.Operations.GetOperation] +// method in the returned +// [google.longrunning.Operation.response][google.longrunning.Operation.response] +// field. +message ImportProductSetsResponse { + // The list of reference_images that are imported successfully. + repeated ReferenceImage reference_images = 1; + + // The rpc status for each ImportProductSet request, including both successes + // and errors. + // + // The number of statuses here matches the number of lines in the csv file, + // and statuses[i] stores the success or failure status of processing the i-th + // line of the csv, starting from line 0. + repeated google.rpc.Status statuses = 2; +} + +// Metadata for the batch operations such as the current state. +// +// This is included in the `metadata` field of the `Operation` returned by the +// `GetOperation` call of the `google::longrunning::Operations` service. +message BatchOperationMetadata { + // Enumerates the possible states that the batch request can be in. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is actively being processed. + PROCESSING = 1; + + // The request is done and at least one item has been successfully + // processed. + SUCCESSFUL = 2; + + // The request is done and no item has been successfully processed. + FAILED = 3; + + // The request is done after the longrunning.Operations.CancelOperation has + // been called by the user. Any records that were processed before the + // cancel command are output as specified in the request. + CANCELLED = 4; + } + + // The current state of the batch operation. + State state = 1; + + // The time when the batch request was submitted to the server. + google.protobuf.Timestamp submit_time = 2; + + // The time when the batch request is finished and + // [google.longrunning.Operation.done][google.longrunning.Operation.done] is + // set to true. + google.protobuf.Timestamp end_time = 3; +} diff --git a/google/cloud/vision/v1/text_annotation.proto b/google/cloud/vision/v1/text_annotation.proto new file mode 100644 index 000000000..417e4f514 --- /dev/null +++ b/google/cloud/vision/v1/text_annotation.proto @@ -0,0 +1,261 @@ +// Copyright 2018 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.vision.v1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1/geometry.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1;vision"; +option java_multiple_files = true; +option java_outer_classname = "TextAnnotationProto"; +option java_package = "com.google.cloud.vision.v1"; +option objc_class_prefix = "GCVN"; + +// TextAnnotation contains a structured representation of OCR extracted text. +// The hierarchy of an OCR extracted text structure is like this: +// TextAnnotation -> Page -> Block -> Paragraph -> Word -> Symbol +// Each structural component, starting from Page, may further have their own +// properties. Properties describe detected languages, breaks etc.. Please refer +// to the +// [TextAnnotation.TextProperty][google.cloud.vision.v1.TextAnnotation.TextProperty] +// message definition below for more detail. +message TextAnnotation { + // Detected language for a structural component. + message DetectedLanguage { + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 1; + + // Confidence of detected language. Range [0, 1]. + float confidence = 2; + } + + // Detected start or end of a structural component. + message DetectedBreak { + // Enum to denote the type of break found. New line, space etc. + enum BreakType { + // Unknown break label type. + UNKNOWN = 0; + + // Regular space. + SPACE = 1; + + // Sure space (very wide). + SURE_SPACE = 2; + + // Line-wrapping break. + EOL_SURE_SPACE = 3; + + // End-line hyphen that is not present in text; does not co-occur with + // `SPACE`, `LEADER_SPACE`, or `LINE_BREAK`. + HYPHEN = 4; + + // Line break that ends a paragraph. + LINE_BREAK = 5; + } + + // Detected break type. + BreakType type = 1; + + // True if break prepends the element. + bool is_prefix = 2; + } + + // Additional information detected on the structural component. + message TextProperty { + // A list of detected languages together with confidence. + repeated DetectedLanguage detected_languages = 1; + + // Detected start or end of a text segment. + DetectedBreak detected_break = 2; + } + + // List of pages detected by OCR. + repeated Page pages = 1; + + // UTF-8 text detected on the pages. + string text = 2; +} + +// Detected page from OCR. +message Page { + // Additional information detected on the page. + TextAnnotation.TextProperty property = 1; + + // Page width. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 width = 2; + + // Page height. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 height = 3; + + // List of blocks of text, images etc on this page. + repeated Block blocks = 4; + + // Confidence of the OCR results on the page. Range [0, 1]. + float confidence = 5; +} + +// Logical element on the page. +message Block { + // Type of a block (text, image etc) as identified by OCR. + enum BlockType { + // Unknown block type. + UNKNOWN = 0; + + // Regular text block. + TEXT = 1; + + // Table block. + TABLE = 2; + + // Image block. + PICTURE = 3; + + // Horizontal/vertical line box. + RULER = 4; + + // Barcode block. + BARCODE = 5; + } + + // Additional information detected for the block. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the block. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // + // * when the text is horizontal it might look like: + // + // 0----1 + // | | + // 3----2 + // + // * when it's rotated 180 degrees around the top-left corner it becomes: + // + // 2----3 + // | | + // 1----0 + // + // and the vertex order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of paragraphs in this block (if this blocks is of type text). + repeated Paragraph paragraphs = 3; + + // Detected block type (text, image etc) for this block. + BlockType block_type = 4; + + // Confidence of the OCR results on the block. Range [0, 1]. + float confidence = 5; +} + +// Structural unit of text representing a number of words in certain order. +message Paragraph { + // Additional information detected for the paragraph. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the paragraph. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertex order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of words in this paragraph. + repeated Word words = 3; + + // Confidence of the OCR results for the paragraph. Range [0, 1]. + float confidence = 4; +} + +// A word representation. +message Word { + // Additional information detected for the word. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the word. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertex order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of symbols in the word. + // The order of the symbols follows the natural reading order. + repeated Symbol symbols = 3; + + // Confidence of the OCR results for the word. Range [0, 1]. + float confidence = 4; +} + +// A single symbol representation. +message Symbol { + // Additional information detected for the symbol. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the symbol. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // The actual UTF-8 representation of the symbol. + string text = 3; + + // Confidence of the OCR results for the symbol. Range [0, 1]. + float confidence = 4; +} diff --git a/google/cloud/vision/v1/vision_gapic.yaml b/google/cloud/vision/v1/vision_gapic.yaml new file mode 100644 index 000000000..29700d344 --- /dev/null +++ b/google/cloud/vision/v1/vision_gapic.yaml @@ -0,0 +1,457 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.vision.v1 + release_level: GA + python: + package_name: google.cloud.vision_v1.gapic + go: + package_name: cloud.google.com/go/vision/apiv1 + release_level: GA + csharp: + package_name: Google.Cloud.Vision.V1 + release_level: GA + ruby: + package_name: Google::Cloud::Vision::V1 + php: + package_name: Google\Cloud\Vision\V1 + nodejs: + package_name: vision.v1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.vision.v1.ImageAnnotator + smoke_test: + method: BatchAnnotateImages + init_fields: + - requests[0].image.source.gcs_image_uri="gs://gapic-toolkit/President_Barack_Obama.jpg" + - requests[0].features[0].type=FACE_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + methods: + - name: BatchAnnotateImages + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AsyncBatchAnnotateFiles + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + long_running: + return_type: google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse + metadata_type: google.cloud.vision.v1.OperationMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 +- name: google.cloud.vision.v1.ProductSearch + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/productSets/{product_set} + entity_name: product_set + - name_pattern: projects/{project}/locations/{location}/products/{product} + entity_name: product + - name_pattern: projects/{project}/locations/{location}/products/{product}/referenceImages/{reference_image} + entity_name: reference_image + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + methods: + - name: CreateProduct + flattening: + groups: + - parameters: + - parent + - product + - product_id + required_fields: + - parent + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + parent: location + - name: ListProducts + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: products + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + parent: location + - name: GetProduct + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + name: product + - name: UpdateProduct + flattening: + groups: + - parameters: + - product + - update_mask + required_fields: + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + product.name: product + - name: DeleteProduct + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + name: product + - name: ListReferenceImages + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: reference_images + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + parent: product + - name: GetReferenceImage + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: reference_image + timeout_millis: 60000 + - name: DeleteReferenceImage + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: reference_image + timeout_millis: 60000 + - name: CreateReferenceImage + flattening: + groups: + - parameters: + - parent + - reference_image + - reference_image_id + required_fields: + - parent + - reference_image + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + parent: product + - name: CreateProductSet + flattening: + groups: + - parameters: + - parent + - product_set + - product_set_id + required_fields: + - parent + - product_set + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + parent: location + - name: ListProductSets + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: product_sets + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + parent: location + - name: GetProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + name: product_set + - name: UpdateProductSet + flattening: + groups: + - parameters: + - product_set + - update_mask + required_fields: + - product_set + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + product_set.name: product_set + - name: DeleteProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + name: product_set + - name: AddProductToProductSet + flattening: + groups: + - parameters: + - name + - product + required_fields: + - name + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + name: product_set + - name: RemoveProductFromProductSet + flattening: + groups: + - parameters: + - name + - product + required_fields: + - name + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + name: product_set + - name: ListProductsInProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: products + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + name: product_set + - name: ImportProductSets + flattening: + groups: + - parameters: + - parent + - input_config + required_fields: + - parent + - input_config + long_running: + return_type: google.cloud.vision.v1.ImportProductSetsResponse + metadata_type: google.cloud.vision.v1.BatchOperationMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + field_name_patterns: + parent: location +# Force string formatting functions to be generated. +enable_string_format_functions_override: true +resource_name_generation: +- message_name: CreateProductSetRequest + field_entity_map: + parent: location +- message_name: ListProductSetsRequest + field_entity_map: + parent: location +- message_name: GetProductSetRequest + field_entity_map: + name: product_set +- message_name: UpdateProductSetRequest + field_entity_map: + product_set.name: product_set +- message_name: DeleteProductSetRequest + field_entity_map: + name: product_set +- message_name: CreateProductRequest + field_entity_map: + parent: location +- message_name: ListProductsRequest + field_entity_map: + parent: location +- message_name: GetProductRequest + field_entity_map: + name: product +- message_name: UpdateProductRequest + field_entity_map: + product.name: product +- message_name: DeleteProductRequest + field_entity_map: + name: product +- message_name: CreateReferenceImageRequest + field_entity_map: + parent: product +- message_name: DeleteReferenceImageRequest + field_entity_map: + name: reference_image +- message_name: ListReferenceImagesRequest + field_entity_map: + parent: product +- message_name: GetReferenceImageRequest + field_entity_map: + name: reference_image +- message_name: AddProductToProductSetRequest + field_entity_map: + name: product_set + product: product +- message_name: RemoveProductFromProductSetRequest + field_entity_map: + name: product_set + product: product +- message_name: ListProductsInProductSetRequest + field_entity_map: + name: product_set +- message_name: ImportProductSetsRequest + field_entity_map: + parent: location +- message_name: Product + field_entity_map: + name: product +- message_name: ProductSet + field_entity_map: + name: product_set +- message_name: ReferenceImage + field_entity_map: + name: reference_image +- message_name: ProductSearchParams + field_entity_map: + product_set: product_set diff --git a/google/cloud/vision/v1/web_detection.proto b/google/cloud/vision/v1/web_detection.proto new file mode 100644 index 000000000..2d3c4a86a --- /dev/null +++ b/google/cloud/vision/v1/web_detection.proto @@ -0,0 +1,107 @@ +// Copyright 2018 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.vision.v1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1;vision"; +option java_multiple_files = true; +option java_outer_classname = "WebDetectionProto"; +option java_package = "com.google.cloud.vision.v1"; +option objc_class_prefix = "GCVN"; + +// Relevant information for the image from the Internet. +message WebDetection { + // Entity deduced from similar images on the Internet. + message WebEntity { + // Opaque entity ID. + string entity_id = 1; + + // Overall relevancy score for the entity. + // Not normalized and not comparable across different image queries. + float score = 2; + + // Canonical description of the entity, in English. + string description = 3; + } + + // Metadata for online images. + message WebImage { + // The result image URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the image. + float score = 2; + } + + // Metadata for web pages. + message WebPage { + // The result web page URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the web page. + float score = 2; + + // Title for the web page, may contain HTML markups. + string page_title = 3; + + // Fully matching images on the page. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 4; + + // Partial matching images on the page. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its + // crops. + repeated WebImage partial_matching_images = 5; + } + + // Label to provide extra metadata for the web detection. + message WebLabel { + // Label for extra metadata. + string label = 1; + + // The BCP-47 language code for `label`, such as "en-US" or "sr-Latn". + // For more information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + } + + // Deduced entities from similar images on the Internet. + repeated WebEntity web_entities = 1; + + // Fully matching images from the Internet. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 2; + + // Partial matching images from the Internet. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its crops. + repeated WebImage partial_matching_images = 3; + + // Web pages containing the matching images from the Internet. + repeated WebPage pages_with_matching_images = 4; + + // The visually similar image results. + repeated WebImage visually_similar_images = 6; + + // The service's best guess as to the topic of the request image. + // Inferred from similar images on the open web. + repeated WebLabel best_guess_labels = 8; +} diff --git a/google/cloud/vision/v1p1beta1/BUILD.bazel b/google/cloud/vision/v1p1beta1/BUILD.bazel new file mode 100644 index 000000000..aa73427db --- /dev/null +++ b/google/cloud/vision/v1p1beta1/BUILD.bazel @@ -0,0 +1,153 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "vision_proto", + srcs = [ + "geometry.proto", + "image_annotator.proto", + "text_annotation.proto", + "web_detection.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "//google/type:color_proto", + "//google/type:latlng_proto", + ], +) + +proto_library_with_info( + name = "vision_proto_with_info", + deps = [":vision_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "vision_java_proto", + deps = [":vision_proto"], +) + +java_grpc_library( + name = "vision_java_grpc", + srcs = [":vision_proto"], + deps = [":vision_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "vision_resource_name_java_proto", + gapic_yaml = "vision_gapic.yaml", + deps = [":vision_proto"], +) + +java_gapic_library( + name = "vision_java_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + service_yaml = "//google/cloud/vision:vision_v1p1beta1.yaml", + test_deps = [":vision_java_grpc"], + deps = [ + ":vision_java_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":vision_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.vision.v1p1beta1.ImageAnnotatorClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-vision-v1p1beta1-java", + client_deps = [":vision_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":vision_java_gapic_test"], + grpc_deps = [":vision_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":vision_java_proto", + ":vision_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "vision_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/vision/v1p1beta1", + protos = [":vision_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + "//google/type:color_go_proto", + "//google/type:latlng_go_proto", + ], +) + +go_gapic_library( + name = "vision_go_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + importpath = "cloud.google.com/go/vision/apiv1p1beta1", + service_yaml = "//google/cloud/vision:vision_v1p1beta1.yaml", + deps = [ + ":vision_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "vision_go_gapic_test", + srcs = [":vision_go_gapic_srcjar_test"], + embed = [":vision_go_gapic"], + importpath = "cloud.google.com/go/vision/apiv1p1beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-vision-v1p1beta1-go", + deps = [ + ":vision_go_gapic", + ":vision_go_gapic_srcjar-smoke-test.srcjar", + ":vision_go_gapic_srcjar-test.srcjar", + ":vision_go_proto", + ], +) diff --git a/google/cloud/vision/v1p1beta1/geometry.proto b/google/cloud/vision/v1p1beta1/geometry.proto new file mode 100644 index 000000000..6d46d9c34 --- /dev/null +++ b/google/cloud/vision/v1p1beta1/geometry.proto @@ -0,0 +1,53 @@ +// 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.vision.v1p1beta1; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p1beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "GeometryProto"; +option java_package = "com.google.cloud.vision.v1p1beta1"; + +// A vertex represents a 2D point in the image. +// NOTE: the vertex coordinates are in the same scale as the original image. +message Vertex { + // X coordinate. + int32 x = 1; + + // Y coordinate. + int32 y = 2; +} + +// A bounding polygon for the detected image annotation. +message BoundingPoly { + // The bounding polygon vertices. + repeated Vertex vertices = 1; +} + +// A 3D position in the image, used primarily for Face detection landmarks. +// A valid Position must have both x and y coordinates. +// The position coordinates are in the same scale as the original image. +message Position { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; + + // Z coordinate (or depth). + float z = 3; +} diff --git a/google/cloud/vision/v1p1beta1/image_annotator.proto b/google/cloud/vision/v1p1beta1/image_annotator.proto new file mode 100644 index 000000000..4869a3311 --- /dev/null +++ b/google/cloud/vision/v1p1beta1/image_annotator.proto @@ -0,0 +1,592 @@ +// 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.vision.v1p1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p1beta1/geometry.proto"; +import "google/cloud/vision/v1p1beta1/text_annotation.proto"; +import "google/cloud/vision/v1p1beta1/web_detection.proto"; +import "google/rpc/status.proto"; +import "google/type/color.proto"; +import "google/type/latlng.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p1beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ImageAnnotatorProto"; +option java_package = "com.google.cloud.vision.v1p1beta1"; + +// Service that performs Google Cloud Vision API detection tasks over client +// images, such as face, landmark, logo, label, and text detection. The +// ImageAnnotator service returns detected entities from the images. +service ImageAnnotator { + // Run image detection and annotation for a batch of images. + rpc BatchAnnotateImages(BatchAnnotateImagesRequest) + returns (BatchAnnotateImagesResponse) { + option (google.api.http) = { + post: "/v1p1beta1/images:annotate" + body: "*" + }; + } +} + +// Users describe the type of Google Cloud Vision API tasks to perform over +// images by using *Feature*s. Each Feature indicates a type of image +// detection task to perform. Features encode the Cloud Vision API +// vertical to operate on and the number of top-scoring results to return. +message Feature { + // Type of image feature. + enum Type { + // Unspecified feature type. + TYPE_UNSPECIFIED = 0; + + // Run face detection. + FACE_DETECTION = 1; + + // Run landmark detection. + LANDMARK_DETECTION = 2; + + // Run logo detection. + LOGO_DETECTION = 3; + + // Run label detection. + LABEL_DETECTION = 4; + + // Run OCR. + TEXT_DETECTION = 5; + + // Run dense text document OCR. Takes precedence when both + // DOCUMENT_TEXT_DETECTION and TEXT_DETECTION are present. + DOCUMENT_TEXT_DETECTION = 11; + + // Run computer vision models to compute image safe-search properties. + SAFE_SEARCH_DETECTION = 6; + + // Compute a set of image properties, such as the image's dominant colors. + IMAGE_PROPERTIES = 7; + + // Run crop hints. + CROP_HINTS = 9; + + // Run web detection. + WEB_DETECTION = 10; + } + + // The feature type. + Type type = 1; + + // Maximum number of results of this type. + int32 max_results = 2; + + // Model to use for the feature. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// External image source (Google Cloud Storage image location). +message ImageSource { + // NOTE: For new code `image_uri` below is preferred. + // Google Cloud Storage image URI, which must be in the following form: + // `gs://bucket_name/object_name` (for details, see + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris)). + // NOTE: Cloud Storage object versioning is not supported. + string gcs_image_uri = 1; + + // Image URI which supports: + // 1) Google Cloud Storage image URI, which must be in the following form: + // `gs://bucket_name/object_name` (for details, see + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris)). + // NOTE: Cloud Storage object versioning is not supported. + // 2) Publicly accessible image HTTP/HTTPS URL. + // This is preferred over the legacy `gcs_image_uri` above. When both + // `gcs_image_uri` and `image_uri` are specified, `image_uri` takes + // precedence. + string image_uri = 2; +} + +// Client image to perform Google Cloud Vision API tasks over. +message Image { + // Image content, represented as a stream of bytes. + // Note: as with all `bytes` fields, protobuffers use a pure binary + // representation, whereas JSON representations use base64. + bytes content = 1; + + // Google Cloud Storage image location. If both `content` and `source` + // are provided for an image, `content` takes precedence and is + // used to perform the image annotation request. + ImageSource source = 2; +} + +// A face annotation object contains the results of face detection. +message FaceAnnotation { + // A face-specific landmark (for example, a face feature). + message Landmark { + // Face landmark (feature) type. + // Left and right are defined from the vantage of the viewer of the image + // without considering mirror projections typical of photos. So, `LEFT_EYE`, + // typically, is the person's right eye. + enum Type { + // Unknown face landmark detected. Should not be filled. + UNKNOWN_LANDMARK = 0; + + // Left eye. + LEFT_EYE = 1; + + // Right eye. + RIGHT_EYE = 2; + + // Left of left eyebrow. + LEFT_OF_LEFT_EYEBROW = 3; + + // Right of left eyebrow. + RIGHT_OF_LEFT_EYEBROW = 4; + + // Left of right eyebrow. + LEFT_OF_RIGHT_EYEBROW = 5; + + // Right of right eyebrow. + RIGHT_OF_RIGHT_EYEBROW = 6; + + // Midpoint between eyes. + MIDPOINT_BETWEEN_EYES = 7; + + // Nose tip. + NOSE_TIP = 8; + + // Upper lip. + UPPER_LIP = 9; + + // Lower lip. + LOWER_LIP = 10; + + // Mouth left. + MOUTH_LEFT = 11; + + // Mouth right. + MOUTH_RIGHT = 12; + + // Mouth center. + MOUTH_CENTER = 13; + + // Nose, bottom right. + NOSE_BOTTOM_RIGHT = 14; + + // Nose, bottom left. + NOSE_BOTTOM_LEFT = 15; + + // Nose, bottom center. + NOSE_BOTTOM_CENTER = 16; + + // Left eye, top boundary. + LEFT_EYE_TOP_BOUNDARY = 17; + + // Left eye, right corner. + LEFT_EYE_RIGHT_CORNER = 18; + + // Left eye, bottom boundary. + LEFT_EYE_BOTTOM_BOUNDARY = 19; + + // Left eye, left corner. + LEFT_EYE_LEFT_CORNER = 20; + + // Right eye, top boundary. + RIGHT_EYE_TOP_BOUNDARY = 21; + + // Right eye, right corner. + RIGHT_EYE_RIGHT_CORNER = 22; + + // Right eye, bottom boundary. + RIGHT_EYE_BOTTOM_BOUNDARY = 23; + + // Right eye, left corner. + RIGHT_EYE_LEFT_CORNER = 24; + + // Left eyebrow, upper midpoint. + LEFT_EYEBROW_UPPER_MIDPOINT = 25; + + // Right eyebrow, upper midpoint. + RIGHT_EYEBROW_UPPER_MIDPOINT = 26; + + // Left ear tragion. + LEFT_EAR_TRAGION = 27; + + // Right ear tragion. + RIGHT_EAR_TRAGION = 28; + + // Left eye pupil. + LEFT_EYE_PUPIL = 29; + + // Right eye pupil. + RIGHT_EYE_PUPIL = 30; + + // Forehead glabella. + FOREHEAD_GLABELLA = 31; + + // Chin gnathion. + CHIN_GNATHION = 32; + + // Chin left gonion. + CHIN_LEFT_GONION = 33; + + // Chin right gonion. + CHIN_RIGHT_GONION = 34; + } + + // Face landmark type. + Type type = 3; + + // Face landmark position. + Position position = 4; + } + + // The bounding polygon around the face. The coordinates of the bounding box + // are in the original image's scale, as returned in `ImageParams`. + // The bounding box is computed to "frame" the face in accordance with human + // expectations. It is based on the landmarker results. + // Note that one or more x and/or y coordinates may not be generated in the + // `BoundingPoly` (the polygon will be unbounded) if only a partial face + // appears in the image to be annotated. + BoundingPoly bounding_poly = 1; + + // The `fd_bounding_poly` bounding polygon is tighter than the + // `boundingPoly`, and encloses only the skin part of the face. Typically, it + // is used to eliminate the face from any image analysis that detects the + // "amount of skin" visible in an image. It is not based on the + // landmarker results, only on the initial face detection, hence + // the <code>fd</code> (face detection) prefix. + BoundingPoly fd_bounding_poly = 2; + + // Detected face landmarks. + repeated Landmark landmarks = 3; + + // Roll angle, which indicates the amount of clockwise/anti-clockwise rotation + // of the face relative to the image vertical about the axis perpendicular to + // the face. Range [-180,180]. + float roll_angle = 4; + + // Yaw angle, which indicates the leftward/rightward angle that the face is + // pointing relative to the vertical plane perpendicular to the image. Range + // [-180,180]. + float pan_angle = 5; + + // Pitch angle, which indicates the upwards/downwards angle that the face is + // pointing relative to the image's horizontal plane. Range [-180,180]. + float tilt_angle = 6; + + // Detection confidence. Range [0, 1]. + float detection_confidence = 7; + + // Face landmarking confidence. Range [0, 1]. + float landmarking_confidence = 8; + + // Joy likelihood. + Likelihood joy_likelihood = 9; + + // Sorrow likelihood. + Likelihood sorrow_likelihood = 10; + + // Anger likelihood. + Likelihood anger_likelihood = 11; + + // Surprise likelihood. + Likelihood surprise_likelihood = 12; + + // Under-exposed likelihood. + Likelihood under_exposed_likelihood = 13; + + // Blurred likelihood. + Likelihood blurred_likelihood = 14; + + // Headwear likelihood. + Likelihood headwear_likelihood = 15; +} + +// Detected entity location information. +message LocationInfo { + // lat/long location coordinates. + google.type.LatLng lat_lng = 1; +} + +// A `Property` consists of a user-supplied name/value pair. +message Property { + // Name of the property. + string name = 1; + + // Value of the property. + string value = 2; + + // Value of numeric properties. + uint64 uint64_value = 3; +} + +// Set of detected entity features. +message EntityAnnotation { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string mid = 1; + + // The language code for the locale in which the entity textual + // `description` is expressed. + string locale = 2; + + // Entity textual description, expressed in its `locale` language. + string description = 3; + + // Overall score of the result. Range [0, 1]. + float score = 4; + + // The accuracy of the entity detection in an image. + // For example, for an image in which the "Eiffel Tower" entity is detected, + // this field represents the confidence that there is a tower in the query + // image. Range [0, 1]. + float confidence = 5; + + // The relevancy of the ICA (Image Content Annotation) label to the + // image. For example, the relevancy of "tower" is likely higher to an image + // containing the detected "Eiffel Tower" than to an image containing a + // detected distant towering building, even though the confidence that + // there is a tower in each image may be the same. Range [0, 1]. + float topicality = 6; + + // Image region to which this entity belongs. Not produced + // for `LABEL_DETECTION` features. + BoundingPoly bounding_poly = 7; + + // The location information for the detected entity. Multiple + // `LocationInfo` elements can be present because one location may + // indicate the location of the scene in the image, and another location + // may indicate the location of the place where the image was taken. + // Location information is usually present for landmarks. + repeated LocationInfo locations = 8; + + // Some entities may have optional user-supplied `Property` (name/value) + // fields, such a score or string that qualifies the entity. + repeated Property properties = 9; +} + +// Set of features pertaining to the image, computed by computer vision +// methods over safe-search verticals (for example, adult, spoof, medical, +// violence). +message SafeSearchAnnotation { + // Represents the adult content likelihood for the image. Adult content may + // contain elements such as nudity, pornographic images or cartoons, or + // sexual activities. + Likelihood adult = 1; + + // Spoof likelihood. The likelihood that an modification + // was made to the image's canonical version to make it appear + // funny or offensive. + Likelihood spoof = 2; + + // Likelihood that this is a medical image. + Likelihood medical = 3; + + // Likelihood that this image contains violent content. + Likelihood violence = 4; + + // Likelihood that the request image contains racy content. Racy content may + // include (but is not limited to) skimpy or sheer clothing, strategically + // covered nudity, lewd or provocative poses, or close-ups of sensitive + // body areas. + Likelihood racy = 9; +} + +// Rectangle determined by min and max `LatLng` pairs. +message LatLongRect { + // Min lat/long pair. + google.type.LatLng min_lat_lng = 1; + + // Max lat/long pair. + google.type.LatLng max_lat_lng = 2; +} + +// Color information consists of RGB channels, score, and the fraction of +// the image that the color occupies in the image. +message ColorInfo { + // RGB components of the color. + google.type.Color color = 1; + + // Image-specific score for this color. Value in range [0, 1]. + float score = 2; + + // The fraction of pixels the color occupies in the image. + // Value in range [0, 1]. + float pixel_fraction = 3; +} + +// Set of dominant colors and their corresponding scores. +message DominantColorsAnnotation { + // RGB color values with their score and pixel fraction. + repeated ColorInfo colors = 1; +} + +// Stores image properties, such as dominant colors. +message ImageProperties { + // If present, dominant colors completed successfully. + DominantColorsAnnotation dominant_colors = 1; +} + +// Single crop hint that is used to generate a new crop when serving an image. +message CropHint { + // The bounding polygon for the crop region. The coordinates of the bounding + // box are in the original image's scale, as returned in `ImageParams`. + BoundingPoly bounding_poly = 1; + + // Confidence of this being a salient region. Range [0, 1]. + float confidence = 2; + + // Fraction of importance of this salient region with respect to the original + // image. + float importance_fraction = 3; +} + +// Set of crop hints that are used to generate new crops when serving images. +message CropHintsAnnotation { + // Crop hint results. + repeated CropHint crop_hints = 1; +} + +// Parameters for crop hints annotation request. +message CropHintsParams { + // Aspect ratios in floats, representing the ratio of the width to the height + // of the image. For example, if the desired aspect ratio is 4/3, the + // corresponding float value should be 1.33333. If not specified, the + // best possible crop is returned. The number of provided aspect ratios is + // limited to a maximum of 16; any aspect ratios provided after the 16th are + // ignored. + repeated float aspect_ratios = 1; +} + +// Parameters for web detection request. +message WebDetectionParams { + // Whether to include results derived from the geo information in the image. + bool include_geo_results = 2; +} + +// Image context and/or feature-specific parameters. +message ImageContext { + // lat/long rectangle that specifies the location of the image. + LatLongRect lat_long_rect = 1; + + // List of languages to use for TEXT_DETECTION. In most cases, an empty value + // yields the best results since it enables automatic language detection. For + // languages based on the Latin alphabet, setting `language_hints` is not + // needed. In rare cases, when the language of the text in the image is known, + // setting a hint will help get better results (although it will be a + // significant hindrance if the hint is wrong). Text detection returns an + // error if one or more of the specified languages is not one of the + // [supported languages](/vision/docs/languages). + repeated string language_hints = 2; + + // Parameters for crop hints annotation request. + CropHintsParams crop_hints_params = 4; + + // Parameters for web detection. + WebDetectionParams web_detection_params = 6; +} + +// Request for performing Google Cloud Vision API tasks over a user-provided +// image, with user-requested features. +message AnnotateImageRequest { + // The image to be processed. + Image image = 1; + + // Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image. + ImageContext image_context = 3; +} + +// Response to an image annotation request. +message AnnotateImageResponse { + // If present, face detection has completed successfully. + repeated FaceAnnotation face_annotations = 1; + + // If present, landmark detection has completed successfully. + repeated EntityAnnotation landmark_annotations = 2; + + // If present, logo detection has completed successfully. + repeated EntityAnnotation logo_annotations = 3; + + // If present, label detection has completed successfully. + repeated EntityAnnotation label_annotations = 4; + + // If present, text (OCR) detection has completed successfully. + repeated EntityAnnotation text_annotations = 5; + + // If present, text (OCR) detection or document (OCR) text detection has + // completed successfully. + // This annotation provides the structural hierarchy for the OCR detected + // text. + TextAnnotation full_text_annotation = 12; + + // If present, safe-search annotation has completed successfully. + SafeSearchAnnotation safe_search_annotation = 6; + + // If present, image properties were extracted successfully. + ImageProperties image_properties_annotation = 8; + + // If present, crop hints have completed successfully. + CropHintsAnnotation crop_hints_annotation = 11; + + // If present, web detection has completed successfully. + WebDetection web_detection = 13; + + // If set, represents the error message for the operation. + // Note that filled-in image annotations are guaranteed to be + // correct, even when `error` is set. + google.rpc.Status error = 9; +} + +// Multiple image annotation requests are batched into a single service call. +message BatchAnnotateImagesRequest { + // Individual image annotation requests for this batch. + repeated AnnotateImageRequest requests = 1; +} + +// Response to a batch image annotation request. +message BatchAnnotateImagesResponse { + // Individual responses to image annotation requests within the batch. + repeated AnnotateImageResponse responses = 1; +} + +// A bucketized representation of likelihood, which is intended to give clients +// highly stable results across model upgrades. +enum Likelihood { + // Unknown likelihood. + UNKNOWN = 0; + + // It is very unlikely that the image belongs to the specified vertical. + VERY_UNLIKELY = 1; + + // It is unlikely that the image belongs to the specified vertical. + UNLIKELY = 2; + + // It is possible that the image belongs to the specified vertical. + POSSIBLE = 3; + + // It is likely that the image belongs to the specified vertical. + LIKELY = 4; + + // It is very likely that the image belongs to the specified vertical. + VERY_LIKELY = 5; +} diff --git a/google/cloud/vision/v1p1beta1/text_annotation.proto b/google/cloud/vision/v1p1beta1/text_annotation.proto new file mode 100644 index 000000000..928e6e88b --- /dev/null +++ b/google/cloud/vision/v1p1beta1/text_annotation.proto @@ -0,0 +1,252 @@ +// 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.vision.v1p1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p1beta1/geometry.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p1beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "TextAnnotationProto"; +option java_package = "com.google.cloud.vision.v1p1beta1"; + +// TextAnnotation contains a structured representation of OCR extracted text. +// The hierarchy of an OCR extracted text structure is like this: +// TextAnnotation -> Page -> Block -> Paragraph -> Word -> Symbol +// Each structural component, starting from Page, may further have their own +// properties. Properties describe detected languages, breaks etc.. Please refer +// to the +// [TextAnnotation.TextProperty][google.cloud.vision.v1p1beta1.TextAnnotation.TextProperty] +// message definition below for more detail. +message TextAnnotation { + // Detected language for a structural component. + message DetectedLanguage { + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 1; + + // Confidence of detected language. Range [0, 1]. + float confidence = 2; + } + + // Detected start or end of a structural component. + message DetectedBreak { + // Enum to denote the type of break found. New line, space etc. + enum BreakType { + // Unknown break label type. + UNKNOWN = 0; + + // Regular space. + SPACE = 1; + + // Sure space (very wide). + SURE_SPACE = 2; + + // Line-wrapping break. + EOL_SURE_SPACE = 3; + + // End-line hyphen that is not present in text; does not co-occur with + // `SPACE`, `LEADER_SPACE`, or `LINE_BREAK`. + HYPHEN = 4; + + // Line break that ends a paragraph. + LINE_BREAK = 5; + } + + // Detected break type. + BreakType type = 1; + + // True if break prepends the element. + bool is_prefix = 2; + } + + // Additional information detected on the structural component. + message TextProperty { + // A list of detected languages together with confidence. + repeated DetectedLanguage detected_languages = 1; + + // Detected start or end of a text segment. + DetectedBreak detected_break = 2; + } + + // List of pages detected by OCR. + repeated Page pages = 1; + + // UTF-8 text detected on the pages. + string text = 2; +} + +// Detected page from OCR. +message Page { + // Additional information detected on the page. + TextAnnotation.TextProperty property = 1; + + // Page width in pixels. + int32 width = 2; + + // Page height in pixels. + int32 height = 3; + + // List of blocks of text, images etc on this page. + repeated Block blocks = 4; + + // Confidence of the OCR results on the page. Range [0, 1]. + float confidence = 5; +} + +// Logical element on the page. +message Block { + // Type of a block (text, image etc) as identified by OCR. + enum BlockType { + // Unknown block type. + UNKNOWN = 0; + + // Regular text block. + TEXT = 1; + + // Table block. + TABLE = 2; + + // Image block. + PICTURE = 3; + + // Horizontal/vertical line box. + RULER = 4; + + // Barcode block. + BARCODE = 5; + } + + // Additional information detected for the block. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the block. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of paragraphs in this block (if this blocks is of type text). + repeated Paragraph paragraphs = 3; + + // Detected block type (text, image etc) for this block. + BlockType block_type = 4; + + // Confidence of the OCR results on the block. Range [0, 1]. + float confidence = 5; +} + +// Structural unit of text representing a number of words in certain order. +message Paragraph { + // Additional information detected for the paragraph. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the paragraph. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of words in this paragraph. + repeated Word words = 3; + + // Confidence of the OCR results for the paragraph. Range [0, 1]. + float confidence = 4; +} + +// A word representation. +message Word { + // Additional information detected for the word. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the word. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of symbols in the word. + // The order of the symbols follows the natural reading order. + repeated Symbol symbols = 3; + + // Confidence of the OCR results for the word. Range [0, 1]. + float confidence = 4; +} + +// A single symbol representation. +message Symbol { + // Additional information detected for the symbol. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the symbol. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // The actual UTF-8 representation of the symbol. + string text = 3; + + // Confidence of the OCR results for the symbol. Range [0, 1]. + float confidence = 4; +} diff --git a/google/cloud/vision/v1p1beta1/vision_gapic.yaml b/google/cloud/vision/v1p1beta1/vision_gapic.yaml new file mode 100644 index 000000000..07b9bd9d4 --- /dev/null +++ b/google/cloud/vision/v1p1beta1/vision_gapic.yaml @@ -0,0 +1,55 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.vision.v1p1beta1 + python: + package_name: google.cloud.vision_v1p1beta1.gapic + go: + package_name: cloud.google.com/go/vision/apiv1p1beta1 + release_level: BETA + csharp: + package_name: Google.Cloud.Vision.V1P1Beta1 + release_level: BETA + ruby: + package_name: Google::Cloud::Vision::V1p1beta1 + php: + package_name: Google\Cloud\Vision\V1p1beta1 + nodejs: + package_name: vision.v1p1beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.vision.v1p1beta1.ImageAnnotator + smoke_test: + method: BatchAnnotateImages + init_fields: + - requests[0].image.source.gcs_image_uri="gs://gapic-toolkit/President_Barack_Obama.jpg" + - requests[0].features[0].type=FACE_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + methods: + - name: BatchAnnotateImages + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/vision/v1p1beta1/web_detection.proto b/google/cloud/vision/v1p1beta1/web_detection.proto new file mode 100644 index 000000000..28249cbde --- /dev/null +++ b/google/cloud/vision/v1p1beta1/web_detection.proto @@ -0,0 +1,104 @@ +// 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.vision.v1p1beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p1beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "WebDetectionProto"; +option java_package = "com.google.cloud.vision.v1p1beta1"; + +// Relevant information for the image from the Internet. +message WebDetection { + // Entity deduced from similar images on the Internet. + message WebEntity { + // Opaque entity ID. + string entity_id = 1; + + // Overall relevancy score for the entity. + // Not normalized and not comparable across different image queries. + float score = 2; + + // Canonical description of the entity, in English. + string description = 3; + } + + // Metadata for online images. + message WebImage { + // The result image URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the image. + float score = 2; + } + + // Metadata for web pages. + message WebPage { + // The result web page URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the web page. + float score = 2; + + // Title for the web page, may contain HTML markups. + string page_title = 3; + + // Fully matching images on the page. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 4; + + // Partial matching images on the page. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its + // crops. + repeated WebImage partial_matching_images = 5; + } + + // Label to provide extra metadata for the web detection. + message WebLabel { + // Label for extra metadata. + string label = 1; + + // The BCP-47 language code for `label`, such as "en-US" or "sr-Latn". + // For more information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + } + + // Deduced entities from similar images on the Internet. + repeated WebEntity web_entities = 1; + + // Fully matching images from the Internet. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 2; + + // Partial matching images from the Internet. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its crops. + repeated WebImage partial_matching_images = 3; + + // Web pages containing the matching images from the Internet. + repeated WebPage pages_with_matching_images = 4; + + // The visually similar image results. + repeated WebImage visually_similar_images = 6; + + // Best guess text labels for the request image. + repeated WebLabel best_guess_labels = 8; +} diff --git a/google/cloud/vision/v1p2beta1/BUILD.bazel b/google/cloud/vision/v1p2beta1/BUILD.bazel new file mode 100644 index 000000000..87336bc96 --- /dev/null +++ b/google/cloud/vision/v1p2beta1/BUILD.bazel @@ -0,0 +1,154 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "vision_proto", + srcs = [ + "geometry.proto", + "image_annotator.proto", + "text_annotation.proto", + "web_detection.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "//google/type:color_proto", + "//google/type:latlng_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "vision_proto_with_info", + deps = [":vision_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "vision_java_proto", + deps = [":vision_proto"], +) + +java_grpc_library( + name = "vision_java_grpc", + srcs = [":vision_proto"], + deps = [":vision_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "vision_resource_name_java_proto", + gapic_yaml = "vision_gapic.yaml", + deps = [":vision_proto"], +) + +java_gapic_library( + name = "vision_java_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + service_yaml = "//google/cloud/vision:vision_v1p2beta1.yaml", + test_deps = [":vision_java_grpc"], + deps = [ + ":vision_java_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":vision_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.vision.v1p2beta1.ImageAnnotatorClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-vision-v1p2beta1-java", + client_deps = [":vision_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":vision_java_gapic_test"], + grpc_deps = [":vision_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":vision_java_proto", + ":vision_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "vision_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/vision/v1p2beta1", + protos = [":vision_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + "//google/type:color_go_proto", + "//google/type:latlng_go_proto", + ], +) + +go_gapic_library( + name = "vision_go_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + importpath = "cloud.google.com/go/vision/apiv1p2beta1", + service_yaml = "//google/cloud/vision:vision_v1p2beta1.yaml", + deps = [ + ":vision_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "vision_go_gapic_test", + srcs = [":vision_go_gapic_srcjar_test"], + embed = [":vision_go_gapic"], + importpath = "cloud.google.com/go/vision/apiv1p2beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-vision-v1p2beta1-go", + deps = [ + ":vision_go_gapic", + ":vision_go_gapic_srcjar-smoke-test.srcjar", + ":vision_go_gapic_srcjar-test.srcjar", + ":vision_go_proto", + ], +)
\ No newline at end of file diff --git a/google/cloud/vision/v1p2beta1/geometry.proto b/google/cloud/vision/v1p2beta1/geometry.proto new file mode 100644 index 000000000..e9fec20bd --- /dev/null +++ b/google/cloud/vision/v1p2beta1/geometry.proto @@ -0,0 +1,67 @@ +// Copyright 2018 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.vision.v1p2beta1; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p2beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "GeometryProto"; +option java_package = "com.google.cloud.vision.v1p2beta1"; + +// A vertex represents a 2D point in the image. +// NOTE: the vertex coordinates are in the same scale as the original image. +message Vertex { + // X coordinate. + int32 x = 1; + + // Y coordinate. + int32 y = 2; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// A bounding polygon for the detected image annotation. +message BoundingPoly { + // The bounding polygon vertices. + repeated Vertex vertices = 1; + + // The bounding polygon normalized vertices. + repeated NormalizedVertex normalized_vertices = 2; +} + +// A 3D position in the image, used primarily for Face detection landmarks. +// A valid Position must have both x and y coordinates. +// The position coordinates are in the same scale as the original image. +message Position { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; + + // Z coordinate (or depth). + float z = 3; +} diff --git a/google/cloud/vision/v1p2beta1/image_annotator.proto b/google/cloud/vision/v1p2beta1/image_annotator.proto new file mode 100644 index 000000000..c5fce50f9 --- /dev/null +++ b/google/cloud/vision/v1p2beta1/image_annotator.proto @@ -0,0 +1,765 @@ +// Copyright 2018 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.vision.v1p2beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p2beta1/geometry.proto"; +import "google/cloud/vision/v1p2beta1/text_annotation.proto"; +import "google/cloud/vision/v1p2beta1/web_detection.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; +import "google/type/color.proto"; +import "google/type/latlng.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p2beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ImageAnnotatorProto"; +option java_package = "com.google.cloud.vision.v1p2beta1"; + +// Service that performs Google Cloud Vision API detection tasks over client +// images, such as face, landmark, logo, label, and text detection. The +// ImageAnnotator service returns detected entities from the images. +service ImageAnnotator { + // Run image detection and annotation for a batch of images. + rpc BatchAnnotateImages(BatchAnnotateImagesRequest) + returns (BatchAnnotateImagesResponse) { + option (google.api.http) = { + post: "/v1p2beta1/images:annotate" + body: "*" + }; + } + + // Run async image detection and annotation for a list of generic files (e.g. + // PDF) which may contain multiple pages and multiple images per page. + // Progress and results can be retrieved through the + // `google.longrunning.Operations` interface. + // `Operation.metadata` contains `OperationMetadata` (metadata). + // `Operation.response` contains `AsyncBatchAnnotateFilesResponse` (results). + rpc AsyncBatchAnnotateFiles(AsyncBatchAnnotateFilesRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p2beta1/files:asyncBatchAnnotate" + body: "*" + }; + } +} + +// The type of Google Cloud Vision API detection to perform, and the maximum +// number of results to return for that type. Multiple `Feature` objects can +// be specified in the `features` list. +message Feature { + // Type of Google Cloud Vision API feature to be extracted. + enum Type { + // Unspecified feature type. + TYPE_UNSPECIFIED = 0; + + // Run face detection. + FACE_DETECTION = 1; + + // Run landmark detection. + LANDMARK_DETECTION = 2; + + // Run logo detection. + LOGO_DETECTION = 3; + + // Run label detection. + LABEL_DETECTION = 4; + + // Run text detection / optical character recognition (OCR). Text detection + // is optimized for areas of text within a larger image; if the image is + // a document, use `DOCUMENT_TEXT_DETECTION` instead. + TEXT_DETECTION = 5; + + // Run dense text document OCR. Takes precedence when both + // `DOCUMENT_TEXT_DETECTION` and `TEXT_DETECTION` are present. + DOCUMENT_TEXT_DETECTION = 11; + + // Run Safe Search to detect potentially unsafe + // or undesirable content. + SAFE_SEARCH_DETECTION = 6; + + // Compute a set of image properties, such as the + // image's dominant colors. + IMAGE_PROPERTIES = 7; + + // Run crop hints. + CROP_HINTS = 9; + + // Run web detection. + WEB_DETECTION = 10; + } + + // The feature type. + Type type = 1; + + // Maximum number of results of this type. Does not apply to + // `TEXT_DETECTION`, `DOCUMENT_TEXT_DETECTION`, or `CROP_HINTS`. + int32 max_results = 2; + + // Model to use for the feature. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// External image source (Google Cloud Storage or web URL image location). +message ImageSource { + // **Use `image_uri` instead.** + // + // The Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more info. + string gcs_image_uri = 1; + + // The URI of the source image. Can be either: + // + // 1. A Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more + // info. + // + // 2. A publicly-accessible image HTTP/HTTPS URL. When fetching images from + // HTTP/HTTPS URLs, Google cannot guarantee that the request will be + // completed. Your request may fail if the specified host denies the + // request (e.g. due to request throttling or DOS prevention), or if Google + // throttles requests to the site for abuse prevention. You should not + // depend on externally-hosted images for production applications. + // + // When both `gcs_image_uri` and `image_uri` are specified, `image_uri` takes + // precedence. + string image_uri = 2; +} + +// Client image to perform Google Cloud Vision API tasks over. +message Image { + // Image content, represented as a stream of bytes. + // Note: As with all `bytes` fields, protobuffers use a pure binary + // representation, whereas JSON representations use base64. + bytes content = 1; + + // Google Cloud Storage image location, or publicly-accessible image + // URL. If both `content` and `source` are provided for an image, `content` + // takes precedence and is used to perform the image annotation request. + ImageSource source = 2; +} + +// A face annotation object contains the results of face detection. +message FaceAnnotation { + // A face-specific landmark (for example, a face feature). + message Landmark { + // Face landmark (feature) type. + // Left and right are defined from the vantage of the viewer of the image + // without considering mirror projections typical of photos. So, `LEFT_EYE`, + // typically, is the person's right eye. + enum Type { + // Unknown face landmark detected. Should not be filled. + UNKNOWN_LANDMARK = 0; + + // Left eye. + LEFT_EYE = 1; + + // Right eye. + RIGHT_EYE = 2; + + // Left of left eyebrow. + LEFT_OF_LEFT_EYEBROW = 3; + + // Right of left eyebrow. + RIGHT_OF_LEFT_EYEBROW = 4; + + // Left of right eyebrow. + LEFT_OF_RIGHT_EYEBROW = 5; + + // Right of right eyebrow. + RIGHT_OF_RIGHT_EYEBROW = 6; + + // Midpoint between eyes. + MIDPOINT_BETWEEN_EYES = 7; + + // Nose tip. + NOSE_TIP = 8; + + // Upper lip. + UPPER_LIP = 9; + + // Lower lip. + LOWER_LIP = 10; + + // Mouth left. + MOUTH_LEFT = 11; + + // Mouth right. + MOUTH_RIGHT = 12; + + // Mouth center. + MOUTH_CENTER = 13; + + // Nose, bottom right. + NOSE_BOTTOM_RIGHT = 14; + + // Nose, bottom left. + NOSE_BOTTOM_LEFT = 15; + + // Nose, bottom center. + NOSE_BOTTOM_CENTER = 16; + + // Left eye, top boundary. + LEFT_EYE_TOP_BOUNDARY = 17; + + // Left eye, right corner. + LEFT_EYE_RIGHT_CORNER = 18; + + // Left eye, bottom boundary. + LEFT_EYE_BOTTOM_BOUNDARY = 19; + + // Left eye, left corner. + LEFT_EYE_LEFT_CORNER = 20; + + // Right eye, top boundary. + RIGHT_EYE_TOP_BOUNDARY = 21; + + // Right eye, right corner. + RIGHT_EYE_RIGHT_CORNER = 22; + + // Right eye, bottom boundary. + RIGHT_EYE_BOTTOM_BOUNDARY = 23; + + // Right eye, left corner. + RIGHT_EYE_LEFT_CORNER = 24; + + // Left eyebrow, upper midpoint. + LEFT_EYEBROW_UPPER_MIDPOINT = 25; + + // Right eyebrow, upper midpoint. + RIGHT_EYEBROW_UPPER_MIDPOINT = 26; + + // Left ear tragion. + LEFT_EAR_TRAGION = 27; + + // Right ear tragion. + RIGHT_EAR_TRAGION = 28; + + // Left eye pupil. + LEFT_EYE_PUPIL = 29; + + // Right eye pupil. + RIGHT_EYE_PUPIL = 30; + + // Forehead glabella. + FOREHEAD_GLABELLA = 31; + + // Chin gnathion. + CHIN_GNATHION = 32; + + // Chin left gonion. + CHIN_LEFT_GONION = 33; + + // Chin right gonion. + CHIN_RIGHT_GONION = 34; + } + + // Face landmark type. + Type type = 3; + + // Face landmark position. + Position position = 4; + } + + // The bounding polygon around the face. The coordinates of the bounding box + // are in the original image's scale, as returned in `ImageParams`. + // The bounding box is computed to "frame" the face in accordance with human + // expectations. It is based on the landmarker results. + // Note that one or more x and/or y coordinates may not be generated in the + // `BoundingPoly` (the polygon will be unbounded) if only a partial face + // appears in the image to be annotated. + BoundingPoly bounding_poly = 1; + + // The `fd_bounding_poly` bounding polygon is tighter than the + // `boundingPoly`, and encloses only the skin part of the face. Typically, it + // is used to eliminate the face from any image analysis that detects the + // "amount of skin" visible in an image. It is not based on the + // landmarker results, only on the initial face detection, hence + // the <code>fd</code> (face detection) prefix. + BoundingPoly fd_bounding_poly = 2; + + // Detected face landmarks. + repeated Landmark landmarks = 3; + + // Roll angle, which indicates the amount of clockwise/anti-clockwise rotation + // of the face relative to the image vertical about the axis perpendicular to + // the face. Range [-180,180]. + float roll_angle = 4; + + // Yaw angle, which indicates the leftward/rightward angle that the face is + // pointing relative to the vertical plane perpendicular to the image. Range + // [-180,180]. + float pan_angle = 5; + + // Pitch angle, which indicates the upwards/downwards angle that the face is + // pointing relative to the image's horizontal plane. Range [-180,180]. + float tilt_angle = 6; + + // Detection confidence. Range [0, 1]. + float detection_confidence = 7; + + // Face landmarking confidence. Range [0, 1]. + float landmarking_confidence = 8; + + // Joy likelihood. + Likelihood joy_likelihood = 9; + + // Sorrow likelihood. + Likelihood sorrow_likelihood = 10; + + // Anger likelihood. + Likelihood anger_likelihood = 11; + + // Surprise likelihood. + Likelihood surprise_likelihood = 12; + + // Under-exposed likelihood. + Likelihood under_exposed_likelihood = 13; + + // Blurred likelihood. + Likelihood blurred_likelihood = 14; + + // Headwear likelihood. + Likelihood headwear_likelihood = 15; +} + +// Detected entity location information. +message LocationInfo { + // lat/long location coordinates. + google.type.LatLng lat_lng = 1; +} + +// A `Property` consists of a user-supplied name/value pair. +message Property { + // Name of the property. + string name = 1; + + // Value of the property. + string value = 2; + + // Value of numeric properties. + uint64 uint64_value = 3; +} + +// Set of detected entity features. +message EntityAnnotation { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string mid = 1; + + // The language code for the locale in which the entity textual + // `description` is expressed. + string locale = 2; + + // Entity textual description, expressed in its `locale` language. + string description = 3; + + // Overall score of the result. Range [0, 1]. + float score = 4; + + // **Deprecated. Use `score` instead.** + // The accuracy of the entity detection in an image. + // For example, for an image in which the "Eiffel Tower" entity is detected, + // this field represents the confidence that there is a tower in the query + // image. Range [0, 1]. + float confidence = 5; + + // The relevancy of the ICA (Image Content Annotation) label to the + // image. For example, the relevancy of "tower" is likely higher to an image + // containing the detected "Eiffel Tower" than to an image containing a + // detected distant towering building, even though the confidence that + // there is a tower in each image may be the same. Range [0, 1]. + float topicality = 6; + + // Image region to which this entity belongs. Not produced + // for `LABEL_DETECTION` features. + BoundingPoly bounding_poly = 7; + + // The location information for the detected entity. Multiple + // `LocationInfo` elements can be present because one location may + // indicate the location of the scene in the image, and another location + // may indicate the location of the place where the image was taken. + // Location information is usually present for landmarks. + repeated LocationInfo locations = 8; + + // Some entities may have optional user-supplied `Property` (name/value) + // fields, such a score or string that qualifies the entity. + repeated Property properties = 9; +} + +// Set of features pertaining to the image, computed by computer vision +// methods over safe-search verticals (for example, adult, spoof, medical, +// violence). +message SafeSearchAnnotation { + // Represents the adult content likelihood for the image. Adult content may + // contain elements such as nudity, pornographic images or cartoons, or + // sexual activities. + Likelihood adult = 1; + + // Spoof likelihood. The likelihood that an modification + // was made to the image's canonical version to make it appear + // funny or offensive. + Likelihood spoof = 2; + + // Likelihood that this is a medical image. + Likelihood medical = 3; + + // Likelihood that this image contains violent content. + Likelihood violence = 4; + + // Likelihood that the request image contains racy content. Racy content may + // include (but is not limited to) skimpy or sheer clothing, strategically + // covered nudity, lewd or provocative poses, or close-ups of sensitive + // body areas. + Likelihood racy = 9; +} + +// Rectangle determined by min and max `LatLng` pairs. +message LatLongRect { + // Min lat/long pair. + google.type.LatLng min_lat_lng = 1; + + // Max lat/long pair. + google.type.LatLng max_lat_lng = 2; +} + +// Color information consists of RGB channels, score, and the fraction of +// the image that the color occupies in the image. +message ColorInfo { + // RGB components of the color. + google.type.Color color = 1; + + // Image-specific score for this color. Value in range [0, 1]. + float score = 2; + + // The fraction of pixels the color occupies in the image. + // Value in range [0, 1]. + float pixel_fraction = 3; +} + +// Set of dominant colors and their corresponding scores. +message DominantColorsAnnotation { + // RGB color values with their score and pixel fraction. + repeated ColorInfo colors = 1; +} + +// Stores image properties, such as dominant colors. +message ImageProperties { + // If present, dominant colors completed successfully. + DominantColorsAnnotation dominant_colors = 1; +} + +// Single crop hint that is used to generate a new crop when serving an image. +message CropHint { + // The bounding polygon for the crop region. The coordinates of the bounding + // box are in the original image's scale, as returned in `ImageParams`. + BoundingPoly bounding_poly = 1; + + // Confidence of this being a salient region. Range [0, 1]. + float confidence = 2; + + // Fraction of importance of this salient region with respect to the original + // image. + float importance_fraction = 3; +} + +// Set of crop hints that are used to generate new crops when serving images. +message CropHintsAnnotation { + // Crop hint results. + repeated CropHint crop_hints = 1; +} + +// Parameters for crop hints annotation request. +message CropHintsParams { + // Aspect ratios in floats, representing the ratio of the width to the height + // of the image. For example, if the desired aspect ratio is 4/3, the + // corresponding float value should be 1.33333. If not specified, the + // best possible crop is returned. The number of provided aspect ratios is + // limited to a maximum of 16; any aspect ratios provided after the 16th are + // ignored. + repeated float aspect_ratios = 1; +} + +// Parameters for web detection request. +message WebDetectionParams { + // Whether to include results derived from the geo information in the image. + bool include_geo_results = 2; +} + +// Image context and/or feature-specific parameters. +message ImageContext { + // Not used. + LatLongRect lat_long_rect = 1; + + // List of languages to use for TEXT_DETECTION. In most cases, an empty value + // yields the best results since it enables automatic language detection. For + // languages based on the Latin alphabet, setting `language_hints` is not + // needed. In rare cases, when the language of the text in the image is known, + // setting a hint will help get better results (although it will be a + // significant hindrance if the hint is wrong). Text detection returns an + // error if one or more of the specified languages is not one of the + // [supported languages](/vision/docs/languages). + repeated string language_hints = 2; + + // Parameters for crop hints annotation request. + CropHintsParams crop_hints_params = 4; + + // Parameters for web detection. + WebDetectionParams web_detection_params = 6; +} + +// Request for performing Google Cloud Vision API tasks over a user-provided +// image, with user-requested features. +message AnnotateImageRequest { + // The image to be processed. + Image image = 1; + + // Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image. + ImageContext image_context = 3; +} + +// If an image was produced from a file (e.g. a PDF), this message gives +// information about the source of that image. +message ImageAnnotationContext { + // The URI of the file used to produce the image. + string uri = 1; + + // If the file was a PDF or TIFF, this field gives the page number within + // the file used to produce the image. + int32 page_number = 2; +} + +// Response to an image annotation request. +message AnnotateImageResponse { + // If present, face detection has completed successfully. + repeated FaceAnnotation face_annotations = 1; + + // If present, landmark detection has completed successfully. + repeated EntityAnnotation landmark_annotations = 2; + + // If present, logo detection has completed successfully. + repeated EntityAnnotation logo_annotations = 3; + + // If present, label detection has completed successfully. + repeated EntityAnnotation label_annotations = 4; + + // If present, text (OCR) detection has completed successfully. + repeated EntityAnnotation text_annotations = 5; + + // If present, text (OCR) detection or document (OCR) text detection has + // completed successfully. + // This annotation provides the structural hierarchy for the OCR detected + // text. + TextAnnotation full_text_annotation = 12; + + // If present, safe-search annotation has completed successfully. + SafeSearchAnnotation safe_search_annotation = 6; + + // If present, image properties were extracted successfully. + ImageProperties image_properties_annotation = 8; + + // If present, crop hints have completed successfully. + CropHintsAnnotation crop_hints_annotation = 11; + + // If present, web detection has completed successfully. + WebDetection web_detection = 13; + + // If set, represents the error message for the operation. + // Note that filled-in image annotations are guaranteed to be + // correct, even when `error` is set. + google.rpc.Status error = 9; + + // If present, contextual information is needed to understand where this image + // comes from. + ImageAnnotationContext context = 21; +} + +// Response to a single file annotation request. A file may contain one or more +// images, which individually have their own responses. +message AnnotateFileResponse { + // Information about the file for which this response is generated. + InputConfig input_config = 1; + + // Individual responses to images found within the file. + repeated AnnotateImageResponse responses = 2; +} + +// Multiple image annotation requests are batched into a single service call. +message BatchAnnotateImagesRequest { + // Individual image annotation requests for this batch. + repeated AnnotateImageRequest requests = 1; +} + +// Response to a batch image annotation request. +message BatchAnnotateImagesResponse { + // Individual responses to image annotation requests within the batch. + repeated AnnotateImageResponse responses = 1; +} + +// An offline file annotation request. +message AsyncAnnotateFileRequest { + // Required. Information about the input file. + InputConfig input_config = 1; + + // Required. Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image(s) in the file. + ImageContext image_context = 3; + + // Required. The desired output location and metadata (e.g. format). + OutputConfig output_config = 4; +} + +// The response for a single offline file annotation request. +message AsyncAnnotateFileResponse { + // The output location and metadata from AsyncAnnotateFileRequest. + OutputConfig output_config = 1; +} + +// Multiple async file annotation requests are batched into a single service +// call. +message AsyncBatchAnnotateFilesRequest { + // Individual async file annotation requests for this batch. + repeated AsyncAnnotateFileRequest requests = 1; +} + +// Response to an async batch file annotation request. +message AsyncBatchAnnotateFilesResponse { + // The list of file annotation responses, one for each request in + // AsyncBatchAnnotateFilesRequest. + repeated AsyncAnnotateFileResponse responses = 1; +} + +// The desired input location and metadata. +message InputConfig { + // The Google Cloud Storage location to read the input from. + GcsSource gcs_source = 1; + + // The type of the file. Currently only "application/pdf" and "image/tiff" + // are supported. Wildcards are not supported. + string mime_type = 2; +} + +// The desired output location and metadata. +message OutputConfig { + // The Google Cloud Storage location to write the output(s) to. + GcsDestination gcs_destination = 1; + + // The max number of response protos to put into each output JSON file on GCS. + // The valid range is [1, 100]. If not specified, the default value is 20. + // + // For example, for one pdf file with 100 pages, 100 response protos will + // be generated. If `batch_size` = 20, then 5 json files each + // containing 20 response protos will be written under the prefix + // `gcs_destination`.`uri`. + // + // Currently, batch_size only applies to GcsDestination, with potential future + // support for other output configurations. + int32 batch_size = 2; +} + +// The Google Cloud Storage location where the input will be read from. +message GcsSource { + // Google Cloud Storage URI for the input file. This must only be a GCS + // object. Wildcards are not currently supported. + string uri = 1; +} + +// The Google Cloud Storage location where the output will be written to. +message GcsDestination { + // Google Cloud Storage URI where the results will be stored. Results will + // be in JSON format and preceded by its corresponding input URI. This field + // can either represent a single file, or a prefix for multiple outputs. + // Prefixes must end in a `/`. + // + // Examples: + // + // * File: gs://bucket-name/filename.json + // * Prefix: gs://bucket-name/prefix/here/ + // * File: gs://bucket-name/prefix/here + // + // If multiple outputs, each response is still AnnotateFileResponse, each of + // which contains some subset of the full list of AnnotateImageResponse. + // Multiple outputs can happen if, for example, the output JSON is too large + // and overflows into multiple sharded files. + string uri = 1; +} + +// Contains metadata for the BatchAnnotateImages operation. +message OperationMetadata { + // Batch operation states. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is received. + CREATED = 1; + + // Request is actively being processed. + RUNNING = 2; + + // The batch processing is done. + DONE = 3; + + // The batch processing was cancelled. + CANCELLED = 4; + } + + // Current state of the batch operation. + State state = 1; + + // The time when the batch request was received. + google.protobuf.Timestamp create_time = 5; + + // The time when the operation result was last updated. + google.protobuf.Timestamp update_time = 6; +} + +// A bucketized representation of likelihood, which is intended to give clients +// highly stable results across model upgrades. +enum Likelihood { + // Unknown likelihood. + UNKNOWN = 0; + + // It is very unlikely that the image belongs to the specified vertical. + VERY_UNLIKELY = 1; + + // It is unlikely that the image belongs to the specified vertical. + UNLIKELY = 2; + + // It is possible that the image belongs to the specified vertical. + POSSIBLE = 3; + + // It is likely that the image belongs to the specified vertical. + LIKELY = 4; + + // It is very likely that the image belongs to the specified vertical. + VERY_LIKELY = 5; +} diff --git a/google/cloud/vision/v1p2beta1/text_annotation.proto b/google/cloud/vision/v1p2beta1/text_annotation.proto new file mode 100644 index 000000000..b35eb47e8 --- /dev/null +++ b/google/cloud/vision/v1p2beta1/text_annotation.proto @@ -0,0 +1,259 @@ +// Copyright 2018 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.vision.v1p2beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p2beta1/geometry.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p2beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "TextAnnotationProto"; +option java_package = "com.google.cloud.vision.v1p2beta1"; + +// TextAnnotation contains a structured representation of OCR extracted text. +// The hierarchy of an OCR extracted text structure is like this: +// TextAnnotation -> Page -> Block -> Paragraph -> Word -> Symbol +// Each structural component, starting from Page, may further have their own +// properties. Properties describe detected languages, breaks etc.. Please refer +// to the +// [TextAnnotation.TextProperty][google.cloud.vision.v1p2beta1.TextAnnotation.TextProperty] +// message definition below for more detail. +message TextAnnotation { + // Detected language for a structural component. + message DetectedLanguage { + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 1; + + // Confidence of detected language. Range [0, 1]. + float confidence = 2; + } + + // Detected start or end of a structural component. + message DetectedBreak { + // Enum to denote the type of break found. New line, space etc. + enum BreakType { + // Unknown break label type. + UNKNOWN = 0; + + // Regular space. + SPACE = 1; + + // Sure space (very wide). + SURE_SPACE = 2; + + // Line-wrapping break. + EOL_SURE_SPACE = 3; + + // End-line hyphen that is not present in text; does not co-occur with + // `SPACE`, `LEADER_SPACE`, or `LINE_BREAK`. + HYPHEN = 4; + + // Line break that ends a paragraph. + LINE_BREAK = 5; + } + + // Detected break type. + BreakType type = 1; + + // True if break prepends the element. + bool is_prefix = 2; + } + + // Additional information detected on the structural component. + message TextProperty { + // A list of detected languages together with confidence. + repeated DetectedLanguage detected_languages = 1; + + // Detected start or end of a text segment. + DetectedBreak detected_break = 2; + } + + // List of pages detected by OCR. + repeated Page pages = 1; + + // UTF-8 text detected on the pages. + string text = 2; +} + +// Detected page from OCR. +message Page { + // Additional information detected on the page. + TextAnnotation.TextProperty property = 1; + + // Page width. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 width = 2; + + // Page height. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 height = 3; + + // List of blocks of text, images etc on this page. + repeated Block blocks = 4; + + // Confidence of the OCR results on the page. Range [0, 1]. + float confidence = 5; +} + +// Logical element on the page. +message Block { + // Type of a block (text, image etc) as identified by OCR. + enum BlockType { + // Unknown block type. + UNKNOWN = 0; + + // Regular text block. + TEXT = 1; + + // Table block. + TABLE = 2; + + // Image block. + PICTURE = 3; + + // Horizontal/vertical line box. + RULER = 4; + + // Barcode block. + BARCODE = 5; + } + + // Additional information detected for the block. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the block. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // + // * when the text is horizontal it might look like: + // + // 0----1 + // | | + // 3----2 + // + // * when it's rotated 180 degrees around the top-left corner it becomes: + // + // 2----3 + // | | + // 1----0 + // + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of paragraphs in this block (if this blocks is of type text). + repeated Paragraph paragraphs = 3; + + // Detected block type (text, image etc) for this block. + BlockType block_type = 4; + + // Confidence of the OCR results on the block. Range [0, 1]. + float confidence = 5; +} + +// Structural unit of text representing a number of words in certain order. +message Paragraph { + // Additional information detected for the paragraph. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the paragraph. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of words in this paragraph. + repeated Word words = 3; + + // Confidence of the OCR results for the paragraph. Range [0, 1]. + float confidence = 4; +} + +// A word representation. +message Word { + // Additional information detected for the word. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the word. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of symbols in the word. + // The order of the symbols follows the natural reading order. + repeated Symbol symbols = 3; + + // Confidence of the OCR results for the word. Range [0, 1]. + float confidence = 4; +} + +// A single symbol representation. +message Symbol { + // Additional information detected for the symbol. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the symbol. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // The actual UTF-8 representation of the symbol. + string text = 3; + + // Confidence of the OCR results for the symbol. Range [0, 1]. + float confidence = 4; +} diff --git a/google/cloud/vision/v1p2beta1/vision_gapic.yaml b/google/cloud/vision/v1p2beta1/vision_gapic.yaml new file mode 100644 index 000000000..41d5c49b4 --- /dev/null +++ b/google/cloud/vision/v1p2beta1/vision_gapic.yaml @@ -0,0 +1,72 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.vision.v1p2beta1 + python: + package_name: google.cloud.vision_v1p2beta1.gapic + go: + package_name: cloud.google.com/go/vision/apiv1p2beta1 + release_level: BETA + csharp: + package_name: Google.Cloud.Vision.V1P2Beta1 + release_level: BETA + ruby: + package_name: Google::Cloud::Vision::V1p2beta1 + php: + package_name: Google\Cloud\Vision\V1p2beta1 + nodejs: + package_name: vision.v1p2beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.vision.v1p2beta1.ImageAnnotator + smoke_test: + method: BatchAnnotateImages + init_fields: + - requests[0].image.source.gcs_image_uri="gs://gapic-toolkit/President_Barack_Obama.jpg" + - requests[0].features[0].type=FACE_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + methods: + - name: BatchAnnotateImages + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AsyncBatchAnnotateFiles + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + long_running: + return_type: google.cloud.vision.v1p2beta1.AsyncBatchAnnotateFilesResponse + metadata_type: google.cloud.vision.v1p2beta1.OperationMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/vision/v1p2beta1/web_detection.proto b/google/cloud/vision/v1p2beta1/web_detection.proto new file mode 100644 index 000000000..f2b9dfef0 --- /dev/null +++ b/google/cloud/vision/v1p2beta1/web_detection.proto @@ -0,0 +1,104 @@ +// Copyright 2018 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.vision.v1p2beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p2beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "WebDetectionProto"; +option java_package = "com.google.cloud.vision.v1p2beta1"; + +// Relevant information for the image from the Internet. +message WebDetection { + // Entity deduced from similar images on the Internet. + message WebEntity { + // Opaque entity ID. + string entity_id = 1; + + // Overall relevancy score for the entity. + // Not normalized and not comparable across different image queries. + float score = 2; + + // Canonical description of the entity, in English. + string description = 3; + } + + // Metadata for online images. + message WebImage { + // The result image URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the image. + float score = 2; + } + + // Metadata for web pages. + message WebPage { + // The result web page URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the web page. + float score = 2; + + // Title for the web page, may contain HTML markups. + string page_title = 3; + + // Fully matching images on the page. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 4; + + // Partial matching images on the page. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its + // crops. + repeated WebImage partial_matching_images = 5; + } + + // Label to provide extra metadata for the web detection. + message WebLabel { + // Label for extra metadata. + string label = 1; + + // The BCP-47 language code for `label`, such as "en-US" or "sr-Latn". + // For more information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + } + + // Deduced entities from similar images on the Internet. + repeated WebEntity web_entities = 1; + + // Fully matching images from the Internet. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 2; + + // Partial matching images from the Internet. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its crops. + repeated WebImage partial_matching_images = 3; + + // Web pages containing the matching images from the Internet. + repeated WebPage pages_with_matching_images = 4; + + // The visually similar image results. + repeated WebImage visually_similar_images = 6; + + // Best guess text labels for the request image. + repeated WebLabel best_guess_labels = 8; +} diff --git a/google/cloud/vision/v1p3beta1/BUILD.bazel b/google/cloud/vision/v1p3beta1/BUILD.bazel new file mode 100644 index 000000000..05aeded73 --- /dev/null +++ b/google/cloud/vision/v1p3beta1/BUILD.bazel @@ -0,0 +1,158 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "vision_proto", + srcs = [ + "geometry.proto", + "image_annotator.proto", + "product_search.proto", + "product_search_service.proto", + "text_annotation.proto", + "web_detection.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "//google/type:color_proto", + "//google/type:latlng_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "vision_proto_with_info", + deps = [":vision_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "vision_java_proto", + deps = [":vision_proto"], +) + +java_grpc_library( + name = "vision_java_grpc", + srcs = [":vision_proto"], + deps = [":vision_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "vision_resource_name_java_proto", + gapic_yaml = "vision_gapic.yaml", + deps = [":vision_proto"], +) + +java_gapic_library( + name = "vision_java_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + service_yaml = "//google/cloud/vision:vision_v1p3beta1.yaml", + test_deps = [":vision_java_grpc"], + deps = [ + ":vision_java_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":vision_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.vision.v1p3beta1.ImageAnnotatorClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-vision-v1p3beta1-java", + client_deps = [":vision_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":vision_java_gapic_test"], + grpc_deps = [":vision_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":vision_java_proto", + ":vision_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "vision_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/vision/v1p3beta1", + protos = [":vision_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + "//google/type:color_go_proto", + "//google/type:latlng_go_proto", + ], +) + +go_gapic_library( + name = "vision_go_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + importpath = "cloud.google.com/go/vision/apiv1p3beta1", + service_yaml = "//google/cloud/vision:vision_v1p3beta1.yaml", + deps = [ + ":vision_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "vision_go_gapic_test", + srcs = [":vision_go_gapic_srcjar_test"], + embed = [":vision_go_gapic"], + importpath = "cloud.google.com/go/vision/apiv1p3beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-vision-v1p3beta1-go", + deps = [ + ":vision_go_gapic", + ":vision_go_gapic_srcjar-smoke-test.srcjar", + ":vision_go_gapic_srcjar-test.srcjar", + ":vision_go_proto", + ], +)
\ No newline at end of file diff --git a/google/cloud/vision/v1p3beta1/geometry.proto b/google/cloud/vision/v1p3beta1/geometry.proto new file mode 100644 index 000000000..28b768eaa --- /dev/null +++ b/google/cloud/vision/v1p3beta1/geometry.proto @@ -0,0 +1,75 @@ +// Copyright 2018 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.vision.v1p3beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p3beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "GeometryProto"; +option java_package = "com.google.cloud.vision.v1p3beta1"; + +// A vertex represents a 2D point in the image. +// NOTE: the vertex coordinates are in the same scale as the original image. +message Vertex { + // X coordinate. + int32 x = 1; + + // Y coordinate. + int32 y = 2; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// A bounding polygon for the detected image annotation. +message BoundingPoly { + // The bounding polygon vertices. + repeated Vertex vertices = 1; + + // The bounding polygon normalized vertices. + repeated NormalizedVertex normalized_vertices = 2; +} + +// A normalized bounding polygon around a portion of an image. +message NormalizedBoundingPoly { + // Normalized vertices of the bounding polygon. + repeated NormalizedVertex vertices = 1; +} + +// A 3D position in the image, used primarily for Face detection landmarks. +// A valid Position must have both x and y coordinates. +// The position coordinates are in the same scale as the original image. +message Position { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; + + // Z coordinate (or depth). + float z = 3; +} diff --git a/google/cloud/vision/v1p3beta1/image_annotator.proto b/google/cloud/vision/v1p3beta1/image_annotator.proto new file mode 100644 index 000000000..2ac3ddb8b --- /dev/null +++ b/google/cloud/vision/v1p3beta1/image_annotator.proto @@ -0,0 +1,803 @@ +// Copyright 2018 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.vision.v1p3beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p3beta1/geometry.proto"; +import "google/cloud/vision/v1p3beta1/product_search.proto"; +import "google/cloud/vision/v1p3beta1/text_annotation.proto"; +import "google/cloud/vision/v1p3beta1/web_detection.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; +import "google/type/color.proto"; +import "google/type/latlng.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p3beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ImageAnnotatorProto"; +option java_package = "com.google.cloud.vision.v1p3beta1"; + +// Service that performs Google Cloud Vision API detection tasks over client +// images, such as face, landmark, logo, label, and text detection. The +// ImageAnnotator service returns detected entities from the images. +service ImageAnnotator { + // Run image detection and annotation for a batch of images. + rpc BatchAnnotateImages(BatchAnnotateImagesRequest) + returns (BatchAnnotateImagesResponse) { + option (google.api.http) = { + post: "/v1p3beta1/images:annotate" + body: "*" + }; + } + + // Run asynchronous image detection and annotation for a list of generic + // files, such as PDF files, which may contain multiple pages and multiple + // images per page. Progress and results can be retrieved through the + // `google.longrunning.Operations` interface. + // `Operation.metadata` contains `OperationMetadata` (metadata). + // `Operation.response` contains `AsyncBatchAnnotateFilesResponse` (results). + rpc AsyncBatchAnnotateFiles(AsyncBatchAnnotateFilesRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p3beta1/files:asyncBatchAnnotate" + body: "*" + }; + } +} + +// The type of Google Cloud Vision API detection to perform, and the maximum +// number of results to return for that type. Multiple `Feature` objects can +// be specified in the `features` list. +message Feature { + // Type of Google Cloud Vision API feature to be extracted. + enum Type { + // Unspecified feature type. + TYPE_UNSPECIFIED = 0; + + // Run face detection. + FACE_DETECTION = 1; + + // Run landmark detection. + LANDMARK_DETECTION = 2; + + // Run logo detection. + LOGO_DETECTION = 3; + + // Run label detection. + LABEL_DETECTION = 4; + + // Run text detection / optical character recognition (OCR). Text detection + // is optimized for areas of text within a larger image; if the image is + // a document, use `DOCUMENT_TEXT_DETECTION` instead. + TEXT_DETECTION = 5; + + // Run dense text document OCR. Takes precedence when both + // `DOCUMENT_TEXT_DETECTION` and `TEXT_DETECTION` are present. + DOCUMENT_TEXT_DETECTION = 11; + + // Run Safe Search to detect potentially unsafe + // or undesirable content. + SAFE_SEARCH_DETECTION = 6; + + // Compute a set of image properties, such as the + // image's dominant colors. + IMAGE_PROPERTIES = 7; + + // Run crop hints. + CROP_HINTS = 9; + + // Run web detection. + WEB_DETECTION = 10; + + // Run Product Search. + PRODUCT_SEARCH = 12; + + // Run localizer for object detection. + OBJECT_LOCALIZATION = 19; + } + + // The feature type. + Type type = 1; + + // Maximum number of results of this type. Does not apply to + // `TEXT_DETECTION`, `DOCUMENT_TEXT_DETECTION`, or `CROP_HINTS`. + int32 max_results = 2; + + // Model to use for the feature. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// External image source (Google Cloud Storage or web URL image location). +message ImageSource { + // **Use `image_uri` instead.** + // + // The Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more info. + string gcs_image_uri = 1; + + // The URI of the source image. Can be either: + // + // 1. A Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more + // info. + // + // 2. A publicly-accessible image HTTP/HTTPS URL. When fetching images from + // HTTP/HTTPS URLs, Google cannot guarantee that the request will be + // completed. Your request may fail if the specified host denies the + // request (e.g. due to request throttling or DOS prevention), or if Google + // throttles requests to the site for abuse prevention. You should not + // depend on externally-hosted images for production applications. + // + // When both `gcs_image_uri` and `image_uri` are specified, `image_uri` takes + // precedence. + string image_uri = 2; +} + +// Client image to perform Google Cloud Vision API tasks over. +message Image { + // Image content, represented as a stream of bytes. + // Note: As with all `bytes` fields, protobuffers use a pure binary + // representation, whereas JSON representations use base64. + bytes content = 1; + + // Google Cloud Storage image location, or publicly-accessible image + // URL. If both `content` and `source` are provided for an image, `content` + // takes precedence and is used to perform the image annotation request. + ImageSource source = 2; +} + +// A face annotation object contains the results of face detection. +message FaceAnnotation { + // A face-specific landmark (for example, a face feature). + message Landmark { + // Face landmark (feature) type. + // Left and right are defined from the vantage of the viewer of the image + // without considering mirror projections typical of photos. So, `LEFT_EYE`, + // typically, is the person's right eye. + enum Type { + // Unknown face landmark detected. Should not be filled. + UNKNOWN_LANDMARK = 0; + + // Left eye. + LEFT_EYE = 1; + + // Right eye. + RIGHT_EYE = 2; + + // Left of left eyebrow. + LEFT_OF_LEFT_EYEBROW = 3; + + // Right of left eyebrow. + RIGHT_OF_LEFT_EYEBROW = 4; + + // Left of right eyebrow. + LEFT_OF_RIGHT_EYEBROW = 5; + + // Right of right eyebrow. + RIGHT_OF_RIGHT_EYEBROW = 6; + + // Midpoint between eyes. + MIDPOINT_BETWEEN_EYES = 7; + + // Nose tip. + NOSE_TIP = 8; + + // Upper lip. + UPPER_LIP = 9; + + // Lower lip. + LOWER_LIP = 10; + + // Mouth left. + MOUTH_LEFT = 11; + + // Mouth right. + MOUTH_RIGHT = 12; + + // Mouth center. + MOUTH_CENTER = 13; + + // Nose, bottom right. + NOSE_BOTTOM_RIGHT = 14; + + // Nose, bottom left. + NOSE_BOTTOM_LEFT = 15; + + // Nose, bottom center. + NOSE_BOTTOM_CENTER = 16; + + // Left eye, top boundary. + LEFT_EYE_TOP_BOUNDARY = 17; + + // Left eye, right corner. + LEFT_EYE_RIGHT_CORNER = 18; + + // Left eye, bottom boundary. + LEFT_EYE_BOTTOM_BOUNDARY = 19; + + // Left eye, left corner. + LEFT_EYE_LEFT_CORNER = 20; + + // Right eye, top boundary. + RIGHT_EYE_TOP_BOUNDARY = 21; + + // Right eye, right corner. + RIGHT_EYE_RIGHT_CORNER = 22; + + // Right eye, bottom boundary. + RIGHT_EYE_BOTTOM_BOUNDARY = 23; + + // Right eye, left corner. + RIGHT_EYE_LEFT_CORNER = 24; + + // Left eyebrow, upper midpoint. + LEFT_EYEBROW_UPPER_MIDPOINT = 25; + + // Right eyebrow, upper midpoint. + RIGHT_EYEBROW_UPPER_MIDPOINT = 26; + + // Left ear tragion. + LEFT_EAR_TRAGION = 27; + + // Right ear tragion. + RIGHT_EAR_TRAGION = 28; + + // Left eye pupil. + LEFT_EYE_PUPIL = 29; + + // Right eye pupil. + RIGHT_EYE_PUPIL = 30; + + // Forehead glabella. + FOREHEAD_GLABELLA = 31; + + // Chin gnathion. + CHIN_GNATHION = 32; + + // Chin left gonion. + CHIN_LEFT_GONION = 33; + + // Chin right gonion. + CHIN_RIGHT_GONION = 34; + } + + // Face landmark type. + Type type = 3; + + // Face landmark position. + Position position = 4; + } + + // The bounding polygon around the face. The coordinates of the bounding box + // are in the original image's scale, as returned in `ImageParams`. + // The bounding box is computed to "frame" the face in accordance with human + // expectations. It is based on the landmarker results. + // Note that one or more x and/or y coordinates may not be generated in the + // `BoundingPoly` (the polygon will be unbounded) if only a partial face + // appears in the image to be annotated. + BoundingPoly bounding_poly = 1; + + // The `fd_bounding_poly` bounding polygon is tighter than the + // `boundingPoly`, and encloses only the skin part of the face. Typically, it + // is used to eliminate the face from any image analysis that detects the + // "amount of skin" visible in an image. It is not based on the + // landmarker results, only on the initial face detection, hence + // the <code>fd</code> (face detection) prefix. + BoundingPoly fd_bounding_poly = 2; + + // Detected face landmarks. + repeated Landmark landmarks = 3; + + // Roll angle, which indicates the amount of clockwise/anti-clockwise rotation + // of the face relative to the image vertical about the axis perpendicular to + // the face. Range [-180,180]. + float roll_angle = 4; + + // Yaw angle, which indicates the leftward/rightward angle that the face is + // pointing relative to the vertical plane perpendicular to the image. Range + // [-180,180]. + float pan_angle = 5; + + // Pitch angle, which indicates the upwards/downwards angle that the face is + // pointing relative to the image's horizontal plane. Range [-180,180]. + float tilt_angle = 6; + + // Detection confidence. Range [0, 1]. + float detection_confidence = 7; + + // Face landmarking confidence. Range [0, 1]. + float landmarking_confidence = 8; + + // Joy likelihood. + Likelihood joy_likelihood = 9; + + // Sorrow likelihood. + Likelihood sorrow_likelihood = 10; + + // Anger likelihood. + Likelihood anger_likelihood = 11; + + // Surprise likelihood. + Likelihood surprise_likelihood = 12; + + // Under-exposed likelihood. + Likelihood under_exposed_likelihood = 13; + + // Blurred likelihood. + Likelihood blurred_likelihood = 14; + + // Headwear likelihood. + Likelihood headwear_likelihood = 15; +} + +// Detected entity location information. +message LocationInfo { + // lat/long location coordinates. + google.type.LatLng lat_lng = 1; +} + +// A `Property` consists of a user-supplied name/value pair. +message Property { + // Name of the property. + string name = 1; + + // Value of the property. + string value = 2; + + // Value of numeric properties. + uint64 uint64_value = 3; +} + +// Set of detected entity features. +message EntityAnnotation { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string mid = 1; + + // The language code for the locale in which the entity textual + // `description` is expressed. + string locale = 2; + + // Entity textual description, expressed in its `locale` language. + string description = 3; + + // Overall score of the result. Range [0, 1]. + float score = 4; + + // **Deprecated. Use `score` instead.** + // The accuracy of the entity detection in an image. + // For example, for an image in which the "Eiffel Tower" entity is detected, + // this field represents the confidence that there is a tower in the query + // image. Range [0, 1]. + float confidence = 5; + + // The relevancy of the ICA (Image Content Annotation) label to the + // image. For example, the relevancy of "tower" is likely higher to an image + // containing the detected "Eiffel Tower" than to an image containing a + // detected distant towering building, even though the confidence that + // there is a tower in each image may be the same. Range [0, 1]. + float topicality = 6; + + // Image region to which this entity belongs. Not produced + // for `LABEL_DETECTION` features. + BoundingPoly bounding_poly = 7; + + // The location information for the detected entity. Multiple + // `LocationInfo` elements can be present because one location may + // indicate the location of the scene in the image, and another location + // may indicate the location of the place where the image was taken. + // Location information is usually present for landmarks. + repeated LocationInfo locations = 8; + + // Some entities may have optional user-supplied `Property` (name/value) + // fields, such a score or string that qualifies the entity. + repeated Property properties = 9; +} + +// Set of detected objects with bounding boxes. +message LocalizedObjectAnnotation { + // Object ID that should align with EntityAnnotation mid. + string mid = 1; + + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + + // Object name, expressed in its `language_code` language. + string name = 3; + + // Score of the result. Range [0, 1]. + float score = 4; + + // Image region to which this object belongs. This must be populated. + BoundingPoly bounding_poly = 5; +} + +// Set of features pertaining to the image, computed by computer vision +// methods over safe-search verticals (for example, adult, spoof, medical, +// violence). +message SafeSearchAnnotation { + // Represents the adult content likelihood for the image. Adult content may + // contain elements such as nudity, pornographic images or cartoons, or + // sexual activities. + Likelihood adult = 1; + + // Spoof likelihood. The likelihood that an modification + // was made to the image's canonical version to make it appear + // funny or offensive. + Likelihood spoof = 2; + + // Likelihood that this is a medical image. + Likelihood medical = 3; + + // Likelihood that this image contains violent content. + Likelihood violence = 4; + + // Likelihood that the request image contains racy content. Racy content may + // include (but is not limited to) skimpy or sheer clothing, strategically + // covered nudity, lewd or provocative poses, or close-ups of sensitive + // body areas. + Likelihood racy = 9; +} + +// Rectangle determined by min and max `LatLng` pairs. +message LatLongRect { + // Min lat/long pair. + google.type.LatLng min_lat_lng = 1; + + // Max lat/long pair. + google.type.LatLng max_lat_lng = 2; +} + +// Color information consists of RGB channels, score, and the fraction of +// the image that the color occupies in the image. +message ColorInfo { + // RGB components of the color. + google.type.Color color = 1; + + // Image-specific score for this color. Value in range [0, 1]. + float score = 2; + + // The fraction of pixels the color occupies in the image. + // Value in range [0, 1]. + float pixel_fraction = 3; +} + +// Set of dominant colors and their corresponding scores. +message DominantColorsAnnotation { + // RGB color values with their score and pixel fraction. + repeated ColorInfo colors = 1; +} + +// Stores image properties, such as dominant colors. +message ImageProperties { + // If present, dominant colors completed successfully. + DominantColorsAnnotation dominant_colors = 1; +} + +// Single crop hint that is used to generate a new crop when serving an image. +message CropHint { + // The bounding polygon for the crop region. The coordinates of the bounding + // box are in the original image's scale, as returned in `ImageParams`. + BoundingPoly bounding_poly = 1; + + // Confidence of this being a salient region. Range [0, 1]. + float confidence = 2; + + // Fraction of importance of this salient region with respect to the original + // image. + float importance_fraction = 3; +} + +// Set of crop hints that are used to generate new crops when serving images. +message CropHintsAnnotation { + // Crop hint results. + repeated CropHint crop_hints = 1; +} + +// Parameters for crop hints annotation request. +message CropHintsParams { + // Aspect ratios in floats, representing the ratio of the width to the height + // of the image. For example, if the desired aspect ratio is 4/3, the + // corresponding float value should be 1.33333. If not specified, the + // best possible crop is returned. The number of provided aspect ratios is + // limited to a maximum of 16; any aspect ratios provided after the 16th are + // ignored. + repeated float aspect_ratios = 1; +} + +// Parameters for web detection request. +message WebDetectionParams { + // Whether to include results derived from the geo information in the image. + bool include_geo_results = 2; +} + +// Image context and/or feature-specific parameters. +message ImageContext { + // Not used. + LatLongRect lat_long_rect = 1; + + // List of languages to use for TEXT_DETECTION. In most cases, an empty value + // yields the best results since it enables automatic language detection. For + // languages based on the Latin alphabet, setting `language_hints` is not + // needed. In rare cases, when the language of the text in the image is known, + // setting a hint will help get better results (although it will be a + // significant hindrance if the hint is wrong). Text detection returns an + // error if one or more of the specified languages is not one of the + // [supported languages](/vision/docs/languages). + repeated string language_hints = 2; + + // Parameters for crop hints annotation request. + CropHintsParams crop_hints_params = 4; + + // Parameters for product search. + google.cloud.vision.v1p3beta1.ProductSearchParams product_search_params = 5; + + // Parameters for web detection. + WebDetectionParams web_detection_params = 6; +} + +// Request for performing Google Cloud Vision API tasks over a user-provided +// image, with user-requested features. +message AnnotateImageRequest { + // The image to be processed. + Image image = 1; + + // Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image. + ImageContext image_context = 3; +} + +// If an image was produced from a file (e.g. a PDF), this message gives +// information about the source of that image. +message ImageAnnotationContext { + // The URI of the file used to produce the image. + string uri = 1; + + // If the file was a PDF or TIFF, this field gives the page number within + // the file used to produce the image. + int32 page_number = 2; +} + +// Response to an image annotation request. +message AnnotateImageResponse { + // If present, face detection has completed successfully. + repeated FaceAnnotation face_annotations = 1; + + // If present, landmark detection has completed successfully. + repeated EntityAnnotation landmark_annotations = 2; + + // If present, logo detection has completed successfully. + repeated EntityAnnotation logo_annotations = 3; + + // If present, label detection has completed successfully. + repeated EntityAnnotation label_annotations = 4; + + // If present, localized object detection has completed successfully. + // This will be sorted descending by confidence score. + repeated LocalizedObjectAnnotation localized_object_annotations = 22; + + // If present, text (OCR) detection has completed successfully. + repeated EntityAnnotation text_annotations = 5; + + // If present, text (OCR) detection or document (OCR) text detection has + // completed successfully. + // This annotation provides the structural hierarchy for the OCR detected + // text. + TextAnnotation full_text_annotation = 12; + + // If present, safe-search annotation has completed successfully. + SafeSearchAnnotation safe_search_annotation = 6; + + // If present, image properties were extracted successfully. + ImageProperties image_properties_annotation = 8; + + // If present, crop hints have completed successfully. + CropHintsAnnotation crop_hints_annotation = 11; + + // If present, web detection has completed successfully. + WebDetection web_detection = 13; + + // If present, product search has completed successfully. + google.cloud.vision.v1p3beta1.ProductSearchResults product_search_results = + 14; + + // If set, represents the error message for the operation. + // Note that filled-in image annotations are guaranteed to be + // correct, even when `error` is set. + google.rpc.Status error = 9; + + // If present, contextual information is needed to understand where this image + // comes from. + ImageAnnotationContext context = 21; +} + +// Response to a single file annotation request. A file may contain one or more +// images, which individually have their own responses. +message AnnotateFileResponse { + // Information about the file for which this response is generated. + InputConfig input_config = 1; + + // Individual responses to images found within the file. + repeated AnnotateImageResponse responses = 2; +} + +// Multiple image annotation requests are batched into a single service call. +message BatchAnnotateImagesRequest { + // Individual image annotation requests for this batch. + repeated AnnotateImageRequest requests = 1; +} + +// Response to a batch image annotation request. +message BatchAnnotateImagesResponse { + // Individual responses to image annotation requests within the batch. + repeated AnnotateImageResponse responses = 1; +} + +// An offline file annotation request. +message AsyncAnnotateFileRequest { + // Required. Information about the input file. + InputConfig input_config = 1; + + // Required. Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image(s) in the file. + ImageContext image_context = 3; + + // Required. The desired output location and metadata (e.g. format). + OutputConfig output_config = 4; +} + +// The response for a single offline file annotation request. +message AsyncAnnotateFileResponse { + // The output location and metadata from AsyncAnnotateFileRequest. + OutputConfig output_config = 1; +} + +// Multiple async file annotation requests are batched into a single service +// call. +message AsyncBatchAnnotateFilesRequest { + // Individual async file annotation requests for this batch. + repeated AsyncAnnotateFileRequest requests = 1; +} + +// Response to an async batch file annotation request. +message AsyncBatchAnnotateFilesResponse { + // The list of file annotation responses, one for each request in + // AsyncBatchAnnotateFilesRequest. + repeated AsyncAnnotateFileResponse responses = 1; +} + +// The desired input location and metadata. +message InputConfig { + // The Google Cloud Storage location to read the input from. + GcsSource gcs_source = 1; + + // The type of the file. Currently only "application/pdf" and "image/tiff" + // are supported. Wildcards are not supported. + string mime_type = 2; +} + +// The desired output location and metadata. +message OutputConfig { + // The Google Cloud Storage location to write the output(s) to. + GcsDestination gcs_destination = 1; + + // The max number of response protos to put into each output JSON file on + // Google Cloud Storage. + // The valid range is [1, 100]. If not specified, the default value is 20. + // + // For example, for one pdf file with 100 pages, 100 response protos will + // be generated. If `batch_size` = 20, then 5 json files each + // containing 20 response protos will be written under the prefix + // `gcs_destination`.`uri`. + // + // Currently, batch_size only applies to GcsDestination, with potential future + // support for other output configurations. + int32 batch_size = 2; +} + +// The Google Cloud Storage location where the input will be read from. +message GcsSource { + // Google Cloud Storage URI for the input file. This must only be a + // Google Cloud Storage object. Wildcards are not currently supported. + string uri = 1; +} + +// The Google Cloud Storage location where the output will be written to. +message GcsDestination { + // Google Cloud Storage URI where the results will be stored. Results will + // be in JSON format and preceded by its corresponding input URI. This field + // can either represent a single file, or a prefix for multiple outputs. + // Prefixes must end in a `/`. + // + // Examples: + // + // * File: gs://bucket-name/filename.json + // * Prefix: gs://bucket-name/prefix/here/ + // * File: gs://bucket-name/prefix/here + // + // If multiple outputs, each response is still AnnotateFileResponse, each of + // which contains some subset of the full list of AnnotateImageResponse. + // Multiple outputs can happen if, for example, the output JSON is too large + // and overflows into multiple sharded files. + string uri = 1; +} + +// A bucketized representation of likelihood, which is intended to give clients +// highly stable results across model upgrades. +enum Likelihood { + // Unknown likelihood. + UNKNOWN = 0; + + // It is very unlikely that the image belongs to the specified vertical. + VERY_UNLIKELY = 1; + + // It is unlikely that the image belongs to the specified vertical. + UNLIKELY = 2; + + // It is possible that the image belongs to the specified vertical. + POSSIBLE = 3; + + // It is likely that the image belongs to the specified vertical. + LIKELY = 4; + + // It is very likely that the image belongs to the specified vertical. + VERY_LIKELY = 5; +} + +// Contains metadata for the BatchAnnotateImages operation. +message OperationMetadata { + // Batch operation states. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is received. + CREATED = 1; + + // Request is actively being processed. + RUNNING = 2; + + // The batch processing is done. + DONE = 3; + + // The batch processing was cancelled. + CANCELLED = 4; + } + // Current state of the batch operation. + State state = 1; + + // The time when the batch request was received. + google.protobuf.Timestamp create_time = 5; + + // The time when the operation result was last updated. + google.protobuf.Timestamp update_time = 6; +} diff --git a/google/cloud/vision/v1p3beta1/product_search.proto b/google/cloud/vision/v1p3beta1/product_search.proto new file mode 100644 index 000000000..6a30c0875 --- /dev/null +++ b/google/cloud/vision/v1p3beta1/product_search.proto @@ -0,0 +1,162 @@ +// Copyright 2018 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.vision.v1p3beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p3beta1/geometry.proto"; +import "google/cloud/vision/v1p3beta1/product_search_service.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p3beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ProductSearchProto"; +option java_package = "com.google.cloud.vision.v1p3beta1"; + +// Parameters for a product search request. +message ProductSearchParams { + // The resource name of the catalog to search. + // + // Format is: `productSearch/catalogs/CATALOG_NAME`. + string catalog_name = 1; + + // The category to search in. + // Optional. It is inferred by the system if it is not specified. + // [Deprecated] Use `product_category`. + ProductSearchCategory category = 2; + + // The product category to search in. + // Optional. It is inferred by the system if it is not specified. + // Supported values are `bag`, `shoe`, `sunglasses`, `dress`, `outerwear`, + // `skirt`, `top`, `shorts`, and `pants`. + string product_category = 5; + + // The bounding polygon around the area of interest in the image. + // Optional. If it is not specified, system discretion will be applied. + // [Deprecated] Use `bounding_poly`. + NormalizedBoundingPoly normalized_bounding_poly = 3; + + // The bounding polygon around the area of interest in the image. + // Optional. If it is not specified, system discretion will be applied. + BoundingPoly bounding_poly = 9; + + // Specifies the verbosity of the product search results. + // Optional. Defaults to `BASIC`. + ProductSearchResultsView view = 4; + + // The resource name of a + // [ProductSet][google.cloud.vision.v1p3beta1.ProductSet] to be searched for + // similar images. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`. + string product_set = 6; + + // The list of product categories to search in. Currently, we only consider + // the first category, and either "homegoods" or "apparel" should be + // specified. + repeated string product_categories = 7; + + // The filtering expression. This can be used to restrict search results based + // on Product labels. We currently support an AND of OR of key-value + // expressions, where each expression within an OR must have the same key. + // + // For example, "(color = red OR color = blue) AND brand = Google" is + // acceptable, but not "(color = red OR brand = Google)" or "color: red". + string filter = 8; +} + +// Results for a product search request. +message ProductSearchResults { + // Information about a product. + message ProductInfo { + // Product ID. + string product_id = 1; + + // The URI of the image which matched the query image. + // + // This field is returned only if `view` is set to `FULL` in + // the request. + string image_uri = 2; + + // A confidence level on the match, ranging from 0 (no confidence) to + // 1 (full confidence). + // + // This field is returned only if `view` is set to `FULL` in + // the request. + float score = 3; + } + + // Information about a product. + message Result { + // The Product. + Product product = 1; + + // A confidence level on the match, ranging from 0 (no confidence) to + // 1 (full confidence). + // + // This field is returned only if `view` is set to `FULL` in + // the request. + float score = 2; + + // The resource name of the image from the product that is the closest match + // to the query. + string image = 3; + } + + // Product category. + // [Deprecated] Use `product_category`. + ProductSearchCategory category = 1; + + // Product category. + // Supported values are `bag` and `shoe`. + // [Deprecated] `product_category` is provided in each Product. + string product_category = 4; + + // Timestamp of the index which provided these results. Changes made after + // this time are not reflected in the current results. + google.protobuf.Timestamp index_time = 2; + + // List of detected products. + repeated ProductInfo products = 3; + + // List of results, one for each product match. + repeated Result results = 5; +} + +// Supported product search categories. +enum ProductSearchCategory { + // Default value used when a category is not specified. + PRODUCT_SEARCH_CATEGORY_UNSPECIFIED = 0; + + // Shoes category. + SHOES = 1; + + // Bags category. + BAGS = 2; +} + +// Specifies the fields to include in product search results. +enum ProductSearchResultsView { + // Product search results contain only `product_category` and `product_id`. + // Default value. + BASIC = 0; + + // Product search results contain `product_category`, `product_id`, + // `image_uri`, and `score`. + FULL = 1; +} diff --git a/google/cloud/vision/v1p3beta1/product_search_service.proto b/google/cloud/vision/v1p3beta1/product_search_service.proto new file mode 100644 index 000000000..23919ee7e --- /dev/null +++ b/google/cloud/vision/v1p3beta1/product_search_service.proto @@ -0,0 +1,842 @@ +// Copyright 2018 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.vision.v1p3beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p3beta1/geometry.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p3beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ProductSearchServiceProto"; +option java_package = "com.google.cloud.vision.v1p3beta1"; + +// Manages Products and ProductSets of reference images for use in product +// search. It uses the following resource model: +// +// - The API has a collection of +// [ProductSet][google.cloud.vision.v1p3beta1.ProductSet] resources, named +// `projects/*/locations/*/productSets/*`, which acts as a way to put different +// products into groups to limit identification. +// +// In parallel, +// +// - The API has a collection of +// [Product][google.cloud.vision.v1p3beta1.Product] resources, named +// `projects/*/locations/*/products/*` +// +// - Each [Product][google.cloud.vision.v1p3beta1.Product] has a collection of +// [ReferenceImage][google.cloud.vision.v1p3beta1.ReferenceImage] resources, +// named +// `projects/*/locations/*/products/*/referenceImages/*` +service ProductSearch { + // Creates and returns a new ProductSet resource. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if display_name is missing, or is longer than + // 4096 characters. + rpc CreateProductSet(CreateProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + post: "/v1p3beta1/{parent=projects/*/locations/*}/productSets" + body: "product_set" + }; + } + + // Lists ProductSets in an unspecified order. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100, or less + // than 1. + rpc ListProductSets(ListProductSetsRequest) + returns (ListProductSetsResponse) { + option (google.api.http) = { + get: "/v1p3beta1/{parent=projects/*/locations/*}/productSets" + }; + } + + // Gets information associated with a ProductSet. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + rpc GetProductSet(GetProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + get: "/v1p3beta1/{name=projects/*/locations/*/productSets/*}" + }; + } + + // Makes changes to a ProductSet resource. + // Only display_name can be updated currently. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + // * Returns INVALID_ARGUMENT if display_name is present in update_mask but + // missing from the request or longer than 4096 characters. + rpc UpdateProductSet(UpdateProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + patch: "/v1p3beta1/{product_set.name=projects/*/locations/*/productSets/*}" + body: "product_set" + }; + } + + // Permanently deletes a ProductSet. All Products and ReferenceImages in the + // ProductSet will be deleted. + // + // The actual image files are not deleted from Google Cloud Storage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + rpc DeleteProductSet(DeleteProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1p3beta1/{name=projects/*/locations/*/productSets/*}" + }; + } + + // Creates and returns a new product resource. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if display_name is missing or longer than 4096 + // characters. + // * Returns INVALID_ARGUMENT if description is longer than 4096 characters. + // * Returns INVALID_ARGUMENT if product_category is missing or invalid. + rpc CreateProduct(CreateProductRequest) returns (Product) { + option (google.api.http) = { + post: "/v1p3beta1/{parent=projects/*/locations/*}/products" + body: "product" + }; + } + + // Lists products in an unspecified order. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1. + rpc ListProducts(ListProductsRequest) returns (ListProductsResponse) { + option (google.api.http) = { + get: "/v1p3beta1/{parent=projects/*/locations/*}/products" + }; + } + + // Gets information associated with a Product. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product does not exist. + rpc GetProduct(GetProductRequest) returns (Product) { + option (google.api.http) = { + get: "/v1p3beta1/{name=projects/*/locations/*/products/*}" + }; + } + + // Makes changes to a Product resource. + // Only display_name, description and labels can be updated right now. + // + // If labels are updated, the change will not be reflected in queries until + // the next index time. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product does not exist. + // * Returns INVALID_ARGUMENT if display_name is present in update_mask but is + // missing from the request or longer than 4096 characters. + // * Returns INVALID_ARGUMENT if description is present in update_mask but is + // longer than 4096 characters. + // * Returns INVALID_ARGUMENT if product_category is present in update_mask. + rpc UpdateProduct(UpdateProductRequest) returns (Product) { + option (google.api.http) = { + patch: "/v1p3beta1/{product.name=projects/*/locations/*/products/*}" + body: "product" + }; + } + + // Permanently deletes a product and its reference images. + // + // Metadata of the product and all its images will be deleted right away, but + // search queries against ProductSets containing the product may still work + // until all related caches are refreshed. + // + // Possible errors: + // + // * Returns NOT_FOUND if the product does not exist. + rpc DeleteProduct(DeleteProductRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1p3beta1/{name=projects/*/locations/*/products/*}" + }; + } + + // Creates and returns a new ReferenceImage resource. + // + // The `bounding_poly` field is optional. If `bounding_poly` is not specified, + // the system will try to detect regions of interest in the image that are + // compatible with the product_category on the parent product. If it is + // specified, detection is ALWAYS skipped. The system converts polygons into + // non-rotated rectangles. + // + // Note that the pipeline will resize the image if the image resolution is too + // large to process (above 50MP). + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if the image_uri is missing or longer than 4096 + // characters. + // * Returns INVALID_ARGUMENT if the product does not exist. + // * Returns INVALID_ARGUMENT if bounding_poly is not provided, and nothing + // compatible with the parent product's product_category is detected. + // * Returns INVALID_ARGUMENT if bounding_poly contains more than 10 polygons. + rpc CreateReferenceImage(CreateReferenceImageRequest) + returns (ReferenceImage) { + option (google.api.http) = { + post: "/v1p3beta1/{parent=projects/*/locations/*/products/*}/referenceImages" + body: "reference_image" + }; + } + + // Permanently deletes a reference image. + // + // The image metadata will be deleted right away, but search queries + // against ProductSets containing the image may still work until all related + // caches are refreshed. + // + // The actual image files are not deleted from Google Cloud Storage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the reference image does not exist. + rpc DeleteReferenceImage(DeleteReferenceImageRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1p3beta1/{name=projects/*/locations/*/products/*/referenceImages/*}" + }; + } + + // Lists reference images. + // + // Possible errors: + // + // * Returns NOT_FOUND if the parent product does not exist. + // * Returns INVALID_ARGUMENT if the page_size is greater than 100, or less + // than 1. + rpc ListReferenceImages(ListReferenceImagesRequest) + returns (ListReferenceImagesResponse) { + option (google.api.http) = { + get: "/v1p3beta1/{parent=projects/*/locations/*/products/*}/referenceImages" + }; + } + + // Gets information associated with a ReferenceImage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the specified image does not exist. + rpc GetReferenceImage(GetReferenceImageRequest) returns (ReferenceImage) { + option (google.api.http) = { + get: "/v1p3beta1/{name=projects/*/locations/*/products/*/referenceImages/*}" + }; + } + + // Adds a Product to the specified ProductSet. If the Product is already + // present, no change is made. + // + // One Product can be added to at most 100 ProductSets. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product or the ProductSet doesn't exist. + rpc AddProductToProductSet(AddProductToProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1p3beta1/{name=projects/*/locations/*/productSets/*}:addProduct" + body: "*" + }; + } + + // Removes a Product from the specified ProductSet. + // + // Possible errors: + // + // * Returns NOT_FOUND If the Product is not found under the ProductSet. + rpc RemoveProductFromProductSet(RemoveProductFromProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1p3beta1/{name=projects/*/locations/*/productSets/*}:removeProduct" + body: "*" + }; + } + + // Lists the Products in a ProductSet, in an unspecified order. If the + // ProductSet does not exist, the products field of the response will be + // empty. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1. + rpc ListProductsInProductSet(ListProductsInProductSetRequest) + returns (ListProductsInProductSetResponse) { + option (google.api.http) = { + get: "/v1p3beta1/{name=projects/*/locations/*/productSets/*}/products" + }; + } + + // Asynchronous API that imports a list of reference images to specified + // product sets based on a list of image information. + // + // The [google.longrunning.Operation][google.longrunning.Operation] API can be + // used to keep track of the progress and results of the request. + // `Operation.metadata` contains `BatchOperationMetadata`. (progress) + // `Operation.response` contains `ImportProductSetsResponse`. (results) + // + // The input source of this method is a csv file on Google Cloud Storage. + // For the format of the csv file please see + // [ImportProductSetsGcsSource.csv_file_uri][google.cloud.vision.v1p3beta1.ImportProductSetsGcsSource.csv_file_uri]. + rpc ImportProductSets(ImportProductSetsRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p3beta1/{parent=projects/*/locations/*}/productSets:import" + body: "*" + }; + } +} + +// A Product contains ReferenceImages. +message Product { + // A product label represented as a key-value pair. + message KeyValue { + // The key of the label attached to the product. Cannot be empty and cannot + // exceed 128 bytes. + string key = 1; + + // The value of the label attached to the product. Cannot be empty and + // cannot exceed 128 bytes. + string value = 2; + } + + // The resource name of the product. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + // + // This field is ignored when creating a product. + string name = 1; + + // The user-provided name for this Product. Must not be empty. Must be at most + // 4096 characters long. + string display_name = 2; + + // User-provided metadata to be stored with this product. Must be at most 4096 + // characters long. + string description = 3; + + // The category for the product identified by the reference image. This should + // be either "homegoods" or "apparel". + // + // This field is immutable. + string product_category = 4; + + // Key-value pairs that can be attached to a product. At query time, + // constraints can be specified based on the product_labels. + // + // Note that integer values can be provided as strings, e.g. "1199". Only + // strings with integer values can match a range-based restriction which is + // to be supported soon. + // + // Multiple values can be assigned to the same key. One product may have up to + // 100 product_labels. + repeated KeyValue product_labels = 5; +} + +// A ProductSet contains Products. A ProductSet can contain a maximum of 1 +// million reference images. If the limit is exceeded, periodic indexing will +// fail. +message ProductSet { + // The resource name of the ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`. + // + // This field is ignored when creating a ProductSet. + string name = 1; + + // The user-provided name for this ProductSet. Must not be empty. Must be at + // most 4096 characters long. + string display_name = 2; + + // Output only. The time at which this ProductSet was last indexed. Query + // results will reflect all updates before this time. If this ProductSet has + // never been indexed, this field is 0. + // + // This field is ignored when creating a ProductSet. + google.protobuf.Timestamp index_time = 3; + + // Output only. If there was an error with indexing the product set, the field + // is populated. + // + // This field is ignored when creating a ProductSet. + google.rpc.Status index_error = 4; +} + +// A `ReferenceImage` represents a product image and its associated metadata, +// such as bounding boxes. +message ReferenceImage { + // The resource name of the reference image. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID`. + // + // This field is ignored when creating a reference image. + string name = 1; + + // The Google Cloud Storage URI of the reference image. + // + // The URI must start with `gs://`. + // + // Required. + string uri = 2; + + // Bounding polygons around the areas of interest in the reference image. + // Optional. If this field is empty, the system will try to detect regions of + // interest. At most 10 bounding polygons will be used. + // + // The provided shape is converted into a non-rotated rectangle. Once + // converted, the small edge of the rectangle must be greater than or equal + // to 300 pixels. The aspect ratio must be 1:4 or less (i.e. 1:3 is ok; 1:5 + // is not). + repeated BoundingPoly bounding_polys = 3; +} + +// Request message for the `CreateProduct` method. +message CreateProductRequest { + // The project in which the Product should be created. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The product to create. + Product product = 2; + + // A user-supplied resource id for this Product. If set, the server will + // attempt to use this value as the resource id. If it is already in use, an + // error is returned with code ALREADY_EXISTS. Must be at most 128 characters + // long. It cannot contain the character `/`. + string product_id = 3; +} + +// Request message for the `ListProducts` method. +message ListProductsRequest { + // The project OR ProductSet from which Products should be listed. + // + // Format: + // `projects/PROJECT_ID/locations/LOC_ID` + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProducts` method. +message ListProductsResponse { + // List of products. + repeated Product products = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// Request message for the `GetProduct` method. +message GetProductRequest { + // Resource name of the Product to get. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string name = 1; +} + +// Request message for the `UpdateProduct` method. +message UpdateProductRequest { + // The Product resource which replaces the one on the server. + // product.name is immutable. + Product product = 1; + + // The [FieldMask][google.protobuf.FieldMask] that specifies which fields + // to update. + // If update_mask isn't specified, all mutable fields are to be updated. + // Valid mask paths include `product_labels`, `display_name` and + // `description`. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for the `DeleteProduct` method. +message DeleteProductRequest { + // Resource name of product to delete. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string name = 1; +} + +// Request message for the `CreateProductSet` method. +message CreateProductSetRequest { + // The project in which the ProductSet should be created. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The ProductSet to create. + ProductSet product_set = 2; + + // A user-supplied resource id for this ProductSet. If set, the server will + // attempt to use this value as the resource id. If it is already in use, an + // error is returned with code ALREADY_EXISTS. Must be at most 128 characters + // long. It cannot contain the character `/`. + string product_set_id = 3; +} + +// Request message for the `ListProductSets` method. +message ListProductSetsRequest { + // The project from which ProductSets should be listed. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProductSets` method. +message ListProductSetsResponse { + // List of ProductSets. + repeated ProductSet product_sets = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// Request message for the `GetProductSet` method. +message GetProductSetRequest { + // Resource name of the ProductSet to get. + // + // Format is: + // `projects/PROJECT_ID/locations/LOG_ID/productSets/PRODUCT_SET_ID` + string name = 1; +} + +// Request message for the `UpdateProductSet` method. +message UpdateProductSetRequest { + // The ProductSet resource which replaces the one on the server. + ProductSet product_set = 1; + + // The [FieldMask][google.protobuf.FieldMask] that specifies which fields to + // update. + // If update_mask isn't specified, all mutable fields are to be updated. + // Valid mask path is `display_name`. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for the `DeleteProductSet` method. +message DeleteProductSetRequest { + // Resource name of the ProductSet to delete. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; +} + +// Request message for the `CreateReferenceImage` method. +message CreateReferenceImageRequest { + // Resource name of the product in which to create the reference image. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + string parent = 1; + + // The reference image to create. + // If an image ID is specified, it is ignored. + ReferenceImage reference_image = 2; + + // A user-supplied resource id for the ReferenceImage to be added. If set, + // the server will attempt to use this value as the resource id. If it is + // already in use, an error is returned with code ALREADY_EXISTS. Must be at + // most 128 characters long. It cannot contain the character `/`. + string reference_image_id = 3; +} + +// Request message for the `ListReferenceImages` method. +message ListReferenceImagesRequest { + // Resource name of the product containing the reference images. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // A token identifying a page of results to be returned. This is the value + // of `nextPageToken` returned in a previous reference image list request. + // + // Defaults to the first page if not specified. + string page_token = 3; +} + +// Response message for the `ListReferenceImages` method. +message ListReferenceImagesResponse { + // The list of reference images. + repeated ReferenceImage reference_images = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string next_page_token = 3; +} + +// Request message for the `GetReferenceImage` method. +message GetReferenceImageRequest { + // The resource name of the ReferenceImage to get. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID`. + string name = 1; +} + +// Request message for the `DeleteReferenceImage` method. +message DeleteReferenceImageRequest { + // The resource name of the reference image to delete. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID` + string name = 1; +} + +// Request message for the `AddProductToProductSet` method. +message AddProductToProductSetRequest { + // The resource name for the ProductSet to modify. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The resource name for the Product to be added to this ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string product = 2; +} + +// Request message for the `RemoveProductFromProductSet` method. +message RemoveProductFromProductSetRequest { + // The resource name for the ProductSet to modify. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The resource name for the Product to be removed from this ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string product = 2; +} + +// Request message for the `ListProductsInProductSet` method. +message ListProductsInProductSetRequest { + // The ProductSet resource for which to retrieve Products. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProductsInProductSet` method. +message ListProductsInProductSetResponse { + // The list of Products. + repeated Product products = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// The Google Cloud Storage location for a csv file which preserves a list of +// ImportProductSetRequests in each line. +message ImportProductSetsGcsSource { + // The Google Cloud Storage URI of the input csv file. + // + // The URI must start with gs:// + // + // The format of the input csv file should be one image per line. + // In each line, there are 6 columns. + // 1. image_uri + // 2, image_id + // 3. product_set_id + // 4. product_id + // 5, product_category + // 6, product_display_name + // 7, labels + // 8. bounding_poly + // + // Columns 1, 3, 4, and 5 are required, other columns are optional. A new + // ProductSet/Product with the same id will be created on the fly + // if the ProductSet/Product specified by product_set_id/product_id does not + // exist. + // + // The image_id field is optional but has to be unique if provided. If it is + // empty, we will automatically assign an unique id to the image. + // + // The product_display_name field is optional. If it is empty, a space (" ") + // is used as the place holder for the product display_name, which can + // be updated later through the realtime API. + // + // If the Product with product_id already exists, the fields + // product_display_name, product_category and labels are ignored. + // + // If a Product doesn't exist and needs to be created on the fly, the + // product_display_name field refers to + // [Product.display_name][google.cloud.vision.v1p3beta1.Product.display_name], + // the product_category field refers to + // [Product.product_category][google.cloud.vision.v1p3beta1.Product.product_category], + // and the labels field refers to [Product.labels][]. + // + // Labels (optional) should be a line containing a list of comma-separated + // key-value pairs, with the format + // "key_1=value_1,key_2=value_2,...,key_n=value_n". + // + // The bounding_poly (optional) field is used to identify one region of + // interest from the image in the same manner as CreateReferenceImage. If no + // bounding_poly is specified, the system will try to detect regions of + // interest automatically. + // + // Note that the pipeline will resize the image if the image resolution is too + // large to process (above 20MP). + // + // Also note that at most one bounding_poly is allowed per line. If the image + // contains multiple regions of interest, the csv should contain one line per + // region of interest. + // + // The bounding_poly column should contain an even number of comma-separated + // numbers, with the format "p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y". Nonnegative + // integers should be used for absolute bounding polygons, and float values + // in [0, 1] should be used for normalized bounding polygons. + string csv_file_uri = 1; +} + +// The input content for the `ImportProductSets` method. +message ImportProductSetsInputConfig { + // The source of the input. + oneof source { + // The Google Cloud Storage location for a csv file which preserves a list + // of ImportProductSetRequests in each line. + ImportProductSetsGcsSource gcs_source = 1; + } +} + +// Request message for the `ImportProductSets` method. +message ImportProductSetsRequest { + // The project in which the ProductSets should be imported. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The input content for the list of requests. + ImportProductSetsInputConfig input_config = 2; +} + +// Response message for the `ImportProductSets` method. +// +// This message is returned by the +// [google.longrunning.Operations.GetOperation][google.longrunning.Operations.GetOperation] +// method in the returned +// [google.longrunning.Operation.response][google.longrunning.Operation.response] +// field. +message ImportProductSetsResponse { + // The list of reference_images that are imported successfully. + repeated ReferenceImage reference_images = 1; + + // The rpc status for each ImportProductSet request, including both successes + // and errors. + // + // The number of statuses here matches the number of lines in the csv file, + // and statuses[i] stores the success or failure status of processing the i-th + // line of the csv, starting from line 0. + repeated google.rpc.Status statuses = 2; +} + +// Metadata for the batch operations such as the current state. +// +// This is included in the `metadata` field of the `Operation` returned by the +// `GetOperation` call of the `google::longrunning::Operations` service. +message BatchOperationMetadata { + // Enumerates the possible states that the batch request can be in. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is actively being processed. + PROCESSING = 1; + + // The request is done and at least one item has been successfully + // processed. + SUCCESSFUL = 2; + + // The request is done and no item has been successfully processed. + FAILED = 3; + + // The request is done after the longrunning.Operations.CancelOperation has + // been called by the user. Any records that were processed before the + // cancel command are output as specified in the request. + CANCELLED = 4; + } + + // The current state of the batch operation. + State state = 1; + + // The time when the batch request was submitted to the server. + google.protobuf.Timestamp submit_time = 2; + + // The time when the batch request is finished and + // [google.longrunning.Operation.done][google.longrunning.Operation.done] is + // set to true. + google.protobuf.Timestamp end_time = 3; +} diff --git a/google/cloud/vision/v1p3beta1/text_annotation.proto b/google/cloud/vision/v1p3beta1/text_annotation.proto new file mode 100644 index 000000000..3c256c577 --- /dev/null +++ b/google/cloud/vision/v1p3beta1/text_annotation.proto @@ -0,0 +1,259 @@ +// Copyright 2018 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.vision.v1p3beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p3beta1/geometry.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p3beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "TextAnnotationProto"; +option java_package = "com.google.cloud.vision.v1p3beta1"; + +// TextAnnotation contains a structured representation of OCR extracted text. +// The hierarchy of an OCR extracted text structure is like this: +// TextAnnotation -> Page -> Block -> Paragraph -> Word -> Symbol +// Each structural component, starting from Page, may further have their own +// properties. Properties describe detected languages, breaks etc.. Please refer +// to the +// [TextAnnotation.TextProperty][google.cloud.vision.v1p3beta1.TextAnnotation.TextProperty] +// message definition below for more detail. +message TextAnnotation { + // Detected language for a structural component. + message DetectedLanguage { + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 1; + + // Confidence of detected language. Range [0, 1]. + float confidence = 2; + } + + // Detected start or end of a structural component. + message DetectedBreak { + // Enum to denote the type of break found. New line, space etc. + enum BreakType { + // Unknown break label type. + UNKNOWN = 0; + + // Regular space. + SPACE = 1; + + // Sure space (very wide). + SURE_SPACE = 2; + + // Line-wrapping break. + EOL_SURE_SPACE = 3; + + // End-line hyphen that is not present in text; does not co-occur with + // `SPACE`, `LEADER_SPACE`, or `LINE_BREAK`. + HYPHEN = 4; + + // Line break that ends a paragraph. + LINE_BREAK = 5; + } + + // Detected break type. + BreakType type = 1; + + // True if break prepends the element. + bool is_prefix = 2; + } + + // Additional information detected on the structural component. + message TextProperty { + // A list of detected languages together with confidence. + repeated DetectedLanguage detected_languages = 1; + + // Detected start or end of a text segment. + DetectedBreak detected_break = 2; + } + + // List of pages detected by OCR. + repeated Page pages = 1; + + // UTF-8 text detected on the pages. + string text = 2; +} + +// Detected page from OCR. +message Page { + // Additional information detected on the page. + TextAnnotation.TextProperty property = 1; + + // Page width. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 width = 2; + + // Page height. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 height = 3; + + // List of blocks of text, images etc on this page. + repeated Block blocks = 4; + + // Confidence of the OCR results on the page. Range [0, 1]. + float confidence = 5; +} + +// Logical element on the page. +message Block { + // Type of a block (text, image etc) as identified by OCR. + enum BlockType { + // Unknown block type. + UNKNOWN = 0; + + // Regular text block. + TEXT = 1; + + // Table block. + TABLE = 2; + + // Image block. + PICTURE = 3; + + // Horizontal/vertical line box. + RULER = 4; + + // Barcode block. + BARCODE = 5; + } + + // Additional information detected for the block. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the block. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // + // * when the text is horizontal it might look like: + // + // 0----1 + // | | + // 3----2 + // + // * when it's rotated 180 degrees around the top-left corner it becomes: + // + // 2----3 + // | | + // 1----0 + // + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of paragraphs in this block (if this blocks is of type text). + repeated Paragraph paragraphs = 3; + + // Detected block type (text, image etc) for this block. + BlockType block_type = 4; + + // Confidence of the OCR results on the block. Range [0, 1]. + float confidence = 5; +} + +// Structural unit of text representing a number of words in certain order. +message Paragraph { + // Additional information detected for the paragraph. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the paragraph. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of words in this paragraph. + repeated Word words = 3; + + // Confidence of the OCR results for the paragraph. Range [0, 1]. + float confidence = 4; +} + +// A word representation. +message Word { + // Additional information detected for the word. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the word. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of symbols in the word. + // The order of the symbols follows the natural reading order. + repeated Symbol symbols = 3; + + // Confidence of the OCR results for the word. Range [0, 1]. + float confidence = 4; +} + +// A single symbol representation. +message Symbol { + // Additional information detected for the symbol. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the symbol. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // The actual UTF-8 representation of the symbol. + string text = 3; + + // Confidence of the OCR results for the symbol. Range [0, 1]. + float confidence = 4; +} diff --git a/google/cloud/vision/v1p3beta1/vision_gapic.yaml b/google/cloud/vision/v1p3beta1/vision_gapic.yaml new file mode 100644 index 000000000..59c695328 --- /dev/null +++ b/google/cloud/vision/v1p3beta1/vision_gapic.yaml @@ -0,0 +1,444 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +language_settings: + java: + package_name: com.google.cloud.vision.v1p3beta1 + python: + package_name: google.cloud.vision_v1p3beta1.gapic + go: + package_name: cloud.google.com/go/vision/apiv1p3beta1 + domain_layer_location: cloud.google.com/go/vision + csharp: + package_name: Google.Cloud.Vision.V1p3beta1 + ruby: + package_name: Google::Cloud::Vision::V1p3beta1 + php: + package_name: Google\Cloud\Vision\V1p3beta1 + nodejs: + package_name: vision.v1p3beta1 + domain_layer_location: google-cloud +interfaces: +- name: google.cloud.vision.v1p3beta1.ProductSearch + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/productSets/{product_set} + entity_name: product_set + - name_pattern: projects/{project}/locations/{location}/products/{product} + entity_name: product + - name_pattern: projects/{project}/locations/{location}/products/{product}/referenceImages/{reference_image} + entity_name: reference_image + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + methods: + - name: CreateProductSet + flattening: + groups: + - parameters: + - parent + - product_set + - product_set_id + required_fields: + - parent + - product_set + - product_set_id + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: ListProductSets + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: product_sets + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: UpdateProductSet + flattening: + groups: + - parameters: + - product_set + - update_mask + required_fields: + - product_set + - update_mask + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + product_set.name: product_set + timeout_millis: 60000 + - name: DeleteProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: CreateProduct + flattening: + groups: + - parameters: + - parent + - product + - product_id + required_fields: + - parent + - product + - product_id + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: ListProducts + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: products + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetProduct + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product + timeout_millis: 60000 + - name: UpdateProduct + flattening: + groups: + - parameters: + - product + - update_mask + required_fields: + - product + - update_mask + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + product.name: product + timeout_millis: 60000 + - name: DeleteProduct + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product + timeout_millis: 60000 + - name: CreateReferenceImage + flattening: + groups: + - parameters: + - parent + - reference_image + - reference_image_id + required_fields: + - parent + - reference_image + - reference_image_id + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: product + timeout_millis: 60000 + - name: DeleteReferenceImage + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: reference_image + timeout_millis: 60000 + - name: ListReferenceImages + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: reference_images + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: product + timeout_millis: 60000 + - name: GetReferenceImage + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: reference_image + timeout_millis: 60000 + - name: AddProductToProductSet + flattening: + groups: + - parameters: + - name + - product + required_fields: + - name + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: RemoveProductFromProductSet + flattening: + groups: + - parameters: + - name + - product + required_fields: + - name + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: ListProductsInProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: products + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: ImportProductSets + flattening: + groups: + - parameters: + - parent + - input_config + required_fields: + - parent + - input_config + long_running: + return_type: google.cloud.vision.v1p3beta1.ImportProductSetsResponse + metadata_type: google.cloud.vision.v1p3beta1.BatchOperationMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 +- name: google.cloud.vision.v1p3beta1.ImageAnnotator + smoke_test: + method: BatchAnnotateImages + init_fields: + - requests[0].image.source.gcs_image_uri="gs://gapic-toolkit/President_Barack_Obama.jpg" + - requests[0].features[0].type=FACE_DETECTION + collections: [] + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + methods: + - name: BatchAnnotateImages + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AsyncBatchAnnotateFiles + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + long_running: + return_type: google.cloud.vision.v1p3beta1.AsyncBatchAnnotateFilesResponse + metadata_type: google.cloud.vision.v1p3beta1.OperationMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 +resource_name_generation: +- message_name: CreateProductSetRequest + field_entity_map: + parent: location +- message_name: ListProductSetsRequest + field_entity_map: + parent: location +- message_name: GetProductSetRequest + field_entity_map: + name: product_set +- message_name: UpdateProductSetRequest + field_entity_map: + product_set.name: product_set +- message_name: DeleteProductSetRequest + field_entity_map: + name: product_set +- message_name: CreateProductRequest + field_entity_map: + parent: location +- message_name: ListProductsRequest + field_entity_map: + parent: location +- message_name: GetProductRequest + field_entity_map: + name: product +- message_name: UpdateProductRequest + field_entity_map: + product.name: product +- message_name: DeleteProductRequest + field_entity_map: + name: product +- message_name: CreateReferenceImageRequest + field_entity_map: + parent: product +- message_name: DeleteReferenceImageRequest + field_entity_map: + name: reference_image +- message_name: ListReferenceImagesRequest + field_entity_map: + parent: product +- message_name: GetReferenceImageRequest + field_entity_map: + name: reference_image +- message_name: AddProductToProductSetRequest + field_entity_map: + name: product_set +- message_name: RemoveProductFromProductSetRequest + field_entity_map: + name: product_set +- message_name: ListProductsInProductSetRequest + field_entity_map: + name: product_set +- message_name: ImportProductSetsRequest + field_entity_map: + parent: location diff --git a/google/cloud/vision/v1p3beta1/web_detection.proto b/google/cloud/vision/v1p3beta1/web_detection.proto new file mode 100644 index 000000000..cf9a22612 --- /dev/null +++ b/google/cloud/vision/v1p3beta1/web_detection.proto @@ -0,0 +1,104 @@ +// Copyright 2018 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.vision.v1p3beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p3beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "WebDetectionProto"; +option java_package = "com.google.cloud.vision.v1p3beta1"; + +// Relevant information for the image from the Internet. +message WebDetection { + // Entity deduced from similar images on the Internet. + message WebEntity { + // Opaque entity ID. + string entity_id = 1; + + // Overall relevancy score for the entity. + // Not normalized and not comparable across different image queries. + float score = 2; + + // Canonical description of the entity, in English. + string description = 3; + } + + // Metadata for online images. + message WebImage { + // The result image URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the image. + float score = 2; + } + + // Metadata for web pages. + message WebPage { + // The result web page URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the web page. + float score = 2; + + // Title for the web page, may contain HTML markups. + string page_title = 3; + + // Fully matching images on the page. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 4; + + // Partial matching images on the page. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its + // crops. + repeated WebImage partial_matching_images = 5; + } + + // Label to provide extra metadata for the web detection. + message WebLabel { + // Label for extra metadata. + string label = 1; + + // The BCP-47 language code for `label`, such as "en-US" or "sr-Latn". + // For more information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + } + + // Deduced entities from similar images on the Internet. + repeated WebEntity web_entities = 1; + + // Fully matching images from the Internet. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 2; + + // Partial matching images from the Internet. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its crops. + repeated WebImage partial_matching_images = 3; + + // Web pages containing the matching images from the Internet. + repeated WebPage pages_with_matching_images = 4; + + // The visually similar image results. + repeated WebImage visually_similar_images = 6; + + // Best guess text labels for the request image. + repeated WebLabel best_guess_labels = 8; +} diff --git a/google/cloud/vision/v1p4beta1/BUILD.bazel b/google/cloud/vision/v1p4beta1/BUILD.bazel new file mode 100644 index 000000000..de02672b8 --- /dev/null +++ b/google/cloud/vision/v1p4beta1/BUILD.bazel @@ -0,0 +1,158 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) + +proto_library( + name = "vision_proto", + srcs = [ + "geometry.proto", + "image_annotator.proto", + "product_search.proto", + "product_search_service.proto", + "text_annotation.proto", + "web_detection.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/longrunning:operations_proto", + "//google/rpc:status_proto", + "//google/type:color_proto", + "//google/type:latlng_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "vision_proto_with_info", + deps = [":vision_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "vision_java_proto", + deps = [":vision_proto"], +) + +java_grpc_library( + name = "vision_java_grpc", + srcs = [":vision_proto"], + deps = [":vision_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "vision_resource_name_java_proto", + gapic_yaml = "vision_gapic.yaml", + deps = [":vision_proto"], +) + +java_gapic_library( + name = "vision_java_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + service_yaml = "//google/cloud/vision:vision_v1p4beta1.yaml", + test_deps = [":vision_java_grpc"], + deps = [ + ":vision_java_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [ + ":vision_java_gapic_test", + ], +) for test_name in [ + "com.google.cloud.vision.v1p4beta1.ImageAnnotatorClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-vision-v1p4beta1-java", + client_deps = [":vision_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":vision_java_gapic_test"], + grpc_deps = [":vision_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":vision_java_proto", + ":vision_proto", + ":vision_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "vision_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/vision/v1p4beta1", + protos = [":vision_proto_with_info"], + deps = [ + "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", + "//google/rpc:status_go_proto", + "//google/type:color_go_proto", + "//google/type:latlng_go_proto", + ], +) + +go_gapic_library( + name = "vision_go_gapic", + src = ":vision_proto_with_info", + gapic_yaml = "vision_gapic.yaml", + importpath = "cloud.google.com/go/vision/apiv1p4beta1", + service_yaml = "//google/cloud/vision:vision_v1p4beta1.yaml", + deps = [ + ":vision_go_proto", + "//google/longrunning:longrunning_go_gapic", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go//longrunning:go_default_library", + ], +) + +go_test( + name = "vision_go_gapic_test", + srcs = [":vision_go_gapic_srcjar_test"], + embed = [":vision_go_gapic"], + importpath = "cloud.google.com/go/vision/apiv1p4beta1", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-vision-v1p4beta1-go", + deps = [ + ":vision_go_gapic", + ":vision_go_gapic_srcjar-smoke-test.srcjar", + ":vision_go_gapic_srcjar-test.srcjar", + ":vision_go_proto", + ], +)
\ No newline at end of file diff --git a/google/cloud/vision/v1p4beta1/geometry.proto b/google/cloud/vision/v1p4beta1/geometry.proto new file mode 100644 index 000000000..b0abd329c --- /dev/null +++ b/google/cloud/vision/v1p4beta1/geometry.proto @@ -0,0 +1,71 @@ +// Copyright 2018 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.vision.v1p4beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p4beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "GeometryProto"; +option java_package = "com.google.cloud.vision.v1p4beta1"; +option objc_class_prefix = "GCVN"; + +// A vertex represents a 2D point in the image. +// NOTE: the vertex coordinates are in the same scale as the original image. +message Vertex { + // X coordinate. + int32 x = 1; + + // Y coordinate. + int32 y = 2; +} + +// A vertex represents a 2D point in the image. +// NOTE: the normalized vertex coordinates are relative to the original image +// and range from 0 to 1. +message NormalizedVertex { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; +} + +// A bounding polygon for the detected image annotation. +message BoundingPoly { + // The bounding polygon vertices. + repeated Vertex vertices = 1; + + // The bounding polygon normalized vertices. + repeated NormalizedVertex normalized_vertices = 2; +} + +// A 3D position in the image, used primarily for Face detection landmarks. +// A valid Position must have both x and y coordinates. +// The position coordinates are in the same scale as the original image. +message Position { + // X coordinate. + float x = 1; + + // Y coordinate. + float y = 2; + + // Z coordinate (or depth). + float z = 3; +} diff --git a/google/cloud/vision/v1p4beta1/image_annotator.proto b/google/cloud/vision/v1p4beta1/image_annotator.proto new file mode 100644 index 000000000..ebbf92c35 --- /dev/null +++ b/google/cloud/vision/v1p4beta1/image_annotator.proto @@ -0,0 +1,905 @@ +// Copyright 2018 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.vision.v1p4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p4beta1/geometry.proto"; +import "google/cloud/vision/v1p4beta1/product_search.proto"; +import "google/cloud/vision/v1p4beta1/text_annotation.proto"; +import "google/cloud/vision/v1p4beta1/web_detection.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; +import "google/type/color.proto"; +import "google/type/latlng.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p4beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ImageAnnotatorProto"; +option java_package = "com.google.cloud.vision.v1p4beta1"; +option objc_class_prefix = "GCVN"; + +// Service that performs Google Cloud Vision API detection tasks over client +// images, such as face, landmark, logo, label, and text detection. The +// ImageAnnotator service returns detected entities from the images. +service ImageAnnotator { + // Run image detection and annotation for a batch of images. + rpc BatchAnnotateImages(BatchAnnotateImagesRequest) + returns (BatchAnnotateImagesResponse) { + option (google.api.http) = { + post: "/v1p4beta1/images:annotate" + body: "*" + }; + } + + // Service that performs image detection and annotation for a batch of files. + // Now only "application/pdf", "image/tiff" and "image/gif" are supported. + // + // This service will extract at most the first 10 frames (gif) or pages + // (pdf or tiff) from each file provided and perform detection and annotation + // for each image extracted. + rpc BatchAnnotateFiles(BatchAnnotateFilesRequest) + returns (BatchAnnotateFilesResponse) { + option (google.api.http) = { + post: "/v1p4beta1/files:annotate" + body: "*" + }; + } + + // Run asynchronous image detection and annotation for a list of images. + // + // Progress and results can be retrieved through the + // `google.longrunning.Operations` interface. + // `Operation.metadata` contains `OperationMetadata` (metadata). + // `Operation.response` contains `AsyncBatchAnnotateImagesResponse` (results). + // + // This service will write image annotation outputs to json files in customer + // GCS bucket, each json file containing BatchAnnotateImagesResponse proto. + rpc AsyncBatchAnnotateImages(AsyncBatchAnnotateImagesRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p4beta1/images:asyncBatchAnnotate" + body: "*" + }; + } + + // Run asynchronous image detection and annotation for a list of generic + // files, such as PDF files, which may contain multiple pages and multiple + // images per page. Progress and results can be retrieved through the + // `google.longrunning.Operations` interface. + // `Operation.metadata` contains `OperationMetadata` (metadata). + // `Operation.response` contains `AsyncBatchAnnotateFilesResponse` (results). + rpc AsyncBatchAnnotateFiles(AsyncBatchAnnotateFilesRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p4beta1/files:asyncBatchAnnotate" + body: "*" + }; + } +} + +// The type of Google Cloud Vision API detection to perform, and the maximum +// number of results to return for that type. Multiple `Feature` objects can +// be specified in the `features` list. +message Feature { + // Type of Google Cloud Vision API feature to be extracted. + enum Type { + // Unspecified feature type. + TYPE_UNSPECIFIED = 0; + + // Run face detection. + FACE_DETECTION = 1; + + // Run landmark detection. + LANDMARK_DETECTION = 2; + + // Run logo detection. + LOGO_DETECTION = 3; + + // Run label detection. + LABEL_DETECTION = 4; + + // Run text detection / optical character recognition (OCR). Text detection + // is optimized for areas of text within a larger image; if the image is + // a document, use `DOCUMENT_TEXT_DETECTION` instead. + TEXT_DETECTION = 5; + + // Run dense text document OCR. Takes precedence when both + // `DOCUMENT_TEXT_DETECTION` and `TEXT_DETECTION` are present. + DOCUMENT_TEXT_DETECTION = 11; + + // Run Safe Search to detect potentially unsafe + // or undesirable content. + SAFE_SEARCH_DETECTION = 6; + + // Compute a set of image properties, such as the + // image's dominant colors. + IMAGE_PROPERTIES = 7; + + // Run crop hints. + CROP_HINTS = 9; + + // Run web detection. + WEB_DETECTION = 10; + + // Run Product Search. + PRODUCT_SEARCH = 12; + + // Run localizer for object detection. + OBJECT_LOCALIZATION = 19; + } + + // The feature type. + Type type = 1; + + // Maximum number of results of this type. Does not apply to + // `TEXT_DETECTION`, `DOCUMENT_TEXT_DETECTION`, or `CROP_HINTS`. + int32 max_results = 2; + + // Model to use for the feature. + // Supported values: "builtin/stable" (the default if unset) and + // "builtin/latest". + string model = 3; +} + +// External image source (Google Cloud Storage or web URL image location). +message ImageSource { + // **Use `image_uri` instead.** + // + // The Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more info. + string gcs_image_uri = 1; + + // The URI of the source image. Can be either: + // + // 1. A Google Cloud Storage URI of the form + // `gs://bucket_name/object_name`. Object versioning is not supported. See + // [Google Cloud Storage Request + // URIs](https://cloud.google.com/storage/docs/reference-uris) for more + // info. + // + // 2. A publicly-accessible image HTTP/HTTPS URL. When fetching images from + // HTTP/HTTPS URLs, Google cannot guarantee that the request will be + // completed. Your request may fail if the specified host denies the + // request (e.g. due to request throttling or DOS prevention), or if Google + // throttles requests to the site for abuse prevention. You should not + // depend on externally-hosted images for production applications. + // + // When both `gcs_image_uri` and `image_uri` are specified, `image_uri` takes + // precedence. + string image_uri = 2; +} + +// Client image to perform Google Cloud Vision API tasks over. +message Image { + // Image content, represented as a stream of bytes. + // Note: As with all `bytes` fields, protobuffers use a pure binary + // representation, whereas JSON representations use base64. + bytes content = 1; + + // Google Cloud Storage image location, or publicly-accessible image + // URL. If both `content` and `source` are provided for an image, `content` + // takes precedence and is used to perform the image annotation request. + ImageSource source = 2; +} + +// A bucketized representation of likelihood, which is intended to give clients +// highly stable results across model upgrades. +enum Likelihood { + // Unknown likelihood. + UNKNOWN = 0; + + // It is very unlikely that the image belongs to the specified vertical. + VERY_UNLIKELY = 1; + + // It is unlikely that the image belongs to the specified vertical. + UNLIKELY = 2; + + // It is possible that the image belongs to the specified vertical. + POSSIBLE = 3; + + // It is likely that the image belongs to the specified vertical. + LIKELY = 4; + + // It is very likely that the image belongs to the specified vertical. + VERY_LIKELY = 5; +} + +// A face annotation object contains the results of face detection. +message FaceAnnotation { + // A face-specific landmark (for example, a face feature). + message Landmark { + // Face landmark (feature) type. + // Left and right are defined from the vantage of the viewer of the image + // without considering mirror projections typical of photos. So, `LEFT_EYE`, + // typically, is the person's right eye. + enum Type { + // Unknown face landmark detected. Should not be filled. + UNKNOWN_LANDMARK = 0; + + // Left eye. + LEFT_EYE = 1; + + // Right eye. + RIGHT_EYE = 2; + + // Left of left eyebrow. + LEFT_OF_LEFT_EYEBROW = 3; + + // Right of left eyebrow. + RIGHT_OF_LEFT_EYEBROW = 4; + + // Left of right eyebrow. + LEFT_OF_RIGHT_EYEBROW = 5; + + // Right of right eyebrow. + RIGHT_OF_RIGHT_EYEBROW = 6; + + // Midpoint between eyes. + MIDPOINT_BETWEEN_EYES = 7; + + // Nose tip. + NOSE_TIP = 8; + + // Upper lip. + UPPER_LIP = 9; + + // Lower lip. + LOWER_LIP = 10; + + // Mouth left. + MOUTH_LEFT = 11; + + // Mouth right. + MOUTH_RIGHT = 12; + + // Mouth center. + MOUTH_CENTER = 13; + + // Nose, bottom right. + NOSE_BOTTOM_RIGHT = 14; + + // Nose, bottom left. + NOSE_BOTTOM_LEFT = 15; + + // Nose, bottom center. + NOSE_BOTTOM_CENTER = 16; + + // Left eye, top boundary. + LEFT_EYE_TOP_BOUNDARY = 17; + + // Left eye, right corner. + LEFT_EYE_RIGHT_CORNER = 18; + + // Left eye, bottom boundary. + LEFT_EYE_BOTTOM_BOUNDARY = 19; + + // Left eye, left corner. + LEFT_EYE_LEFT_CORNER = 20; + + // Right eye, top boundary. + RIGHT_EYE_TOP_BOUNDARY = 21; + + // Right eye, right corner. + RIGHT_EYE_RIGHT_CORNER = 22; + + // Right eye, bottom boundary. + RIGHT_EYE_BOTTOM_BOUNDARY = 23; + + // Right eye, left corner. + RIGHT_EYE_LEFT_CORNER = 24; + + // Left eyebrow, upper midpoint. + LEFT_EYEBROW_UPPER_MIDPOINT = 25; + + // Right eyebrow, upper midpoint. + RIGHT_EYEBROW_UPPER_MIDPOINT = 26; + + // Left ear tragion. + LEFT_EAR_TRAGION = 27; + + // Right ear tragion. + RIGHT_EAR_TRAGION = 28; + + // Left eye pupil. + LEFT_EYE_PUPIL = 29; + + // Right eye pupil. + RIGHT_EYE_PUPIL = 30; + + // Forehead glabella. + FOREHEAD_GLABELLA = 31; + + // Chin gnathion. + CHIN_GNATHION = 32; + + // Chin left gonion. + CHIN_LEFT_GONION = 33; + + // Chin right gonion. + CHIN_RIGHT_GONION = 34; + } + + // Face landmark type. + Type type = 3; + + // Face landmark position. + Position position = 4; + } + + // The bounding polygon around the face. The coordinates of the bounding box + // are in the original image's scale. + // The bounding box is computed to "frame" the face in accordance with human + // expectations. It is based on the landmarker results. + // Note that one or more x and/or y coordinates may not be generated in the + // `BoundingPoly` (the polygon will be unbounded) if only a partial face + // appears in the image to be annotated. + BoundingPoly bounding_poly = 1; + + // The `fd_bounding_poly` bounding polygon is tighter than the + // `boundingPoly`, and encloses only the skin part of the face. Typically, it + // is used to eliminate the face from any image analysis that detects the + // "amount of skin" visible in an image. It is not based on the + // landmarker results, only on the initial face detection, hence + // the <code>fd</code> (face detection) prefix. + BoundingPoly fd_bounding_poly = 2; + + // Detected face landmarks. + repeated Landmark landmarks = 3; + + // Roll angle, which indicates the amount of clockwise/anti-clockwise rotation + // of the face relative to the image vertical about the axis perpendicular to + // the face. Range [-180,180]. + float roll_angle = 4; + + // Yaw angle, which indicates the leftward/rightward angle that the face is + // pointing relative to the vertical plane perpendicular to the image. Range + // [-180,180]. + float pan_angle = 5; + + // Pitch angle, which indicates the upwards/downwards angle that the face is + // pointing relative to the image's horizontal plane. Range [-180,180]. + float tilt_angle = 6; + + // Detection confidence. Range [0, 1]. + float detection_confidence = 7; + + // Face landmarking confidence. Range [0, 1]. + float landmarking_confidence = 8; + + // Joy likelihood. + Likelihood joy_likelihood = 9; + + // Sorrow likelihood. + Likelihood sorrow_likelihood = 10; + + // Anger likelihood. + Likelihood anger_likelihood = 11; + + // Surprise likelihood. + Likelihood surprise_likelihood = 12; + + // Under-exposed likelihood. + Likelihood under_exposed_likelihood = 13; + + // Blurred likelihood. + Likelihood blurred_likelihood = 14; + + // Headwear likelihood. + Likelihood headwear_likelihood = 15; +} + +// Detected entity location information. +message LocationInfo { + // lat/long location coordinates. + google.type.LatLng lat_lng = 1; +} + +// A `Property` consists of a user-supplied name/value pair. +message Property { + // Name of the property. + string name = 1; + + // Value of the property. + string value = 2; + + // Value of numeric properties. + uint64 uint64_value = 3; +} + +// Set of detected entity features. +message EntityAnnotation { + // Opaque entity ID. Some IDs may be available in + // [Google Knowledge Graph Search + // API](https://developers.google.com/knowledge-graph/). + string mid = 1; + + // The language code for the locale in which the entity textual + // `description` is expressed. + string locale = 2; + + // Entity textual description, expressed in its `locale` language. + string description = 3; + + // Overall score of the result. Range [0, 1]. + float score = 4; + + // **Deprecated. Use `score` instead.** + // The accuracy of the entity detection in an image. + // For example, for an image in which the "Eiffel Tower" entity is detected, + // this field represents the confidence that there is a tower in the query + // image. Range [0, 1]. + float confidence = 5 [deprecated = true]; + + // The relevancy of the ICA (Image Content Annotation) label to the + // image. For example, the relevancy of "tower" is likely higher to an image + // containing the detected "Eiffel Tower" than to an image containing a + // detected distant towering building, even though the confidence that + // there is a tower in each image may be the same. Range [0, 1]. + float topicality = 6; + + // Image region to which this entity belongs. Not produced + // for `LABEL_DETECTION` features. + BoundingPoly bounding_poly = 7; + + // The location information for the detected entity. Multiple + // `LocationInfo` elements can be present because one location may + // indicate the location of the scene in the image, and another location + // may indicate the location of the place where the image was taken. + // Location information is usually present for landmarks. + repeated LocationInfo locations = 8; + + // Some entities may have optional user-supplied `Property` (name/value) + // fields, such a score or string that qualifies the entity. + repeated Property properties = 9; +} + +// Set of detected objects with bounding boxes. +message LocalizedObjectAnnotation { + // Object ID that should align with EntityAnnotation mid. + string mid = 1; + + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + + // Object name, expressed in its `language_code` language. + string name = 3; + + // Score of the result. Range [0, 1]. + float score = 4; + + // Image region to which this object belongs. This must be populated. + BoundingPoly bounding_poly = 5; +} + +// Set of features pertaining to the image, computed by computer vision +// methods over safe-search verticals (for example, adult, spoof, medical, +// violence). +message SafeSearchAnnotation { + // Represents the adult content likelihood for the image. Adult content may + // contain elements such as nudity, pornographic images or cartoons, or + // sexual activities. + Likelihood adult = 1; + + // Spoof likelihood. The likelihood that an modification + // was made to the image's canonical version to make it appear + // funny or offensive. + Likelihood spoof = 2; + + // Likelihood that this is a medical image. + Likelihood medical = 3; + + // Likelihood that this image contains violent content. + Likelihood violence = 4; + + // Likelihood that the request image contains racy content. Racy content may + // include (but is not limited to) skimpy or sheer clothing, strategically + // covered nudity, lewd or provocative poses, or close-ups of sensitive + // body areas. + Likelihood racy = 9; +} + +// Rectangle determined by min and max `LatLng` pairs. +message LatLongRect { + // Min lat/long pair. + google.type.LatLng min_lat_lng = 1; + + // Max lat/long pair. + google.type.LatLng max_lat_lng = 2; +} + +// Color information consists of RGB channels, score, and the fraction of +// the image that the color occupies in the image. +message ColorInfo { + // RGB components of the color. + google.type.Color color = 1; + + // Image-specific score for this color. Value in range [0, 1]. + float score = 2; + + // The fraction of pixels the color occupies in the image. + // Value in range [0, 1]. + float pixel_fraction = 3; +} + +// Set of dominant colors and their corresponding scores. +message DominantColorsAnnotation { + // RGB color values with their score and pixel fraction. + repeated ColorInfo colors = 1; +} + +// Stores image properties, such as dominant colors. +message ImageProperties { + // If present, dominant colors completed successfully. + DominantColorsAnnotation dominant_colors = 1; +} + +// Single crop hint that is used to generate a new crop when serving an image. +message CropHint { + // The bounding polygon for the crop region. The coordinates of the bounding + // box are in the original image's scale. + BoundingPoly bounding_poly = 1; + + // Confidence of this being a salient region. Range [0, 1]. + float confidence = 2; + + // Fraction of importance of this salient region with respect to the original + // image. + float importance_fraction = 3; +} + +// Set of crop hints that are used to generate new crops when serving images. +message CropHintsAnnotation { + // Crop hint results. + repeated CropHint crop_hints = 1; +} + +// Parameters for crop hints annotation request. +message CropHintsParams { + // Aspect ratios in floats, representing the ratio of the width to the height + // of the image. For example, if the desired aspect ratio is 4/3, the + // corresponding float value should be 1.33333. If not specified, the + // best possible crop is returned. The number of provided aspect ratios is + // limited to a maximum of 16; any aspect ratios provided after the 16th are + // ignored. + repeated float aspect_ratios = 1; +} + +// Parameters for web detection request. +message WebDetectionParams { + // Whether to include results derived from the geo information in the image. + bool include_geo_results = 2; +} + +// Image context and/or feature-specific parameters. +message ImageContext { + // Not used. + LatLongRect lat_long_rect = 1; + + // List of languages to use for TEXT_DETECTION. In most cases, an empty value + // yields the best results since it enables automatic language detection. For + // languages based on the Latin alphabet, setting `language_hints` is not + // needed. In rare cases, when the language of the text in the image is known, + // setting a hint will help get better results (although it will be a + // significant hindrance if the hint is wrong). Text detection returns an + // error if one or more of the specified languages is not one of the + // [supported languages](/vision/docs/languages). + repeated string language_hints = 2; + + // Parameters for crop hints annotation request. + CropHintsParams crop_hints_params = 4; + + // Parameters for product search. + ProductSearchParams product_search_params = 5; + + // Parameters for web detection. + WebDetectionParams web_detection_params = 6; +} + +// Request for performing Google Cloud Vision API tasks over a user-provided +// image, with user-requested features, and with context information. +message AnnotateImageRequest { + // The image to be processed. + Image image = 1; + + // Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image. + ImageContext image_context = 3; +} + +// If an image was produced from a file (e.g. a PDF), this message gives +// information about the source of that image. +message ImageAnnotationContext { + // The URI of the file used to produce the image. + string uri = 1; + + // If the file was a PDF or TIFF, this field gives the page number within + // the file used to produce the image. + int32 page_number = 2; +} + +// Response to an image annotation request. +message AnnotateImageResponse { + // If present, face detection has completed successfully. + repeated FaceAnnotation face_annotations = 1; + + // If present, landmark detection has completed successfully. + repeated EntityAnnotation landmark_annotations = 2; + + // If present, logo detection has completed successfully. + repeated EntityAnnotation logo_annotations = 3; + + // If present, label detection has completed successfully. + repeated EntityAnnotation label_annotations = 4; + + // If present, localized object detection has completed successfully. + // This will be sorted descending by confidence score. + repeated LocalizedObjectAnnotation localized_object_annotations = 22; + + // If present, text (OCR) detection has completed successfully. + repeated EntityAnnotation text_annotations = 5; + + // If present, text (OCR) detection or document (OCR) text detection has + // completed successfully. + // This annotation provides the structural hierarchy for the OCR detected + // text. + TextAnnotation full_text_annotation = 12; + + // If present, safe-search annotation has completed successfully. + SafeSearchAnnotation safe_search_annotation = 6; + + // If present, image properties were extracted successfully. + ImageProperties image_properties_annotation = 8; + + // If present, crop hints have completed successfully. + CropHintsAnnotation crop_hints_annotation = 11; + + // If present, web detection has completed successfully. + WebDetection web_detection = 13; + + // If present, product search has completed successfully. + ProductSearchResults product_search_results = 14; + + // If set, represents the error message for the operation. + // Note that filled-in image annotations are guaranteed to be + // correct, even when `error` is set. + google.rpc.Status error = 9; + + // If present, contextual information is needed to understand where this image + // comes from. + ImageAnnotationContext context = 21; +} + +// Response to a single file annotation request. A file may contain one or more +// images, which individually have their own responses. +message AnnotateFileResponse { + // Information about the file for which this response is generated. + InputConfig input_config = 1; + + // Individual responses to images found within the file. + repeated AnnotateImageResponse responses = 2; + + // This field gives the total number of pages in the file. + int32 total_pages = 3; +} + +// Multiple image annotation requests are batched into a single service call. +message BatchAnnotateImagesRequest { + // Individual image annotation requests for this batch. + repeated AnnotateImageRequest requests = 1; +} + +// Response to a batch image annotation request. +message BatchAnnotateImagesResponse { + // Individual responses to image annotation requests within the batch. + repeated AnnotateImageResponse responses = 1; +} + +// A request to annotate one single file, e.g. a PDF, TIFF or GIF file. +message AnnotateFileRequest { + // Required. Information about the input file. + InputConfig input_config = 1; + + // Required. Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image(s) in the file. + ImageContext image_context = 3; + + // Pages of the file to perform image annotation. + // + // Pages starts from 1, we assume the first page of the file is page 1. + // At most 5 pages are supported per request. Pages can be negative. + // + // Page 1 means the first page. + // Page 2 means the second page. + // Page -1 means the last page. + // Page -2 means the second to the last page. + // + // If the file is GIF instead of PDF or TIFF, page refers to GIF frames. + // + // If this field is empty, by default the service performs image annotation + // for the first 5 pages of the file. + repeated int32 pages = 4; +} + +// A list of requests to annotate files using the BatchAnnotateFiles API. +message BatchAnnotateFilesRequest { + // The list of file annotation requests. Right now we support only one + // AnnotateFileRequest in BatchAnnotateFilesRequest. + repeated AnnotateFileRequest requests = 1; +} + +// A list of file annotation responses. +message BatchAnnotateFilesResponse { + // The list of file annotation responses, each response corresponding to each + // AnnotateFileRequest in BatchAnnotateFilesRequest. + repeated AnnotateFileResponse responses = 1; +} + +// An offline file annotation request. +message AsyncAnnotateFileRequest { + // Required. Information about the input file. + InputConfig input_config = 1; + + // Required. Requested features. + repeated Feature features = 2; + + // Additional context that may accompany the image(s) in the file. + ImageContext image_context = 3; + + // Required. The desired output location and metadata (e.g. format). + OutputConfig output_config = 4; +} + +// The response for a single offline file annotation request. +message AsyncAnnotateFileResponse { + // The output location and metadata from AsyncAnnotateFileRequest. + OutputConfig output_config = 1; +} + +// Request for async image annotation for a list of images. +message AsyncBatchAnnotateImagesRequest { + // Individual image annotation requests for this batch. + repeated AnnotateImageRequest requests = 1; + + // Required. The desired output location and metadata (e.g. format). + OutputConfig output_config = 2; +} + +// Response to an async batch image annotation request. +message AsyncBatchAnnotateImagesResponse { + // The output location and metadata from AsyncBatchAnnotateImagesRequest. + OutputConfig output_config = 1; +} + +// Multiple async file annotation requests are batched into a single service +// call. +message AsyncBatchAnnotateFilesRequest { + // Individual async file annotation requests for this batch. + repeated AsyncAnnotateFileRequest requests = 1; +} + +// Response to an async batch file annotation request. +message AsyncBatchAnnotateFilesResponse { + // The list of file annotation responses, one for each request in + // AsyncBatchAnnotateFilesRequest. + repeated AsyncAnnotateFileResponse responses = 1; +} + +// The desired input location and metadata. +message InputConfig { + // The Google Cloud Storage location to read the input from. + GcsSource gcs_source = 1; + + // File content, represented as a stream of bytes. + // Note: As with all `bytes` fields, protobuffers use a pure binary + // representation, whereas JSON representations use base64. + // + // Currently, this field only works for BatchAnnotateFiles requests. It does + // not work for AsyncBatchAnnotateFiles requests. + bytes content = 3; + + // The type of the file. Currently only "application/pdf" and "image/tiff" + // are supported. Wildcards are not supported. + string mime_type = 2; +} + +// The desired output location and metadata. +message OutputConfig { + // The Google Cloud Storage location to write the output(s) to. + GcsDestination gcs_destination = 1; + + // The max number of response protos to put into each output JSON file on + // Google Cloud Storage. + // The valid range is [1, 100]. If not specified, the default value is 20. + // + // For example, for one pdf file with 100 pages, 100 response protos will + // be generated. If `batch_size` = 20, then 5 json files each + // containing 20 response protos will be written under the prefix + // `gcs_destination`.`uri`. + // + // Currently, batch_size only applies to GcsDestination, with potential future + // support for other output configurations. + int32 batch_size = 2; +} + +// The Google Cloud Storage location where the input will be read from. +message GcsSource { + // Google Cloud Storage URI for the input file. This must only be a + // Google Cloud Storage object. Wildcards are not currently supported. + string uri = 1; +} + +// The Google Cloud Storage location where the output will be written to. +message GcsDestination { + // Google Cloud Storage URI where the results will be stored. Results will + // be in JSON format and preceded by its corresponding input URI. This field + // can either represent a single file, or a prefix for multiple outputs. + // Prefixes must end in a `/`. + // + // Examples: + // + // * File: gs://bucket-name/filename.json + // * Prefix: gs://bucket-name/prefix/here/ + // * File: gs://bucket-name/prefix/here + // + // If multiple outputs, each response is still AnnotateFileResponse, each of + // which contains some subset of the full list of AnnotateImageResponse. + // Multiple outputs can happen if, for example, the output JSON is too large + // and overflows into multiple sharded files. + string uri = 1; +} + +// Contains metadata for the BatchAnnotateImages operation. +message OperationMetadata { + // Batch operation states. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is received. + CREATED = 1; + + // Request is actively being processed. + RUNNING = 2; + + // The batch processing is done. + DONE = 3; + + // The batch processing was cancelled. + CANCELLED = 4; + } + + // Current state of the batch operation. + State state = 1; + + // The time when the batch request was received. + google.protobuf.Timestamp create_time = 5; + + // The time when the operation result was last updated. + google.protobuf.Timestamp update_time = 6; +} diff --git a/google/cloud/vision/v1p4beta1/product_search.proto b/google/cloud/vision/v1p4beta1/product_search.proto new file mode 100644 index 000000000..007804f31 --- /dev/null +++ b/google/cloud/vision/v1p4beta1/product_search.proto @@ -0,0 +1,98 @@ +// Copyright 2018 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.vision.v1p4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p4beta1/geometry.proto"; +import "google/cloud/vision/v1p4beta1/product_search_service.proto"; +import "google/protobuf/timestamp.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p4beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ProductSearchProto"; +option java_package = "com.google.cloud.vision.v1p4beta1"; +option objc_class_prefix = "GCVN"; + +// Parameters for a product search request. +message ProductSearchParams { + // The bounding polygon around the area of interest in the image. + // Optional. If it is not specified, system discretion will be applied. + BoundingPoly bounding_poly = 9; + + // The resource name of a + // [ProductSet][google.cloud.vision.v1p4beta1.ProductSet] to be searched for + // similar images. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`. + string product_set = 6; + + // The list of product categories to search in. Currently, we only consider + // the first category, and either "homegoods", "apparel", or "toys" should be + // specified. + repeated string product_categories = 7; + + // The filtering expression. This can be used to restrict search results based + // on Product labels. We currently support an AND of OR of key-value + // expressions, where each expression within an OR must have the same key. + // + // For example, "(color = red OR color = blue) AND brand = Google" is + // acceptable, but not "(color = red OR brand = Google)" or "color: red". + string filter = 8; +} + +// Results for a product search request. +message ProductSearchResults { + // Information about a product. + message Result { + // The Product. + Product product = 1; + + // A confidence level on the match, ranging from 0 (no confidence) to + // 1 (full confidence). + float score = 2; + + // The resource name of the image from the product that is the closest match + // to the query. + string image = 3; + } + + // Information about the products similar to a single product in a query + // image. + message GroupedResult { + // The bounding polygon around the product detected in the query image. + BoundingPoly bounding_poly = 1; + + // List of results, one for each product match. + repeated Result results = 2; + } + + // Timestamp of the index which provided these results. Changes made after + // this time are not reflected in the current results. + google.protobuf.Timestamp index_time = 2; + + // List of results, one for each product match. + repeated Result results = 5; + + // List of results grouped by products detected in the query image. Each entry + // corresponds to one bounding polygon in the query image, and contains the + // matching products specific to that region. There may be duplicate product + // matches in the union of all the per-product results. + repeated GroupedResult product_grouped_results = 6; +} diff --git a/google/cloud/vision/v1p4beta1/product_search_service.proto b/google/cloud/vision/v1p4beta1/product_search_service.proto new file mode 100644 index 000000000..e3b23c7b3 --- /dev/null +++ b/google/cloud/vision/v1p4beta1/product_search_service.proto @@ -0,0 +1,852 @@ +// Copyright 2018 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.vision.v1p4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p4beta1/geometry.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p4beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "ProductSearchServiceProto"; +option java_package = "com.google.cloud.vision.v1p4beta1"; +option objc_class_prefix = "GCVN"; + +// Manages Products and ProductSets of reference images for use in product +// search. It uses the following resource model: +// +// - The API has a collection of +// [ProductSet][google.cloud.vision.v1p4beta1.ProductSet] resources, named +// `projects/*/locations/*/productSets/*`, which acts as a way to put different +// products into groups to limit identification. +// +// In parallel, +// +// - The API has a collection of +// [Product][google.cloud.vision.v1p4beta1.Product] resources, named +// `projects/*/locations/*/products/*` +// +// - Each [Product][google.cloud.vision.v1p4beta1.Product] has a collection of +// [ReferenceImage][google.cloud.vision.v1p4beta1.ReferenceImage] resources, +// named +// `projects/*/locations/*/products/*/referenceImages/*` +service ProductSearch { + // Creates and returns a new ProductSet resource. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if display_name is missing, or is longer than + // 4096 characters. + rpc CreateProductSet(CreateProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + post: "/v1p4beta1/{parent=projects/*/locations/*}/productSets" + body: "product_set" + }; + } + + // Lists ProductSets in an unspecified order. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100, or less + // than 1. + rpc ListProductSets(ListProductSetsRequest) + returns (ListProductSetsResponse) { + option (google.api.http) = { + get: "/v1p4beta1/{parent=projects/*/locations/*}/productSets" + }; + } + + // Gets information associated with a ProductSet. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + rpc GetProductSet(GetProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + get: "/v1p4beta1/{name=projects/*/locations/*/productSets/*}" + }; + } + + // Makes changes to a ProductSet resource. + // Only display_name can be updated currently. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + // * Returns INVALID_ARGUMENT if display_name is present in update_mask but + // missing from the request or longer than 4096 characters. + rpc UpdateProductSet(UpdateProductSetRequest) returns (ProductSet) { + option (google.api.http) = { + patch: "/v1p4beta1/{product_set.name=projects/*/locations/*/productSets/*}" + body: "product_set" + }; + } + + // Permanently deletes a ProductSet. Products and ReferenceImages in the + // ProductSet are not deleted. + // + // The actual image files are not deleted from Google Cloud Storage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the ProductSet does not exist. + rpc DeleteProductSet(DeleteProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1p4beta1/{name=projects/*/locations/*/productSets/*}" + }; + } + + // Creates and returns a new product resource. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if display_name is missing or longer than 4096 + // characters. + // * Returns INVALID_ARGUMENT if description is longer than 4096 characters. + // * Returns INVALID_ARGUMENT if product_category is missing or invalid. + rpc CreateProduct(CreateProductRequest) returns (Product) { + option (google.api.http) = { + post: "/v1p4beta1/{parent=projects/*/locations/*}/products" + body: "product" + }; + } + + // Lists products in an unspecified order. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1. + rpc ListProducts(ListProductsRequest) returns (ListProductsResponse) { + option (google.api.http) = { + get: "/v1p4beta1/{parent=projects/*/locations/*}/products" + }; + } + + // Gets information associated with a Product. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product does not exist. + rpc GetProduct(GetProductRequest) returns (Product) { + option (google.api.http) = { + get: "/v1p4beta1/{name=projects/*/locations/*/products/*}" + }; + } + + // Makes changes to a Product resource. + // Only the `display_name`, `description`, and `labels` fields can be updated + // right now. + // + // If labels are updated, the change will not be reflected in queries until + // the next index time. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product does not exist. + // * Returns INVALID_ARGUMENT if display_name is present in update_mask but is + // missing from the request or longer than 4096 characters. + // * Returns INVALID_ARGUMENT if description is present in update_mask but is + // longer than 4096 characters. + // * Returns INVALID_ARGUMENT if product_category is present in update_mask. + rpc UpdateProduct(UpdateProductRequest) returns (Product) { + option (google.api.http) = { + patch: "/v1p4beta1/{product.name=projects/*/locations/*/products/*}" + body: "product" + }; + } + + // Permanently deletes a product and its reference images. + // + // Metadata of the product and all its images will be deleted right away, but + // search queries against ProductSets containing the product may still work + // until all related caches are refreshed. + // + // Possible errors: + // + // * Returns NOT_FOUND if the product does not exist. + rpc DeleteProduct(DeleteProductRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1p4beta1/{name=projects/*/locations/*/products/*}" + }; + } + + // Creates and returns a new ReferenceImage resource. + // + // The `bounding_poly` field is optional. If `bounding_poly` is not specified, + // the system will try to detect regions of interest in the image that are + // compatible with the product_category on the parent product. If it is + // specified, detection is ALWAYS skipped. The system converts polygons into + // non-rotated rectangles. + // + // Note that the pipeline will resize the image if the image resolution is too + // large to process (above 50MP). + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if the image_uri is missing or longer than 4096 + // characters. + // * Returns INVALID_ARGUMENT if the product does not exist. + // * Returns INVALID_ARGUMENT if bounding_poly is not provided, and nothing + // compatible with the parent product's product_category is detected. + // * Returns INVALID_ARGUMENT if bounding_poly contains more than 10 polygons. + rpc CreateReferenceImage(CreateReferenceImageRequest) + returns (ReferenceImage) { + option (google.api.http) = { + post: "/v1p4beta1/{parent=projects/*/locations/*/products/*}/referenceImages" + body: "reference_image" + }; + } + + // Permanently deletes a reference image. + // + // The image metadata will be deleted right away, but search queries + // against ProductSets containing the image may still work until all related + // caches are refreshed. + // + // The actual image files are not deleted from Google Cloud Storage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the reference image does not exist. + rpc DeleteReferenceImage(DeleteReferenceImageRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1p4beta1/{name=projects/*/locations/*/products/*/referenceImages/*}" + }; + } + + // Lists reference images. + // + // Possible errors: + // + // * Returns NOT_FOUND if the parent product does not exist. + // * Returns INVALID_ARGUMENT if the page_size is greater than 100, or less + // than 1. + rpc ListReferenceImages(ListReferenceImagesRequest) + returns (ListReferenceImagesResponse) { + option (google.api.http) = { + get: "/v1p4beta1/{parent=projects/*/locations/*/products/*}/referenceImages" + }; + } + + // Gets information associated with a ReferenceImage. + // + // Possible errors: + // + // * Returns NOT_FOUND if the specified image does not exist. + rpc GetReferenceImage(GetReferenceImageRequest) returns (ReferenceImage) { + option (google.api.http) = { + get: "/v1p4beta1/{name=projects/*/locations/*/products/*/referenceImages/*}" + }; + } + + // Adds a Product to the specified ProductSet. If the Product is already + // present, no change is made. + // + // One Product can be added to at most 100 ProductSets. + // + // Possible errors: + // + // * Returns NOT_FOUND if the Product or the ProductSet doesn't exist. + rpc AddProductToProductSet(AddProductToProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1p4beta1/{name=projects/*/locations/*/productSets/*}:addProduct" + body: "*" + }; + } + + // Removes a Product from the specified ProductSet. + // + // Possible errors: + // + // * Returns NOT_FOUND If the Product is not found under the ProductSet. + rpc RemoveProductFromProductSet(RemoveProductFromProductSetRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1p4beta1/{name=projects/*/locations/*/productSets/*}:removeProduct" + body: "*" + }; + } + + // Lists the Products in a ProductSet, in an unspecified order. If the + // ProductSet does not exist, the products field of the response will be + // empty. + // + // Possible errors: + // + // * Returns INVALID_ARGUMENT if page_size is greater than 100 or less than 1. + rpc ListProductsInProductSet(ListProductsInProductSetRequest) + returns (ListProductsInProductSetResponse) { + option (google.api.http) = { + get: "/v1p4beta1/{name=projects/*/locations/*/productSets/*}/products" + }; + } + + // Asynchronous API that imports a list of reference images to specified + // product sets based on a list of image information. + // + // The [google.longrunning.Operation][google.longrunning.Operation] API can be + // used to keep track of the progress and results of the request. + // `Operation.metadata` contains `BatchOperationMetadata`. (progress) + // `Operation.response` contains `ImportProductSetsResponse`. (results) + // + // The input source of this method is a csv file on Google Cloud Storage. + // For the format of the csv file please see + // [ImportProductSetsGcsSource.csv_file_uri][google.cloud.vision.v1p4beta1.ImportProductSetsGcsSource.csv_file_uri]. + rpc ImportProductSets(ImportProductSetsRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1p4beta1/{parent=projects/*/locations/*}/productSets:import" + body: "*" + }; + } +} + +// A Product contains ReferenceImages. +message Product { + // A product label represented as a key-value pair. + message KeyValue { + // The key of the label attached to the product. Cannot be empty and cannot + // exceed 128 bytes. + string key = 1; + + // The value of the label attached to the product. Cannot be empty and + // cannot exceed 128 bytes. + string value = 2; + } + + // The resource name of the product. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + // + // This field is ignored when creating a product. + string name = 1; + + // The user-provided name for this Product. Must not be empty. Must be at most + // 4096 characters long. + string display_name = 2; + + // User-provided metadata to be stored with this product. Must be at most 4096 + // characters long. + string description = 3; + + // The category for the product identified by the reference image. This should + // be either "homegoods", "apparel", or "toys". + // + // This field is immutable. + string product_category = 4; + + // Key-value pairs that can be attached to a product. At query time, + // constraints can be specified based on the product_labels. + // + // Note that integer values can be provided as strings, e.g. "1199". Only + // strings with integer values can match a range-based restriction which is + // to be supported soon. + // + // Multiple values can be assigned to the same key. One product may have up to + // 100 product_labels. + repeated KeyValue product_labels = 5; +} + +// A ProductSet contains Products. A ProductSet can contain a maximum of 1 +// million reference images. If the limit is exceeded, periodic indexing will +// fail. +message ProductSet { + // The resource name of the ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`. + // + // This field is ignored when creating a ProductSet. + string name = 1; + + // The user-provided name for this ProductSet. Must not be empty. Must be at + // most 4096 characters long. + string display_name = 2; + + // Output only. The time at which this ProductSet was last indexed. Query + // results will reflect all updates before this time. If this ProductSet has + // never been indexed, this timestamp is the default value + // "1970-01-01T00:00:00Z". + // + // This field is ignored when creating a ProductSet. + google.protobuf.Timestamp index_time = 3; + + // Output only. If there was an error with indexing the product set, the field + // is populated. + // + // This field is ignored when creating a ProductSet. + google.rpc.Status index_error = 4; +} + +// A `ReferenceImage` represents a product image and its associated metadata, +// such as bounding boxes. +message ReferenceImage { + // The resource name of the reference image. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID`. + // + // This field is ignored when creating a reference image. + string name = 1; + + // The Google Cloud Storage URI of the reference image. + // + // The URI must start with `gs://`. + // + // Required. + string uri = 2; + + // Bounding polygons around the areas of interest in the reference image. + // Optional. If this field is empty, the system will try to detect regions of + // interest. At most 10 bounding polygons will be used. + // + // The provided shape is converted into a non-rotated rectangle. Once + // converted, the small edge of the rectangle must be greater than or equal + // to 300 pixels. The aspect ratio must be 1:4 or less (i.e. 1:3 is ok; 1:5 + // is not). + repeated BoundingPoly bounding_polys = 3; +} + +// Request message for the `CreateProduct` method. +message CreateProductRequest { + // The project in which the Product should be created. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The product to create. + Product product = 2; + + // A user-supplied resource id for this Product. If set, the server will + // attempt to use this value as the resource id. If it is already in use, an + // error is returned with code ALREADY_EXISTS. Must be at most 128 characters + // long. It cannot contain the character `/`. + string product_id = 3; +} + +// Request message for the `ListProducts` method. +message ListProductsRequest { + // The project OR ProductSet from which Products should be listed. + // + // Format: + // `projects/PROJECT_ID/locations/LOC_ID` + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProducts` method. +message ListProductsResponse { + // List of products. + repeated Product products = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// Request message for the `GetProduct` method. +message GetProductRequest { + // Resource name of the Product to get. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string name = 1; +} + +// Request message for the `UpdateProduct` method. +message UpdateProductRequest { + // The Product resource which replaces the one on the server. + // product.name is immutable. + Product product = 1; + + // The [FieldMask][google.protobuf.FieldMask] that specifies which fields + // to update. + // If update_mask isn't specified, all mutable fields are to be updated. + // Valid mask paths include `product_labels`, `display_name`, and + // `description`. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for the `DeleteProduct` method. +message DeleteProductRequest { + // Resource name of product to delete. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string name = 1; +} + +// Request message for the `CreateProductSet` method. +message CreateProductSetRequest { + // The project in which the ProductSet should be created. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The ProductSet to create. + ProductSet product_set = 2; + + // A user-supplied resource id for this ProductSet. If set, the server will + // attempt to use this value as the resource id. If it is already in use, an + // error is returned with code ALREADY_EXISTS. Must be at most 128 characters + // long. It cannot contain the character `/`. + string product_set_id = 3; +} + +// Request message for the `ListProductSets` method. +message ListProductSetsRequest { + // The project from which ProductSets should be listed. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProductSets` method. +message ListProductSetsResponse { + // List of ProductSets. + repeated ProductSet product_sets = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// Request message for the `GetProductSet` method. +message GetProductSetRequest { + // Resource name of the ProductSet to get. + // + // Format is: + // `projects/PROJECT_ID/locations/LOG_ID/productSets/PRODUCT_SET_ID` + string name = 1; +} + +// Request message for the `UpdateProductSet` method. +message UpdateProductSetRequest { + // The ProductSet resource which replaces the one on the server. + ProductSet product_set = 1; + + // The [FieldMask][google.protobuf.FieldMask] that specifies which fields to + // update. + // If update_mask isn't specified, all mutable fields are to be updated. + // Valid mask path is `display_name`. + google.protobuf.FieldMask update_mask = 2; +} + +// Request message for the `DeleteProductSet` method. +message DeleteProductSetRequest { + // Resource name of the ProductSet to delete. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; +} + +// Request message for the `CreateReferenceImage` method. +message CreateReferenceImageRequest { + // Resource name of the product in which to create the reference image. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + string parent = 1; + + // The reference image to create. + // If an image ID is specified, it is ignored. + ReferenceImage reference_image = 2; + + // A user-supplied resource id for the ReferenceImage to be added. If set, + // the server will attempt to use this value as the resource id. If it is + // already in use, an error is returned with code ALREADY_EXISTS. Must be at + // most 128 characters long. It cannot contain the character `/`. + string reference_image_id = 3; +} + +// Request message for the `ListReferenceImages` method. +message ListReferenceImagesRequest { + // Resource name of the product containing the reference images. + // + // Format is + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`. + string parent = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // A token identifying a page of results to be returned. This is the value + // of `nextPageToken` returned in a previous reference image list request. + // + // Defaults to the first page if not specified. + string page_token = 3; +} + +// Response message for the `ListReferenceImages` method. +message ListReferenceImagesResponse { + // The list of reference images. + repeated ReferenceImage reference_images = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string next_page_token = 3; +} + +// Request message for the `GetReferenceImage` method. +message GetReferenceImageRequest { + // The resource name of the ReferenceImage to get. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID`. + string name = 1; +} + +// Request message for the `DeleteReferenceImage` method. +message DeleteReferenceImageRequest { + // The resource name of the reference image to delete. + // + // Format is: + // + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID/referenceImages/IMAGE_ID` + string name = 1; +} + +// Request message for the `AddProductToProductSet` method. +message AddProductToProductSetRequest { + // The resource name for the ProductSet to modify. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The resource name for the Product to be added to this ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string product = 2; +} + +// Request message for the `RemoveProductFromProductSet` method. +message RemoveProductFromProductSetRequest { + // The resource name for the ProductSet to modify. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The resource name for the Product to be removed from this ProductSet. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID` + string product = 2; +} + +// Request message for the `ListProductsInProductSet` method. +message ListProductsInProductSetRequest { + // The ProductSet resource for which to retrieve Products. + // + // Format is: + // `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID` + string name = 1; + + // The maximum number of items to return. Default 10, maximum 100. + int32 page_size = 2; + + // The next_page_token returned from a previous List request, if any. + string page_token = 3; +} + +// Response message for the `ListProductsInProductSet` method. +message ListProductsInProductSetResponse { + // The list of Products. + repeated Product products = 1; + + // Token to retrieve the next page of results, or empty if there are no more + // results in the list. + string next_page_token = 2; +} + +// The Google Cloud Storage location for a csv file which preserves a list of +// ImportProductSetRequests in each line. +message ImportProductSetsGcsSource { + // The Google Cloud Storage URI of the input csv file. + // + // The URI must start with `gs://`. + // + // The format of the input csv file should be one image per line. + // In each line, there are 8 columns. + // + // 1. image-uri + // 2. image-id + // 3. product-set-id + // 4. product-id + // 5. product-category + // 6. product-display-name + // 7. labels + // 8. bounding-poly + // + // The `image-uri`, `product-set-id`, `product-id`, and `product-category` + // columns are required. All other columns are optional. + // + // If the `ProductSet` or `Product` specified by the `product-set-id` and + // `product-id` values does not exist, then the system will create a new + // `ProductSet` or `Product` for the image. In this case, the + // `product-display-name` column refers to + // [display_name][google.cloud.vision.v1p4beta1.Product.display_name], the + // `product-category` column refers to + // [product_category][google.cloud.vision.v1p4beta1.Product.product_category], + // and the `labels` column refers to + // [product_labels][google.cloud.vision.v1p4beta1.Product.product_labels]. + // + // The `image-id` column is optional but must be unique if provided. If it is + // empty, the system will automatically assign a unique id to the image. + // + // The `product-display-name` column is optional. If it is empty, the system + // sets the [display_name][google.cloud.vision.v1p4beta1.Product.display_name] + // field for the product to a space (" "). You can update the `display_name` + // later by using the API. + // + // If a `Product` with the specified `product-id` already exists, then the + // system ignores the `product-display-name`, `product-category`, and `labels` + // columns. + // + // The `labels` column (optional) is a line containing a list of + // comma-separated key-value pairs, in the following format: + // + // "key_1=value_1,key_2=value_2,...,key_n=value_n" + // + // The `bounding-poly` column (optional) identifies one region of + // interest from the image in the same manner as `CreateReferenceImage`. If + // you do not specify the `bounding-poly` column, then the system will try to + // detect regions of interest automatically. + // + // At most one `bounding-poly` column is allowed per line. If the image + // contains multiple regions of interest, add a line to the CSV file that + // includes the same product information, and the `bounding-poly` values for + // each region of interest. + // + // The `bounding-poly` column must contain an even number of comma-separated + // numbers, in the format "p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y". Use + // non-negative integers for absolute bounding polygons, and float values + // in [0, 1] for normalized bounding polygons. + // + // The system will resize the image if the image resolution is too + // large to process (larger than 20MP). + string csv_file_uri = 1; +} + +// The input content for the `ImportProductSets` method. +message ImportProductSetsInputConfig { + // The source of the input. + oneof source { + // The Google Cloud Storage location for a csv file which preserves a list + // of ImportProductSetRequests in each line. + ImportProductSetsGcsSource gcs_source = 1; + } +} + +// Request message for the `ImportProductSets` method. +message ImportProductSetsRequest { + // The project in which the ProductSets should be imported. + // + // Format is `projects/PROJECT_ID/locations/LOC_ID`. + string parent = 1; + + // The input content for the list of requests. + ImportProductSetsInputConfig input_config = 2; +} + +// Response message for the `ImportProductSets` method. +// +// This message is returned by the +// [google.longrunning.Operations.GetOperation][google.longrunning.Operations.GetOperation] +// method in the returned +// [google.longrunning.Operation.response][google.longrunning.Operation.response] +// field. +message ImportProductSetsResponse { + // The list of reference_images that are imported successfully. + repeated ReferenceImage reference_images = 1; + + // The rpc status for each ImportProductSet request, including both successes + // and errors. + // + // The number of statuses here matches the number of lines in the csv file, + // and statuses[i] stores the success or failure status of processing the i-th + // line of the csv, starting from line 0. + repeated google.rpc.Status statuses = 2; +} + +// Metadata for the batch operations such as the current state. +// +// This is included in the `metadata` field of the `Operation` returned by the +// `GetOperation` call of the `google::longrunning::Operations` service. +message BatchOperationMetadata { + // Enumerates the possible states that the batch request can be in. + enum State { + // Invalid. + STATE_UNSPECIFIED = 0; + + // Request is actively being processed. + PROCESSING = 1; + + // The request is done and at least one item has been successfully + // processed. + SUCCESSFUL = 2; + + // The request is done and no item has been successfully processed. + FAILED = 3; + + // The request is done after the longrunning.Operations.CancelOperation has + // been called by the user. Any records that were processed before the + // cancel command are output as specified in the request. + CANCELLED = 4; + } + + // The current state of the batch operation. + State state = 1; + + // The time when the batch request was submitted to the server. + google.protobuf.Timestamp submit_time = 2; + + // The time when the batch request is finished and + // [google.longrunning.Operation.done][google.longrunning.Operation.done] is + // set to true. + google.protobuf.Timestamp end_time = 3; +} diff --git a/google/cloud/vision/v1p4beta1/text_annotation.proto b/google/cloud/vision/v1p4beta1/text_annotation.proto new file mode 100644 index 000000000..542677f27 --- /dev/null +++ b/google/cloud/vision/v1p4beta1/text_annotation.proto @@ -0,0 +1,261 @@ +// Copyright 2018 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.vision.v1p4beta1; + +import "google/api/annotations.proto"; +import "google/cloud/vision/v1p4beta1/geometry.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p4beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "TextAnnotationProto"; +option java_package = "com.google.cloud.vision.v1p4beta1"; +option objc_class_prefix = "GCVN"; + +// TextAnnotation contains a structured representation of OCR extracted text. +// The hierarchy of an OCR extracted text structure is like this: +// TextAnnotation -> Page -> Block -> Paragraph -> Word -> Symbol +// Each structural component, starting from Page, may further have their own +// properties. Properties describe detected languages, breaks etc.. Please refer +// to the +// [TextAnnotation.TextProperty][google.cloud.vision.v1p4beta1.TextAnnotation.TextProperty] +// message definition below for more detail. +message TextAnnotation { + // Detected language for a structural component. + message DetectedLanguage { + // The BCP-47 language code, such as "en-US" or "sr-Latn". For more + // information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 1; + + // Confidence of detected language. Range [0, 1]. + float confidence = 2; + } + + // Detected start or end of a structural component. + message DetectedBreak { + // Enum to denote the type of break found. New line, space etc. + enum BreakType { + // Unknown break label type. + UNKNOWN = 0; + + // Regular space. + SPACE = 1; + + // Sure space (very wide). + SURE_SPACE = 2; + + // Line-wrapping break. + EOL_SURE_SPACE = 3; + + // End-line hyphen that is not present in text; does not co-occur with + // `SPACE`, `LEADER_SPACE`, or `LINE_BREAK`. + HYPHEN = 4; + + // Line break that ends a paragraph. + LINE_BREAK = 5; + } + + // Detected break type. + BreakType type = 1; + + // True if break prepends the element. + bool is_prefix = 2; + } + + // Additional information detected on the structural component. + message TextProperty { + // A list of detected languages together with confidence. + repeated DetectedLanguage detected_languages = 1; + + // Detected start or end of a text segment. + DetectedBreak detected_break = 2; + } + + // List of pages detected by OCR. + repeated Page pages = 1; + + // UTF-8 text detected on the pages. + string text = 2; +} + +// Detected page from OCR. +message Page { + // Additional information detected on the page. + TextAnnotation.TextProperty property = 1; + + // Page width. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 width = 2; + + // Page height. For PDFs the unit is points. For images (including + // TIFFs) the unit is pixels. + int32 height = 3; + + // List of blocks of text, images etc on this page. + repeated Block blocks = 4; + + // Confidence of the OCR results on the page. Range [0, 1]. + float confidence = 5; +} + +// Logical element on the page. +message Block { + // Type of a block (text, image etc) as identified by OCR. + enum BlockType { + // Unknown block type. + UNKNOWN = 0; + + // Regular text block. + TEXT = 1; + + // Table block. + TABLE = 2; + + // Image block. + PICTURE = 3; + + // Horizontal/vertical line box. + RULER = 4; + + // Barcode block. + BARCODE = 5; + } + + // Additional information detected for the block. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the block. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // + // * when the text is horizontal it might look like: + // + // 0----1 + // | | + // 3----2 + // + // * when it's rotated 180 degrees around the top-left corner it becomes: + // + // 2----3 + // | | + // 1----0 + // + // and the vertex order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of paragraphs in this block (if this blocks is of type text). + repeated Paragraph paragraphs = 3; + + // Detected block type (text, image etc) for this block. + BlockType block_type = 4; + + // Confidence of the OCR results on the block. Range [0, 1]. + float confidence = 5; +} + +// Structural unit of text representing a number of words in certain order. +message Paragraph { + // Additional information detected for the paragraph. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the paragraph. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertex order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of words in this paragraph. + repeated Word words = 3; + + // Confidence of the OCR results for the paragraph. Range [0, 1]. + float confidence = 4; +} + +// A word representation. +message Word { + // Additional information detected for the word. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the word. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertex order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // List of symbols in the word. + // The order of the symbols follows the natural reading order. + repeated Symbol symbols = 3; + + // Confidence of the OCR results for the word. Range [0, 1]. + float confidence = 4; +} + +// A single symbol representation. +message Symbol { + // Additional information detected for the symbol. + TextAnnotation.TextProperty property = 1; + + // The bounding box for the symbol. + // The vertices are in the order of top-left, top-right, bottom-right, + // bottom-left. When a rotation of the bounding box is detected the rotation + // is represented as around the top-left corner as defined when the text is + // read in the 'natural' orientation. + // For example: + // * when the text is horizontal it might look like: + // 0----1 + // | | + // 3----2 + // * when it's rotated 180 degrees around the top-left corner it becomes: + // 2----3 + // | | + // 1----0 + // and the vertice order will still be (0, 1, 2, 3). + BoundingPoly bounding_box = 2; + + // The actual UTF-8 representation of the symbol. + string text = 3; + + // Confidence of the OCR results for the symbol. Range [0, 1]. + float confidence = 4; +} diff --git a/google/cloud/vision/v1p4beta1/vision_gapic.yaml b/google/cloud/vision/v1p4beta1/vision_gapic.yaml new file mode 100644 index 000000000..90d6f5000 --- /dev/null +++ b/google/cloud/vision/v1p4beta1/vision_gapic.yaml @@ -0,0 +1,603 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.vision.v1p4beta1 + python: + package_name: google.cloud.vision_v1p4beta1.gapic + go: + package_name: cloud.google.com/go/vision/apiv1p4beta1 + csharp: + package_name: Google.Cloud.Vision.V1p4beta1 + ruby: + package_name: Google::Cloud::Vision::V1p4beta1 + php: + package_name: Google\Cloud\Vision\V1p4beta1 + nodejs: + package_name: vision.v1p4beta1 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.vision.v1p4beta1.ProductSearch + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location} + entity_name: location + - name_pattern: projects/{project}/locations/{location}/productSets/{product_set} + entity_name: product_set + - name_pattern: projects/{project}/locations/{location}/products/{product} + entity_name: product + - name_pattern: projects/{project}/locations/{location}/products/{product}/referenceImages/{reference_image} + entity_name: reference_image + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateProductSet + flattening: + groups: + - parameters: + - parent + - product_set + - product_set_id + required_fields: + - parent + - product_set + - product_set_id + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: ListProductSets + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: product_sets + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: UpdateProductSet + flattening: + groups: + - parameters: + - product_set + - update_mask + required_fields: + - product_set + - update_mask + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + product_set.name: product_set + timeout_millis: 60000 + - name: DeleteProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: CreateProduct + flattening: + groups: + - parameters: + - parent + - product + - product_id + required_fields: + - parent + - product + - product_id + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: ListProducts + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: products + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + - name: GetProduct + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product + timeout_millis: 60000 + - name: UpdateProduct + # params. + flattening: + groups: + - parameters: + - product + - update_mask + required_fields: + - product + - update_mask + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + product.name: product + timeout_millis: 60000 + - name: DeleteProduct + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product + timeout_millis: 60000 + - name: CreateReferenceImage + flattening: + groups: + - parameters: + - parent + - reference_image + - reference_image_id + required_fields: + - parent + - reference_image + - reference_image_id + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: product + timeout_millis: 60000 + - name: DeleteReferenceImage + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: reference_image + timeout_millis: 60000 + - name: ListReferenceImages + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: reference_images + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: product + timeout_millis: 60000 + - name: GetReferenceImage + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: reference_image + timeout_millis: 60000 + - name: AddProductToProductSet + flattening: + groups: + - parameters: + - name + - product + required_fields: + - name + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: RemoveProductFromProductSet + flattening: + groups: + - parameters: + - name + - product + required_fields: + - name + - product + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: ListProductsInProductSet + flattening: + groups: + - parameters: + - name + required_fields: + - name + resource_name_treatment: STATIC_TYPES + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: products + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: product_set + timeout_millis: 60000 + - name: ImportProductSets + flattening: + groups: + - parameters: + - parent + - input_config + required_fields: + - parent + - input_config + long_running: + return_type: google.cloud.vision.v1p4beta1.ImportProductSetsResponse + metadata_type: google.cloud.vision.v1p4beta1.BatchOperationMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + resource_name_treatment: STATIC_TYPES + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: location + timeout_millis: 60000 + # The fully qualified name of the API interface. +- name: google.cloud.vision.v1p4beta1.ImageAnnotator + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 60000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 60000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: BatchAnnotateImages + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: BatchAnnotateFiles + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: AsyncBatchAnnotateImages + flattening: + groups: + - parameters: + - requests + - output_config + required_fields: + - requests + - output_config + retry_codes_name: non_idempotent + retry_params_name: default + long_running: + return_type: google.cloud.vision.v1p4beta1.AsyncBatchAnnotateImagesResponse + metadata_type: google.cloud.vision.v1p4beta1.OperationMetadata + initial_poll_delay_millis: 500 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 5000 + total_poll_timeout_millis: 300000 + timeout_millis: 60000 + - name: AsyncBatchAnnotateFiles + flattening: + groups: + - parameters: + - requests + required_fields: + - requests + long_running: + return_type: google.cloud.vision.v1p4beta1.AsyncBatchAnnotateFilesResponse + metadata_type: google.cloud.vision.v1p4beta1.OperationMetadata + initial_poll_delay_millis: 20000 + poll_delay_multiplier: 1.5 + max_poll_delay_millis: 45000 + total_poll_timeout_millis: 86400000 + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 +resource_name_generation: +- message_name: CreateProductSetRequest + field_entity_map: + parent: location +- message_name: ListProductSetsRequest + field_entity_map: + parent: location +- message_name: GetProductSetRequest + field_entity_map: + name: product_set +- message_name: UpdateProductSetRequest + field_entity_map: + product_set.name: product_set +- message_name: DeleteProductSetRequest + field_entity_map: + name: product_set +- message_name: CreateProductRequest + field_entity_map: + parent: location +- message_name: ListProductsRequest + field_entity_map: + parent: location +- message_name: GetProductRequest + field_entity_map: + name: product +- message_name: UpdateProductRequest + field_entity_map: + product.name: product +- message_name: DeleteProductRequest + field_entity_map: + name: product +- message_name: CreateReferenceImageRequest + field_entity_map: + parent: product +- message_name: DeleteReferenceImageRequest + field_entity_map: + name: reference_image +- message_name: ListReferenceImagesRequest + field_entity_map: + parent: product +- message_name: GetReferenceImageRequest + field_entity_map: + name: reference_image +- message_name: AddProductToProductSetRequest + field_entity_map: + name: product_set +- message_name: RemoveProductFromProductSetRequest + field_entity_map: + name: product_set +- message_name: ListProductsInProductSetRequest + field_entity_map: + name: product_set +- message_name: ImportProductSetsRequest + field_entity_map: + parent: location diff --git a/google/cloud/vision/v1p4beta1/web_detection.proto b/google/cloud/vision/v1p4beta1/web_detection.proto new file mode 100644 index 000000000..15822563b --- /dev/null +++ b/google/cloud/vision/v1p4beta1/web_detection.proto @@ -0,0 +1,107 @@ +// Copyright 2018 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.vision.v1p4beta1; + +import "google/api/annotations.proto"; + +option cc_enable_arenas = true; +option go_package = "google.golang.org/genproto/googleapis/cloud/vision/v1p4beta1;vision"; +option java_multiple_files = true; +option java_outer_classname = "WebDetectionProto"; +option java_package = "com.google.cloud.vision.v1p4beta1"; +option objc_class_prefix = "GCVN"; + +// Relevant information for the image from the Internet. +message WebDetection { + // Entity deduced from similar images on the Internet. + message WebEntity { + // Opaque entity ID. + string entity_id = 1; + + // Overall relevancy score for the entity. + // Not normalized and not comparable across different image queries. + float score = 2; + + // Canonical description of the entity, in English. + string description = 3; + } + + // Metadata for online images. + message WebImage { + // The result image URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the image. + float score = 2; + } + + // Label to provide extra metadata for the web detection. + message WebLabel { + // Label for extra metadata. + string label = 1; + + // The BCP-47 language code for `label`, such as "en-US" or "sr-Latn". + // For more information, see + // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. + string language_code = 2; + } + + // Metadata for web pages. + message WebPage { + // The result web page URL. + string url = 1; + + // (Deprecated) Overall relevancy score for the web page. + float score = 2; + + // Title for the web page, may contain HTML markups. + string page_title = 3; + + // Fully matching images on the page. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 4; + + // Partial matching images on the page. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its + // crops. + repeated WebImage partial_matching_images = 5; + } + + // Deduced entities from similar images on the Internet. + repeated WebEntity web_entities = 1; + + // Fully matching images from the Internet. + // Can include resized copies of the query image. + repeated WebImage full_matching_images = 2; + + // Partial matching images from the Internet. + // Those images are similar enough to share some key-point features. For + // example an original image will likely have partial matching for its crops. + repeated WebImage partial_matching_images = 3; + + // Web pages containing the matching images from the Internet. + repeated WebPage pages_with_matching_images = 4; + + // The visually similar image results. + repeated WebImage visually_similar_images = 6; + + // The service's best guess as to the topic of the request image. + // Inferred from similar images on the open web. + repeated WebLabel best_guess_labels = 8; +} diff --git a/google/cloud/vision/vision_v1.yaml b/google/cloud/vision/vision_v1.yaml new file mode 100644 index 000000000..8491f774c --- /dev/null +++ b/google/cloud/vision/vision_v1.yaml @@ -0,0 +1,37 @@ +type: google.api.Service +config_version: 3 +name: vision.googleapis.com +title: Cloud Vision API + +apis: +- name: google.cloud.vision.v1.ProductSearch +- name: google.cloud.vision.v1.ImageAnnotator + +types: +- name: google.cloud.vision.v1.AnnotateFileResponse +- name: google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse +- name: google.cloud.vision.v1.BatchOperationMetadata +- name: google.cloud.vision.v1.ImportProductSetsResponse +- name: google.cloud.vision.v1.OperationMetadata + +documentation: + summary: |- + Integrates Google Vision features, including image labeling, face, logo, and + landmark detection, optical character recognition (OCR), and detection of + explicit content, into applications. + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=operations/*}' + additional_bindings: + - get: '/v1/{name=locations/*/operations/*}' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-vision diff --git a/google/cloud/vision/vision_v1p1beta1.yaml b/google/cloud/vision/vision_v1p1beta1.yaml new file mode 100644 index 000000000..81ff06d19 --- /dev/null +++ b/google/cloud/vision/vision_v1p1beta1.yaml @@ -0,0 +1,21 @@ +type: google.api.Service +config_version: 3 +name: vision.googleapis.com +title: Google Cloud Vision API + +apis: +- name: google.cloud.vision.v1p1beta1.ImageAnnotator + +documentation: + summary: |- + Integrates Google Vision features, including image labeling, face, logo, and + landmark detection, optical character recognition (OCR), and detection of + explicit content, into applications. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-vision diff --git a/google/cloud/vision/vision_v1p2beta1.yaml b/google/cloud/vision/vision_v1p2beta1.yaml new file mode 100644 index 000000000..0065f6302 --- /dev/null +++ b/google/cloud/vision/vision_v1p2beta1.yaml @@ -0,0 +1,26 @@ +type: google.api.Service +config_version: 3 +name: vision.googleapis.com +title: Google Cloud Vision API + +apis: +- name: google.cloud.vision.v1p2beta1.ImageAnnotator + +types: +- name: google.cloud.vision.v1p2beta1.AnnotateFileResponse +- name: google.cloud.vision.v1p2beta1.AsyncBatchAnnotateFilesResponse +- name: google.cloud.vision.v1p2beta1.OperationMetadata + +documentation: + summary: |- + Integrates Google Vision features, including image labeling, face, logo, and + landmark detection, optical character recognition (OCR), and detection of + explicit content, into applications. + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-vision diff --git a/google/cloud/vision/vision_v1p3beta1.yaml b/google/cloud/vision/vision_v1p3beta1.yaml new file mode 100644 index 000000000..8c384f050 --- /dev/null +++ b/google/cloud/vision/vision_v1p3beta1.yaml @@ -0,0 +1,37 @@ +type: google.api.Service +config_version: 3 +name: vision.googleapis.com +title: Cloud Vision API + +apis: +- name: google.cloud.vision.v1p3beta1.ProductSearch +- name: google.cloud.vision.v1p3beta1.ImageAnnotator + +types: +- name: google.cloud.vision.v1p3beta1.AnnotateFileResponse +- name: google.cloud.vision.v1p3beta1.AsyncBatchAnnotateFilesResponse +- name: google.cloud.vision.v1p3beta1.BatchOperationMetadata +- name: google.cloud.vision.v1p3beta1.ImportProductSetsResponse +- name: google.cloud.vision.v1p3beta1.OperationMetadata + +documentation: + summary: |- + Integrates Google Vision features, including image labeling, face, logo, and + landmark detection, optical character recognition (OCR), and detection of + explicit content, into applications. + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=operations/*}' + additional_bindings: + - get: '/v1/{name=locations/*/operations/*}' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-vision diff --git a/google/cloud/vision/vision_v1p4beta1.yaml b/google/cloud/vision/vision_v1p4beta1.yaml new file mode 100644 index 000000000..f5bdd9b9b --- /dev/null +++ b/google/cloud/vision/vision_v1p4beta1.yaml @@ -0,0 +1,39 @@ +type: google.api.Service +config_version: 3 +name: vision.googleapis.com +title: Cloud Vision API + +apis: +- name: google.cloud.vision.v1p4beta1.ProductSearch +- name: google.cloud.vision.v1p4beta1.ImageAnnotator + +types: +- name: google.cloud.vision.v1p4beta1.BatchOperationMetadata +- name: google.cloud.vision.v1p4beta1.ImportProductSetsResponse +- name: google.cloud.vision.v1p4beta1.AnnotateFileResponse +- name: google.cloud.vision.v1p4beta1.AsyncBatchAnnotateFilesResponse +- name: google.cloud.vision.v1p4beta1.OperationMetadata +- name: google.cloud.vision.v1p4beta1.AsyncBatchAnnotateImagesResponse +- name: google.cloud.vision.v1p4beta1.BatchAnnotateFilesResponse + +documentation: + summary: |- + Integrates Google Vision features, including image labeling, face, logo, and + landmark detection, optical character recognition (OCR), and detection of + explicit content, into applications. + +http: + rules: + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=operations/*}' + additional_bindings: + - get: '/v1/{name=locations/*/operations/*}' + + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/cloud-vision diff --git a/google/cloud/webrisk/artman_webrisk_v1beta1.yaml b/google/cloud/webrisk/artman_webrisk_v1beta1.yaml new file mode 100644 index 000000000..4e27f0413 --- /dev/null +++ b/google/cloud/webrisk/artman_webrisk_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: webrisk + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: webrisk.yaml + gapic_yaml: v1beta1/webrisk_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/webrisk/v1beta1/webrisk.proto b/google/cloud/webrisk/v1beta1/webrisk.proto new file mode 100644 index 000000000..c6b5f7c90 --- /dev/null +++ b/google/cloud/webrisk/v1beta1/webrisk.proto @@ -0,0 +1,295 @@ +// Copyright 2019 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.webrisk.v1beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.WebRisk.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/webrisk/v1beta1;webrisk"; +option java_multiple_files = true; +option java_outer_classname = "WebRiskProto"; +option java_package = "com.google.webrisk.v1beta1"; +option objc_class_prefix = "GCWR"; +option php_namespace = "Google\\Cloud\\WebRisk\\V1beta1"; + +// Web Risk v1beta1 API defines an interface to detect malicious URLs on your +// website and in client applications. +service WebRiskServiceV1Beta1 { + // Gets the most recent threat list diffs. + rpc ComputeThreatListDiff(ComputeThreatListDiffRequest) + returns (ComputeThreatListDiffResponse) { + option (google.api.http) = { + get: "/v1beta1/threatLists:computeDiff" + }; + } + + // This method is used to check whether a URI is on a given threatList. + rpc SearchUris(SearchUrisRequest) returns (SearchUrisResponse) { + option (google.api.http) = { + get: "/v1beta1/uris:search" + }; + } + + // Gets the full hashes that match the requested hash prefix. + // This is used after a hash prefix is looked up in a threatList + // and there is a match. The client side threatList only holds partial hashes + // so the client must query this method to determine if there is a full + // hash match of a threat. + rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse) { + option (google.api.http) = { + get: "/v1beta1/hashes:search" + }; + } +} + +// Describes an API diff request. +message ComputeThreatListDiffRequest { + // The constraints for this diff. + message Constraints { + // The maximum size in number of entries. The diff will not contain more + // entries than this value. This should be a power of 2 between 2**10 and + // 2**20. If zero, no diff size limit is set. + int32 max_diff_entries = 1; + + // Sets the maximum number of entries that the client is willing to have + // in the local database. This should be a power of 2 between 2**10 and + // 2**20. If zero, no database size limit is set. + int32 max_database_entries = 2; + + // The compression types supported by the client. + repeated CompressionType supported_compressions = 3; + } + + // Required. The ThreatList to update. + ThreatType threat_type = 1; + + // The current version token of the client for the requested list (the + // client version that was received from the last successful diff). + bytes version_token = 2; + + // The constraints associated with this request. + Constraints constraints = 3; +} + +message ComputeThreatListDiffResponse { + // The expected state of a client's local database. + message Checksum { + // The SHA256 hash of the client state; that is, of the sorted list of all + // hashes present in the database. + bytes sha256 = 1; + } + + // The type of response sent to the client. + enum ResponseType { + // Unknown. + RESPONSE_TYPE_UNSPECIFIED = 0; + + // Partial updates are applied to the client's existing local database. + DIFF = 1; + + // Full updates resets the client's entire local database. This means + // that either the client had no state, was seriously out-of-date, + // or the client is believed to be corrupt. + RESET = 2; + } + + // The type of response. This may indicate that an action is required by the + // client when the response is received. + ResponseType response_type = 4; + + // A set of entries to add to a local threat type's list. + ThreatEntryAdditions additions = 5; + + // A set of entries to remove from a local threat type's list. + // This field may be empty. + ThreatEntryRemovals removals = 6; + + // The new opaque client version token. + bytes new_version_token = 7; + + // The expected SHA256 hash of the client state; that is, of the sorted list + // of all hashes present in the database after applying the provided diff. + // If the client state doesn't match the expected state, the client must + // disregard this diff and retry later. + Checksum checksum = 8; + + // The soonest the client should wait before issuing any diff + // request. Querying sooner is unlikely to produce a meaningful diff. + // Waiting longer is acceptable considering the use case. + // If this field is not set clients may update as soon as they want. + google.protobuf.Timestamp recommended_next_diff = 2; +} + +// Request to check URI entries against threatLists. +message SearchUrisRequest { + // The URI to be checked for matches. + string uri = 1; + + // Required. The ThreatLists to search in. + repeated ThreatType threat_types = 2; +} + +message SearchUrisResponse { + // Contains threat information on a matching uri. + message ThreatUri { + // The ThreatList this threat belongs to. + repeated ThreatType threat_types = 1; + + // The cache lifetime for the returned match. Clients must not cache this + // response past this timestamp to avoid false positives. + google.protobuf.Timestamp expire_time = 2; + } + + // The threat list matches. This may be empty if the URI is on no list. + ThreatUri threat = 1; +} + +// Request to return full hashes matched by the provided hash prefixes. +message SearchHashesRequest { + // A hash prefix, consisting of the most significant 4-32 bytes of a SHA256 + // hash. For JSON requests, this field is base64-encoded. + bytes hash_prefix = 1; + + // Required. The ThreatLists to search in. + repeated ThreatType threat_types = 2; +} + +message SearchHashesResponse { + // Contains threat information on a matching hash. + message ThreatHash { + // The ThreatList this threat belongs to. + // This must contain at least one entry. + repeated ThreatType threat_types = 1; + + // A 32 byte SHA256 hash. This field is in binary format. For JSON + // requests, hashes are base64-encoded. + bytes hash = 2; + + // The cache lifetime for the returned match. Clients must not cache this + // response past this timestamp to avoid false positives. + google.protobuf.Timestamp expire_time = 3; + } + + // The full hashes that matched the requested prefixes. + // The hash will be populated in the key. + repeated ThreatHash threats = 1; + + // For requested entities that did not match the threat list, how long to + // cache the response until. + google.protobuf.Timestamp negative_expire_time = 2; +} + +// Contains the set of entries to add to a local database. +// May contain a combination of compressed and raw data in a single response. +message ThreatEntryAdditions { + // The raw SHA256-formatted entries. + // Repeated to allow returning sets of hashes with different prefix sizes. + repeated RawHashes raw_hashes = 1; + + // The encoded 4-byte prefixes of SHA256-formatted entries, using a + // Golomb-Rice encoding. The hashes are converted to uint32, sorted in + // ascending order, then delta encoded and stored as encoded_data. + RiceDeltaEncoding rice_hashes = 2; +} + +// Contains the set of entries to remove from a local database. +message ThreatEntryRemovals { + // The raw removal indices for a local list. + RawIndices raw_indices = 1; + + // The encoded local, lexicographically-sorted list indices, using a + // Golomb-Rice encoding. Used for sending compressed removal indices. The + // removal indices (uint32) are sorted in ascending order, then delta encoded + // and stored as encoded_data. + RiceDeltaEncoding rice_indices = 2; +} + +// The type of threat. This maps dirrectly to the threat list a threat may +// belong to. +enum ThreatType { + // Unknown. + THREAT_TYPE_UNSPECIFIED = 0; + + // Malware targeting any platform. + MALWARE = 1; + + // Social engineering targeting any platform. + SOCIAL_ENGINEERING = 2; + + // Unwanted software targeting any platform. + UNWANTED_SOFTWARE = 3; +} + +// The ways in which threat entry sets can be compressed. +enum CompressionType { + // Unknown. + COMPRESSION_TYPE_UNSPECIFIED = 0; + + // Raw, uncompressed data. + RAW = 1; + + // Rice-Golomb encoded data. + RICE = 2; +} + +// A set of raw indices to remove from a local list. +message RawIndices { + // The indices to remove from a lexicographically-sorted local list. + repeated int32 indices = 1; +} + +// The uncompressed threat entries in hash format. +// Hashes can be anywhere from 4 to 32 bytes in size. A large majority are 4 +// bytes, but some hashes are lengthened if they collide with the hash of a +// popular URI. +// +// Used for sending ThreatEntryAdditons to clients that do not support +// compression, or when sending non-4-byte hashes to clients that do support +// compression. +message RawHashes { + // The number of bytes for each prefix encoded below. This field can be + // anywhere from 4 (shortest prefix) to 32 (full SHA256 hash). + int32 prefix_size = 1; + + // The hashes, in binary format, concatenated into one long string. Hashes are + // sorted in lexicographic order. For JSON API users, hashes are + // base64-encoded. + bytes raw_hashes = 2; +} + +// The Rice-Golomb encoded data. Used for sending compressed 4-byte hashes or +// compressed removal indices. +message RiceDeltaEncoding { + // The offset of the first entry in the encoded data, or, if only a single + // integer was encoded, that single integer's value. If the field is empty or + // missing, assume zero. + int64 first_value = 1; + + // The Golomb-Rice parameter, which is a number between 2 and 28. This field + // is missing (that is, zero) if `num_entries` is zero. + int32 rice_parameter = 2; + + // The number of entries that are delta encoded in the encoded data. If only a + // single integer was encoded, this will be zero and the single value will be + // stored in `first_value`. + int32 entry_count = 3; + + // The encoded deltas that are encoded using the Golomb-Rice coder. + bytes encoded_data = 4; +} diff --git a/google/cloud/webrisk/v1beta1/webrisk_gapic.yaml b/google/cloud/webrisk/v1beta1/webrisk_gapic.yaml new file mode 100644 index 000000000..298dda3e2 --- /dev/null +++ b/google/cloud/webrisk/v1beta1/webrisk_gapic.yaml @@ -0,0 +1,140 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.webrisk.v1beta1 + python: + package_name: google.cloud.webrisk_v1beta1.gapic + go: + package_name: cloud.google.com/go/webrisk/apiv1beta1 + csharp: + package_name: Google.Cloud.WebRisk.V1Beta1 + ruby: + package_name: Google::Cloud::Webrisk::V1beta1 + php: + package_name: Google\Cloud\WebRisk\V1beta1 + nodejs: + package_name: webrisk.v1beta1 +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.webrisk.v1beta1.WebRiskServiceV1Beta1 + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ComputeThreatListDiff + flattening: + groups: + - parameters: + - threat_type + - version_token + - constraints + required_fields: + - threat_type + - constraints + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: SearchUris + flattening: + groups: + - parameters: + - uri + - threat_types + required_fields: + - uri + - threat_types + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 + - name: SearchHashes + flattening: + groups: + - parameters: + - hash_prefix + - threat_types + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/webrisk/webrisk.yaml b/google/cloud/webrisk/webrisk.yaml new file mode 100644 index 000000000..f43119679 --- /dev/null +++ b/google/cloud/webrisk/webrisk.yaml @@ -0,0 +1,14 @@ +type: google.api.Service +config_version: 3 +name: webrisk.googleapis.com +title: Web Risk API + +apis: + - name: google.cloud.webrisk.v1beta1.WebRiskServiceV1Beta1 + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/websecurityscanner/BUILD.bazel b/google/cloud/websecurityscanner/BUILD.bazel new file mode 100644 index 000000000..1e5b8c2af --- /dev/null +++ b/google/cloud/websecurityscanner/BUILD.bazel @@ -0,0 +1 @@ +exports_files(glob(["*.yaml"]))
\ No newline at end of file diff --git a/google/cloud/websecurityscanner/artman_websecurityscanner_v1alpha.yaml b/google/cloud/websecurityscanner/artman_websecurityscanner_v1alpha.yaml new file mode 100644 index 000000000..31dceecef --- /dev/null +++ b/google/cloud/websecurityscanner/artman_websecurityscanner_v1alpha.yaml @@ -0,0 +1,34 @@ +common: + api_name: websecurityscanner + api_version: v1alpha + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1alpha + service_yaml: web_security_scanner_v1alpha.yaml + gapic_yaml: v1alpha/websecurityscanner_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/websecurityscanner/v1alpha/BUILD.bazel b/google/cloud/websecurityscanner/v1alpha/BUILD.bazel new file mode 100644 index 000000000..de5801eec --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/BUILD.bazel @@ -0,0 +1,142 @@ +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@com_google_api_codegen//rules_gapic:gapic.bzl", "proto_library_with_info") + +proto_library( + name = "websecurityscanner_proto", + srcs = [ + "crawled_url.proto", + "finding.proto", + "finding_addon.proto", + "finding_type_stats.proto", + "scan_config.proto", + "scan_run.proto", + "web_security_scanner.proto", + ], + deps = [ + "//google/api:annotations_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:timestamp_proto", + ], +) + +proto_library_with_info( + name = "websecurityscanner_proto_with_info", + deps = [":websecurityscanner_proto"], +) + +############################################################################## +# Java +############################################################################## +load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") +load( + "@com_google_api_codegen//rules_gapic/java:java_gapic.bzl", + "java_gapic_library", + "java_resource_name_proto_library", +) +load("@com_google_api_codegen//rules_gapic/java:java_gapic_pkg.bzl", "java_gapic_assembly_gradle_pkg") + +_JAVA_GRPC_DEPS = [ + "@com_google_api_grpc_proto_google_common_protos//jar", +] + +java_proto_library( + name = "websecurityscanner_java_proto", + deps = [":websecurityscanner_proto"], +) + +java_grpc_library( + name = "websecurityscanner_java_grpc", + srcs = [":websecurityscanner_proto"], + deps = [":websecurityscanner_java_proto"] + _JAVA_GRPC_DEPS, +) + +java_resource_name_proto_library( + name = "websecurityscanner_resource_name_java_proto", + gapic_yaml = "websecurityscanner_gapic.yaml", + deps = [":websecurityscanner_proto"], +) + +java_gapic_library( + name = "websecurityscanner_java_gapic", + src = ":websecurityscanner_proto_with_info", + gapic_yaml = "websecurityscanner_gapic.yaml", + service_yaml = "//google/cloud/websecurityscanner:web_security_scanner_v1alpha.yaml", + test_deps = [":websecurityscanner_java_grpc"], + deps = [ + ":websecurityscanner_java_proto", + ":websecurityscanner_resource_name_java_proto", + ] + _JAVA_GRPC_DEPS, +) + +[java_test( + name = test_name, + test_class = test_name, + runtime_deps = [":websecurityscanner_java_gapic_test"], +) for test_name in [ + "com.google.cloud.websecurityscanner.v1alpha.WebSecurityScannerClientTest", +]] + +# Opensource Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-websecurityscanner-v1alpha-java", + client_deps = [":websecurityscanner_java_gapic"], + client_group = "com.google.cloud", + client_test_deps = [":websecurityscanner_java_gapic_test"], + grpc_deps = [":websecurityscanner_java_grpc"], + grpc_group = "com.google.api.grpc", + proto_deps = [ + ":websecurityscanner_resource_name_java_proto", + ":websecurityscanner_java_proto", + ":websecurityscanner_proto", + ] + _JAVA_GRPC_DEPS, + version = "0.0.0-SNAPSHOT", +) + +############################################################################## +# Go +############################################################################## +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") +load("@com_google_api_codegen//rules_gapic/go:go_gapic.bzl", "go_gapic_srcjar", "go_gapic_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test") +load("@com_google_api_codegen//rules_gapic/go:go_gapic_pkg.bzl", "go_gapic_assembly_pkg") + +go_proto_library( + name = "websecurityscanner_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha", + protos = [":websecurityscanner_proto_with_info"], + deps = ["//google/api:annotations_go_proto"], +) + +go_gapic_library( + name = "websecurityscanner_go_gapic", + src = ":websecurityscanner_proto_with_info", + gapic_yaml = "websecurityscanner_gapic.yaml", + importpath = "cloud.google.com/go/cloud/websecurityscanner/apiv1alpha", + service_yaml = "//google/cloud/websecurityscanner:web_security_scanner_v1alpha.yaml", + deps = [":websecurityscanner_go_proto"], +) + +go_test( + name = "websecurityscanner_go_gapic_test", + srcs = [":websecurityscanner_go_gapic_srcjar_test"], + embed = [":websecurityscanner_go_gapic"], + importpath = "cloud.google.com/go/cloud/websecurityscanner/apiv1alpha", +) + +# Opensource Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-websecurityscanner-v1alpha-go", + deps = [ + ":websecurityscanner_go_gapic", + ":websecurityscanner_go_gapic_srcjar-smoke-test.srcjar", + ":websecurityscanner_go_gapic_srcjar-test.srcjar", + ":websecurityscanner_go_proto", + ], +) diff --git a/google/cloud/websecurityscanner/v1alpha/crawled_url.proto b/google/cloud/websecurityscanner/v1alpha/crawled_url.proto new file mode 100644 index 000000000..d4c40eae8 --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/crawled_url.proto @@ -0,0 +1,42 @@ +// Copyright 2018 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.websecurityscanner.v1alpha; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha;websecurityscanner"; +option java_multiple_files = true; +option java_outer_classname = "CrawledUrlProto"; +option java_package = "com.google.cloud.websecurityscanner.v1alpha"; + +// A CrawledUrl resource represents a URL that was crawled during a ScanRun. Web +// Security Scanner Service crawls the web applications, following all links +// within the scope of sites, to find the URLs to test against. +message CrawledUrl { + // Output only. + // The http method of the request that was used to visit the URL, in + // uppercase. + string http_method = 1; + + // Output only. + // The URL that was crawled. + string url = 2; + + // Output only. + // The body of the request that was used to visit the URL. + string body = 3; +} diff --git a/google/cloud/websecurityscanner/v1alpha/finding.proto b/google/cloud/websecurityscanner/v1alpha/finding.proto new file mode 100644 index 000000000..07140e276 --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/finding.proto @@ -0,0 +1,140 @@ +// Copyright 2018 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.websecurityscanner.v1alpha; + +import "google/api/annotations.proto"; +import "google/cloud/websecurityscanner/v1alpha/finding_addon.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha;websecurityscanner"; +option java_multiple_files = true; +option java_outer_classname = "FindingProto"; +option java_package = "com.google.cloud.websecurityscanner.v1alpha"; + +// A Finding resource represents a vulnerability instance identified during a +// ScanRun. +message Finding { + // Types of Findings. + enum FindingType { + // The invalid finding type. + FINDING_TYPE_UNSPECIFIED = 0; + + // A page that was served over HTTPS also resources over HTTP. A + // man-in-the-middle attacker could tamper with the HTTP resource and gain + // full access to the website that loads the resource or to monitor the + // actions taken by the user. + MIXED_CONTENT = 1; + + // The version of an included library is known to contain a security issue. + // The scanner checks the version of library in use against a known list of + // vulnerable libraries. False positives are possible if the version + // detection fails or if the library has been manually patched. + OUTDATED_LIBRARY = 2; + + // This type of vulnerability occurs when the value of a request parameter + // is reflected at the beginning of the response, for example, in requests + // using JSONP. Under certain circumstances, an attacker may be able to + // supply an alphanumeric-only Flash file in the vulnerable parameter + // causing the browser to execute the Flash file as if it originated on the + // vulnerable server. + ROSETTA_FLASH = 5; + + // A cross-site scripting (XSS) bug is found via JavaScript callback. For + // detailed explanations on XSS, see + // https://www.google.com/about/appsecurity/learning/xss/. + XSS_CALLBACK = 3; + + // A potential cross-site scripting (XSS) bug due to JavaScript breakage. + // In some circumstances, the application under test might modify the test + // string before it is parsed by the browser. When the browser attempts to + // runs this modified test string, it will likely break and throw a + // JavaScript execution error, thus an injection issue is occurring. + // However, it may not be exploitable. Manual verification is needed to see + // if the test string modifications can be evaded and confirm that the issue + // is in fact an XSS vulnerability. For detailed explanations on XSS, see + // https://www.google.com/about/appsecurity/learning/xss/. + XSS_ERROR = 4; + + // An application appears to be transmitting a password field in clear text. + // An attacker can eavesdrop network traffic and sniff the password field. + CLEAR_TEXT_PASSWORD = 6; + } + + // Output only. + // The resource name of the Finding. The name follows the format of + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanruns/{scanRunId}/findings/{findingId}'. + // The finding IDs are generated by the system. + string name = 1; + + // Output only. + // The type of the Finding. + FindingType finding_type = 2; + + // Output only. + // The http method of the request that triggered the vulnerability, in + // uppercase. + string http_method = 3; + + // Output only. + // The URL produced by the server-side fuzzer and used in the request that + // triggered the vulnerability. + string fuzzed_url = 4; + + // Output only. + // The body of the request that triggered the vulnerability. + string body = 5; + + // Output only. + // The description of the vulnerability. + string description = 6; + + // Output only. + // The URL containing human-readable payload that user can leverage to + // reproduce the vulnerability. + string reproduction_url = 7; + + // Output only. + // If the vulnerability was originated from nested IFrame, the immediate + // parent IFrame is reported. + string frame_url = 8; + + // Output only. + // The URL where the browser lands when the vulnerability is detected. + string final_url = 9; + + // Output only. + // The tracking ID uniquely identifies a vulnerability instance across + // multiple ScanRuns. + string tracking_id = 10; + + // Output only. + // An addon containing information about outdated libraries. + OutdatedLibrary outdated_library = 11; + + // Output only. + // An addon containing detailed information regarding any resource causing the + // vulnerability such as JavaScript sources, image, audio files, etc. + ViolatingResource violating_resource = 12; + + // Output only. + // An addon containing information about request parameters which were found + // to be vulnerable. + VulnerableParameters vulnerable_parameters = 13; + + // Output only. + // An addon containing information reported for an XSS, if any. + Xss xss = 14; +} diff --git a/google/cloud/websecurityscanner/v1alpha/finding_addon.proto b/google/cloud/websecurityscanner/v1alpha/finding_addon.proto new file mode 100644 index 000000000..a7d344b84 --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/finding_addon.proto @@ -0,0 +1,61 @@ +// Copyright 2018 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.websecurityscanner.v1alpha; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha;websecurityscanner"; +option java_multiple_files = true; +option java_outer_classname = "FindingAddonProto"; +option java_package = "com.google.cloud.websecurityscanner.v1alpha"; + +// Information reported for an outdated library. +message OutdatedLibrary { + // The name of the outdated library. + string library_name = 1; + + // The version number. + string version = 2; + + // URLs to learn more information about the vulnerabilities in the library. + repeated string learn_more_urls = 3; +} + +// Information regarding any resource causing the vulnerability such +// as JavaScript sources, image, audio files, etc. +message ViolatingResource { + // The MIME type of this resource. + string content_type = 1; + + // URL of this violating resource. + string resource_url = 2; +} + +// Information about vulnerable request parameters. +message VulnerableParameters { + // The vulnerable parameter names. + repeated string parameter_names = 1; +} + +// Information reported for an XSS. +message Xss { + // Stack traces leading to the point where the XSS occurred. + repeated string stack_traces = 1; + + // An error message generated by a javascript breakage. + string error_message = 2; +} diff --git a/google/cloud/websecurityscanner/v1alpha/finding_type_stats.proto b/google/cloud/websecurityscanner/v1alpha/finding_type_stats.proto new file mode 100644 index 000000000..73115667f --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/finding_type_stats.proto @@ -0,0 +1,37 @@ +// Copyright 2018 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.websecurityscanner.v1alpha; + +import "google/api/annotations.proto"; +import "google/cloud/websecurityscanner/v1alpha/finding.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha;websecurityscanner"; +option java_multiple_files = true; +option java_outer_classname = "FindingTypeStatsProto"; +option java_package = "com.google.cloud.websecurityscanner.v1alpha"; + +// A FindingTypeStats resource represents stats regarding a specific FindingType +// of Findings under a given ScanRun. +message FindingTypeStats { + // Output only. + // The finding type associated with the stats. + Finding.FindingType finding_type = 1; + + // Output only. + // The count of findings belonging to this finding type. + int32 finding_count = 2; +} diff --git a/google/cloud/websecurityscanner/v1alpha/scan_config.proto b/google/cloud/websecurityscanner/v1alpha/scan_config.proto new file mode 100644 index 000000000..144f7f2b5 --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/scan_config.proto @@ -0,0 +1,149 @@ +// Copyright 2018 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.websecurityscanner.v1alpha; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha;websecurityscanner"; +option java_multiple_files = true; +option java_outer_classname = "ScanConfigProto"; +option java_package = "com.google.cloud.websecurityscanner.v1alpha"; + +// A ScanConfig resource contains the configurations to launch a scan. +message ScanConfig { + // Scan authentication configuration. + message Authentication { + // Describes authentication configuration that uses a Google account. + message GoogleAccount { + // Required. + // The user name of the Google account. + string username = 1; + + // Input only. + // Required. + // The password of the Google account. The credential is stored encrypted + // and not returned in any response. + string password = 2; + } + + // Describes authentication configuration that uses a custom account. + message CustomAccount { + // Required. + // The user name of the custom account. + string username = 1; + + // Input only. + // Required. + // The password of the custom account. The credential is stored encrypted + // and not returned in any response. + string password = 2; + + // Required. + // The login form URL of the website. + string login_url = 3; + } + + // Required. + // Authentication configuration + oneof authentication { + // Authentication using a Google account. + GoogleAccount google_account = 1; + + // Authentication using a custom account. + CustomAccount custom_account = 2; + } + } + + // Scan schedule configuration. + message Schedule { + // A timestamp indicates when the next run will be scheduled. The value is + // refreshed by the server after each run. If unspecified, it will default + // to current server time, which means the scan will be scheduled to start + // immediately. + google.protobuf.Timestamp schedule_time = 1; + + // Required. + // The duration of time between executions in days. + int32 interval_duration_days = 2; + } + + // Type of user agents used for scanning. + enum UserAgent { + // The user agent is unknown. Service will default to CHROME_LINUX. + USER_AGENT_UNSPECIFIED = 0; + + // Chrome on Linux. This is the service default if unspecified. + CHROME_LINUX = 1; + + // Chrome on Android. + CHROME_ANDROID = 2; + + // Safari on IPhone. + SAFARI_IPHONE = 3; + } + + // Cloud platforms supported by Cloud Web Security Scanner. + enum TargetPlatform { + // The target platform is unknown. Requests with this enum value will be + // rejected with INVALID_ARGUMENT error. + TARGET_PLATFORM_UNSPECIFIED = 0; + + // Google App Engine service. + APP_ENGINE = 1; + + // Google Compute Engine service. + COMPUTE = 2; + } + + // The resource name of the ScanConfig. The name follows the format of + // 'projects/{projectId}/scanConfigs/{scanConfigId}'. The ScanConfig IDs are + // generated by the system. + string name = 1; + + // Required. + // The user provided display name of the ScanConfig. + string display_name = 2; + + // The maximum QPS during scanning. A valid value ranges from 5 to 20 + // inclusively. If the field is unspecified or its value is set 0, server will + // default to 15. Other values outside of [5, 20] range will be rejected with + // INVALID_ARGUMENT error. + int32 max_qps = 3; + + // Required. + // The starting URLs from which the scanner finds site pages. + repeated string starting_urls = 4; + + // The authentication configuration. If specified, service will use the + // authentication configuration during scanning. + Authentication authentication = 5; + + // The user agent used during scanning. + UserAgent user_agent = 6; + + // The blacklist URL patterns as described in + // https://cloud.google.com/security-scanner/docs/excluded-urls + repeated string blacklist_patterns = 7; + + // The schedule of the ScanConfig. + Schedule schedule = 8; + + // Set of Cloud Platforms targeted by the scan. If empty, APP_ENGINE will be + // used as a default. + repeated TargetPlatform target_platforms = 9; +} diff --git a/google/cloud/websecurityscanner/v1alpha/scan_run.proto b/google/cloud/websecurityscanner/v1alpha/scan_run.proto new file mode 100644 index 000000000..36e2d0925 --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/scan_run.proto @@ -0,0 +1,107 @@ +// Copyright 2018 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.websecurityscanner.v1alpha; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha;websecurityscanner"; +option java_multiple_files = true; +option java_outer_classname = "ScanRunProto"; +option java_package = "com.google.cloud.websecurityscanner.v1alpha"; + +// A ScanRun is a output-only resource representing an actual run of the scan. +message ScanRun { + // Types of ScanRun execution state. + enum ExecutionState { + // Represents an invalid state caused by internal server error. This value + // should never be returned. + EXECUTION_STATE_UNSPECIFIED = 0; + + // The scan is waiting in the queue. + QUEUED = 1; + + // The scan is in progress. + SCANNING = 2; + + // The scan is either finished or stopped by user. + FINISHED = 3; + } + + // Types of ScanRun result state. + enum ResultState { + // Default value. This value is returned when the ScanRun is not yet + // finished. + RESULT_STATE_UNSPECIFIED = 0; + + // The scan finished without errors. + SUCCESS = 1; + + // The scan finished with errors. + ERROR = 2; + + // The scan was terminated by user. + KILLED = 3; + } + + // Output only. + // The resource name of the ScanRun. The name follows the format of + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}'. + // The ScanRun IDs are generated by the system. + string name = 1; + + // Output only. + // The execution state of the ScanRun. + ExecutionState execution_state = 2; + + // Output only. + // The result state of the ScanRun. This field is only available after the + // execution state reaches "FINISHED". + ResultState result_state = 3; + + // Output only. + // The time at which the ScanRun started. + google.protobuf.Timestamp start_time = 4; + + // Output only. + // The time at which the ScanRun reached termination state - that the ScanRun + // is either finished or stopped by user. + google.protobuf.Timestamp end_time = 5; + + // Output only. + // The number of URLs crawled during this ScanRun. If the scan is in progress, + // the value represents the number of URLs crawled up to now. + int64 urls_crawled_count = 6; + + // Output only. + // The number of URLs tested during this ScanRun. If the scan is in progress, + // the value represents the number of URLs tested up to now. The number of + // URLs tested is usually larger than the number URLS crawled because + // typically a crawled URL is tested with multiple test payloads. + int64 urls_tested_count = 7; + + // Output only. + // Whether the scan run has found any vulnerabilities. + bool has_vulnerabilities = 8; + + // Output only. + // The percentage of total completion ranging from 0 to 100. + // If the scan is in queue, the value is 0. + // If the scan is running, the value ranges from 0 to 100. + // If the scan is finished, the value is 100. + int32 progress_percent = 9; +} diff --git a/google/cloud/websecurityscanner/v1alpha/web_security_scanner.proto b/google/cloud/websecurityscanner/v1alpha/web_security_scanner.proto new file mode 100644 index 000000000..b07516aaf --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/web_security_scanner.proto @@ -0,0 +1,349 @@ +// Copyright 2018 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.websecurityscanner.v1alpha; + +import "google/api/annotations.proto"; +import "google/cloud/websecurityscanner/v1alpha/crawled_url.proto"; +import "google/cloud/websecurityscanner/v1alpha/finding.proto"; +import "google/cloud/websecurityscanner/v1alpha/finding_type_stats.proto"; +import "google/cloud/websecurityscanner/v1alpha/scan_config.proto"; +import "google/cloud/websecurityscanner/v1alpha/scan_run.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/websecurityscanner/v1alpha;websecurityscanner"; +option java_multiple_files = true; +option java_outer_classname = "WebSecurityScannerProto"; +option java_package = "com.google.cloud.websecurityscanner.v1alpha"; + +// Cloud Web Security Scanner Service identifies security vulnerabilities in web +// applications hosted on Google Cloud Platform. It crawls your application, and +// attempts to exercise as many user inputs and event handlers as possible. +service WebSecurityScanner { + // Creates a new ScanConfig. + rpc CreateScanConfig(CreateScanConfigRequest) returns (ScanConfig) { + option (google.api.http) = { + post: "/v1alpha/{parent=projects/*}/scanConfigs" + body: "scan_config" + }; + } + + // Deletes an existing ScanConfig and its child resources. + rpc DeleteScanConfig(DeleteScanConfigRequest) + returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1alpha/{name=projects/*/scanConfigs/*}" + }; + } + + // Gets a ScanConfig. + rpc GetScanConfig(GetScanConfigRequest) returns (ScanConfig) { + option (google.api.http) = { + get: "/v1alpha/{name=projects/*/scanConfigs/*}" + }; + } + + // Lists ScanConfigs under a given project. + rpc ListScanConfigs(ListScanConfigsRequest) + returns (ListScanConfigsResponse) { + option (google.api.http) = { + get: "/v1alpha/{parent=projects/*}/scanConfigs" + }; + } + + // Updates a ScanConfig. This method support partial update of a ScanConfig. + rpc UpdateScanConfig(UpdateScanConfigRequest) returns (ScanConfig) { + option (google.api.http) = { + patch: "/v1alpha/{scan_config.name=projects/*/scanConfigs/*}" + body: "scan_config" + }; + } + + // Start a ScanRun according to the given ScanConfig. + rpc StartScanRun(StartScanRunRequest) returns (ScanRun) { + option (google.api.http) = { + post: "/v1alpha/{name=projects/*/scanConfigs/*}:start" + body: "*" + }; + } + + // Gets a ScanRun. + rpc GetScanRun(GetScanRunRequest) returns (ScanRun) { + option (google.api.http) = { + get: "/v1alpha/{name=projects/*/scanConfigs/*/scanRuns/*}" + }; + } + + // Lists ScanRuns under a given ScanConfig, in descending order of ScanRun + // stop time. + rpc ListScanRuns(ListScanRunsRequest) returns (ListScanRunsResponse) { + option (google.api.http) = { + get: "/v1alpha/{parent=projects/*/scanConfigs/*}/scanRuns" + }; + } + + // Stops a ScanRun. The stopped ScanRun is returned. + rpc StopScanRun(StopScanRunRequest) returns (ScanRun) { + option (google.api.http) = { + post: "/v1alpha/{name=projects/*/scanConfigs/*/scanRuns/*}:stop" + body: "*" + }; + } + + // List CrawledUrls under a given ScanRun. + rpc ListCrawledUrls(ListCrawledUrlsRequest) + returns (ListCrawledUrlsResponse) { + option (google.api.http) = { + get: "/v1alpha/{parent=projects/*/scanConfigs/*/scanRuns/*}/crawledUrls" + }; + } + + // Gets a Finding. + rpc GetFinding(GetFindingRequest) returns (Finding) { + option (google.api.http) = { + get: "/v1alpha/{name=projects/*/scanConfigs/*/scanRuns/*/findings/*}" + }; + } + + // List Findings under a given ScanRun. + rpc ListFindings(ListFindingsRequest) returns (ListFindingsResponse) { + option (google.api.http) = { + get: "/v1alpha/{parent=projects/*/scanConfigs/*/scanRuns/*}/findings" + }; + } + + // List all FindingTypeStats under a given ScanRun. + rpc ListFindingTypeStats(ListFindingTypeStatsRequest) + returns (ListFindingTypeStatsResponse) { + option (google.api.http) = { + get: "/v1alpha/{parent=projects/*/scanConfigs/*/scanRuns/*}/findingTypeStats" + }; + } +} + +// Request for the `CreateScanConfig` method. +message CreateScanConfigRequest { + // Required. + // The parent resource name where the scan is created, which should be a + // project resource name in the format 'projects/{projectId}'. + string parent = 1; + + // Required. + // The ScanConfig to be created. + ScanConfig scan_config = 2; +} + +// Request for the `DeleteScanConfig` method. +message DeleteScanConfigRequest { + // Required. + // The resource name of the ScanConfig to be deleted. The name follows the + // format of 'projects/{projectId}/scanConfigs/{scanConfigId}'. + string name = 1; +} + +// Request for the `GetScanConfig` method. +message GetScanConfigRequest { + // Required. + // The resource name of the ScanConfig to be returned. The name follows the + // format of 'projects/{projectId}/scanConfigs/{scanConfigId}'. + string name = 1; +} + +// Request for the `ListScanConfigs` method. +message ListScanConfigsRequest { + // Required. + // The parent resource name, which should be a project resource name in the + // format 'projects/{projectId}'. + string parent = 1; + + // A token identifying a page of results to be returned. This should be a + // `next_page_token` value returned from a previous List request. + // If unspecified, the first page of results is returned. + string page_token = 2; + + // The maximum number of ScanConfigs to return, can be limited by server. + // If not specified or not positive, the implementation will select a + // reasonable value. + int32 page_size = 3; +} + +// Request for the `UpdateScanConfigRequest` method. +message UpdateScanConfigRequest { + // Required. + // The ScanConfig to be updated. The name field must be set to identify the + // resource to be updated. The values of fields not covered by the mask + // will be ignored. + ScanConfig scan_config = 2; + + // Required. + // The update mask applies to the resource. For the `FieldMask` definition, + // see + // https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask + google.protobuf.FieldMask update_mask = 3; +} + +// Response for the `ListScanConfigs` method. +message ListScanConfigsResponse { + // The list of ScanConfigs returned. + repeated ScanConfig scan_configs = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// Request for the `StartScanRun` method. +message StartScanRunRequest { + // Required. + // The resource name of the ScanConfig to be used. The name follows the + // format of 'projects/{projectId}/scanConfigs/{scanConfigId}'. + string name = 1; +} + +// Request for the `GetScanRun` method. +message GetScanRunRequest { + // Required. + // The resource name of the ScanRun to be returned. The name follows the + // format of + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}'. + string name = 1; +} + +// Request for the `ListScanRuns` method. +message ListScanRunsRequest { + // Required. + // The parent resource name, which should be a scan resource name in the + // format 'projects/{projectId}/scanConfigs/{scanConfigId}'. + string parent = 1; + + // A token identifying a page of results to be returned. This should be a + // `next_page_token` value returned from a previous List request. + // If unspecified, the first page of results is returned. + string page_token = 2; + + // The maximum number of ScanRuns to return, can be limited by server. + // If not specified or not positive, the implementation will select a + // reasonable value. + int32 page_size = 3; +} + +// Response for the `ListScanRuns` method. +message ListScanRunsResponse { + // The list of ScanRuns returned. + repeated ScanRun scan_runs = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// Request for the `StopScanRun` method. +message StopScanRunRequest { + // Required. + // The resource name of the ScanRun to be stopped. The name follows the + // format of + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}'. + string name = 1; +} + +// Request for the `ListCrawledUrls` method. +message ListCrawledUrlsRequest { + // Required. + // The parent resource name, which should be a scan run resource name in the + // format + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}'. + string parent = 1; + + // A token identifying a page of results to be returned. This should be a + // `next_page_token` value returned from a previous List request. + // If unspecified, the first page of results is returned. + string page_token = 2; + + // The maximum number of CrawledUrls to return, can be limited by server. + // If not specified or not positive, the implementation will select a + // reasonable value. + int32 page_size = 3; +} + +// Response for the `ListCrawledUrls` method. +message ListCrawledUrlsResponse { + // The list of CrawledUrls returned. + repeated CrawledUrl crawled_urls = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// Request for the `GetFinding` method. +message GetFindingRequest { + // Required. + // The resource name of the Finding to be returned. The name follows the + // format of + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}/findings/{findingId}'. + string name = 1; +} + +// Request for the `ListFindings` method. +message ListFindingsRequest { + // Required. + // The parent resource name, which should be a scan run resource name in the + // format + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}'. + string parent = 1; + + // The filter expression. The expression must be in the format: <field> + // <operator> <value>. + // Supported field: 'finding_type'. + // Supported operator: '='. + string filter = 2; + + // A token identifying a page of results to be returned. This should be a + // `next_page_token` value returned from a previous List request. + // If unspecified, the first page of results is returned. + string page_token = 3; + + // The maximum number of Findings to return, can be limited by server. + // If not specified or not positive, the implementation will select a + // reasonable value. + int32 page_size = 4; +} + +// Response for the `ListFindings` method. +message ListFindingsResponse { + // The list of Findings returned. + repeated Finding findings = 1; + + // Token to retrieve the next page of results, or empty if there are no + // more results in the list. + string next_page_token = 2; +} + +// Request for the `ListFindingTypeStats` method. +message ListFindingTypeStatsRequest { + // Required. + // The parent resource name, which should be a scan run resource name in the + // format + // 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}'. + string parent = 1; +} + +// Response for the `ListFindingTypeStats` method. +message ListFindingTypeStatsResponse { + // The list of FindingTypeStats returned. + repeated FindingTypeStats finding_type_stats = 1; +} diff --git a/google/cloud/websecurityscanner/v1alpha/websecurityscanner_gapic.yaml b/google/cloud/websecurityscanner/v1alpha/websecurityscanner_gapic.yaml new file mode 100644 index 000000000..3b2c313c6 --- /dev/null +++ b/google/cloud/websecurityscanner/v1alpha/websecurityscanner_gapic.yaml @@ -0,0 +1,356 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.websecurityscanner.v1alpha + python: + package_name: google.cloud.websecurityscanner_v1alpha.gapic + go: + package_name: cloud.google.com/go/cloud/websecurityscanner/apiv1alpha + csharp: + package_name: Google.Cloud.Websecurityscanner.V1Alpha + ruby: + package_name: Google::Cloud::Websecurityscanner::V1alpha + php: + package_name: Google\Cloud\Websecurityscanner\V1alpha + nodejs: + package_name: websecurityscanner.v1alpha +# A list of API interface configurations. +interfaces: + # The fully qualified name of the API interface. +- name: google.cloud.websecurityscanner.v1alpha.WebSecurityScanner + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project} + entity_name: project + language_overrides: + - language: csharp + common_resource_name: Google.Api.Gax.ResourceNames.ProjectName + - name_pattern: projects/{project}/scanConfigs/{scan_config} + entity_name: scan_config + - name_pattern: projects/{project}/scanConfigs/{scan_config}/scanRuns/{scan_run} + entity_name: scan_run + - name_pattern: projects/{project}/scanConfigs/{scan_config}/scanRuns/{scan_run}/findings/{finding} + entity_name: finding + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - UNAVAILABLE + - DEADLINE_EXCEEDED + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # resource_name_treatment - An enum that specifies how to treat the resource + # name formats defined in the field_name_patterns and + # response_field_name_patterns fields. + # UNSET: default value + # NONE: the collection configs will not be used by the generated code. + # VALIDATE: string fields will be validated by the client against the + # specified resource name formats. + # STATIC_TYPES: the client will use generated types for resource names. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateScanConfig + flattening: + groups: + - parameters: + - parent + - scan_config + required_fields: + - parent + - scan_config + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: DeleteScanConfig + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: scan_config + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetScanConfig + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: scan_config + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: ListScanConfigs + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: scan_configs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: project + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: UpdateScanConfig + flattening: + groups: + - parameters: + - scan_config + - update_mask + required_fields: + - scan_config + - update_mask + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + scan_config.name: scan_config + timeout_millis: 60000 + - name: StartScanRun + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: scan_config + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetScanRun + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: scan_run + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: ListScanRuns + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: scan_runs + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: scan_config + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: StopScanRun + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: scan_run + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: ListCrawledUrls + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: crawled_urls + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: scan_run + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: GetFinding + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: finding + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: ListFindings + flattening: + groups: + - parameters: + - parent + - filter + required_fields: + - parent + - filter + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: findings + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: scan_run + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES + - name: ListFindingTypeStats + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: scan_run + timeout_millis: 60000 + resource_name_treatment: STATIC_TYPES +resource_name_generation: +- message_name: CreateScanConfigRequest + field_entity_map: + parent: project +- message_name: DeleteScanConfigRequest + field_entity_map: + name: scan_config +- message_name: GetScanConfigRequest + field_entity_map: + name: scan_config +- message_name: ListScanConfigsRequest + field_entity_map: + parent: project +- message_name: StartScanRunRequest + field_entity_map: + name: scan_config +- message_name: GetScanRunRequest + field_entity_map: + name: scan_run +- message_name: ListScanRunsRequest + field_entity_map: + parent: scan_config +- message_name: StopScanRunRequest + field_entity_map: + name: scan_run +- message_name: ListCrawledUrlsRequest + field_entity_map: + parent: scan_run +- message_name: GetFindingRequest + field_entity_map: + name: finding +- message_name: ListFindingsRequest + field_entity_map: + parent: scan_run +- message_name: ListFindingTypeStatsRequest + field_entity_map: + parent: scan_run diff --git a/google/cloud/websecurityscanner/web_security_scanner_v1alpha.yaml b/google/cloud/websecurityscanner/web_security_scanner_v1alpha.yaml new file mode 100644 index 000000000..a31df929a --- /dev/null +++ b/google/cloud/websecurityscanner/web_security_scanner_v1alpha.yaml @@ -0,0 +1,17 @@ +type: google.api.Service +config_version: 3 +name: websecurityscanner.googleapis.com +title: Web Security Scanner API + +apis: +- name: google.cloud.websecurityscanner.v1alpha.WebSecurityScanner + +documentation: + summary: Web Security Scanner API (under development). + +authentication: + rules: + - selector: '*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform |