feat: users can skip validation, search personalization, return ids, and more; docs: suggest search users to not send IP, deprecate request_id, and more (#160)

* docs: users can self enroll retail search feature on cloud console
docs: suggest search users not to send IP and use hashed user id
docs: deprecate request_id in ImportProductsRequest
docs: deprecate search dynamic_facet_spec and suggest to config on cloud console
docs: keep the API doc up-to-date with recent changes
feat: add new AddLocalInventories and RemoveLocalInventories APIs
feat: users cannot switch to empty default branch unless force override
feat: allow search users to skip validation for invalid boost specs
feat: support search personalization
feat: search returns applied control ids in the response

PiperOrigin-RevId: 437355889

Source-Link: googleapis/googleapis@4d00815

Source-Link: googleapis/googleapis-gen@b2b7982
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiYjJiNzk4MjQ3ZDQ2YzkzMjczN2NmNjg5NzQ0YTgyN2ZhZTdlNTMxMyJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* docs: users can self enroll retail search feature on cloud console (v2beta)
docs: suggest search users not to send IP and use hashed user id (v2beta)
docs: deprecate request_id in ImportProductsRequest (v2beta)
docs: deprecate search dynamic_facet_spec and suggest to config on cloud console (v2beta)
docs: keep the API doc up-to-date with recent changes (v2beta)
feat: add new AddLocalInventories and RemoveLocalInventories APIs (v2beta)
feat: users cannot switch to empty default branch unless force override (v2beta)
feat: allow search users to skip validation for invalid boost specs (v2beta)
feat: support search personalization (v2beta)
feat: search returns applied control ids in the response (v2beta)

PiperOrigin-RevId: 438326512

Source-Link: googleapis/googleapis@d6abf63

Source-Link: googleapis/googleapis-gen@bfbcd23
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiYmZiY2QyM2FhOTkwZTBkZjgzNjRkNDc4MDI4ZjYxYWQ3ZmY1YzhjOSJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

packages/google-cloud-retail/protos/google/cloud/retail/v2/catalog_service.proto

@@ -91,10 +91,6 @@ service CatalogService {
   //   (if branch is not explicitly set).
   // * UserEventService will only join events with products from branch
   //   {newBranch}.
-  //
-  // This feature is only available for users who have Retail Search enabled.
-  // Please submit a form [here](https://cloud.google.com/contact) to contact
-  // cloud sales if you are interested in using Retail Search.
   rpc SetDefaultBranch(SetDefaultBranchRequest)
       returns (google.protobuf.Empty) {
     option (google.api.http) = {
@@ -107,10 +103,6 @@ service CatalogService {
   // Get which branch is currently default branch set by
   // [CatalogService.SetDefaultBranch][google.cloud.retail.v2.CatalogService.SetDefaultBranch]
   // method under a specified parent catalog.
-  //
-  // This feature is only available for users who have Retail Search enabled.
-  // Please submit a form [here](https://cloud.google.com/contact) to contact
-  // cloud sales if you are interested in using Retail Search.
   rpc GetDefaultBranch(GetDefaultBranchRequest)
       returns (GetDefaultBranchResponse) {
     option (google.api.http) = {
@@ -205,6 +197,10 @@ message SetDefaultBranchRequest {
   //
   // This field must be one of "0", "1" or "2". Otherwise, an INVALID_ARGUMENT
   // error is returned.
+  //
+  // If there are no sufficient active products in the targeted branch and
+  // [force][google.cloud.retail.v2.SetDefaultBranchRequest.force] is not set, a
+  // FAILED_PRECONDITION error is returned.
   string branch_id = 2 [
     (google.api.resource_reference) = { type: "retail.googleapis.com/Branch" }
   ];
@@ -216,6 +212,11 @@ message SetDefaultBranchRequest {
   // This field must be a UTF-8 encoded string with a length limit of 1,000
   // characters. Otherwise, an INVALID_ARGUMENT error is returned.
   string note = 3;
+
+  // If set to true, it permits switching to a branch with
+  // [branch_id][google.cloud.retail.v2.SetDefaultBranchRequest.branch_id] even
+  // if it has no sufficient active products.
+  bool force = 4;
 }
 
 // Request message to show which branch is currently the default branch.

packages/google-cloud-retail/protos/google/cloud/retail/v2/common.proto

@@ -99,9 +99,8 @@ message CustomAttribute {
   // The textual values of this custom attribute. For example, `["yellow",
   // "green"]` when the key is "color".
   //
-  // At most 400 values are allowed. Empty values are not allowed. Each value
-  // must be a UTF-8 encoded string with a length limit of 256 characters.
-  // Otherwise, an INVALID_ARGUMENT error is returned.
+  // Empty string is not allowed. Otherwise, an INVALID_ARGUMENT error is
+  // returned.
   //
   // Exactly one of [text][google.cloud.retail.v2.CustomAttribute.text] or
   // [numbers][google.cloud.retail.v2.CustomAttribute.numbers] should be set.
@@ -111,15 +110,16 @@ message CustomAttribute {
   // The numerical values of this custom attribute. For example, `[2.3, 15.4]`
   // when the key is "lengths_cm".
   //
-  // At most 400 values are allowed.Otherwise, an INVALID_ARGUMENT error is
-  // returned.
-  //
   // Exactly one of [text][google.cloud.retail.v2.CustomAttribute.text] or
   // [numbers][google.cloud.retail.v2.CustomAttribute.numbers] should be set.
   // Otherwise, an INVALID_ARGUMENT error is returned.
   repeated double numbers = 2;
 
-  // If true, custom attribute values are searchable by text queries in
+  // This field will only be used when
+  // [AttributesConfig.attribute_config_level][] of the
+  // [Catalog][google.cloud.retail.v2.Catalog] is
+  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
+  // searchable by text queries in
   // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
   //
   // This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
@@ -128,8 +128,11 @@ message CustomAttribute {
   // set. Otherwise, a INVALID_ARGUMENT error is returned.
   optional bool searchable = 3;
 
-  // If true, custom attribute values are indexed, so that it can be filtered,
-  // faceted or boosted in
+  // This field will only be used when
+  // [AttributesConfig.attribute_config_level][] of the
+  // [Catalog][google.cloud.retail.v2.Catalog] is
+  // 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
+  // indexed, so that it can be filtered, faceted or boosted in
   // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
   //
   // This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
@@ -178,7 +181,10 @@ message FulfillmentInfo {
   repeated string place_ids = 2;
 }
 
-// [Product][google.cloud.retail.v2.Product] thumbnail/detail image.
+// [Product][google.cloud.retail.v2.Product] image. Recommendations AI and
+// Retail Search do not use product images to improve prediction and search
+// results. However, product images can be returned in results, and are shown in
+// prediction or search previews in the console.
 message Image {
   // Required. URI of the image.
   //
@@ -274,7 +280,7 @@ message PriceInfo {
   //
   // Google Merchant Center property
   // [price](https://support.google.com/merchants/answer/6324371). Schema.org
-  // property [Offer.priceSpecification](https://schema.org/priceSpecification).
+  // property [Offer.price](https://schema.org/price).
   float price = 2;
 
   // Price of the product without any discount. If zero, by default set to be
@@ -364,19 +370,24 @@ message UserInfo {
   // Highly recommended for logged-in users. Unique identifier for logged-in
   // user, such as a user name.
   //
+  // Always use a hashed value for this ID.
+  //
   // The field must be a UTF-8 encoded string with a length limit of 128
   // characters. Otherwise, an INVALID_ARGUMENT error is returned.
   string user_id = 1;
 
-  // The end user's IP address. Required for getting
-  // [SearchResponse.sponsored_results][google.cloud.retail.v2.SearchResponse.sponsored_results].
-  // This field is used to extract location information for personalization.
+  // The end user's IP address. This field is used to extract location
+  // information for personalization.
   //
   // This field must be either an IPv4 address (e.g. "104.133.9.80") or an IPv6
   // address (e.g. "2001:0db8:85a3:0000:0000:8a2e:0370:7334"). Otherwise, an
   // INVALID_ARGUMENT error is returned.
   //
-  // This should not be set when using the JavaScript tag in
+  // This should not be set when:
+  //
+  // * setting
+  // [SearchRequest.user_info][google.cloud.retail.v2.SearchRequest.user_info].
+  // * using the JavaScript tag in
   // [UserEventService.CollectUserEvent][google.cloud.retail.v2.UserEventService.CollectUserEvent]
   // or if
   // [direct_user_request][google.cloud.retail.v2.UserInfo.direct_user_request]
@@ -409,16 +420,60 @@ message UserInfo {
   bool direct_user_request = 4;
 }
 
-// Promotion information.
-message Promotion {
-  // ID of the promotion. For example, "free gift".
-  //
-  // The value value must be a UTF-8 encoded string with a length limit of 128
-  // characters, and match the pattern: `[a-zA-Z][a-zA-Z0-9_]*`. For example,
-  // id0LikeThis or ID_1_LIKE_THIS. Otherwise, an INVALID_ARGUMENT error is
-  // returned.
+// The inventory information at a place (e.g. a store) identified
+// by a place ID.
+message LocalInventory {
+  // The place ID for the current set of inventory information.
+  string place_id = 1;
+
+  // Product price and cost information.
   //
   // Google Merchant Center property
-  // [promotion](https://support.google.com/merchants/answer/7050148).
-  string promotion_id = 1;
+  // [price](https://support.google.com/merchants/answer/6324371).
+  PriceInfo price_info = 2;
+
+  // Additional local inventory attributes, for example, store name, promotion
+  // tags, etc.
+  //
+  // This field needs to pass all below criteria, otherwise an INVALID_ARGUMENT
+  // error is returned:
+  //
+  // * At most 30 attributes are allowed.
+  // * The key must be a UTF-8 encoded string with a length limit of 32
+  //   characters.
+  // * The key must match the pattern: `[a-zA-Z0-9][a-zA-Z0-9_]*`. For example,
+  //   key0LikeThis or KEY_1_LIKE_THIS.
+  // * The attribute values must be of the same type (text or number).
+  // * Only 1 value is allowed for each attribute.
+  // * For text values, the length limit is 256 UTF-8 characters.
+  // * The attribute does not support search. The `searchable` field should be
+  //   unset or set to false.
+  // * The max summed total bytes of custom attribute keys and values per
+  //   product is 5MiB.
+  map<string, CustomAttribute> attributes = 3;
+
+  // Input only. Supported fulfillment types. Valid fulfillment type values
+  // include commonly used types (such as pickup in store and same day
+  // delivery), and custom types. Customers have to map custom types to their
+  // display names before rendering UI.
+  //
+  // Supported values:
+  //
+  // * "pickup-in-store"
+  // * "ship-to-store"
+  // * "same-day-delivery"
+  // * "next-day-delivery"
+  // * "custom-type-1"
+  // * "custom-type-2"
+  // * "custom-type-3"
+  // * "custom-type-4"
+  // * "custom-type-5"
+  //
+  // If this field is set to an invalid value other than these, an
+  // INVALID_ARGUMENT error is returned.
+  //
+  // All the elements must be distinct. Otherwise, an INVALID_ARGUMENT error is
+  // returned.
+  repeated string fulfillment_types = 4
+      [(google.api.field_behavior) = INPUT_ONLY];
 }

packages/google-cloud-retail/protos/google/cloud/retail/v2/completion_service.proto

@@ -36,8 +36,7 @@ option ruby_package = "Google::Cloud::Retail::V2";
 // Auto-completion service for retail.
 //
 // This feature is only available for users who have Retail Search enabled.
-// Please submit a form [here](https://cloud.google.com/contact) to contact
-// cloud sales if you are interested in using Retail Search.
+// Please enable Retail Search on Cloud Console before using this feature.
 service CompletionService {
   option (google.api.default_host) = "retail.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -46,8 +45,7 @@ service CompletionService {
   // Completes the specified prefix with keyword suggestions.
   //
   // This feature is only available for users who have Retail Search enabled.
-  // Please submit a form [here](https://cloud.google.com/contact) to contact
-  // cloud sales if you are interested in using Retail Search.
+  // Please enable Retail Search on Cloud Console before using this feature.
   rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) {
     option (google.api.http) = {
       get: "/v2/{catalog=projects/*/locations/*/catalogs/*}:completeQuery"
@@ -56,11 +54,13 @@ service CompletionService {
 
   // Bulk import of processed completion dataset.
   //
-  // Request processing may be synchronous. Partial updating is not supported.
+  // Request processing is asynchronous. Partial updating is not supported.
+  //
+  // The operation is successfully finished only after the imported suggestions
+  // are indexed successfully and ready for serving. The process takes hours.
   //
   // This feature is only available for users who have Retail Search enabled.
-  // Please submit a form [here](https://cloud.google.com/contact) to contact
-  // cloud sales if you are interested in using Retail Search.
+  // Please enable Retail Search on Cloud Console before using this feature.
   rpc ImportCompletionData(ImportCompletionDataRequest)
       returns (google.longrunning.Operation) {
     option (google.api.http) = {
@@ -90,22 +90,21 @@ message CompleteQueryRequest {
   // The maximum number of allowed characters is 255.
   string query = 2 [(google.api.field_behavior) = REQUIRED];
 
-  // A unique identifier for tracking visitors. For example, this could be
-  // implemented with an HTTP cookie, which should be able to uniquely identify
-  // a visitor on a single device. This unique identifier should not change if
-  // the visitor logs in or out of the website.
+  // Required field. A unique identifier for tracking visitors. For example,
+  // this could be implemented with an HTTP cookie, which should be able to
+  // uniquely identify a visitor on a single device. This unique identifier
+  // should not change if the visitor logs in or out of the website.
   //
   // The field must be a UTF-8 encoded string with a length limit of 128
   // characters. Otherwise, an INVALID_ARGUMENT error is returned.
   string visitor_id = 7;
 
-  // The list of languages of the query. This is
-  // the BCP-47 language code, such as "en-US" or "sr-Latn".
-  // For more information, see
-  // [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47).
-  //
-  // The maximum number of allowed characters is 255.
-  // Only "en-US" is currently supported.
+  // The language filters applied to the output suggestions. If set, it should
+  // contain the language of the query. If not set, suggestions are returned
+  // without considering language restrictions. This is the BCP-47 language
+  // code, such as "en-US" or "sr-Latn". For more information, see [Tags for
+  // Identifying Languages](https://tools.ietf.org/html/bcp47). The maximum
+  // number of language codes is 3.
   repeated string language_codes = 3;
 
   // The device type context for completion suggestions.
@@ -154,7 +153,11 @@ message CompleteQueryResponse {
     // The suggestion for the query.
     string suggestion = 1;
 
-    // Additional custom attributes ingested through BigQuery.
+    // Custom attributes for the suggestion term.
+    // * For "user-data", the attributes are additional custom attributes
+    // ingested through BigQuery.
+    // * For "cloud-retail", the attributes are product attributes generated
+    // by Cloud Retail.
     map<string, CustomAttribute> attributes = 2;
   }
 
@@ -169,9 +172,9 @@ message CompleteQueryResponse {
   repeated CompletionResult completion_results = 1;
 
   // A unique complete token. This should be included in the
-  // [SearchRequest][google.cloud.retail.v2.SearchRequest] resulting from this
-  // completion, which enables accurate attribution of complete model
-  // performance.
+  // [UserEvent.completion_detail][google.cloud.retail.v2.UserEvent.completion_detail]
+  // for search events resulting from this completion, which enables accurate
+  // attribution of complete model performance.
   string attribution_token = 2;
 
   // Matched recent searches of this user. The maximum number of recent searches