Eseguire la migrazione dall'API Content for Shopping all'API Merchant

Questa guida spiega il processo di migrazione dall'API Content for Shopping all'API Merchant per la gestione dei dati aziendali.

Puoi utilizzare questa guida per eseguire la migrazione della tua implementazione esistente dell'API Content for Shopping all'API Merchant. Per saperne di più sui dettagli dell'API Merchant e delle relative API secondarie, consulta la pagina Progettazione dell'API Merchant.

Inizia

Per iniziare a utilizzare l'API Merchant, modifica gli URL di richiesta nel seguente formato:

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

Per utilizzare l'API Merchant, devi collegare il tuo account Merchant Center e il tuo progetto Google Cloud utilizzando il metodo di registrazione dello sviluppatore, come segue:

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

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

Per saperne di più, consulta la guida rapida e il riferimento dell'API Merchant.

Miglioramenti rispetto all'API Content for Shopping

L'API Merchant ti consente di automatizzare e semplificare i flussi di lavoro in Merchant Center e offre funzionalità avanzate rispetto all'API Content for Shopping.

Casi d'uso principali:

  • Gestione automatizzata degli account
  • Gestione automatizzata dei prodotti
  • Gestione automatica dell'inventario
  • Rapporti personalizzati

Principali aree di miglioramento:

Che cosa è cambiato

  • Il numero massimo di pageSize è aumentato da 250 a 1000 righe per chiamata API.
  • È stato risolto un ritardo che si verificava per l'inserimento dei prodotti, le promozioni, le recensioni prodotto e le recensioni dei commercianti dopo la creazione di DataSources.
  • Lancio di una definizione aggiornata per clickPotentialRank nella tabella productView nella sub-API Reporting:
    • Il ranking dei prodotti in base a clickPotential è normalizzato su valori compresi tra 1 e 1000.
  • La risorsa AccountIdAlias in AccountRelationship consente di gestire meglio strutture di account complesse. Ad esempio, i marketplace utilizzano un alias definito dall'utente anziché l'ID interno del commerciante, come l'ID account.

Supporto gRPC

L'API Merchant supporta gRPC e REST. Puoi utilizzare gRPC per l'API Merchant e REST per l'API Content for Shopping contemporaneamente.

Le librerie client dell'API Merchant richiedono gRPC.

Per saperne di più, consulta la panoramica di gRPC.

Compatibilità

Questa guida descrive le modifiche generali che si applicano all'intera API Merchant.

L'API Merchant è progettata per funzionare insieme alle funzionalità esistenti dell'API Content for Shopping.

Ad esempio, puoi utilizzare l'API Inventory insieme all'implementazione esistente dell'API Content for Shopping v2.1 products. Puoi utilizzare l'API Content for Shopping per caricare un nuovo prodotto locale (che vendi in un negozio fisico) e poi utilizzare la risorsa LocalInventory dell'API Merchant Inventories per gestire le informazioni in negozio per quel prodotto.

Miglioramenti strutturali rispetto all'API Content

L'API Merchant migliora l'API Content nelle seguenti aree:

Esamina queste modifiche in modo più dettagliato.

Controllo delle versioni e API secondarie

L'API Merchant introduce i concetti di controllo delle versioni e API secondarie. Il suo design modulare migliora la facilità d'uso, consentendoti di concentrarti sulle API secondarie di cui hai bisogno e semplificando le migrazioni future a versioni più recenti. Il controllo delle versioni verrà applicato con gli URL di richiesta. La strategia è simile all'esperienza con l'API Google Ads.

Richieste più solide

Le richieste di URL dell'API Merchant richiedono più parametri per chiamare l'API Merchant. Sono inclusi la risorsa, la versione, il nome (identificatori) e il metodo (metodi non standard). Per saperne di più, consulta ID account e prodotto ed esempi.

Principi AIP per gli identificatori

