intent.proto 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377
  1. // Copyright 2021 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. syntax = "proto3";
  15. package google.cloud.dialogflow.cx.v3;
  16. import "google/api/annotations.proto";
  17. import "google/api/client.proto";
  18. import "google/api/field_behavior.proto";
  19. import "google/api/resource.proto";
  20. import "google/longrunning/operations.proto";
  21. import "google/protobuf/empty.proto";
  22. import "google/protobuf/field_mask.proto";
  23. import "google/protobuf/timestamp.proto";
  24. option cc_enable_arenas = true;
  25. option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3";
  26. option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3;cx";
  27. option java_multiple_files = true;
  28. option java_outer_classname = "IntentProto";
  29. option java_package = "com.google.cloud.dialogflow.cx.v3";
  30. option objc_class_prefix = "DF";
  31. // Service for managing [Intents][google.cloud.dialogflow.cx.v3.Intent].
  32. service Intents {
  33. option (google.api.default_host) = "dialogflow.googleapis.com";
  34. option (google.api.oauth_scopes) =
  35. "https://www.googleapis.com/auth/cloud-platform,"
  36. "https://www.googleapis.com/auth/dialogflow";
  37. // Returns the list of all intents in the specified agent.
  38. rpc ListIntents(ListIntentsRequest) returns (ListIntentsResponse) {
  39. option (google.api.http) = {
  40. get: "/v3/{parent=projects/*/locations/*/agents/*}/intents"
  41. };
  42. option (google.api.method_signature) = "parent";
  43. }
  44. // Retrieves the specified intent.
  45. rpc GetIntent(GetIntentRequest) returns (Intent) {
  46. option (google.api.http) = {
  47. get: "/v3/{name=projects/*/locations/*/agents/*/intents/*}"
  48. };
  49. option (google.api.method_signature) = "name";
  50. }
  51. // Creates an intent in the specified agent.
  52. //
  53. // Note: You should always train a flow prior to sending it queries. See the
  54. // [training
  55. // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  56. rpc CreateIntent(CreateIntentRequest) returns (Intent) {
  57. option (google.api.http) = {
  58. post: "/v3/{parent=projects/*/locations/*/agents/*}/intents"
  59. body: "intent"
  60. };
  61. option (google.api.method_signature) = "parent,intent";
  62. }
  63. // Updates the specified intent.
  64. //
  65. // Note: You should always train a flow prior to sending it queries. See the
  66. // [training
  67. // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  68. rpc UpdateIntent(UpdateIntentRequest) returns (Intent) {
  69. option (google.api.http) = {
  70. patch: "/v3/{intent.name=projects/*/locations/*/agents/*/intents/*}"
  71. body: "intent"
  72. };
  73. option (google.api.method_signature) = "intent,update_mask";
  74. }
  75. // Deletes the specified intent.
  76. //
  77. // Note: You should always train a flow prior to sending it queries. See the
  78. // [training
  79. // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  80. rpc DeleteIntent(DeleteIntentRequest) returns (google.protobuf.Empty) {
  81. option (google.api.http) = {
  82. delete: "/v3/{name=projects/*/locations/*/agents/*/intents/*}"
  83. };
  84. option (google.api.method_signature) = "name";
  85. }
  86. }
  87. // An intent represents a user's intent to interact with a conversational agent.
  88. //
  89. // You can provide information for the Dialogflow API to use to match user input
  90. // to an intent by adding training phrases (i.e., examples of user input) to
  91. // your intent.
  92. message Intent {
  93. option (google.api.resource) = {
  94. type: "dialogflow.googleapis.com/Intent"
  95. pattern: "projects/{project}/locations/{location}/agents/{agent}/intents/{intent}"
  96. };
  97. // Represents an example that the agent is trained on to identify the intent.
  98. message TrainingPhrase {
  99. // Represents a part of a training phrase.
  100. message Part {
  101. // Required. The text for this part.
  102. string text = 1 [(google.api.field_behavior) = REQUIRED];
  103. // The [parameter][google.cloud.dialogflow.cx.v3.Intent.Parameter] used to annotate this part of the
  104. // training phrase. This field is required for annotated parts of the
  105. // training phrase.
  106. string parameter_id = 2;
  107. }
  108. // Output only. The unique identifier of the training phrase.
  109. string id = 1;
  110. // Required. The ordered list of training phrase parts.
  111. // The parts are concatenated in order to form the training phrase.
  112. //
  113. // Note: The API does not automatically annotate training phrases like the
  114. // Dialogflow Console does.
  115. //
  116. // Note: Do not forget to include whitespace at part boundaries, so the
  117. // training phrase is well formatted when the parts are concatenated.
  118. //
  119. // If the training phrase does not need to be annotated with parameters,
  120. // you just need a single part with only the [Part.text][google.cloud.dialogflow.cx.v3.Intent.TrainingPhrase.Part.text] field set.
  121. //
  122. // If you want to annotate the training phrase, you must create multiple
  123. // parts, where the fields of each part are populated in one of two ways:
  124. //
  125. // - `Part.text` is set to a part of the phrase that has no parameters.
  126. // - `Part.text` is set to a part of the phrase that you want to annotate,
  127. // and the `parameter_id` field is set.
  128. repeated Part parts = 2 [(google.api.field_behavior) = REQUIRED];
  129. // Indicates how many times this example was added to the intent.
  130. int32 repeat_count = 3;
  131. }
  132. // Represents an intent parameter.
  133. message Parameter {
  134. // Required. The unique identifier of the parameter. This field
  135. // is used by [training phrases][google.cloud.dialogflow.cx.v3.Intent.TrainingPhrase] to annotate their
  136. // [parts][google.cloud.dialogflow.cx.v3.Intent.TrainingPhrase.Part].
  137. string id = 1 [(google.api.field_behavior) = REQUIRED];
  138. // Required. The entity type of the parameter.
  139. // Format: `projects/-/locations/-/agents/-/entityTypes/<System Entity Type
  140. // ID>` for system entity types (for example,
  141. // `projects/-/locations/-/agents/-/entityTypes/sys.date`), or
  142. // `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  143. // ID>/entityTypes/<Entity Type ID>` for developer entity types.
  144. string entity_type = 2 [
  145. (google.api.field_behavior) = REQUIRED,
  146. (google.api.resource_reference) = {
  147. type: "dialogflow.googleapis.com/EntityType"
  148. }
  149. ];
  150. // Indicates whether the parameter represents a list of values.
  151. bool is_list = 3;
  152. // Indicates whether the parameter content should be redacted in log. If
  153. // redaction is enabled, the parameter content will be replaced by parameter
  154. // name during logging.
  155. // Note: the parameter content is subject to redaction if either parameter
  156. // level redaction or [entity type level redaction][google.cloud.dialogflow.cx.v3.EntityType.redact] is
  157. // enabled.
  158. bool redact = 4;
  159. }
  160. // The unique identifier of the intent.
  161. // Required for the [Intents.UpdateIntent][google.cloud.dialogflow.cx.v3.Intents.UpdateIntent] method. [Intents.CreateIntent][google.cloud.dialogflow.cx.v3.Intents.CreateIntent]
  162. // populates the name automatically.
  163. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  164. // ID>/intents/<Intent ID>`.
  165. string name = 1;
  166. // Required. The human-readable name of the intent, unique within the agent.
  167. string display_name = 2 [(google.api.field_behavior) = REQUIRED];
  168. // The collection of training phrases the agent is trained on to identify the
  169. // intent.
  170. repeated TrainingPhrase training_phrases = 3;
  171. // The collection of parameters associated with the intent.
  172. repeated Parameter parameters = 4;
  173. // The priority of this intent. Higher numbers represent higher
  174. // priorities.
  175. //
  176. // - If the supplied value is unspecified or 0, the service
  177. // translates the value to 500,000, which corresponds to the
  178. // `Normal` priority in the console.
  179. // - If the supplied value is negative, the intent is ignored
  180. // in runtime detect intent requests.
  181. int32 priority = 5;
  182. // Indicates whether this is a fallback intent. Currently only default
  183. // fallback intent is allowed in the agent, which is added upon agent
  184. // creation.
  185. // Adding training phrases to fallback intent is useful in the case of
  186. // requests that are mistakenly matched, since training phrases assigned to
  187. // fallback intents act as negative examples that triggers no-match event.
  188. bool is_fallback = 6;
  189. // The key/value metadata to label an intent. Labels can contain
  190. // lowercase letters, digits and the symbols '-' and '_'. International
  191. // characters are allowed, including letters from unicase alphabets. Keys must
  192. // start with a letter. Keys and values can be no longer than 63 characters
  193. // and no more than 128 bytes.
  194. //
  195. // Prefix "sys-" is reserved for Dialogflow defined labels. Currently allowed
  196. // Dialogflow defined labels include:
  197. // * sys-head
  198. // * sys-contextual
  199. // The above labels do not require value. "sys-head" means the intent is a
  200. // head intent. "sys.contextual" means the intent is a contextual intent.
  201. map<string, string> labels = 7;
  202. // Human readable description for better understanding an intent like its
  203. // scope, content, result etc. Maximum character limit: 140 characters.
  204. string description = 8;
  205. }
  206. // The request message for [Intents.ListIntents][google.cloud.dialogflow.cx.v3.Intents.ListIntents].
  207. message ListIntentsRequest {
  208. // Required. The agent to list all intents for.
  209. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  210. string parent = 1 [
  211. (google.api.field_behavior) = REQUIRED,
  212. (google.api.resource_reference) = {
  213. child_type: "dialogflow.googleapis.com/Intent"
  214. }
  215. ];
  216. // The language to list intents for. The following fields are language
  217. // dependent:
  218. //
  219. // * `Intent.training_phrases.parts.text`
  220. //
  221. // If not specified, the agent's default language is used.
  222. // [Many
  223. // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  224. // are supported.
  225. // Note: languages must be enabled in the agent before they can be used.
  226. string language_code = 2;
  227. // The resource view to apply to the returned intent.
  228. IntentView intent_view = 5;
  229. // The maximum number of items to return in a single page. By default 100 and
  230. // at most 1000.
  231. int32 page_size = 3;
  232. // The next_page_token value returned from a previous list request.
  233. string page_token = 4;
  234. }
  235. // The response message for [Intents.ListIntents][google.cloud.dialogflow.cx.v3.Intents.ListIntents].
  236. message ListIntentsResponse {
  237. // The list of intents. There will be a maximum number of items returned based
  238. // on the page_size field in the request.
  239. repeated Intent intents = 1;
  240. // Token to retrieve the next page of results, or empty if there are no more
  241. // results in the list.
  242. string next_page_token = 2;
  243. }
  244. // The request message for [Intents.GetIntent][google.cloud.dialogflow.cx.v3.Intents.GetIntent].
  245. message GetIntentRequest {
  246. // Required. The name of the intent.
  247. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  248. // ID>/intents/<Intent ID>`.
  249. string name = 1 [
  250. (google.api.field_behavior) = REQUIRED,
  251. (google.api.resource_reference) = {
  252. type: "dialogflow.googleapis.com/Intent"
  253. }
  254. ];
  255. // The language to retrieve the intent for. The following fields are language
  256. // dependent:
  257. //
  258. // * `Intent.training_phrases.parts.text`
  259. //
  260. // If not specified, the agent's default language is used.
  261. // [Many
  262. // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  263. // are supported.
  264. // Note: languages must be enabled in the agent before they can be used.
  265. string language_code = 2;
  266. }
  267. // The request message for [Intents.CreateIntent][google.cloud.dialogflow.cx.v3.Intents.CreateIntent].
  268. message CreateIntentRequest {
  269. // Required. The agent to create an intent for.
  270. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  271. string parent = 1 [
  272. (google.api.field_behavior) = REQUIRED,
  273. (google.api.resource_reference) = {
  274. child_type: "dialogflow.googleapis.com/Intent"
  275. }
  276. ];
  277. // Required. The intent to create.
  278. Intent intent = 2 [(google.api.field_behavior) = REQUIRED];
  279. // The language of the following fields in `intent`:
  280. //
  281. // * `Intent.training_phrases.parts.text`
  282. //
  283. // If not specified, the agent's default language is used.
  284. // [Many
  285. // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  286. // are supported.
  287. // Note: languages must be enabled in the agent before they can be used.
  288. string language_code = 3;
  289. }
  290. // The request message for [Intents.UpdateIntent][google.cloud.dialogflow.cx.v3.Intents.UpdateIntent].
  291. message UpdateIntentRequest {
  292. // Required. The intent to update.
  293. Intent intent = 1 [(google.api.field_behavior) = REQUIRED];
  294. // The language of the following fields in `intent`:
  295. //
  296. // * `Intent.training_phrases.parts.text`
  297. //
  298. // If not specified, the agent's default language is used.
  299. // [Many
  300. // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  301. // are supported.
  302. // Note: languages must be enabled in the agent before they can be used.
  303. string language_code = 2;
  304. // The mask to control which fields get updated. If the mask is not present,
  305. // all fields will be updated.
  306. google.protobuf.FieldMask update_mask = 3;
  307. }
  308. // The request message for [Intents.DeleteIntent][google.cloud.dialogflow.cx.v3.Intents.DeleteIntent].
  309. message DeleteIntentRequest {
  310. // Required. The name of the intent to delete.
  311. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  312. // ID>/intents/<Intent ID>`.
  313. string name = 1 [
  314. (google.api.field_behavior) = REQUIRED,
  315. (google.api.resource_reference) = {
  316. type: "dialogflow.googleapis.com/Intent"
  317. }
  318. ];
  319. }
  320. // Represents the options for views of an intent.
  321. // An intent can be a sizable object. Therefore, we provide a resource view that
  322. // does not return training phrases in the response.
  323. enum IntentView {
  324. // Not specified. Treated as INTENT_VIEW_FULL.
  325. INTENT_VIEW_UNSPECIFIED = 0;
  326. // Training phrases field is not populated in the response.
  327. INTENT_VIEW_PARTIAL = 1;
  328. // All fields are populated.
  329. INTENT_VIEW_FULL = 2;
  330. }