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 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, conforme mostrado abaixo:
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 de produtos automático
- Gerenciamento de inventário automático
- Relatórios personalizados
Principais áreas de melhoria:
- Sub-APIs com novos recursos, incluindo:
- O acompanhamento de pedidos oferece o histórico de acompanhamento de pedidos comerciais para fornecer estimativas de frete precisas e exatas aos clientes. Os indicadores também permitem listagens aprimoradas com frete grátis e rápido shipping.
- A resolução de problemas oferece acesso ao conteúdo de diagnóstico e às ações de suporte da mesma forma que está disponível na interface do Merchant Center.
- O Product Studio (ALPHA) usa a IA generativa para gerar e otimizar títulos e descrições de produtos. Você precisa assinar este formulário para solicitar acesso.
- Novos recursos na Accounts sub-API.
OmnichannelSettingsgerencia a configuração da conta para veiculação omnichannel, como listagens locais sem custo financeiro (LLG) e anúncios de inventário local (AIL).LfpProvidersse conecta a parceiros do programa de parceria de feeds locais (LFP, na sigla em inglês) para dados de inventário.GbpAccountsse conecta à conta do Perfil da Empresa no Google para dados de lojas locais.OnlineReturnPolicyoferece a capacidade de criar, excluir e atualizar suas políticas on-line.
- Novos métodos para inventário, dados de produtos e outras APIs, incluindo:
- Um novo método na Products sub-API.
ProductsUpdatepermite atualizar produtos individuais sem a necessidade de fornecer todos os campos obrigatórios paraProductInput.
- A capacidade de criar não apenas fontes de dados principais, mas várias fontes de dados, como:
- Introduz o upload de avaliações do produto e avaliações de comerciantes
- Com a API Merchant, você pode ativar notificações de mudanças nos dados da conta
O que mudou:
- O
pageSizemáximo aumentou de 250 para 1.000 linhas por chamada de API. - Um atraso que existia para inserção de produtos, promoções, avaliações do produto e avaliações de comerciantes após
DataSourcescriação foi corrigido. - Lançamento de uma definição atualizada para
clickPotentialRanknaproductViewtabela na sub-API Reporting:- A classificação de produtos com base em
clickPotentialé normalizada para valores entre 1 e 1.000.
- A classificação de produtos com base em
- O
AccountIdAliasno recursoAccountRelationshippermite 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 projetada para funcionar com os recursos da API Content for Shopping.
Por exemplo, você pode usar a API Merchant Inventories com sua implementação da API Content for Shopping v2.1
products. Você pode usar a API Content for Shopping para fazer o upload de um novo produto disponível na loja física (que você vende em uma loja física) e, em seguida, 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 melhora a API Content nas seguintes áreas:
- Sub-APIs com novos recursos para sua integração exclusiva
- Novos métodos para inventário, dados de produtos e outras APIs
- A capacidade de criar não apenas fontes de dados principais, mas várias fontes de dados, como:
- Introduz o upload de avaliações do produto e avaliações de comerciantes
- Com a API Merchant, você pode ativar notificações de mudanças nos dados da conta.
- Introduz a capacidade de filtragem para o recurso Accounts
Considere essas mudanças com mais detalhes.
Controle de versões e sub-APIs
A API Merchant introduz os conceitos de controle de versões e sub-APís. 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ões será aplicado aos 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 contas e produtos e exemplos.
Princípios de AIP para identificadores
Enquanto a API Content for Shopping usa IDs para identificar recursos (por exemplo,
merchantId, productId), a API Merchant usa um
name
identificador para se alinhar ao AIP (consulte
Princípios de melhoria da API).
O identificador {name} inclui o identificador do recurso e o pai (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 recuperar o name de um recurso e armazene a saída como uma variável em vez de construir o name dos IDs do comerciante e do recurso.
Confira um exemplo de como usar o campo name nas 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 identificadores.
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 (:) denotam um delimitador no nome do produto, enquanto na API Merchant, um til (~) executa 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 se torna o seguinte:
contentLanguage~feedLabel~offerId.
Campos pai para recursos filhos
Na API Merchant, todos os recursos filhos têm o
parent
campo. Você pode usar o campo parent para especificar o {name} do recurso em que o filho será inserido, em vez de transmitir todo o recurso pai. Você também pode usar o campo parent com
list
Por exemplo, para listar inventários locais de um determinado produto, especifique o
produto name no
parent
campo para o
list
método. Nesse caso, o product fornecido é o parent dos
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}. Nesse caso
o
localInventories
recurso tem dois pais incluídos no identificador de nome (accounts/ e
products/), já que a conta é o pai do recurso 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 a segmentação de destino e é
unificado em todas as sub-APIs, por exemplo, para atributos
de promoções.
O campo
ReportingContext.ReportingContextEnum
representa o contexto a que os problemas da conta e do produto se aplicam.
Esse campo é usado em métodos de relatórios (por exemplo, para
IssueSeverityPerReportingContext).
Compatibilidade com versões anteriores
Ao começar a usar a API Merchant, sua integração da API Content for Shopping vai continuar funcionando sem interrupção. Para mais informações, consulte Compatibilidade.
Depois de migrar suas sub-APIs para a API Merchant, recomendamos usar apenas a API Merchant para as sub-APIs migradas.
Disponibilidade de chamada de procedimento remoto (gRPC)
gRPC é a nova maneira recomendada de fazer a integração com a API Merchant.
As vantagens incluem:
- Independência de linguagem
- Depende de buffers de protocolo
Usa HTTP/2 para fornecer soluções escalonáveis de alto desempenho (referência de RPC)
Se você usar nossas bibliotecas de cliente ou exemplos de código, o gRPC será o mecanismo de transporte padrão.
Para mais informações sobre o gRPC, consulte:
O lote personalizado se torna um lote integrado
O lote é executado com mais eficiência quando você usa chamadas assíncronas. Saiba mais sobre como usar chamadas paralelas para realizar o lote 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
customBatch
método apresentado na API Content for Shopping. Em vez disso, consulte Enviar várias
solicitações de uma vez ou executar 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.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);
}
}
Se você usa
customBatch na
API Content e precisa desse recurso para a API Merchant, informe o motivo no seu
feedback.
Recursos exclusivos
Os recursos futuros vão aparecer apenas na API Merchant. Haverá 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 do produto de uma conta.
Preço
Confira o que mudou para Price no pacote comum do comerciante:
| API Content for Shopping | API Merchant | |
|---|---|---|
| Campo do valor | value:string |
amountMicros:int64 |
| Campo da moeda | currency:string
|
currencyCode:string |
O valor de Price agora é registrado em micros, em que 1 milhão de micros equivale à 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 de 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 da API Merchant, consulte nossas atualizações mais recentes.
Para mais detalhes específicos e para saber mais sobre a API Merchant, consulte a visão geral do site para desenvolvedores e o guia de migração geral para mais detalhes.
Consulte Design da API Merchant para detalhes sobre a API Merchant e as sub-APIs.