1// Copyright 2021 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.retail.v2alpha; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/cloud/retail/v2alpha/common.proto"; 24import "google/cloud/retail/v2alpha/import_config.proto"; 25import "google/cloud/retail/v2alpha/search_service.proto"; 26import "google/longrunning/operations.proto"; 27 28option csharp_namespace = "Google.Cloud.Retail.V2Alpha"; 29option go_package = "cloud.google.com/go/retail/apiv2alpha/retailpb;retailpb"; 30option java_multiple_files = true; 31option java_outer_classname = "CompletionServiceProto"; 32option java_package = "com.google.cloud.retail.v2alpha"; 33option objc_class_prefix = "RETAIL"; 34option php_namespace = "Google\\Cloud\\Retail\\V2alpha"; 35option ruby_package = "Google::Cloud::Retail::V2alpha"; 36 37// Autocomplete service for retail. 38// 39// This feature is only available for users who have Retail Search enabled. 40// Enable Retail Search on Cloud Console before using this feature. 41service CompletionService { 42 option (google.api.default_host) = "retail.googleapis.com"; 43 option (google.api.oauth_scopes) = 44 "https://www.googleapis.com/auth/cloud-platform"; 45 46 // Completes the specified prefix with keyword suggestions. 47 // 48 // This feature is only available for users who have Retail Search enabled. 49 // Enable Retail Search on Cloud Console before using this feature. 50 rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) { 51 option (google.api.http) = { 52 get: "/v2alpha/{catalog=projects/*/locations/*/catalogs/*}:completeQuery" 53 }; 54 } 55 56 // Bulk import of processed completion dataset. 57 // 58 // Request processing is asynchronous. Partial updating is not supported. 59 // 60 // The operation is successfully finished only after the imported suggestions 61 // are indexed successfully and ready for serving. The process takes hours. 62 // 63 // This feature is only available for users who have Retail Search enabled. 64 // Enable Retail Search on Cloud Console before using this feature. 65 rpc ImportCompletionData(ImportCompletionDataRequest) 66 returns (google.longrunning.Operation) { 67 option (google.api.http) = { 68 post: "/v2alpha/{parent=projects/*/locations/*/catalogs/*}/completionData:import" 69 body: "*" 70 }; 71 option (google.longrunning.operation_info) = { 72 response_type: "google.cloud.retail.v2alpha.ImportCompletionDataResponse" 73 metadata_type: "google.cloud.retail.v2alpha.ImportMetadata" 74 }; 75 } 76} 77 78// Autocomplete parameters. 79message CompleteQueryRequest { 80 // Required. Catalog for which the completion is performed. 81 // 82 // Full resource name of catalog, such as 83 // `projects/*/locations/global/catalogs/default_catalog`. 84 string catalog = 1 [ 85 (google.api.field_behavior) = REQUIRED, 86 (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" } 87 ]; 88 89 // Required. The query used to generate suggestions. 90 // 91 // The maximum number of allowed characters is 255. 92 string query = 2 [(google.api.field_behavior) = REQUIRED]; 93 94 // Required field. A unique identifier for tracking visitors. For example, 95 // this could be implemented with an HTTP cookie, which should be able to 96 // uniquely identify a visitor on a single device. This unique identifier 97 // should not change if the visitor logs in or out of the website. 98 // 99 // The field must be a UTF-8 encoded string with a length limit of 128 100 // characters. Otherwise, an INVALID_ARGUMENT error is returned. 101 string visitor_id = 7; 102 103 // Note that this field applies for `user-data` dataset only. For requests 104 // with `cloud-retail` dataset, setting this field has no effect. 105 // 106 // The language filters applied to the output suggestions. If set, it should 107 // contain the language of the query. If not set, suggestions are returned 108 // without considering language restrictions. This is the BCP-47 language 109 // code, such as "en-US" or "sr-Latn". For more information, see [Tags for 110 // Identifying Languages](https://tools.ietf.org/html/bcp47). The maximum 111 // number of language codes is 3. 112 repeated string language_codes = 3; 113 114 // The device type context for completion suggestions. We recommend that you 115 // leave this field empty. 116 // 117 // It can apply different suggestions on different device types, e.g. 118 // `DESKTOP`, `MOBILE`. If it is empty, the suggestions are across all device 119 // types. 120 // 121 // Supported formats: 122 // 123 // * `UNKNOWN_DEVICE_TYPE` 124 // 125 // * `DESKTOP` 126 // 127 // * `MOBILE` 128 // 129 // * A customized string starts with `OTHER_`, e.g. `OTHER_IPHONE`. 130 string device_type = 4; 131 132 // Determines which dataset to use for fetching completion. "user-data" will 133 // use the imported dataset through 134 // [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". 137 // 138 // Current supported values: 139 // 140 // * user-data 141 // 142 // * cloud-retail: 143 // This option requires enabling auto-learning function first. See 144 // [guidelines](https://cloud.google.com/retail/docs/completion-overview#generated-completion-dataset). 145 string dataset = 6; 146 147 // Completion max suggestions. If left unset or set to 0, then will fallback 148 // to the configured value 149 // [CompletionConfig.max_suggestions][google.cloud.retail.v2alpha.CompletionConfig.max_suggestions]. 150 // 151 // The maximum allowed max suggestions is 20. If it is set higher, it will be 152 // capped by 20. 153 int32 max_suggestions = 5; 154 155 // If true, attribute suggestions are enabled and provided in response. 156 // 157 // This field is only available for "cloud-retail" dataset. 158 bool enable_attribute_suggestions = 9; 159 160 // The entity for customers that may run multiple different entities, domains, 161 // sites or regions, for example, `Google US`, `Google Ads`, `Waymo`, 162 // `google.com`, `youtube.com`, etc. 163 // If this is set, it should be exactly matched with 164 // [UserEvent.entity][google.cloud.retail.v2alpha.UserEvent.entity] to get 165 // per-entity autocomplete results. 166 string entity = 10; 167} 168 169// Response of the autocomplete query. 170message CompleteQueryResponse { 171 // Resource that represents completion results. 172 message CompletionResult { 173 // The suggestion for the query. 174 string suggestion = 1; 175 176 // Custom attributes for the suggestion term. 177 // 178 // * For "user-data", the attributes are additional custom attributes 179 // ingested through BigQuery. 180 // 181 // * For "cloud-retail", the attributes are product attributes generated 182 // by Cloud Retail. It requires 183 // [UserEvent.product_details][google.cloud.retail.v2alpha.UserEvent.product_details] 184 // is imported properly. 185 map<string, CustomAttribute> attributes = 2; 186 187 // Facet information for the suggestion term. Gives the number of items 188 // resulting from a search with this suggestion term for each facet. 189 // 190 // This is an experimental feature for limited customers. Please reach out 191 // to the support team if you would like to receive this information. 192 repeated SearchResponse.Facet facets = 3; 193 194 // Total number of products associated with a search with this suggestion. 195 // 196 // This is an experimental feature for limited customers. Please reach out 197 // to the support team if you would like to receive this information. 198 int32 total_product_count = 4; 199 } 200 201 // Recent search of this user. 202 message RecentSearchResult { 203 // The recent search query. 204 string recent_search = 1; 205 } 206 207 // Resource that represents attribute results. 208 message AttributeResult { 209 // The list of suggestions for the attribute. 210 repeated string suggestions = 1; 211 } 212 213 // Results of the matching suggestions. The result list is ordered and the 214 // first result is top suggestion. 215 repeated CompletionResult completion_results = 1; 216 217 // A unique complete token. This should be included in the 218 // [UserEvent.completion_detail][google.cloud.retail.v2alpha.UserEvent.completion_detail] 219 // for search events resulting from this completion, which enables accurate 220 // attribution of complete model performance. 221 string attribution_token = 2; 222 223 // Matched recent searches of this user. The maximum number of recent searches 224 // is 10. This field is a restricted feature. Contact Retail Search support 225 // team if you are interested in enabling it. 226 // 227 // This feature is only available when 228 // [CompleteQueryRequest.visitor_id][google.cloud.retail.v2alpha.CompleteQueryRequest.visitor_id] 229 // field is set and [UserEvent][google.cloud.retail.v2alpha.UserEvent] is 230 // imported. The recent searches satisfy the follow rules: 231 // 232 // * They are ordered from latest to oldest. 233 // 234 // * They are matched with 235 // [CompleteQueryRequest.query][google.cloud.retail.v2alpha.CompleteQueryRequest.query] 236 // case insensitively. 237 // 238 // * They are transformed to lower case. 239 // 240 // * They are UTF-8 safe. 241 // 242 // Recent searches are deduplicated. More recent searches will be reserved 243 // when duplication happens. 244 repeated RecentSearchResult recent_search_results = 3; 245 246 // A map of matched attribute suggestions. This field is only available for 247 // "cloud-retail" dataset. 248 // 249 // Current supported keys: 250 // 251 // * `brands` 252 // 253 // * `categories` 254 map<string, AttributeResult> attribute_results = 4; 255} 256