push all website files

This commit is contained in:
Jacob Levine
2019-01-06 13:14:45 -06:00
parent d7301e26c3
commit d2d5d4c04e
15662 changed files with 2166516 additions and 0 deletions

View File

@@ -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;
}

View File

@@ -0,0 +1,653 @@
// 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;
}

View File

@@ -0,0 +1,222 @@
// 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;
}

View File

@@ -0,0 +1,525 @@
// 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;
}

View File

@@ -0,0 +1,214 @@
// 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;
}

View File

@@ -0,0 +1,597 @@
// 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.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 Google 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 Google 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 Google 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 Google Compute Engine config settings for
// all instances in a cluster.
GceClusterConfig gce_cluster_config = 8;
// Optional. The Google Compute Engine config settings for
// the master instance in a cluster.
InstanceGroupConfig master_config = 9;
// Optional. The Google Compute Engine config settings for
// worker instances in a cluster.
InstanceGroupConfig worker_config = 10;
// Optional. The Google 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;
}
// Common config settings for resources of Google Compute Engine cluster
// instances, applicable to all instances in the cluster.
message GceClusterConfig {
// Optional. The zone where the Google 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 Google 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 Google 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
// Google Compute Engine service account. Custom service accounts need
// permissions equivalent to the folloing 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 Google
// 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 Google Compute Engine tags to add to all instances (see
// [Tagging instances](/compute/docs/label-or-tag-resources#tags)).
repeated string tags = 4;
// The Google 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 Google 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;
// Optional. The list of instance names. Cloud Dataproc derives the names from
// `cluster_name`, `num_instances`, and the instance group if not set by user
// (recommended practice is to let Cloud Dataproc derive the name).
repeated string instance_names = 2;
// Output-only. The Google Compute Engine image resource used for cluster
// instances. Inferred from `SoftwareConfig.image_version`.
string image_uri = 3;
// Optional. The Google 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`
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 Google Compute Engine Instance Group
// Manager that manages this group.
// This is only used for preemptible instance groups.
ManagedGroupConfig managed_group_config = 7;
// Optional. The Google 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 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 [Google 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`
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. 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. Google 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;
}
enum Substate {
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 match the
// regular expression `[0-9]+\.[0-9]+`. If unspecified, it defaults to the
// latest version (see [Cloud Dataproc Versioning](/dataproc/versioning)).
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;
}
// 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;
// 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;
}
// 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;
}
// 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 Google 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;
}

View File

@@ -0,0 +1,740 @@
// 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.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;
}
enum Substate {
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;
}
// Job scheduling options.
//
// **Beta Feature**: These options are available for testing purposes only.
// They may be changed before final release.
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;
}
// 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;
}

View File

@@ -0,0 +1,85 @@
// 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.dataproc.v1;
import "google/api/annotations.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 = "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;
}

View File

@@ -0,0 +1,712 @@
// 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.dataproc.v1beta2;
import "google/api/annotations.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;
// 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;
}
// 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;
// Output only. The Compute Engine image resource used for cluster
// instances. 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&rarr;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 related schedule configuration.
message LifecycleConfig {
// Optional. The longest duration that cluster would keep alive while staying
// idle; passing this threshold will cause cluster to be auto-deleted.
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 life duration of cluster, the cluster will be auto-deleted
// at the end of this duration.
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;
}

View File

@@ -0,0 +1,767 @@
// 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.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. 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;
}
// 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;
}

View File

@@ -0,0 +1,83 @@
// 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.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;
}

View File

@@ -0,0 +1,25 @@
// 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.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";

View File

@@ -0,0 +1,544 @@
// 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.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/*/regions/*}/workflowTemplates:instantiateInline"
body: "template"
additional_bindings {
post: "/v1beta2/{parent=projects/*/locations/*}/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;
}
// 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 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 managed cluster.
string cluster_name = 7;
// Map from parameter names to values that were used for those parameters.
map<string, string> parameters = 8;
}
// 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;
// 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 instance_id = 3;
}
// 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 instance_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;
}

View File

@@ -0,0 +1,330 @@
// 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.dialogflow.v2;
import "google/api/annotations.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](/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://dialogflow.com/docs/prebuilt-agents) 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://dialogflow.com/docs/agents).
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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://dialogflow.com/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://dialogflow.com/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 is 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 URI to export the agent to.
// Note: The URI must start with
// "gs://". 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:
//
// curl \
// 'https://dialogflow.googleapis.com/v2/projects/<project_name>/agent:export'\
// -X POST \
// -H 'Authorization: Bearer '$(gcloud auth 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>
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:
//
// curl \
// 'https://dialogflow.googleapis.com/v2/projects/<project_name>/agent:import\
// -X POST \
// -H 'Authorization: Bearer '$(gcloud auth print-access-token) \
// -H 'Accept: application/json' \
// -H 'Content-Type: application/json' \
// --compressed \
// --data-binary "{
// 'agentContent': '$(cat <agent zip file> | base64 -w 0)'
// }"
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:
//
// curl \
// 'https://dialogflow.googleapis.com/v2/projects/<project_name>/agent:restore\
// -X POST \
// -H 'Authorization: Bearer '$(gcloud auth print-access-token) \
// -H 'Accept: application/json' \
// -H 'Content-Type: application/json' \
// --compressed \
// --data-binary "{
// 'agentContent': '$(cat <agent zip file> | base64 -w 0)'
// }" \
bytes agent_content = 3;
}
}

