Migrer de Content API for Shopping vers Merchant API

Ce guide explique comment migrer de Content API for Shopping vers l'API Merchant 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 l'API Merchant. Pour en savoir plus sur Merchant API et ses sous-API, consultez Conception de Merchant API.

Commencer

Pour commencer à utiliser l'API Merchant, remplacez les URL de vos requêtes par le 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 du développeur, comme suit :

POST https://merchantapi.googleapis.com/accounts/v1beta/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 l'API Merchant.

Consultez les dernières mises à jour de l'API Merchant (bêta).

Améliorations par rapport à Content API for Shopping

L'API Merchant vous permet d'automatiser et de simplifier les workflows dans Merchant Center. Elle 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 d'amélioration :

Principales modifications :

  • Le nombre maximal de pageSize est passé de 250 à 1 000 lignes par appel d'API.
  • Le délai qui existait pour l'insertion de produits, les promotions, les avis sur les produits et les avis sur les marchands après la création du DataSources a été corrigé.

Voici ce qui vous attend :

  • Abandon et suppression future du champ "canal" pour DataSources et les produits.
  • Lancement d'une définition mise à jour pour clickPotentialRank dans le tableau productView de la sous-API Reporting : * Le classement des produits basé sur clickPotential est normalisé sur des valeurs comprises entre 1 et 1 000.
    • Les produits avec un clickPotentialRank faible ont toujours le plus grand potentiel de clics parmi les produits du marchand qui répondent aux conditions de la requête de recherche. Il s'agit d'une modification non destructrice qui pourra être lancée le 1er juillet 2025.
  • Le 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 l'API Merchant 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.

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

Par exemple, vous pouvez utiliser l'API Merchant Inventories en parallèle de votre implémentation products existante de Content API for Shopping v2.1. Vous pouvez utiliser la 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

L'API Merchant présente les avantages suivants par rapport à Content API :

Examinons ces modifications 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 futures migrations vers des versions plus récentes. La gestion des versions s'appliquera à vos URL de requête.Cette stratégie est semblable à celle de l'API Google Ads.

Des demandes plus robustes

Les requêtes d'URL de l'API Merchant nécessitent plus de paramètres pour appeler l'API Merchant. 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 de l'AIP pour les identifiants

Alors que Content API for Shopping utilise des ID pour identifier les ressources (par exemple, merchantId, productId), l'API Merchant utilise un identifiant name pour s'aligner sur l'AIP (voir les 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 comme 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 à des identifiants produit.

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

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

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

Le tableau ci-dessous 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/v1beta/{name}

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

Par exemple, pour récupérer un produit avec l'identifiant online~en~US~1234 à partir de l'ID Merchant Center 4321 à l'aide de l'API Merchant, la requête se présenterait comme suit :

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

où {name} est égal à accounts/4321/products/online~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 l'API Content for Shopping, le deux-points (:) est un délimiteur dans le nom du produit, tandis que dans l'API Merchant, c'est le tilde (~).

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

channel:contentLanguage:feedLabel:offerId.

dans l'API Merchant Center devient :

channel~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 le 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/v1beta/{parent}/localInventories

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

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

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 produit.

Énumérations courantes

L'utilisation d'énums courants 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 des destinations et est unifié dans les sous-API, par exemple pour les attributs des 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 toutes les méthodes de reporting (par exemple, pour IssueSeverityPerReportingContext).

Rétrocompatibilité

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

Une fois que vous avez migré vos sous-API vers l'API Merchant, nous vous recommandons de n'utiliser que l'API Merchant 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.

Cette solution présente les avantages suivants :

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

Le traitement par lots est plus efficace lorsque vous utilisez des appels asynchrones. Découvrez comment utiliser les appels parallèles pour effectuer le traitement par lot dans l'API Merchant 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.

L'API Merchant ne prend pas en charge la méthode customBatch présentée dans 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.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1beta.Attributes;
import com.google.shopping.merchant.products.v1beta.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1beta.ProductInput;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1beta.Shipping;
import com.google.shopping.type.Channel.ChannelEnum;
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();

    Attributes attributes =
        Attributes.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("in stock")
            .setCondition("new")
            .setGoogleProductCategory("Media > Books")
            .addGtin("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setChannel(ChannelEnum.ONLINE)
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setAttributes(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 service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .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);
  }
}
InsertProductInputAsyncSample.java

Si vous utilisez customBatch dans Content API et que vous avez besoin de cette fonctionnalité pour l'API Merchant, 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 les spécifications annuelles des flux pour 2025.)

Voici quelques exemples de fonctionnalités exclusives à l'API Merchant :

  • API Reviews. Utilisez la fonctionnalité Avis pour implémenter et gérer les notes de vos produits et de votre boutique. Pour en savoir plus, consultez Avis sur les vendeurs et Avis sur les produits.
  • Notifications : inscrivez-vous pour recevoir des notifications push en cas de modification des données produit d'un compte.

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ù 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 la forme d'une 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 mises à jour et annonces

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

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

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

Précédent
Quickstart
Suivant
Migrate accountstatuses to Account Issues