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

Même si les méthodes CRUD (création, lecture, mise à jour et suppression) Product sont utilisées pour modifier de manière générale les attributs d'un objet Product, il existe un ensemble de méthodes Product qui peuvent être utilisées pour mettre à jour des champs spécifiques à l'inventaire avec différents niveaux de précision. Les champs Product suivants sont considérés comme des champs d'inventaire :

  • Product.price_info
  • Product.availability
  • Product.available_quantity
  • Product.fulfillment_info

Configurer l'inventaire

Ce tutoriel explique comment appliquer des mises à jour de l'inventaire à l'aide de la méthode SetInventory au lieu de mettre à jour l'ensemble du produit.

Pour obtenir des instructions détaillées sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

Visite guidée

Ajouter des lieux de traitement

Nous vous recommandons d'utiliser la méthode AddLocalInventories au lieu de AddFulfillmentPlaces. AddLocalInventories permet d'obtenir les mêmes résultats, mais offre un contrôle plus précis de l'ingestion des données d'inventaire en magasin. Pour en savoir plus, reportez-vous à la documentation AddLocalInventories.

Ce tutoriel explique comment mettre à jour les informations de traitement des produits à l'aide de la méthode AddFulfillmentPlaces. De cette manière, la recherche peut afficher des informations indiquant où les produits sont disponibles et où les commandes peuvent être traitées. Par exemple, un acheteur recherche un jean bleu dans un magasin, mais ce dernier n'est pas disponible. Dès que le jean sera de nouveau en stock dans ce magasin ou dans n'importe quel autre magasin, l'acheteur verra les modifications et pourra passer sa commande.

Pour obtenir des instructions détaillées sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

Visite guidée

Supprimer des lieux de traitement

Nous vous recommandons d'utiliser la méthode RemoveLocalInventories au lieu de RemoveFulfillmentPlaces. RmoveLocalInventories permet d'obtenir les mêmes résultats, mais offre un contrôle plus précis de l'ingestion des données d'inventaire en magasin. Pour en savoir plus, reportez-vous à la documentation RemoveLocalInventories.

Ce tutoriel explique comment mettre à jour les informations de traitement des produits à l'aide de la méthode RemoveFulfillmentPlaces. De cette manière, Vertex AI Search pour le commerce peut afficher des informations concernant les produits indisponibles et les commandes ne pouvant pas être traitées. De cette manière, la recherche peut afficher des informations indiquant que les produits ne sont pas disponibles et que les commandes ne peuvent pas être traitées. Par exemple, un acheteur recherche un jean en magasin. Si le jean n'est plus disponible dans cette boutique, le client le voit et ne peut pas passer commande.

Pour obtenir des instructions détaillées sur cette tâche directement dans l'éditeur Cloud Shell, cliquez sur Visite guidée :

Visite guidée

Méthodes de mise à jour de l'inventaire

Les modifications d'informations d'inventaire d'un produit peuvent survenir beaucoup plus fréquemment que les modifications de ses informations de catalogue. De ce fait, un ensemble de méthodes spécialisées est fourni pour gérer de grands volumes de mises à jour spécifiques à l'inventaire. 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.

Mises à jour incrémentielles

Nous vous recommandons de suivre le guide de mise à jour de l'inventaire en magasin pour effectuer des mises à jour incrémentielles de l'inventaire. Les nouvelles méthodes d'API offrent un contrôle plus précis des attributs d'inventaire par lieu.

fulfillment_info est souvent utilisé pour encoder la disponibilité de fulfillment au niveau du lieu pour un Product. Dans certains cas, la disponibilité de fulfillment pour certains lieux spécifiques peut changer. Vous pouvez décider de publier des mises à jour décrivant cette modification plutôt que d'utiliser la méthode UpdateProduct pour spécifier à nouveau l'intégralité des informations de fulfillment du produit.

Dans ce cas, les méthodes AddFulfillmentPlaces et RemoveFulfillmentPlaces peuvent être utilisées pour mettre à jour de manière incrémentielle les modifications de fulfillment d'un produit en fonction des ID de lieu qui sont ajoutés ou supprimés pour un type de fulfillment donné.

Java

Pour découvrir comment installer et utiliser la bibliothèque cliente de Vertex AI Search pour le commerce, consultez la page Vertex AI Search pour les bibliothèques clientes pour le commerce. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Search pour le commerce Java.

Pour vous authentifier auprès de Vertex AI Search pour le commerce, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

public static AddFulfillmentPlacesResponse addFulfillmentPlaces(
    Product productToUpdate, String fulfillmentInfoType, ImmutableList<String> placeIds)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  AddFulfillmentPlacesRequest request = AddFulfillmentPlacesRequest.newBuilder()
      .setProduct(productToUpdate.getName())
      .setType(fulfillmentInfoType)
      .addAllPlaceIds(placeIds)
      .setAddTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .build();

  AddFulfillmentPlacesResponse response = productClient
      .addFulfillmentPlacesAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    type: "pickup-in-store"
    place_ids: "store0"
    place_ids: "store1"
    add_time: {
      seconds: 100
      nanos: 100
    }
    allow_missing: true
  }