View File

@@ -0,0 +1,177 @@
// 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.dialogflow.v2;
import "google/api/annotations.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 10 minutes
// if no intents are matched for a `DetectIntent` request.
//
// For more information about contexts, see the
// [Dialogflow documentation](https://dialogflow.com/docs/contexts).
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.
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>`.
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 10 minutes even if there
// are no matching queries.
int32 lifespan_count = 2;
// Optional. The collection of parameters associated with this context.
// Refer to [this doc](https://dialogflow.com/docs/actions-and-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;
}

View File

@@ -0,0 +1,419 @@
// 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.dialogflow.v2;
import "google/api/annotations.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://dialogflow.com/docs/entities).
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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 (extends the
// existing collection of entries).
//
// 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 entities in the specified entity type (replaces the existing
// collection of entries).
//
// Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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 {
// Optional. Represents an entity.
message Entity {
// Required.
// For `KIND_MAP` entity types:
// A canonical name 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 synonyms. For `KIND_LIST` entity types this
// 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;
}
// Required for all methods except `create` (`create` populates the name
// automatically.
// The unique identifier of the entity type. Format:
// `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
string name = 1;
// Required. The name of the entity.
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 entities 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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
EntityType entity_type = 1;
// Optional. The language of entity synonyms defined in `entity_type`. If not
// specified, the agent's default language is used.
// [More than a dozen
// languages](https://dialogflow.com/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 type 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.
// [More than a dozen
// languages](https://dialogflow.com/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 collection of 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.
// [More than a dozen
// languages](https://dialogflow.com/docs/reference/language) are supported.
// Note: languages must be enabled in the agent, before they can be used.
string language_code = 3;
}
// The response message for [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2.EntityTypes.BatchCreateEntities].
message BatchUpdateEntitiesRequest {
// Required. The name of the entity type to update the entities in. Format:
// `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
string parent = 1;
// Required. The collection of new entities to replace the existing entities.
repeated EntityType.Entity entities = 2;
// Optional. The language of entity synonyms defined in `entities`. If not
// specified, the agent's default language is used.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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;
}

View File

@@ -0,0 +1,811 @@
// 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.dialogflow.v2;
import "google/api/annotations.proto";
import "google/cloud/dialogflow/v2/context.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 = "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://dialogflow.com/docs/intents).
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.
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 or template that the agent is trained on.
message TrainingPhrase {
// Represents a part of a training phrase.
message Part {
// Required. The text corresponding to the example or template,
// if there are no annotations. For
// annotated examples, it is the text for one of the example's parts.
string text = 1;
// Optional. The entity type name prefixed with `@`. This field is
// required for the annotated part of the text and applies only to
// examples.
string entity_type = 2;
// Optional. The parameter name for the value extracted from the
// annotated part of the example.
string alias = 3;
// Optional. Indicates whether the text was manually annotated by the
// developer.
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 = 2;
}
// Required. The unique identifier of this training phrase.
string name = 1;
// Required. The type of the training phrase.
Type type = 2;
// Required. The collection of training phrase parts (can be annotated).
// Fields: `entity_type`, `alias` and `user_defined` should be populated
// only for the annotated parts of the training phrase.
repeated Part parts = 3;
// Optional. Indicates how many times this example or template 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 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;
}
// Required for all methods except `create` (`create` populates the name
// automatically.
// The unique identifier of this intent.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
string name = 1;
// Required. The name of this intent.
string display_name = 2;
// Required. Indicates whether webhooks are enabled for the intent.
WebhookState webhook_state = 6;
// Optional. The priority of this intent. Higher numbers represent higher
// priorities. Zero or 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/templates that the agent is
// trained on.
repeated TrainingPhrase training_phrases = 9;
// Optional. The name of the action associated with the intent.
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;
// The unique identifier of the root intent in the chain of followup intents.
// It identifies the correct followup intents chain for this intent.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
string root_followup_intent_name = 16;
// The unique identifier of the parent intent in the chain of followup
// intents.
// It identifies the parent followup intent.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
string parent_followup_intent_name = 17;
// Optional. Collection of information about all followup intents that have
// name of this intent as a root_name.
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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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. [More than a dozen
// languages](https://dialogflow.com/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.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
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. [More than a dozen
// languages](https://dialogflow.com/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.
// 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. [More than a dozen
// languages](https://dialogflow.com/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;
}

View File

@@ -0,0 +1,478 @@
// 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.dialogflow.v2;
import "google/api/annotations.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. 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 results of the conversational query or event processing.
QueryResult query_result = 2;
// Specifies the status of the webhook request. `webhook_status`
// is never populated in webhook requests.
google.rpc.Status webhook_status = 3;
}
// 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. The collection of session entity types to replace or extend
// developer entities with for this query only. The entity synonyms apply
// to all languages.
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;
}
// 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://dialogflow.com/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.
//
// You should not rely on this field as it isn't guaranteed to be accurate, or
// even set. In particular this field isn't set in Webhook calls and 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.
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).
float intent_detection_confidence = 12;
// The free-form diagnostic info. For example, this field
// could contain webhook call latency.
google.protobuf.Struct diagnostic_info = 14;
}
// 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>`. Its 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. 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;
}
// 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. recognition_event_type: `RECOGNITION_EVENT_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 `event_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 `event_type` = `RECOGNITION_EVENT_TRANSCRIPT`.
string transcript = 2;
// The default of 0.0 is a sentinel value indicating `confidence` was not set.
// 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 `event_type` = `RECOGNITION_EVENT_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](/speech/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://dialogflow.com/docs/languages) 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](/speech/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 bytes.
string text = 1;
// Required. The language of this conversational query. See [Language
// Support](https://dialogflow.com/docs/languages) 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://dialogflow.com/docs/languages) 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;
}
// Audio encoding of the audio content sent in the conversational query request.
// Refer to the [Cloud Speech API documentation](/speech/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;
}

