Migrar da API Content for Shopping para a API Merchant

Este guia explica o processo de migração da API Content for Shopping para a API Merchant para gerenciamento de dados comerciais.

Use este guia para migrar sua implementação atual da API Content for Shopping para a API Merchant. Para mais informações sobre os detalhes da API Merchant e das sub-APIs, consulte Design da API Merchant.

Primeiros passos

Para começar a usar a API Merchant, mude os URLs de solicitação para o seguinte formato:

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

Para usar a API Merchant, vincule sua conta do Merchant Center e seu projeto do Google Cloud usando o método de registro de desenvolvedor, da seguinte forma:

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

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

Para mais informações, consulte o guia de início rápido e a referência da API Merchant.

Melhorias em relação à API Content for Shopping

A API Merchant permite automatizar e simplificar fluxos de trabalho no Merchant Center e oferece recursos aprimorados em relação à API Content for Shopping.

Principais casos de uso:

  • gerenciamento de contas automático
  • Gerenciamento automatizado de produtos
  • Gerenciamento automatizado de inventário
  • Relatórios personalizados

Principais áreas de melhoria:

O que mudou:

  • O pageSize máximo aumentou de 250 para 1.000 linhas por chamada de API.
  • Foi corrigido um atraso que existia para inserção de produtos, promoções, avaliações de produtos e avaliações de comerciantes após a criação de DataSources.

O que vem por aí:

  • Lançamento de uma definição atualizada para clickPotentialRank na tabela productView na sub-API Reporting: * O ranking de produtos com base em clickPotential é normalizado para valores entre 1 e 1.000.
    • Os produtos com clickPotentialRank baixo ainda têm o maior potencial de cliques entre os produtos da loja que atendem às condições da consulta de pesquisa. Essa é uma mudança não destrutiva que pode ser lançada em 1º de julho de 2025.
  • O AccountIdAlias no recurso AccountRelationship permite gerenciar melhor estruturas de contas complexas. Por exemplo, os marketplaces usam um alias definido pelo usuário em vez do ID interno do comerciante, como o ID da conta.

Suporte ao gRPC

A API Merchant oferece suporte a gRPC e REST. Você pode usar o gRPC para a API Merchant e o REST para a API Content for Shopping ao mesmo tempo.

As bibliotecas de cliente da API Merchant exigem o gRPC.

Para mais informações, consulte Visão geral do gRPC.

Compatibilidade

Este guia descreve as mudanças gerais que se aplicam a toda a API Merchant.

A API Merchant foi criada para funcionar com os recursos atuais da API Content for Shopping.

Por exemplo, você pode usar a API Merchant Inventories com sua implementação atual da API Content para Shopping v2.1 products. Você pode usar a API Content for Shopping para fazer upload de um novo produto local (que você vende em uma loja física) e usar o recurso LocalInventory da API Merchant Inventories para gerenciar as informações na loja desse produto.

Melhorias em relação à API Content

A API Merchant é melhor que a API Content nas seguintes áreas:

Considere essas mudanças com mais detalhes.

Controle de versões e sub-APIs

A API Merchant apresenta os conceitos de controle de versões e sub-APIs. O design modular melhora a facilidade de uso, permitindo que você se concentre nas sub-APIs necessárias e facilitando migrações futuras para versões mais recentes. O controle de versões será aplicado com seus URLs de solicitação.A estratégia é semelhante à experiência da API Google Ads.

Solicitações mais robustas

As solicitações de URL da API Merchant exigem mais parâmetros para chamar a API Merchant. Isso inclui o recurso, a versão, o nome (identificadores) e o método (métodos não padrão). Para mais informações, consulte Identificadores de conta e produto e exemplos.

Princípios da AIP para identificadores

Enquanto a API Content for Shopping usa IDs para identificar recursos (por exemplo, merchantId, productId), a API Merchant usa um identificador name para se alinhar com a AIP (consulte Princípios de melhoria da API).

O identificador {name} inclui o identificador do recurso e o pai dele (ou potencialmente vários pais), de modo que {name} seja igual a accounts/{account}/products/{product}.

Todas as chamadas de leitura e gravação retornam o campo name como o identificador do recurso.

{name} também inclui os identificadores de coleção accounts/ e products/.

A API Merchant usa {account} para se referir a um ID do Merchant Center e {product} para se referir a identificadores de produtos.

Por exemplo, implemente um método getName() para extrair o name de um recurso e armazene a saída como uma variável em vez de construir o name usando os IDs do comerciante e do recurso.

Confira um exemplo de como usar o campo name nas suas chamadas:

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

A tabela mostra como a solicitação products.get da API Content for Shopping muda:

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}

Para mais detalhes, consulte Mudanças de identificador.

