@google-cloud/discoveryengine 1.0.0 → 1.2.0

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

@@ -0,0 +1,154 @@
+// 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.v1alpha;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/httpbody.proto";
+import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1alpha/import_config.proto";
+import "google/cloud/discoveryengine/v1alpha/purge_config.proto";
+import "google/cloud/discoveryengine/v1alpha/user_event.proto";
+import "google/longrunning/operations.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Alpha";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1alpha/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "UserEventServiceProto";
+option java_package = "com.google.cloud.discoveryengine.v1alpha";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1alpha";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1alpha";
+
+// Service for ingesting end user actions on a website to Discovery Engine API.
+service UserEventService {
+  option (google.api.default_host) = "discoveryengine.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Writes a single user event.
+  rpc WriteUserEvent(WriteUserEventRequest) returns (UserEvent) {
+    option (google.api.http) = {
+      post: "/v1alpha/{parent=projects/*/locations/*/dataStores/*}/userEvents:write"
+      body: "user_event"
+      additional_bindings {
+        post: "/v1alpha/{parent=projects/*/locations/*/collections/*/dataStores/*}/userEvents:write"
+        body: "user_event"
+      }
+    };
+  }
+
+  // Writes a single user event from the browser. This uses a GET request to
+  // 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.
+  rpc CollectUserEvent(CollectUserEventRequest) returns (google.api.HttpBody) {
+    option (google.api.http) = {
+      get: "/v1alpha/{parent=projects/*/locations/*/dataStores/*}/userEvents:collect"
+      additional_bindings {
+        get: "/v1alpha/{parent=projects/*/locations/*/collections/*/dataStores/*}/userEvents:collect"
+      }
+    };
+  }
+
+  // Deletes permanently all user events specified by the filter provided.
+  // Depending on the number of events specified by the filter, this operation
+  // could take hours or days to complete. To test a filter, use the list
+  // command first.
+  rpc PurgeUserEvents(PurgeUserEventsRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1alpha/{parent=projects/*/locations/*/dataStores/*}/userEvents:purge"
+      body: "*"
+      additional_bindings {
+        post: "/v1alpha/{parent=projects/*/locations/*/collections/*/dataStores/*}/userEvents:purge"
+        body: "*"
+      }
+    };
+    option (google.longrunning.operation_info) = {
+      response_type: "google.cloud.discoveryengine.v1alpha.PurgeUserEventsResponse"
+      metadata_type: "google.cloud.discoveryengine.v1alpha.PurgeUserEventsMetadata"
+    };
+  }
+
+  // Bulk import of User events. Request processing might be
+  // synchronous. Events that already exist are skipped.
+  // Use this method for backfilling historical user events.
+  //
+  // Operation.response is of type ImportResponse. Note that it is
+  // possible for a subset of the items to be successfully inserted.
+  // Operation.metadata is of type ImportMetadata.
+  rpc ImportUserEvents(ImportUserEventsRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1alpha/{parent=projects/*/locations/*/dataStores/*}/userEvents:import"
+      body: "*"
+      additional_bindings {
+        post: "/v1alpha/{parent=projects/*/locations/*/collections/*/dataStores/*}/userEvents:import"
+        body: "*"
+      }
+    };
+    option (google.longrunning.operation_info) = {
+      response_type: "google.cloud.discoveryengine.v1alpha.ImportUserEventsResponse"
+      metadata_type: "google.cloud.discoveryengine.v1alpha.ImportUserEventsMetadata"
+    };
+  }
+}
+
+// Request message for WriteUserEvent method.
+message WriteUserEventRequest {
+  // Required. The parent DataStore resource name, such as
+  // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/DataStore"
+    }
+  ];
+
+  // Required. User event to write.
+  optional UserEvent user_event = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request message for CollectUserEvent method.
+message CollectUserEventRequest {
+  // Required. The parent DataStore resource name, such as
+  // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/DataStore"
+    }
+  ];
+
+  // Required. URL encoded UserEvent proto with a length limit of 2,000,000
+  // characters.
+  string user_event = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // 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 third-party
+  // requests.
+  optional string uri = 3;
+
+  // The event timestamp in milliseconds. This prevents browser caching of
+  // otherwise identical get requests. The name is abbreviated to reduce the
+  // payload bytes.
+  optional int64 ets = 4;
+}

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

@@ -126,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/conversation.proto

@@ -18,6 +18,7 @@ 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";
@@ -75,6 +76,8 @@ message Conversation {
 message Reply {
   // Defines reference in reply.
   message Reference {
+    option deprecated = true;
+
     // URI link reference.
     string uri = 1;
 
@@ -88,11 +91,15 @@ message Reply {
     int32 end = 4;
   }
 
+  // DEPRECATED: use `summary` instead.
   // Text reply.
-  string reply = 1;
+  string reply = 1 [deprecated = true];
 
   // References in the reply.
-  repeated Reference references = 2;
+  repeated Reference references = 2 [deprecated = true];
+
+  // Summary based on search results.
+  SearchResponse.Summary summary = 3;
 }
 
 // Defines context of the conversation

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

@@ -162,6 +162,28 @@ message ConverseConversationRequest {
 
   // Whether to turn on safe search.
   bool safe_search = 6;
+
+  // The user labels applied to a resource must meet the following requirements:
+  //
+  // * Each resource can have multiple labels, up to a maximum of 64.
+  // * Each label must be a key-value pair.
+  // * Keys have a minimum length of 1 character and a maximum length of 63
+  //   characters and cannot be empty. Values can be empty and have a maximum
+  //   length of 63 characters.
+  // * Keys and values can contain only lowercase letters, numeric characters,
+  //   underscores, and dashes. All characters must use UTF-8 encoding, and
+  //   international characters are allowed.
+  // * The key portion of a label must be unique. However, you can use the same
+  //   key with multiple resources.
+  // * Keys must start with a lowercase letter or international character.
+  //
+  // See [Google Cloud
+  // Document](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
+  // for more details.
+  map<string, string> user_labels = 7;
+
+  // A specification for configuring the summary returned in the response.
+  SearchRequest.ContentSearchSpec.SummarySpec summary_spec = 8;
 }
 
 // Response message for
@@ -174,6 +196,9 @@ message ConverseConversationResponse {
   // Updated conversation including the answer.
   Conversation conversation = 2;
 
+  // Suggested related questions.
+  repeated string related_questions = 6;
+
   // Search Results.
   repeated SearchResponse.SearchResult search_results = 3;
 }

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

@@ -262,6 +262,11 @@ message SearchRequest {
     // The condition under which query expansion should occur. Default to
     // [Condition.DISABLED][google.cloud.discoveryengine.v1beta.SearchRequest.QueryExpansionSpec.Condition.DISABLED].
     Condition condition = 1;
+
+    // Whether to pin unexpanded results. If this field is set to true,
+    // unexpanded products are always at the top of the search results, followed
+    // by the expanded results.
+    bool pin_unexpanded_results = 2;
   }
 
   // The specification for query spell correction.
@@ -362,6 +367,10 @@ message SearchRequest {
       // generating summaries for non-summary seeking queries and return
       // fallback messages instead.
       bool ignore_non_summary_seeking_query = 4;
+
+      // Language code for Summary. Use language tags defined by
+      // [BCP47][https://www.rfc-editor.org/rfc/bcp/bcp47.txt].
+      string language_code = 6;
     }
 
     // A specification for configuring the extractive content in a search
@@ -399,10 +408,21 @@ message SearchRequest {
       // If the number of matching segments is less than
       // `max_extractive_segment_count`, return all of the segments. Otherwise,
       // return the `max_extractive_segment_count`.
-      //
-      // Currently one segment is returned for each
-      // [SearchResult][google.cloud.discoveryengine.v1beta.SearchResponse.SearchResult].
       int32 max_extractive_segment_count = 2;
+
+      // Specifies whether to return the confidence score from the extractive
+      // segments in each search result. The default value is `false`.
+      bool return_extractive_segment_score = 3;
+
+      // Specifies whether to also include the adjacent from each selected
+      // segments.
+      // Return at most `num_previous_segments` segments before each selected
+      // segments.
+      int32 num_previous_segments = 4;
+
+      // Return at most `num_next_segments` segments after each selected
+      // segments.
+      int32 num_next_segments = 5;
     }
 
     // If `snippetSpec` is not specified, snippets are not included in the
@@ -418,6 +438,22 @@ message SearchRequest {
     ExtractiveContentSpec extractive_content_spec = 3;
   }
 
+  // The specification that uses customized query embedding vector to do
+  // semantic document retrieval.
+  message EmbeddingSpec {
+    // Embedding vector.
+    message EmbeddingVector {
+      // Embedding field path in schema.
+      string field_path = 1;
+
+      // Query embedding vector.
+      repeated float vector = 2;
+    }
+
+    // The embedding vector used for retrieval. Limit to 1.
+    repeated EmbeddingVector embedding_vectors = 1;
+  }
+
   // Required. The resource name of the Search serving config, such as
   // `projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config`.
   // This field is used to identify the serving configuration name, set
@@ -539,6 +575,37 @@ message SearchRequest {
   // A specification for configuring the behavior of content search.
   ContentSearchSpec content_search_spec = 24;
 
+  // Uses the provided embedding to do additional semantic document retrieval.
+  // The retrieval is based on the dot product of
+  // [SearchRequest.embedding_spec.embedding_vectors.vector][] and the document
+  // embedding that is provided in
+  // [SearchRequest.embedding_spec.embedding_vectors.field_path][].
+  //
+  // If [SearchRequest.embedding_spec.embedding_vectors.field_path][] is not
+  // provided, it will use [ServingConfig.embedding_config.field_paths][].
+  EmbeddingSpec embedding_spec = 23;
+
+  // The ranking expression controls the customized ranking on retrieval
+  // documents. This overrides [ServingConfig.ranking_expression][].
+  // The ranking expression is a single function or multiple functions that are
+  // joint by "+".
+  //   * ranking_expression = function, { " + ", function };
+  // Supported functions:
+  //   * double * relevance_score
+  //   * double * dotProduct(embedding_field_path)
+  // Function variables:
+  //   `relevance_score`: pre-defined keywords, used for measure relevance
+  //   between query and document.
+  //   `embedding_field_path`: the document embedding field
+  //   used with query embedding vector.
+  //   `dotProduct`: embedding function between embedding_field_path and query
+  //   embedding vector.
+  //
+  //  Example ranking expression:
+  //    If document has an embedding field doc_embedding, the ranking expression
+  //    could be `0.5 * relevance_score + 0.3 * dotProduct(doc_embedding)`.
+  string ranking_expression = 26;
+
   // Whether to turn on safe search. This is only supported for
   // website search.
   bool safe_search = 20;
@@ -576,6 +643,9 @@ message SearchResponse {
     // The document data snippet in the search response. Only fields that are
     // marked as retrievable are populated.
     Document document = 2;
+
+    // Google provided available scores.
+    map<string, DoubleList> model_scores = 4;
   }
 
   // A facet result.
@@ -629,6 +699,17 @@ message SearchResponse {
 
   // Summary of the top N search result specified by the summary spec.
   message Summary {
+    // Safety Attribute categories and their associated confidence scores.
+    message SafetyAttributes {
+      // The display names of Safety Attribute categories associated with the
+      // generated content. Order matches the Scores.
+      repeated string categories = 1;
+
+      // The confidence scores of the each category, higher
+      // value means higher confidence. Order matches the Categories.
+      repeated float scores = 2;
+    }
+
     // An Enum for summary-skipped reasons.
     enum SummarySkippedReason {
       // Default value. The summary skipped reason is not specified.
@@ -654,6 +735,17 @@ message SearchResponse {
       // For example, the data store contains facts about company A but the
       // user query is asking questions about company B.
       OUT_OF_DOMAIN_QUERY_IGNORED = 3;
+
+      // The potential policy violation case.
+      //
+      // Google skips the summary if there is a potential policy violation
+      // detected. This includes content that may be violent or toxic.
+      POTENTIAL_POLICY_VIOLATION = 4;
+
+      // The LLM addon not enabled case.
+      //
+      // Google skips the summary if the LLM addon is not enabled.
+      LLM_ADDON_NOT_ENABLED = 5;
     }
 
     // The summary content.
@@ -662,6 +754,23 @@ message SearchResponse {
     // Additional summary-skipped reasons. This provides the reason for ignored
     // cases. If nothing is skipped, this field is not set.
     repeated SummarySkippedReason summary_skipped_reasons = 2;
+
+    // A collection of Safety Attribute categories and their associated
+    // confidence scores.
+    SafetyAttributes safety_attributes = 3;
+  }
+
+  // Information describing query expansion including whether expansion has
+  // occurred.
+  message QueryExpansionInfo {
+    // Bool describing whether query expansion has occurred.
+    bool expanded_query = 1;
+
+    // Number of pinned results. This field will only be set when expansion
+    // happens and
+    // [SearchRequest.QueryExpansionSpec.pin_unexpanded_results][google.cloud.discoveryengine.v1beta.SearchRequest.QueryExpansionSpec.pin_unexpanded_results]
+    // is set to true.
+    int64 pinned_result_count = 2;
   }
 
   // A list of matched documents. The order represents the ranking.
@@ -714,4 +823,7 @@ message SearchResponse {
 
   // Controls applied as part of the Control service.
   repeated string applied_controls = 10;
+
+  // Query expansion information for the returned results.
+  QueryExpansionInfo query_expansion_info = 14;
 }

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

@@ -410,6 +410,10 @@ message DocumentInfo {
     string name = 2 [(google.api.resource_reference) = {
       type: "discoveryengine.googleapis.com/Document"
     }];
+
+    // The [Document][google.cloud.discoveryengine.v1beta.Document] URI - only
+    // allowed for website data stores.
+    string uri = 6;
   }
 
   // Quantity of the Document associated with the user event. Defaults to 1.