legacy-libs/dialogflow/protos/google/cloud/dialogflow/v2/entity_type.proto

   1 // Copyright 2018 Google Inc.
   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
  15 syntax = "proto3";
  16
  17 package google.cloud.dialogflow.v2;
  18
  19 import "google/api/annotations.proto";
  20 import "google/longrunning/operations.proto";
  21 import "google/protobuf/empty.proto";
  22 import "google/protobuf/field_mask.proto";
  23 import "google/protobuf/struct.proto";
  24
  25 option cc_enable_arenas = true;
  26 option csharp_namespace = "Google.Cloud.Dialogflow.V2";
  27 option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow";
  28 option java_multiple_files = true;
  29 option java_outer_classname = "EntityTypeProto";
  30 option java_package = "com.google.cloud.dialogflow.v2";
  31 option objc_class_prefix = "DF";
  32
  33 // Entities are extracted from user input and represent parameters that are
  34 // meaningful to your application. For example, a date range, a proper name
  35 // such as a geographic location or landmark, and so on. Entities represent
  36 // actionable data for your application.
  37 //
  38 // When you define an entity, you can also include synonyms that all map to
  39 // that entity. For example, "soft drink", "soda", "pop", and so on.
  40 //
  41 // There are three types of entities:
  42 //
  43 // *   **System** - entities that are defined by the Dialogflow API for common
  44 //     data types such as date, time, currency, and so on. A system entity is
  45 //     represented by the `EntityType` type.
  46 //
  47 // *   **Developer** - entities that are defined by you that represent
  48 //     actionable data that is meaningful to your application. For example,
  49 //     you could define a `pizza.sauce` entity for red or white pizza sauce,
  50 //     a `pizza.cheese` entity for the different types of cheese on a pizza,
  51 //     a `pizza.topping` entity for different toppings, and so on. A developer
  52 //     entity is represented by the `EntityType` type.
  53 //
  54 // *   **User** - entities that are built for an individual user such as
  55 //     favorites, preferences, playlists, and so on. A user entity is
  56 //     represented by the
  57 //     [SessionEntityType][google.cloud.dialogflow.v2.SessionEntityType] type.
  58 //
  59 // For more information about entity types, see the
  60 // [Dialogflow documentation](https://dialogflow.com/docs/entities).
  61 service EntityTypes {
  62   // Returns the list of all entity types in the specified agent.
  63   rpc ListEntityTypes(ListEntityTypesRequest)
  64       returns (ListEntityTypesResponse) {
  65     option (google.api.http) = {
  66       get: "/v2/{parent=projects/*/agent}/entityTypes"
  67     };
  68   }
  69
  70   // Retrieves the specified entity type.
  71   rpc GetEntityType(GetEntityTypeRequest) returns (EntityType) {
  72     option (google.api.http) = {
  73       get: "/v2/{name=projects/*/agent/entityTypes/*}"
  74     };
  75   }
  76
  77   // Creates an entity type in the specified agent.
  78   rpc CreateEntityType(CreateEntityTypeRequest) returns (EntityType) {
  79     option (google.api.http) = {
  80       post: "/v2/{parent=projects/*/agent}/entityTypes"
  81       body: "entity_type"
  82     };
  83   }
  84
  85   // Updates the specified entity type.
  86   rpc UpdateEntityType(UpdateEntityTypeRequest) returns (EntityType) {
  87     option (google.api.http) = {
  88       patch: "/v2/{entity_type.name=projects/*/agent/entityTypes/*}"
  89       body: "entity_type"
  90     };
  91   }
  92
  93   // Deletes the specified entity type.
  94   rpc DeleteEntityType(DeleteEntityTypeRequest)
  95       returns (google.protobuf.Empty) {
  96     option (google.api.http) = {
  97       delete: "/v2/{name=projects/*/agent/entityTypes/*}"
  98     };
  99   }
 100
 101   // Updates/Creates multiple entity types in the specified agent.
 102   //
 103   // Operation <response:
 104   // [BatchUpdateEntityTypesResponse][google.cloud.dialogflow.v2.BatchUpdateEntityTypesResponse],
 105   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
 106   rpc BatchUpdateEntityTypes(BatchUpdateEntityTypesRequest)
 107       returns (google.longrunning.Operation) {
 108     option (google.api.http) = {
 109       post: "/v2/{parent=projects/*/agent}/entityTypes:batchUpdate"
 110       body: "*"
 111     };
 112   }
 113
 114   // Deletes entity types in the specified agent.
 115   //
 116   // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
 117   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
 118   rpc BatchDeleteEntityTypes(BatchDeleteEntityTypesRequest)
 119       returns (google.longrunning.Operation) {
 120     option (google.api.http) = {
 121       post: "/v2/{parent=projects/*/agent}/entityTypes:batchDelete"
 122       body: "*"
 123     };
 124   }
 125
 126   // Creates multiple new entities in the specified entity type (extends the
 127   // existing collection of entries).
 128   //
 129   // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]>
 130   rpc BatchCreateEntities(BatchCreateEntitiesRequest)
 131       returns (google.longrunning.Operation) {
 132     option (google.api.http) = {
 133       post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchCreate"
 134       body: "*"
 135     };
 136   }
 137
 138   // Updates entities in the specified entity type (replaces the existing
 139   // collection of entries).
 140   //
 141   // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
 142   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
 143   rpc BatchUpdateEntities(BatchUpdateEntitiesRequest)
 144       returns (google.longrunning.Operation) {
 145     option (google.api.http) = {
 146       post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchUpdate"
 147       body: "*"
 148     };
 149   }
 150
 151   // Deletes entities in the specified entity type.
 152   //
 153   // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
 154   //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
 155   rpc BatchDeleteEntities(BatchDeleteEntitiesRequest)
 156       returns (google.longrunning.Operation) {
 157     option (google.api.http) = {
 158       post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchDelete"
 159       body: "*"
 160     };
 161   }
 162 }
 163
 164 // Represents an entity type.
 165 // Entity types serve as a tool for extracting parameter values from natural
 166 // language queries.
 167 message EntityType {
 168   // Optional. Represents an entity.
 169   message Entity {
 170     // Required.
 171     // For `KIND_MAP` entity types:
 172     //   A canonical name to be used in place of synonyms.
 173     // For `KIND_LIST` entity types:
 174     //   A string that can contain references to other entity types (with or
 175     //   without aliases).
 176     string value = 1;
 177
 178     // Required. A collection of synonyms. For `KIND_LIST` entity types this
 179     // must contain exactly one synonym equal to `value`.
 180     repeated string synonyms = 2;
 181   }
 182
 183   // Represents kinds of entities.
 184   enum Kind {
 185     // Not specified. This value should be never used.
 186     KIND_UNSPECIFIED = 0;
 187
 188     // Map entity types allow mapping of a group of synonyms to a canonical
 189     // value.
 190     KIND_MAP = 1;
 191
 192     // List entity types contain a set of entries that do not map to canonical
 193     // values. However, list entity types can contain references to other entity
 194     // types (with or without aliases).
 195     KIND_LIST = 2;
 196   }
 197
 198   // Represents different entity type expansion modes. Automated expansion
 199   // allows an agent to recognize values that have not been explicitly listed in
 200   // the entity (for example, new kinds of shopping list items).
 201   enum AutoExpansionMode {
 202     // Auto expansion disabled for the entity.
 203     AUTO_EXPANSION_MODE_UNSPECIFIED = 0;
 204
 205     // Allows an agent to recognize values that have not been explicitly
 206     // listed in the entity.
 207     AUTO_EXPANSION_MODE_DEFAULT = 1;
 208   }
 209
 210   // Required for all methods except `create` (`create` populates the name
 211   // automatically.
 212   // The unique identifier of the entity type. Format:
 213   // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
 214   string name = 1;
 215
 216   // Required. The name of the entity.
 217   string display_name = 2;
 218
 219   // Required. Indicates the kind of entity type.
 220   Kind kind = 3;
 221
 222   // Optional. Indicates whether the entity type can be automatically
 223   // expanded.
 224   AutoExpansionMode auto_expansion_mode = 4;
 225
 226   // Optional. The collection of entities associated with the entity type.
 227   repeated Entity entities = 6;
 228 }
 229
 230 // The request message for
 231 // [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2.EntityTypes.ListEntityTypes].
 232 message ListEntityTypesRequest {
 233   // Required. The agent to list all entity types from.
 234   // Format: `projects/<Project ID>/agent`.
 235   string parent = 1;
 236
 237   // Optional. The language to list entity synonyms for. If not specified,
 238   // the agent's default language is used.
 239   // [More than a dozen
 240   // languages](https://dialogflow.com/docs/reference/language) are supported.
 241   // Note: languages must be enabled in the agent, before they can be used.
 242   string language_code = 2;
 243
 244   // Optional. The maximum number of items to return in a single page. By
 245   // default 100 and at most 1000.
 246   int32 page_size = 3;
 247
 248   // Optional. The next_page_token value returned from a previous list request.
 249   string page_token = 4;
 250 }
 251
 252 // The response message for
 253 // [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2.EntityTypes.ListEntityTypes].
 254 message ListEntityTypesResponse {
 255   // The list of agent entity types. There will be a maximum number of items
 256   // returned based on the page_size field in the request.
 257   repeated EntityType entity_types = 1;
 258
 259   // Token to retrieve the next page of results, or empty if there are no
 260   // more results in the list.
 261   string next_page_token = 2;
 262 }
 263
 264 // The request message for
 265 // [EntityTypes.GetEntityType][google.cloud.dialogflow.v2.EntityTypes.GetEntityType].
 266 message GetEntityTypeRequest {
 267   // Required. The name of the entity type.
 268   // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
 269   string name = 1;
 270
 271   // Optional. The language to retrieve entity synonyms for. If not specified,
 272   // the agent's default language is used.
 273   // [More than a dozen
 274   // languages](https://dialogflow.com/docs/reference/language) are supported.
 275   // Note: languages must be enabled in the agent, before they can be used.
 276   string language_code = 2;
 277 }
 278
 279 // The request message for
 280 // [EntityTypes.CreateEntityType][google.cloud.dialogflow.v2.EntityTypes.CreateEntityType].
 281 message CreateEntityTypeRequest {
 282   // Required. The agent to create a entity type for.
 283   // Format: `projects/<Project ID>/agent`.
 284   string parent = 1;
 285
 286   // Required. The entity type to create.
 287   EntityType entity_type = 2;
 288
 289   // Optional. The language of entity synonyms defined in `entity_type`. If not
 290   // specified, the agent's default language is used.
 291   // [More than a dozen
 292   // languages](https://dialogflow.com/docs/reference/language) are supported.
 293   // Note: languages must be enabled in the agent, before they can be used.
 294   string language_code = 3;
 295 }
 296
 297 // The request message for
 298 // [EntityTypes.UpdateEntityType][google.cloud.dialogflow.v2.EntityTypes.UpdateEntityType].
 299 message UpdateEntityTypeRequest {
 300   // Required. The entity type to update.
 301   // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
 302   EntityType entity_type = 1;
 303
 304   // Optional. The language of entity synonyms defined in `entity_type`. If not
 305   // specified, the agent's default language is used.
 306   // [More than a dozen
 307   // languages](https://dialogflow.com/docs/reference/language) are supported.
 308   // Note: languages must be enabled in the agent, before they can be used.
 309   string language_code = 2;
 310
 311   // Optional. The mask to control which fields get updated.
 312   google.protobuf.FieldMask update_mask = 3;
 313 }
 314
 315 // The request message for
 316 // [EntityTypes.DeleteEntityType][google.cloud.dialogflow.v2.EntityTypes.DeleteEntityType].
 317 message DeleteEntityTypeRequest {
 318   // Required. The name of the entity type to delete.
 319   // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
 320   string name = 1;
 321 }
 322
 323 // The request message for
 324 // [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntityTypes].
 325 message BatchUpdateEntityTypesRequest {
 326   // Required. The name of the agent to update or create entity types in.
 327   // Format: `projects/<Project ID>/agent`.
 328   string parent = 1;
 329
 330   // Required. The source of the entity type batch.
 331   //
 332   // For each entity type in the batch:
 333   // * If `name` is specified, we update an existing entity type.
 334   // * If `name` is not specified, we create a new entity type.
 335   oneof entity_type_batch {
 336     // The URI to a Google Cloud Storage file containing entity types to update
 337     // or create. The file format can either be a serialized proto (of
 338     // EntityBatch type) or a JSON object. Note: The URI must start with
 339     // "gs://".
 340     string entity_type_batch_uri = 2;
 341
 342     // The collection of entity type to update or create.
 343     EntityTypeBatch entity_type_batch_inline = 3;
 344   }
 345
 346   // Optional. The language of entity synonyms defined in `entity_types`. If not
 347   // specified, the agent's default language is used.
 348   // [More than a dozen
 349   // languages](https://dialogflow.com/docs/reference/language) are supported.
 350   // Note: languages must be enabled in the agent, before they can be used.
 351   string language_code = 4;
 352
 353   // Optional. The mask to control which fields get updated.
 354   google.protobuf.FieldMask update_mask = 5;
 355 }
 356
 357 // The response message for
 358 // [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntityTypes].
 359 message BatchUpdateEntityTypesResponse {
 360   // The collection of updated or created entity types.
 361   repeated EntityType entity_types = 1;
 362 }
 363
 364 // The request message for
 365 // [EntityTypes.BatchDeleteEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchDeleteEntityTypes].
 366 message BatchDeleteEntityTypesRequest {
 367   // Required. The name of the agent to delete all entities types for. Format:
 368   // `projects/<Project ID>/agent`.
 369   string parent = 1;
 370
 371   // Required. The names entity types to delete. All names must point to the
 372   // same agent as `parent`.
 373   repeated string entity_type_names = 2;
 374 }
 375
 376 // The request message for
 377 // [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2.EntityTypes.BatchCreateEntities].
 378 message BatchCreateEntitiesRequest {
 379   // Required. The name of the entity type to create entities in. Format:
 380   // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
 381   string parent = 1;
 382
 383   // Required. The collection of entities to create.
 384   repeated EntityType.Entity entities = 2;
 385
 386   // Optional. The language of entity synonyms defined in `entities`. If not
 387   // specified, the agent's default language is used.
 388   // [More than a dozen
 389   // languages](https://dialogflow.com/docs/reference/language) are supported.
 390   // Note: languages must be enabled in the agent, before they can be used.
 391   string language_code = 3;
 392 }
 393
 394 // The response message for
 395 // [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2.EntityTypes.BatchCreateEntities].
 396 message BatchUpdateEntitiesRequest {
 397   // Required. The name of the entity type to update the entities in. Format:
 398   // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
 399   string parent = 1;
 400
 401   // Required. The collection of new entities to replace the existing entities.
 402   repeated EntityType.Entity entities = 2;
 403
 404   // Optional. The language of entity synonyms defined in `entities`. If not
 405   // specified, the agent's default language is used.
 406   // [More than a dozen
 407   // languages](https://dialogflow.com/docs/reference/language) are supported.
 408   // Note: languages must be enabled in the agent, before they can be used.
 409   string language_code = 3;
 410
 411   // Optional. The mask to control which fields get updated.
 412   google.protobuf.FieldMask update_mask = 4;
 413 }
 414
 415 // The request message for
 416 // [EntityTypes.BatchDeleteEntities][google.cloud.dialogflow.v2.EntityTypes.BatchDeleteEntities].
 417 message BatchDeleteEntitiesRequest {
 418   // Required. The name of the entity type to delete entries for. Format:
 419   // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
 420   string parent = 1;
 421
 422   // Required. The canonical `values` of the entities to delete. Note that
 423   // these are not fully-qualified names, i.e. they don't start with
 424   // `projects/<Project ID>`.
 425   repeated string entity_values = 2;
 426
 427   // Optional. The language of entity synonyms defined in `entities`. If not
 428   // specified, the agent's default language is used.
 429   // [More than a dozen
 430   // languages](https://dialogflow.com/docs/reference/language) are supported.
 431   // Note: languages must be enabled in the agent, before they can be used.
 432   string language_code = 3;
 433 }
 434
 435 // This message is a wrapper around a collection of entity types.
 436 message EntityTypeBatch {
 437   // A collection of entity types.
 438   repeated EntityType entity_types = 1;
 439 }