Mentre l'API Content for Shopping utilizza gli ID per identificare le risorse (ad es. merchantId, productId), l'API Merchant utilizza un identificatore name per l'allineamento con l'AIP (consulta i principi di miglioramento dell'API).

L'identificatore {name} include l'identificatore della risorsa e il relativo elemento principale (o potenzialmente più elementi principali), in modo che {name} sia uguale a accounts/{account}/products/{product}

Tutte le chiamate di lettura e scrittura restituiscono il campo name come identificatore della risorsa.

{name} include anche gli identificatori di raccolta accounts/ e products/.

L'API Merchant utilizza {account} per fare riferimento a un ID Merchant Center e {product} per fare riferimento agli ID prodotto.

Ad esempio, implementa un metodo getName() per recuperare name da una risorsa e memorizza l'output come variabile anziché creare autonomamente name dagli ID commerciante e risorsa.

Ecco un esempio di come utilizzare il campo name nelle chiamate:

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

La tabella mostra come cambia la richiesta products.get dell'API Content for Shopping:

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

Per maggiori dettagli, consulta Modifiche agli identificatori.

Un altro esempio è il recupero di un prodotto con l'identificatore en~US~1234 dall'ID Merchant Center 4321 utilizzando l'API Merchant:

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

dove {name} è uguale a accounts/4321/products/en~US~1234. Questo nuovo campo del nome viene restituito come identificatore della risorsa per tutte le chiamate di lettura e scrittura nell'API Merchant.

Nell'API Content for Shopping, i due punti (:) indicano un delimitatore nel nome del prodotto, mentre nell'API Merchant questa funzione viene eseguita da una tilde (~). L'identificatore dell'API Merchant non contiene la parte channel.

Ad esempio, l'ID prodotto nell'API Content for Shopping:

channel:contentLanguage:feedLabel:offerId.

nell'API Merchant diventa:

contentLanguage~feedLabel~offerId.

Campi padre per le risorse figlio

Nell'API Merchant, tutte le risorse secondarie hanno il campo parent. Puoi utilizzare il campo parent per specificare il {name} della risorsa in cui inserire l'elemento secondario, anziché passare l'intera risorsa principale. Puoi anche utilizzare il campo parent con list.

Ad esempio, per elencare gli inventari locali di un determinato prodotto, specifica il name del prodotto nel campo parent per il metodo list. In questo caso, l'elemento product specificato è l'elemento parent delle risorse LocalInventory restituite.

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

Per recuperare tutti gli inventari locali per il prodotto en~US~1234 e l'account 4321, la richiesta sarà simile alla seguente:

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

Il genitore è accounts/{account}/products/{product}. Tieni presente che in questo caso la risorsa localInventories ha due elementi principali inclusi nell'identificatore del nome (accounts/ e products/), poiché l'account è l'elemento principale della risorsa del prodotto.

Enum comuni

L'utilizzo di enum comuni garantisce una maggiore coerenza.

Il campo Destination.DestinationEnum specifica le piattaforme su cui mostrare le risorse. DestinationEnum elenca tutti i valori disponibili per il targeting per destinazione ed è unificato tra le API secondarie, ad esempio per gli attributi delle promozioni.

Il campo ReportingContext.ReportingContextEnum rappresenta il contesto a cui si applicano i problemi relativi all'account e ai prodotti. Questo campo viene utilizzato in tutti i metodi di generazione dei report (ad esempio per IssueSeverityPerReportingContext).

Compatibilità con le versioni precedenti

Quando inizi a utilizzare l'API Merchant, la tua integrazione esistente dell'API Content for Shopping continua a funzionare senza interruzioni. Per saperne di più, consulta Compatibilità.

Una volta eseguita la migrazione delle sub-API all'API Merchant, ti consigliamo di utilizzare solo l'API Merchant per le sub-API di cui è stata eseguita la migrazione.

Disponibilità di chiamate di procedura remota (gRPC)

gRPC è il nuovo metodo consigliato per l'integrazione con l'API Merchant.

I vantaggi includono:

Il raggruppamento in batch personalizzato diventa raggruppamento in batch integrato

Il raggruppamento in batch è più efficiente quando utilizzi chiamate asincrone. Scopri di più sull'utilizzo delle chiamate parallele per ottenere il batching nell'API Merchant e su come rifattorizzare il codice per le richieste in parallelo.

Per accelerare la migrazione, ti consigliamo di utilizzare le librerie client.

L'API Merchant non supporta il metodo customBatch presente nell'API Content for Shopping. Consulta invece Invia più richieste contemporaneamente o esegui le chiamate in modo asincrono.

Il seguente esempio Java mostra come inserire un input del prodotto:

   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);
  }
}

Se utilizzi customBatch nell'API Content e hai bisogno di questa funzionalità per l'API Merchant, comunicaci il motivo nel tuo feedback.

Funzionalità esclusive

Le funzionalità future verranno visualizzate solo nell'API Merchant. (Ci saranno alcune eccezioni, come la specifica dei feed annuale del 2025).

Le funzionalità esclusive dell'API Merchant includono:

  • Reviews API. Utilizza Recensioni per implementare e gestire le valutazioni dei tuoi prodotti e del tuo negozio. Per saperne di più, consulta Recensione del venditore e Recensione prodotto.
  • Notifiche: registrati per ricevere notifiche push relative alle modifiche ai dati dell'account e ai dati di prodotto.

Prezzo

Ecco cosa è cambiato per Price nel pacchetto Merchant Common:

API Content per Shopping API Merchant
Campo Importo value:string amountMicros:int64
Campo Valuta currency:string currencyCode:string

L'importo Price viene ora registrato in micro, dove 1 milione di micro equivale all'unità standard della tua valuta.

Nell'API Content for Shopping, Price era un numero decimale sotto forma di stringa.

Il nome del campo dell'importo è cambiato da value a amountMicros

Il nome del campo della valuta è cambiato da currency a currencyCode. Il formato continua a essere ISO 4217.

Ultimi aggiornamenti e annunci

Per aggiornamenti più granulari, consulta le note di rilascio specifiche per ogni API secondaria. Per aggiornamenti aggregati più regolari dell'API Merchant, consulta i nostri ultimi aggiornamenti.

Per dettagli più specifici e per saperne di più sull'API Merchant, consulta la panoramica del nostro sito per sviluppatori e la guida alla migrazione generale.

Per informazioni dettagliate sull'API Merchant e sulle relative API secondarie, consulta la sezione Progettazione dell'API Merchant.

Indietro
Manage and transition Google Cloud projects
Avanti
Start your migration