1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.dialogflow.cx.v3; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/cloud/dialogflow/cx/v3/test_case.proto"; 24import "google/cloud/dialogflow/cx/v3/webhook.proto"; 25import "google/longrunning/operations.proto"; 26import "google/protobuf/empty.proto"; 27import "google/protobuf/field_mask.proto"; 28import "google/protobuf/struct.proto"; 29import "google/protobuf/timestamp.proto"; 30 31option cc_enable_arenas = true; 32option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3"; 33option go_package = "cloud.google.com/go/dialogflow/cx/apiv3/cxpb;cxpb"; 34option java_multiple_files = true; 35option java_outer_classname = "EnvironmentProto"; 36option java_package = "com.google.cloud.dialogflow.cx.v3"; 37option objc_class_prefix = "DF"; 38option ruby_package = "Google::Cloud::Dialogflow::CX::V3"; 39 40// Service for managing 41// [Environments][google.cloud.dialogflow.cx.v3.Environment]. 42service Environments { 43 option (google.api.default_host) = "dialogflow.googleapis.com"; 44 option (google.api.oauth_scopes) = 45 "https://www.googleapis.com/auth/cloud-platform," 46 "https://www.googleapis.com/auth/dialogflow"; 47 48 // Returns the list of all environments in the specified 49 // [Agent][google.cloud.dialogflow.cx.v3.Agent]. 50 rpc ListEnvironments(ListEnvironmentsRequest) 51 returns (ListEnvironmentsResponse) { 52 option (google.api.http) = { 53 get: "/v3/{parent=projects/*/locations/*/agents/*}/environments" 54 }; 55 option (google.api.method_signature) = "parent"; 56 } 57 58 // Retrieves the specified 59 // [Environment][google.cloud.dialogflow.cx.v3.Environment]. 60 rpc GetEnvironment(GetEnvironmentRequest) returns (Environment) { 61 option (google.api.http) = { 62 get: "/v3/{name=projects/*/locations/*/agents/*/environments/*}" 63 }; 64 option (google.api.method_signature) = "name"; 65 } 66 67 // Creates an [Environment][google.cloud.dialogflow.cx.v3.Environment] in the 68 // specified [Agent][google.cloud.dialogflow.cx.v3.Agent]. 69 // 70 // This method is a [long-running 71 // operation](https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation). 72 // The returned `Operation` type has the following method-specific fields: 73 // 74 // - `metadata`: An empty [Struct 75 // message](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct) 76 // - `response`: [Environment][google.cloud.dialogflow.cx.v3.Environment] 77 rpc CreateEnvironment(CreateEnvironmentRequest) 78 returns (google.longrunning.Operation) { 79 option (google.api.http) = { 80 post: "/v3/{parent=projects/*/locations/*/agents/*}/environments" 81 body: "environment" 82 }; 83 option (google.api.method_signature) = "parent,environment"; 84 option (google.longrunning.operation_info) = { 85 response_type: "Environment" 86 metadata_type: "google.protobuf.Struct" 87 }; 88 } 89 90 // Updates the specified 91 // [Environment][google.cloud.dialogflow.cx.v3.Environment]. 92 // 93 // This method is a [long-running 94 // operation](https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation). 95 // The returned `Operation` type has the following method-specific fields: 96 // 97 // - `metadata`: An empty [Struct 98 // message](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct) 99 // - `response`: [Environment][google.cloud.dialogflow.cx.v3.Environment] 100 rpc UpdateEnvironment(UpdateEnvironmentRequest) 101 returns (google.longrunning.Operation) { 102 option (google.api.http) = { 103 patch: "/v3/{environment.name=projects/*/locations/*/agents/*/environments/*}" 104 body: "environment" 105 }; 106 option (google.api.method_signature) = "environment,update_mask"; 107 option (google.longrunning.operation_info) = { 108 response_type: "Environment" 109 metadata_type: "google.protobuf.Struct" 110 }; 111 } 112 113 // Deletes the specified 114 // [Environment][google.cloud.dialogflow.cx.v3.Environment]. 115 rpc DeleteEnvironment(DeleteEnvironmentRequest) 116 returns (google.protobuf.Empty) { 117 option (google.api.http) = { 118 delete: "/v3/{name=projects/*/locations/*/agents/*/environments/*}" 119 }; 120 option (google.api.method_signature) = "name"; 121 } 122 123 // Looks up the history of the specified 124 // [Environment][google.cloud.dialogflow.cx.v3.Environment]. 125 rpc LookupEnvironmentHistory(LookupEnvironmentHistoryRequest) 126 returns (LookupEnvironmentHistoryResponse) { 127 option (google.api.http) = { 128 get: "/v3/{name=projects/*/locations/*/agents/*/environments/*}:lookupEnvironmentHistory" 129 }; 130 option (google.api.method_signature) = "name"; 131 } 132 133 // Kicks off a continuous test under the specified 134 // [Environment][google.cloud.dialogflow.cx.v3.Environment]. 135 // 136 // This method is a [long-running 137 // operation](https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation). 138 // The returned `Operation` type has the following method-specific fields: 139 // 140 // - `metadata`: 141 // [RunContinuousTestMetadata][google.cloud.dialogflow.cx.v3.RunContinuousTestMetadata] 142 // - `response`: 143 // [RunContinuousTestResponse][google.cloud.dialogflow.cx.v3.RunContinuousTestResponse] 144 rpc RunContinuousTest(RunContinuousTestRequest) 145 returns (google.longrunning.Operation) { 146 option (google.api.http) = { 147 post: "/v3/{environment=projects/*/locations/*/agents/*/environments/*}:runContinuousTest" 148 body: "*" 149 }; 150 option (google.longrunning.operation_info) = { 151 response_type: "RunContinuousTestResponse" 152 metadata_type: "RunContinuousTestMetadata" 153 }; 154 } 155 156 // Fetches a list of continuous test results for a given environment. 157 rpc ListContinuousTestResults(ListContinuousTestResultsRequest) 158 returns (ListContinuousTestResultsResponse) { 159 option (google.api.http) = { 160 get: "/v3/{parent=projects/*/locations/*/agents/*/environments/*}/continuousTestResults" 161 }; 162 option (google.api.method_signature) = "parent"; 163 } 164 165 // Deploys a flow to the specified 166 // [Environment][google.cloud.dialogflow.cx.v3.Environment]. 167 // 168 // This method is a [long-running 169 // operation](https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation). 170 // The returned `Operation` type has the following method-specific fields: 171 // 172 // - `metadata`: 173 // [DeployFlowMetadata][google.cloud.dialogflow.cx.v3.DeployFlowMetadata] 174 // - `response`: 175 // [DeployFlowResponse][google.cloud.dialogflow.cx.v3.DeployFlowResponse] 176 rpc DeployFlow(DeployFlowRequest) returns (google.longrunning.Operation) { 177 option (google.api.http) = { 178 post: "/v3/{environment=projects/*/locations/*/agents/*/environments/*}:deployFlow" 179 body: "*" 180 }; 181 option (google.longrunning.operation_info) = { 182 response_type: "DeployFlowResponse" 183 metadata_type: "DeployFlowMetadata" 184 }; 185 } 186} 187 188// Represents an environment for an agent. You can create multiple versions 189// of your agent and publish them to separate environments. When you edit an 190// agent, you are editing the draft agent. At any point, you can save the draft 191// agent as an agent version, which is an immutable snapshot of your agent. When 192// you save the draft agent, it is published to the default environment. When 193// you create agent versions, you can publish them to custom environments. You 194// can create a variety of custom environments for testing, development, 195// production, etc. 196message Environment { 197 option (google.api.resource) = { 198 type: "dialogflow.googleapis.com/Environment" 199 pattern: "projects/{project}/locations/{location}/agents/{agent}/environments/{environment}" 200 }; 201 202 // Configuration for the version. 203 message VersionConfig { 204 // Required. Format: projects/<Project ID>/locations/<Location 205 // ID>/agents/<Agent ID>/flows/<Flow ID>/versions/<Version ID>. 206 string version = 1 [ 207 (google.api.field_behavior) = REQUIRED, 208 (google.api.resource_reference) = { 209 type: "dialogflow.googleapis.com/Version" 210 } 211 ]; 212 } 213 214 // The configuration for continuous tests. 215 message TestCasesConfig { 216 // A list of test case names to run. They should be under the same agent. 217 // Format of each test case name: `projects/<Project ID>/locations/ 218 // <Location ID>/agents/<AgentID>/testCases/<TestCase ID>` 219 repeated string test_cases = 1 [(google.api.resource_reference) = { 220 type: "dialogflow.googleapis.com/TestCase" 221 }]; 222 223 // Whether to run test cases in 224 // [TestCasesConfig.test_cases][google.cloud.dialogflow.cx.v3.Environment.TestCasesConfig.test_cases] 225 // periodically. Default false. If set to true, run once a day. 226 bool enable_continuous_run = 2; 227 228 // Whether to run test cases in 229 // [TestCasesConfig.test_cases][google.cloud.dialogflow.cx.v3.Environment.TestCasesConfig.test_cases] 230 // before deploying a flow version to the environment. Default false. 231 bool enable_predeployment_run = 3; 232 } 233 234 // Configuration for webhooks. 235 message WebhookConfig { 236 // The list of webhooks to override for the agent environment. The webhook 237 // must exist in the agent. You can override fields in 238 // [`generic_web_service`][google.cloud.dialogflow.cx.v3.Webhook.generic_web_service] 239 // and 240 // [`service_directory`][google.cloud.dialogflow.cx.v3.Webhook.service_directory]. 241 repeated Webhook webhook_overrides = 1; 242 } 243 244 // The name of the environment. 245 // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent 246 // ID>/environments/<Environment ID>`. 247 string name = 1; 248 249 // Required. The human-readable name of the environment (unique in an agent). 250 // Limit of 64 characters. 251 string display_name = 2 [(google.api.field_behavior) = REQUIRED]; 252 253 // The human-readable description of the environment. The maximum length is 254 // 500 characters. If exceeded, the request is rejected. 255 string description = 3; 256 257 // A list of configurations for flow versions. You should include version 258 // configs for all flows that are reachable from [`Start 259 // Flow`][Agent.start_flow] in the agent. Otherwise, an error will be 260 // returned. 261 repeated VersionConfig version_configs = 6; 262 263 // Output only. Update time of this environment. 264 google.protobuf.Timestamp update_time = 5 265 [(google.api.field_behavior) = OUTPUT_ONLY]; 266 267 // The test cases config for continuous tests of this environment. 268 TestCasesConfig test_cases_config = 7; 269 270 // The webhook configuration for this environment. 271 WebhookConfig webhook_config = 10; 272} 273 274// The request message for 275// [Environments.ListEnvironments][google.cloud.dialogflow.cx.v3.Environments.ListEnvironments]. 276message ListEnvironmentsRequest { 277 // Required. The [Agent][google.cloud.dialogflow.cx.v3.Agent] to list all 278 // environments for. Format: `projects/<Project ID>/locations/<Location 279 // ID>/agents/<Agent ID>`. 280 string parent = 1 [ 281 (google.api.field_behavior) = REQUIRED, 282 (google.api.resource_reference) = { 283 child_type: "dialogflow.googleapis.com/Environment" 284 } 285 ]; 286 287 // The maximum number of items to return in a single page. By default 20 and 288 // at most 100. 289 int32 page_size = 2; 290 291 // The next_page_token value returned from a previous list request. 292 string page_token = 3; 293} 294 295// The response message for 296// [Environments.ListEnvironments][google.cloud.dialogflow.cx.v3.Environments.ListEnvironments]. 297message ListEnvironmentsResponse { 298 // The list of environments. There will be a maximum number of items 299 // returned based on the page_size field in the request. The list may in some 300 // cases be empty or contain fewer entries than page_size even if this isn't 301 // the last page. 302 repeated Environment environments = 1; 303 304 // Token to retrieve the next page of results, or empty if there are no more 305 // results in the list. 306 string next_page_token = 2; 307} 308 309// The request message for 310// [Environments.GetEnvironment][google.cloud.dialogflow.cx.v3.Environments.GetEnvironment]. 311message GetEnvironmentRequest { 312 // Required. The name of the 313 // [Environment][google.cloud.dialogflow.cx.v3.Environment]. Format: 314 // `projects/<Project ID>/locations/<Location ID>/agents/<Agent 315 // ID>/environments/<Environment ID>`. 316 string name = 1 [ 317 (google.api.field_behavior) = REQUIRED, 318 (google.api.resource_reference) = { 319 type: "dialogflow.googleapis.com/Environment" 320 } 321 ]; 322} 323 324// The request message for 325// [Environments.CreateEnvironment][google.cloud.dialogflow.cx.v3.Environments.CreateEnvironment]. 326message CreateEnvironmentRequest { 327 // Required. The [Agent][google.cloud.dialogflow.cx.v3.Agent] to create an 328 // [Environment][google.cloud.dialogflow.cx.v3.Environment] for. Format: 329 // `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`. 330 string parent = 1 [ 331 (google.api.field_behavior) = REQUIRED, 332 (google.api.resource_reference) = { 333 child_type: "dialogflow.googleapis.com/Environment" 334 } 335 ]; 336 337 // Required. The environment to create. 338 Environment environment = 2 [(google.api.field_behavior) = REQUIRED]; 339} 340 341// The request message for 342// [Environments.UpdateEnvironment][google.cloud.dialogflow.cx.v3.Environments.UpdateEnvironment]. 343message UpdateEnvironmentRequest { 344 // Required. The environment to update. 345 Environment environment = 1 [(google.api.field_behavior) = REQUIRED]; 346 347 // Required. The mask to control which fields get updated. 348 google.protobuf.FieldMask update_mask = 2 349 [(google.api.field_behavior) = REQUIRED]; 350} 351 352// The request message for 353// [Environments.DeleteEnvironment][google.cloud.dialogflow.cx.v3.Environments.DeleteEnvironment]. 354message DeleteEnvironmentRequest { 355 // Required. The name of the 356 // [Environment][google.cloud.dialogflow.cx.v3.Environment] to delete. Format: 357 // `projects/<Project ID>/locations/<Location ID>/agents/<Agent 358 // ID>/environments/<Environment ID>`. 359 string name = 1 [ 360 (google.api.field_behavior) = REQUIRED, 361 (google.api.resource_reference) = { 362 type: "dialogflow.googleapis.com/Environment" 363 } 364 ]; 365} 366 367// The request message for 368// [Environments.LookupEnvironmentHistory][google.cloud.dialogflow.cx.v3.Environments.LookupEnvironmentHistory]. 369message LookupEnvironmentHistoryRequest { 370 // Required. Resource name of the environment to look up the history for. 371 // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent 372 // ID>/environments/<Environment ID>`. 373 string name = 1 [ 374 (google.api.field_behavior) = REQUIRED, 375 (google.api.resource_reference) = { 376 type: "dialogflow.googleapis.com/Environment" 377 } 378 ]; 379 380 // The maximum number of items to return in a single page. By default 100 and 381 // at most 1000. 382 int32 page_size = 2; 383 384 // The next_page_token value returned from a previous list request. 385 string page_token = 3; 386} 387 388// The response message for 389// [Environments.LookupEnvironmentHistory][google.cloud.dialogflow.cx.v3.Environments.LookupEnvironmentHistory]. 390message LookupEnvironmentHistoryResponse { 391 // Represents a list of snapshots for an environment. Time of the snapshots is 392 // stored in 393 // [`update_time`][google.cloud.dialogflow.cx.v3.Environment.update_time]. 394 repeated Environment environments = 1; 395 396 // Token to retrieve the next page of results, or empty if there are no more 397 // results in the list. 398 string next_page_token = 2; 399} 400 401// Represents a result from running a test case in an agent environment. 402message ContinuousTestResult { 403 option (google.api.resource) = { 404 type: "dialogflow.googleapis.com/ContinuousTestResult" 405 pattern: "projects/{project}/locations/{location}/agents/{agent}/environments/{environment}/continuousTestResults/{continuous_test_result}" 406 }; 407 408 // The overall result for a continuous test run in an agent environment. 409 enum AggregatedTestResult { 410 // Not specified. Should never be used. 411 AGGREGATED_TEST_RESULT_UNSPECIFIED = 0; 412 413 // All the tests passed. 414 PASSED = 1; 415 416 // At least one test did not pass. 417 FAILED = 2; 418 } 419 420 // The resource name for the continuous test result. Format: 421 // `projects/<Project ID>/locations/<Location ID>/agents/<Agent 422 // ID>/environments/<Environment 423 // ID>/continuousTestResults/<ContinuousTestResult ID>`. 424 string name = 1; 425 426 // The result of this continuous test run, i.e. whether all the tests in this 427 // continuous test run pass or not. 428 AggregatedTestResult result = 2; 429 430 // A list of individual test case results names in this continuous test run. 431 repeated string test_case_results = 3 [(google.api.resource_reference) = { 432 type: "dialogflow.googleapis.com/TestCaseResult" 433 }]; 434 435 // Time when the continuous testing run starts. 436 google.protobuf.Timestamp run_time = 4; 437} 438 439// The request message for 440// [Environments.RunContinuousTest][google.cloud.dialogflow.cx.v3.Environments.RunContinuousTest]. 441message RunContinuousTestRequest { 442 // Required. Format: `projects/<Project ID>/locations/<Location 443 // ID>/agents/<Agent ID>/environments/<Environment ID>`. 444 string environment = 1 [ 445 (google.api.field_behavior) = REQUIRED, 446 (google.api.resource_reference) = { 447 type: "dialogflow.googleapis.com/Environment" 448 } 449 ]; 450} 451 452// The response message for 453// [Environments.RunContinuousTest][google.cloud.dialogflow.cx.v3.Environments.RunContinuousTest]. 454message RunContinuousTestResponse { 455 // The result for a continuous test run. 456 ContinuousTestResult continuous_test_result = 1; 457} 458 459// Metadata returned for the 460// [Environments.RunContinuousTest][google.cloud.dialogflow.cx.v3.Environments.RunContinuousTest] 461// long running operation. 462message RunContinuousTestMetadata { 463 // The test errors. 464 repeated TestError errors = 1; 465} 466 467// The request message for 468// [Environments.ListContinuousTestResults][google.cloud.dialogflow.cx.v3.Environments.ListContinuousTestResults]. 469message ListContinuousTestResultsRequest { 470 // Required. The environment to list results for. 471 // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>/ 472 // environments/<Environment ID>`. 473 string parent = 1 [ 474 (google.api.field_behavior) = REQUIRED, 475 (google.api.resource_reference) = { 476 child_type: "dialogflow.googleapis.com/ContinuousTestResult" 477 } 478 ]; 479 480 // The maximum number of items to return in a single page. By default 100 and 481 // at most 1000. 482 int32 page_size = 2; 483 484 // The next_page_token value returned from a previous list request. 485 string page_token = 3; 486} 487 488// The response message for [Environments.ListTestCaseResults][]. 489message ListContinuousTestResultsResponse { 490 // The list of continuous test results. 491 repeated ContinuousTestResult continuous_test_results = 1; 492 493 // Token to retrieve the next page of results, or empty if there are no more 494 // results in the list. 495 string next_page_token = 2; 496} 497 498// The request message for 499// [Environments.DeployFlow][google.cloud.dialogflow.cx.v3.Environments.DeployFlow]. 500message DeployFlowRequest { 501 // Required. The environment to deploy the flow to. 502 // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>/ 503 // environments/<Environment ID>`. 504 string environment = 1 [ 505 (google.api.field_behavior) = REQUIRED, 506 (google.api.resource_reference) = { 507 type: "dialogflow.googleapis.com/Environment" 508 } 509 ]; 510 511 // Required. The flow version to deploy. 512 // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>/ 513 // flows/<Flow ID>/versions/<Version ID>`. 514 string flow_version = 2 [ 515 (google.api.field_behavior) = REQUIRED, 516 (google.api.resource_reference) = { 517 type: "dialogflow.googleapis.com/Version" 518 } 519 ]; 520} 521 522// The response message for 523// [Environments.DeployFlow][google.cloud.dialogflow.cx.v3.Environments.DeployFlow]. 524message DeployFlowResponse { 525 // The updated environment where the flow is deployed. 526 Environment environment = 1; 527 528 // The name of the flow version 529 // [Deployment][google.cloud.dialogflow.cx.v3.Deployment]. Format: 530 // `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>/ 531 // environments/<Environment ID>/deployments/<Deployment ID>`. 532 string deployment = 2; 533} 534 535// Metadata returned for the 536// [Environments.DeployFlow][google.cloud.dialogflow.cx.v3.Environments.DeployFlow] 537// long running operation. 538message DeployFlowMetadata { 539 // Errors of running deployment tests. 540 repeated TestError test_errors = 1; 541} 542