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