@google-cloud/discoveryengine 0.8.0 → 1.1.0

package/build/protos/google/cloud/discoveryengine/v1/user_event.proto

@@ -66,7 +66,7 @@ message UserEvent {
   // quality.
   //
   // The field must be a UTF-8 encoded string with a length limit of 128
-  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   //
   // The field should not contain PII or user-data. We recommend to use Google
   // Analytics [Client
@@ -119,20 +119,17 @@ message UserEvent {
   //
   // The value must be one of:
   //
-  // * [PredictResponse.attribution_token][] for events that are the result of
+  // * [RecommendResponse.attribution_token][] for events that are the result of
   // [RecommendationService.Recommend][].
   // * [SearchResponse.attribution_token][google.cloud.discoveryengine.v1.SearchResponse.attribution_token] for events that are the result of
   // [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search].
-  // * [CompleteQueryResponse.attribution_token][] for events that are the
-  // result of
-  // [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1.CompletionService.CompleteQuery].
   //
   // This token enables us to accurately attribute page view or conversion
   // completion back to the event and the particular predict response containing
   // this clicked/purchased product. If user clicks on product K in the
-  // recommendation results, pass [PredictResponse.attribution_token][] as a URL
-  // parameter to product K's page. When recording events on product K's page,
-  // log the [PredictResponse.attribution_token][] to this field.
+  // recommendation results, pass [RecommendResponse.attribution_token][] as a
+  // URL parameter to product K's page. When recording events on product K's
+  // page, log the [RecommendResponse.attribution_token][] to this field.
   string attribution_token = 8;
 
   // The filter syntax consists of an expression language for constructing a
@@ -140,8 +137,9 @@ message UserEvent {
   //
   // One example is for `search` events, the associated
   // [SearchRequest][google.cloud.discoveryengine.v1.SearchRequest] may contain
-  // a filter expression in [SearchRequest.filter][] conforming to
-  // https://google.aip.dev/160#filtering.
+  // a filter expression in
+  // [SearchRequest.filter][google.cloud.discoveryengine.v1.SearchRequest.filter]
+  // conforming to https://google.aip.dev/160#filtering.
   //
   // Similarly, for `view-item-list` events that are generated from a
   // [RecommendationService.RecommendRequest][], this field may be populated
@@ -149,10 +147,11 @@ message UserEvent {
   // to https://google.aip.dev/160#filtering.
   //
   // The value must be a UTF-8 encoded string with a length limit of 1,000
-  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string filter = 9;
 
-  // List of Documents associated with this user event.
+  // List of [Document][google.cloud.discoveryengine.v1.Document]s associated
+  // with this user event.
   //
   // This field is optional except for the following event types:
   //
@@ -174,12 +173,14 @@ message UserEvent {
   // Panel metadata associated with this user event.
   PanelInfo panel = 11;
 
-  // Search API details related to the event.
+  // [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search]
+  // details related to the event.
   //
   // This field should be set for `search` event.
   SearchInfo search_info = 12;
 
-  // CompleteQuery API details related to the event.
+  // [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1.CompletionService.CompleteQuery]
+  // details related to the event.
   //
   // This field should be set for `search` event when autocomplete function is
   // enabled and the user clicks a suggestion for search.
@@ -219,7 +220,7 @@ message UserEvent {
   // * For number attributes, at most 400 values are allowed.
   //
   // For product recommendations, an example of extra user information is
-  // ` traffic_channel`, which is how a user arrives at the site. Users can
+  // `traffic_channel`, which is how a user arrives at the site. Users can
   // arrive
   // at the site by coming to the site directly, coming through Google
   // search, or in other ways.
@@ -235,7 +236,7 @@ message PageInfo {
   //
   // This should be kept the same for all user events triggered from the same
   // pageview. For example, an item detail page view could trigger multiple
-  // events as the user is browsing the page. The `pageViewId` property should
+  // events as the user is browsing the page. The `pageview_id` property should
   // be kept the same for all these events so that they can be grouped together
   // properly.
   //
@@ -251,10 +252,10 @@ message PageInfo {
   //
   // Category pages include special pages such as sales or promotions. For
   // instance, a special sale page may have the category hierarchy:
-  // "pageCategory" : "Sales > 2017 Black Friday Deals".
+  // `"pageCategory" : "Sales > 2017 Black Friday Deals"`.
   //
   // Required for `view-category-page` events. Other event types should not set
-  // this field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // this field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string page_category = 2;
 
   // Complete URL (window.location.href) of the user's current page.
@@ -281,24 +282,26 @@ message SearchInfo {
   // for definition.
   //
   // The value must be a UTF-8 encoded string with a length limit of 5,000
-  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   //
   // At least one of
   // [search_query][google.cloud.discoveryengine.v1.SearchInfo.search_query] or
   // [PageInfo.page_category][google.cloud.discoveryengine.v1.PageInfo.page_category]
   // is required for `search` events. Other event types should not set this
-  // field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string search_query = 1;
 
   // The order in which products are returned, if applicable.
   //
-  // See [SearchRequest.order_by][] for definition and syntax.
+  // See
+  // [SearchRequest.order_by][google.cloud.discoveryengine.v1.SearchRequest.order_by]
+  // for definition and syntax.
   //
   // The value must be a UTF-8 encoded string with a length limit of 1,000
-  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
+  // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   //
   // This can only be set for `search` events. Other event types should not set
-  // this field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // this field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string order_by = 2;
 
   // An integer that specifies the current offset for pagination (the 0-indexed
@@ -308,20 +311,22 @@ message SearchInfo {
   // [SearchRequest.offset][google.cloud.discoveryengine.v1.SearchRequest.offset]
   // for definition.
   //
-  // If this field is negative, an INVALID_ARGUMENT is returned.
+  // If this field is negative, an `INVALID_ARGUMENT` is returned.
   //
   // This can only be set for `search` events. Other event types should not set
-  // this field. Otherwise, an INVALID_ARGUMENT error is returned.
+  // this field. Otherwise, an `INVALID_ARGUMENT` error is returned.
   optional int32 offset = 3;
 }
 
 // Detailed completion information including completion attribution token and
 // clicked completion info.
 message CompletionInfo {
-  // End user selected [CompleteQueryResponse.CompletionResult.suggestion][].
+  // End user selected
+  // [CompleteQueryResponse.QuerySuggestion.suggestion][google.cloud.discoveryengine.v1.CompleteQueryResponse.QuerySuggestion.suggestion].
   string selected_suggestion = 1;
 
-  // End user selected [CompleteQueryResponse.CompletionResult.suggestion][]
+  // End user selected
+  // [CompleteQueryResponse.QuerySuggestion.suggestion][google.cloud.discoveryengine.v1.CompleteQueryResponse.QuerySuggestion.suggestion]
   // position, starting from 0.
   int32 selected_position = 2;
 }
@@ -389,17 +394,19 @@ message DocumentInfo {
   // `{location}`, `{collection_id}`, `{data_store_id}`, and
   // `{branch_id}` are used when annotating with the stored Document.
   oneof document_descriptor {
-    // Required. The Document resource ID.
-    string id = 1 [(google.api.field_behavior) = REQUIRED];
+    // The [Document][google.cloud.discoveryengine.v1.Document] resource ID.
+    string id = 1;
 
-    // Required. The Document resource full name, of the form:
+    // The [Document][google.cloud.discoveryengine.v1.Document] resource full
+    // name, of the form:
     // `projects/{project_id}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}/branches/{branch_id}/documents/{document_id}`
-    string name = 2 [
-      (google.api.field_behavior) = REQUIRED,
-      (google.api.resource_reference) = {
-        type: "discoveryengine.googleapis.com/Document"
-      }
-    ];
+    string name = 2 [(google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Document"
+    }];
+
+    // The [Document][google.cloud.discoveryengine.v1.Document] URI - only
+    // allowed for website data stores.
+    string uri = 6;
   }
 
   // Quantity of the Document associated with the user event. Defaults to 1.
@@ -443,11 +450,13 @@ message PanelInfo {
 message MediaInfo {
   // The media progress time in seconds, if applicable.
   // For example, if the end user has finished 90 seconds of a playback video,
-  // then [MediaInfo.media_progress_duration.seconds][Duration.seconds] should
-  // be set to 90.
+  // then
+  // [MediaInfo.media_progress_duration.seconds][google.protobuf.Duration.seconds]
+  // should be set to 90.
   google.protobuf.Duration media_progress_duration = 1;
 
-  // Media progress should be computed using only the media_progress_duration
+  // Media progress should be computed using only the
+  // [media_progress_duration][google.cloud.discoveryengine.v1.MediaInfo.media_progress_duration]
   // relative to the media total length.
   //
   // This value must be between `[0, 1.0]` inclusive.

package/build/protos/google/cloud/discoveryengine/v1/user_event_service.proto

@@ -53,7 +53,7 @@ service UserEventService {
   }
 
   // Writes a single user event from the browser. This uses a GET request to
-  // due to browser restriction of POST-ing to a 3rd party domain.
+  // due to browser restriction of POST-ing to a third-party domain.
   //
   // This method is used only by the Discovery Engine API JavaScript pixel and
   // Google Tag Manager. Users should not call this method directly.
@@ -122,7 +122,7 @@ message CollectUserEventRequest {
 
   // The URL including cgi-parameters but excluding the hash fragment with a
   // length limit of 5,000 characters. This is often more useful than the
-  // referer URL, because many browsers only send the domain for 3rd party
+  // referer URL, because many browsers only send the domain for third-party
   // requests.
   optional string uri = 3;
 

package/build/protos/google/cloud/discoveryengine/v1beta/common.proto

@@ -113,8 +113,7 @@ message UserInfo {
   // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string user_id = 1;
 
-  // User agent as included in the HTTP header. Required for getting
-  // [SearchResponse.sponsored_results][].
+  // User agent as included in the HTTP header.
   //
   // The field must be a UTF-8 encoded string with a length limit of 1,000
   // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
@@ -127,3 +126,9 @@ message UserInfo {
   // is set.
   string user_agent = 2;
 }
+
+// Double list.
+message DoubleList {
+  // Double values.
+  repeated double values = 1;
+}

package/build/protos/google/cloud/discoveryengine/v1beta/completion_service.proto

@@ -81,8 +81,7 @@ message CompleteQueryRequest {
   //
   // * `document` is the default model for regular dataStores.
   // * `search-history` is the default model for
-  // [IndustryVertical.SITE_SEARCH][google.cloud.discoveryengine.v1beta.IndustryVertical.SITE_SEARCH]
-  // dataStores.
+  // [IndustryVertical.SITE_SEARCH][] dataStores.
   string query_model = 3;
 
   // A unique identifier for tracking visitors. For example, this could be
@@ -100,6 +99,12 @@ message CompleteQueryRequest {
   // The field must be a UTF-8 encoded string with a length limit of 128
   // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
   string user_pseudo_id = 4;
+
+  // Indicates if tail suggestions should be returned if there are no
+  // suggestions that match the full query. Even if set to true, if there are
+  // suggestions that match the full query, those are returned and no
+  // tail suggestions are returned.
+  bool include_tail_suggestions = 5;
 }
 
 // Response message for
@@ -115,4 +120,10 @@ message CompleteQueryResponse {
   // Results of the matched query suggestions. The result list is ordered and
   // the first result is a top suggestion.
   repeated QuerySuggestion query_suggestions = 1;
+
+  // True if the returned suggestions are all tail suggestions.
+  //
+  // For tail matching to be triggered, include_tail_suggestions in the request
+  // must be true and there must be no suggestions that match the full query.
+  bool tail_match_triggered = 2;
 }

package/build/protos/google/cloud/discoveryengine/v1beta/conversation.proto

@@ -0,0 +1,138 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.cloud.discoveryengine.v1beta;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1beta/search_service.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "ConversationProto";
+option java_package = "com.google.cloud.discoveryengine.v1beta";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta";
+
+// External conversation proto definition.
+message Conversation {
+  option (google.api.resource) = {
+    type: "discoveryengine.googleapis.com/Conversation"
+    pattern: "projects/{project}/locations/{location}/dataStores/{data_store}/conversations/{conversation}"
+    pattern: "projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/conversations/{conversation}"
+  };
+
+  // Enumeration of the state of the conversation.
+  enum State {
+    // Unknown.
+    STATE_UNSPECIFIED = 0;
+
+    // Conversation is currently open.
+    IN_PROGRESS = 1;
+
+    // Conversation has been completed.
+    COMPLETED = 2;
+  }
+
+  // Immutable. Fully qualified name
+  // `project/*/locations/global/collections/{collection}/dataStore/*/conversations/*`
+  string name = 1 [(google.api.field_behavior) = IMMUTABLE];
+
+  // The state of the Conversation.
+  State state = 2;
+
+  // A unique identifier for tracking users.
+  string user_pseudo_id = 3;
+
+  // Conversation messages.
+  repeated ConversationMessage messages = 4;
+
+  // Output only. The time the conversation started.
+  google.protobuf.Timestamp start_time = 5
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The time the conversation finished.
+  google.protobuf.Timestamp end_time = 6
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// Defines a reply message to user.
+message Reply {
+  // Defines reference in reply.
+  message Reference {
+    option deprecated = true;
+
+    // URI link reference.
+    string uri = 1;
+
+    // Anchor text.
+    string anchor_text = 2;
+
+    // Anchor text start index.
+    int32 start = 3;
+
+    // Anchor text end index.
+    int32 end = 4;
+  }
+
+  // DEPRECATED: use `summary` instead.
+  // Text reply.
+  string reply = 1 [deprecated = true];
+
+  // References in the reply.
+  repeated Reference references = 2 [deprecated = true];
+
+  // Summary based on search results.
+  SearchResponse.Summary summary = 3;
+}
+
+// Defines context of the conversation
+message ConversationContext {
+  // The current list of documents the user is seeing.
+  // It contains the document resource references.
+  repeated string context_documents = 1;
+
+  // The current active document the user opened.
+  // It contains the document resource reference.
+  string active_document = 2;
+}
+
+// Defines text input.
+message TextInput {
+  // Text input.
+  string input = 1;
+
+  // Conversation context of the input.
+  ConversationContext context = 2;
+}
+
+// Defines a conversation message.
+message ConversationMessage {
+  oneof message {
+    // User text input.
+    TextInput user_input = 1;
+
+    // Search reply.
+    Reply reply = 2;
+  }
+
+  // Output only. Message creation timestamp.
+  google.protobuf.Timestamp create_time = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}