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