Cet exemple de AddFulfillmentPlacesRequest ajoute le type de traitement "pickup-in-store" aux ID de lieu "store0" et "store1" pour le produit spécifié. Étant donné que AddFulfillmentPlacesRequest.allow_missing est défini sur "true", même si le produit n'existe pas déjà, les informations d'inventaire mises à jour seront stockées lorsque le produit sera créé. La mise à jour est horodatée par AddFulfillmentPlacesRequest.add_time afin d'empêcher les mises à jour obsolètes d'ignorer l'état de fulfillment pour ces ID de lieu. Ces fonctionnalités sont décrites plus en détail dans les sections suivantes.

Le comportement de RemoveFulfillmentPlacesRequest est identique et le schéma est très similaire.

Lorsque fulfillment_types est mis à jour par AddLocalInventories et RemoveLocalInventories, il reflète un mappage entre chaque ID de lieu et la liste des types de traitement compatibles. Lorsque fulfillment_info est mis à jour par AddFulfillmentPlaces et RemoveFulfillmentPlaces, il reflète un mappage de chaque type de traitement spécifique à une liste d'ID de lieu compatibles avec chaque type. Les deux types d'API modifient les mêmes informations de traitement sous-jacentes, et leur effet est reflété par Product.fulfillment_info.

Mises à jour non incrémentielles

price_info, availability et available_quantity ne peuvent pas être mis à jour de manière incrémentielle, car ils représentent l'inventaire au niveau du produit plutôt que des informations au niveau du lieu. De plus, il peut être souhaitable de publier des mises à jour non incrémentielles sur fulfillment_info plutôt que de n'effectuer que des modifications incrémentielles. Dans ce cas, la méthode SetInventory est recommandée.

Java

Pour découvrir comment installer et utiliser la bibliothèque cliente de Vertex AI Search pour le commerce, consultez la page Vertex AI Search pour les bibliothèques clientes pour le commerce. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Search pour le commerce Java.

Pour vous authentifier auprès de Vertex AI Search pour le commerce, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

public static SetInventoryResponse setInventoryWithMask(Product productToUpdate,
    FieldMask updateMask)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetMask(updateMask)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: {
      name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
      availability: IN_STOCK
      fulfillment_info: {
        type: "pickup-in-store"
        place_ids: "store0"
        place_ids: "store1"
        place_ids: "store2"
        place_ids: "store3"
      }
      fulfillment_info: {
        type: "same-day-delivery"
      }
    }
    set_time: {
      seconds: 100
      nanos: 100
    }
    set_mask: {
      paths: "availability"
      paths: "fulfillment_info"
    }
    allow_missing: true
  }

Dans cette requête spécifique, les champs SetInventoryRequest.product.fulfillment_info sont des descriptions complètes des ID de lieu éligibles pour chaque type de fulfillment plutôt que des spécifications incrémentielles. La mise à jour de "same-day-delivery" indique qu'aucun ID de lieu n'est éligible pour ce type de fulfillment pour ce produit. Tous les autres types de fulfillment ne sont pas mis à jour dans cette requête. Ainsi, cette méthode peut être utilisée pour remplacer les ID de lieu uniquement pour un sous-ensemble de types de traitement, tout en laissant les autres types intacts.

Par défaut, SetInventory met à jour tous les champs d'inventaire si SetInventory.set_mask n'est pas défini ou est vide. Si le masque n'est pas vide ou si un champ d'inventaire n'est pas explicitement répertorié dans SetInventoryRequest.set_mask, toute valeur spécifiée pour ce champ d'inventaire sera ignorée dans la requête de mise à jour.

Comme pour les mises à jour incrémentielles, le champ SetInventoryRequest.set_time peut être utilisé pour définir une heure de mise à jour qui sera comparée à la dernière heure de mise à jour enregistrée de tous les champs d'inventaire mis à jour.

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

Il existe plusieurs chemins pour mettre à jour les champs d'inventaire d'un produit. Pour se protéger contre les mises à jour désordonnées, chaque champ d'inventaire est associé à une heure de dernière mise à jour.

L'heure de dernière mise à jour est enregistrée pour price_info, availability, available_quantity et chaque paire de (fulfillment_info.place_ids, fulfillment_info.type).

Les méthodes AddFulfillmentPlaces, RemoveFulfillmentPlaces et SetInventory 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 du type de fulfillment "pickup-in- store", avec T comme heure de dernière mise à jour enregistrée. Si RemoveFulfillmentPlacesRequest.type = "pickup-in-store" et RemoveFulfillmentPlacesRequest.place_ids contiennent "store1", la requête effacera "pickup-in-store" de "store1" si et seulement si RemoveFulfillmentPlacesRequest.remove_time est postérieur à T. Il en va de même pour AddFulfillmentPlacesRequests.

SetInventory fonctionne de la même manière pour mettre à jour price_info, availability et available_quantity. Lors de la mise à jour de fulfillment_info, une requête SetInventoryRequest demande implicitement d'ajouter tous les ID de lieu spécifiés pour un type de fulfillment donné et de supprimer tous les ID de lieu existants non spécifiés.

