diff --git a/google/cloud/dialogflow/cx/v3/BUILD.bazel b/google/cloud/dialogflow/cx/v3/BUILD.bazel index caa0cca9..cd676a23 100644 --- a/google/cloud/dialogflow/cx/v3/BUILD.bazel +++ b/google/cloud/dialogflow/cx/v3/BUILD.bazel @@ -25,6 +25,7 @@ proto_library( "audio_config.proto", "entity_type.proto", "environment.proto", + "experiment.proto", "flow.proto", "fulfillment.proto", "intent.proto", @@ -89,6 +90,7 @@ java_gapic_library( srcs = [":cx_proto_with_info"], gapic_yaml = "dialogflow_gapic.yaml", grpc_service_config = "dialogflow_grpc_service_config.json", + package = "google.cloud.dialogflow.cx.v3", test_deps = [ ":cx_java_grpc", ], @@ -103,6 +105,7 @@ java_gapic_test( "com.google.cloud.dialogflow.cx.v3.AgentsClientTest", "com.google.cloud.dialogflow.cx.v3.EntityTypesClientTest", "com.google.cloud.dialogflow.cx.v3.EnvironmentsClientTest", + "com.google.cloud.dialogflow.cx.v3.ExperimentsClientTest", "com.google.cloud.dialogflow.cx.v3.FlowsClientTest", "com.google.cloud.dialogflow.cx.v3.IntentsClientTest", "com.google.cloud.dialogflow.cx.v3.PagesClientTest", @@ -187,7 +190,6 @@ go_gapic_assembly_pkg( ############################################################################## # Python ############################################################################## - load( "@com_google_googleapis_imports//:imports.bzl", "py_gapic_assembly_pkg", diff --git a/google/cloud/dialogflow/cx/v3/dialogflow_grpc_service_config.json b/google/cloud/dialogflow/cx/v3/dialogflow_grpc_service_config.json index 42fd7664..e5442309 100644 --- a/google/cloud/dialogflow/cx/v3/dialogflow_grpc_service_config.json +++ b/google/cloud/dialogflow/cx/v3/dialogflow_grpc_service_config.json @@ -11,6 +11,9 @@ { "service": "google.cloud.dialogflow.cx.v3.Environments" }, + { + "service": "google.cloud.dialogflow.cx.v3.Experiments" + }, { "service": "google.cloud.dialogflow.cx.v3.Flows" }, @@ -32,6 +35,9 @@ { "service": "google.cloud.dialogflow.cx.v3.SessionEntityTypes" }, + { + "service": "google.cloud.dialogflow.cx.v3.TestCases" + }, { "service": "google.cloud.dialogflow.cx.v3.TransitionRouteGroups" }, @@ -40,6 +46,12 @@ }, { "service": "google.cloud.dialogflow.cx.v3.Webhooks" + }, + { + "service": "google.cloud.dialogflow.cx.v3.Documents" + }, + { + "service": "google.cloud.dialogflow.cx.v3.KnowledgeBases" } ], "timeout": "60s", diff --git a/google/cloud/dialogflow/cx/v3/dialogflow_v3.yaml b/google/cloud/dialogflow/cx/v3/dialogflow_v3.yaml index bfe660a9..4a55cca9 100644 --- a/google/cloud/dialogflow/cx/v3/dialogflow_v3.yaml +++ b/google/cloud/dialogflow/cx/v3/dialogflow_v3.yaml @@ -7,6 +7,7 @@ apis: - name: google.cloud.dialogflow.cx.v3.Agents - name: google.cloud.dialogflow.cx.v3.EntityTypes - name: google.cloud.dialogflow.cx.v3.Environments +- name: google.cloud.dialogflow.cx.v3.Experiments - name: google.cloud.dialogflow.cx.v3.Flows - name: google.cloud.dialogflow.cx.v3.Intents - name: google.cloud.dialogflow.cx.v3.Pages @@ -51,6 +52,8 @@ backend: deadline: 60.0 - selector: 'google.cloud.dialogflow.cx.v3.Environments.*' deadline: 60.0 + - selector: 'google.cloud.dialogflow.cx.v3.Experiments.*' + deadline: 60.0 - selector: 'google.cloud.dialogflow.cx.v3.Flows.*' deadline: 60.0 - selector: 'google.cloud.dialogflow.cx.v3.Intents.*' @@ -95,6 +98,11 @@ authentication: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform, https://www.googleapis.com/auth/dialogflow + - selector: 'google.cloud.dialogflow.cx.v3.Experiments.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform, + https://www.googleapis.com/auth/dialogflow - selector: 'google.cloud.dialogflow.cx.v3.Flows.*' oauth: canonical_scopes: |- diff --git a/google/cloud/dialogflow/cx/v3/experiment.proto b/google/cloud/dialogflow/cx/v3/experiment.proto new file mode 100644 index 00000000..92f48189 --- /dev/null +++ b/google/cloud/dialogflow/cx/v3/experiment.proto @@ -0,0 +1,415 @@ +// Copyright 2020 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.dialogflow.cx.v3; + +import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.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 csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3"; +option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3;cx"; +option java_multiple_files = true; +option java_outer_classname = "ExperimentProto"; +option java_package = "com.google.cloud.dialogflow.cx.v3"; +option objc_class_prefix = "DF"; + +// Service for managing [Experiments][google.cloud.dialogflow.cx.v3.Experiment]. +service Experiments { + option (google.api.default_host) = "dialogflow.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform," + "https://www.googleapis.com/auth/dialogflow"; + + // Returns the list of all experiments in the specified [Environment][google.cloud.dialogflow.cx.v3.Environment]. + rpc ListExperiments(ListExperimentsRequest) returns (ListExperimentsResponse) { + option (google.api.http) = { + get: "/v3/{parent=projects/*/locations/*/agents/*/environments/*}/experiments" + }; + option (google.api.method_signature) = "parent"; + } + + // Retrieves the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment]. + rpc GetExperiment(GetExperimentRequest) returns (Experiment) { + option (google.api.http) = { + get: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Creates an [Experiment][google.cloud.dialogflow.cx.v3.Experiment] in the specified [Environment][google.cloud.dialogflow.cx.v3.Environment]. + rpc CreateExperiment(CreateExperimentRequest) returns (Experiment) { + option (google.api.http) = { + post: "/v3/{parent=projects/*/locations/*/agents/*/environments/*}/experiments" + body: "experiment" + }; + option (google.api.method_signature) = "parent,experiment"; + } + + // Updates the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment]. + rpc UpdateExperiment(UpdateExperimentRequest) returns (Experiment) { + option (google.api.http) = { + patch: "/v3/{experiment.name=projects/*/locations/*/agents/*/environments/*/experiments/*}" + body: "experiment" + }; + option (google.api.method_signature) = "experiment,update_mask"; + } + + // Deletes the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment]. + rpc DeleteExperiment(DeleteExperimentRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Starts the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment]. This rpc only changes the state of + // experiment from PENDING to RUNNING. + rpc StartExperiment(StartExperimentRequest) returns (Experiment) { + option (google.api.http) = { + post: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}:start" + body: "*" + }; + option (google.api.method_signature) = "name"; + } + + // Stops the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment]. This rpc only changes the state of + // experiment from RUNNING to DONE. + rpc StopExperiment(StopExperimentRequest) returns (Experiment) { + option (google.api.http) = { + post: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}:stop" + body: "*" + }; + option (google.api.method_signature) = "name"; + } +} + +// Represents an experiment in an environment. +// Next ID: 13 +message Experiment { + option (google.api.resource) = { + type: "dialogflow.googleapis.com/Experiment" + pattern: "projects/{project}/locations/{location}/agents/{agent}/environments/{environment}/experiments/{experiment}" + }; + + // Definition of the experiment. + // Next ID: 3 + message Definition { + // The condition defines which subset of sessions are selected for + // this experiment. If not specified, all sessions are eligible. E.g. + // "query_input.language_code=en" See the [conditions + // reference](https://cloud.google.com/dialogflow/cx/docs/reference/condition). + string condition = 1; + + // The variants of the experiment. We currently only support single variant + // experiment. + oneof variants { + // The flow versions as the variants of this experiment. + VersionVariants version_variants = 2; + } + } + + // The inference result which includes an objective metric to optimize and the + // confidence interval. + message Result { + // A confidence interval is a range of possible values for the experiment + // objective you are trying to measure. + message ConfidenceInterval { + // The confidence level used to construct the interval, i.e. there is X% + // chance that the true value is within this interval. + double confidence_level = 1; + + // The percent change between an experiment metric's value and the value + // for its control. + double ratio = 2; + + // Lower bound of the interval. + double lower_bound = 3; + + // Upper bound of the interval. + double upper_bound = 4; + } + + // Metric and corresponding confidence intervals. + message Metric { + // The type of the metric. + MetricType type = 1; + + // The actual value of the metric. + oneof value { + // Ratio value of a metric. + double ratio = 2; + } + + // The probability that the treatment is better than all other treatments + // in the experiment + ConfidenceInterval confidence_interval = 3; + } + + // Version variant and associated metrics. + message VersionMetrics { + // The name of the flow [Version][google.cloud.dialogflow.cx.v3.Version]. + // Format: `projects//locations//agents//flows//versions/`. + string version = 1 [(google.api.resource_reference) = { + type: "dialogflow.googleapis.com/Version" + }]; + + // The metrics and corresponding confidence intervals in the inference + // result. + repeated Metric metrics = 2; + + // Number of sessions that were allocated to this version. + int32 session_count = 3; + } + + // Types of metric for Dialogflow experiment. + enum MetricType { + // Metric unspecified. + METRIC_UNSPECIFIED = 0; + + // Percentage of contained sessions without user calling back in 24 hours. + CONTAINED_SESSION_NO_CALLBACK_RATE = 1; + + // Percentage of sessions that were handed to a human agent. + LIVE_AGENT_HANDOFF_RATE = 2; + + // Percentage of sessions with the same user calling back. + CALLBACK_SESSION_RATE = 3; + + // Percentage of sessions where user hung up. + ABANDONED_SESSION_RATE = 4; + + // Percentage of sessions reached Dialogflow 'END_PAGE' or + // 'END_SESSION'. + SESSION_END_RATE = 5; + } + + // Version variants and metrics. + repeated VersionMetrics version_metrics = 1; + + // The last time the experiment's stats data was updated. Will have default + // value if stats have never been computed for this experiment. + google.protobuf.Timestamp last_update_time = 2; + } + + // The state of the experiment. + enum State { + // State unspecified. + STATE_UNSPECIFIED = 0; + + // The experiment is created but not started yet. + DRAFT = 1; + + // The experiment is running. + RUNNING = 2; + + // The experiment is done. + DONE = 3; + } + + // The name of the experiment. + // Format: projects//locations//agents//environments//experiments/.. + string name = 1; + + // Required. The human-readable name of the experiment (unique in an environment). Limit + // of 64 characters. + string display_name = 2 [(google.api.field_behavior) = REQUIRED]; + + // The human-readable description of the experiment. + string description = 3; + + // The current state of the experiment. + // Transition triggered by Expriments.StartExperiment: PENDING->RUNNING. + // Transition triggered by Expriments.CancelExperiment: PENDING->CANCELLED or + // RUNNING->CANCELLED. + State state = 4; + + // The definition of the experiment. + Definition definition = 5; + + // Inference result of the experiment. + Result result = 6; + + // Creation time of this experiment. + google.protobuf.Timestamp create_time = 7; + + // Start time of this experiment. + google.protobuf.Timestamp start_time = 8; + + // End time of this experiment. + google.protobuf.Timestamp end_time = 9; + + // Last update time of this experiment. + google.protobuf.Timestamp last_update_time = 10; + + // Maximum number of days to run the experiment. + google.protobuf.Duration experiment_length = 11; + + // The history of updates to the experiment variants. + repeated VariantsHistory variants_history = 12; +} + +// A list of flow version variants. +message VersionVariants { + // A single flow version with specified traffic allocation. + message Variant { + // The name of the flow version. + // Format: `projects//locations//agents//flows//versions/`. + string version = 1; + + // Percentage of the traffic which should be routed to this + // version of flow. Traffic allocation for a single flow must sum up to 1.0. + float traffic_allocation = 2; + + // Whether the variant is for the control group. + bool is_control_group = 3; + } + + // A list of flow version variants. + repeated Variant variants = 1; +} + +// The history of variants update. +message VariantsHistory { + // The variants updated. We currently only support single variant + // experiment. + oneof variants { + // The flow versions as the variants. + VersionVariants version_variants = 1; + } + + // Update time of the variants. + google.protobuf.Timestamp update_time = 2; +} + +// The request message for [Experiments.ListExperiments][google.cloud.dialogflow.cx.v3.Experiments.ListExperiments]. +message ListExperimentsRequest { + // Required. The [Environment][google.cloud.dialogflow.cx.v3.Environment] to list all environments for. + // Format: `projects//locations//agents//environments/`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + child_type: "dialogflow.googleapis.com/Experiment" + } + ]; + + // The maximum number of items to return in a single page. By default 20 and + // at most 100. + int32 page_size = 2; + + // The next_page_token value returned from a previous list request. + string page_token = 3; +} + +// The response message for [Experiments.ListExperiments][google.cloud.dialogflow.cx.v3.Experiments.ListExperiments]. +message ListExperimentsResponse { + // The list of experiments. There will be a maximum number of items + // returned based on the page_size field in the request. The list may in some + // cases be empty or contain fewer entries than page_size even if this isn't + // the last page. + repeated Experiment experiments = 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 [Experiments.GetExperiment][google.cloud.dialogflow.cx.v3.Experiments.GetExperiment]. +message GetExperimentRequest { + // Required. The name of the [Environment][google.cloud.dialogflow.cx.v3.Environment]. + // Format: `projects//locations//agents//environments//experiments/`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "dialogflow.googleapis.com/Experiment" + } + ]; +} + +// The request message for [Experiments.CreateExperiment][google.cloud.dialogflow.cx.v3.Experiments.CreateExperiment]. +message CreateExperimentRequest { + // Required. The [Agent][google.cloud.dialogflow.cx.v3.Agent] to create an [Environment][google.cloud.dialogflow.cx.v3.Environment] for. + // Format: `projects//locations//agents//environments/`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + child_type: "dialogflow.googleapis.com/Experiment" + } + ]; + + // Required. The experiment to create. + Experiment experiment = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// The request message for [Experiments.UpdateExperiment][google.cloud.dialogflow.cx.v3.Experiments.UpdateExperiment]. +message UpdateExperimentRequest { + // Required. The experiment to update. + Experiment experiment = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The mask to control which fields get updated. + google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// The request message for [Experiments.DeleteExperiment][google.cloud.dialogflow.cx.v3.Experiments.DeleteExperiment]. +message DeleteExperimentRequest { + // Required. The name of the [Environment][google.cloud.dialogflow.cx.v3.Environment] to delete. + // Format: `projects//locations//agents//environments//experiments/`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "dialogflow.googleapis.com/Experiment" + } + ]; +} + +// The request message for [Experiments.StartExperiment][google.cloud.dialogflow.cx.v3.Experiments.StartExperiment]. +message StartExperimentRequest { + // Required. Resource name of the experiment to start. + // Format: `projects//locations//agents//environments//experiments/`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "dialogflow.googleapis.com/Experiment" + } + ]; +} + +// The request message for [Experiments.StopExperiment][google.cloud.dialogflow.cx.v3.Experiments.StopExperiment]. +message StopExperimentRequest { + // Required. Resource name of the experiment to stop. + // Format: `projects//locations//agents//environments//experiments/`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "dialogflow.googleapis.com/Experiment" + } + ]; +} diff --git a/google/cloud/dialogflow/cx/v3/session.proto b/google/cloud/dialogflow/cx/v3/session.proto index f2e8968b..55de80b9 100644 --- a/google/cloud/dialogflow/cx/v3/session.proto +++ b/google/cloud/dialogflow/cx/v3/session.proto @@ -57,6 +57,10 @@ service Sessions { // as a result. This method is not idempotent, because it may cause session // entity types to be updated, which in turn might affect results of future // queries. + // + // Note: Always use agent versions for production traffic. + // See [Versions and + // environments](https://cloud.google.com/dialogflow/cx/docs/concept/version). rpc DetectIntent(DetectIntentRequest) returns (DetectIntentResponse) { option (google.api.http) = { post: "/v3/{session=projects/*/locations/*/agents/*/sessions/*}:detectIntent" @@ -71,6 +75,10 @@ service Sessions { // 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). + // + // Note: Always use agent versions for production traffic. + // See [Versions and + // environments](https://cloud.google.com/dialogflow/cx/docs/concept/version). rpc StreamingDetectIntent(stream StreamingDetectIntentRequest) returns (stream StreamingDetectIntentResponse) { } @@ -116,6 +124,10 @@ message DetectIntentRequest { // // For more information, see the [sessions // guide](https://cloud.google.com/dialogflow/cx/docs/concept/session). + // + // Note: Always use agent versions for production traffic. + // See [Versions and + // environments](https://cloud.google.com/dialogflow/cx/docs/concept/version). string session = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -201,6 +213,10 @@ message StreamingDetectIntentRequest { // // For more information, see the [sessions // guide](https://cloud.google.com/dialogflow/cx/docs/concept/session). + // + // Note: Always use agent versions for production traffic. + // See [Versions and + // environments](https://cloud.google.com/dialogflow/cx/docs/concept/version). string session = 1 [(google.api.resource_reference) = { type: "dialogflow.googleapis.com/Session" }]; @@ -364,7 +380,8 @@ message QueryParameters { // - MapKey value: parameter name // - MapValue type: // - If parameter's entity type is a composite entity: map - // - Else: string or number, depending on parameter value type + // - Else: depending on parameter value type, could be one of string, + // number, boolean, null, list or map // - MapValue value: // - If parameter's entity type is a composite entity: // map from composite entity property names to property values @@ -374,6 +391,16 @@ message QueryParameters { // Configures whether sentiment analysis should be performed. If not // provided, sentiment analysis is not performed. bool analyze_query_text_sentiment = 8; + + // This field can be used to pass HTTP headers for a webhook + // call. These headers will be sent to webhook along with the headers that + // have been configured through Dialogflow web console. The headers defined + // within this field will overwrite the headers configured through Dialogflow + // console if there is a conflict. Header names are case-insensitive. + // Google's specified headers are not allowed. Including: "Host", + // "Content-Length", "Connection", "From", "User-Agent", "Accept-Encoding", + // "If-Modified-Since", "If-None-Match", "X-Forwarded-For", etc. + map webhook_headers = 10; } // Represents the query input. It can contain one of: @@ -449,7 +476,8 @@ message QueryResult { // - MapKey value: parameter name // - MapValue type: // - If parameter's entity type is a composite entity: map - // - Else: string or number, depending on parameter value type + // - Else: depending on parameter value type, could be one of string, + // number, boolean, null, list or map // - MapValue value: // - If parameter's entity type is a composite entity: // map from composite entity property names to property values @@ -600,7 +628,8 @@ message Match { // - MapKey value: parameter name // - MapValue type: // - If parameter's entity type is a composite entity: map - // - Else: string or number, depending on parameter value type + // - Else: depending on parameter value type, could be one of string, + // number, boolean, null, list or map // - MapValue value: // - If parameter's entity type is a composite entity: // map from composite entity property names to property values