View File

@@ -0,0 +1,184 @@
// 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.dialogflow.v2;
import "google/api/annotations.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://dialogflow.com/docs/entities).
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.
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.
// Calls to `ListSessionEntityTypes`, `GetSessionEntityType`,
// `CreateSessionEntityType` and `UpdateSessionEntityType` return the full
// collection of entities from the developer entity type in the agent's
// default language and the session entity type.
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>`.
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;
}

View File

@@ -0,0 +1,111 @@
// 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.dialogflow.v2;
import "google/api/annotations.proto";
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";
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>`.
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. This field is set to the value of `QueryParameters.payload` field
// passed in the request.
google.protobuf.Struct payload = 3;
}

View File

@@ -0,0 +1,334 @@
// 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.dialogflow.v2beta1;
import "google/api/annotations.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](/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://dialogflow.com/docs/prebuilt-agents) 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://dialogflow.com/docs/agents).
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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://dialogflow.com/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://dialogflow.com/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 is 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 URI to export the agent to.
// Note: The URI must start with
// "gs://". 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:
//
// curl \
// 'https://dialogflow.googleapis.com/v2beta1/projects/<project_name>/agent:export'\
// -X POST \
// -H 'Authorization: Bearer '$(gcloud auth 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>
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:
//
// curl \
// 'https://dialogflow.googleapis.com/v2beta1/projects/<project_name>/agent:import\
// -X POST \
// -H 'Authorization: Bearer '$(gcloud auth print-access-token) \
// -H 'Accept: application/json' \
// -H 'Content-Type: application/json' \
// --compressed \
// --data-binary "{
// 'agentContent': '$(cat <agent zip file> | base64 -w 0)'
// }"
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:
//
// curl \
// 'https://dialogflow.googleapis.com/v2beta1/projects/<project_name>/agent:restore\
// -X POST \
// -H 'Authorization: Bearer '$(gcloud auth print-access-token) \
// -H 'Accept: application/json' \
// -H 'Content-Type: application/json' \
// --compressed \
// --data-binary "{
// 'agentContent': '$(cat <agent zip file> | base64 -w 0)'
// }" \
bytes agent_content = 3;
}
}

View File

@@ -0,0 +1,230 @@
// 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.dialogflow.v2beta1;
import "google/api/annotations.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 10 minutes
// if no intents are matched for a `DetectIntent` request.
//
// For more information about contexts, see the
// [Dialogflow documentation](https://dialogflow.com/docs/contexts).
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.
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>`. Note: Environments and
// users are under construction and will be available soon. The Context ID is
// always converted to lowercase. 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 10 minutes even if there
// are no matching queries.
int32 lifespan_count = 2;
// Optional. The collection of parameters associated with this context.
// Refer to [this doc](https://dialogflow.com/docs/actions-and-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>`. Note: Environments and users are under
// construction and will be available soon. 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>`. Note: Environments and
// users are under construction and will be available soon. 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>`. Note: Environments and users are under
// construction and will be available soon. 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>`. Note: Environments and
// users are under construction and will be available soon. 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>`. Note: Environments and users are under construction and will be
// available soon. If <Environment ID> is not specified we assume default
// 'draft' environment. If <User ID> is not specified, we assume default
// '-' user.
string parent = 1;
}

View File

