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

Com a API Merchant, é possível automatizar e simplificar fluxos de trabalho no Merchant Center, além de oferecer 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 do produto e de comerciantes após a criação de DataSources.
  • Lançamento de uma definição atualizada para clickPotentialRank na tabela productView em Sub-API de relatórios:
    • A classificação dos produtos com base em clickPotential é normalizada para valores entre 1 e 1.000.
  • 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, é possível usar a API Merchant Inventories com sua implementação atual da API Content for 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ão e sub-APIs. O design modular melhora a facilidade de uso, permitindo que você se concentre nas sub-APIs necessárias e facilitando futuras migrações para versões mais recentes. O controle de versão será aplicado com os 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 do 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 vários pais em potencial), de modo que {name} é 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, um 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 pai é accounts/{account}/products/{product}. Note que neste caso o recurso localInventories tem dois pais incluídos no identificador de nome (accounts/ e products/), já que a conta é o pai do recurso de produto.

Enums comuns

O uso de enums comuns oferece mais consistência.

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

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

Compatibilidade com versões anteriores

À medida que você começa a usar a API Merchant, sua integração atual da API Content for 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 melhor 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 é compatível com o método customBatch destacado na API Content for Shopping. Em vez disso, consulte Enviar várias solicitações de uma só vez ou execute suas chamadas de forma assíncrona.

O exemplo em 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.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 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 de 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 e informações sobre a API Merchant, consulte a visão geral do site para desenvolvedores e o guia de migração geral.

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

Avançar
Start your migration