Ce document concerne Recommendations AI, Retail Search et la nouvelle console Retail.

Mettre à jour l'inventaire en magasin pour Retail Search

LocalInventory correspond aux informations sur l'inventaire associées à un lieu spécifique, identifiées par son place_id. Par exemple, vous pouvez créer un LocalInventory pour un magasin ou une région où un certain prix 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 est compatible avec la rétrocompatibilité, disponible via Product.fulfillment_info). Ce champ est généré uniquement. La définition de 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 sur la mise à jour de l'inventaire. La méthode fulfillment_types mise à jour par AddLocalInventories et RemoveLocalInventories ci-dessous reflète le mappage de chaque ID de lieu vers une liste des types de traitement qu'elle accepte, tandis que fulfillment_info est mis à jour par AddFulfillmentPlaces et RemoveFulfillmentPlaces. Cependant, les deux types d'API modifient les mêmes informations de traitement sous-jacente, et l'effet des deux types est répercuté dans Product.fulfillment_info.

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

Les modifications apportées aux informations sur l'inventaire en magasin d'un produit peuvent être beaucoup plus fréquentes que celles sur son catalogue. Un ensemble spécialisé de méthodes est fourni pour gérer de grands volumes de mises à jour spécifiques à l'inventaire en magasin. Ces méthodes sont asynchrones, car des optimisations en aval sont compatibles avec des centaines de mises à jour simultanées par produit, sans sacrifier les performances.

AddLocalInventories

AddLocalInventories peut être utilisé pour créer des inventaires locaux à de nouveaux emplacements (représentés avec de nouveaux place_id) ou mettre à jour des champs existants sur 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 valides sont les suivantes:

  • price_info: remplace LocalInventory.price_info.
  • attributes : écrase tout LocalInventory.attributes. Les attributs existants qui ne sont pas mentionnés dans le corps de la requête sont supprimés.
  • attributes.PLACEHOLDER_NAME : écrase uniquement l'attribut personnalisé spécifié. Si aucun nom d'attribut existant n'est indiqué dans la requête, l'attribut est supprimé. Vous pouvez spécifier plusieurs attributs attributes.PLACEHOLDER_NAME, à condition que chaque nom d'attribut soit différent. Toutefois, AddLocalInventoriesRequest.add_mask ne peut pas inclure à la fois les valeurs attributes et 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.

Proto

{
  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 de modèle AddLocalInventoriesRequest ajoute ou met à jour deux inventaires locaux 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, celle-ci mettra à jour les champs de store1 et créera store2 avec les valeurs de champ données.

AddLocalInventoriesRequest.add_mask spécifie que price_info, un seul attribut personnalisé portant le nom "attr1", et fulfillment_types doit ê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 sur store1 ne fournit pas la valeur attr1 dans la requête, l'attribut personnalisé attr1 sera supprimé de l'élément LocalInventory existant de store1, le cas échéant. L'attribut de la propriété store2 sera attr1's défini sur store2_value. Les autres attributs personnalisés existants sur store1 et store2 ne sont pas modifiés.

fulfillment_types représente la liste des disponibilités de traitement pour un Product à un seul endroit. Elle est identique et accepte les mêmes valeurs que fulfillment_info.type. Cette valeur AddLocalInventoriesRequest indique 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 requête seront supprimés.

Comme AddLocalInventoriesRequest.allow_missing est défini sur "true", même si le produit n'existe pas encore, les informations sur l'inventaire en magasin mises à jour seront stockées lors de la création du produit. La mise à jour est horodatée avec AddLocalInventoriesRequest.add_time pour éviter que les mises à jour obsolètes ne remplacent les champs spécifiés de ces ID de lieu. Pour savoir comment éviter les mises à jour obsolètes et stocker les informations sur l'inventaire en magasin avant la création de votre produit, consultez les sections Protections de l'horodatage pour les mises à jour de l'inventaire en magasin et Précharger les informations de l'inventaire.

Proto

{
  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 de code AddLocalInventoriesRequest ajoute ou met à jour un inventaire en magasin avec l'ID de lieu "store3" pour le produit spécifié. Comme 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. Sinon, une erreur NOT_FOUND est générée.

RemoveLocalInventories

RemoveLocalInventories permet de supprimer les inventaires locaux existants à l'aide d'identifiants de lieu donnés.

Proto

{
  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 code RemoveLocalInventoriesRequest supprime les inventaires locaux pour les lieux associés aux ID de lieu "store1" et "store2" pour le produit spécifié. La mise à jour est horodatée avec RemoveLocalInventoriesRequest.remove_time pour éviter que les mises à jour obsolètes ne remplacent la suppression de ces ID de lieu. Pour les ID de lieu spécifiés sans inventaires locaux existants, la requête enregistre également l'heure de mise à jour dans remove_time. Pour en savoir plus sur les horodatages des mises à jour, consultez Protections de l'horodatage pour les mises à jour de l'inventaire en magasin.

Protections de l'horodatage pour les mises à jour de l'inventaire en magasin

Pour éviter les mises à jour hors commande, chaque champ d'inventaire en magasin est associé à une heure de mise à jour la plus récente.

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 l'heure à laquelle la requête doit être émise. Cette heure est comparée à l'heure de la dernière mise à jour enregistrée pour les champs d'inventaire pertinents. De plus, la mise à jour n'est validée que si cette heure est strictement postérieure à la date et à l'heure de la dernière mise à jour.

Par exemple, supposons que l'ID de lieu "store1" affiche price_info avec la dernière date et heure d'enregistrement définies sur T. Si RemoveLocalInventoriesRequest.place_ids contient "store1", la requête supprime price_info de "store1" uniquement si RemoveLocalInventoriesRequest.remove_time est ultérieur à T. Il en va de même pour les RemoveLocalInventoriesRequests.

Dans le cadre de la protection de l'horodatage, il est possible qu'un élément RemoveLocalInventoriesRequest ne supprime que certains champs d'un élément LocalInventory au lieu de tous les champs. Supposons qu'un inventaire en magasin avec l'ID de lieu "store1" a price_info pour l'heure de dernière mise à jour définie sur l'heure T1 et que son seul attribut personnalisé existant soit "attr1" et possède la dernière heure d'enregistrement pour T2. Si un élément RemoveLocalInventoriesRequest.place_ids contient "store1" et que remove_time est défini sur T3 (où T1 < T3 < T2), store_1 est supprimé, tandis que son attribut attr1 n'est pas modifié.

Précharger les informations d'inventaire

Chacune de ces méthodes permet à l'appelant de définir allow_missing dans la requête. Lorsque la valeur allow_missing est définie sur "true", une mise à jour d'inventaire en magasin vers une valeur Product inexistante est traitée comme si la valeur Product existait conformément aux spécifications de la méthode. Les informations sur l'inventaire en magasin seront conservées pendant une durée maximale de deux jours si le Product correspondant n'est pas créé via CreateProduct au cours de cette période.