@@ -0,0 +1,419 @@
// 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.dialogflow.v2beta1;
import "google/api/annotations.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://dialogflow.com/docs/entities).
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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 (extends the
// existing collection of entries).
//
// 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 entities in the specified entity type (replaces the existing
// collection of entries).
//
// Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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],
// metadata: [google.protobuf.Struct][google.protobuf.Struct]>
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 {
// Optional. Represents an entity.
message Entity {
// Required.
// For `KIND_MAP` entity types:
// A canonical name 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 synonyms. For `KIND_LIST` entity types this
// 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;
}
// Required for all methods except `create` (`create` populates the name
// automatically.
// The unique identifier of the entity type. Format:
// `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
string name = 1;
// Required. The name of the entity.
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 entities 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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
EntityType entity_type = 1;
// Optional. The language of entity synonyms defined in `entity_type`. If not
// specified, the agent's default language is used.
// [More than a dozen
// languages](https://dialogflow.com/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 type 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.
// [More than a dozen
// languages](https://dialogflow.com/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 collection of 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.
// [More than a dozen
// languages](https://dialogflow.com/docs/reference/language) are supported.
// Note: languages must be enabled in the agent, before they can be used.
string language_code = 3;
}
// The response message for [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2beta1.EntityTypes.BatchCreateEntities].
message BatchUpdateEntitiesRequest {
// Required. The name of the entity type to update the entities in. Format:
// `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
string parent = 1;
// Required. The collection of new entities to replace the existing entities.
repeated EntityType.Entity entities = 2;
// Optional. The language of entity synonyms defined in `entities`. If not
// specified, the agent's default language is used.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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;
}

View File

@@ -0,0 +1,824 @@
// 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.dialogflow.v2beta1;
import "google/api/annotations.proto";
import "google/cloud/dialogflow/v2beta1/context.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 = "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://dialogflow.com/docs/intents).
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.
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 or template that the agent is trained on.
message TrainingPhrase {
// Represents a part of a training phrase.
message Part {
// Required. The text corresponding to the example or template,
// if there are no annotations. For
// annotated examples, it is the text for one of the example's parts.
string text = 1;
// Optional. The entity type name prefixed with `@`. This field is
// required for the annotated part of the text and applies only to
// examples.
string entity_type = 2;
// Optional. The parameter name for the value extracted from the
// annotated part of the example.
string alias = 3;
// Optional. Indicates whether the text was manually annotated by the
// developer.
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 = 2;
}
// Required. The unique identifier of this training phrase.
string name = 1;
// Required. The type of the training phrase.
Type type = 2;
// Required. The collection of training phrase parts (can be annotated).
// Fields: `entity_type`, `alias` and `user_defined` should be populated
// only for the annotated parts of the training phrase.
repeated Part parts = 3;
// Optional. Indicates how many times this example or template 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 {
// 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;
}
// 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 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;
}
// Required for all methods except `create` (`create` populates the name
// automatically.
// The unique identifier of this intent.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
string name = 1;
// Required. The name of this intent.
string display_name = 2;
// Required. Indicates whether webhooks are enabled for the intent.
WebhookState webhook_state = 6;
// Optional. The priority of this intent. Higher numbers represent higher
// priorities. Zero or 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 neither `ml_enabled` nor `ml_disabled` field is set, 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;
// 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. 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/templates that the agent is
// trained on.
repeated TrainingPhrase training_phrases = 9;
// Optional. The name of the action associated with the intent.
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;
// The unique identifier of the root intent in the chain of followup intents.
// It identifies the correct followup intents chain for this intent.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
string root_followup_intent_name = 16;
// The unique identifier of the parent intent in the chain of followup
// intents.
// It identifies the parent followup intent.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
string parent_followup_intent_name = 17;
// Optional. Collection of information about all followup intents that have
// name of this intent as a root_name.
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.
// [More than a dozen
// languages](https://dialogflow.com/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.
// [More than a dozen
// languages](https://dialogflow.com/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. [More than a dozen
// languages](https://dialogflow.com/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.
// Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
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. [More than a dozen
// languages](https://dialogflow.com/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.
// 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. [More than a dozen
// languages](https://dialogflow.com/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;
}

View File

