@google-cloud/discoveryengine 1.7.0 → 1.9.0

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

@@ -0,0 +1,214 @@
+// Copyright 2024 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.v1;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1/common.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "ControlProto";
+option java_package = "com.google.cloud.discoveryengine.v1";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1";
+
+// Defines circumstances to be checked before allowing a behavior
+message Condition {
+  // Matcher for search request query
+  message QueryTerm {
+    // The specific query value to match against
+    //
+    // Must be lowercase, must be UTF-8.
+    // Can have at most 3 space separated terms if full_match is true.
+    // Cannot be an empty string.
+    // Maximum length of 5000 characters.
+    string value = 1;
+
+    // Whether the search query needs to exactly match the query term.
+    bool full_match = 2;
+  }
+
+  // Used for time-dependent conditions.
+  message TimeRange {
+    // Start of time range.
+    //
+    // Range is inclusive.
+    google.protobuf.Timestamp start_time = 1;
+
+    // End of time range.
+    //
+    // Range is inclusive.
+    // Must be in the future.
+    google.protobuf.Timestamp end_time = 2;
+  }
+
+  // Search only
+  // A list of terms to match the query on.
+  //
+  // Maximum of 10 query terms.
+  repeated QueryTerm query_terms = 2;
+
+  // Range of time(s) specifying when condition is active.
+  //
+  // Maximum of 10 time ranges.
+  repeated TimeRange active_time_range = 3;
+}
+
+// Defines a conditioned behavior to employ during serving.
+// Must be attached to a [ServingConfig][] to be considered at serving time.
+// Permitted actions dependent on `SolutionType`.
+message Control {
+  option (google.api.resource) = {
+    type: "discoveryengine.googleapis.com/Control"
+    pattern: "projects/{project}/locations/{location}/dataStores/{data_store}/controls/{control}"
+    pattern: "projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/controls/{control}"
+    pattern: "projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/controls/{control}"
+  };
+
+  // Adjusts order of products in returned list.
+  message BoostAction {
+    // Required. Strength of the boost, which should be in [-1, 1]. Negative
+    // boost means demotion. Default is 0.0 (No-op).
+    float boost = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. Specifies which products to apply the boost to.
+    //
+    // If no filter is provided all products will be boosted (No-op).
+    // Syntax documentation:
+    // https://cloud.google.com/retail/docs/filter-and-order
+    // Maximum length is 5000 characters.
+    // Otherwise an INVALID ARGUMENT error is thrown.
+    string filter = 2 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. Specifies which data store's documents can be boosted by this
+    // control. Full data store name e.g.
+    // projects/123/locations/global/collections/default_collection/dataStores/default_data_store
+    string data_store = 3 [
+      (google.api.field_behavior) = REQUIRED,
+      (google.api.resource_reference) = {
+        type: "discoveryengine.googleapis.com/DataStore"
+      }
+    ];
+  }
+
+  // Specified which products may be included in results.
+  // Uses same filter as boost.
+  message FilterAction {
+    // Required. A filter to apply on the matching condition results.
+    //
+    // Required
+    // Syntax documentation:
+    // https://cloud.google.com/retail/docs/filter-and-order
+    // Maximum length is 5000 characters. Otherwise an INVALID
+    // ARGUMENT error is thrown.
+    string filter = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. Specifies which data store's documents can be filtered by this
+    // control. Full data store name e.g.
+    // projects/123/locations/global/collections/default_collection/dataStores/default_data_store
+    string data_store = 2 [
+      (google.api.field_behavior) = REQUIRED,
+      (google.api.resource_reference) = {
+        type: "discoveryengine.googleapis.com/DataStore"
+      }
+    ];
+  }
+
+  // Redirects a shopper to the provided URI.
+  message RedirectAction {
+    // Required. The URI to which the shopper will be redirected.
+    //
+    // Required.
+    // URI must have length equal or less than 2000 characters.
+    // Otherwise an INVALID ARGUMENT error is thrown.
+    string redirect_uri = 1 [(google.api.field_behavior) = REQUIRED];
+  }
+
+  // Creates a set of terms that will act as synonyms of one another.
+  //
+  // Example: "happy" will also be considered as "glad", "glad" will also be
+  // considered as "happy".
+  message SynonymsAction {
+    // Defines a set of synonyms.
+    // Can specify up to 100 synonyms.
+    // Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is
+    // thrown.
+    repeated string synonyms = 1;
+  }
+
+  // Actions are restricted by Vertical and Solution
+  //
+  // Required.
+  oneof action {
+    // Defines a boost-type control
+    BoostAction boost_action = 6;
+
+    // Defines a filter-type control
+    // Currently not supported by Recommendation
+    FilterAction filter_action = 7;
+
+    // Defines a redirect-type control.
+    RedirectAction redirect_action = 9;
+
+    // Treats a group of terms as synonyms of one another.
+    SynonymsAction synonyms_action = 10;
+  }
+
+  // Immutable. Fully qualified name
+  // `projects/*/locations/global/dataStore/*/controls/*`
+  string name = 1 [(google.api.field_behavior) = IMMUTABLE];
+
+  // Required. Human readable name. The identifier used in UI views.
+  //
+  // Must be UTF-8 encoded string. Length limit is 128 characters.
+  // Otherwise an INVALID ARGUMENT error is thrown.
+  string display_name = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Output only. List of all [ServingConfig][] ids this control is attached to.
+  // May take up to 10 minutes to update after changes.
+  repeated string associated_serving_config_ids = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Required. Immutable. What solution the control belongs to.
+  //
+  // Must be compatible with vertical of resource.
+  // Otherwise an INVALID ARGUMENT error is thrown.
+  SolutionType solution_type = 4 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.field_behavior) = IMMUTABLE
+  ];
+
+  // Specifies the use case for the control.
+  // Affects what condition fields can be set.
+  // Only applies to
+  // [SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1.SolutionType.SOLUTION_TYPE_SEARCH].
+  // Currently only allow one use case per control.
+  // Must be set when solution_type is
+  // [SolutionType.SOLUTION_TYPE_SEARCH][google.cloud.discoveryengine.v1.SolutionType.SOLUTION_TYPE_SEARCH].
+  repeated SearchUseCase use_cases = 8;
+
+  // Determines when the associated action will trigger.
+  //
+  // Omit to always apply the action.
+  // Currently only a single condition may be specified.
+  // Otherwise an INVALID ARGUMENT error is thrown.
+  repeated Condition conditions = 5;
+}

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

