xref: /aosp_15_r20/external/googleapis/google/cloud/recommendationengine/v1beta1/catalog.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)
1// Copyright 2020 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.recommendationengine.v1beta1;
18
19import "google/api/field_behavior.proto";
20import "google/cloud/recommendationengine/v1beta1/common.proto";
21
22option csharp_namespace = "Google.Cloud.RecommendationEngine.V1Beta1";
23option go_package = "cloud.google.com/go/recommendationengine/apiv1beta1/recommendationenginepb;recommendationenginepb";
24option java_multiple_files = true;
25option java_package = "com.google.cloud.recommendationengine.v1beta1";
26option objc_class_prefix = "RECAI";
27option php_namespace = "Google\\Cloud\\RecommendationEngine\\V1beta1";
28option ruby_package = "Google::Cloud::RecommendationEngine::V1beta1";
29
30// CatalogItem captures all metadata information of items to be recommended.
31message CatalogItem {
32  // Category represents catalog item category hierarchy.
33  message CategoryHierarchy {
34    // Required. Catalog item categories. Each category should be a UTF-8
35    // encoded string with a length limit of 2 KiB.
36    //
37    // Note that the order in the list denotes the specificity (from least to
38    // most specific).
39    repeated string categories = 1 [(google.api.field_behavior) = REQUIRED];
40  }
41
42  // Required. Catalog item identifier. UTF-8 encoded string with a length limit
43  // of 128 bytes.
44  //
45  // This id must be unique among all catalog items within the same catalog. It
46  // should also be used when logging user events in order for the user events
47  // to be joined with the Catalog.
48  string id = 1 [(google.api.field_behavior) = REQUIRED];
49
50  // Required. Catalog item categories. This field is repeated for supporting
51  // one catalog item belonging to several parallel category hierarchies.
52  //
53  // For example, if a shoes product belongs to both
54  // ["Shoes & Accessories" -> "Shoes"] and
55  // ["Sports & Fitness" -> "Athletic Clothing" -> "Shoes"], it could be
56  // represented as:
57  //
58  //      "categoryHierarchies": [
59  //        { "categories": ["Shoes & Accessories", "Shoes"]},
60  //        { "categories": ["Sports & Fitness", "Athletic Clothing", "Shoes"] }
61  //      ]
62  repeated CategoryHierarchy category_hierarchies = 2 [(google.api.field_behavior) = REQUIRED];
63
64  // Required. Catalog item title. UTF-8 encoded string with a length limit of 1
65  // KiB.
66  string title = 3 [(google.api.field_behavior) = REQUIRED];
67
68  // Optional. Catalog item description. UTF-8 encoded string with a length
69  // limit of 5 KiB.
70  string description = 4 [(google.api.field_behavior) = OPTIONAL];
71
72  // Optional. Highly encouraged. Extra catalog item attributes to be
73  // included in the recommendation model. For example, for retail products,
74  // this could include the store name, vendor, style, color, etc. These are
75  // very strong signals for recommendation model, thus we highly recommend
76  // providing the item attributes here.
77  FeatureMap item_attributes = 5 [(google.api.field_behavior) = OPTIONAL];
78
79  // Optional. Language of the title/description/item_attributes. Use language
80  // tags defined by BCP 47. https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Our
81  // supported language codes include 'en', 'es', 'fr', 'de', 'ar', 'fa', 'zh',
82  // 'ja', 'ko', 'sv', 'ro', 'nl'. For other languages, contact
83  // your Google account manager.
84  string language_code = 6 [(google.api.field_behavior) = OPTIONAL];
85
86  // Optional. Filtering tags associated with the catalog item. Each tag should
87  // be a UTF-8 encoded string with a length limit of 1 KiB.
88  //
89  // This tag can be used for filtering recommendation results by passing the
90  // tag as part of the predict request filter.
91  repeated string tags = 8 [(google.api.field_behavior) = OPTIONAL];
92
93  // Optional. Variant group identifier for prediction results. UTF-8 encoded
94  // string with a length limit of 128 bytes.
95  //
96  // This field must be enabled before it can be used. [Learn
97  // more](/recommendations-ai/docs/catalog#item-group-id).
98  string item_group_id = 9 [(google.api.field_behavior) = OPTIONAL];
99
100  // Extra catalog item metadata for different recommendation types.
101  oneof recommendation_type {
102    // Optional. Metadata specific to retail products.
103    ProductCatalogItem product_metadata = 10 [(google.api.field_behavior) = OPTIONAL];
104  }
105}
106
107// ProductCatalogItem captures item metadata specific to retail products.
108message ProductCatalogItem {
109  // Exact product price.
110  message ExactPrice {
111    // Optional. Display price of the product.
112    float display_price = 1 [(google.api.field_behavior) = OPTIONAL];
113
114    // Optional. Price of the product without any discount. If zero, by default
115    // set to be the 'displayPrice'.
116    float original_price = 2 [(google.api.field_behavior) = OPTIONAL];
117  }
118
119  // Product price range when there are a range of prices for different
120  // variations of the same product.
121  message PriceRange {
122    // Required. The minimum product price.
123    float min = 1 [(google.api.field_behavior) = REQUIRED];
124
125    // Required. The maximum product price.
126    float max = 2 [(google.api.field_behavior) = REQUIRED];
127  }
128
129  // Item stock state. If this field is unspecified, the item is
130  // assumed to be in stock.
131  enum StockState {
132    option allow_alias = true;
133
134    // Default item stock status. Should never be used.
135    STOCK_STATE_UNSPECIFIED = 0;
136
137    // Item in stock.
138    IN_STOCK = 0;
139
140    // Item out of stock.
141    OUT_OF_STOCK = 1;
142
143    // Item that is in pre-order state.
144    PREORDER = 2;
145
146    // Item that is back-ordered (i.e. temporarily out of stock).
147    BACKORDER = 3;
148  }
149
150  // Product price. Only one of 'exactPrice'/'priceRange' can be provided.
151  oneof price {
152    // Optional. The exact product price.
153    ExactPrice exact_price = 1 [(google.api.field_behavior) = OPTIONAL];
154
155    // Optional. The product price range.
156    PriceRange price_range = 2 [(google.api.field_behavior) = OPTIONAL];
157  }
158
159  // Optional. A map to pass the costs associated with the product.
160  //
161  // For example:
162  // {"manufacturing": 45.5} The profit of selling this item is computed like
163  // so:
164  //
165  // * If 'exactPrice' is provided, profit = displayPrice - sum(costs)
166  // * If 'priceRange' is provided, profit = minPrice - sum(costs)
167  map<string, float> costs = 3 [(google.api.field_behavior) = OPTIONAL];
168
169  // Optional. Only required if the price is set. Currency code for price/costs. Use
170  // three-character ISO-4217 code.
171  string currency_code = 4 [(google.api.field_behavior) = OPTIONAL];
172
173  // Optional. Online stock state of the catalog item. Default is `IN_STOCK`.
174  StockState stock_state = 5 [(google.api.field_behavior) = OPTIONAL];
175
176  // Optional. The available quantity of the item.
177  int64 available_quantity = 6 [(google.api.field_behavior) = OPTIONAL];
178
179  // Optional. Canonical URL directly linking to the item detail page with a
180  // length limit of 5 KiB..
181  string canonical_product_uri = 7 [(google.api.field_behavior) = OPTIONAL];
182
183  // Optional. Product images for the catalog item.
184  repeated Image images = 8 [(google.api.field_behavior) = OPTIONAL];
185}
186
187// Catalog item thumbnail/detail image.
188message Image {
189  // Required. URL of the image with a length limit of 5 KiB.
190  string uri = 1 [(google.api.field_behavior) = REQUIRED];
191
192  // Optional. Height of the image in number of pixels.
193  int32 height = 2 [(google.api.field_behavior) = OPTIONAL];
194
195  // Optional. Width of the image in number of pixels.
196  int32 width = 3 [(google.api.field_behavior) = OPTIONAL];
197}
198