Como outro exemplo, a recuperação de um produto com o identificador en~US~1234 do ID do Merchant Center 4321 usando a API Merchant seria assim:

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

em que {name} é igual a accounts/4321/products/en~US~1234. Esse novo campo de nome é retornado como o identificador de recurso para todas as chamadas de leitura e gravação na API Merchant.

Na API Content for Shopping, dois pontos (:) indicam um delimitador no nome do produto. Já na API Merchant, uma til (~) realiza essa função. O identificador da API Merchant não contém a parte channel.

Por exemplo, ID do produto na API Content for Shopping:

channel:contentLanguage:feedLabel:offerId.

na API Merchant passa a ser:

contentLanguage~feedLabel~offerId.

Campos principais para recursos filhos

Na API Merchant, todos os recursos filhos têm o campo parent. É possível usar o campo parent para especificar o {name} do recurso em que o filho será inserido, em vez de transmitir todo o recurso pai. Também é possível usar o campo parent com list

Por exemplo, para listar inventários locais de um determinado produto, especifique o name do produto no campo parent do método list. Nesse caso, o product fornecido é o parent dos recursos LocalInventory retornados.

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

Para recuperar todos os inventários locais do produto en~US~1234' e da conta 4321, a solicitação seria assim:

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

O elemento pai é accounts/{account}/products/{product}. Neste caso, o recurso localInventories tem dois recursos principais incluídos no identificador de nome (accounts/ e products/), já que a conta é o recurso principal do produto.

Enums comuns

O uso de enums comuns oferece mais consistência.

O campo Destination.DestinationEnum especifica as plataformas em que os recursos serão exibidos. DestinationEnum lista todos os valores disponíveis para segmentação por destino e é unificado em todas as sub-APIs, por exemplo, para atributos de promoções.

O campo ReportingContext.ReportingContextEnum representa o contexto em que os problemas da conta e do produto se aplicam. Esse campo é usado em todos os métodos de geração de relatórios (por exemplo, para IssueSeverityPerReportingContext).

Compatibilidade com versões anteriores

Ao começar a usar a API Merchant, sua integração atual da API Content para o Shopping continua funcionando sem interrupções. Para mais informações, consulte Compatibilidade.

Depois de migrar suas sub-APIs para a API Merchant, recomendamos que você use apenas a API Merchant para as sub-APIs migradas.

Disponibilidade de chamada de procedimento remoto (gRPC)

O gRPC é a nova maneira recomendada de integrar com a API Merchant.

As vantagens incluem:

O agrupamento personalizado se torna agrupamento integrado

O processamento em lote funciona de maneira mais eficiente quando você usa chamadas assíncronas. Saiba mais sobre como usar chamadas paralelas para alcançar o agrupamento em lotes na API Merchant e como refatorar o código para solicitações simultâneas.

Para acelerar a migração, recomendamos as bibliotecas de cliente.

A API Merchant não oferece suporte ao método customBatch apresentado na API Content for Shopping. Em vez disso, consulte Enviar várias solicitações de uma vez ou execute suas chamadas de forma assíncrona.

O exemplo de Java a seguir demonstra como inserir uma entrada de produto.

   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.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 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 você usa customBatch na API Content e precisa desse recurso na API Merchant, informe o motivo no seu feedback.

Recursos exclusivos

Os recursos futuros vão aparecer apenas na API Merchant. Há algumas exceções, como a especificação anual do feed de 2025.

Os recursos exclusivos da API Merchant incluem:

  • API Reviews. Use as avaliações para implementar e gerenciar as classificações de produtos e lojas. Para mais informações, consulte Avaliação do vendedor e Avaliação do produto.
  • Notificações: inscreva-se para receber notificações push sobre mudanças nos dados de produtos de uma conta.

Preço

Confira o que mudou para Price no pacote Merchant Common:

API Content for Shopping API Merchant
Campo de valor value:string amountMicros:int64
Campo de moeda currency:string currencyCode:string

O valor Price agora é registrado em micros, em que 1 milhão de micros é equivalente à unidade padrão da sua moeda.

Na API Content for Shopping, Price era um número decimal na forma de uma string.

O nome do campo "Valor" mudou de value para amountMicros

O nome do campo de moeda mudou de currency para currencyCode. O formato continua sendo ISO 4217.

Atualizações e anúncios mais recentes

Para atualizações mais detalhadas, consulte as notas da versão específicas de cada sub-API. Para atualizações mais regulares e agregadas da API Merchant, consulte nossas atualizações mais recentes.

Para mais detalhes específicos e informações sobre a API Merchant, consulte a visão geral do site para desenvolvedores e o guia geral de migração.

Consulte Design da API Merchant para detalhes sobre a API Merchant e as sub-APIs.

Anterior
Quickstart
Avançar
Migrate accountstatuses to Account Issues