@@ -0,0 +1,492 @@
// 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.dialogflow.v2beta1;
import "google/api/annotations.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>`. Note: Environments and users are under
// construction and will be available soon. If <Environment ID> is not
// specified, we assume default 'draft' environment. If <User ID> is not
// specified, we are using "-". Its 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. 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 results of the conversational query or event processing.
QueryResult query_result = 2;
// Specifies the status of the webhook request. `webhook_status`
// is never populated in webhook requests.
google.rpc.Status webhook_status = 3;
}
// 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. The collection of session entity types to replace or extend
// developer entities with for this query only. The entity synonyms apply
// to all languages.
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;
}
// 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://dialogflow.com/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.
//
// You should not rely on this field as it isn't guaranteed to be accurate, or
// even set. In particular this field isn't set in Webhook calls and 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.
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).
float intent_detection_confidence = 12;
// The free-form diagnostic info. For example, this field
// could contain webhook call latency.
google.protobuf.Struct diagnostic_info = 14;
}
// 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>`, or
// `projects/<Project ID>/agent/environments/<Environment ID>/users/<User
// ID>/sessions/<Session ID>`. Note: Environments and users are under
// construction and will be available soon. If <Environment ID> is not
// specified, we assume default 'draft' environment. If <User ID> is not
// specified, we are using "-". Its 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. 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;
}
// 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. recognition_event_type: `RECOGNITION_EVENT_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 `event_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 `event_type` = `RECOGNITION_EVENT_TRANSCRIPT`.
string transcript = 2;
// The default of 0.0 is a sentinel value indicating `confidence` was not set.
// 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 `event_type` = `RECOGNITION_EVENT_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](/speech/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://dialogflow.com/docs/languages) 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](/speech/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 bytes.
string text = 1;
// Required. The language of this conversational query. See [Language
// Support](https://dialogflow.com/docs/languages) 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://dialogflow.com/docs/languages) 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;
}
// Audio encoding of the audio content sent in the conversational query request.
// Refer to the [Cloud Speech API documentation](/speech/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;
}

View File

@@ -0,0 +1,232 @@
// 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.dialogflow.v2beta1;
import "google/api/annotations.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://dialogflow.com/docs/entities).
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.
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.
// Calls to `ListSessionEntityTypes`, `GetSessionEntityType`,
// `CreateSessionEntityType` and `UpdateSessionEntityType` return the full
// collection of entities from the developer entity type in the agent's
// default language and the session entity type.
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>`.
// Note: Environments and users are under construction and will be available
// soon. If <Environment ID> is not specified, we assume default 'draft'
// environment. If <User ID> is not specified, we assume default '-' user.
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>`.
// Note: Environments and users are under construction and will be available
// soon. 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>`.
// Note: Environments and users re under construction and will be available
// soon. 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>`.
// Note: Environments and users are under construction and will be available
// soon. 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>`.
// Note: Environments and users are under construction and will be available
// soon. 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>`.
// Note: Environments and users are under construction and will be available
// soon. If <Environment ID> is not specified, we assume default 'draft'
// environment. If <User ID> is not specified, we assume default '-' user.
string name = 1;
}

View File

