Migrer de Content API for Shopping vers Merchant API

Ce guide explique le processus de migration de Content API for Shopping vers Merchant API pour la gestion des données d'entreprise.

Ce guide vous explique comment migrer votre implémentation existante de Content API for Shopping vers Merchant API. Pour en savoir plus sur Merchant API et ses sous-API, consultez Conception de Merchant API.

Commencer

Pour commencer à utiliser l'API Merchant, modifiez les URL de vos requêtes au format suivant :

https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}…

Pour utiliser l'API Merchant, vous devez associer votre compte Merchant Center et votre projet Google Cloud à l'aide de la méthode d'enregistrement des développeurs, comme suit :

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  developer_email:"example-email@example.com"
}

Pour en savoir plus, consultez le guide de démarrage rapide et la documentation de référence de Merchant API.

Améliorations par rapport à Content API for Shopping

Merchant API vous permet d'automatiser et de simplifier les workflows dans Merchant Center, et offre des fonctionnalités améliorées par rapport à Content API for Shopping.

Principaux cas d'utilisation :

  • Gestion automatisée des comptes
  • Gestion automatisée des produits
  • Gestion automatique de l'inventaire
  • Création de rapports personnalisés

Principaux domaines à améliorer :

Modifications apportées

  • Le nombre maximal de pageSize est passé de 250 à 1 000 lignes par appel d'API.
  • Un délai existait pour l'insertion de produits, les promotions, les avis sur les produits et les avis sur les marchands après la création de DataSources. Ce problème a été résolu.
  • Lancement d'une définition mise à jour pour clickPotentialRank dans la table productView sous la sous-API Reporting :
    • Le classement des produits en fonction de clickPotential est normalisé avec des valeurs comprises entre 1 et 1 000.
  • Le champ AccountIdAlias de la ressource AccountRelationship permet de mieux gérer les structures de compte complexes. Par exemple, les places de marché utilisent un alias défini par l'utilisateur au lieu de l'ID interne du marchand, tel que l'ID de compte.

Compatibilité avec gRPC

L'API Merchant est compatible avec gRPC et REST. Vous pouvez utiliser gRPC pour Merchant API et REST pour Content API for Shopping en même temps.

Les bibliothèques clientes de l'API Merchant nécessitent gRPC.

Pour en savoir plus, consultez la présentation de gRPC.

Compatibilité

Ce guide décrit les modifications générales qui s'appliquent à l'ensemble de l'API Merchant.

La Merchant API est conçue pour fonctionner avec les fonctionnalités existantes de Content API for Shopping.

Par exemple, vous pouvez utiliser l'API Merchant Inventories avec votre implémentation products existante de Content API for Shopping v2.1. Vous pouvez utiliser Content API for Shopping pour importer un nouveau produit en magasin (que vous vendez dans un magasin physique), puis utiliser la ressource LocalInventory de l'API Merchant Inventories pour gérer les informations en magasin de ce produit.

Améliorations structurelles par rapport à Content API

Merchant API apporte des améliorations par rapport à Content API dans les domaines suivants :

Examinons ces changements plus en détail.

Gestion des versions et sous-API

L'API Merchant introduit les concepts de gestion des versions et de sous-API. Sa conception modulaire améliore la facilité d'utilisation, en vous permettant de vous concentrer sur les sous-API dont vous avez besoin et en facilitant les migrations futures vers des versions plus récentes. Le contrôle des versions sera appliqué à vos URL de requête. La stratégie est semblable à celle de l'API Google Ads.

Requêtes plus robustes

Les requêtes d'URL Merchant API nécessitent davantage de paramètres pour appeler Merchant API. Cela inclut la ressource, la version, le nom (identifiants) et la méthode (méthodes non standards). Pour en savoir plus, consultez Identifiants de compte et de produit et Exemples.

Principes AIP pour les identifiants

