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

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

Puoi utilizzare questa guida per eseguire la migrazione dell'implementazione esistente dell'API Content for Shopping all'API Merchant. Per ulteriori informazioni sui dettagli dell'API Merchant e delle relative sotto-API, consulta la pagina dedicata alla progettazione dell'API Merchant.

Inizia

Per iniziare a utilizzare l'API Merchant, modifica gli URL delle richieste 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 indicato di seguito:

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 dell'account
  • Gestione automatizzata dei prodotti
  • Gestione automatizzata dell'inventario
  • Report personalizzati

Aree di miglioramento principali:

Che cosa è cambiato:

  • Il valore massimo di pageSize è aumentato da 250 a 1000 righe per chiamata API.
  • È stato risolto un ritardo che si verificava per l'inserimento di prodotti, promozioni, recensioni prodotto e recensioni dei commercianti dopo DataSources la creazione è stato risolto.
  • È stata lanciata una definizione aggiornata di clickPotentialRank nella productView tabella nella sotto-API Reporting:
    • La classificazione dei prodotti in base a clickPotential è normalizzata a valori compresi tra 1 e 1000.
  • Il AccountIdAlias nella risorsa AccountRelationship consente di gestire meglio le strutture di account complesse. Ad esempio, i marketplace utilizzano un alias definito dall'utente anziché l'ID interno del commerciante, ad esempio 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 Merchant Inventories insieme all'implementazione esistente di API Content for Shopping v2.1 products. Potresti utilizzare l'API Content for Shopping per caricare un nuovo prodotto locale (che vendi in un negozio locale), quindi utilizzare la risorsa LocalInventory dell'API Merchant Inventories per gestire le informazioni in negozio per quel prodotto.

Miglioramenti rispetto all'API Content

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

Esaminiamo queste modifiche in modo più dettagliato.

Controllo delle versioni e sotto-API

L'API Merchant introduce i concetti di gestione delle versioni e sotto-API. Il suo design modulare migliora la facilità d'uso, consentendoti di concentrarti sulle sotto-API di cui hai bisogno e di semplificare le migrazioni future alle versioni più recenti. La gestione delle versioni verrà applicata agli URL delle richieste . La strategia è simile all'esperienza dell'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 Identificatori di account e prodotti ed esempi.

Principi AIP per gli identificatori

Mentre l'API Content for Shopping utilizza gli ID per identificare le risorse (ad esempio, merchantId, productId), l'API Merchant utilizza un name identificatore per allinearsi all'AIP (vedi Principi di miglioramento delle API).

L'identificatore {name} include l'identificatore della risorsa e il relativo padre (o potenzialmente più padri), 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 della raccolta accounts/ e products/.

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

Ad esempio, implementa un metodo getName() per recuperare il name da una risorsa e memorizza l'output come variabile anziché creare il name dagli ID del commerciante e della 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 for Shopping API Merchant
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/{name}

Per ulteriori dettagli, consulta Modifiche degli identificatori.

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

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

dove {name} è uguale a accounts/4321/products/en~US~1234. Questo nuovo campo name 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, la tilde (~) svolge questa funzione. 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 secondarie

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

Ad esempio, per elencare gli inventari locali per un determinato prodotto, specifica il prodotto name nel parent campo per il list metodo. In questo caso, il product specificato è il parent delle 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 sarebbe

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

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

Enum comuni

L'utilizzo di enum comuni offre maggiore coerenza.

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

Il campo ReportingContext.ReportingContextEnum rappresenta il contesto a cui si applicano i problemi relativi all'account e al prodotto. Questo campo viene utilizzato nei metodi di generazione di report (ad esempio, per IssueSeverityPerReportingContext).

Compatibilità con le versioni precedenti

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

Una volta eseguita la migrazione delle sotto-API all'API Merchant, ti consigliamo di utilizzare solo l'API Merchant per le sotto-API migrate.

Disponibilità della chiamata di procedura remota (gRPC)

gRPC è il nuovo modo consigliato per integrarsi con l'API Merchant.

I vantaggi includono:

Il batching personalizzato diventa batching integrato

Il batching funziona in modo più efficiente quando utilizzi le chiamate asincrone. Scopri di più sull'utilizzo delle chiamate parallele per ottenere il batching nell'API Merchant e su come eseguire il refactoring del codice per le richieste in parallelo.

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

L'API Merchant non supporta il customBatch metodo presente nell'API Content for Shopping. In alternativa, consulta Inviare più richieste contemporaneamente o eseguire le chiamate in modo asincrono.

Il seguente esempio Java mostra come inserire un input di 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.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);
  }
}
InsertProductInputAsyncSample.java

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

Funzionalità esclusive

Le funzionalità future verranno visualizzate solo nell'API Merchant. (Ci saranno alcune eccezioni, ad esempio le specifiche dei feed annuali del 2025.)

Le funzionalità esclusive dell'API Merchant includono

  • API delle recensioni. Utilizza le recensioni per implementare e gestire le valutazioni dei prodotti e dei negozi. Per saperne di più, consulta Recensione del venditore e Recensione prodotto.
  • Notifiche: registrati per ricevere notifiche push per le modifiche ai dati di prodotto di un account.

Prezzo

Ecco cosa è cambiato per Price nel pacchetto Merchant Common:

API Content for Shopping API Merchant
Campo dell'importo value:string amountMicros:int64
Campo della valuta currency:string currencyCode:string

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

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

Il nome del campo dell'importo è stato modificato da value a amountMicros.

Il nome del campo della valuta è stato modificato 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 sotto-API. 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 generale alla migrazione per maggiori dettagli.

Per dettagli sull'API Merchant e sulle relative sotto-API, consulta la pagina dedicata alla progettazione dell'API Merchant.

Indietro
Design
Avanti
Migrate accountstatuses to Account Issues