From a6b2dac798ed266136e990a2319b2e2e96f3bdbe Mon Sep 17 00:00:00 2001 From: Google APIs Date: Fri, 24 Jul 2020 15:42:41 -0700 Subject: [PATCH] docs: more detailed docs on APIs such as Environment, Intents, Sessions. PiperOrigin-RevId: 323086730 --- google/cloud/dialogflow/v2/BUILD.bazel | 9 ++++ google/cloud/dialogflow/v2/agent.proto | 3 +- google/cloud/dialogflow/v2/context.proto | 35 +++++++-------- google/cloud/dialogflow/v2/entity_type.proto | 44 ++++++------------ google/cloud/dialogflow/v2/environment.proto | 21 ++++++++- google/cloud/dialogflow/v2/intent.proto | 45 +++++-------------- google/cloud/dialogflow/v2/session.proto | 26 ++++++++--- .../dialogflow/v2/session_entity_type.proto | 31 ++++--------- 8 files changed, 96 insertions(+), 118 deletions(-) diff --git a/google/cloud/dialogflow/v2/BUILD.bazel b/google/cloud/dialogflow/v2/BUILD.bazel index e9972eb2..8614f623 100644 --- a/google/cloud/dialogflow/v2/BUILD.bazel +++ b/google/cloud/dialogflow/v2/BUILD.bazel @@ -1,4 +1,13 @@ # This file was automatically generated by BuildFileGenerator +# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel + +# Most of the manual changes to this file will be overwritten. +# It's **only** allowed to change the following rule attribute values: +# - names of *_gapic_assembly_* rules +# - certain parameters of *_gapic_library rules, including but not limited to: +# * extra_protoc_parameters +# * extra_protoc_file_parameters +# The complete list of preserved parameters can be found in the source code. # This is an API workspace, having public visibility by default makes perfect sense. package(default_visibility = ["//visibility:public"]) diff --git a/google/cloud/dialogflow/v2/agent.proto b/google/cloud/dialogflow/v2/agent.proto index 7eb7c525..1ce27173 100644 --- a/google/cloud/dialogflow/v2/agent.proto +++ b/google/cloud/dialogflow/v2/agent.proto @@ -173,8 +173,7 @@ service Agents { // conversations required for your system. // // For more information about agents, see the -// [Agents -// documentation](https://cloud.google.com/dialogflow/docs/agents-overview). +// [Agent guide](https://cloud.google.com/dialogflow/docs/agents-overview). message Agent { option (google.api.resource) = { type: "dialogflow.googleapis.com/Agent" diff --git a/google/cloud/dialogflow/v2/context.proto b/google/cloud/dialogflow/v2/context.proto index e647c4ff..07740d1f 100644 --- a/google/cloud/dialogflow/v2/context.proto +++ b/google/cloud/dialogflow/v2/context.proto @@ -32,24 +32,7 @@ option java_outer_classname = "ContextProto"; option java_package = "com.google.cloud.dialogflow.v2"; option objc_class_prefix = "DF"; -// A context represents additional information included with user input or with -// an intent returned by the Dialogflow API. Contexts are helpful for -// differentiating user input which may be vague or have a different meaning -// depending on additional details from your application such as user setting -// and preferences, previous user input, where the user is in your application, -// geographic location, and so on. -// -// You can include contexts as input parameters of a -// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or -// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) request, -// or as output contexts included in the returned intent. -// Contexts expire when an intent is matched, after the number of `DetectIntent` -// requests specified by the `lifespan_count` parameter, or after 20 minutes -// if no intents are matched for a `DetectIntent` request. -// -// For more information about contexts, see the -// [Dialogflow -// documentation](https://cloud.google.com/dialogflow/docs/contexts-overview). +// Service for managing [Contexts][google.cloud.dialogflow.v2.Context]. service Contexts { option (google.api.default_host) = "dialogflow.googleapis.com"; option (google.api.oauth_scopes) = @@ -129,7 +112,21 @@ service Contexts { } } -// Represents a context. +// Dialogflow contexts are similar to natural language context. If a person says +// to you "they are orange", you need context in order to understand what "they" +// is referring to. Similarly, for Dialogflow to handle an end-user expression +// like that, it needs to be provided with context in order to correctly match +// an intent. +// +// Using contexts, you can control the flow of a conversation. You can configure +// contexts for an intent by setting input and output contexts, which are +// identified by string names. When an intent is matched, any configured output +// contexts for that intent become active. While any contexts are active, +// Dialogflow is more likely to match intents that are configured with input +// contexts that correspond to the currently active contexts. +// +// For more information about context, see the +// [Contexts guide](https://cloud.google.com/dialogflow/docs/contexts-overview). message Context { option (google.api.resource) = { type: "dialogflow.googleapis.com/Context" diff --git a/google/cloud/dialogflow/v2/entity_type.proto b/google/cloud/dialogflow/v2/entity_type.proto index 5c027372..13fcdb05 100644 --- a/google/cloud/dialogflow/v2/entity_type.proto +++ b/google/cloud/dialogflow/v2/entity_type.proto @@ -32,34 +32,7 @@ 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. -// -// * **Custom** - 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 custom -// 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://cloud.google.com/dialogflow/docs/entities-overview). +// Service for managing [EntityTypes][google.cloud.dialogflow.v2.EntityType]. service EntityTypes { option (google.api.default_host) = "dialogflow.googleapis.com"; option (google.api.oauth_scopes) = @@ -194,9 +167,18 @@ service EntityTypes { } } -// Represents an entity type. -// Entity types serve as a tool for extracting parameter values from natural -// language queries. +// Each intent parameter has a type, called the entity type, which dictates +// exactly how data from an end-user expression is extracted. +// +// Dialogflow provides predefined system entities that can match many common +// types of data. For example, there are system entities for matching dates, +// times, colors, email addresses, and so on. You can also create your own +// custom entities for matching custom data. For example, you could define a +// vegetable entity that can match the types of vegetables available for +// purchase with a grocery store agent. +// +// For more information, see the +// [Entity guide](https://cloud.google.com/dialogflow/docs/entities-overview). message EntityType { option (google.api.resource) = { type: "dialogflow.googleapis.com/EntityType" diff --git a/google/cloud/dialogflow/v2/environment.proto b/google/cloud/dialogflow/v2/environment.proto index 5bb7413f..d48c210f 100644 --- a/google/cloud/dialogflow/v2/environment.proto +++ b/google/cloud/dialogflow/v2/environment.proto @@ -32,7 +32,7 @@ option java_outer_classname = "EnvironmentProto"; option java_package = "com.google.cloud.dialogflow.v2"; option objc_class_prefix = "DF"; -// Manages agent environments. +// Service for managing [Environments][google.cloud.dialogflow.v2.Environment]. service Environments { option (google.api.default_host) = "dialogflow.googleapis.com"; option (google.api.oauth_scopes) = @@ -47,7 +47,24 @@ service Environments { } } -// Represents an agent environment. +// You can create multiple versions of your agent and publish them to separate +// environments. +// +// When you edit an agent, you are editing the draft agent. At any point, you +// can save the draft agent as an agent version, which is an immutable snapshot +// of your agent. +// +// When you save the draft agent, it is published to the default environment. +// When you create agent versions, you can publish them to custom environments. +// You can create a variety of custom environments for: +// +// - testing +// - development +// - production +// - etc. +// +// For more information, see the [versions and environments +// guide](https://cloud.google.com/dialogflow/docs/agents-versions). message Environment { option (google.api.resource) = { type: "dialogflow.googleapis.com/Environment" diff --git a/google/cloud/dialogflow/v2/intent.proto b/google/cloud/dialogflow/v2/intent.proto index 6a176c35..f4f78aca 100644 --- a/google/cloud/dialogflow/v2/intent.proto +++ b/google/cloud/dialogflow/v2/intent.proto @@ -36,38 +36,7 @@ option java_outer_classname = "IntentProto"; option java_package = "com.google.cloud.dialogflow.v2"; option objc_class_prefix = "DF"; -// An intent represents a mapping between input from a user and an action to -// be taken by your application. When you pass user input to the -// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or -// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method, the -// Dialogflow API analyzes the input and searches -// for a matching intent. If no match is found, the Dialogflow API returns a -// fallback intent (`is_fallback` = true). -// -// You can provide additional information for the Dialogflow API to use to -// match user input to an intent by adding the following to your intent. -// -// * **Contexts** - provide additional context for intent analysis. For -// example, if an intent is related to an object in your application that -// plays music, you can provide a context to determine when to match the -// intent if the user input is "turn it off". You can include a context -// that matches the intent when there is previous user input of -// "play music", and not when there is previous user input of -// "turn on the light". -// -// * **Events** - allow for matching an intent by using an event name -// instead of user input. Your application can provide an event name and -// related parameters to the Dialogflow API to match an intent. For -// example, when your application starts, you can send a welcome event -// with a user name parameter to the Dialogflow API to match an intent with -// a personalized welcome message for the user. -// -// * **Training phrases** - provide examples of user input to train the -// Dialogflow API agent to better match intents. -// -// For more information about intents, see the -// [Dialogflow -// documentation](https://cloud.google.com/dialogflow/docs/intents-overview). +// Service for managing [Intents][google.cloud.dialogflow.v2.Intent]. service Intents { option (google.api.default_host) = "dialogflow.googleapis.com"; option (google.api.oauth_scopes) = @@ -152,9 +121,15 @@ service Intents { } } -// Represents an intent. -// Intents convert a number of user expressions or patterns into an action. An -// action is an extraction of a user command or sentence semantics. +// An intent categorizes an end-user's intention for one conversation turn. For +// each agent, you define many intents, where your combined intents can handle a +// complete conversation. When an end-user writes or says something, referred to +// as an end-user expression or end-user input, Dialogflow matches the end-user +// input to the best intent in your agent. Matching an intent is also known as +// intent classification. +// +// For more information, see the [intent +// guide](https://cloud.google.com/dialogflow/docs/intents-overview). message Intent { option (google.api.resource) = { type: "dialogflow.googleapis.com/Intent" diff --git a/google/cloud/dialogflow/v2/session.proto b/google/cloud/dialogflow/v2/session.proto index 9e3d9442..96e7c2ce 100644 --- a/google/cloud/dialogflow/v2/session.proto +++ b/google/cloud/dialogflow/v2/session.proto @@ -43,10 +43,10 @@ option (google.api.resource_definition) = { pattern: "projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}" }; -// A session represents an interaction with a user. You retrieve user input -// and pass it to the [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or -// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method to determine -// user intent and respond. +// A service used for session interactions. +// +// For more information, see the [API interactions +// guide](https://cloud.google.com/dialogflow/docs/api-overview). service Sessions { option (google.api.default_host) = "dialogflow.googleapis.com"; option (google.api.oauth_scopes) = @@ -87,6 +87,9 @@ message DetectIntentRequest { // `User Id`. They can be a random number or some type of user and session // identifiers (preferably hashed). The length of the `Session ID` and // `User ID` must not exceed 36 characters. + // + // For more information, see the [API interactions + // guide](https://cloud.google.com/dialogflow/docs/api-overview). string session = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -362,6 +365,9 @@ message StreamingDetectIntentRequest { // `User Id`. They can be a random number or some type of user and session // identifiers (preferably hashed). The length of the `Session ID` and // `User ID` must not exceed 36 characters. + // + // For more information, see the [API interactions + // guide](https://cloud.google.com/dialogflow/docs/api-overview). string session = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -591,8 +597,16 @@ message SentimentAnalysisRequestConfig { bool analyze_query_text_sentiment = 1; } -// The result of sentiment analysis as configured by -// `sentiment_analysis_request_config`. +// The result of sentiment analysis. Sentiment analysis inspects user input +// and identifies the prevailing subjective opinion, especially to determine a +// user's attitude as positive, negative, or neutral. +// For [Participants.AnalyzeContent][google.cloud.dialogflow.v2.Participants.AnalyzeContent], it needs to be configured in +// [DetectIntentRequest.query_params][google.cloud.dialogflow.v2.DetectIntentRequest.query_params]. For +// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2.Participants.StreamingAnalyzeContent], it needs to be configured in +// [StreamingDetectIntentRequest.query_params][google.cloud.dialogflow.v2.StreamingDetectIntentRequest.query_params]. +// And for [Participants.AnalyzeContent][google.cloud.dialogflow.v2.Participants.AnalyzeContent] and +// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2.Participants.StreamingAnalyzeContent], it needs to be configured in +// [ConversationProfile.human_agent_assistant_config][google.cloud.dialogflow.v2.ConversationProfile.human_agent_assistant_config] message SentimentAnalysisResult { // The sentiment analysis result for `query_text`. Sentiment query_text_sentiment = 1; diff --git a/google/cloud/dialogflow/v2/session_entity_type.proto b/google/cloud/dialogflow/v2/session_entity_type.proto index 9a16a558..8d7fa89c 100644 --- a/google/cloud/dialogflow/v2/session_entity_type.proto +++ b/google/cloud/dialogflow/v2/session_entity_type.proto @@ -32,23 +32,7 @@ option java_outer_classname = "SessionEntityTypeProto"; 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. -// -// Session entity types are referred to as **User** entity types and are -// entities that are built for an individual user such as -// favorites, preferences, playlists, and so on. You can redefine a session -// entity type at the session level. -// -// Session entity methods do not work with Google Assistant integration. -// Contact Dialogflow support if you need to use session entities -// with Google Assistant integration. -// -// For more information about entity types, see the -// [Dialogflow -// documentation](https://cloud.google.com/dialogflow/docs/entities-overview). +// Service for managing [SessionEntityTypes][google.cloud.dialogflow.v2.SessionEntityType]. service SessionEntityTypes { option (google.api.default_host) = "dialogflow.googleapis.com"; option (google.api.oauth_scopes) = @@ -139,13 +123,14 @@ service SessionEntityTypes { } } -// Represents a session entity type. +// A session represents a conversation between a Dialogflow agent and an +// end-user. You can create special entities, called session entities, during a +// session. Session entities can extend or replace custom entity types and only +// exist during the session that they were created for. All session data, +// including session entities, is stored by Dialogflow for 20 minutes. // -// Extends or replaces a custom entity type at the user session level (we -// refer to the entity types defined at the agent level as "custom entity -// types"). -// -// Note: session entity types apply to all queries, regardless of the language. +// For more information, see the [session entity +// guide](https://cloud.google.com/dialogflow/docs/entities-session). message SessionEntityType { option (google.api.resource) = { type: "dialogflow.googleapis.com/SessionEntityType"