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 dell'implementazione esistente dell'API Content for Shopping all'API Merchant. Per ulteriori informazioni 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 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 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 dell'account
  • Gestione automatizzata dei prodotti
  • Gestione automatica dell'inventario
  • Rapporti personalizzati

Aree di miglioramento principali:

Che cosa è cambiato:

  • Il valore massimo di pageSize è stato aumentato da 250 a 1000 righe per chiamata API.
  • È stato risolto un ritardo esistente per l'inserimento di prodotti, promozioni, recensioni di prodotti e recensioni del commerciante dopo la creazione di DataSources.

Novità in arrivo:

  • Lancio di una definizione aggiornata per clickPotentialRank nella tabella productView nella sub-API Reporting: * La classificazione dei prodotti in base a clickPotential è normalizzata a valori compresi tra 1 e 1000.
    • I prodotti con un valore di clickPotentialRank basso hanno comunque il potenziale di clic più elevato tra i prodotti del commerciante che soddisfano le condizioni della query di ricerca. Si tratta di una modifica non distruttiva che potrebbe essere lanciata il 1° luglio 2025.
  • AccountIdAlias nella risorsa AccountRelationship consente di gestire meglio le strutture degli 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 ulteriori informazioni, 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 Content API 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 API Merchant Inventories LocalInventory per gestire le informazioni in negozio per quel prodotto.

Miglioramenti rispetto all'API Content

L'API Merchant migliora l'API Content nei seguenti ambiti:

Esaminiamo queste modifiche più nel dettaglio.

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 future migrazioni alle versioni più recenti. Il controllo delle versioni verrà applicato con gli 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. Ciò include la risorsa, la versione, il nome (identificatori) e il metodo (metodi non standard). Per saperne di più, consulta Identificatori di account e prodotto 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 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 della 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 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 all'identificatore.

Come altro esempio, il recupero di un prodotto con l'identificatore en~US~1234 dall'ID Merchant Center 4321 utilizzando l'API Merchant avrebbe il seguente aspetto:

    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 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 svolta da una tilde (~). L'identificatore dell'API Merchant non contiene la parte channel.

Ad esempio, 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 campo parent. Puoi utilizzare il campo parent per specificare il {name} della risorsa in cui inserire la risorsa secondaria, anziché trasmettere l'intera risorsa principale. Puoi anche utilizzare il campo parent con list.

Ad esempio, per elencare gli inventari locali di un determinato prodotto, specifica l'name del prodotto nel campo parent per il metodo list. In questo caso, il product specificato è il 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 a questa:

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

L'elemento principale è 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/), in quanto l'account è l'elemento principale della risorsa prodotto.

Enumerazioni comuni

L'utilizzo di enumerazioni comuni garantisce una maggiore coerenza.

Il campo Destination.DestinationEnum specifica le piattaforme su cui visualizzare le risorse. DestinationEnum elenca tutti i valori disponibili per il targeting della destinazione ed è unificato in tutte 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, 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 API secondarie all'API Merchant, ti consigliamo di utilizzare solo l'API Merchant per le API secondarie di cui è stata eseguita la migrazione.

Disponibilità della chiamata di procedura remota (gRPC)

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

I suoi vantaggi includono:

Il batch personalizzato diventa batch integrato

Il batching è più efficiente quando utilizzi chiamate asincrone. Scopri di più sull'utilizzo di chiamate parallele per ottenere il batching nell'API Merchant e su come refactoring del codice per richieste simultanee.

Per velocizzare la migrazione, ti consigliamo le librerie client.

L'API Merchant non supporta il metodo customBatch presente nella Content API for Shopping. In alternativa, consulta Inviare più richieste contemporaneamente o esegui 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.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
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("in stock")
            .setCondition("new")
            .setGoogleProductCategory("Media > Books")
            .addGtins("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setChannel(ChannelEnum.ONLINE)
        .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 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

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, come le specifiche del feed annuale 2025.

Le funzionalità esclusive dell'API Merchant includono

  • API Reviews. Utilizza le recensioni per implementare e gestire le valutazioni dei prodotti e del negozio. Per ulteriori informazioni, consulta Recensione del venditore e Recensione del prodotto.
  • Notifiche: iscriviti 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 per Shopping API Merchant
Campo Importo value:string amountMicros:int64
Campo Valuta currency:string currencyCode:string

L'importo Price 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 Importo è cambiato da value a amountMicros

Il nome del campo 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 più regolari e aggregati dell'API Merchant, consulta i nostri ultimi aggiornamenti.

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

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

Indietro
Quickstart
Avanti
Migrate accountstatuses to Account Issues