Ainsi, lorsque le SetInventoryRequest est traité, la mise à jour de fulfillment_info est implicitement convertie en AddFulfillmentPlacesRequest et RemoveFulfillmentPlacesRequest pour chaque type de fulfillment spécifié. Cela signifie que si un emplacement existant "store1" avec le fulfillment "pickup-in-store" a une date et une heure de dernière mise à jour T plus récentes que SetInventoryRequest.set_time, l'ajout/la suppression implicite sur "store1" et "pickup-in-store" ne sera pas appliqué.

Précharger les informations d'inventaire

Chacune des méthodes de mise à jour d'inventaire 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 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 sont conservées pendant deux jours au maximum si la valeur Product correspondante n'est pas créée via CreateProduct dans ce délai.

Java

public static SetInventoryResponse setInventory(Product productToUpdate)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Quand utiliser les méthodes Product

Bien qu'il soit possible de mettre à jour les champs d'inventaire avec les méthodes CRUD de produit, l'appelant doit bien comprendre les effets d'une telle modification sur les informations d'inventaire existantes ou préexistantes.

Ces méthodes sont synchrones, ce qui signifie que les optimisations en aval utilisées pour les méthodes d'inventaire ne s'appliquent pas et qu'il peut s'avérer coûteux de s'appuyer sur ces méthodes pour des mises à jour d'inventaire fréquentes. Dans la mesure du possible, préférez l'utilisation des méthodes de mise à jour d'inventaire mentionnées ci-dessus.

CreateProduct

Lorsque CreateProduct est appelé avec un ou plusieurs champs d'inventaire définis, les valeurs fournies dans CreateProductRequest.product remplacent les valeurs préchargées pour ces champs respectifs. Si aucun champ d'inventaire n'est défini, toutes les informations d'inventaire préexistantes sont automatiquement utilisées.

En outre, l'heure de la dernière mise à jour des champs d'inventaire remplacés est réinitialisée sur l'heure de l'appel de méthode.

CreateProduct avec un inventaire préchargé.

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
  }
}

Dans cet exemple, aucun champ d'inventaire n'est défini pour le produit créé. Cela signifie que les informations d'inventaire préchargées seront automatiquement utilisées si ont été mises à jour à l'aide des méthodes de mise à jour d'inventaire. Cela peut être utile lorsque les mises à jour d'inventaire sont découplées des mises à jour de catalogue et que vous souhaitez synchroniser Product avec des informations d'inventaire préexistantes.

CreateProduct avec un inventaire explicite.

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
    availability: OUT_OF_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
}

Dans cet exemple, un objet Product est créé avec des champs d'inventaire explicitement définis. Ces champs remplacent les valeurs préexistantes, en ignorant la dernière heure de mise à jour pour les champs correspondants. Ainsi, vous pouvez garantir que la disponibilité de l'objet Product est définie sur OUT_OF_STOCK et qu'aucun ID de lieu n'est compatible avec les types de fulfillment "pickup-in-store" et "same-day-delivery".

CreateProduct avec les informations d'inventaire peut être utile si vous ne savez pas si toutes les informations d'inventaire préchargées sont exactes et que vous préférez définir explicitement l'inventaire au moment de la création deProduct pour synchroniser entièrement le catalogue et l'inventaire.

UpdateProduct

Lorsque UpdateProduct est appelé et que le masque de champ UpdateProductRequest.update_mask contient des champs d'inventaire, les valeurs fournies dans UpdateProductRequest.product remplacent les valeurs préchargées pour ces champs respectifs.

En outre, l'heure de la dernière mise à jour des champs d'inventaire remplacés est réinitialisée sur l'heure de l'appel de méthode.

PROTO

{
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    availability: IN_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
      place_ids: "store0"
      place_ids: "store1"
      place_ids: "store2"
      place_ids: "store3"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
  update_mask: {
    paths: "availability"
    paths: "fulfillment_info"
  }
}

Cet exemple est très semblable à l'exemple SetInventory, à ceci près qu'il est garanti que la mise à jour est appliquée, quelle que soit l'heure de la dernière mise à jour de chaque champ d'inventaire.

UpdateProduct pour l'inventaire peut être utile lorsque vous devez synchroniser des informations d'inventaire en ignorant les protections d'horodatage.

Bien qu'il soit possible de précharger les informations d'inventaire à l'aide de UpdateProduct en définissant UpdateProductRequest.allow_missing sur true pour effectuer une insertion Product, la méthode nécessite de définir des champs de catalogue spécifiques tels queUpdateProductRequest.product.title. Par conséquent, il est recommandé d'utiliser les méthodes de mise à jour d'inventaire pour les cas d'utilisation de préchargement.

DeleteProduct

Lorsque DeleteProduct est appelé, toutes les informations d'inventaire existantes pour le produit spécifié dans DeleteProductRequest.name sont supprimées, y compris tous les enregistrements de l'heure de dernière mise à jour pour chaque champ d'inventaire.