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 15syntax = "proto3"; 16 17package google.cloud.retail.v2alpha; 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/retail/v2alpha/catalog.proto"; 24import "google/protobuf/empty.proto"; 25import "google/protobuf/field_mask.proto"; 26import "google/protobuf/timestamp.proto"; 27 28option csharp_namespace = "Google.Cloud.Retail.V2Alpha"; 29option go_package = "cloud.google.com/go/retail/apiv2alpha/retailpb;retailpb"; 30option java_multiple_files = true; 31option java_outer_classname = "CatalogServiceProto"; 32option java_package = "com.google.cloud.retail.v2alpha"; 33option objc_class_prefix = "RETAIL"; 34option php_namespace = "Google\\Cloud\\Retail\\V2alpha"; 35option ruby_package = "Google::Cloud::Retail::V2alpha"; 36 37// Service for managing catalog configuration. 38service CatalogService { 39 option (google.api.default_host) = "retail.googleapis.com"; 40 option (google.api.oauth_scopes) = 41 "https://www.googleapis.com/auth/cloud-platform"; 42 43 // Lists all the [Catalog][google.cloud.retail.v2alpha.Catalog]s associated 44 // with the project. 45 rpc ListCatalogs(ListCatalogsRequest) returns (ListCatalogsResponse) { 46 option (google.api.http) = { 47 get: "/v2alpha/{parent=projects/*/locations/*}/catalogs" 48 }; 49 option (google.api.method_signature) = "parent"; 50 } 51 52 // Updates the [Catalog][google.cloud.retail.v2alpha.Catalog]s. 53 rpc UpdateCatalog(UpdateCatalogRequest) returns (Catalog) { 54 option (google.api.http) = { 55 patch: "/v2alpha/{catalog.name=projects/*/locations/*/catalogs/*}" 56 body: "catalog" 57 }; 58 option (google.api.method_signature) = "catalog,update_mask"; 59 } 60 61 // Set a specified branch id as default branch. API methods such as 62 // [SearchService.Search][google.cloud.retail.v2alpha.SearchService.Search], 63 // [ProductService.GetProduct][google.cloud.retail.v2alpha.ProductService.GetProduct], 64 // [ProductService.ListProducts][google.cloud.retail.v2alpha.ProductService.ListProducts] 65 // will treat requests using "default_branch" to the actual branch id set as 66 // default. 67 // 68 // For example, if `projects/*/locations/*/catalogs/*/branches/1` is set as 69 // default, setting 70 // [SearchRequest.branch][google.cloud.retail.v2alpha.SearchRequest.branch] to 71 // `projects/*/locations/*/catalogs/*/branches/default_branch` is equivalent 72 // to setting 73 // [SearchRequest.branch][google.cloud.retail.v2alpha.SearchRequest.branch] to 74 // `projects/*/locations/*/catalogs/*/branches/1`. 75 // 76 // Using multiple branches can be useful when developers would like 77 // to have a staging branch to test and verify for future usage. When it 78 // becomes ready, developers switch on the staging branch using this API while 79 // keeping using `projects/*/locations/*/catalogs/*/branches/default_branch` 80 // as [SearchRequest.branch][google.cloud.retail.v2alpha.SearchRequest.branch] 81 // to route the traffic to this staging branch. 82 // 83 // CAUTION: If you have live predict/search traffic, switching the default 84 // branch could potentially cause outages if the ID space of the new branch is 85 // very different from the old one. 86 // 87 // More specifically: 88 // 89 // * PredictionService will only return product IDs from branch {newBranch}. 90 // * SearchService will only return product IDs from branch {newBranch} 91 // (if branch is not explicitly set). 92 // * UserEventService will only join events with products from branch 93 // {newBranch}. 94 rpc SetDefaultBranch(SetDefaultBranchRequest) 95 returns (google.protobuf.Empty) { 96 option (google.api.http) = { 97 post: "/v2alpha/{catalog=projects/*/locations/*/catalogs/*}:setDefaultBranch" 98 body: "*" 99 }; 100 option (google.api.method_signature) = "catalog"; 101 } 102 103 // Get which branch is currently default branch set by 104 // [CatalogService.SetDefaultBranch][google.cloud.retail.v2alpha.CatalogService.SetDefaultBranch] 105 // method under a specified parent catalog. 106 rpc GetDefaultBranch(GetDefaultBranchRequest) 107 returns (GetDefaultBranchResponse) { 108 option (google.api.http) = { 109 get: "/v2alpha/{catalog=projects/*/locations/*/catalogs/*}:getDefaultBranch" 110 }; 111 option (google.api.method_signature) = "catalog"; 112 } 113 114 // Gets a [CompletionConfig][google.cloud.retail.v2alpha.CompletionConfig]. 115 rpc GetCompletionConfig(GetCompletionConfigRequest) 116 returns (CompletionConfig) { 117 option (google.api.http) = { 118 get: "/v2alpha/{name=projects/*/locations/*/catalogs/*/completionConfig}" 119 }; 120 option (google.api.method_signature) = "name"; 121 } 122 123 // Updates the 124 // [CompletionConfig][google.cloud.retail.v2alpha.CompletionConfig]s. 125 rpc UpdateCompletionConfig(UpdateCompletionConfigRequest) 126 returns (CompletionConfig) { 127 option (google.api.http) = { 128 patch: "/v2alpha/{completion_config.name=projects/*/locations/*/catalogs/*/completionConfig}" 129 body: "completion_config" 130 }; 131 option (google.api.method_signature) = "completion_config,update_mask"; 132 } 133 134 // Gets an [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig]. 135 rpc GetAttributesConfig(GetAttributesConfigRequest) 136 returns (AttributesConfig) { 137 option (google.api.http) = { 138 get: "/v2alpha/{name=projects/*/locations/*/catalogs/*/attributesConfig}" 139 }; 140 option (google.api.method_signature) = "name"; 141 } 142 143 // Updates the 144 // [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig]. 145 // 146 // The catalog attributes in the request will be updated in the catalog, or 147 // inserted if they do not exist. Existing catalog attributes not included in 148 // the request will remain unchanged. Attributes that are assigned to 149 // products, but do not exist at the catalog level, are always included in the 150 // response. The product attribute is assigned default values for missing 151 // catalog attribute fields, e.g., searchable and dynamic facetable options. 152 rpc UpdateAttributesConfig(UpdateAttributesConfigRequest) 153 returns (AttributesConfig) { 154 option (google.api.http) = { 155 patch: "/v2alpha/{attributes_config.name=projects/*/locations/*/catalogs/*/attributesConfig}" 156 body: "attributes_config" 157 }; 158 option (google.api.method_signature) = "attributes_config,update_mask"; 159 } 160 161 // Adds the specified 162 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] to the 163 // [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig]. 164 // 165 // If the [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] to 166 // add already exists, an ALREADY_EXISTS error is returned. 167 rpc AddCatalogAttribute(AddCatalogAttributeRequest) 168 returns (AttributesConfig) { 169 option (google.api.http) = { 170 post: "/v2alpha/{attributes_config=projects/*/locations/*/catalogs/*/attributesConfig}:addCatalogAttribute" 171 body: "*" 172 }; 173 } 174 175 // Removes the specified 176 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] from the 177 // [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig]. 178 // 179 // If the [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] to 180 // remove does not exist, a NOT_FOUND error is returned. 181 rpc RemoveCatalogAttribute(RemoveCatalogAttributeRequest) 182 returns (AttributesConfig) { 183 option (google.api.http) = { 184 post: "/v2alpha/{attributes_config=projects/*/locations/*/catalogs/*/attributesConfig}:removeCatalogAttribute" 185 body: "*" 186 }; 187 } 188 189 // Removes all specified 190 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute]s from the 191 // [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig]. 192 rpc BatchRemoveCatalogAttributes(BatchRemoveCatalogAttributesRequest) 193 returns (BatchRemoveCatalogAttributesResponse) { 194 option (google.api.http) = { 195 post: "/v2alpha/{attributes_config=projects/*/locations/*/catalogs/*/attributesConfig}:batchRemoveCatalogAttributes" 196 body: "*" 197 }; 198 } 199 200 // Replaces the specified 201 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] in the 202 // [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig] by 203 // updating the catalog attribute with the same 204 // [CatalogAttribute.key][google.cloud.retail.v2alpha.CatalogAttribute.key]. 205 // 206 // If the [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] to 207 // replace does not exist, a NOT_FOUND error is returned. 208 rpc ReplaceCatalogAttribute(ReplaceCatalogAttributeRequest) 209 returns (AttributesConfig) { 210 option (google.api.http) = { 211 post: "/v2alpha/{attributes_config=projects/*/locations/*/catalogs/*/attributesConfig}:replaceCatalogAttribute" 212 body: "*" 213 }; 214 } 215} 216 217// Request for 218// [CatalogService.ListCatalogs][google.cloud.retail.v2alpha.CatalogService.ListCatalogs] 219// method. 220message ListCatalogsRequest { 221 // Required. The account resource name with an associated location. 222 // 223 // If the caller does not have permission to list 224 // [Catalog][google.cloud.retail.v2alpha.Catalog]s under this location, 225 // regardless of whether or not this location exists, a PERMISSION_DENIED 226 // error is returned. 227 string parent = 1 [ 228 (google.api.field_behavior) = REQUIRED, 229 (google.api.resource_reference) = { 230 type: "locations.googleapis.com/Location" 231 } 232 ]; 233 234 // Maximum number of [Catalog][google.cloud.retail.v2alpha.Catalog]s to 235 // return. If unspecified, defaults to 50. The maximum allowed value is 1000. 236 // Values above 1000 will be coerced to 1000. 237 // 238 // If this field is negative, an INVALID_ARGUMENT is returned. 239 int32 page_size = 2; 240 241 // A page token 242 // [ListCatalogsResponse.next_page_token][google.cloud.retail.v2alpha.ListCatalogsResponse.next_page_token], 243 // received from a previous 244 // [CatalogService.ListCatalogs][google.cloud.retail.v2alpha.CatalogService.ListCatalogs] 245 // call. Provide this to retrieve the subsequent page. 246 // 247 // When paginating, all other parameters provided to 248 // [CatalogService.ListCatalogs][google.cloud.retail.v2alpha.CatalogService.ListCatalogs] 249 // must match the call that provided the page token. Otherwise, an 250 // INVALID_ARGUMENT error is returned. 251 string page_token = 3; 252} 253 254// Response for 255// [CatalogService.ListCatalogs][google.cloud.retail.v2alpha.CatalogService.ListCatalogs] 256// method. 257message ListCatalogsResponse { 258 // All the customer's [Catalog][google.cloud.retail.v2alpha.Catalog]s. 259 repeated Catalog catalogs = 1; 260 261 // A token that can be sent as 262 // [ListCatalogsRequest.page_token][google.cloud.retail.v2alpha.ListCatalogsRequest.page_token] 263 // to retrieve the next page. If this field is omitted, there are no 264 // subsequent pages. 265 string next_page_token = 2; 266} 267 268// Request for 269// [CatalogService.UpdateCatalog][google.cloud.retail.v2alpha.CatalogService.UpdateCatalog] 270// method. 271message UpdateCatalogRequest { 272 // Required. The [Catalog][google.cloud.retail.v2alpha.Catalog] to update. 273 // 274 // If the caller does not have permission to update the 275 // [Catalog][google.cloud.retail.v2alpha.Catalog], regardless of whether or 276 // not it exists, a PERMISSION_DENIED error is returned. 277 // 278 // If the [Catalog][google.cloud.retail.v2alpha.Catalog] to update does not 279 // exist, a NOT_FOUND error is returned. 280 Catalog catalog = 1 [(google.api.field_behavior) = REQUIRED]; 281 282 // Indicates which fields in the provided 283 // [Catalog][google.cloud.retail.v2alpha.Catalog] to update. 284 // 285 // If an unsupported or unknown field is provided, an INVALID_ARGUMENT error 286 // is returned. 287 google.protobuf.FieldMask update_mask = 2; 288} 289 290// Request message to set a specified branch as new default_branch. 291message SetDefaultBranchRequest { 292 // Full resource name of the catalog, such as 293 // `projects/*/locations/global/catalogs/default_catalog`. 294 string catalog = 1 [ 295 (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" } 296 ]; 297 298 // The final component of the resource name of a branch. 299 // 300 // This field must be one of "0", "1" or "2". Otherwise, an INVALID_ARGUMENT 301 // error is returned. 302 // 303 // If there are no sufficient active products in the targeted branch and 304 // [force][google.cloud.retail.v2alpha.SetDefaultBranchRequest.force] is not 305 // set, a FAILED_PRECONDITION error is returned. 306 string branch_id = 2 [ 307 (google.api.resource_reference) = { type: "retail.googleapis.com/Branch" } 308 ]; 309 310 // Some note on this request, this can be retrieved by 311 // [CatalogService.GetDefaultBranch][google.cloud.retail.v2alpha.CatalogService.GetDefaultBranch] 312 // before next valid default branch set occurs. 313 // 314 // This field must be a UTF-8 encoded string with a length limit of 1,000 315 // characters. Otherwise, an INVALID_ARGUMENT error is returned. 316 string note = 3; 317 318 // If set to true, it permits switching to a branch with 319 // [branch_id][google.cloud.retail.v2alpha.SetDefaultBranchRequest.branch_id] 320 // even if it has no sufficient active products. 321 bool force = 4; 322} 323 324// Request message to show which branch is currently the default branch. 325message GetDefaultBranchRequest { 326 // The parent catalog resource name, such as 327 // `projects/*/locations/global/catalogs/default_catalog`. 328 string catalog = 1 [ 329 (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" } 330 ]; 331} 332 333// Response message of 334// [CatalogService.GetDefaultBranch][google.cloud.retail.v2alpha.CatalogService.GetDefaultBranch]. 335message GetDefaultBranchResponse { 336 // Full resource name of the branch id currently set as default branch. 337 string branch = 1 [ 338 (google.api.resource_reference) = { type: "retail.googleapis.com/Branch" } 339 ]; 340 341 // The time when this branch is set to default. 342 google.protobuf.Timestamp set_time = 2; 343 344 // This corresponds to 345 // [SetDefaultBranchRequest.note][google.cloud.retail.v2alpha.SetDefaultBranchRequest.note] 346 // field, when this branch was set as default. 347 string note = 3; 348} 349 350// Request for 351// [CatalogService.GetCompletionConfig][google.cloud.retail.v2alpha.CatalogService.GetCompletionConfig] 352// method. 353message GetCompletionConfigRequest { 354 // Required. Full CompletionConfig resource name. Format: 355 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/completionConfig` 356 string name = 1 [ 357 (google.api.field_behavior) = REQUIRED, 358 (google.api.resource_reference) = { 359 type: "retail.googleapis.com/CompletionConfig" 360 } 361 ]; 362} 363 364// Request for 365// [CatalogService.UpdateCompletionConfig][google.cloud.retail.v2alpha.CatalogService.UpdateCompletionConfig] 366// method. 367message UpdateCompletionConfigRequest { 368 // Required. The 369 // [CompletionConfig][google.cloud.retail.v2alpha.CompletionConfig] to update. 370 // 371 // If the caller does not have permission to update the 372 // [CompletionConfig][google.cloud.retail.v2alpha.CompletionConfig], then a 373 // PERMISSION_DENIED error is returned. 374 // 375 // If the [CompletionConfig][google.cloud.retail.v2alpha.CompletionConfig] to 376 // update does not exist, a NOT_FOUND error is returned. 377 CompletionConfig completion_config = 1 378 [(google.api.field_behavior) = REQUIRED]; 379 380 // Indicates which fields in the provided 381 // [CompletionConfig][google.cloud.retail.v2alpha.CompletionConfig] to update. 382 // The following are the only supported fields: 383 // 384 // * [CompletionConfig.matching_order][google.cloud.retail.v2alpha.CompletionConfig.matching_order] 385 // * [CompletionConfig.max_suggestions][google.cloud.retail.v2alpha.CompletionConfig.max_suggestions] 386 // * [CompletionConfig.min_prefix_length][google.cloud.retail.v2alpha.CompletionConfig.min_prefix_length] 387 // * [CompletionConfig.auto_learning][google.cloud.retail.v2alpha.CompletionConfig.auto_learning] 388 // 389 // If not set, all supported fields are updated. 390 google.protobuf.FieldMask update_mask = 2; 391} 392 393// Request for 394// [CatalogService.GetAttributesConfig][google.cloud.retail.v2alpha.CatalogService.GetAttributesConfig] 395// method. 396message GetAttributesConfigRequest { 397 // Required. Full AttributesConfig resource name. Format: 398 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig` 399 string name = 1 [ 400 (google.api.field_behavior) = REQUIRED, 401 (google.api.resource_reference) = { 402 type: "retail.googleapis.com/AttributesConfig" 403 } 404 ]; 405} 406 407// Request for 408// [CatalogService.UpdateAttributesConfig][google.cloud.retail.v2alpha.CatalogService.UpdateAttributesConfig] 409// method. 410message UpdateAttributesConfigRequest { 411 // Required. The 412 // [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig] to update. 413 AttributesConfig attributes_config = 1 414 [(google.api.field_behavior) = REQUIRED]; 415 416 // Indicates which fields in the provided 417 // [AttributesConfig][google.cloud.retail.v2alpha.AttributesConfig] to update. 418 // The following is the only supported field: 419 // 420 // * [AttributesConfig.catalog_attributes][google.cloud.retail.v2alpha.AttributesConfig.catalog_attributes] 421 // 422 // If not set, all supported fields are updated. 423 google.protobuf.FieldMask update_mask = 2; 424} 425 426// Request for 427// [CatalogService.AddCatalogAttribute][google.cloud.retail.v2alpha.CatalogService.AddCatalogAttribute] 428// method. 429message AddCatalogAttributeRequest { 430 // Required. Full AttributesConfig resource name. Format: 431 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig` 432 string attributes_config = 1 [ 433 (google.api.field_behavior) = REQUIRED, 434 (google.api.resource_reference) = { 435 type: "retail.googleapis.com/AttributesConfig" 436 } 437 ]; 438 439 // Required. The 440 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] to add. 441 CatalogAttribute catalog_attribute = 2 442 [(google.api.field_behavior) = REQUIRED]; 443} 444 445// Request for 446// [CatalogService.RemoveCatalogAttribute][google.cloud.retail.v2alpha.CatalogService.RemoveCatalogAttribute] 447// method. 448message RemoveCatalogAttributeRequest { 449 // Required. Full AttributesConfig resource name. Format: 450 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig` 451 string attributes_config = 1 [ 452 (google.api.field_behavior) = REQUIRED, 453 (google.api.resource_reference) = { 454 type: "retail.googleapis.com/AttributesConfig" 455 } 456 ]; 457 458 // Required. The attribute name key of the 459 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] to remove. 460 string key = 2 [(google.api.field_behavior) = REQUIRED]; 461} 462 463// Request for 464// [CatalogService.BatchRemoveCatalogAttributes][google.cloud.retail.v2alpha.CatalogService.BatchRemoveCatalogAttributes] 465// method. 466message BatchRemoveCatalogAttributesRequest { 467 // Required. The attributes config resource shared by all catalog attributes 468 // being deleted. Format: 469 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig` 470 string attributes_config = 1 [ 471 (google.api.field_behavior) = REQUIRED, 472 (google.api.resource_reference) = { 473 type: "retail.googleapis.com/AttributesConfig" 474 } 475 ]; 476 477 // Required. The attribute name keys of the 478 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute]s to 479 // delete. A maximum of 1000 catalog attributes can be deleted in a batch. 480 repeated string attribute_keys = 2 [(google.api.field_behavior) = REQUIRED]; 481} 482 483// Response of the 484// [CatalogService.BatchRemoveCatalogAttributes][google.cloud.retail.v2alpha.CatalogService.BatchRemoveCatalogAttributes]. 485message BatchRemoveCatalogAttributesResponse { 486 // Catalog attributes that were deleted. Only pre-loaded [catalog 487 // attributes][google.cloud.retail.v2alpha.CatalogAttribute] that are 488 // neither [in 489 // use][google.cloud.retail.v2alpha.CatalogAttribute.in_use] by 490 // products nor predefined can be deleted. 491 repeated string deleted_catalog_attributes = 1; 492 493 // Catalog attributes that were reset. [Catalog 494 // attributes][google.cloud.retail.v2alpha.CatalogAttribute] that are either 495 // [in use][google.cloud.retail.v2alpha.CatalogAttribute.in_use] by products 496 // or are predefined attributes cannot be deleted; however, their 497 // configuration properties will reset to default values upon removal request. 498 repeated string reset_catalog_attributes = 2; 499} 500 501// Request for 502// [CatalogService.ReplaceCatalogAttribute][google.cloud.retail.v2alpha.CatalogService.ReplaceCatalogAttribute] 503// method. 504message ReplaceCatalogAttributeRequest { 505 // Required. Full AttributesConfig resource name. Format: 506 // `projects/{project_number}/locations/{location_id}/catalogs/{catalog_id}/attributesConfig` 507 string attributes_config = 1 [ 508 (google.api.field_behavior) = REQUIRED, 509 (google.api.resource_reference) = { 510 type: "retail.googleapis.com/AttributesConfig" 511 } 512 ]; 513 514 // Required. The updated 515 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute]. 516 CatalogAttribute catalog_attribute = 2 517 [(google.api.field_behavior) = REQUIRED]; 518 519 // Indicates which fields in the provided 520 // [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] to update. 521 // The following are NOT supported: 522 // 523 // * [CatalogAttribute.key][google.cloud.retail.v2alpha.CatalogAttribute.key] 524 // 525 // If not set, all supported fields are updated. 526 google.protobuf.FieldMask update_mask = 3; 527} 528