feat: [google-cloud-retail] add language_code, region_code and place_id to SearchRequest (#13845)

- [ ] Regenerate this pull request now.

BEGIN_COMMIT_OVERRIDE
feat: add language_code, region_code and place_id to SearchRequest
feat: add pin_control_metadata to SearchResponse
docs: keep the API doc up-to-date with recent changes
feat: add conversational search API
END_COMMIT_OVERRIDE



PiperOrigin-RevId: 752323436

Source-Link:
googleapis/googleapis@1ac7dc2

Source-Link:
googleapis/googleapis-gen@117bcc0
Copy-Tag:
eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLXJldGFpbC8uT3dsQm90LnlhbWwiLCJoIjoiMTE3YmNjMGQyZGE5YzEzZmQwN2U2MzA1MTE1YTY4NzliZmE5ODZmZCJ9

BEGIN_NESTED_COMMIT
feat: [google-cloud-retail] add conversational search API
PiperOrigin-RevId: 751643959

Source-Link:
googleapis/googleapis@2eec62d

Source-Link:
googleapis/googleapis-gen@dc04c51
Copy-Tag:
eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLXJldGFpbC8uT3dsQm90LnlhbWwiLCJoIjoiZGMwNGM1MWFlMTA4NTg3MmY0Njk0ODc2OGQzYzIxMTcyZjQ4YWYwMSJ9
END_NESTED_COMMIT
BEGIN_NESTED_COMMIT
feat: [google-cloud-retail] add language_code, region_code and place_id
to SearchRequest
feat: add pin_control_metadata to SearchResponse
docs: keep the API doc up-to-date with recent changes

PiperOrigin-RevId: 751590638

Source-Link:
googleapis/googleapis@7b29e66

Source-Link:
googleapis/googleapis-gen@a7be28d
Copy-Tag:
eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLXJldGFpbC8uT3dsQm90LnlhbWwiLCJoIjoiYTdiZTI4ZGNhOWNiMGQwNmE0ZGM5MDA1NmRjM2NhYWI3MzRhODI3NyJ9
END_NESTED_COMMIT

---------

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

Author: gcf-owl-bot[bot]

packages/google-cloud-retail/docs/retail_v2alpha/conversational_search_service.rst

@@ -0,0 +1,6 @@
+ConversationalSearchService
+---------------------------------------------
+
+.. automodule:: google.cloud.retail_v2alpha.services.conversational_search_service
+    :members:
+    :inherited-members:

packages/google-cloud-retail/docs/retail_v2alpha/services_.rst

@@ -8,6 +8,7 @@ Services for Google Cloud Retail v2alpha API
     catalog_service
     completion_service
     control_service
+    conversational_search_service
     generative_question_service
     merchant_center_account_link_service
     model_service

packages/google-cloud-retail/google/cloud/retail/__init__.py

@@ -106,6 +106,7 @@
     Image,
     Interval,
     LocalInventory,
+    PinControlMetadata,
     PriceInfo,
     Rating,
     RecommendationsFilteringOption,
@@ -302,6 +303,7 @@
     "Image",
     "Interval",
     "LocalInventory",
+    "PinControlMetadata",
     "PriceInfo",
     "Rating",
     "Rule",

packages/google-cloud-retail/google/cloud/retail/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.0.0"  # {x-release-please-version}
+__version__ = "0.0.0"  # {x-release-please-version}

packages/google-cloud-retail/google/cloud/retail_v2/__init__.py

@@ -79,6 +79,7 @@
     Image,
     Interval,
     LocalInventory,
+    PinControlMetadata,
     PriceInfo,
     Rating,
     RecommendationsFilteringOption,
@@ -320,6 +321,7 @@
     "OutputConfig",
     "OutputResult",
     "PauseModelRequest",
+    "PinControlMetadata",
     "PredictRequest",
     "PredictResponse",
     "PredictionServiceClient",

packages/google-cloud-retail/google/cloud/retail_v2/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.0.0"  # {x-release-please-version}
+__version__ = "0.0.0"  # {x-release-please-version}

packages/google-cloud-retail/google/cloud/retail_v2/services/user_event_service/async_client.py

@@ -408,9 +408,11 @@ async def collect_user_event(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
     ) -> httpbody_pb2.HttpBody:
-        r"""Writes a single user event from the browser. This
-        uses a GET request to due to browser restriction of
-        POST-ing to a 3rd party domain.
+        r"""Writes a single user event from the browser.
+
+        For larger user event payload over 16 KB, the POST
+        method should be used instead, otherwise a 400 Bad
+        Request error is returned.
 
         This method is used only by the Retail API JavaScript
         pixel and Google Tag Manager. Users should not call this

packages/google-cloud-retail/google/cloud/retail_v2/services/user_event_service/client.py

@@ -854,9 +854,11 @@ def collect_user_event(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
     ) -> httpbody_pb2.HttpBody:
-        r"""Writes a single user event from the browser. This
-        uses a GET request to due to browser restriction of
-        POST-ing to a 3rd party domain.
+        r"""Writes a single user event from the browser.
+
+        For larger user event payload over 16 KB, the POST
+        method should be used instead, otherwise a 400 Bad
+        Request error is returned.
 
         This method is used only by the Retail API JavaScript
         pixel and Google Tag Manager. Users should not call this

packages/google-cloud-retail/google/cloud/retail_v2/services/user_event_service/transports/grpc.py

@@ -377,9 +377,11 @@ def collect_user_event(
     ) -> Callable[[user_event_service.CollectUserEventRequest], httpbody_pb2.HttpBody]:
         r"""Return a callable for the collect user event method over gRPC.
 
-        Writes a single user event from the browser. This
-        uses a GET request to due to browser restriction of
-        POST-ing to a 3rd party domain.
+        Writes a single user event from the browser.
+
+        For larger user event payload over 16 KB, the POST
+        method should be used instead, otherwise a 400 Bad
+        Request error is returned.
 
         This method is used only by the Retail API JavaScript
         pixel and Google Tag Manager. Users should not call this

packages/google-cloud-retail/google/cloud/retail_v2/services/user_event_service/transports/grpc_asyncio.py

@@ -389,9 +389,11 @@ def collect_user_event(
     ]:
         r"""Return a callable for the collect user event method over gRPC.
 
-        Writes a single user event from the browser. This
-        uses a GET request to due to browser restriction of
-        POST-ing to a 3rd party domain.
+        Writes a single user event from the browser.
+
+        For larger user event payload over 16 KB, the POST
+        method should be used instead, otherwise a 400 Bad
+        Request error is returned.
 
         This method is used only by the Retail API JavaScript
         pixel and Google Tag Manager. Users should not call this

packages/google-cloud-retail/google/cloud/retail_v2/services/user_event_service/transports/rest_base.py

@@ -118,6 +118,11 @@ def _get_http_options():
                     "method": "get",
                     "uri": "/v2/{parent=projects/*/locations/*/catalogs/*}/userEvents:collect",
                 },