@@ -0,0 +1,111 @@
// 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.dialogflow.v2beta1;
import "google/api/annotations.proto";
import "google/cloud/dialogflow/v2beta1/context.proto";
import "google/cloud/dialogflow/v2beta1/intent.proto";
import "google/cloud/dialogflow/v2beta1/session.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 = "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>`.
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. This field is set to the value of `QueryParameters.payload` field
// passed in the request.
google.protobuf.Struct payload = 3;
}

View File

@@ -0,0 +1,295 @@
// 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;
}

View File

@@ -0,0 +1,54 @@
// 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;
}

View File

@@ -0,0 +1,419 @@
// 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.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";
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. Allows to manipulate device registry
// instances and the registration of devices (Things) to the cloud.
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/*}"
additional_bindings {
delete: "/v1/{name=projects/*/locations/*/registries/*/groups/*/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/*/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: "*"
}
};
}
}
// 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, but if there is a non-empty `page_token`, it
// indicates that more entries are available.
int32 page_size = 2;
// The value returned by the last `ListDeviceRegistriesResponse`; indicates
// that this is a continuation of a prior `ListDeviceRegistries` call, and
// that 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
// will generate that field from the device registry `id` provided 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 registry. 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 numerical ids. If empty, it will ignore this field. This
// field cannot hold more than 10,000 entries.
repeated uint64 device_num_ids = 2;
// A list of device string identifiers. If empty, it will ignore this field.
// For example, `['device0', 'device12']`. This field cannot hold more than
// 10,000 entries.
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 by default, along with any
// other fields specified.
google.protobuf.FieldMask field_mask = 4;
// 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, but if there is a non-empty `page_token`, it
// indicates that more entries are available.
int32 page_size = 100;
// The value returned by the last `ListDevicesResponse`; indicates
// that this is a continuation of a prior `ListDevices` call, and
// that the system should return the next page of data.
string page_token = 101;
}
// 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;
}

View File

@@ -0,0 +1,385 @@
// 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.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;
// 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;
}
// 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;
// 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;
}
// 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;
}

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,950 @@
// 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;
}

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,99 @@
// 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;
}

View File

@@ -0,0 +1,605 @@
// 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;
}

View File

@@ -0,0 +1,371 @@
// 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;
}

View File

@@ -0,0 +1,72 @@
// 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;
}

View File

@@ -0,0 +1,240 @@
// 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;
}

View File

@@ -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;
}

View File

@@ -0,0 +1,71 @@
// 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;
}

View File

@@ -0,0 +1,149 @@
// 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;
}

View File

@@ -0,0 +1,148 @@
// 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;
}

View File

@@ -0,0 +1,149 @@
// 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;
}

View File

@@ -0,0 +1,340 @@
// 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.redis.v1beta1;
import "google/api/annotations.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 peered to 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"
};
}
// 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. Details can be
// found in the `status_message` field.
REPAIRING = 5;
// Maintenance is being performed on this Redis instance.
MAINTENANCE = 6;
}
// 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 get to 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.
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 a 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. In
// single zone deployments, this will always be the same as [location_id]
// provided by the user at creation time. In cross-zone instances (only
// applicable in STANDARD_HA tier), this can be either [location_id] or
// [alternative_location_id] and can change on 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 GB.
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;
}
// 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][CloudRedis.Instance]:
// * `display_name`
// * `labels`
// * `memory_size_gb`
// * `redis_config`
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;
}
// 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 {
}

View File

@@ -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.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 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 Folders parent's resource name.
// Updates to the folder's parent must be performed via [MoveFolders].
string parent = 2;
// The folders display name.
// A folders 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;
}

View File

@@ -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 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;
}

View File

@@ -0,0 +1,411 @@
// 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;
}

View File

@@ -0,0 +1,445 @@
// 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.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/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
// [audio limits](https://cloud.google.com/speech/limits#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 {
// Audio encoding of the data sent in the audio message. All encodings support
// only 1 channel (mono) audio. Only `FLAC` and `WAV` include a header that
// describes the bytes of audio that follow the header. The other encodings
// are raw audio bytes with no header.
//
// For best results, the audio source should be captured and transmitted using
// a lossless encoding (`FLAC` or `LINEAR16`). Recognition accuracy may be
// reduced if lossy codecs, which include the other codecs listed in
// this section, are used to capture or transmit the audio, particularly if
// background noise is present.
enum AudioEncoding {
// Not specified. Will return result [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT].
ENCODING_UNSPECIFIED = 0;
// Uncompressed 16-bit signed little-endian samples (Linear PCM).
LINEAR16 = 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.
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 16000.
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;
}
// *Required* Encoding of audio data sent in all `RecognitionAudio` messages.
AudioEncoding encoding = 1;
// *Required* 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).
int32 sample_rate_hertz = 2;
// *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 = 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* A means to provide context to assist the speech recognition.
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;
}
// 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;
}
// 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
// [audio limits](https://cloud.google.com/speech/limits#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`. 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 more `is_final=false` results followed by zero or one
// `is_final=true` result (the newly settled portion).
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`).
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;
}
// 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;
}
// 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;
}

View File

@@ -0,0 +1,421 @@
// 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.speech.v1beta1;
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 go_package = "google.golang.org/genproto/googleapis/cloud/speech/v1beta1;speech";
option java_multiple_files = true;
option java_outer_classname = "SpeechProto";
option java_package = "com.google.cloud.speech.v1beta1";
// Service that implements Google Cloud Speech API.
service Speech {
// Performs synchronous speech recognition: receive results after all audio
// has been sent and processed.
rpc SyncRecognize(SyncRecognizeRequest) returns (SyncRecognizeResponse) {
option (google.api.http) = { post: "/v1beta1/speech:syncrecognize" body: "*" };
}
// Performs asynchronous speech recognition: receive results via the
// [google.longrunning.Operations]
// (/speech/reference/rest/v1beta1/operations#Operation)
// interface. Returns either an
// `Operation.error` or an `Operation.response` which contains
// an `AsyncRecognizeResponse` message.
rpc AsyncRecognize(AsyncRecognizeRequest) returns (google.longrunning.Operation) {
option (google.api.http) = { post: "/v1beta1/speech:asyncrecognize" 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 `SyncRecognize` method.
message SyncRecognizeRequest {
// *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 `AsyncRecognize` method.
message AsyncRecognizeRequest {
// *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
// [audio limits](https://cloud.google.com/speech/limits#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_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 {
// Audio encoding of the data sent in the audio message. All encodings support
// only 1 channel (mono) audio. Only `FLAC` includes a header that describes
// the bytes of audio that follow the header. The other encodings are raw
// audio bytes with no header.
//
// For best results, the audio source should be captured and transmitted using
// a lossless encoding (`FLAC` or `LINEAR16`). Recognition accuracy may be
// reduced if lossy codecs (such as AMR, AMR_WB and MULAW) are used to capture
// or transmit the audio, particularly if background noise is present.
enum AudioEncoding {
// Not specified. Will return result [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT].
ENCODING_UNSPECIFIED = 0;
// Uncompressed 16-bit signed little-endian samples (Linear PCM).
// This is the only encoding that may be used by `AsyncRecognize`.
LINEAR16 = 1;
// This is the recommended encoding for `SyncRecognize` and
// `StreamingRecognize` because it uses lossless compression; therefore
// recognition accuracy is not compromised by a lossy codec.
//
// The stream FLAC (Free Lossless Audio Codec) encoding is specified at:
// http://flac.sourceforge.net/documentation.html.
// 16-bit and 24-bit samples are supported.
// 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` must be 8000 Hz.
AMR = 4;
// Adaptive Multi-Rate Wideband codec. `sample_rate` must be 16000 Hz.
AMR_WB = 5;
}
// *Required* Encoding of audio data sent in all `RecognitionAudio` messages.
AudioEncoding encoding = 1;
// *Required* 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).
int32 sample_rate = 2;
// *Optional* The language of the supplied audio as a BCP-47 language tag.
// Example: "en-GB" https://www.rfc-editor.org/rfc/bcp/bcp47.txt
// If omitted, defaults to "en-US". See
// [Language Support](https://cloud.google.com/speech/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* A means to provide context to assist the speech recognition.
SpeechContext speech_context = 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;
}
// 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
// [audio limits](https://cloud.google.com/speech/limits#content).
message RecognitionAudio {
// The audio source, which is either inline content or a GCS 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`. 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 `SyncRecognize`. method. It
// contains the result as zero or more sequential `SpeechRecognitionResult`
// messages.
message SyncRecognizeResponse {
// *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 `AsyncRecognize`. 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 AsyncRecognizeResponse {
// *Output-only* Sequential list of transcription results corresponding to
// sequential portions of audio.
repeated SpeechRecognitionResult results = 2;
}
// Describes the progress of a long-running `AsyncRecognize` call. It is
// included in the `metadata` field of the `Operation` returned by the
// `GetOperation` call of the `google::longrunning::Operations` service.
message AsyncRecognizeMetadata {
// 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 one or more `StreamingRecognizeResponse`
// 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. endpointer_type: START_OF_SPEECH
//
// 2. results { alternatives { transcript: "tube" } stability: 0.01 }
// result_index: 0
//
// 3. results { alternatives { transcript: "to be a" } stability: 0.01 }
// result_index: 0
//
// 4. results { alternatives { transcript: "to be" } stability: 0.9 }
// results { alternatives { transcript: " or not to be" } stability: 0.01 }
// result_index: 0
//
// 5. results { alternatives { transcript: "to be or not to be"
// confidence: 0.92 }
// alternatives { transcript: "to bee or not to bee" }
// is_final: true }
// result_index: 0
//
// 6. results { alternatives { transcript: " that's" } stability: 0.01 }
// result_index: 1
//
// 7. results { alternatives { transcript: " that is" } stability: 0.9 }
// results { alternatives { transcript: " the question" } stability: 0.01 }
// result_index: 1
//
// 8. endpointer_type: END_OF_SPEECH
//
// 9. results { alternatives { transcript: " that is the question"
// confidence: 0.98 }
// alternatives { transcript: " that was the question" }
// is_final: true }
// result_index: 1
//
// 10. endpointer_type: END_OF_AUDIO
//
// Notes:
//
// - Only two of the above responses #5 and #9 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`. #4 and #7 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.
//
// - The `result_index` indicates the portion of audio that has had final
// results returned, and is no longer being processed. For example, the
// `results` in #6 and later correspond to the portion of audio after
// "to be or not to be".
message StreamingRecognizeResponse {
// Indicates the type of endpointer event.
enum EndpointerType {
// No endpointer event specified.
ENDPOINTER_EVENT_UNSPECIFIED = 0;
// Speech has been detected in the audio stream, and the service is
// beginning to process it.
START_OF_SPEECH = 1;
// Speech has ceased to be detected in the audio stream. (For example, the
// user may have paused after speaking.) If `single_utterance` is `false`,
// the service will continue to process audio, and if subsequent speech is
// detected, will send another START_OF_SPEECH event.
END_OF_SPEECH = 2;
// This event is sent after the client has half-closed the input stream gRPC
// connection and the server has received all of the audio. (The server may
// still be processing the audio and may subsequently return additional
// results.)
END_OF_AUDIO = 3;
// This event is only sent when `single_utterance` is `true`. It 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.
END_OF_UTTERANCE = 4;
}
// *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.
repeated StreamingRecognitionResult results = 2;
// *Output-only* Indicates the lowest index in the `results` array that has
// changed. The repeated `StreamingRecognitionResult` results overwrite past
// results at this index and higher.
int32 result_index = 3;
// *Output-only* Indicates the type of endpointer event.
EndpointerType endpointer_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`).
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;
}
// 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`).
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 even set, in
// any of the results.
// The default of 0.0 is a sentinel value indicating `confidence` was not set.
float confidence = 2;
}

View File

@@ -0,0 +1,658 @@
// 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.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/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
// [audio limits](https://cloud.google.com/speech/limits#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;
// *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 = 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* A means to provide context to assist the speech recognition.
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* 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.
// You must also set the `model` field to a valid, enhanced model. If
// `use_enhanced` is set to true and the `model` field is not set, then
// `use_enhanced` is ignored. 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 the audio logging using
// instructions in the [alpha documentation](/speech/data-sharing). 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](https://cloud.google.com/speech/limits#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
// [audio limits](https://cloud.google.com/speech/limits#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`. 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;
}
// 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;
}
// 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;
}

