document.proto 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533
  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.v2beta1;
  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/cloud/dialogflow/v2beta1/gcs.proto";
  21. import "google/longrunning/operations.proto";
  22. import "google/protobuf/empty.proto";
  23. import "google/protobuf/field_mask.proto";
  24. import "google/protobuf/timestamp.proto";
  25. import "google/rpc/status.proto";
  26. option cc_enable_arenas = true;
  27. option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1";
  28. option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow";
  29. option java_multiple_files = true;
  30. option java_outer_classname = "DocumentProto";
  31. option java_package = "com.google.cloud.dialogflow.v2beta1";
  32. option objc_class_prefix = "DF";
  33. // Service for managing knowledge [Documents][google.cloud.dialogflow.v2beta1.Document].
  34. service Documents {
  35. option (google.api.default_host) = "dialogflow.googleapis.com";
  36. option (google.api.oauth_scopes) =
  37. "https://www.googleapis.com/auth/cloud-platform,"
  38. "https://www.googleapis.com/auth/dialogflow";
  39. // Returns the list of all documents of the knowledge base.
  40. //
  41. // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
  42. // only use `projects.knowledgeBases.documents`.
  43. rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) {
  44. option (google.api.http) = {
  45. get: "/v2beta1/{parent=projects/*/knowledgeBases/*}/documents"
  46. additional_bindings {
  47. get: "/v2beta1/{parent=projects/*/locations/*/knowledgeBases/*}/documents"
  48. }
  49. additional_bindings {
  50. get: "/v2beta1/{parent=projects/*/agent/knowledgeBases/*}/documents"
  51. }
  52. };
  53. option (google.api.method_signature) = "parent";
  54. }
  55. // Retrieves the specified document.
  56. //
  57. // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
  58. // only use `projects.knowledgeBases.documents`.
  59. rpc GetDocument(GetDocumentRequest) returns (Document) {
  60. option (google.api.http) = {
  61. get: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}"
  62. additional_bindings {
  63. get: "/v2beta1/{name=projects/*/locations/*/knowledgeBases/*/documents/*}"
  64. }
  65. additional_bindings {
  66. get: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}"
  67. }
  68. };
  69. option (google.api.method_signature) = "name";
  70. }
  71. // Creates a new document.
  72. //
  73. // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
  74. // only use `projects.knowledgeBases.documents`.
  75. rpc CreateDocument(CreateDocumentRequest) returns (google.longrunning.Operation) {
  76. option (google.api.http) = {
  77. post: "/v2beta1/{parent=projects/*/knowledgeBases/*}/documents"
  78. body: "document"
  79. additional_bindings {
  80. post: "/v2beta1/{parent=projects/*/locations/*/knowledgeBases/*}/documents"
  81. body: "document"
  82. }
  83. additional_bindings {
  84. post: "/v2beta1/{parent=projects/*/agent/knowledgeBases/*}/documents"
  85. body: "document"
  86. }
  87. };
  88. option (google.api.method_signature) = "parent,document";
  89. option (google.longrunning.operation_info) = {
  90. response_type: "Document"
  91. metadata_type: "KnowledgeOperationMetadata"
  92. };
  93. }
  94. // Create documents by importing data from external sources.
  95. // Dialogflow supports up to 350 documents in each request. If you try to
  96. // import more, Dialogflow will return an error.
  97. rpc ImportDocuments(ImportDocumentsRequest) returns (google.longrunning.Operation) {
  98. option (google.api.http) = {
  99. post: "/v2beta1/{parent=projects/*/knowledgeBases/*}/documents:import"
  100. body: "*"
  101. additional_bindings {
  102. post: "/v2beta1/{parent=projects/*/locations/*/knowledgeBases/*}/documents:import"
  103. body: "*"
  104. }
  105. };
  106. option (google.longrunning.operation_info) = {
  107. response_type: "ImportDocumentsResponse"
  108. metadata_type: "KnowledgeOperationMetadata"
  109. };
  110. }
  111. // Deletes the specified document.
  112. //
  113. // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
  114. // only use `projects.knowledgeBases.documents`.
  115. rpc DeleteDocument(DeleteDocumentRequest) returns (google.longrunning.Operation) {
  116. option (google.api.http) = {
  117. delete: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}"
  118. additional_bindings {
  119. delete: "/v2beta1/{name=projects/*/locations/*/knowledgeBases/*/documents/*}"
  120. }
  121. additional_bindings {
  122. delete: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}"
  123. }
  124. };
  125. option (google.api.method_signature) = "name";
  126. option (google.longrunning.operation_info) = {
  127. response_type: "google.protobuf.Empty"
  128. metadata_type: "KnowledgeOperationMetadata"
  129. };
  130. }
  131. // Updates the specified document.
  132. //
  133. // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
  134. // only use `projects.knowledgeBases.documents`.
  135. rpc UpdateDocument(UpdateDocumentRequest) returns (google.longrunning.Operation) {
  136. option (google.api.http) = {
  137. patch: "/v2beta1/{document.name=projects/*/knowledgeBases/*/documents/*}"
  138. body: "document"
  139. additional_bindings {
  140. patch: "/v2beta1/{document.name=projects/*/locations/*/knowledgeBases/*/documents/*}"
  141. body: "document"
  142. }
  143. additional_bindings {
  144. patch: "/v2beta1/{document.name=projects/*/agent/knowledgeBases/*/documents/*}"
  145. body: "document"
  146. }
  147. };
  148. option (google.api.method_signature) = "document,update_mask";
  149. option (google.api.method_signature) = "document";
  150. option (google.longrunning.operation_info) = {
  151. response_type: "Document"
  152. metadata_type: "KnowledgeOperationMetadata"
  153. };
  154. }
  155. // Reloads the specified document from its specified source, content_uri or
  156. // content. The previously loaded content of the document will be deleted.
  157. // Note: Even when the content of the document has not changed, there still
  158. // may be side effects because of internal implementation changes.
  159. // Note: If the document source is Google Cloud Storage URI, its metadata will
  160. // be replaced with the custom metadata from Google Cloud Storage if the
  161. // `import_gcs_custom_metadata` field is set to true in the request.
  162. //
  163. // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
  164. // only use `projects.knowledgeBases.documents`.
  165. rpc ReloadDocument(ReloadDocumentRequest) returns (google.longrunning.Operation) {
  166. option (google.api.http) = {
  167. post: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}:reload"
  168. body: "*"
  169. additional_bindings {
  170. post: "/v2beta1/{name=projects/*/locations/*/knowledgeBases/*/documents/*}:reload"
  171. body: "*"
  172. }
  173. additional_bindings {
  174. post: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}:reload"
  175. body: "*"
  176. }
  177. };
  178. option (google.api.method_signature) = "name,gcs_source";
  179. option (google.longrunning.operation_info) = {
  180. response_type: "Document"
  181. metadata_type: "KnowledgeOperationMetadata"
  182. };
  183. }
  184. }
  185. // A knowledge document to be used by a [KnowledgeBase][google.cloud.dialogflow.v2beta1.KnowledgeBase].
  186. //
  187. // For more information, see the [knowledge base
  188. // guide](https://cloud.google.com/dialogflow/docs/how/knowledge-bases).
  189. //
  190. // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
  191. // only use `projects.knowledgeBases.documents`.
  192. message Document {
  193. option (google.api.resource) = {
  194. type: "dialogflow.googleapis.com/Document"
  195. pattern: "projects/{project}/knowledgeBases/{knowledge_base}/documents/{document}"
  196. pattern: "projects/{project}/locations/{location}/knowledgeBases/{knowledge_base}/documents/{document}"
  197. };
  198. // The status of a reload attempt.
  199. message ReloadStatus {
  200. // Output only. The time of a reload attempt.
  201. // This reload may have been triggered automatically or manually and may
  202. // not have succeeded.
  203. google.protobuf.Timestamp time = 1;
  204. // Output only. The status of a reload attempt or the initial load.
  205. google.rpc.Status status = 2;
  206. }
  207. // The knowledge type of document content.
  208. enum KnowledgeType {
  209. // The type is unspecified or arbitrary.
  210. KNOWLEDGE_TYPE_UNSPECIFIED = 0;
  211. // The document content contains question and answer pairs as either HTML or
  212. // CSV. Typical FAQ HTML formats are parsed accurately, but unusual formats
  213. // may fail to be parsed.
  214. //
  215. // CSV must have questions in the first column and answers in the second,
  216. // with no header. Because of this explicit format, they are always parsed
  217. // accurately.
  218. FAQ = 1;
  219. // Documents for which unstructured text is extracted and used for
  220. // question answering.
  221. EXTRACTIVE_QA = 2;
  222. // The entire document content as a whole can be used for query results.
  223. // Only for Contact Center Solutions on Dialogflow.
  224. ARTICLE_SUGGESTION = 3;
  225. // The legacy enum for agent-facing smart reply feature.
  226. SMART_REPLY = 4;
  227. }
  228. // Optional. The document resource name.
  229. // The name must be empty when creating a document.
  230. // Format: `projects/<Project ID>/locations/<Location
  231. // ID>/knowledgeBases/<Knowledge Base ID>/documents/<Document ID>`.
  232. string name = 1 [(google.api.field_behavior) = OPTIONAL];
  233. // Required. The display name of the document. The name must be 1024 bytes or
  234. // less; otherwise, the creation request fails.
  235. string display_name = 2 [(google.api.field_behavior) = REQUIRED];
  236. // Required. The MIME type of this document.
  237. string mime_type = 3 [(google.api.field_behavior) = REQUIRED];
  238. // Required. The knowledge type of document content.
  239. repeated KnowledgeType knowledge_types = 4 [(google.api.field_behavior) = REQUIRED];
  240. // The source of this document.
  241. oneof source {
  242. // The URI where the file content is located.
  243. //
  244. // For documents stored in Google Cloud Storage, these URIs must have
  245. // the form `gs://<bucket-name>/<object-name>`.
  246. //
  247. // NOTE: External URLs must correspond to public webpages, i.e., they must
  248. // be indexed by Google Search. In particular, URLs for showing documents in
  249. // Google Cloud Storage (i.e. the URL in your browser) are not supported.
  250. // Instead use the `gs://` format URI described above.
  251. string content_uri = 5;
  252. // The raw content of the document. This field is only permitted for
  253. // EXTRACTIVE_QA and FAQ knowledge types.
  254. // Note: This field is in the process of being deprecated, please use
  255. // raw_content instead.
  256. string content = 6 [deprecated = true];
  257. // The raw content of the document. This field is only permitted for
  258. // EXTRACTIVE_QA and FAQ knowledge types.
  259. bytes raw_content = 9;
  260. }
  261. // Optional. If true, we try to automatically reload the document every day
  262. // (at a time picked by the system). If false or unspecified, we don't try
  263. // to automatically reload the document.
  264. //
  265. // Currently you can only enable automatic reload for documents sourced from
  266. // a public url, see `source` field for the source types.
  267. //
  268. // Reload status can be tracked in `latest_reload_status`. If a reload
  269. // fails, we will keep the document unchanged.
  270. //
  271. // If a reload fails with internal errors, the system will try to reload the
  272. // document on the next day.
  273. // If a reload fails with non-retriable errors (e.g. PERMISION_DENIED), the
  274. // system will not try to reload the document anymore. You need to manually
  275. // reload the document successfully by calling `ReloadDocument` and clear the
  276. // errors.
  277. bool enable_auto_reload = 11 [(google.api.field_behavior) = OPTIONAL];
  278. // Output only. The time and status of the latest reload.
  279. // This reload may have been triggered automatically or manually
  280. // and may not have succeeded.
  281. ReloadStatus latest_reload_status = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
  282. // Optional. Metadata for the document. The metadata supports arbitrary
  283. // key-value pairs. Suggested use cases include storing a document's title,
  284. // an external URL distinct from the document's content_uri, etc.
  285. // The max size of a `key` or a `value` of the metadata is 1024 bytes.
  286. map<string, string> metadata = 7 [(google.api.field_behavior) = OPTIONAL];
  287. }
  288. // Request message for [Documents.GetDocument][google.cloud.dialogflow.v2beta1.Documents.GetDocument].
  289. message GetDocumentRequest {
  290. // Required. The name of the document to retrieve.
  291. // Format `projects/<Project ID>/locations/<Location
  292. // ID>/knowledgeBases/<Knowledge Base ID>/documents/<Document ID>`.
  293. string name = 1 [
  294. (google.api.field_behavior) = REQUIRED,
  295. (google.api.resource_reference) = {
  296. type: "dialogflow.googleapis.com/Document"
  297. }
  298. ];
  299. }
  300. // Request message for [Documents.ListDocuments][google.cloud.dialogflow.v2beta1.Documents.ListDocuments].
  301. message ListDocumentsRequest {
  302. // Required. The knowledge base to list all documents for.
  303. // Format: `projects/<Project ID>/locations/<Location
  304. // ID>/knowledgeBases/<Knowledge Base ID>`.
  305. string parent = 1 [
  306. (google.api.field_behavior) = REQUIRED,
  307. (google.api.resource_reference) = {
  308. child_type: "dialogflow.googleapis.com/Document"
  309. }
  310. ];
  311. // The maximum number of items to return in a single page. By
  312. // default 10 and at most 100.
  313. int32 page_size = 2;
  314. // The next_page_token value returned from a previous list request.
  315. string page_token = 3;
  316. // The filter expression used to filter documents returned by the list method.
  317. // The expression has the following syntax:
  318. //
  319. // <field> <operator> <value> [AND <field> <operator> <value>] ...
  320. //
  321. // The following fields and operators are supported:
  322. //
  323. // * knowledge_types with has(:) operator
  324. // * display_name with has(:) operator
  325. // * state with equals(=) operator
  326. //
  327. // Examples:
  328. //
  329. // * "knowledge_types:FAQ" matches documents with FAQ knowledge type.
  330. // * "display_name:customer" matches documents whose display name contains
  331. // "customer".
  332. // * "state=ACTIVE" matches documents with ACTIVE state.
  333. // * "knowledge_types:FAQ AND state=ACTIVE" matches all active FAQ documents.
  334. //
  335. // For more information about filtering, see
  336. // [API Filtering](https://aip.dev/160).
  337. string filter = 4;
  338. }
  339. // Response message for [Documents.ListDocuments][google.cloud.dialogflow.v2beta1.Documents.ListDocuments].
  340. message ListDocumentsResponse {
  341. // The list of documents.
  342. repeated Document documents = 1;
  343. // Token to retrieve the next page of results, or empty if there are no
  344. // more results in the list.
  345. string next_page_token = 2;
  346. }
  347. // Request message for [Documents.CreateDocument][google.cloud.dialogflow.v2beta1.Documents.CreateDocument].
  348. message CreateDocumentRequest {
  349. // Required. The knowledge base to create a document for.
  350. // Format: `projects/<Project ID>/locations/<Location
  351. // ID>/knowledgeBases/<Knowledge Base ID>`.
  352. string parent = 1 [
  353. (google.api.field_behavior) = REQUIRED,
  354. (google.api.resource_reference) = {
  355. child_type: "dialogflow.googleapis.com/Document"
  356. }
  357. ];
  358. // Required. The document to create.
  359. Document document = 2 [(google.api.field_behavior) = REQUIRED];
  360. // Whether to import custom metadata from Google Cloud Storage.
  361. // Only valid when the document source is Google Cloud Storage URI.
  362. bool import_gcs_custom_metadata = 3;
  363. }
  364. // Request message for [Documents.ImportDocuments][google.cloud.dialogflow.v2beta1.Documents.ImportDocuments].
  365. message ImportDocumentsRequest {
  366. // Required. The knowledge base to import documents into.
  367. // Format: `projects/<Project ID>/locations/<Location
  368. // ID>/knowledgeBases/<Knowledge Base ID>`.
  369. string parent = 1 [
  370. (google.api.field_behavior) = REQUIRED,
  371. (google.api.resource_reference) = {
  372. child_type: "dialogflow.googleapis.com/Document"
  373. }
  374. ];
  375. // Required. The source to use for importing documents.
  376. //
  377. // If the source captures multiple objects, then multiple documents will be
  378. // created, one corresponding to each object, and all of these documents will
  379. // be created using the same document template.
  380. //
  381. // Dialogflow supports up to 350 documents in each request. If you try to
  382. // import more, Dialogflow will return an error.
  383. oneof source {
  384. // The Google Cloud Storage location for the documents.
  385. // The path can include a wildcard.
  386. //
  387. // These URIs may have the forms
  388. // `gs://<bucket-name>/<object-name>`.
  389. // `gs://<bucket-name>/<object-path>/*.<extension>`.
  390. GcsSources gcs_source = 2;
  391. }
  392. // Required. Document template used for importing all the documents.
  393. ImportDocumentTemplate document_template = 3 [(google.api.field_behavior) = REQUIRED];
  394. // Whether to import custom metadata from Google Cloud Storage.
  395. // Only valid when the document source is Google Cloud Storage URI.
  396. bool import_gcs_custom_metadata = 4;
  397. }
  398. // The template used for importing documents.
  399. message ImportDocumentTemplate {
  400. // Required. The MIME type of the document.
  401. string mime_type = 1 [(google.api.field_behavior) = REQUIRED];
  402. // Required. The knowledge type of document content.
  403. repeated Document.KnowledgeType knowledge_types = 2 [(google.api.field_behavior) = REQUIRED];
  404. // Metadata for the document. The metadata supports arbitrary
  405. // key-value pairs. Suggested use cases include storing a document's title,
  406. // an external URL distinct from the document's content_uri, etc.
  407. // The max size of a `key` or a `value` of the metadata is 1024 bytes.
  408. map<string, string> metadata = 3;
  409. }
  410. // Response message for [Documents.ImportDocuments][google.cloud.dialogflow.v2beta1.Documents.ImportDocuments].
  411. message ImportDocumentsResponse {
  412. // Includes details about skipped documents or any other warnings.
  413. repeated google.rpc.Status warnings = 1;
  414. }
  415. // Request message for [Documents.DeleteDocument][google.cloud.dialogflow.v2beta1.Documents.DeleteDocument].
  416. message DeleteDocumentRequest {
  417. // Required. The name of the document to delete.
  418. // Format: `projects/<Project ID>/locations/<Location
  419. // ID>/knowledgeBases/<Knowledge Base ID>/documents/<Document ID>`.
  420. string name = 1 [
  421. (google.api.field_behavior) = REQUIRED,
  422. (google.api.resource_reference) = {
  423. type: "dialogflow.googleapis.com/Document"
  424. }
  425. ];
  426. }
  427. // Request message for [Documents.UpdateDocument][google.cloud.dialogflow.v2beta1.Documents.UpdateDocument].
  428. message UpdateDocumentRequest {
  429. // Required. The document to update.
  430. Document document = 1 [(google.api.field_behavior) = REQUIRED];
  431. // Optional. Not specified means `update all`.
  432. // Currently, only `display_name` can be updated, an InvalidArgument will be
  433. // returned for attempting to update other fields.
  434. google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = OPTIONAL];
  435. }
  436. // Metadata in google::longrunning::Operation for Knowledge operations.
  437. message KnowledgeOperationMetadata {
  438. // States of the operation.
  439. enum State {
  440. // State unspecified.
  441. STATE_UNSPECIFIED = 0;
  442. // The operation has been created.
  443. PENDING = 1;
  444. // The operation is currently running.
  445. RUNNING = 2;
  446. // The operation is done, either cancelled or completed.
  447. DONE = 3;
  448. }
  449. // Required. Output only. The current state of this operation.
  450. State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  451. }
  452. // Request message for [Documents.ReloadDocument][google.cloud.dialogflow.v2beta1.Documents.ReloadDocument].
  453. message ReloadDocumentRequest {
  454. // Required. The name of the document to reload.
  455. // Format: `projects/<Project ID>/locations/<Location
  456. // ID>/knowledgeBases/<Knowledge Base ID>/documents/<Document ID>`
  457. string name = 1 [
  458. (google.api.field_behavior) = REQUIRED,
  459. (google.api.resource_reference) = {
  460. type: "dialogflow.googleapis.com/Document"
  461. }
  462. ];
  463. // The source for document reloading.
  464. // Optional. If provided, the service will load the contents from the source
  465. // and update document in the knowledge base.
  466. oneof source {
  467. // The path for a Cloud Storage source file for reloading document content.
  468. // If not provided, the Document's existing source will be reloaded.
  469. GcsSource gcs_source = 3;
  470. }
  471. // Whether to import custom metadata from Google Cloud Storage.
  472. // Only valid when the document source is Google Cloud Storage URI.
  473. bool import_gcs_custom_metadata = 4;
  474. }