@@ -0,0 +1,236 @@
+// Copyright 2024 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.v1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1/control.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "ControlServiceProto";
+option java_package = "com.google.cloud.discoveryengine.v1";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1";
+
+// Service for performing CRUD operations on Controls.
+// Controls allow for custom logic to be implemented in the serving path.
+// Controls need to be attached to a Serving Config to be considered during a
+// request.
+service ControlService {
+  option (google.api.default_host) = "discoveryengine.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Creates a Control.
+  //
+  // By default 1000 controls are allowed for a data store.
+  // A request can be submitted to adjust this limit.
+  // If the [Control][google.cloud.discoveryengine.v1.Control] to create already
+  // exists, an ALREADY_EXISTS error is returned.
+  rpc CreateControl(CreateControlRequest) returns (Control) {
+    option (google.api.http) = {
+      post: "/v1/{parent=projects/*/locations/*/dataStores/*}/controls"
+      body: "control"
+      additional_bindings {
+        post: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*}/controls"
+        body: "control"
+      }
+      additional_bindings {
+        post: "/v1/{parent=projects/*/locations/*/collections/*/engines/*}/controls"
+        body: "control"
+      }
+    };
+    option (google.api.method_signature) = "parent,control,control_id";
+  }
+
+  // Deletes a Control.
+  //
+  // If the [Control][google.cloud.discoveryengine.v1.Control] to delete does
+  // not exist, a NOT_FOUND error is returned.
+  rpc DeleteControl(DeleteControlRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {
+      delete: "/v1/{name=projects/*/locations/*/dataStores/*/controls/*}"
+      additional_bindings {
+        delete: "/v1/{name=projects/*/locations/*/collections/*/dataStores/*/controls/*}"
+      }
+      additional_bindings {
+        delete: "/v1/{name=projects/*/locations/*/collections/*/engines/*/controls/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Updates a Control.
+  //
+  // [Control][google.cloud.discoveryengine.v1.Control] action type cannot be
+  // changed. If the [Control][google.cloud.discoveryengine.v1.Control] to
+  // update does not exist, a NOT_FOUND error is returned.
+  rpc UpdateControl(UpdateControlRequest) returns (Control) {
+    option (google.api.http) = {
+      patch: "/v1/{control.name=projects/*/locations/*/dataStores/*/controls/*}"
+      body: "control"
+      additional_bindings {
+        patch: "/v1/{control.name=projects/*/locations/*/collections/*/dataStores/*/controls/*}"
+        body: "control"
+      }
+      additional_bindings {
+        patch: "/v1/{control.name=projects/*/locations/*/collections/*/engines/*/controls/*}"
+        body: "control"
+      }
+    };
+    option (google.api.method_signature) = "control,update_mask";
+  }
+
+  // Gets a Control.
+  rpc GetControl(GetControlRequest) returns (Control) {
+    option (google.api.http) = {
+      get: "/v1/{name=projects/*/locations/*/dataStores/*/controls/*}"
+      additional_bindings {
+        get: "/v1/{name=projects/*/locations/*/collections/*/dataStores/*/controls/*}"
+      }
+      additional_bindings {
+        get: "/v1/{name=projects/*/locations/*/collections/*/engines/*/controls/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists all Controls by their parent
+  // [DataStore][google.cloud.discoveryengine.v1.DataStore].
+  rpc ListControls(ListControlsRequest) returns (ListControlsResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=projects/*/locations/*/dataStores/*}/controls"
+      additional_bindings {
+        get: "/v1/{parent=projects/*/locations/*/collections/*/dataStores/*}/controls"
+      }
+      additional_bindings {
+        get: "/v1/{parent=projects/*/locations/*/collections/*/engines/*}/controls"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}
+
+// Request for CreateControl method.
+message CreateControlRequest {
+  // Required. Full resource name of parent data store. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection_id}/dataStores/{data_store_id}`
+  // or
+  // `projects/{project_number}/locations/{location_id}/collections/{collection_id}/engines/{engine_id}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "discoveryengine.googleapis.com/Control"
+    }
+  ];
+
+  // Required. The Control to create.
+  Control control = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The ID to use for the Control, which will become the final
+  // component of the Control's resource name.
+  //
+  // This value must be within 1-63 characters.
+  // Valid characters are /[a-z][0-9]-_/.
+  string control_id = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for UpdateControl method.
+message UpdateControlRequest {
+  // Required. The Control to update.
+  Control control = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Indicates which fields in the provided
+  // [Control][google.cloud.discoveryengine.v1.Control] to update. The following
+  // are NOT supported:
+  //
+  // * [Control.name][google.cloud.discoveryengine.v1.Control.name]
+  // * [Control.solution_type][google.cloud.discoveryengine.v1.Control.solution_type]
+  //
+  // If not set or empty, all supported fields are updated.
+  google.protobuf.FieldMask update_mask = 2
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Request for DeleteControl method.
+message DeleteControlRequest {
+  // Required. The resource name of the Control to delete. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection_id}/dataStores/{data_store_id}/controls/{control_id}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Control"
+    }
+  ];
+}
+
+// Request for GetControl method.
+message GetControlRequest {
+  // Required. The resource name of the Control to get. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection_id}/dataStores/{data_store_id}/controls/{control_id}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Control"
+    }
+  ];
+}
+
+// Request for ListControls method.
+message ListControlsRequest {
+  // Required. The data store resource name. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection_id}/dataStores/{data_store_id}`
+  // or
+  // `projects/{project_number}/locations/{location_id}/collections/{collection_id}/engines/{engine_id}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "discoveryengine.googleapis.com/Control"
+    }
+  ];
+
+  // Optional. Maximum number of results to return. If unspecified, defaults
+  // to 50. Max allowed value is 1000.
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A page token, received from a previous `ListControls` call.
+  // Provide this to retrieve the subsequent page.
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A filter to apply on the list results. Supported features:
+  //
+  // * List all the products under the parent branch if
+  // [filter][google.cloud.discoveryengine.v1.ListControlsRequest.filter] is
+  // unset. Currently this field is unsupported.
+  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response for ListControls method.
+message ListControlsResponse {
+  // All the Controls for a given data store.
+  repeated Control controls = 1;
+
+  // Pagination token, if not returned indicates the last page.
+  string next_page_token = 2;
+}

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

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -52,9 +52,9 @@ message Conversation {
   }
 
   // Immutable. Fully qualified name
-  // `project/*/locations/global/collections/{collection}/dataStore/*/conversations/*`
+  // `projects/{project}/locations/global/collections/{collection}/dataStore/*/conversations/*`
   // or
-  // `project/*/locations/global/collections/{collection}/engines/*/conversations/*`.
+  // `projects/{project}/locations/global/collections/{collection}/engines/*/conversations/*`.
   string name = 1 [(google.api.field_behavior) = IMMUTABLE];
 
   // The state of the Conversation.