Mettre à jour l'inventaire local pour Vertex AI Search pour le commerce

LocalInventory correspond aux informations d'inventaire associées à un lieu donné, identifié par son place_id. Par exemple, vous pouvez créer un LocalInventory pour un magasin ou une région où un prix spécifique est disponible. LocalInventory comporte les champs suivants:

• LocalInventory.price_info
• LocalInventory.attributes
• LocalInventory.fulfillment_types

Les entrées LocalInventory existantes sont visibles via Product.local_inventories (à l'exception de fulfillment_types, qui, pour assurer la rétrocompatibilité, est disponible via Product.fulfillment_info). Ce champ est à sortie uniquement. Définir Product.local_inventories pour les API CRUD Product ou SetInventory n'a aucun effet.

Chaque paire (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) pointe vers la même paire (fulfillment_info.place_ids, fulfillment_info.type) mentionnée dans la documentation de mise à jour de l'inventaire. fulfillment_types, mis à jour par AddLocalInventories et RemoveLocalInventories décrit ci-dessous, reflète une mise en correspondance de chaque ID de lieu avec une liste des types de traitement compatibles, tandis que fulfillment_info, mis à jour par AddFulfillmentPlaces et RemoveFulfillmentPlaces, reflète une mise en correspondance de chaque type de traitement spécifique avec une liste des ID de lieu compatibles avec ce type. Toutefois, les deux types d'API modifient les mêmes informations de traitement sous-jacentes, et l'effet des deux types d'API sera reflété sur Product.fulfillment_info.

Méthodes de mise à jour de l'inventaire en magasin

Les modifications apportées aux informations sur l'inventaire local d'un produit peuvent survenir beaucoup plus fréquemment que les modifications de ses informations de catalogue. Un ensemble de méthodes spécialisées est fourni pour gérer de grands volumes de mises à jour spécifiques à l'inventaire en magasin. Ces méthodes sont asynchrones en raison des optimisations en aval qui permettent d'accepter des centaines de mises à jour simultanées par produit, sans compromis sur les performances.

AddLocalInventories

AddLocalInventories peut être utilisé pour créer des inventaires locaux dans de nouveaux lieux (représentés par de nouveaux place_id) ou pour mettre à jour des champs existants dans des inventaires locaux existants. Les champs ajoutés ou mis à jour dans la liste des entrées LocalInventory du corps de la requête peuvent être spécifiés via AddLocalInventoriesRequest.add_mask. Les valeurs add_mask possibles sont:

• price_info: remplace LocalInventory.price_info.
• attributes: remplace tous les LocalInventory.attributes. Les attributs existants qui ne sont pas mentionnés dans le corps de la requête sont supprimés.
• attributes.PLACEHOLDER_NAME: ne remplace que l'attribut personnalisé spécifié. Si aucun nom d'attribut existant n'est fourni dans la requête, l'attribut est supprimé. Vous pouvez spécifier plusieurs attributes.PLACEHOLDER_NAME, à condition que chaque nom d'attribut soit différent. Toutefois, AddLocalInventoriesRequest.add_mask ne peut pas inclure à la fois la valeur attributes et les valeurs attributes.PLACEHOLDER_NAME dans la même requête.
• fulfillment_types: écrase tous les types de traitement compatibles. Les types de traitement existants qui ne sont pas mentionnés dans le corps de la requête sont supprimés.

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store1"
    price_info: {
      currency_code: "USD"
      price: 100
      original_price: 110
      cost: 95
    }
    fulfillment_types: "pickup-in-store"
    fulfillment_types: "ship-to-store"
  }
  local_inventories: {
    place_id: "store2"
    price_info: {
      currency_code: "USD"
      price: 200
      original_price: 210
      cost: 195
    }
    attributes: {
      key: "attr1",
      value: {
        text: "store2_value"
      }
    }
    fulfillment_types: "custom-type-1"
  }
  add_mask: {
    paths: "price_info"
    paths: "attributes.attr1"
    paths: "fulfillment_types"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}
  

Cet exemple AddLocalInventoriesRequest ajoute ou met à jour deux inventaires en magasin avec les ID de lieu "store1" et "store2" pour le produit spécifié. Si store1 existe et que store2 n'existe pas avant la requête, la requête met à jour les champs de store1 et crée store2 avec les valeurs de champ données.

Ce AddLocalInventoriesRequest.add_mask spécifie que price_info, un seul attribut personnalisé nommé "attr1", et fulfillment_types doivent être mis à jour à l'aide des valeurs fournies dans AddLocalInventoriesRequest.local_inventories.

attributes sont des attributs associés à un lieu avec un nom et des valeurs personnalisables. Étant donné que LocalInventory de store1 ne fournit pas la valeur de attr1 dans la requête, l'attribut personnalisé attr1 est supprimé de l'LocalInventory existant de store1 s'il existe. La valeur de l'attribut attr1 de store2 sera définie sur une valeur textuelle store2_value. Les autres attributs personnalisés existants sur store1 et store2 ne sont pas modifiés.

