feat: support async write mode for WriteUserEvent API (#3779)

* feat: support async write mode for WriteUserEvent API feat: support collect and import GA4 event format with prebuilt whistle rule feat: support exact searchable and retrievable in catalog attribute config feat: deprecate retrievable_fields in product attribute feat: support diversity type in serving config feat: allow set feed id in merchant center link feat: support data output to GCS docs: keep the API doc up-to-date with recent changes PiperOrigin-RevId: 495893148 Source-Link: googleapis/googleapis@02dcec3 Source-Link: googleapis/googleapis-gen@996aa46 Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLXJldGFpbC8uT3dsQm90LnlhbWwiLCJoIjoiOTk2YWE0NmZlNDgyZWY4MDdhMzNiNTZkMTViMjhhZDU1ZmJhYzdiOSJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: sofisl <[email protected]>
googleapis · Dec 20, 2022 · 1f1795d · 1f1795d
1 parent 8057cc8
commit 1f1795d
Show file tree

Hide file tree

Showing 24 changed files with 1,205 additions and 72 deletions.
diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/catalog.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/catalog.proto
@@ -104,8 +104,7 @@ message CatalogAttribute {
 
   // The status of the indexable option of a catalog attribute.
   enum IndexableOption {
-    // Value used when unset. Defaults to
-    // [INDEXABLE_ENABLED][google.cloud.retail.v2beta.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED].
+    // Value used when unset.
     INDEXABLE_OPTION_UNSPECIFIED = 0;
 
     // Indexable option enabled for an attribute.
@@ -117,8 +116,7 @@ message CatalogAttribute {
 
   // The status of the dynamic facetable option of a catalog attribute.
   enum DynamicFacetableOption {
-    // Value used when unset. Defaults to
-    // [DYNAMIC_FACETABLE_ENABLED][google.cloud.retail.v2beta.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED].
+    // Value used when unset.
     DYNAMIC_FACETABLE_OPTION_UNSPECIFIED = 0;
 
     // Dynamic facetable option enabled for an attribute.
@@ -130,8 +128,7 @@ message CatalogAttribute {
 
   // The status of the searchable option of a catalog attribute.
   enum SearchableOption {
-    // Value used when unset. Defaults to
-    // [SEARCHABLE_DISABLED][google.cloud.retail.v2beta.CatalogAttribute.SearchableOption.SEARCHABLE_DISABLED].
+    // Value used when unset.
     SEARCHABLE_OPTION_UNSPECIFIED = 0;
 
     // Searchable option enabled for an attribute.
@@ -154,6 +151,19 @@ message CatalogAttribute {
     EXACT_SEARCHABLE_DISABLED = 2;
   }
 
+  // The status of the retrievable option of a catalog attribute.
+  enum RetrievableOption {
+    // Value used when unset. Defaults to
+    // [RETRIEVABLE_DISABLED][google.cloud.retail.v2beta.CatalogAttribute.RetrievableOption.RETRIEVABLE_DISABLED].
+    RETRIEVABLE_OPTION_UNSPECIFIED = 0;
+
+    // Retrievable option enabled for an attribute.
+    RETRIEVABLE_ENABLED = 1;
+
+    // Retrievable option disabled for an attribute.
+    RETRIEVABLE_DISABLED = 2;
+  }
+
   // Required. Attribute name.
   // For example: `color`, `brands`, `attributes.custom_attribute`, such as
   // `attributes.xyz`.
@@ -177,13 +187,13 @@ message CatalogAttribute {
   // APIs. This field is `False` for pre-loaded
   // [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]s.
   //
-  // Only pre-loaded
-  // [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]s that are
-  // neither in use by products nor predefined can be deleted.
-  // [CatalogAttribute][google.cloud.retail.v2beta.CatalogAttribute]s that are
-  // either in use by products or are predefined cannot be deleted; however,
-  // their configuration properties will reset to default values upon removal
-  // request.
+  // Only pre-loaded [catalog
+  // attributes][google.cloud.retail.v2beta.CatalogAttribute] that are neither
+  // in use by products nor predefined can be deleted. [Catalog
+  // attributes][google.cloud.retail.v2beta.CatalogAttribute] that are
+  // either in use by products or are predefined attributes cannot be deleted;
+  // however, their configuration properties will reset to default values upon
+  // removal request.
   //
   // After catalog changes, it takes about 10 minutes for this field to update.
   bool in_use = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -197,12 +207,16 @@ message CatalogAttribute {
   // is CATALOG_LEVEL_ATTRIBUTE_CONFIG, if INDEXABLE_ENABLED attribute values
   // are indexed so that it can be filtered, faceted, or boosted in
   // [SearchService.Search][google.cloud.retail.v2beta.SearchService.Search].
+  //
+  // Must be specified, otherwise throws INVALID_FORMAT error.
   IndexableOption indexable_option = 5;
 
   // If DYNAMIC_FACETABLE_ENABLED, attribute values are available for dynamic
   // facet. Could only be DYNAMIC_FACETABLE_DISABLED if
   // [CatalogAttribute.indexable_option][google.cloud.retail.v2beta.CatalogAttribute.indexable_option]
   // is INDEXABLE_DISABLED. Otherwise, an INVALID_ARGUMENT error is returned.
+  //
+  // Must be specified, otherwise throws INVALID_FORMAT error.
   DynamicFacetableOption dynamic_facetable_option = 6;
 
   // When
@@ -215,6 +229,8 @@ message CatalogAttribute {
   // will not be searchable by text queries in
   // [SearchService.Search][google.cloud.retail.v2beta.SearchService.Search], as
   // there are no text values associated to numerical attributes.
+  //
+  // Must be specified, otherwise throws INVALID_FORMAT error.
   SearchableOption searchable_option = 7;
 
   // When
@@ -229,6 +245,10 @@ message CatalogAttribute {
   // This property only applies to textual custom attributes and requires
   // indexable set to enabled to enable exact-searchable.
   ExactSearchableOption exact_searchable_option = 11;
+
+  // If RETRIEVABLE_ENABLED, attribute values are retrievable in the search
+  // results.
+  RetrievableOption retrievable_option = 12;
 }
 
 // Catalog level attribute config.
@@ -353,16 +373,16 @@ message CompletionConfig {
 // will be streamed to the linked branch.
 message MerchantCenterLink {
   // Required. The linked [Merchant center account
-  // id](https://developers.google.com/shopping-content/guides/accountstatuses).
+  // ID](https://developers.google.com/shopping-content/guides/accountstatuses).
   // The account must be a standalone account or a sub-account of a MCA.
   int64 merchant_center_account_id = 1 [(google.api.field_behavior) = REQUIRED];
 
-  // The branch id (e.g. 0/1/2) within this catalog that products from
+  // The branch ID (e.g. 0/1/2) within this catalog that products from
   // merchant_center_account_id are streamed to. When updating this field, an
   // empty value will use the currently configured default branch. However,
   // changing the default branch later on won't change the linked branch here.
   //
-  // A single branch id can only have one linked merchant center account id.
+  // A single branch ID can only have one linked merchant center account ID.
   string branch_id = 2;
 
   // String representing the destination to import for, all if left empty.
@@ -392,6 +412,21 @@ message MerchantCenterLink {
   //
   // Example value: `en`.
   string language_code = 5;
+
+  // Criteria for the Merchant Center feeds to be ingested via the link.
+  // All offers will be ingested if the list is empty.
+  // Otherwise the offers will be ingested from selected feeds.
+  repeated MerchantCenterFeedFilter feeds = 6;
+}
+
+// Merchant Center Feed filter criterion.
+message MerchantCenterFeedFilter {
+  // Merchant Center primary feed ID.
+  int64 primary_feed_id = 1;
+
+  // Merchant Center primary feed name. The name is used for the display
+  // purposes only.
+  string primary_feed_name = 2;
 }
 
 // Configures Merchant Center linking.

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/catalog_service.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/catalog_service.proto
@@ -483,13 +483,18 @@ message BatchRemoveCatalogAttributesRequest {
 // Response of the
 // [CatalogService.BatchRemoveCatalogAttributes][google.cloud.retail.v2beta.CatalogService.BatchRemoveCatalogAttributes].
 message BatchRemoveCatalogAttributesResponse {
-  // Catalog attributes that were deleted. Only attributes that are not [in
-  // use][CatalogAttribute.in_use] by products can be deleted.
+  // Catalog attributes that were deleted. Only pre-loaded [catalog
+  // attributes][google.cloud.retail.v2beta.CatalogAttribute] that are
+  // neither [in
+  // use][google.cloud.retail.v2beta.CatalogAttribute.in_use] by
+  // products nor predefined can be deleted.
   repeated string deleted_catalog_attributes = 1;
 
-  // Catalog attributes that were reset. Attributes that are [in
-  // use][CatalogAttribute.in_use] by products cannot be deleted, however their
-  // configuration properties will reset to default values upon removal request.
+  // Catalog attributes that were reset. [Catalog
+  // attributes][google.cloud.retail.v2beta.CatalogAttribute] that are either
+  // [in use][google.cloud.retail.v2beta.CatalogAttribute.in_use] by products or
+  // are predefined attributes cannot be deleted; however, their configuration
+  // properties will reset to default values upon removal request.
   repeated string reset_catalog_attributes = 2;
 }
 

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/common.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/common.proto
@@ -218,7 +218,8 @@ message Rule {
   }
 
   // Creates a set of terms that will be treated as synonyms of each other.
-  // Example: synonyms of "sneakers" and "shoes".
+  // Example: synonyms of "sneakers" and "shoes":
+  //
   //  * "sneakers" will use a synonym of "shoes".
   //  * "shoes" will use a synonym of "sneakers".
   message TwowaySynonymsAction {

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/completion_service.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/completion_service.proto
@@ -110,8 +110,10 @@ message CompleteQueryRequest {
   // number of language codes is 3.
   repeated string language_codes = 3;
 
-  // The device type context for completion suggestions.
-  // It is useful to apply different suggestions on different device types, e.g.
+  // The device type context for completion suggestions. We recommend that you
+  // leave this field empty.
+  //
+  // It can apply different suggestions on different device types, e.g.
   // `DESKTOP`, `MOBILE`. If it is empty, the suggestions are across all device
   // types.
   //

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/control.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/control.proto
@@ -68,8 +68,8 @@ message Control {
   string display_name = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Output only. List of [serving
-  // configuration][google.cloud.retail.v2beta.ServingConfig] ids that are
-  // associated with this control in the same
+  // config][google.cloud.retail.v2beta.ServingConfig] ids that are associated
+  // with this control in the same
   // [Catalog][google.cloud.retail.v2beta.Catalog].
   //
   // Note the association is managed via the

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/export_config.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/export_config.proto
@@ -81,10 +81,14 @@ message ExportUserEventsResponse {
   OutputResult output_result = 3;
 }
 
-// Output result.
+// Output result that stores the information about where the exported data is
+// stored.
 message OutputResult {
-  // Export result in BigQuery.
+  // The BigQuery location where the result is stored.
   repeated BigQueryOutputResult bigquery_result = 1;
+
+  // The Google Cloud Storage location where the result is stored.
+  repeated GcsOutputResult gcs_result = 2;
 }
 
 // A BigQuery output result.
@@ -95,3 +99,9 @@ message BigQueryOutputResult {
   // The ID of a BigQuery Table.
   string table_id = 2;
 }
+
+// A Gcs output result.
+message GcsOutputResult {
+  // The uri of Gcs output
+  string output_uri = 1;
+}
diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/model.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/model.proto
@@ -160,7 +160,8 @@ message Model {
   //
   // Currently supported values: `recommended-for-you`, `others-you-may-like`,
   // `frequently-bought-together`, `page-optimization`, `similar-items`,
-  // `buy-it-again`, and `recently-viewed`(readonly value).
+  // `buy-it-again`, `on-sale-items`, and `recently-viewed`(readonly value).
+  //
   //
   // This field together with
   // [optimization_objective][google.cloud.retail.v2beta.Model.optimization_objective]

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/prediction_service.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/prediction_service.proto
@@ -62,7 +62,7 @@ message PredictRequest {
   // The ID of the Recommendations AI serving config or placement.
   // Before you can request predictions from your model, you must create at
   // least one serving config or placement for it. For more information, see
-  // [Managing serving configurations]
+  // [Manage serving configs]
   // (https://cloud.google.com/retail/docs/manage-configs).
   //
   // The full list of available serving configs can be seen at
@@ -117,12 +117,11 @@ message PredictRequest {
   //  * filterOutOfStockItems  tag=(-"promotional")
   //  * filterOutOfStockItems
   //
-  // If your filter blocks all prediction results, the API will return generic
-  // (unfiltered) popular products. If you only want results strictly matching
-  // the filters, set `strictFiltering` to True in `PredictRequest.params` to
-  // receive empty results instead.
-  // Note that the API will never return items with storageStatus of "EXPIRED"
-  // or "DELETED" regardless of filter choices.
+  // If your filter blocks all prediction results, the API will return *no*
+  // results. If instead you want empty result sets to return generic
+  // (unfiltered) popular products, set `strictFiltering` to False in
+  // `PredictRequest.params`. Note that the API will never return items with
+  // storageStatus of "EXPIRED" or "DELETED" regardless of filter choices.
   //
   // If `filterSyntaxV2` is set to true under the `params` field, then
   // attribute-based expressions are expected instead of the above described
@@ -149,7 +148,7 @@ message PredictRequest {
   // * `returnScore`: Boolean. If set to true, the prediction 'score'
   //    corresponding to each returned product will be set in the
   //    `results.metadata` field in the prediction response. The given
-  //    'score' indicates the probability of an product being clicked/purchased
+  //    'score' indicates the probability of a product being clicked/purchased
   //    given the user's context and history.
   // * `strictFiltering`: Boolean. True by default. If set to false, the service
   //    will return generic (unfiltered) popular products instead of empty if

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/product.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/product.proto
@@ -105,6 +105,13 @@ message Product {
   oneof expiration {
     // The timestamp when this product becomes unavailable for
     // [SearchService.Search][google.cloud.retail.v2beta.SearchService.Search].
+    // Note that this is only applicable to
+    // [Type.PRIMARY][google.cloud.retail.v2beta.Product.Type.PRIMARY] and
+    // [Type.COLLECTION][google.cloud.retail.v2beta.Product.Type.COLLECTION],
+    // and ignored for
+    // [Type.VARIANT][google.cloud.retail.v2beta.Product.Type.VARIANT]. In
+    // general, we suggest the users to delete the stale products explicitly,
+    // instead of using this field to determine staleness.
     //
     // If it is set, the [Product][google.cloud.retail.v2beta.Product] is not
     // available for
@@ -125,7 +132,14 @@ message Product {
     // [expiration_date](https://support.google.com/merchants/answer/6324499).
     google.protobuf.Timestamp expire_time = 16;
 
-    // Input only. The TTL (time to live) of the product.
+    // Input only. The TTL (time to live) of the product. Note that this is only
+    // applicable to
+    // [Type.PRIMARY][google.cloud.retail.v2beta.Product.Type.PRIMARY] and
+    // [Type.COLLECTION][google.cloud.retail.v2beta.Product.Type.COLLECTION],
+    // and ignored for
+    // [Type.VARIANT][google.cloud.retail.v2beta.Product.Type.VARIANT]. In
+    // general, we suggest the users to delete the stale products explicitly,
+    // instead of using this field to determine staleness.
     //
     // If it is set, it must be a non-negative value, and
     // [expire_time][google.cloud.retail.v2beta.Product.expire_time] is set as
@@ -363,6 +377,11 @@ message Product {
   // The timestamp when this [Product][google.cloud.retail.v2beta.Product]
   // becomes available for
   // [SearchService.Search][google.cloud.retail.v2beta.SearchService.Search].
+  // Note that this is only applicable to
+  // [Type.PRIMARY][google.cloud.retail.v2beta.Product.Type.PRIMARY] and
+  // [Type.COLLECTION][google.cloud.retail.v2beta.Product.Type.COLLECTION], and
+  // ignored for
+  // [Type.VARIANT][google.cloud.retail.v2beta.Product.Type.VARIANT].
   google.protobuf.Timestamp available_time = 18;
 
   // The online availability of the
@@ -550,7 +569,9 @@ message Product {
   // Note: Returning more fields in
   // [SearchResponse][google.cloud.retail.v2beta.SearchResponse] can increase
   // response payload size and serving latency.
-  google.protobuf.FieldMask retrievable_fields = 30;
+  //
+  // This field is deprecated. Use the retrievable site-wide control instead.
+  google.protobuf.FieldMask retrievable_fields = 30 [deprecated = true];
 
   // Output only. Product variants grouped together on primary product which
   // share similar product attributes. It's automatically grouped by

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/search_service.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/search_service.proto
@@ -218,7 +218,7 @@ message SearchRequest {
     FacetKey facet_key = 1 [(google.api.field_behavior) = REQUIRED];
 
     // Maximum of facet values that should be returned for this facet. If
-    // unspecified, defaults to 20. The maximum allowed value is 300. Values
+    // unspecified, defaults to 50. The maximum allowed value is 300. Values
     // above 300 will be coerced to 300.
     //
     // If this field is negative, an INVALID_ARGUMENT is returned.
@@ -478,7 +478,7 @@ message SearchRequest {
   // `projects/*/locations/global/catalogs/default_catalog/servingConfigs/default_serving_config`
   // or the name of the legacy placement resource, such as
   // `projects/*/locations/global/catalogs/default_catalog/placements/default_search`.
-  // This field is used to identify the serving configuration name and the set
+  // This field is used to identify the serving config name and the set
   // of models that will be used to make the search.
   string placement = 1 [(google.api.field_behavior) = REQUIRED];
 

diff --git a/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/user_event_service.proto b/packages/google-cloud-retail/protos/google/cloud/retail/v2beta/user_event_service.proto
@@ -124,10 +124,24 @@ message WriteUserEventRequest {
 
   // Required. User event to write.
   UserEvent user_event = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // If set to true, the user event will be written asynchronously after
+  // validation, and the API will respond without waiting for the write.
+  // Therefore, silent failures can occur even if the API returns success. In
+  // case of silent failures, error messages can be found in Stackdriver logs.
+  bool write_async = 3;
 }
 
 // Request message for CollectUserEvent method.
 message CollectUserEventRequest {
+  // The rule that can convert the raw_json to a user event. It is needed
+  // only when the raw_json is set.
+  oneof conversion_rule {
+    // The prebuilt rule name that can convert a specific type of raw_json.
+    // For example: "default_schema/v1.0"
+    string prebuilt_rule = 6;
+  }
+
   // Required. The parent catalog name, such as
   // `projects/1234/locations/global/catalogs/default_catalog`.
   string parent = 1 [(google.api.field_behavior) = REQUIRED];
@@ -146,6 +160,12 @@ message CollectUserEventRequest {
   // otherwise identical get requests. The name is abbreviated to reduce the
   // payload bytes.
   int64 ets = 4;
+
+  // An arbitrary serialized JSON string that contains necessary information
+  // that can comprise a user event. When this field is specified, the
+  // user_event field will be ignored. Note: line-delimited JSON is not
+  // supported, a single JSON only.
+  string raw_json = 5;
 }
 
 // Request message for RejoinUserEvents method.