Skip to content

Commit 7b29e66

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
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 PiperOrigin-RevId: 751590638
1 parent 567d956 commit 7b29e66

12 files changed

Lines changed: 178 additions & 72 deletions

‎google/cloud/retail/v2beta/catalog.proto‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -302,8 +302,8 @@ message CatalogAttribute {
302302
//
303303
// [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute] can be
304304
// pre-loaded by using
305-
// [CatalogService.AddCatalogAttribute][google.cloud.retail.v2beta.CatalogService.AddCatalogAttribute],
306-
// [CatalogService.ImportCatalogAttributes][], or
305+
// [CatalogService.AddCatalogAttribute][google.cloud.retail.v2beta.CatalogService.AddCatalogAttribute]
306+
// or
307307
// [CatalogService.UpdateAttributesConfig][google.cloud.retail.v2beta.CatalogService.UpdateAttributesConfig]
308308
// APIs. This field is `False` for pre-loaded
309309
// [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]s.

‎google/cloud/retail/v2beta/catalog_service.proto‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
// you may not use this file except in compliance with the License.
55
// You may obtain a copy of the License at
66
//
7-
// http://www.apache.org/licenses/LICENSE-2.0
7+
// http://www.apache.org/licenses/LICENSE-2.0
88
//
99
// Unless required by applicable law or agreed to in writing, software
1010
// distributed under the License is distributed on an "AS IS" BASIS,
@@ -75,14 +75,15 @@ service CatalogService {
7575
//
7676
// Using multiple branches can be useful when developers would like
7777
// 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.v2beta.SearchRequest.branch]
81-
// to route the traffic to this staging branch.
78+
// becomes ready, developers switch on the staging branch using this API
79+
// while keeping using
80+
// `projects/*/locations/*/catalogs/*/branches/default_branch` as
81+
// [SearchRequest.branch][google.cloud.retail.v2beta.SearchRequest.branch] to
82+
// route the traffic to this staging branch.
8283
//
8384
// 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.
85+
// branch could potentially cause outages if the ID space of the new branch
86+
// is very different from the old one.
8687
//
8788
// More specifically:
8889
//

‎google/cloud/retail/v2beta/common.proto‎

Lines changed: 86 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ enum AttributeConfigLevel {
3939
PRODUCT_LEVEL_ATTRIBUTE_CONFIG = 1;
4040

4141
// At this level, we honor the attribute configurations set in
42-
// [CatalogConfig.attribute_configs][].
42+
// `CatalogConfig.attribute_configs`.
4343
CATALOG_LEVEL_ATTRIBUTE_CONFIG = 2;
4444
}
4545

@@ -369,6 +369,48 @@ message Rule {
369369
repeated string attribute_names = 1;
370370
}
371371

372+
// Pins one or more specified products to a specific position in the
373+
// results.
374+
//
375+
// * Rule Condition:
376+
// Must specify non-empty
377+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
378+
// (for search only) or
379+
// [Condition.page_categories][google.cloud.retail.v2beta.Condition.page_categories]
380+
// (for browse only), but can't specify both.
381+
//
382+
// * Action Input: mapping of `[pin_position, product_id]` pairs (pin position
383+
// uses 1-based indexing).
384+
//
385+
// * Action Result: Will pin products with matching ids to the position
386+
// specified in the final result order.
387+
//
388+
// Example: Suppose the query is `shoes`, the
389+
// [Condition.query_terms][google.cloud.retail.v2beta.Condition.query_terms]
390+
// is `shoes` and the pin_map has `{1, "pid1"}`, then product with `pid1` will
391+
// be pinned to the top position in the final results.
392+
//
393+
// If multiple PinActions are matched to a single request the actions will
394+
// be processed from most to least recently updated.
395+
//
396+
// Pins to positions larger than the max allowed page size of 120 are not
397+
// allowed.
398+
message PinAction {
399+
// Required. A map of positions to product_ids.
400+
//
401+
// Partial matches per action are allowed, if a certain position in the map
402+
// is already filled that `[position, product_id]` pair will be ignored
403+
// but the rest may still be applied. This case will only occur if multiple
404+
// pin actions are matched to a single request, as the map guarantees that
405+
// pin positions are unique within the same action.
406+
//
407+
// Duplicate product_ids are not permitted within a single pin map.
408+
//
409+
// The max size of this map is 120, equivalent to the max [request page
410+
// size](https://cloud.google.com/retail/docs/reference/rest/v2/projects.locations.catalogs.placements/search#request-body).
411+
map<int64, string> pin_map = 1 [(google.api.field_behavior) = REQUIRED];
412+
}
413+
372414
// An action must be provided.
373415
oneof action {
374416
// A boost action.
@@ -401,6 +443,10 @@ message Rule {
401443

402444
// Remove an attribute as a facet in the request (if present).
403445
RemoveFacetAction remove_facet_action = 13;
446+
447+
// Pins one or more specified products to a specific position in the
448+
// results.
449+
PinAction pin_action = 14;
404450
}
405451

406452
// Required. The condition that triggers the rule.
@@ -445,9 +491,9 @@ message Audience {
445491
message ColorInfo {
446492
// The standard color families. Strongly recommended to use the following
447493
// standard color groups: "Red", "Pink", "Orange", "Yellow", "Purple",
448-
// "Green", "Cyan", "Blue", "Brown", "White", "Gray", "Black" and
449-
// "Mixed". Normally it is expected to have only 1 color family. May consider
450-
// using single "Mixed" instead of multiple values.
494+
// "Green", "Cyan", "Blue", "Brown", "White", "Gray", "Black" and "Mixed".
495+
// Normally it is expected to have only 1 color family. May consider using
496+
// single "Mixed" instead of multiple values.
451497
//
452498
// A maximum of 5 values are allowed. Each value must be a UTF-8 encoded
453499
// string with a length limit of 128 characters. Otherwise, an
@@ -456,6 +502,10 @@ message ColorInfo {
456502
// Google Merchant Center property
457503
// [color](https://support.google.com/merchants/answer/6324487). Schema.org
458504
// property [Product.color](https://schema.org/color).
505+
//
506+
// The colorFamilies field as a system attribute is not a required field but
507+
// strongly recommended to be specified. Google Search models treat this field
508+
// as more important than a custom product attribute when specified.
459509
repeated string color_families = 1;
460510

461511
// The color display names, which may be different from standard color family
@@ -570,9 +620,10 @@ message FulfillmentInfo {
570620
}
571621

572622
// [Product][google.cloud.retail.v2beta.Product] image. Recommendations AI and
573-
// Retail Search do not use product images to improve prediction and search
574-
// results. However, product images can be returned in results, and are shown in
575-
// prediction or search previews in the console.
623+
// Retail Search use product images to improve prediction and search results.
624+
// Product images can be returned in results, and are shown in prediction or
625+
// search previews in the console. Please try to provide correct product images
626+
// and avoid using images with size too small.
576627
message Image {
577628
// Required. URI of the image.
578629
//
@@ -793,9 +844,7 @@ message UserInfo {
793844
// is set.
794845
string ip_address = 2;
795846

796-
// User agent as included in the HTTP header. Required for getting
797-
// [SearchResponse.sponsored_results][google.cloud.retail.v2beta.SearchResponse.sponsored_results].
798-
//
847+
// User agent as included in the HTTP header.
799848
// The field must be a UTF-8 encoded string with a length limit of 1,000
800849
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
801850
//
@@ -822,17 +871,17 @@ message UserInfo {
822871
// The inventory information at a place (e.g. a store) identified
823872
// by a place ID.
824873
message LocalInventory {
825-
// The place ID for the current set of inventory information.
826-
string place_id = 1;
874+
// Optional. The place ID for the current set of inventory information.
875+
string place_id = 1 [(google.api.field_behavior) = OPTIONAL];
827876

828-
// Product price and cost information.
877+
// Optional. Product price and cost information.
829878
//
830879
// Google Merchant Center property
831880
// [price](https://support.google.com/merchants/answer/6324371).
832-
PriceInfo price_info = 2;
881+
PriceInfo price_info = 2 [(google.api.field_behavior) = OPTIONAL];
833882

834-
// Additional local inventory attributes, for example, store name, promotion
835-
// tags, etc.
883+
// Optional. Additional local inventory attributes, for example, store name,
884+
// promotion tags, etc.
836885
//
837886
// This field needs to pass all below criteria, otherwise an INVALID_ARGUMENT
838887
// error is returned:
@@ -849,9 +898,10 @@ message LocalInventory {
849898
// unset or set to false.
850899
// * The max summed total bytes of custom attribute keys and values per
851900
// product is 5MiB.
852-
map<string, CustomAttribute> attributes = 3;
901+
map<string, CustomAttribute> attributes = 3
902+
[(google.api.field_behavior) = OPTIONAL];
853903

854-
// Input only. Supported fulfillment types. Valid fulfillment type values
904+
// Optional. Supported fulfillment types. Valid fulfillment type values
855905
// include commonly used types (such as pickup in store and same day
856906
// delivery), and custom types. Customers have to map custom types to their
857907
// display names before rendering UI.
@@ -874,5 +924,22 @@ message LocalInventory {
874924
// All the elements must be distinct. Otherwise, an INVALID_ARGUMENT error is
875925
// returned.
876926
repeated string fulfillment_types = 4
877-
[(google.api.field_behavior) = INPUT_ONLY];
927+
[(google.api.field_behavior) = OPTIONAL];
928+
}
929+
930+
// Metadata for pinning to be returned in the response.
931+
// This is used for distinguishing between applied vs dropped pins.
932+
message PinControlMetadata {
933+
// List of product ids which have associated pins.
934+
message ProductPins {
935+
// List of product ids which have associated pins.
936+
repeated string product_id = 1;
937+
}
938+
939+
// Map of all matched pins, keyed by pin position.
940+
map<int64, ProductPins> all_matched_pins = 1;
941+
942+
// Map of pins that were dropped due to overlap with other matching pins,
943+
// keyed by pin position.
944+
map<int64, ProductPins> dropped_pins = 2;
878945
}

‎google/cloud/retail/v2beta/completion_service.proto‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ message CompleteQueryRequest {
9090
// The maximum number of allowed characters is 255.
9191
string query = 2 [(google.api.field_behavior) = REQUIRED];
9292

93-
// Required field. A unique identifier for tracking visitors. For example,
93+
// Recommended field. A unique identifier for tracking visitors. For example,
9494
// this could be implemented with an HTTP cookie, which should be able to
9595
// uniquely identify a visitor on a single device. This unique identifier
9696
// should not change if the visitor logs in or out of the website.
@@ -129,10 +129,11 @@ message CompleteQueryRequest {
129129
string device_type = 4;
130130

131131
// Determines which dataset to use for fetching completion. "user-data" will
132-
// use the imported dataset through
132+
// use the dataset imported through
133133
// [CompletionService.ImportCompletionData][google.cloud.retail.v2beta.CompletionService.ImportCompletionData].
134-
// "cloud-retail" will use the dataset generated by cloud retail based on user
135-
// events. If leave empty, it will use the "user-data".
134+
// `cloud-retail` will use the dataset generated by Cloud Retail based on user
135+
// events. If left empty, completions will be fetched from the `user-data`
136+
// dataset.
136137
//
137138
// Current supported values:
138139
//
@@ -153,15 +154,20 @@ message CompleteQueryRequest {
153154

154155
// If true, attribute suggestions are enabled and provided in the response.
155156
//
156-
// This field is only available for the "cloud-retail" dataset.
157+
// This field is only available for the `cloud-retail` dataset.
157158
bool enable_attribute_suggestions = 9;
158159

159160
// The entity for customers who run multiple entities, domains, sites, or
160161
// regions, for example, `Google US`, `Google Ads`, `Waymo`,
161162
// `google.com`, `youtube.com`, etc.
162163
// If this is set, it must be an exact match with
163164
// [UserEvent.entity][google.cloud.retail.v2beta.UserEvent.entity] to get
164-
// per-entity autocomplete results.
165+
// per-entity autocomplete results. This field will be applied to
166+
// `completion_results` only. It has no effect on the `attribute_results`.
167+
// Also, this entity should be limited to 256 characters, if too long, it will
168+
// be truncated to 256 characters in both generation and serving time, and may
169+
// lead to mis-match. To ensure it works, please set the entity with string
170+
// within 256 characters.
165171
string entity = 10;
166172
}
167173

@@ -174,10 +180,10 @@ message CompleteQueryResponse {
174180

175181
// Custom attributes for the suggestion term.
176182
//
177-
// * For "user-data", the attributes are additional custom attributes
183+
// * For `user-data`, the attributes are additional custom attributes
178184
// ingested through BigQuery.
179185
//
180-
// * For "cloud-retail", the attributes are product attributes generated
186+
// * For `cloud-retail`, the attributes are product attributes generated
181187
// by Cloud Retail. It requires
182188
// [UserEvent.product_details][google.cloud.retail.v2beta.UserEvent.product_details]
183189
// is imported properly.
@@ -193,8 +199,8 @@ message CompleteQueryResponse {
193199
}
194200

195201
// Resource that represents attribute results.
196-
// The list of suggestions for the attribute.
197202
message AttributeResult {
203+
// The list of suggestions for the attribute.
198204
repeated string suggestions = 1;
199205
}
200206

@@ -232,7 +238,7 @@ message CompleteQueryResponse {
232238
repeated RecentSearchResult recent_search_results = 3 [deprecated = true];
233239

234240
// A map of matched attribute suggestions. This field is only available for
235-
// "cloud-retail" dataset.
241+
// `cloud-retail` dataset.
236242
//
237243
// Current supported keys:
238244
//

‎google/cloud/retail/v2beta/import_config.proto‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,6 @@ message BigQuerySource {
8181
// is not partitioned.
8282
oneof partition {
8383
// BigQuery time partitioned table's _PARTITIONDATE in YYYY-MM-DD format.
84-
//
85-
// Only supported in
86-
// [ImportProductsRequest][google.cloud.retail.v2beta.ImportProductsRequest].
8784
google.type.Date partition_date = 6;
8885
}
8986

‎google/cloud/retail/v2beta/model.proto‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,6 @@ message Model {
197197
// `frequently-bought-together`, `page-optimization`, `similar-items`,
198198
// `buy-it-again`, `on-sale-items`, and `recently-viewed`(readonly value).
199199
//
200-
//
201200
// This field together with
202201
// [optimization_objective][google.cloud.retail.v2beta.Model.optimization_objective]
203202
// describe model metadata to use to control model training and serving.

‎google/cloud/retail/v2beta/product.proto‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -572,7 +572,6 @@ message Product {
572572
// * [name][google.cloud.retail.v2beta.Product.name]
573573
// * [color_info][google.cloud.retail.v2beta.Product.color_info]
574574
//
575-
//
576575
// Note: Returning more fields in
577576
// [SearchResponse][google.cloud.retail.v2beta.SearchResponse] can increase
578577
// response payload size and serving latency.

‎google/cloud/retail/v2beta/retail_v2beta.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
type: google.api.Service
22
config_version: 3
33
name: retail.googleapis.com
4-
title: Vertex AI Search for Retail API
4+
title: Vertex AI Search for commerce API
55

66
apis:
77
- name: google.cloud.location.Locations
@@ -54,7 +54,7 @@ types:
5454

5555
documentation:
5656
summary: |-
57-
Vertex AI Search for Retail API is made up of Retail Search, Browse and
57+
Vertex AI Search for commerce API is made up of Retail Search, Browse and
5858
Recommendations. These discovery AI solutions help you implement
5959
personalized search, browse and recommendations, based on machine learning
6060
models, across your websites and mobile applications.

0 commit comments

Comments
 (0)