Skip to content

Commit 1ac7dc2

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: 752323436
1 parent 2f29b4c commit 1ac7dc2

12 files changed

Lines changed: 200 additions & 94 deletions

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

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

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

Lines changed: 30 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -59,38 +59,39 @@ service CatalogService {
5959
}
6060

6161
// Set a specified branch id as default branch. API methods such as
62-
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search],
63-
// [ProductService.GetProduct][google.cloud.retail.v2.ProductService.GetProduct],
64-
// [ProductService.ListProducts][google.cloud.retail.v2.ProductService.ListProducts]
65-
// will treat requests using "default_branch" to the actual branch id set as
66-
// default.
62+
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search],
63+
// [ProductService.GetProduct][google.cloud.retail.v2.ProductService.GetProduct],
64+
// [ProductService.ListProducts][google.cloud.retail.v2.ProductService.ListProducts]
65+
// will treat requests using "default_branch" to the actual branch id set as
66+
// default.
6767
//
68-
// For example, if `projects/*/locations/*/catalogs/*/branches/1` is set as
69-
// default, setting
70-
// [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to
71-
// `projects/*/locations/*/catalogs/*/branches/default_branch` is equivalent
72-
// to setting
73-
// [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to
74-
// `projects/*/locations/*/catalogs/*/branches/1`.
68+
// For example, if `projects/*/locations/*/catalogs/*/branches/1` is set as
69+
// default, setting
70+
// [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to
71+
// `projects/*/locations/*/catalogs/*/branches/default_branch` is equivalent
72+
// to setting
73+
// [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to
74+
// `projects/*/locations/*/catalogs/*/branches/1`.
7575
//
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.v2.SearchRequest.branch] to
81-
// route the traffic to this staging branch.
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
79+
// while keeping using
80+
// `projects/*/locations/*/catalogs/*/branches/default_branch` as
81+
// [SearchRequest.branch][google.cloud.retail.v2.SearchRequest.branch] to
82+
// route the traffic to this staging branch.
8283
//
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.
84+
// CAUTION: If you have live predict/search traffic, switching the default
85+
// branch could potentially cause outages if the ID space of the new branch
86+
// is very different from the old one.
8687
//
87-
// More specifically:
88+
// More specifically:
8889
//
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}.
90+
// * PredictionService will only return product IDs from branch {newBranch}.
91+
// * SearchService will only return product IDs from branch {newBranch}
92+
// (if branch is not explicitly set).
93+
// * UserEventService will only join events with products from branch
94+
// {newBranch}.
9495
rpc SetDefaultBranch(SetDefaultBranchRequest)
9596
returns (google.protobuf.Empty) {
9697
option (google.api.http) = {
@@ -101,8 +102,8 @@ service CatalogService {
101102
}
102103

103104
// Get which branch is currently default branch set by
104-
// [CatalogService.SetDefaultBranch][google.cloud.retail.v2.CatalogService.SetDefaultBranch]
105-
// method under a specified parent catalog.
105+
// [CatalogService.SetDefaultBranch][google.cloud.retail.v2.CatalogService.SetDefaultBranch]
106+
// method under a specified parent catalog.
106107
rpc GetDefaultBranch(GetDefaultBranchRequest)
107108
returns (GetDefaultBranchResponse) {
108109
option (google.api.http) = {

‎google/cloud/retail/v2/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

@@ -367,6 +367,48 @@ message Rule {
367367
repeated string attribute_names = 1;
368368
}
369369

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

400442
// Remove an attribute as a facet in the request (if present).
401443
RemoveFacetAction remove_facet_action = 13;
444+
445+
// Pins one or more specified products to a specific position in the
446+
// results.
447+
PinAction pin_action = 14;
402448
}
403449

404450
// Required. The condition that triggers the rule.
@@ -443,9 +489,9 @@ message Audience {
443489
message ColorInfo {
444490
// The standard color families. Strongly recommended to use the following
445491
// standard color groups: "Red", "Pink", "Orange", "Yellow", "Purple",
446-
// "Green", "Cyan", "Blue", "Brown", "White", "Gray", "Black" and
447-
// "Mixed". Normally it is expected to have only 1 color family. May consider
448-
// using single "Mixed" instead of multiple values.
492+
// "Green", "Cyan", "Blue", "Brown", "White", "Gray", "Black" and "Mixed".
493+
// Normally it is expected to have only 1 color family. May consider using
494+
// single "Mixed" instead of multiple values.
449495
//
450496
// A maximum of 5 values are allowed. Each value must be a UTF-8 encoded
451497
// string with a length limit of 128 characters. Otherwise, an
@@ -454,6 +500,10 @@ message ColorInfo {
454500
// Google Merchant Center property
455501
// [color](https://support.google.com/merchants/answer/6324487). Schema.org
456502
// property [Product.color](https://schema.org/color).
503+
//
504+
// The colorFamilies field as a system attribute is not a required field but
505+
// strongly recommended to be specified. Google Search models treat this field
506+
// as more important than a custom product attribute when specified.
457507
repeated string color_families = 1;
458508

459509
// The color display names, which may be different from standard color family
@@ -565,9 +615,10 @@ message FulfillmentInfo {
565615
}
566616

567617
// [Product][google.cloud.retail.v2.Product] image. Recommendations AI and
568-
// Retail Search do not use product images to improve prediction and search
569-
// results. However, product images can be returned in results, and are shown in
570-
// prediction or search previews in the console.
618+
// Retail Search use product images to improve prediction and search results.
619+
// Product images can be returned in results, and are shown in prediction or
620+
// search previews in the console. Please try to provide correct product images
621+
// and avoid using images with size too small.
571622
message Image {
572623
// Required. URI of the image.
573624
//
@@ -782,9 +833,7 @@ message UserInfo {
782833
// is set.
783834
string ip_address = 2;
784835

785-
// User agent as included in the HTTP header. Required for getting
786-
// [SearchResponse.sponsored_results][google.cloud.retail.v2.SearchResponse.sponsored_results].
787-
//
836+
// User agent as included in the HTTP header.
788837
// The field must be a UTF-8 encoded string with a length limit of 1,000
789838
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
790839
//
@@ -811,17 +860,17 @@ message UserInfo {
811860
// The inventory information at a place (e.g. a store) identified
812861
// by a place ID.
813862
message LocalInventory {
814-
// The place ID for the current set of inventory information.
815-
string place_id = 1;
863+
// Optional. The place ID for the current set of inventory information.
864+
string place_id = 1 [(google.api.field_behavior) = OPTIONAL];
816865

817-
// Product price and cost information.
866+
// Optional. Product price and cost information.
818867
//
819868
// Google Merchant Center property
820869
// [price](https://support.google.com/merchants/answer/6324371).
821-
PriceInfo price_info = 2;
870+
PriceInfo price_info = 2 [(google.api.field_behavior) = OPTIONAL];
822871

823-
// Additional local inventory attributes, for example, store name, promotion
824-
// tags, etc.
872+
// Optional. Additional local inventory attributes, for example, store name,
873+
// promotion tags, etc.
825874
//
826875
// This field needs to pass all below criteria, otherwise an INVALID_ARGUMENT
827876
// error is returned:
@@ -838,9 +887,10 @@ message LocalInventory {
838887
// unset or set to false.
839888
// * The max summed total bytes of custom attribute keys and values per
840889
// product is 5MiB.
841-
map<string, CustomAttribute> attributes = 3;
890+
map<string, CustomAttribute> attributes = 3
891+
[(google.api.field_behavior) = OPTIONAL];
842892

843-
// Input only. Supported fulfillment types. Valid fulfillment type values
893+
// Optional. Supported fulfillment types. Valid fulfillment type values
844894
// include commonly used types (such as pickup in store and same day
845895
// delivery), and custom types. Customers have to map custom types to their
846896
// display names before rendering UI.
@@ -863,5 +913,22 @@ message LocalInventory {
863913
// All the elements must be distinct. Otherwise, an INVALID_ARGUMENT error is
864914
// returned.
865915
repeated string fulfillment_types = 4
866-
[(google.api.field_behavior) = INPUT_ONLY];
916+
[(google.api.field_behavior) = OPTIONAL];
917+
}
918+
919+
// Metadata for pinning to be returned in the response.
920+
// This is used for distinguishing between applied vs dropped pins.
921+
message PinControlMetadata {
922+
// List of product ids which have associated pins.
923+
message ProductPins {
924+
// List of product ids which have associated pins.
925+
repeated string product_id = 1;
926+
}
927+
928+
// Map of all matched pins, keyed by pin position.
929+
map<int64, ProductPins> all_matched_pins = 1;
930+
931+
// Map of pins that were dropped due to overlap with other matching pins,
932+
// keyed by pin position.
933+
map<int64, ProductPins> dropped_pins = 2;
867934
}

‎google/cloud/retail/v2/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.v2.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.v2.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.v2.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/v2/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.v2.ImportProductsRequest].
8784
google.type.Date partition_date = 6;
8885
}
8986

‎google/cloud/retail/v2/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.v2.Model.optimization_objective]
203202
// describe model metadata to use to control model training and serving.

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -562,7 +562,6 @@ message Product {
562562
// * [name][google.cloud.retail.v2.Product.name]
563563
// * [color_info][google.cloud.retail.v2.Product.color_info]
564564
//
565-
//
566565
// Note: Returning more fields in
567566
// [SearchResponse][google.cloud.retail.v2.SearchResponse] can increase
568567
// response payload size and serving latency.

‎google/cloud/retail/v2/retail_v2.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
@@ -50,7 +50,7 @@ types:
5050

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

0 commit comments

Comments
 (0)