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.

Vous pouvez utiliser ce guide pour 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 la section Conception de Merchant API.

Premiers pas

Pour commencer à utiliser Merchant API, remplacez vos URL de requête par le format suivant :

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

Pour utiliser Merchant API, vous devez associer votre compte Merchant Center et votre projet Google Cloud à l'aide de la méthode d'inscription 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 automatisée de l'inventaire
  • Création de rapports personnalisés

Principaux domaines d'amélioration :

Principales modifications :

  • La valeur maximale de pageSize est passée de 250 à 1 000 lignes par appel d'API.
  • Un délai qui existait pour l'insertion de produits, les promotions, les avis sur les produits et les avis sur les marchands après DataSources la création a été corrigé.
  • Lancement d'une définition mise à jour pour clickPotentialRank dans le productView tableau de la sous-API Reporting:
    • Le classement des produits en fonction de clickPotential est normalisé à des valeurs comprises entre 1 et 1 000.
  • Le AccountIdAlias dans 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

Merchant API 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 Merchant API 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 Merchant API.

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 existante de Content API for Shopping v2.1 products. 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 par rapport à Content API

Merchant API améliore Content API dans les domaines suivants :

Examinons ces modifications plus en détail.

Gestion des versions et sous-API

Merchant API introduit les concepts de gestion des versions et de sous-API. Sa conception modulaire facilite l'utilisation, car elle vous permet de vous concentrer sur les sous-API dont vous avez besoin et de faciliter les futures migrations vers des versions plus récentes. La gestion des versions sera appliquée à 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 de Merchant API nécessitent plus 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 la section 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 name identifiant 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} soit égal à accounts/{account}/products/{product}.

Tous les appels de lecture et d'écriture renvoient le champ name comme identifiant de la 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 à des identifiants de produit.

name

Par exemple, implémentez une méthode getName() pour récupérer le name d'une ressource et stocker le résultat en tant que variable au lieu de créer 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 Merchant API
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/{name}

Pour en savoir plus, consultez la section Modifications des identifiants.

Autre exemple : la récupération d'un produit avec l'identifiant en~US~1234 à partir de l'ID Merchant Center 4321 à l'aide de Merchant API se présente comme suit :

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

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

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

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

channel:contentLanguage:feedLabel:offerId.

dans Merchant API devient :

contentLanguage~feedLabel~offerId.

Champs parents pour les ressources enfants

Dans Merchant API, toutes les ressources enfants comportent le parent champ. 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 le produit name dans le parent champ de la list méthode. Dans ce cas, le product donné est le parent des LocalInventory renvoyées.

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

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

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

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

Énumérations courantes

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

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

Le ReportingContext.ReportingContextEnum champ 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 création de rapports (par exemple, pour IssueSeverityPerReportingContext).

Rétrocompatibilité

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

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

Disponibilité de l'appel de procédure à distance (gRPC)

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

Cette solution présente les avantages 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.

Merchant API n'est pas compatible avec la customBatch méthode présentée dans Content API for Shopping. Consultez plutôt Envoyer plusieurs requêtes à la fois ou exécuter 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.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().setPoolSize(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 Merchant API. (Il y aura quelques exceptions, comme la spécification annuelle des flux 2025.)

Les fonctionnalités exclusives de Merchant API incluent :

  • L'API Reviews. Utilisez Reviews 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 les produits.
  • Les notifications : inscrivez-vous pour recevoir des notifications push lorsque les données produit d'un compte sont modifiées.

Prix

Voici les modifications apportées à Price dans le package Merchant Common :

Content API for Shopping Merchant API
Champ "Montant" value:string amountMicros:int64
Champ "Devise" currency:string currencyCode:string

Le montant Price est désormais enregistré en micro-unités, où 1 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 "Devise" est passé de currency à currencyCode. Le format reste ISO 4217.

Dernières mises à jour et annonces

Pour des mises à jour plus précises, consultez les notes de version spécifiques à chaque sous-API. Pour des mises à jour plus régulières et agrégées de Merchant API, 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.

Pour en savoir plus sur Merchant API et ses sous-API, consultez la section Conception de Merchant API.

Suivant
Start your migration