feat: Add local inventory ingestion APIs to product service in alpha …

…channel (#112)

* feat: Add local inventory ingestion APIs to product service in alpha channel

PiperOrigin-RevId: 406273138

Source-Link: googleapis/googleapis@148d29d

Source-Link: googleapis/googleapis-gen@9e96961
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiOWU5Njk2MTgzYTNmMmQwNWJjZjZjYTExODA2MGUxMjU2MmY5MGY1NSJ9

* 🦉 Updates from OwlBot

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>

protos/google/cloud/retail/v2alpha/common.proto

@@ -432,3 +432,29 @@ message Promotion {
   // [promotion](https://support.google.com/merchants/answer/7050148).
   string promotion_id = 1;
 }
+
+// The inventory information at a place (e.g. a store) identified
+// by a place ID.
+message LocalInventory {
+  // The place ID for the current set of inventory information.
+  string place_id = 1;
+
+  // Product price and cost information.
+  //
+  // Google Merchant Center property
+  // [price](https://support.google.com/merchants/answer/6324371).
+  PriceInfo price_info = 2;
+
+  // Additional local inventory attributes, for example, store name, promotion
+  // tags, etc.
+  // * At most 5 values are allowed. Otherwise, an INVALID_ARGUMENT error is
+  //   returned.
+  // * The key must be a UTF-8 encoded string with a length limit of 10
+  //   characters.
+  // * The key must match the pattern: `[a-zA-Z0-9][a-zA-Z0-9_]*`. For example,
+  //   key0LikeThis or KEY_1_LIKE_THIS.
+  // * The attribute values must be of the same type (text or number).
+  // * The max number of values per attribute is 10.
+  // * For text values, the length limit is 10 UTF-8 characters.
+  map<string, CustomAttribute> attributes = 3;
+}

protos/google/cloud/retail/v2alpha/product_service.proto

@@ -216,6 +216,74 @@ service ProductService {
       metadata_type: "google.cloud.retail.v2alpha.RemoveFulfillmentPlacesMetadata"
     };
   }
