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/flow.proto"; 24import "google/longrunning/operations.proto"; 25import "google/protobuf/empty.proto"; 26import "google/protobuf/field_mask.proto"; 27import "google/protobuf/struct.proto"; 28import "google/protobuf/timestamp.proto"; 29 30option cc_enable_arenas = true; 31option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3"; 32option go_package = "cloud.google.com/go/dialogflow/cx/apiv3/cxpb;cxpb"; 33option java_multiple_files = true; 34option java_outer_classname = "VersionProto"; 35option java_package = "com.google.cloud.dialogflow.cx.v3"; 36option objc_class_prefix = "DF"; 37option ruby_package = "Google::Cloud::Dialogflow::CX::V3"; 38 39// Service for managing [Versions][google.cloud.dialogflow.cx.v3.Version]. 40service Versions { 41 option (google.api.default_host) = "dialogflow.googleapis.com"; 42 option (google.api.oauth_scopes) = 43 "https://www.googleapis.com/auth/cloud-platform," 44 "https://www.googleapis.com/auth/dialogflow"; 45 46 // Returns the list of all versions in the specified 47 // [Flow][google.cloud.dialogflow.cx.v3.Flow]. 48 rpc ListVersions(ListVersionsRequest) returns (ListVersionsResponse) { 49 option (google.api.http) = { 50 get: "/v3/{parent=projects/*/locations/*/agents/*/flows/*}/versions" 51 }; 52 option (google.api.method_signature) = "parent"; 53 } 54 55 // Retrieves the specified [Version][google.cloud.dialogflow.cx.v3.Version]. 56 rpc GetVersion(GetVersionRequest) returns (Version) { 57 option (google.api.http) = { 58 get: "/v3/{name=projects/*/locations/*/agents/*/flows/*/versions/*}" 59 }; 60 option (google.api.method_signature) = "name"; 61 } 62 63 // Creates a [Version][google.cloud.dialogflow.cx.v3.Version] in the specified 64 // [Flow][google.cloud.dialogflow.cx.v3.Flow]. 65 // 66 // This method is a [long-running 67 // operation](https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation). 68 // The returned `Operation` type has the following method-specific fields: 69 // 70 // - `metadata`: 71 // [CreateVersionOperationMetadata][google.cloud.dialogflow.cx.v3.CreateVersionOperationMetadata] 72 // - `response`: [Version][google.cloud.dialogflow.cx.v3.Version] 73 rpc CreateVersion(CreateVersionRequest) 74 returns (google.longrunning.Operation) { 75 option (google.api.http) = { 76 post: "/v3/{parent=projects/*/locations/*/agents/*/flows/*}/versions" 77 body: "version" 78 }; 79 option (google.api.method_signature) = "parent,version"; 80 option (google.longrunning.operation_info) = { 81 response_type: "Version" 82 metadata_type: "CreateVersionOperationMetadata" 83 }; 84 } 85 86 // Updates the specified [Version][google.cloud.dialogflow.cx.v3.Version]. 87 rpc UpdateVersion(UpdateVersionRequest) returns (Version) { 88 option (google.api.http) = { 89 patch: "/v3/{version.name=projects/*/locations/*/agents/*/flows/*/versions/*}" 90 body: "version" 91 }; 92 option (google.api.method_signature) = "version,update_mask"; 93 } 94 95 // Deletes the specified [Version][google.cloud.dialogflow.cx.v3.Version]. 96 rpc DeleteVersion(DeleteVersionRequest) returns (google.protobuf.Empty) { 97 option (google.api.http) = { 98 delete: "/v3/{name=projects/*/locations/*/agents/*/flows/*/versions/*}" 99 }; 100 option (google.api.method_signature) = "name"; 101 } 102 103 // Loads resources in the specified version to the draft flow. 104 // 105 // This method is a [long-running 106 // operation](https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation). 107 // The returned `Operation` type has the following method-specific fields: 108 // 109 // - `metadata`: An empty [Struct 110 // message](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct) 111 // - `response`: An [Empty 112 // message](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#empty) 113 rpc LoadVersion(LoadVersionRequest) returns (google.longrunning.Operation) { 114 option (google.api.http) = { 115 post: "/v3/{name=projects/*/locations/*/agents/*/flows/*/versions/*}:load" 116 body: "*" 117 }; 118 option (google.api.method_signature) = "name"; 119 option (google.longrunning.operation_info) = { 120 response_type: "google.protobuf.Empty" 121 metadata_type: "google.protobuf.Struct" 122 }; 123 } 124 125 // Compares the specified base version with target version. 126 rpc CompareVersions(CompareVersionsRequest) 127 returns (CompareVersionsResponse) { 128 option (google.api.http) = { 129 post: "/v3/{base_version=projects/*/locations/*/agents/*/flows/*/versions/*}:compareVersions" 130 body: "*" 131 }; 132 option (google.api.method_signature) = "base_version"; 133 } 134} 135 136// Metadata associated with the long running operation for 137// [Versions.CreateVersion][google.cloud.dialogflow.cx.v3.Versions.CreateVersion]. 138message CreateVersionOperationMetadata { 139 // Name of the created version. 140 // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent 141 // ID>/flows/<Flow ID>/versions/<Version ID>`. 142 string version = 1 [(google.api.resource_reference) = { 143 type: "dialogflow.googleapis.com/Version" 144 }]; 145} 146 147// Represents a version of a flow. 148message Version { 149 option (google.api.resource) = { 150 type: "dialogflow.googleapis.com/Version" 151 pattern: "projects/{project}/locations/{location}/agents/{agent}/flows/{flow}/versions/{version}" 152 }; 153 154 // The state of the version. 155 enum State { 156 // Not specified. This value is not used. 157 STATE_UNSPECIFIED = 0; 158 159 // Version is not ready to serve (e.g. training is running). 160 RUNNING = 1; 161 162 // Training has succeeded and this version is ready to serve. 163 SUCCEEDED = 2; 164 165 // Version training failed. 166 FAILED = 3; 167 } 168 169 // Format: projects/<Project ID>/locations/<Location ID>/agents/<Agent 170 // ID>/flows/<Flow ID>/versions/<Version ID>. Version ID is a self-increasing 171 // number generated by Dialogflow upon version creation. 172 string name = 1; 173 174 // Required. The human-readable name of the version. Limit of 64 characters. 175 string display_name = 2 [(google.api.field_behavior) = REQUIRED]; 176 177 // The description of the version. The maximum length is 500 characters. If 178 // exceeded, the request is rejected. 179 string description = 3; 180 181 // Output only. The NLU settings of the flow at version creation. 182 NluSettings nlu_settings = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; 183 184 // Output only. Create time of the version. 185 google.protobuf.Timestamp create_time = 5 186 [(google.api.field_behavior) = OUTPUT_ONLY]; 187 188 // Output only. The state of this version. This field is read-only and cannot 189 // be set by create and update methods. 190 State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; 191} 192 193// The request message for 194// [Versions.ListVersions][google.cloud.dialogflow.cx.v3.Versions.ListVersions]. 195message ListVersionsRequest { 196 // Required. The [Flow][google.cloud.dialogflow.cx.v3.Flow] to list all 197 // versions for. Format: `projects/<Project ID>/locations/<Location 198 // ID>/agents/<Agent ID>/flows/<Flow ID>`. 199 string parent = 1 [ 200 (google.api.field_behavior) = REQUIRED, 201 (google.api.resource_reference) = { 202 child_type: "dialogflow.googleapis.com/Version" 203 } 204 ]; 205 206 // The maximum number of items to return in a single page. By default 20 and 207 // at most 100. 208 int32 page_size = 2; 209 210 // The next_page_token value returned from a previous list request. 211 string page_token = 3; 212} 213 214// The response message for 215// [Versions.ListVersions][google.cloud.dialogflow.cx.v3.Versions.ListVersions]. 216message ListVersionsResponse { 217 // A list of versions. There will be a maximum number of items returned based 218 // on the page_size field in the request. The list may in some cases be empty 219 // or contain fewer entries than page_size even if this isn't the last page. 220 repeated Version versions = 1; 221 222 // Token to retrieve the next page of results, or empty if there are no more 223 // results in the list. 224 string next_page_token = 2; 225} 226 227// The request message for 228// [Versions.GetVersion][google.cloud.dialogflow.cx.v3.Versions.GetVersion]. 229message GetVersionRequest { 230 // Required. The name of the [Version][google.cloud.dialogflow.cx.v3.Version]. 231 // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent 232 // ID>/flows/<Flow ID>/versions/<Version ID>`. 233 string name = 1 [ 234 (google.api.field_behavior) = REQUIRED, 235 (google.api.resource_reference) = { 236 type: "dialogflow.googleapis.com/Version" 237 } 238 ]; 239} 240 241// The request message for 242// [Versions.CreateVersion][google.cloud.dialogflow.cx.v3.Versions.CreateVersion]. 243message CreateVersionRequest { 244 // Required. The [Flow][google.cloud.dialogflow.cx.v3.Flow] to create an 245 // [Version][google.cloud.dialogflow.cx.v3.Version] for. Format: 246 // `projects/<Project ID>/locations/<Location ID>/agents/<Agent 247 // ID>/flows/<Flow ID>`. 248 string parent = 1 [ 249 (google.api.field_behavior) = REQUIRED, 250 (google.api.resource_reference) = { 251 child_type: "dialogflow.googleapis.com/Version" 252 } 253 ]; 254 255 // Required. The version to create. 256 Version version = 2 [(google.api.field_behavior) = REQUIRED]; 257} 258 259// The request message for 260// [Versions.UpdateVersion][google.cloud.dialogflow.cx.v3.Versions.UpdateVersion]. 261message UpdateVersionRequest { 262 // Required. The version to update. 263 Version version = 1 [(google.api.field_behavior) = REQUIRED]; 264 265 // Required. The mask to control which fields get updated. Currently only 266 // `description` and `display_name` can be updated. 267 google.protobuf.FieldMask update_mask = 2 268 [(google.api.field_behavior) = REQUIRED]; 269} 270 271// The request message for 272// [Versions.DeleteVersion][google.cloud.dialogflow.cx.v3.Versions.DeleteVersion]. 273message DeleteVersionRequest { 274 // Required. The name of the [Version][google.cloud.dialogflow.cx.v3.Version] 275 // to delete. Format: `projects/<Project ID>/locations/<Location 276 // ID>/agents/<Agent ID>/flows/<Flow ID>/versions/<Version ID>`. 277 string name = 1 [ 278 (google.api.field_behavior) = REQUIRED, 279 (google.api.resource_reference) = { 280 type: "dialogflow.googleapis.com/Version" 281 } 282 ]; 283} 284 285// The request message for 286// [Versions.LoadVersion][google.cloud.dialogflow.cx.v3.Versions.LoadVersion]. 287message LoadVersionRequest { 288 // Required. The [Version][google.cloud.dialogflow.cx.v3.Version] to be loaded 289 // to draft flow. Format: `projects/<Project ID>/locations/<Location 290 // ID>/agents/<Agent ID>/flows/<Flow ID>/versions/<Version ID>`. 291 string name = 1 [ 292 (google.api.field_behavior) = REQUIRED, 293 (google.api.resource_reference) = { 294 type: "dialogflow.googleapis.com/Version" 295 } 296 ]; 297 298 // This field is used to prevent accidental overwrite of other agent 299 // resources, which can potentially impact other flow's behavior. If 300 // `allow_override_agent_resources` is false, conflicted agent-level resources 301 // will not be overridden (i.e. intents, entities, webhooks). 302 bool allow_override_agent_resources = 2; 303} 304 305// The request message for 306// [Versions.CompareVersions][google.cloud.dialogflow.cx.v3.Versions.CompareVersions]. 307message CompareVersionsRequest { 308 // Required. Name of the base flow version to compare with the target version. 309 // Use version ID `0` to indicate the draft version of the specified flow. 310 // 311 // Format: `projects/<Project ID>/locations/<Location ID>/agents/ 312 // <Agent ID>/flows/<Flow ID>/versions/<Version ID>`. 313 string base_version = 1 [ 314 (google.api.field_behavior) = REQUIRED, 315 (google.api.resource_reference) = { 316 type: "dialogflow.googleapis.com/Version" 317 } 318 ]; 319 320 // Required. Name of the target flow version to compare with the 321 // base version. Use version ID `0` to indicate the draft version of the 322 // specified flow. Format: `projects/<Project ID>/locations/<Location 323 // ID>/agents/<Agent ID>/flows/<Flow ID>/versions/<Version ID>`. 324 string target_version = 2 [ 325 (google.api.field_behavior) = REQUIRED, 326 (google.api.resource_reference) = { 327 type: "dialogflow.googleapis.com/Version" 328 } 329 ]; 330 331 // The language to compare the flow versions for. 332 // 333 // If not specified, the agent's default language is used. 334 // [Many 335 // languages](https://cloud.google.com/dialogflow/docs/reference/language) are 336 // supported. Note: languages must be enabled in the agent before they can be 337 // used. 338 string language_code = 3; 339} 340 341// The response message for 342// [Versions.CompareVersions][google.cloud.dialogflow.cx.v3.Versions.CompareVersions]. 343message CompareVersionsResponse { 344 // JSON representation of the base version content. 345 string base_version_content_json = 1; 346 347 // JSON representation of the target version content. 348 string target_version_content_json = 2; 349 350 // The timestamp when the two version compares. 351 google.protobuf.Timestamp compare_time = 3; 352} 353