1// Copyright 2022 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 15syntax = "proto3"; 16 17package google.cloud.discoveryengine.v1; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/cloud/discoveryengine/v1/document.proto"; 24import "google/cloud/discoveryengine/v1/import_config.proto"; 25import "google/cloud/discoveryengine/v1/purge_config.proto"; 26import "google/longrunning/operations.proto"; 27import "google/protobuf/empty.proto"; 28import "google/protobuf/field_mask.proto"; 29 30option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1"; 31option go_package = "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb;discoveryenginepb"; 32option java_multiple_files = true; 33option java_outer_classname = "DocumentServiceProto"; 34option java_package = "com.google.cloud.discoveryengine.v1"; 35option objc_class_prefix = "DISCOVERYENGINE"; 36option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1"; 37option ruby_package = "Google::Cloud::DiscoveryEngine::V1"; 38 39// Service for ingesting [Document][google.cloud.discoveryengine.v1.Document] 40// information of the customer's website. 41service DocumentService { 42 option (google.api.default_host) = "discoveryengine.googleapis.com"; 43 option (google.api.oauth_scopes) = 44 "https://www.googleapis.com/auth/cloud-platform"; 45 46 // Gets a [Document][google.cloud.discoveryengine.v1.Document]. 47 rpc GetDocument(GetDocumentRequest) returns (Document) { 48 option (google.api.http) = { 49 get: "/v1/{name=projects/*/locations/*/dataStores/*/branches/*/documents/*}" 50 additional_bindings { 51 get: "/v1/{name=projects/*/locations/*/collections/*/dataStores/*/branches/*/documents/*}" 52 } 53 }; 54 option (google.api.method_signature) = "name"; 55 } 56 57 // Gets a list of [Document][google.cloud.discoveryengine.v1.Document]s. 58 rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) { 59 option (google.api.http) = { 60 get: "/v1/{parent=projects/*/locations/*/dataStores/*/branches/*}/documents" 61 additional_bindings { 62 get: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*/branches/*}/documents" 63 } 64 }; 65 option (google.api.method_signature) = "parent"; 66 } 67 68 // Creates a [Document][google.cloud.discoveryengine.v1.Document]. 69 rpc CreateDocument(CreateDocumentRequest) returns (Document) { 70 option (google.api.http) = { 71 post: "/v1/{parent=projects/*/locations/*/dataStores/*/branches/*}/documents" 72 body: "document" 73 additional_bindings { 74 post: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*/branches/*}/documents" 75 body: "document" 76 } 77 }; 78 option (google.api.method_signature) = "parent,document,document_id"; 79 } 80 81 // Updates a [Document][google.cloud.discoveryengine.v1.Document]. 82 rpc UpdateDocument(UpdateDocumentRequest) returns (Document) { 83 option (google.api.http) = { 84 patch: "/v1/{document.name=projects/*/locations/*/dataStores/*/branches/*/documents/*}" 85 body: "document" 86 additional_bindings { 87 patch: "/v1/{document.name=projects/*/locations/*/collections/*/dataStores/*/branches/*/documents/*}" 88 body: "document" 89 } 90 }; 91 option (google.api.method_signature) = "document,update_mask"; 92 } 93 94 // Deletes a [Document][google.cloud.discoveryengine.v1.Document]. 95 rpc DeleteDocument(DeleteDocumentRequest) returns (google.protobuf.Empty) { 96 option (google.api.http) = { 97 delete: "/v1/{name=projects/*/locations/*/dataStores/*/branches/*/documents/*}" 98 additional_bindings { 99 delete: "/v1/{name=projects/*/locations/*/collections/*/dataStores/*/branches/*/documents/*}" 100 } 101 }; 102 option (google.api.method_signature) = "name"; 103 } 104 105 // Bulk import of multiple 106 // [Document][google.cloud.discoveryengine.v1.Document]s. Request processing 107 // may be synchronous. Non-existing items will be created. 108 // 109 // Note: It is possible for a subset of the 110 // [Document][google.cloud.discoveryengine.v1.Document]s to be successfully 111 // updated. 112 rpc ImportDocuments(ImportDocumentsRequest) 113 returns (google.longrunning.Operation) { 114 option (google.api.http) = { 115 post: "/v1/{parent=projects/*/locations/*/dataStores/*/branches/*}/documents:import" 116 body: "*" 117 additional_bindings { 118 post: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*/branches/*}/documents:import" 119 body: "*" 120 } 121 }; 122 option (google.longrunning.operation_info) = { 123 response_type: "google.cloud.discoveryengine.v1.ImportDocumentsResponse" 124 metadata_type: "google.cloud.discoveryengine.v1.ImportDocumentsMetadata" 125 }; 126 } 127 128 // Permanently deletes all selected 129 // [Document][google.cloud.discoveryengine.v1.Document]s in a branch. 130 // 131 // This process is asynchronous. Depending on the number of 132 // [Document][google.cloud.discoveryengine.v1.Document]s to be deleted, this 133 // operation can take hours to complete. Before the delete operation 134 // completes, some [Document][google.cloud.discoveryengine.v1.Document]s might 135 // still be returned by 136 // [DocumentService.GetDocument][google.cloud.discoveryengine.v1.DocumentService.GetDocument] 137 // or 138 // [DocumentService.ListDocuments][google.cloud.discoveryengine.v1.DocumentService.ListDocuments]. 139 // 140 // To get a list of the [Document][google.cloud.discoveryengine.v1.Document]s 141 // to be deleted, set 142 // [PurgeDocumentsRequest.force][google.cloud.discoveryengine.v1.PurgeDocumentsRequest.force] 143 // to false. 144 rpc PurgeDocuments(PurgeDocumentsRequest) 145 returns (google.longrunning.Operation) { 146 option (google.api.http) = { 147 post: "/v1/{parent=projects/*/locations/*/dataStores/*/branches/*}/documents:purge" 148 body: "*" 149 additional_bindings { 150 post: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*/branches/*}/documents:purge" 151 body: "*" 152 } 153 }; 154 option (google.longrunning.operation_info) = { 155 response_type: "google.cloud.discoveryengine.v1.PurgeDocumentsResponse" 156 metadata_type: "google.cloud.discoveryengine.v1.PurgeDocumentsMetadata" 157 }; 158 } 159} 160 161// Request message for 162// [DocumentService.GetDocument][google.cloud.discoveryengine.v1.DocumentService.GetDocument] 163// method. 164message GetDocumentRequest { 165 // Required. Full resource name of 166 // [Document][google.cloud.discoveryengine.v1.Document], such as 167 // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}/documents/{document}`. 168 // 169 // If the caller does not have permission to access the 170 // [Document][google.cloud.discoveryengine.v1.Document], regardless of whether 171 // or not it exists, a `PERMISSION_DENIED` error is returned. 172 // 173 // If the requested [Document][google.cloud.discoveryengine.v1.Document] does 174 // not exist, a `NOT_FOUND` error is returned. 175 string name = 1 [ 176 (google.api.field_behavior) = REQUIRED, 177 (google.api.resource_reference) = { 178 type: "discoveryengine.googleapis.com/Document" 179 } 180 ]; 181} 182 183// Request message for 184// [DocumentService.ListDocuments][google.cloud.discoveryengine.v1.DocumentService.ListDocuments] 185// method. 186message ListDocumentsRequest { 187 // Required. The parent branch resource name, such as 188 // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}`. 189 // Use `default_branch` as the branch ID, to list documents under the default 190 // branch. 191 // 192 // If the caller does not have permission to list 193 // [Document][google.cloud.discoveryengine.v1.Document]s under this branch, 194 // regardless of whether or not this branch exists, a `PERMISSION_DENIED` 195 // error is returned. 196 string parent = 1 [ 197 (google.api.field_behavior) = REQUIRED, 198 (google.api.resource_reference) = { 199 type: "discoveryengine.googleapis.com/Branch" 200 } 201 ]; 202 203 // Maximum number of [Document][google.cloud.discoveryengine.v1.Document]s to 204 // return. If unspecified, defaults to 100. The maximum allowed value is 1000. 205 // Values above 1000 will be coerced to 1000. 206 // 207 // If this field is negative, an `INVALID_ARGUMENT` error is returned. 208 int32 page_size = 2; 209 210 // A page token 211 // [ListDocumentsResponse.next_page_token][google.cloud.discoveryengine.v1.ListDocumentsResponse.next_page_token], 212 // received from a previous 213 // [DocumentService.ListDocuments][google.cloud.discoveryengine.v1.DocumentService.ListDocuments] 214 // call. Provide this to retrieve the subsequent page. 215 // 216 // When paginating, all other parameters provided to 217 // [DocumentService.ListDocuments][google.cloud.discoveryengine.v1.DocumentService.ListDocuments] 218 // must match the call that provided the page token. Otherwise, an 219 // `INVALID_ARGUMENT` error is returned. 220 string page_token = 3; 221} 222 223// Response message for 224// [DocumentService.ListDocuments][google.cloud.discoveryengine.v1.DocumentService.ListDocuments] 225// method. 226message ListDocumentsResponse { 227 // The [Document][google.cloud.discoveryengine.v1.Document]s. 228 repeated Document documents = 1; 229 230 // A token that can be sent as 231 // [ListDocumentsRequest.page_token][google.cloud.discoveryengine.v1.ListDocumentsRequest.page_token] 232 // to retrieve the next page. If this field is omitted, there are no 233 // subsequent pages. 234 string next_page_token = 2; 235} 236 237// Request message for 238// [DocumentService.CreateDocument][google.cloud.discoveryengine.v1.DocumentService.CreateDocument] 239// method. 240message CreateDocumentRequest { 241 // Required. The parent resource name, such as 242 // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}`. 243 string parent = 1 [ 244 (google.api.field_behavior) = REQUIRED, 245 (google.api.resource_reference) = { 246 type: "discoveryengine.googleapis.com/Branch" 247 } 248 ]; 249 250 // Required. The [Document][google.cloud.discoveryengine.v1.Document] to 251 // create. 252 Document document = 2 [(google.api.field_behavior) = REQUIRED]; 253 254 // Required. The ID to use for the 255 // [Document][google.cloud.discoveryengine.v1.Document], which will become the 256 // final component of the 257 // [Document.name][google.cloud.discoveryengine.v1.Document.name]. 258 // 259 // If the caller does not have permission to create the 260 // [Document][google.cloud.discoveryengine.v1.Document], regardless of whether 261 // or not it exists, a `PERMISSION_DENIED` error is returned. 262 // 263 // This field must be unique among all 264 // [Document][google.cloud.discoveryengine.v1.Document]s with the same 265 // [parent][google.cloud.discoveryengine.v1.CreateDocumentRequest.parent]. 266 // Otherwise, an `ALREADY_EXISTS` error is returned. 267 // 268 // This field must conform to [RFC-1034](https://tools.ietf.org/html/rfc1034) 269 // standard with a length limit of 63 characters. Otherwise, an 270 // `INVALID_ARGUMENT` error is returned. 271 string document_id = 3 [(google.api.field_behavior) = REQUIRED]; 272} 273 274// Request message for 275// [DocumentService.UpdateDocument][google.cloud.discoveryengine.v1.DocumentService.UpdateDocument] 276// method. 277message UpdateDocumentRequest { 278 // Required. The document to update/create. 279 // 280 // If the caller does not have permission to update the 281 // [Document][google.cloud.discoveryengine.v1.Document], regardless of whether 282 // or not it exists, a `PERMISSION_DENIED` error is returned. 283 // 284 // If the [Document][google.cloud.discoveryengine.v1.Document] to update does 285 // not exist and 286 // [allow_missing][google.cloud.discoveryengine.v1.UpdateDocumentRequest.allow_missing] 287 // is not set, a `NOT_FOUND` error is returned. 288 Document document = 1 [(google.api.field_behavior) = REQUIRED]; 289 290 // If set to true, and the 291 // [Document][google.cloud.discoveryengine.v1.Document] is not found, a new 292 // [Document][google.cloud.discoveryengine.v1.Document] will be created. 293 bool allow_missing = 2; 294 295 // Indicates which fields in the provided imported 'document' to update. If 296 // not set, will by default update all fields. 297 google.protobuf.FieldMask update_mask = 3; 298} 299 300// Request message for 301// [DocumentService.DeleteDocument][google.cloud.discoveryengine.v1.DocumentService.DeleteDocument] 302// method. 303message DeleteDocumentRequest { 304 // Required. Full resource name of 305 // [Document][google.cloud.discoveryengine.v1.Document], such as 306 // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}/documents/{document}`. 307 // 308 // If the caller does not have permission to delete the 309 // [Document][google.cloud.discoveryengine.v1.Document], regardless of whether 310 // or not it exists, a `PERMISSION_DENIED` error is returned. 311 // 312 // If the [Document][google.cloud.discoveryengine.v1.Document] to delete does 313 // not exist, a `NOT_FOUND` error is returned. 314 string name = 1 [ 315 (google.api.field_behavior) = REQUIRED, 316 (google.api.resource_reference) = { 317 type: "discoveryengine.googleapis.com/Document" 318 } 319 ]; 320} 321