Alors que Content API for Shopping utilise des ID pour identifier les ressources (par exemple, merchantId, productId), Merchant API utilise un identifiant name pour s'aligner sur l'AIP (voir Principes d'amélioration des API).

L'identifiant {name} inclut l'identifiant de la ressource et son parent (ou potentiellement plusieurs parents), de sorte que {name} est égal à accounts/{account}/products/{product}.

Tous les appels de lecture et d'écriture renvoient le champ name en tant qu'identifiant de ressource.

{name} inclut également les identifiants de collection accounts/ et products/.

Merchant API utilise {account} pour faire référence à un ID Merchant Center et {product} pour faire référence aux codes produit.

Par exemple, implémentez une méthode getName() pour récupérer le name à partir d'une ressource, puis stockez le résultat en tant que variable au lieu de construire vous-même le name à partir des ID de marchand et de ressource.

Voici un exemple d'utilisation du champ name dans vos appels :

   POST https://merchantapi.googleapis.com/inventories/v1/{PARENT}/regionalInventories:insert

Le tableau montre comment la requête products.get de Content API for Shopping change :

Content API for Shopping API Merchant
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/{name}

Pour en savoir plus, consultez Modifications apportées aux identifiants.

Autre exemple : pour récupérer un produit avec l'identifiant en~US~1234 à partir de l'ID Merchant Center 4321 à l'aide de Merchant API, procédez comme suit :

    GET
    https://merchantapi.googleapis.com/products/v1/accounts/4321/products/en~US~1234

où {name} est égal à accounts/4321/products/en~US~1234. Ce nouveau champ de nom est renvoyé en tant qu'identifiant de ressource pour tous les appels de lecture et d'écriture dans l'API Merchant.

Dans Content API for Shopping, le signe deux-points (:) sert de délimiteur dans le nom du produit, tandis que dans Merchant API, c'est le tilde (~) qui remplit cette fonction. L'identifiant de l'API Merchant ne contient pas la partie channel.

Par exemple, l'ID produit dans Content API for Shopping :

channel:contentLanguage:feedLabel:offerId.

dans l'API Merchant devient :

contentLanguage~feedLabel~offerId.

Champs parents pour les ressources enfants

Dans l'API Merchant, toutes les ressources enfants comportent le champ parent. Vous pouvez utiliser le champ parent pour spécifier le {name} de la ressource dans laquelle insérer l'enfant, au lieu de transmettre l'intégralité de la ressource parente. Vous pouvez également utiliser le champ parent avec list.

Par exemple, pour lister les inventaires en magasin d'un produit donné, spécifiez l'name du produit dans le champ parent de la méthode list. Dans ce cas, le product donné est le parent des ressources LocalInventory renvoyées.

    GET
    https://merchantapi.googleapis.com/inventories/v1/{parent}/localInventories

Pour récupérer tous les inventaires en magasin pour le produit en~US~1234 et le compte 4321, la requête se présente comme suit :

    GET
    https://merchantapi.googleapis.com/inventories/v1/accounts/4321/products/en~US~1234/localInventories

Le parent est accounts/{account}/products/{product}. Notez que dans ce cas, la ressource localInventories comporte deux parents inclus dans l'identifiant de nom (accounts/ et products/), car le compte est le parent de la ressource de produit.

Énumérations courantes

L'utilisation d'énumérations courantes offre une plus grande cohérence.

Le champ Destination.DestinationEnum spécifie les surfaces sur lesquelles afficher vos ressources. DestinationEnum liste toutes les valeurs disponibles pour le ciblage par destination et est unifié entre les sous-API, par exemple pour les attributs de promotions.

Le champ ReportingContext.ReportingContextEnum représente le contexte auquel s'appliquent les problèmes liés à votre compte et à vos produits. Ce champ est utilisé dans les méthodes de reporting (par exemple, pour IssueSeverityPerReportingContext).

Rétrocompatibilité.

Lorsque vous commencez à utiliser Merchant API, votre intégration Content API for Shopping existante continue de fonctionner sans interruption. Pour en savoir plus, consultez Compatibilité.

Une fois que vous avez migré vos sous-API vers Merchant API, nous vous recommandons de n'utiliser que Merchant API pour vos sous-API migrées.

Disponibilité des appels de procédure à distance (gRPC)

gRPC est la nouvelle méthode recommandée pour l'intégration à l'API Merchant.

Ses avantages sont les suivants :

Le traitement par lot personnalisé devient un traitement par lot intégré

Le traitement par lot est plus efficace lorsque vous utilisez des appels asynchrones. Découvrez comment utiliser des appels parallèles pour effectuer un traitement par lot dans Merchant API et comment refactoriser le code pour les requêtes simultanées.

Pour accélérer votre migration, nous vous recommandons d'utiliser les bibliothèques clientes.

La Merchant API n'est pas compatible avec la méthode customBatch de Content API for Shopping. Consultez plutôt Envoyer plusieurs requêtes à la fois ou exécutez vos appels de manière asynchrone.

.

L'exemple Java suivant montre comment insérer une entrée de produit :

   import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.api.gax.grpc.ChannelPoolSettings;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1.Availability;
import com.google.shopping.merchant.products.v1.Condition;
import com.google.shopping.merchant.products.v1.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1.ProductAttributes;
import com.google.shopping.merchant.products.v1.ProductInput;
import com.google.shopping.merchant.products.v1.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1.Shipping;
import com.google.shopping.type.Price;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert a product input */
public class InsertProductInputAsyncSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static ProductInput createRandomProduct() {
    Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();

    Shipping shipping =
        Shipping.newBuilder().setPrice(price).setCountry("GB").setService("1st class post").build();

    Shipping shipping2 =
        Shipping.newBuilder().setPrice(price).setCountry("FR").setService("1st class post").build();

    ProductAttributes attributes =
        ProductAttributes.newBuilder()
            .setTitle("A Tale of Two Cities")
            .setDescription("A classic novel about the French Revolution")
            .setLink("https://exampleWebsite.com/tale-of-two-cities.html")
            .setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
            .setAvailability(Availability.IN_STOCK)
            .setCondition(Condition.NEW)
            .setGoogleProductCategory("Media > Books")
            .addGtins("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setProductAttributes(attributes)
        .build();
  }

  public static void asyncInsertProductInput(Config config, String dataSource) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates a channel provider. This provider manages a pool of gRPC channels
    // to enhance throughput for bulk operations. Each individual channel in the pool
    // can handle up to approximately 100 concurrent requests.
    //
    // Channel: A single connection pathway to the service.
    // Pool: A collection of multiple channels managed by this provider.
    //   Requests are distributed across the channels in the pool.
    //
    // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
    // utilization of channel capacity), and set the pool size to that number.
    InstantiatingGrpcChannelProvider channelProvider =
        InstantiatingGrpcChannelProvider.newBuilder()
            .setChannelPoolSettings(ChannelPoolSettings.staticallySized(30))
            .build();

    // Creates service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .setTransportChannelProvider(channelProvider)
            .build();

    // Creates parent to identify where to insert the product.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (ProductInputsServiceClient productInputsServiceClient =
        ProductInputsServiceClient.create(productInputsServiceSettings)) {

      // Creates five insert product input requests with random product IDs.
      List<InsertProductInputRequest> requests = new ArrayList<>(5);
      for (int i = 0; i < 5; i++) {
        InsertProductInputRequest request =
            InsertProductInputRequest.newBuilder()
                .setParent(parent)
                // You can only insert products into datasource types of Input "API", and of Type
                // "Primary" or "Supplemental."
                // This field takes the `name` field of the datasource.
                .setDataSource(dataSource)
                // If this product is already owned by another datasource, when re-inserting, the
                // new datasource will take ownership of the product.
                .setProductInput(createRandomProduct())
                .build();

        requests.add(request);
      }

      System.out.println("Sending insert product input requests");
      List<ApiFuture<ProductInput>> futures =
          requests.stream()
              .map(
                  request ->
                      productInputsServiceClient.insertProductInputCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<ProductInput>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<ProductInput>>() {
            @Override
            public void onSuccess(List<ProductInput> results) {
              System.out.println("Inserted products below");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // Identifies the data source that will own the product input.
    String dataSource = "accounts/" + config.getAccountId() + "/dataSources/{datasourceId}";

    asyncInsertProductInput(config, dataSource);
  }
}

Si vous utilisez customBatch dans Content API et que vous avez besoin de cette fonctionnalité pour Merchant API, indiquez-nous pourquoi dans vos commentaires.

Fonctionnalités exclusives

Les futures fonctionnalités n'apparaîtront que dans l'API Merchant. (Il y aura quelques exceptions, comme la spécification annuelle des flux pour 2025.)

Fonctionnalités exclusives à la Merchant API :

  • API Reviews. Utilisez les avis pour implémenter et gérer les notes de vos produits et de votre boutique. Pour en savoir plus, consultez Avis sur le marchand et Avis sur le produit.
  • Notifications : inscrivez-vous pour recevoir des notifications push concernant les modifications apportées aux données de votre compte et aux données produit.

Prix

Voici ce qui a changé pour Price dans le package Merchant Common :

Content API for Shopping API Merchant
Champ du montant value:string amountMicros:int64
Champ de devise currency:string currencyCode:string

Le montant Price est désormais enregistré en micro-unités, où un million de micro-unités équivaut à l'unité standard de votre devise.

Dans Content API for Shopping, Price était un nombre décimal sous forme de chaîne.

Le nom du champ "Montant" est passé de value à amountMicros

Le nom du champ de devise est passé de currency à currencyCode. Le format reste ISO 4217.

Dernières actualités et annonces

Pour des mises à jour plus précises, consultez les notes de version spécifiques à chaque sous-API. Pour obtenir des informations plus régulières sur l'API Merchant, consultez nos dernières mises à jour.

Pour en savoir plus sur Merchant API, consultez la présentation de notre site pour les développeurs et le guide de migration global.

Consultez Conception de l'API Merchant pour en savoir plus sur l'API Merchant et ses sous-API.

Précédent
Manage and transition Google Cloud projects
Suivant
Start your migration