View File

@@ -0,0 +1,334 @@
// 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;
}

View File

@@ -0,0 +1,199 @@
// 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 {
}

View File

@@ -0,0 +1,850 @@
// 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.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";
// 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](/cloud-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](/cloud-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](/cloud-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](/cloud-tasks/pdfs/managing-cloud-tasks-scaling-risks-2017-06-05.pdf).
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](/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](/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.
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), this
// 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](/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](/iam/) permission on the
// [Task][google.cloud.tasks.v2beta2.Task] resource.
Task.View response_view = 2;
// Sort order used for the query. The only fields supported for sorting
// are `schedule_time` and `pull_message.tag`. All results will be
// returned in approximately ascending order. The default ordering is by
// `schedule_time`.
string order_by = 3;
// 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](/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](/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 maximum that can be
// requested 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](/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](/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](/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](/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](/iam/) permission on the
// [Task][google.cloud.tasks.v2beta2.Task] resource.
Task.View response_view = 2;
}

View File

@@ -0,0 +1,357 @@
// 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.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](/appengine/docs/python/config/queueref) or
// [queue.xml](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;
}
// 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](/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.
//
// Caller-specified and required in [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue],
// after which it becomes output only.
string name = 1;
// The queue's target.
//
// The target applies to all tasks in the queue.
//
// 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.
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](/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](/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](/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, 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](/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](/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](/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](/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](/appengine/docs/standard/python/config/queueref#retry_parameters).
google.protobuf.Duration max_retry_duration = 3;
// A task will be [scheduled](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](/appengine/docs/standard/python/config/queueref#retry_parameters).
google.protobuf.Duration min_backoff = 4;
// A task will be [scheduled](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](/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](/appengine/docs/standard/python/config/queueref#retry_parameters).
int32 max_doublings = 6;
}