+                {
+                    "method": "post",
+                    "uri": "/v2/{parent=projects/*/locations/*/catalogs/*}/userEvents:collect",
+                    "body": "*",
+                },
             ]
             return http_options
 

packages/google-cloud-retail/google/cloud/retail_v2/types/__init__.py

@@ -45,6 +45,7 @@
     Image,
     Interval,
     LocalInventory,
+    PinControlMetadata,
     PriceInfo,
     Rating,
     RecommendationsFilteringOption,
@@ -208,6 +209,7 @@
     "Image",
     "Interval",
     "LocalInventory",
+    "PinControlMetadata",
     "PriceInfo",
     "Rating",
     "Rule",

packages/google-cloud-retail/google/cloud/retail_v2/types/catalog.py

@@ -134,8 +134,8 @@ class CatalogAttribute(proto.Message):
 
             [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute]
             can be pre-loaded by using
-            [CatalogService.AddCatalogAttribute][google.cloud.retail.v2.CatalogService.AddCatalogAttribute],
-            [CatalogService.ImportCatalogAttributes][], or
+            [CatalogService.AddCatalogAttribute][google.cloud.retail.v2.CatalogService.AddCatalogAttribute]
+            or
             [CatalogService.UpdateAttributesConfig][google.cloud.retail.v2.CatalogService.UpdateAttributesConfig]
             APIs. This field is ``False`` for pre-loaded
             [CatalogAttribute][google.cloud.retail.v2.CatalogAttribute]s.