fulfillment_types représente une liste de disponibilités de traitement pour un Product à un seul endroit. Il est identique et accepte les mêmes valeurs que fulfillment_info.type. Ce AddLocalInventoriesRequest spécifie que store1 est compatible avec les types de traitement pickup-in-store et ship-to-store, tandis que store1 est compatible avec custom-type-1. Les types de traitement existants avant cette mise à jour qui ne sont pas mentionnés dans la demande seront supprimés.

Étant donné que AddLocalInventoriesRequest.allow_missing est défini sur "true", même si le produit n'existe pas déjà, les informations d'inventaire en magasin mises à jour seront stockées pour être utilisées une fois le produit créé. La mise à jour est horodatée par AddLocalInventoriesRequest.add_time afin d'empêcher les mises à jour obsolètes d'ignorer les champs spécifiés de ces ID de lieu. Pour en savoir plus sur la prévention des mises à jour obsolètes et le stockage des informations sur l'inventaire en magasin avant la création du produit, consultez les pages Protections d'horodatage pour les mises à jour d'inventaire en magasin et Précharger des informations sur l'inventaire.

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store3"
    attributes: {
      key: "attr1",
      value: {
        text: "attr1_value"
      }
    }
    attributes: {
      key: "attr2",
      value: {
        numbers: 123
      }
    }
  }
  add_mask: {
    paths: "attributes"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
}
  

Cet exemple AddLocalInventoriesRequest ajoute ou met à jour un seul inventaire en magasin avec l'ID de lieu "store3" pour le produit spécifié. Étant donné que son add_mask contient "attributes", tous les attributs personnalisés existants de store3 sont supprimés et remplacés par attr1 et attr2, comme spécifié dans la requête. Notez que, comme allow_missing n'est pas défini, le produit spécifié doit exister. Dans le cas contraire, une erreur NOT_FOUND est renvoyée.

RemoveLocalInventories

RemoveLocalInventories permet de supprimer les inventaires en magasin existants pour les lieux associés à des ID de lieu donnés.

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  place_ids: "store1"
  place_ids: "store2"
  remove_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}
  

Cet exemple de RemoveLocalInventoriesRequest supprime les inventaires en magasin pour les lieux dont les ID de lieu sont "store1" et "store2" pour le produit spécifié. La mise à jour est horodatée par RemoveLocalInventoriesRequest.remove_time afin d'empêcher les mises à jour obsolètes d'ignorer la suppression de ces ID de lieu. Pour les ID de lieu spécifiés sans inventaire en magasin existant, la requête enregistre également leur heure de mise à jour sur remove_time. Pour en savoir plus sur les horodatages des mises à jour, consultez la section Protections d'horodatage pour les mises à jour d'inventaire en magasin.

Protections d'horodatage pour les mises à jour d'inventaire en magasin

Pour se protéger contre les mises à jour désordonnées, chaque champ d'inventaire local est associé à une heure de dernière mise à jour.

L'heure de la dernière mise à jour est enregistrée pour chaque paire (place_id, price_info), (place_id, attributes[...]) et (place_id, fulfillment_types[...]).

Les méthodes AddLocalInventories et RemoveLocalInventories permettent à l'appelant de spécifier une heure de mise à jour pour le moment où la requête est émise. Cette heure de mise à jour est comparée à l'heure de dernière mise à jour enregistrée pour les champs d'inventaire concernés. La mise à jour n'est validée que si elle est strictement postérieure à l'heure de dernière mise à jour.

Par exemple, supposons que l'ID de lieu "store1" dispose de price_info, avec T comme heure de dernière mise à jour enregistrée. Si RemoveLocalInventoriesRequest.place_ids contient "store1", la requête ne supprimera price_info de "store1" que si RemoveLocalInventoriesRequest.remove_time est postérieur à T. Il en va de même pour les RemoveLocalInventoriesRequest.

Avec la protection par code temporel, il est possible qu'un RemoveLocalInventoriesRequest ne supprime que certains champs d'un LocalInventory au lieu de tous. Supposons qu'un inventaire local avec l'ID de lieu "store1" dispose de price_info avec l'heure de dernière mise à jour enregistrée définie sur T1 et que son seul attribut personnalisé existant, nommé "attr1", dispose de l'heure de dernière mise à jour enregistrée sur T2. Si un RemoveLocalInventoriesRequest.place_ids contient "store1" et que remove_time est défini sur T3 (où T1 < T3 < T2), le price_info de store_1 est supprimé, tandis que son attribut attr1 reste inchangé.

Précharger les informations d'inventaire

Chacune des méthodes de mise à jour d'inventaire en magasin permet à l'appelant de définir allow_missing dans la requête. Lorsque allow_missing est défini sur "true", une mise à jour d'inventaire local vers un Product inexistant est traitée comme si l'objet Product existait et conformément aux spécifications de la méthode. Les informations d'inventaire locales sont conservées pendant deux jours au maximum si la valeur Product correspondante n'est pas créée via CreateProduct dans ce délai.