View File

@@ -0,0 +1,353 @@
// 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.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](/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`](/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`](/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](/appengine/docs/standard/python/how-requests-are-routed)
// and how routing is affected by
// [dispatch files](/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](/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](/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](/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](/appengine/docs/python/an-overview-of-app-engine),
// [Microservices Architecture on Google App Engine](/appengine/docs/python/microservices-on-app-engine),
// [App Engine Standard request routing](/appengine/docs/standard/python/how-requests-are-routed),
// and [App Engine Flex request routing](/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 ("default").
//
// 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 ("default").
//
// 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](/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](/appengine/docs/standard/python/how-requests-are-routed)
// and [App Engine Flex request routing](/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](/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.
//
// When [service][google.cloud.tasks.v2beta2.AppEngineRouting.service] is "default",
// [version][google.cloud.tasks.v2beta2.AppEngineRouting.version] is "default", and
// [instance][google.cloud.tasks.v2beta2.AppEngineRouting.instance] is empty,
// [host][google.cloud.tasks.v2beta2.AppEngineRouting.host] is shortened to just the
// `application_domain_name`.
//
// 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;
}

View File

@@ -0,0 +1,180 @@
// 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.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;
}
// 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](/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.
//
// Optionally caller-specified in [CreateTask][google.cloud.tasks.v2beta2.CloudTasks.CreateTask].
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.PullTaskTarget).
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.PullTaskTarget).
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.PullTaskTarget).
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;
}

View File

@@ -0,0 +1,225 @@
// 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.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][google.cloud.texttospeech.v1.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;
}
// 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;
}

View File

@@ -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;
}

View File

@@ -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.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 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;
}

View File

@@ -0,0 +1,340 @@
// 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;
}

View File

@@ -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.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;
}

View File

@@ -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;
}

View File

@@ -0,0 +1,68 @@
// 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.v1;
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";
// 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;
}

View File

@@ -0,0 +1,766 @@
// 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.v1;
import "google/api/annotations.proto";
import "google/cloud/vision/v1/geometry.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/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";
// 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;
}
// 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
// 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;
}

View File

@@ -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.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";
// 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 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;
}

View File

@@ -0,0 +1,105 @@
// 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.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";
// 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;
}

View File

@@ -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;
}

View File

@@ -0,0 +1,591 @@
// 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;
}

View File

@@ -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;
}

View File

@@ -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;
}

View File

@@ -0,0 +1,68 @@
// 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;
}

View File

@@ -0,0 +1,764 @@
// 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;
}

View File

@@ -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;
}

View File

@@ -0,0 +1,105 @@
// 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;
}

View File

@@ -0,0 +1,43 @@
// 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;
}

View File

@@ -0,0 +1,141 @@
// 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;
}

View File

@@ -0,0 +1,62 @@
// 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;
}

View File

@@ -0,0 +1,38 @@
// 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;
}

View File

@@ -0,0 +1,150 @@
// 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;
}

View File

@@ -0,0 +1,108 @@
// 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;
}

View File

@@ -0,0 +1,346 @@
// 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;
}