packages/google-cloud-retail/google/cloud/retail_v2/types/common.py

@@ -39,6 +39,7 @@
         "Rating",
         "UserInfo",
         "LocalInventory",
+        "PinControlMetadata",
     },
 )
 
@@ -56,7 +57,7 @@ class AttributeConfigLevel(proto.Enum):
             [Product.attributes][google.cloud.retail.v2.Product.attributes].
         CATALOG_LEVEL_ATTRIBUTE_CONFIG (2):
             At this level, we honor the attribute configurations set in
-            [CatalogConfig.attribute_configs][].
+            ``CatalogConfig.attribute_configs``.
     """
     ATTRIBUTE_CONFIG_LEVEL_UNSPECIFIED = 0
     PRODUCT_LEVEL_ATTRIBUTE_CONFIG = 1
@@ -270,6 +271,11 @@ class Rule(proto.Message):
             Remove an attribute as a facet in the request
             (if present).
 
+            This field is a member of `oneof`_ ``action``.
+        pin_action (google.cloud.retail_v2.types.Rule.PinAction):
+            Pins one or more specified products to a
+            specific position in the results.
+
             This field is a member of `oneof`_ ``action``.
         condition (google.cloud.retail_v2.types.Condition):
             Required. The condition that triggers the
@@ -613,6 +619,59 @@ class RemoveFacetAction(proto.Message):
             number=1,
         )
 
+    class PinAction(proto.Message):
+        r"""Pins one or more specified products to a specific position in the
+        results.
+
+        -  Rule Condition: Must specify non-empty
+           [Condition.query_terms][google.cloud.retail.v2.Condition.query_terms]
+           (for search only) or
+           [Condition.page_categories][google.cloud.retail.v2.Condition.page_categories]
+           (for browse only), but can't specify both.
+
+        -  Action Input: mapping of ``[pin_position, product_id]`` pairs
+           (pin position uses 1-based indexing).
+
+        -  Action Result: Will pin products with matching ids to the
+           position specified in the final result order.
+
+        Example: Suppose the query is ``shoes``, the
+        [Condition.query_terms][google.cloud.retail.v2.Condition.query_terms]
+        is ``shoes`` and the pin_map has ``{1, "pid1"}``, then product with
+        ``pid1`` will be pinned to the top position in the final results.
+
+        If multiple PinActions are matched to a single request the actions
+        will be processed from most to least recently updated.
+
+        Pins to positions larger than the max allowed page size of 120 are
+        not allowed.
+
+        Attributes:
+            pin_map (MutableMapping[int, str]):
+                Required. A map of positions to product_ids.
+
+                Partial matches per action are allowed, if a certain
+                position in the map is already filled that
+                ``[position, product_id]`` pair will be ignored but the rest
+                may still be applied. This case will only occur if multiple
+                pin actions are matched to a single request, as the map
+                guarantees that pin positions are unique within the same
+                action.
+
+                Duplicate product_ids are not permitted within a single pin
+                map.
+
+                The max size of this map is 120, equivalent to the max
+                `request page
+                size <https://cloud.google.com/retail/docs/reference/rest/v2/projects.locations.catalogs.placements/search#request-body>`__.
+        """
+
+        pin_map: MutableMapping[int, str] = proto.MapField(
+            proto.INT64,
+            proto.STRING,
+            number=1,
+        )
+
     boost_action: BoostAction = proto.Field(
         proto.MESSAGE,
         number=2,
@@ -673,6 +732,12 @@ class RemoveFacetAction(proto.Message):
         oneof="action",
         message=RemoveFacetAction,
     )
+    pin_action: PinAction = proto.Field(
+        proto.MESSAGE,
+        number=14,
+        oneof="action",
+        message=PinAction,
+    )
     condition: "Condition" = proto.Field(
         proto.MESSAGE,
         number=1,
@@ -746,6 +811,11 @@ class ColorInfo(proto.Message):
             `color <https://support.google.com/merchants/answer/6324487>`__.
             Schema.org property
             `Product.color <https://schema.org/color>`__.
+
+            The colorFamilies field as a system attribute is not a
+            required field but strongly recommended to be specified.
+            Google Search models treat this field as more important than
+            a custom product attribute when specified.
         colors (MutableSequence[str]):
             The color display names, which may be different from
             standard color family names, such as the color aliases used
@@ -918,10 +988,11 @@ class FulfillmentInfo(proto.Message):
 
 class Image(proto.Message):
     r"""[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.
+    and Retail Search use product images to improve prediction and
+    search results. Product images can be returned in results, and are
+    shown in prediction or search previews in the console. Please try to
+    provide correct product images and avoid using images with size too
+    small.
 
     Attributes:
         uri (str):
@@ -1253,12 +1324,9 @@ class UserInfo(proto.Message):
                [direct_user_request][google.cloud.retail.v2.UserInfo.direct_user_request]
                is set.
         user_agent (str):
-            User agent as included in the HTTP header. Required for
-            getting
-            [SearchResponse.sponsored_results][google.cloud.retail.v2.SearchResponse.sponsored_results].
-
-            The field must be a UTF-8 encoded string with a length limit
-            of 1,000 characters. Otherwise, an INVALID_ARGUMENT error is
+            User agent as included in the HTTP header. The field must be
+            a UTF-8 encoded string with a length limit of 1,000
+            characters. Otherwise, an INVALID_ARGUMENT error is
             returned.
 
             This should not be set when using the client side event
@@ -1305,16 +1373,16 @@ class LocalInventory(proto.Message):
 
     Attributes:
         place_id (str):
-            The place ID for the current set of inventory
-            information.
+            Optional. The place ID for the current set of
+            inventory information.
         price_info (google.cloud.retail_v2.types.PriceInfo):
-            Product price and cost information.
+            Optional. Product price and cost information.
 
             Google Merchant Center property
             `price <https://support.google.com/merchants/answer/6324371>`__.
         attributes (MutableMapping[str, google.cloud.retail_v2.types.CustomAttribute]):
-            Additional local inventory attributes, for example, store
-            name, promotion tags, etc.
+            Optional. 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:
@@ -1335,7 +1403,7 @@ class LocalInventory(proto.Message):
             -  The max summed total bytes of custom attribute keys and
                values per product is 5MiB.
         fulfillment_types (MutableSequence[str]):
-            Input only. Supported fulfillment types. Valid fulfillment
+            Optional. 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
@@ -1381,4 +1449,45 @@ class LocalInventory(proto.Message):
     )
 
 
