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