// Copyright 2018 Google Inc.
//
// 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.v2;

import "google/api/annotations.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Dialogflow.V2";
option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow";
option java_multiple_files = true;
option java_outer_classname = "EntityTypeProto";
option java_package = "com.google.cloud.dialogflow.v2";
option objc_class_prefix = "DF";


// Entities are extracted from user input and represent parameters that are
// meaningful to your application. For example, a date range, a proper name
// such as a geographic location or landmark, and so on. Entities represent
// actionable data for your application.
//
// When you define an entity, you can also include synonyms that all map to
// that entity. For example, "soft drink", "soda", "pop", and so on.
//
// There are three types of entities:
//
// *   **System** - entities that are defined by the Dialogflow API for common
//     data types such as date, time, currency, and so on. A system entity is
//     represented by the `EntityType` type.
//
// *   **Developer** - entities that are defined by you that represent
//     actionable data that is meaningful to your application. For example,
//     you could define a `pizza.sauce` entity for red or white pizza sauce,
//     a `pizza.cheese` entity for the different types of cheese on a pizza,
//     a `pizza.topping` entity for different toppings, and so on. A developer
//     entity is represented by the `EntityType` type.
//
// *   **User** - entities that are built for an individual user such as
//     favorites, preferences, playlists, and so on. A user entity is
//     represented by the [SessionEntityType][google.cloud.dialogflow.v2.SessionEntityType] type.
//
// For more information about entity types, see the
// [Dialogflow documentation](https://dialogflow.com/docs/entities).
service EntityTypes {
  // Returns the list of all entity types in the specified agent.
  rpc ListEntityTypes(ListEntityTypesRequest) returns (ListEntityTypesResponse) {
    option (google.api.http) = {
      get: "/v2/{parent=projects/*/agent}/entityTypes"
    };
  }

  // Retrieves the specified entity type.
  rpc GetEntityType(GetEntityTypeRequest) returns (EntityType) {
    option (google.api.http) = {
      get: "/v2/{name=projects/*/agent/entityTypes/*}"
    };
  }

  // Creates an entity type in the specified agent.
  rpc CreateEntityType(CreateEntityTypeRequest) returns (EntityType) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent}/entityTypes"
      body: "entity_type"
    };
  }

  // Updates the specified entity type.
  rpc UpdateEntityType(UpdateEntityTypeRequest) returns (EntityType) {
    option (google.api.http) = {
      patch: "/v2/{entity_type.name=projects/*/agent/entityTypes/*}"
      body: "entity_type"
    };
  }

  // Deletes the specified entity type.
  rpc DeleteEntityType(DeleteEntityTypeRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v2/{name=projects/*/agent/entityTypes/*}"
    };
  }

  // Updates/Creates multiple entity types in the specified agent.
  //
  // Operation <response: [BatchUpdateEntityTypesResponse][google.cloud.dialogflow.v2.BatchUpdateEntityTypesResponse],
  //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
  rpc BatchUpdateEntityTypes(BatchUpdateEntityTypesRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent}/entityTypes:batchUpdate"
      body: "*"
    };
  }

  // Deletes entity types in the specified agent.
  //
  // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
  //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
  rpc BatchDeleteEntityTypes(BatchDeleteEntityTypesRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent}/entityTypes:batchDelete"
      body: "*"
    };
  }

  // Creates multiple new entities in the specified entity type (extends the
  // existing collection of entries).
  //
  // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]>
  rpc BatchCreateEntities(BatchCreateEntitiesRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchCreate"
      body: "*"
    };
  }

  // Updates entities in the specified entity type (replaces the existing
  // collection of entries).
  //
  // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
  //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
  rpc BatchUpdateEntities(BatchUpdateEntitiesRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchUpdate"
      body: "*"
    };
  }

  // Deletes entities in the specified entity type.
  //
  // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
  //            metadata: [google.protobuf.Struct][google.protobuf.Struct]>
  rpc BatchDeleteEntities(BatchDeleteEntitiesRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchDelete"
      body: "*"
    };
  }
}

// Represents an entity type.
// Entity types serve as a tool for extracting parameter values from natural
// language queries.
message EntityType {
  // Optional. Represents an entity.
  message Entity {
    // Required.
    // For `KIND_MAP` entity types:
    //   A canonical name to be used in place of synonyms.
    // For `KIND_LIST` entity types:
    //   A string that can contain references to other entity types (with or
    //   without aliases).
    string value = 1;

    // Required. A collection of synonyms. For `KIND_LIST` entity types this
    // must contain exactly one synonym equal to `value`.
    repeated string synonyms = 2;
  }

  // Represents kinds of entities.
  enum Kind {
    // Not specified. This value should be never used.
    KIND_UNSPECIFIED = 0;

    // Map entity types allow mapping of a group of synonyms to a canonical
    // value.
    KIND_MAP = 1;

    // List entity types contain a set of entries that do not map to canonical
    // values. However, list entity types can contain references to other entity
    // types (with or without aliases).
    KIND_LIST = 2;
  }

  // Represents different entity type expansion modes. Automated expansion
  // allows an agent to recognize values that have not been explicitly listed in
  // the entity (for example, new kinds of shopping list items).
  enum AutoExpansionMode {
    // Auto expansion disabled for the entity.
    AUTO_EXPANSION_MODE_UNSPECIFIED = 0;

    // Allows an agent to recognize values that have not been explicitly
    // listed in the entity.
    AUTO_EXPANSION_MODE_DEFAULT = 1;
  }

  // Required for all methods except `create` (`create` populates the name
  // automatically.
  // The unique identifier of the entity type. Format:
  // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
  string name = 1;

  // Required. The name of the entity.
  string display_name = 2;

  // Required. Indicates the kind of entity type.
  Kind kind = 3;

  // Optional. Indicates whether the entity type can be automatically
  // expanded.
  AutoExpansionMode auto_expansion_mode = 4;

  // Optional. The collection of entities associated with the entity type.
  repeated Entity entities = 6;
}

// The request message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2.EntityTypes.ListEntityTypes].
message ListEntityTypesRequest {
  // Required. The agent to list all entity types from.
  // Format: `projects/<Project ID>/agent`.
  string parent = 1;

  // Optional. The language to list entity synonyms for. If not specified,
  // the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 2;

  // Optional. The maximum number of items to return in a single page. By
  // default 100 and at most 1000.
  int32 page_size = 3;

  // Optional. The next_page_token value returned from a previous list request.
  string page_token = 4;
}

// The response message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.v2.EntityTypes.ListEntityTypes].
message ListEntityTypesResponse {
  // The list of agent entity types. There will be a maximum number of items
  // returned based on the page_size field in the request.
  repeated EntityType entity_types = 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 [EntityTypes.GetEntityType][google.cloud.dialogflow.v2.EntityTypes.GetEntityType].
message GetEntityTypeRequest {
  // Required. The name of the entity type.
  // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
  string name = 1;

  // Optional. The language to retrieve entity synonyms for. If not specified,
  // the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 2;
}

// The request message for [EntityTypes.CreateEntityType][google.cloud.dialogflow.v2.EntityTypes.CreateEntityType].
message CreateEntityTypeRequest {
  // Required. The agent to create a entity type for.
  // Format: `projects/<Project ID>/agent`.
  string parent = 1;

  // Required. The entity type to create.
  EntityType entity_type = 2;

  // Optional. The language of entity synonyms defined in `entity_type`. If not
  // specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 3;
}

// The request message for [EntityTypes.UpdateEntityType][google.cloud.dialogflow.v2.EntityTypes.UpdateEntityType].
message UpdateEntityTypeRequest {
  // Required. The entity type to update.
  // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
  EntityType entity_type = 1;

  // Optional. The language of entity synonyms defined in `entity_type`. If not
  // specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 2;

  // Optional. The mask to control which fields get updated.
  google.protobuf.FieldMask update_mask = 3;
}

// The request message for [EntityTypes.DeleteEntityType][google.cloud.dialogflow.v2.EntityTypes.DeleteEntityType].
message DeleteEntityTypeRequest {
  // Required. The name of the entity type to delete.
  // Format: `projects/<Project ID>/agent/entityTypes/<EntityType ID>`.
  string name = 1;
}

// The request message for [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntityTypes].
message BatchUpdateEntityTypesRequest {
  // Required. The name of the agent to update or create entity types in.
  // Format: `projects/<Project ID>/agent`.
  string parent = 1;

  // Required. The source of the entity type batch.
  //
  // For each entity type in the batch:
  // * If `name` is specified, we update an existing entity type.
  // * If `name` is not specified, we create a new entity type.
  oneof entity_type_batch {
    // The URI to a Google Cloud Storage file containing entity types to update
    // or create. The file format can either be a serialized proto (of
    // EntityBatch type) or a JSON object. Note: The URI must start with
    // "gs://".
    string entity_type_batch_uri = 2;

    // The collection of entity type to update or create.
    EntityTypeBatch entity_type_batch_inline = 3;
  }

  // Optional. The language of entity synonyms defined in `entity_types`. If not
  // specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 4;

  // Optional. The mask to control which fields get updated.
  google.protobuf.FieldMask update_mask = 5;
}

// The response message for [EntityTypes.BatchUpdateEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchUpdateEntityTypes].
message BatchUpdateEntityTypesResponse {
  // The collection of updated or created entity types.
  repeated EntityType entity_types = 1;
}

// The request message for [EntityTypes.BatchDeleteEntityTypes][google.cloud.dialogflow.v2.EntityTypes.BatchDeleteEntityTypes].
message BatchDeleteEntityTypesRequest {
  // Required. The name of the agent to delete all entities types for. Format:
  // `projects/<Project ID>/agent`.
  string parent = 1;

  // Required. The names entity types to delete. All names must point to the
  // same agent as `parent`.
  repeated string entity_type_names = 2;
}

// The request message for [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2.EntityTypes.BatchCreateEntities].
message BatchCreateEntitiesRequest {
  // Required. The name of the entity type to create entities in. Format:
  // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
  string parent = 1;

  // Required. The collection of entities to create.
  repeated EntityType.Entity entities = 2;

  // Optional. The language of entity synonyms defined in `entities`. If not
  // specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 3;
}

// The response message for [EntityTypes.BatchCreateEntities][google.cloud.dialogflow.v2.EntityTypes.BatchCreateEntities].
message BatchUpdateEntitiesRequest {
  // Required. The name of the entity type to update the entities in. Format:
  // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
  string parent = 1;

  // Required. The collection of new entities to replace the existing entities.
  repeated EntityType.Entity entities = 2;

  // Optional. The language of entity synonyms defined in `entities`. If not
  // specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 3;

  // Optional. The mask to control which fields get updated.
  google.protobuf.FieldMask update_mask = 4;
}

// The request message for [EntityTypes.BatchDeleteEntities][google.cloud.dialogflow.v2.EntityTypes.BatchDeleteEntities].
message BatchDeleteEntitiesRequest {
  // Required. The name of the entity type to delete entries for. Format:
  // `projects/<Project ID>/agent/entityTypes/<Entity Type ID>`.
  string parent = 1;

  // Required. The canonical `values` of the entities to delete. Note that
  // these are not fully-qualified names, i.e. they don't start with
  // `projects/<Project ID>`.
  repeated string entity_values = 2;

  // Optional. The language of entity synonyms defined in `entities`. If not
  // specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 3;
}

// This message is a wrapper around a collection of entity types.
message EntityTypeBatch {
  // A collection of entity types.
  repeated EntityType entity_types = 1;
}