+class PinControlMetadata(proto.Message):
+    r"""Metadata for pinning to be returned in the response.
+    This is used for distinguishing between applied vs dropped pins.
+
+    Attributes:
+        all_matched_pins (MutableMapping[int, google.cloud.retail_v2.types.PinControlMetadata.ProductPins]):
+            Map of all matched pins, keyed by pin
+            position.
+        dropped_pins (MutableMapping[int, google.cloud.retail_v2.types.PinControlMetadata.ProductPins]):
+            Map of pins that were dropped due to overlap
+            with other matching pins, keyed by pin position.
+    """
+
+    class ProductPins(proto.Message):
+        r"""List of product ids which have associated pins.
+
+        Attributes:
+            product_id (MutableSequence[str]):
+                List of product ids which have associated
+                pins.
+        """
+
+        product_id: MutableSequence[str] = proto.RepeatedField(
+            proto.STRING,
+            number=1,
+        )
+
+    all_matched_pins: MutableMapping[int, ProductPins] = proto.MapField(
+        proto.INT64,
+        proto.MESSAGE,
+        number=1,
+        message=ProductPins,
+    )
+    dropped_pins: MutableMapping[int, ProductPins] = proto.MapField(
+        proto.INT64,
+        proto.MESSAGE,
+        number=2,
+        message=ProductPins,
+    )
+
+
 __all__ = tuple(sorted(__protobuf__.manifest))