+
+  // Updates local inventory information for a
+  // [Product][google.cloud.retail.v2alpha.Product] at a list of places, while
+  // respecting the last update timestamps of each inventory field.
+  //
+  // This process is asynchronous and does not require the
+  // [Product][google.cloud.retail.v2alpha.Product] to exist before updating
+  // inventory information. If the request is valid, the update will be enqueued
+  // and processed downstream. As a consequence, when a response is returned,
+  // updates are not immediately manifested in the
+  // [Product][google.cloud.retail.v2alpha.Product] queried by
+  // [GetProduct][google.cloud.retail.v2alpha.ProductService.GetProduct] or
+  // [ListProducts][google.cloud.retail.v2alpha.ProductService.ListProducts].
+  //
+  // Store inventory information can only be modified using this method.
+  // [CreateProduct][google.cloud.retail.v2alpha.ProductService.CreateProduct]
+  // and
+  // [UpdateProduct][google.cloud.retail.v2alpha.ProductService.UpdateProduct]
+  // has no effect on local inventories.
+  //
+  // This feature is only available for users who have Retail Search enabled.
+  // Please submit a form [here](https://cloud.google.com/contact) to contact
+  // Cloud sales if you are interested in using Retail Search.
+  rpc AddLocalInventories(AddLocalInventoriesRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v2alpha/{product=projects/*/locations/*/catalogs/*/branches/*/products/**}:addLocalInventories"
+      body: "*"
+    };
+    option (google.api.method_signature) = "product";
+    option (google.longrunning.operation_info) = {
+      response_type: "google.cloud.retail.v2alpha.AddLocalInventoriesResponse"
+      metadata_type: "google.cloud.retail.v2alpha.AddLocalInventoriesMetadata"
+    };
+  }
+
+  // Remove local inventory information for a
+  // [Product][google.cloud.retail.v2alpha.Product] at a list of places at a
+  // removal timestamp.
+  //
+  // This process is asynchronous. If the request is valid, the removal will be
+  // enqueued and processed downstream. As a consequence, when a response is
+  // returned, removals are not immediately manifested in the
+  // [Product][google.cloud.retail.v2alpha.Product] queried by
+  // [GetProduct][google.cloud.retail.v2alpha.ProductService.GetProduct] or
+  // [ListProducts][google.cloud.retail.v2alpha.ProductService.ListProducts].
+  //
+  // Store inventory information can only be removed using this method.
+  // [CreateProduct][google.cloud.retail.v2alpha.ProductService.CreateProduct]
+  // and
+  // [UpdateProduct][google.cloud.retail.v2alpha.ProductService.UpdateProduct]
+  // has no effect on local inventories.
+  //
+  // This feature is only available for users who have Retail Search enabled.
+  // Please submit a form [here](https://cloud.google.com/contact) to contact
+  // Cloud sales if you are interested in using Retail Search.
+  rpc RemoveLocalInventories(RemoveLocalInventoriesRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v2alpha/{product=projects/*/locations/*/catalogs/*/branches/*/products/**}:removeLocalInventories"
+      body: "*"
+    };
+    option (google.api.method_signature) = "product";
+    option (google.longrunning.operation_info) = {
+      response_type: "google.cloud.retail.v2alpha.RemoveLocalInventoriesResponse"
+      metadata_type: "google.cloud.retail.v2alpha.RemoveLocalInventoriesMetadata"
+    };
+  }
 }
 
 // Request message for [CreateProduct][] method.
@@ -597,6 +665,109 @@ message AddFulfillmentPlacesMetadata {}
 // method.
 message AddFulfillmentPlacesResponse {}
 
+// Request message for [AddLocalInventories][] method.
+message AddLocalInventoriesRequest {
+  // 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
+  // [Product][google.cloud.retail.v2alpha.Product], regardless of whether or
+  // not it exists, a PERMISSION_DENIED error is returned.
+  string product = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "retail.googleapis.com/Product" }
+  ];
+
+  // Required. A list of inventory information at difference places. Each place
+  // is identified by its place ID. At most 1000 inventories are allowed per
+  // request.
+  repeated LocalInventory local_inventories = 2
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Indicates which inventory fields in the provided list of
+  // [LocalInventory][google.cloud.retail.v2alpha.LocalInventory] to update. The
+  // field is updated to the provided value.
+  //
+  // If a field is set while the place does not have a previous local inventory,
+  // the local inventory at that store is created.
+  //
+  // If a field is set while the value of that field is not provided, the
+  // original field value, if it exists, is deleted.
+  //
+  // If the mask is not set or set with empty paths, all inventory fields will
+  // be updated.
+  //
+  // If an unsupported or unknown field is provided, an INVALID_ARGUMENT error
+  // is returned and the entire update will be ignored.
+  google.protobuf.FieldMask add_mask = 4;
+
+  // The time when the inventory updates are issued. Used to prevent
+  // out-of-order updates on local inventory fields. If not provided, the
+  // internal system time will be used.
+  google.protobuf.Timestamp add_time = 5;
+
+  // If set to true, and the [Product][google.cloud.retail.v2alpha.Product] is
+  // not found, the local inventory will still be processed and retained for at
+  // most 1 day and processed once the
+  // [Product][google.cloud.retail.v2alpha.Product] is created. If set to false,
+  // an INVALID_ARGUMENT error is returned if the
+  // [Product][google.cloud.retail.v2alpha.Product] is not found.
+  bool allow_missing = 6;
+}
+
+// Metadata related to the progress of the AddLocalInventories operation.
+// Currently empty because there is no meaningful metadata populated from the
+// [AddLocalInventories][] method.
+message AddLocalInventoriesMetadata {}
+
+// Response of the [AddLocalInventories][] API.  Currently empty because
+// there is no meaningful response populated from the [AddLocalInventories][]
+// method.
+message AddLocalInventoriesResponse {}
+
+// Request message for [RemoveLocalInventories][] method.
+message RemoveLocalInventoriesRequest {
+  // 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
+  // [Product][google.cloud.retail.v2alpha.Product], regardless of whether or
+  // not it exists, a PERMISSION_DENIED error is returned.
+  string product = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "retail.googleapis.com/Product" }
+  ];
+
+  // Required. A list of place IDs to have their inventory deleted.
+  // At most 1000 place IDs are allowed per request.
+  repeated string place_ids = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // The time when the inventory deletions are issued. Used to prevent
+  // out-of-order updates and deletions on local inventory fields. If not
+  // provided, the internal system time will be used.
+  google.protobuf.Timestamp remove_time = 5;
+
+  // If set to true, and the [Product][google.cloud.retail.v2alpha.Product] is
+  // not found, the local inventory removal request will still be processed and
+  // retained for at most 1 day and processed once the
+  // [Product][google.cloud.retail.v2alpha.Product] is created. If set to false,
+  // a NOT_FOUND error is returned if the
+  // [Product][google.cloud.retail.v2alpha.Product] is not found.
+  bool allow_missing = 3;
+}
+
+// Metadata related to the progress of the RemoveLocalInventories operation.
+// Currently empty because there is no meaningful metadata populated from the
+// [RemoveLocalInventories][] method.
+message RemoveLocalInventoriesMetadata {}
+
+// Response of the [RemoveLocalInventories][] API.  Currently empty because
+// there is no meaningful response populated from the [RemoveLocalInventories][]
+// method.
+message RemoveLocalInventoriesResponse {}
+
 // Request message for [RemoveFulfillmentPlaces][] method.
 message RemoveFulfillmentPlacesRequest {
   // Required. Full resource name of