Skip to content

Commit 1422653

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: add availability field to Localnventory
feat: add new fields including language_code, region_code and place_id to SearchRequest. feat: add pin_control_metadata to SearchResponse. fix!: An existing message `LlmEmbeddingConfig` is removed. fix!: An existing field `llm_embedding_config` is removed from message `.google.cloud.retail.v2alpha.Model` docs: keep the API doc up-to-date with recent changes PiperOrigin-RevId: 750240703
1 parent f6ed507 commit 1422653

13 files changed

Lines changed: 247 additions & 110 deletions

‎google/cloud/retail/v2alpha/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ java_grpc_library(
108108
java_gapic_library(
109109
name = "retail_java_gapic",
110110
srcs = [":retail_proto_with_info"],
111+
gapic_yaml = None,
111112
grpc_service_config = "retail_grpc_service_config.json",
112113
rest_numeric_enums = True,
113114
service_yaml = "retail_v2alpha.yaml",

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -302,8 +302,7 @@ message CatalogAttribute {
302302
//
303303
// [CatalogAttribute][google.cloud.retail.v2alpha.CatalogAttribute] can be
304304
// pre-loaded by using
305-
// [CatalogService.AddCatalogAttribute][google.cloud.retail.v2alpha.CatalogService.AddCatalogAttribute],
306-
// [CatalogService.ImportCatalogAttributes][google.cloud.retail.v2alpha.CatalogService.ImportCatalogAttributes],
305+
// [CatalogService.AddCatalogAttribute][google.cloud.retail.v2alpha.CatalogService.AddCatalogAttribute]
307306
// or
308307
// [CatalogService.UpdateAttributesConfig][google.cloud.retail.v2alpha.CatalogService.UpdateAttributesConfig]
309308
// APIs. This field is `False` for pre-loaded

‎google/cloud/retail/v2alpha/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.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.
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.
6767
//
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`.
68+
// For example, if `projects/*/locations/*/catalogs/*/branches/1` is set as
69+
// default, setting
70+
// [SearchRequest.branch][google.cloud.retail.v2alpha.SearchRequest.branch]
71+
// to `projects/*/locations/*/catalogs/*/branches/default_branch` is
72+
// equivalent to setting
73+
// [SearchRequest.branch][google.cloud.retail.v2alpha.SearchRequest.branch]
74+
// to `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.v2alpha.SearchRequest.branch]
81-
// to 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.v2alpha.SearchRequest.branch]
82+
// to 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.v2alpha.CatalogService.SetDefaultBranch]
105-
// method under a specified parent catalog.
105+
// [CatalogService.SetDefaultBranch][google.cloud.retail.v2alpha.CatalogService.SetDefaultBranch]
106+
// method under a specified parent catalog.
106107
rpc GetDefaultBranch(GetDefaultBranchRequest)
107108
returns (GetDefaultBranchResponse) {
108109
option (google.api.http) = {

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

Lines changed: 132 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][google.cloud.retail.v2alpha.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.v2alpha.Condition.query_terms]
378+
// (for search only) or
379+
// [Condition.page_categories][google.cloud.retail.v2alpha.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.v2alpha.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.v2alpha.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
//
@@ -794,9 +845,7 @@ message UserInfo {
794845
// is set.
795846
string ip_address = 2;
796847

797-
// User agent as included in the HTTP header. Required for getting
798-
// [SearchResponse.sponsored_results][google.cloud.retail.v2alpha.SearchResponse.sponsored_results].
799-
//
848+
// User agent as included in the HTTP header.
800849
// The field must be a UTF-8 encoded string with a length limit of 1,000
801850
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
802851
//
@@ -823,17 +872,63 @@ message UserInfo {
823872
// The inventory information at a place (e.g. a store) identified
824873
// by a place ID.
825874
message LocalInventory {
826-
// The place ID for the current set of inventory information.
827-
string place_id = 1;
875+
// Product availability. If this field is unspecified, the product is
876+
// assumed to be in stock.
877+
enum Availability {
878+
// Default product availability. Default to
879+
// [Availability.IN_STOCK][google.cloud.retail.v2alpha.LocalInventory.Availability.IN_STOCK]
880+
// if unset.
881+
AVAILABILITY_UNSPECIFIED = 0;
882+
883+
// Product in stock.
884+
IN_STOCK = 1;
885+
886+
// Product out of stock.
887+
OUT_OF_STOCK = 2;
888+
889+
// Product that is in pre-order state.
890+
PREORDER = 3;
891+
892+
// Product that is back-ordered (i.e. temporarily out of stock).
893+
BACKORDER = 4;
894+
}
895+
896+
// Optional. The place ID for the current set of inventory information.
897+
string place_id = 1 [(google.api.field_behavior) = OPTIONAL];
828898

829-
// Product price and cost information.
899+
// Optional. Product price and cost information.
830900
//
831901
// Google Merchant Center property
832902
// [price](https://support.google.com/merchants/answer/6324371).
833-
PriceInfo price_info = 2;
903+
PriceInfo price_info = 2 [(google.api.field_behavior) = OPTIONAL];
904+
905+
// Optional. The availability of the
906+
// [Product][google.cloud.retail.v2alpha.Product] at this place_id. Default to
907+
// [Availability.IN_STOCK][google.cloud.retail.v2alpha.LocalInventory.Availability.IN_STOCK].
908+
//
909+
// For primary products with variants set the availability of the primary as
910+
// [Availability.OUT_OF_STOCK][google.cloud.retail.v2alpha.LocalInventory.Availability.OUT_OF_STOCK]
911+
// and set the true availability at the variant level. This way the primary
912+
// product will be considered "in stock" as long as it has at least one
913+
// variant in stock.
914+
//
915+
// For primary products with no variants set the true availability at the
916+
// primary level.
917+
//
918+
// Corresponding properties: Google Merchant Center property
919+
// [availability](https://support.google.com/merchants/answer/6324448).
920+
// Schema.org property [Offer.availability](https://schema.org/availability).
921+
//
922+
// This field is currently only used by the Recommendations API. For Search,
923+
// please make use of
924+
// [fulfillment_types][google.cloud.retail.v2alpha.LocalInventory.fulfillment_types]
925+
// or custom attributes for similar behaviour. See [here](
926+
// https://cloud.google.com/retail/docs/local-inventory-updates#local-inventory-update-methods)
927+
// for more details.
928+
Availability availability = 5 [(google.api.field_behavior) = OPTIONAL];
834929

835-
// Additional local inventory attributes, for example, store name, promotion
836-
// tags, etc.
930+
// Optional. Additional local inventory attributes, for example, store name,
931+
// promotion tags, etc.
837932
//
838933
// This field needs to pass all below criteria, otherwise an INVALID_ARGUMENT
839934
// error is returned:
@@ -850,9 +945,10 @@ message LocalInventory {
850945
// unset or set to false.
851946
// * The max summed total bytes of custom attribute keys and values per
852947
// product is 5MiB.
853-
map<string, CustomAttribute> attributes = 3;
948+
map<string, CustomAttribute> attributes = 3
949+
[(google.api.field_behavior) = OPTIONAL];
854950

855-
// Input only. Supported fulfillment types. Valid fulfillment type values
951+
// Optional. Supported fulfillment types. Valid fulfillment type values
856952
// include commonly used types (such as pickup in store and same day
857953
// delivery), and custom types. Customers have to map custom types to their
858954
// display names before rendering UI.
@@ -875,5 +971,22 @@ message LocalInventory {
875971
// All the elements must be distinct. Otherwise, an INVALID_ARGUMENT error is
876972
// returned.
877973
repeated string fulfillment_types = 4
878-
[(google.api.field_behavior) = INPUT_ONLY];
974+
[(google.api.field_behavior) = OPTIONAL];
975+
}
976+
977+
// Metadata for pinning to be returned in the response.
978+
// This is used for distinguishing between applied vs dropped pins.
979+
message PinControlMetadata {
980+
// List of product ids which have associated pins.
981+
message ProductPins {
982+
// List of product ids which have associated pins.
983+
repeated string product_id = 1;
984+
}
985+
986+
// Map of all matched pins, keyed by pin position.
987+
map<int64, ProductPins> all_matched_pins = 1;
988+
989+
// Map of pins that were dropped due to overlap with other matching pins,
990+
// keyed by pin position.
991+
map<int64, ProductPins> dropped_pins = 2;
879992
}

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

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

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

132132
// Determines which dataset to use for fetching completion. "user-data" will
133-
// use the imported dataset through
133+
// use the dataset imported through
134134
// [CompletionService.ImportCompletionData][google.cloud.retail.v2alpha.CompletionService.ImportCompletionData].
135-
// "cloud-retail" will use the dataset generated by cloud retail based on user
136-
// events. If leave empty, it will use the "user-data".
135+
// `cloud-retail` will use the dataset generated by Cloud Retail based on user
136+
// events. If left empty, completions will be fetched from the `user-data`
137+
// dataset.
137138
//
138139
// Current supported values:
139140
//
@@ -154,15 +155,20 @@ message CompleteQueryRequest {
154155

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

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

@@ -175,10 +181,10 @@ message CompleteQueryResponse {
175181

176182
// Custom attributes for the suggestion term.
177183
//
178-
// * For "user-data", the attributes are additional custom attributes
184+
// * For `user-data`, the attributes are additional custom attributes
179185
// ingested through BigQuery.
180186
//
181-
// * For "cloud-retail", the attributes are product attributes generated
187+
// * For `cloud-retail`, the attributes are product attributes generated
182188
// by Cloud Retail. It requires
183189
// [UserEvent.product_details][google.cloud.retail.v2alpha.UserEvent.product_details]
184190
// is imported properly.
@@ -208,8 +214,8 @@ message CompleteQueryResponse {
208214
}
209215

210216
// Resource that represents attribute results.
211-
// The list of suggestions for the attribute.
212217
message AttributeResult {
218+
// The list of suggestions for the attribute.
213219
repeated string suggestions = 1;
214220
}
215221

@@ -247,7 +253,7 @@ message CompleteQueryResponse {
247253
repeated RecentSearchResult recent_search_results = 3 [deprecated = true];
248254

249255
// A map of matched attribute suggestions. This field is only available for
250-
// "cloud-retail" dataset.
256+
// `cloud-retail` dataset.
251257
//
252258
// Current supported keys:
253259
//

0 commit comments

Comments
 (0)