feat: add a Type field to Product.proto. This field is currently outp…

…ut only. docs: Keep the API doc up-to-date PiperOrigin-RevId: 346583028
googleapis · Dec 9, 2020 · 98476fa · 98476fa
1 parent c32a98c
commit 98476fa
Show file tree

Hide file tree

Showing 12 changed files with 165 additions and 61 deletions.
diff --git a/google/cloud/retail/v2/catalog.proto b/google/cloud/retail/v2/catalog.proto
@@ -35,13 +35,16 @@ message ProductLevelConfig {
   // The type of [Product][google.cloud.retail.v2.Product]s allowed to be
   // ingested into the catalog. Acceptable values are:
   //
-  // * `primary` (default): You can only ingest PRIMARY
-  // [Product][google.cloud.retail.v2.Product]s. This means
+  // * `primary` (default): You can only ingest
+  // [Product.Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
+  //   [Product][google.cloud.retail.v2.Product]s. This means
   //   [Product.primary_product_id][google.cloud.retail.v2.Product.primary_product_id]
   //   can only be empty or set to the same value as
   //   [Product.id][google.cloud.retail.v2.Product.id].
-  // * `variant`: You can only ingest VARIANT
-  // [Product][google.cloud.retail.v2.Product]s. This means
+  // * `variant`: You can only ingest
+  // [Product.Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
+  // [Product][google.cloud.retail.v2.Product]s.
+  //   This means
   //   [Product.primary_product_id][google.cloud.retail.v2.Product.primary_product_id]
   //   cannot be empty.
   //

diff --git a/google/cloud/retail/v2/prediction_service.proto b/google/cloud/retail/v2/prediction_service.proto
@@ -76,10 +76,7 @@ message PredictRequest {
   //   Recently viewed.
   //
   // The full list of available placements can be seen at
-  //
-  // https:
-  // //console.cloud.google.com/recommendatio
-  // // n/catalogs/default_catalog/placements
+  // https://console.cloud.google.com/recommendation/catalogs/default_catalog/placements
   string placement = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Required. Context about the user, what they are looking at and what action

diff --git a/google/cloud/retail/v2/product.proto b/google/cloud/retail/v2/product.proto
@@ -45,6 +45,40 @@ message Product {
     pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/branches/{branch}/products/{product}"
   };
 
+  // The type of this product.
+  enum Type {
+    // Default value. Default to
+    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY] if unset.
+    TYPE_UNSPECIFIED = 0;
+
+    // The primary type.
+    //
+    // As the primary unit for predicting, indexing and search serving, a
+    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
+    // [Product][google.cloud.retail.v2.Product] is grouped with multiple
+    // [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
+    // [Product][google.cloud.retail.v2.Product]s.
+    PRIMARY = 1;
+
+    // The variant type.
+    //
+    // [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
+    // [Product][google.cloud.retail.v2.Product]s usually share some common
+    // attributes on the same
+    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
+    // [Product][google.cloud.retail.v2.Product]s, but they have variant
+    // attributes like different colors, sizes and prices, etc.
+    VARIANT = 2;
+
+    // The collection type. Collection products are bundled
+    // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
+    // [Product][google.cloud.retail.v2.Product]s or
+    // [Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
+    // [Product][google.cloud.retail.v2.Product]s that are sold together, such
+    // as a jewelry set with necklaces, earrings and rings, etc.
+    COLLECTION = 3;
+  }
+
   // Product availability. If this field is unspecified, the product is
   // assumed to be in stock.
   enum Availability {
@@ -67,7 +101,6 @@ message Product {
   }
 
   // Immutable. Full resource name of the product, such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/product_id".
   //
   // The branch ID must be "default_branch".
@@ -77,7 +110,6 @@ message Product {
   // the final component of [name][google.cloud.retail.v2.Product.name]. For
   // example, this field is "id_1", if
   // [name][google.cloud.retail.v2.Product.name] is
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/id_1".
   //
   // This field must be a UTF-8 encoded string with a length limit of 128
@@ -88,16 +120,20 @@ message Product {
   // Property [Product.sku](https://schema.org/sku).
   string id = 2 [(google.api.field_behavior) = IMMUTABLE];
 
+  // Immutable. The type of the product. This field is output-only.
+  Type type = 3 [(google.api.field_behavior) = IMMUTABLE];
+
   // Variant group identifier. Must be an
   // [id][google.cloud.retail.v2.Product.id], with the same parent branch with
   // this product. Otherwise, an error is thrown.
   //
-  // For PRIMARY [Product][google.cloud.retail.v2.Product]s, this field can only
-  // be empty or set to the same value as
-  // [id][google.cloud.retail.v2.Product.id].
+  // For [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
+  // [Product][google.cloud.retail.v2.Product]s, this field can only be empty or
+  // set to the same value as [id][google.cloud.retail.v2.Product.id].
   //
   // For VARIANT [Product][google.cloud.retail.v2.Product]s, this field cannot
-  // be empty. A maximum of 2,000 products are allowed to share the same PRIMARY
+  // be empty. A maximum of 2,000 products are allowed to share the same
+  // [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
   // [Product][google.cloud.retail.v2.Product]. Otherwise, an INVALID_ARGUMENT
   // error is returned.
   //
@@ -129,8 +165,9 @@ message Product {
   //        "Sports & Fitness > Athletic Clothing > Shoes"
   //      ]
   //
-  // Must be set for PRIMARY [Product][google.cloud.retail.v2.Product] otherwise
-  // an INVALID_ARGUMENT error is returned.
+  // Must be set for [Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
+  // [Product][google.cloud.retail.v2.Product] otherwise an INVALID_ARGUMENT
+  // error is returned.
   //
   // At most 250 values are allowed per
   // [Product][google.cloud.retail.v2.Product]. Empty values are not allowed.

diff --git a/google/cloud/retail/v2/product_service.proto b/google/cloud/retail/v2/product_service.proto
@@ -60,8 +60,7 @@ service ProductService {
     option (google.api.method_signature) = "name";
   }
 
-  // Updates a [Product][google.cloud.retail.v2.Product]. Non-existing items
-  // will be created.
+  // Updates a [Product][google.cloud.retail.v2.Product].
   rpc UpdateProduct(UpdateProductRequest) returns (Product) {
     option (google.api.http) = {
       patch: "/v2/{product.name=projects/*/locations/*/catalogs/*/branches/*/products/**}"
@@ -101,7 +100,6 @@ service ProductService {
 // Request message for [CreateProduct][] method.
 message CreateProductRequest {
   // Required. The parent catalog resource name, such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch".
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
@@ -133,7 +131,6 @@ message CreateProductRequest {
 message GetProductRequest {
   // Required. Full resource name of [Product][google.cloud.retail.v2.Product],
   // such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/some_product_id".
   //
   // If the caller does not have permission to access the
@@ -174,7 +171,6 @@ message UpdateProductRequest {
 message DeleteProductRequest {
   // Required. Full resource name of [Product][google.cloud.retail.v2.Product],
   // such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/some_product_id".
   //
   // If the caller does not have permission to delete the

diff --git a/google/cloud/retail/v2alpha/catalog.proto b/google/cloud/retail/v2alpha/catalog.proto
@@ -35,13 +35,16 @@ message ProductLevelConfig {
   // The type of [Product][google.cloud.retail.v2alpha.Product]s allowed to be
   // ingested into the catalog. Acceptable values are:
   //
-  // * `primary` (default): You can only ingest PRIMARY
-  // [Product][google.cloud.retail.v2alpha.Product]s. This means
+  // * `primary` (default): You can only ingest
+  // [Product.Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY]
+  //   [Product][google.cloud.retail.v2alpha.Product]s. This means
   //   [Product.primary_product_id][google.cloud.retail.v2alpha.Product.primary_product_id]
   //   can only be empty or set to the same value as
   //   [Product.id][google.cloud.retail.v2alpha.Product.id].
-  // * `variant`: You can only ingest VARIANT
-  // [Product][google.cloud.retail.v2alpha.Product]s. This means
+  // * `variant`: You can only ingest
+  // [Product.Type.VARIANT][google.cloud.retail.v2alpha.Product.Type.VARIANT]
+  // [Product][google.cloud.retail.v2alpha.Product]s.
+  //   This means
   //   [Product.primary_product_id][google.cloud.retail.v2alpha.Product.primary_product_id]
   //   cannot be empty.
   //

diff --git a/google/cloud/retail/v2alpha/prediction_service.proto b/google/cloud/retail/v2alpha/prediction_service.proto
@@ -76,10 +76,7 @@ message PredictRequest {
   //   Recently viewed.
   //
   // The full list of available placements can be seen at
-  //
-  // https:
-  // //console.cloud.google.com/recommendatio
-  // // n/catalogs/default_catalog/placements
+  // https://console.cloud.google.com/recommendation/catalogs/default_catalog/placements
   string placement = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Required. Context about the user, what they are looking at and what action

diff --git a/google/cloud/retail/v2alpha/product.proto b/google/cloud/retail/v2alpha/product.proto
@@ -45,6 +45,41 @@ message Product {
     pattern: "projects/{project}/locations/{location}/catalogs/{catalog}/branches/{branch}/products/{product}"
   };
 
+  // The type of this product.
+  enum Type {
+    // Default value. Default to
+    // [Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY] if
+    // unset.
+    TYPE_UNSPECIFIED = 0;
+
+    // The primary type.
+    //
+    // As the primary unit for predicting, indexing and search serving, a
+    // [Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY]
+    // [Product][google.cloud.retail.v2alpha.Product] is grouped with multiple
+    // [Type.VARIANT][google.cloud.retail.v2alpha.Product.Type.VARIANT]
+    // [Product][google.cloud.retail.v2alpha.Product]s.
+    PRIMARY = 1;
+
+    // The variant type.
+    //
+    // [Type.VARIANT][google.cloud.retail.v2alpha.Product.Type.VARIANT]
+    // [Product][google.cloud.retail.v2alpha.Product]s usually share some common
+    // attributes on the same
+    // [Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY]
+    // [Product][google.cloud.retail.v2alpha.Product]s, but they have variant
+    // attributes like different colors, sizes and prices, etc.
+    VARIANT = 2;
+
+    // The collection type. Collection products are bundled
+    // [Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY]
+    // [Product][google.cloud.retail.v2alpha.Product]s or
+    // [Type.VARIANT][google.cloud.retail.v2alpha.Product.Type.VARIANT]
+    // [Product][google.cloud.retail.v2alpha.Product]s that are sold together,
+    // such as a jewelry set with necklaces, earrings and rings, etc.
+    COLLECTION = 3;
+  }
+
   // Product availability. If this field is unspecified, the product is
   // assumed to be in stock.
   enum Availability {
@@ -67,7 +102,6 @@ message Product {
   }
 
   // Immutable. Full resource name of the product, such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/product_id".
   //
   // The branch ID must be "default_branch".
@@ -77,7 +111,6 @@ message Product {
   // is the final component of [name][google.cloud.retail.v2alpha.Product.name].
   // For example, this field is "id_1", if
   // [name][google.cloud.retail.v2alpha.Product.name] is
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/id_1".
   //
   // This field must be a UTF-8 encoded string with a length limit of 128
@@ -88,17 +121,22 @@ message Product {
   // Property [Product.sku](https://schema.org/sku).
   string id = 2 [(google.api.field_behavior) = IMMUTABLE];
 
+  // Immutable. The type of the product. This field is output-only.
+  Type type = 3 [(google.api.field_behavior) = IMMUTABLE];
+
   // Variant group identifier. Must be an
   // [id][google.cloud.retail.v2alpha.Product.id], with the same parent branch
   // with this product. Otherwise, an error is thrown.
   //
-  // For PRIMARY [Product][google.cloud.retail.v2alpha.Product]s, this field can
-  // only be empty or set to the same value as
+  // For [Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY]
+  // [Product][google.cloud.retail.v2alpha.Product]s, this field can only be
+  // empty or set to the same value as
   // [id][google.cloud.retail.v2alpha.Product.id].
   //
   // For VARIANT [Product][google.cloud.retail.v2alpha.Product]s, this field
   // cannot be empty. A maximum of 2,000 products are allowed to share the same
-  // PRIMARY [Product][google.cloud.retail.v2alpha.Product]. Otherwise, an
+  // [Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY]
+  // [Product][google.cloud.retail.v2alpha.Product]. Otherwise, an
   // INVALID_ARGUMENT error is returned.
   //
   // Google Merchant Center Property
@@ -129,8 +167,10 @@ message Product {
   //        "Sports & Fitness > Athletic Clothing > Shoes"
   //      ]
   //
-  // Must be set for PRIMARY [Product][google.cloud.retail.v2alpha.Product]
-  // otherwise an INVALID_ARGUMENT error is returned.
+  // Must be set for
+  // [Type.PRIMARY][google.cloud.retail.v2alpha.Product.Type.PRIMARY]
+  // [Product][google.cloud.retail.v2alpha.Product] otherwise an
+  // INVALID_ARGUMENT error is returned.
   //
   // At most 250 values are allowed per
   // [Product][google.cloud.retail.v2alpha.Product]. Empty values are not

diff --git a/google/cloud/retail/v2alpha/product_service.proto b/google/cloud/retail/v2alpha/product_service.proto
@@ -60,8 +60,7 @@ service ProductService {
     option (google.api.method_signature) = "name";
   }
 
-  // Updates a [Product][google.cloud.retail.v2alpha.Product]. Non-existing
-  // items will be created.
+  // Updates a [Product][google.cloud.retail.v2alpha.Product].
   rpc UpdateProduct(UpdateProductRequest) returns (Product) {
     option (google.api.http) = {
       patch: "/v2alpha/{product.name=projects/*/locations/*/catalogs/*/branches/*/products/**}"
@@ -101,7 +100,6 @@ service ProductService {
 // Request message for [CreateProduct][] method.
 message CreateProductRequest {
   // Required. The parent catalog resource name, such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch".
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
@@ -133,7 +131,6 @@ message CreateProductRequest {
 message GetProductRequest {
   // Required. Full resource name of
   // [Product][google.cloud.retail.v2alpha.Product], such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/some_product_id".
   //
   // If the caller does not have permission to access the
@@ -174,7 +171,6 @@ message UpdateProductRequest {
 message DeleteProductRequest {
   // Required. Full resource name of
   // [Product][google.cloud.retail.v2alpha.Product], such as
-  //
   // "projects/*/locations/global/catalogs/default_catalog/branches/default_branch/products/some_product_id".
   //
   // If the caller does not have permission to delete the

diff --git a/google/cloud/retail/v2beta/catalog.proto b/google/cloud/retail/v2beta/catalog.proto
@@ -35,13 +35,16 @@ message ProductLevelConfig {
   // The type of [Product][google.cloud.retail.v2beta.Product]s allowed to be
   // ingested into the catalog. Acceptable values are:
   //
-  // * `primary` (default): You can only ingest PRIMARY
-  // [Product][google.cloud.retail.v2beta.Product]s. This means
+  // * `primary` (default): You can only ingest
+  // [Product.Type.PRIMARY][google.cloud.retail.v2beta.Product.Type.PRIMARY]
+  //   [Product][google.cloud.retail.v2beta.Product]s. This means
   //   [Product.primary_product_id][google.cloud.retail.v2beta.Product.primary_product_id]
   //   can only be empty or set to the same value as
   //   [Product.id][google.cloud.retail.v2beta.Product.id].
-  // * `variant`: You can only ingest VARIANT
-  // [Product][google.cloud.retail.v2beta.Product]s. This means
+  // * `variant`: You can only ingest
+  // [Product.Type.VARIANT][google.cloud.retail.v2beta.Product.Type.VARIANT]
+  // [Product][google.cloud.retail.v2beta.Product]s.
+  //   This means
   //   [Product.primary_product_id][google.cloud.retail.v2beta.Product.primary_product_id]
   //   cannot be empty.
   //

diff --git a/google/cloud/retail/v2beta/prediction_service.proto b/google/cloud/retail/v2beta/prediction_service.proto
@@ -76,10 +76,7 @@ message PredictRequest {
   //   Recently viewed.
   //
   // The full list of available placements can be seen at
-  //
-  // https:
-  // //console.cloud.google.com/recommendatio
-  // // n/catalogs/default_catalog/placements
+  // https://console.cloud.google.com/recommendation/catalogs/default_catalog/placements
   string placement = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Required. Context about the user, what they are looking at and what action