Skip to content

Commit 4d00815

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
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
1 parent 94287f4 commit 4d00815

15 files changed

Lines changed: 540 additions & 160 deletions

‎google/cloud/retail/logging/error_log.proto‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ syntax = "proto3";
1616

1717
package google.cloud.retail.logging;
1818

19-
import "google/api/annotations.proto";
2019
import "google/protobuf/struct.proto";
2120
import "google/rpc/status.proto";
2221

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ proto_library(
2929
"prediction_service.proto",
3030
"product.proto",
3131
"product_service.proto",
32+
"promotion.proto",
3233
"purge_config.proto",
3334
"search_service.proto",
3435
"user_event.proto",
@@ -86,7 +87,9 @@ java_grpc_library(
8687
java_gapic_library(
8788
name = "retail_java_gapic",
8889
srcs = [":retail_proto_with_info"],
90+
gapic_yaml = None,
8991
grpc_service_config = "retail_grpc_service_config.json",
92+
service_yaml = "retail_v2.yaml",
9093
test_deps = [
9194
":retail_java_grpc",
9295
],

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

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,6 @@ service CatalogService {
9191
// (if branch is not explicitly set).
9292
// * UserEventService will only join events with products from branch
9393
// {newBranch}.
94-
//
95-
// This feature is only available for users who have Retail Search enabled.
96-
// Please submit a form [here](https://cloud.google.com/contact) to contact
97-
// cloud sales if you are interested in using Retail Search.
9894
rpc SetDefaultBranch(SetDefaultBranchRequest)
9995
returns (google.protobuf.Empty) {
10096
option (google.api.http) = {
@@ -107,10 +103,6 @@ service CatalogService {
107103
// Get which branch is currently default branch set by
108104
// [CatalogService.SetDefaultBranch][google.cloud.retail.v2.CatalogService.SetDefaultBranch]
109105
// method under a specified parent catalog.
110-
//
111-
// This feature is only available for users who have Retail Search enabled.
112-
// Please submit a form [here](https://cloud.google.com/contact) to contact
113-
// cloud sales if you are interested in using Retail Search.
114106
rpc GetDefaultBranch(GetDefaultBranchRequest)
115107
returns (GetDefaultBranchResponse) {
116108
option (google.api.http) = {
@@ -205,6 +197,10 @@ message SetDefaultBranchRequest {
205197
//
206198
// This field must be one of "0", "1" or "2". Otherwise, an INVALID_ARGUMENT
207199
// error is returned.
200+
//
201+
// If there are no sufficient active products in the targeted branch and
202+
// [force][google.cloud.retail.v2.SetDefaultBranchRequest.force] is not set, a
203+
// FAILED_PRECONDITION error is returned.
208204
string branch_id = 2 [
209205
(google.api.resource_reference) = { type: "retail.googleapis.com/Branch" }
210206
];
@@ -216,6 +212,11 @@ message SetDefaultBranchRequest {
216212
// This field must be a UTF-8 encoded string with a length limit of 1,000
217213
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
218214
string note = 3;
215+
216+
// If set to true, it permits switching to a branch with
217+
// [branch_id][google.cloud.retail.v2.SetDefaultBranchRequest.branch_id] even
218+
// if it has no sufficient active products.
219+
bool force = 4;
219220
}
220221

221222
// Request message to show which branch is currently the default branch.

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

Lines changed: 80 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -99,9 +99,8 @@ message CustomAttribute {
9999
// The textual values of this custom attribute. For example, `["yellow",
100100
// "green"]` when the key is "color".
101101
//
102-
// At most 400 values are allowed. Empty values are not allowed. Each value
103-
// must be a UTF-8 encoded string with a length limit of 256 characters.
104-
// Otherwise, an INVALID_ARGUMENT error is returned.
102+
// Empty string is not allowed. Otherwise, an INVALID_ARGUMENT error is
103+
// returned.
105104
//
106105
// Exactly one of [text][google.cloud.retail.v2.CustomAttribute.text] or
107106
// [numbers][google.cloud.retail.v2.CustomAttribute.numbers] should be set.
@@ -111,15 +110,16 @@ message CustomAttribute {
111110
// The numerical values of this custom attribute. For example, `[2.3, 15.4]`
112111
// when the key is "lengths_cm".
113112
//
114-
// At most 400 values are allowed.Otherwise, an INVALID_ARGUMENT error is
115-
// returned.
116-
//
117113
// Exactly one of [text][google.cloud.retail.v2.CustomAttribute.text] or
118114
// [numbers][google.cloud.retail.v2.CustomAttribute.numbers] should be set.
119115
// Otherwise, an INVALID_ARGUMENT error is returned.
120116
repeated double numbers = 2;
121117

122-
// If true, custom attribute values are searchable by text queries in
118+
// This field will only be used when
119+
// [AttributesConfig.attribute_config_level][] of the
120+
// [Catalog][google.cloud.retail.v2.Catalog] is
121+
// 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
122+
// searchable by text queries in
123123
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
124124
//
125125
// This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
@@ -128,8 +128,11 @@ message CustomAttribute {
128128
// set. Otherwise, a INVALID_ARGUMENT error is returned.
129129
optional bool searchable = 3;
130130

131-
// If true, custom attribute values are indexed, so that it can be filtered,
132-
// faceted or boosted in
131+
// This field will only be used when
132+
// [AttributesConfig.attribute_config_level][] of the
133+
// [Catalog][google.cloud.retail.v2.Catalog] is
134+
// 'PRODUCT_LEVEL_ATTRIBUTE_CONFIG', if true, custom attribute values are
135+
// indexed, so that it can be filtered, faceted or boosted in
133136
// [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
134137
//
135138
// This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
@@ -178,7 +181,10 @@ message FulfillmentInfo {
178181
repeated string place_ids = 2;
179182
}
180183

181-
// [Product][google.cloud.retail.v2.Product] thumbnail/detail image.
184+
// [Product][google.cloud.retail.v2.Product] image. Recommendations AI and
185+
// Retail Search do not use product images to improve prediction and search
186+
// results. However, product images can be returned in results, and are shown in
187+
// prediction or search previews in the console.
182188
message Image {
183189
// Required. URI of the image.
184190
//
@@ -274,7 +280,7 @@ message PriceInfo {
274280
//
275281
// Google Merchant Center property
276282
// [price](https://support.google.com/merchants/answer/6324371). Schema.org
277-
// property [Offer.priceSpecification](https://schema.org/priceSpecification).
283+
// property [Offer.price](https://schema.org/price).
278284
float price = 2;
279285

280286
// Price of the product without any discount. If zero, by default set to be
@@ -364,19 +370,24 @@ message UserInfo {
364370
// Highly recommended for logged-in users. Unique identifier for logged-in
365371
// user, such as a user name.
366372
//
373+
// Always use a hashed value for this ID.
374+
//
367375
// The field must be a UTF-8 encoded string with a length limit of 128
368376
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
369377
string user_id = 1;
370378

371-
// The end user's IP address. Required for getting
372-
// [SearchResponse.sponsored_results][google.cloud.retail.v2.SearchResponse.sponsored_results].
373-
// This field is used to extract location information for personalization.
379+
// The end user's IP address. This field is used to extract location
380+
// information for personalization.
374381
//
375382
// This field must be either an IPv4 address (e.g. "104.133.9.80") or an IPv6
376383
// address (e.g. "2001:0db8:85a3:0000:0000:8a2e:0370:7334"). Otherwise, an
377384
// INVALID_ARGUMENT error is returned.
378385
//
379-
// This should not be set when using the JavaScript tag in
386+
// This should not be set when:
387+
//
388+
// * setting
389+
// [SearchRequest.user_info][google.cloud.retail.v2.SearchRequest.user_info].
390+
// * using the JavaScript tag in
380391
// [UserEventService.CollectUserEvent][google.cloud.retail.v2.UserEventService.CollectUserEvent]
381392
// or if
382393
// [direct_user_request][google.cloud.retail.v2.UserInfo.direct_user_request]
@@ -409,16 +420,60 @@ message UserInfo {
409420
bool direct_user_request = 4;
410421
}
411422

412-
// Promotion information.
413-
message Promotion {
414-
// ID of the promotion. For example, "free gift".
415-
//
416-
// The value value must be a UTF-8 encoded string with a length limit of 128
417-
// characters, and match the pattern: `[a-zA-Z][a-zA-Z0-9_]*`. For example,
418-
// id0LikeThis or ID_1_LIKE_THIS. Otherwise, an INVALID_ARGUMENT error is
419-
// returned.
423+
// The inventory information at a place (e.g. a store) identified
424+
// by a place ID.
425+
message LocalInventory {
426+
// The place ID for the current set of inventory information.
427+
string place_id = 1;
428+
429+
// Product price and cost information.
420430
//
421431
// Google Merchant Center property
422-
// [promotion](https://support.google.com/merchants/answer/7050148).
423-
string promotion_id = 1;
432+
// [price](https://support.google.com/merchants/answer/6324371).
433+
PriceInfo price_info = 2;
434+
435+
// Additional local inventory attributes, for example, store name, promotion
436+
// tags, etc.
437+
//
438+
// This field needs to pass all below criteria, otherwise an INVALID_ARGUMENT
439+
// error is returned:
440+
//
441+
// * At most 30 attributes are allowed.
442+
// * The key must be a UTF-8 encoded string with a length limit of 32
443+
// characters.
444+
// * The key must match the pattern: `[a-zA-Z0-9][a-zA-Z0-9_]*`. For example,
445+
// key0LikeThis or KEY_1_LIKE_THIS.
446+
// * The attribute values must be of the same type (text or number).
447+
// * Only 1 value is allowed for each attribute.
448+
// * For text values, the length limit is 256 UTF-8 characters.
449+
// * The attribute does not support search. The `searchable` field should be
450+
// unset or set to false.
451+
// * The max summed total bytes of custom attribute keys and values per
452+
// product is 5MiB.
453+
map<string, CustomAttribute> attributes = 3;
454+
455+
// Input only. Supported fulfillment types. Valid fulfillment type values
456+
// include commonly used types (such as pickup in store and same day
457+
// delivery), and custom types. Customers have to map custom types to their
458+
// display names before rendering UI.
459+
//
460+
// Supported values:
461+
//
462+
// * "pickup-in-store"
463+
// * "ship-to-store"
464+
// * "same-day-delivery"
465+
// * "next-day-delivery"
466+
// * "custom-type-1"
467+
// * "custom-type-2"
468+
// * "custom-type-3"
469+
// * "custom-type-4"
470+
// * "custom-type-5"
471+
//
472+
// If this field is set to an invalid value other than these, an
473+
// INVALID_ARGUMENT error is returned.
474+
//
475+
// All the elements must be distinct. Otherwise, an INVALID_ARGUMENT error is
476+
// returned.
477+
repeated string fulfillment_types = 4
478+
[(google.api.field_behavior) = INPUT_ONLY];
424479
}

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

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,7 @@ option ruby_package = "Google::Cloud::Retail::V2";
3636
// Auto-completion service for retail.
3737
//
3838
// This feature is only available for users who have Retail Search enabled.
39-
// Please submit a form [here](https://cloud.google.com/contact) to contact
40-
// cloud sales if you are interested in using Retail Search.
39+
// Please enable Retail Search on Cloud Console before using this feature.
4140
service CompletionService {
4241
option (google.api.default_host) = "retail.googleapis.com";
4342
option (google.api.oauth_scopes) =
@@ -46,8 +45,7 @@ service CompletionService {
4645
// Completes the specified prefix with keyword suggestions.
4746
//
4847
// This feature is only available for users who have Retail Search enabled.
49-
// Please submit a form [here](https://cloud.google.com/contact) to contact
50-
// cloud sales if you are interested in using Retail Search.
48+
// Please enable Retail Search on Cloud Console before using this feature.
5149
rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) {
5250
option (google.api.http) = {
5351
get: "/v2/{catalog=projects/*/locations/*/catalogs/*}:completeQuery"
@@ -56,11 +54,13 @@ service CompletionService {
5654

5755
// Bulk import of processed completion dataset.
5856
//
59-
// Request processing may be synchronous. Partial updating is not supported.
57+
// Request processing is asynchronous. Partial updating is not supported.
58+
//
59+
// The operation is successfully finished only after the imported suggestions
60+
// are indexed successfully and ready for serving. The process takes hours.
6061
//
6162
// This feature is only available for users who have Retail Search enabled.
62-
// Please submit a form [here](https://cloud.google.com/contact) to contact
63-
// cloud sales if you are interested in using Retail Search.
63+
// Please enable Retail Search on Cloud Console before using this feature.
6464
rpc ImportCompletionData(ImportCompletionDataRequest)
6565
returns (google.longrunning.Operation) {
6666
option (google.api.http) = {
@@ -90,22 +90,21 @@ message CompleteQueryRequest {
9090
// The maximum number of allowed characters is 255.
9191
string query = 2 [(google.api.field_behavior) = REQUIRED];
9292

93-
// A unique identifier for tracking visitors. For example, this could be
94-
// implemented with an HTTP cookie, which should be able to uniquely identify
95-
// a visitor on a single device. This unique identifier should not change if
96-
// the visitor logs in or out of the website.
93+
// Required field. A unique identifier for tracking visitors. For example,
94+
// this could be implemented with an HTTP cookie, which should be able to
95+
// uniquely identify a visitor on a single device. This unique identifier
96+
// should not change if the visitor logs in or out of the website.
9797
//
9898
// The field must be a UTF-8 encoded string with a length limit of 128
9999
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
100100
string visitor_id = 7;
101101

102-
// The list of languages of the query. This is
103-
// the BCP-47 language code, such as "en-US" or "sr-Latn".
104-
// For more information, see
105-
// [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47).
106-
//
107-
// The maximum number of allowed characters is 255.
108-
// Only "en-US" is currently supported.
102+
// The language filters applied to the output suggestions. If set, it should
103+
// contain the language of the query. If not set, suggestions are returned
104+
// without considering language restrictions. This is the BCP-47 language
105+
// code, such as "en-US" or "sr-Latn". For more information, see [Tags for
106+
// Identifying Languages](https://tools.ietf.org/html/bcp47). The maximum
107+
// number of language codes is 3.
109108
repeated string language_codes = 3;
110109

111110
// The device type context for completion suggestions.
@@ -154,7 +153,11 @@ message CompleteQueryResponse {
154153
// The suggestion for the query.
155154
string suggestion = 1;
156155

157-
// Additional custom attributes ingested through BigQuery.
156+
// Custom attributes for the suggestion term.
157+
// * For "user-data", the attributes are additional custom attributes
158+
// ingested through BigQuery.
159+
// * For "cloud-retail", the attributes are product attributes generated
160+
// by Cloud Retail.
158161
map<string, CustomAttribute> attributes = 2;
159162
}
160163

@@ -169,9 +172,9 @@ message CompleteQueryResponse {
169172
repeated CompletionResult completion_results = 1;
170173

171174
// A unique complete token. This should be included in the
172-
// [SearchRequest][google.cloud.retail.v2.SearchRequest] resulting from this
173-
// completion, which enables accurate attribution of complete model
174-
// performance.
175+
// [UserEvent.completion_detail][google.cloud.retail.v2.UserEvent.completion_detail]
176+
// for search events resulting from this completion, which enables accurate
177+
// attribution of complete model performance.
175178
string attribution_token = 2;
176179

177180
// Matched recent searches of this user. The maximum number of recent searches

0 commit comments

Comments
 (0)