Produtos de migração

A API Merchant apresenta uma maneira mais robusta e intuitiva de gerenciar os dados de produtos. A principal mudança é a separação dos dados do produto em dois recursos distintos: ProductInput para enviar seus dados e Product para visualizar a versão final processada, incluindo o status e os problemas do produto. Essa nova estrutura oferece uma experiência mais previsível e transparente.

Este guia mostra as principais diferenças para ajudar você a migrar sua integração da API Content for Shopping. Para um guia detalhado sobre como usar os novos recursos, consulte Gerenciar seus produtos.

principais diferenças

Confira as mudanças mais significativas na forma de gerenciar produtos na API Merchant em comparação com a API Content for Shopping:

• Recursos dedicados para dados de entrada e processados: a API Merchant divide o gerenciamento de produtos em dois recursos. Use o recurso ProductInput para inserir, atualizar e excluir os dados do produto. Use o recurso somente leitura Product para conferir o produto final depois que o Google processar suas entradas, aplicar regras e combinar dados de fontes complementares.

• Codificação para nomes de produtos: é possível usar a codificação base64url sem preenchimento (RFC 4648, seção 5) para os campos ProductInput.name e Product.name. Se os nomes dos produtos tiverem caracteres usados pela API Merchant ou reservados para URLs, a codificação será obrigatória. Por exemplo, é necessário codificar os nomes dos produtos se eles contiverem algum dos seguintes caracteres:

  % . + / : ~ , ( * ! ) & ? = @ # $
  

• Status do produto integrado: o serviço productstatuses foi removido. Os problemas de validação de produtos e os status de destino agora estão incluídos diretamente no recurso Product no campo productStatus, simplificando a recuperação de dados.

• Atualizações de produtos previsíveis: o novo método productInputs.patch modifica diretamente uma entrada de produto específica. Essa é uma melhoria significativa em relação à API Content for Shopping, em que as atualizações podiam ser substituídas inesperadamente por outros uploads de feed. Na API Merchant, uma atualização permanece até que essa entrada de produto específica seja atualizada novamente ou excluída. As atualizações de produtos são aplicadas ao recurso ProductInput, em vez do recurso Product processado.

• Escolha sua fonte de dados para um gerenciamento de dados mais limpo: todas as operações de gravação do productInputs agora exigem um parâmetro de consulta dataSource, deixando explícito qual fonte de dados você está modificando. Isso é especialmente útil se você tiver várias fontes que fornecem dados.

• Novos identificadores de recursos: agora os produtos são identificados por um recurso RESTful name em vez do campo id. O formato é accounts/{account}/products/{product}.

• Sem lotes personalizados: o método custombatch não está mais disponível. É possível usar solicitações assíncronas ou lotes HTTP para enviar várias solicitações em uma única chamada HTTP.

Diretrizes para fontes de dados durante a migração

Antes de migrar suas fontes de dados, recomendamos que você escolha sua estratégia de fonte de dados.

Para garantir uma migração tranquila e evitar problemas como o roubo de ofertas, siga estas recomendações:

• Preencher o banco de dados: em vez de chamar dataSources.list antes de cada operação de produto, recomendamos que você faça um preenchimento único do banco de dados local. Adicione um campo de nome dataSource a cada registro de produto para fornecer o identificador correto diretamente nas suas solicitações.

• Consolidar e usar fontes de dados para qualquer rótulo e idioma: com a API Merchant, é possível criar uma fonte de dados sem especificar rótulo e idioma e, portanto, inserir produtos com qualquer rótulo de fonte de dados e idioma. Considere usar uma única fonte de dados para qualquer rótulo e idioma.

• Proteja seus produtos: se você usa regras de fonte de dados, chame products.get para encontrar o dataSource exato associado a um produto antes de atualizá-lo ou excluí-lo. Isso garante que você está modificando a origem pretendida e evita o roubo acidental de ofertas.

Solicitações

Nesta seção, comparamos os formatos de solicitação da API Content for Shopping e da API Merchant.

Descrição da solicitação	API Content for Shopping	API Merchant
Receber um produto	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Listar produtos	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Inserir um produto	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert
Atualizar um produto	PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Excluir um produto	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Receber o status do produto	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Listar status dos produtos	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Agrupar várias solicitações em lote	POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch	Usar solicitações assíncronas ou lotes HTTP

Identificadores

O formato dos identificadores de produtos mudou na API Merchant para um nome de recurso REST padrão.

Descrição do identificador	API Content for Shopping	API Merchant
ID do produto	Uma string composta por segmentos separados por dois pontos (:). Formato: channel:contentLanguage:targetCountry:offerId ou channel:contentLanguage:feedLabel:offerId. Exemplo: online:en:US:sku123	Uma string name de recurso REST. Formato: accounts/{account}/products/{product}, em que {product} é contentLanguage~feedLabel~offerId. Exemplo: accounts/12345/products/en~US~sku123. Codificação: codificação base64url sem padding recomendada e obrigatória no caso de IDs de produtos que contêm caracteres usados pela API Merchant ou caracteres reservados para URL.

Métodos

Esta tabela mostra os métodos da API Content for Shopping e os equivalentes na API Merchant.

Método da API Content for Shopping	Método da API Merchant	Disponibilidade e observações
products.get	products.get	Recupera o produto final processado.
products.list	products.list	Lista os produtos finais processados.
products.insert	productInputs.insert	Insere uma entrada de produto. Requer um dataSource.
products.update	productInputs.patch	O comportamento é significativamente diferente. Ela atualiza uma entrada de produto específica e é persistente.
products.delete	productInputs.delete	Exclui uma entrada de produto específica. Requer um dataSource.
products.custombatch	Indisponível	Use solicitações assíncronas ou lotes HTTP.
productstatuses.get	products.get	O serviço productstatuses é removido. As informações de status agora fazem parte do recurso Product.
productstatuses.list	products.list	O serviço productstatuses é removido. As informações de status agora fazem parte do recurso Product.
productstatuses.custombatch	Indisponível	Use solicitações assíncronas ou lotes HTTP.

Mudanças detalhadas nos campos

Esta tabela destaca campos importantes que foram alterados, adicionados ou removidos na API Merchant.

API Content for Shopping	API Merchant	Descrição
id	name	O identificador principal de um produto agora é o recurso REST name. A codificação base64url sem preenchimento é recomendada e obrigatória no caso de nomes de produtos que contêm caracteres usados pela API Merchant ou caracteres reservados para URLs.
Atributos de especificação dos dados do produto de nível superior (por exemplo, title, price, link)	Objeto productAttributes	Atributos de produtos como title, price e link não são mais campos de nível superior. Agora eles estão agrupados no objeto productAttributes nos recursos Product e ProductInput. Isso proporciona uma estrutura de recursos mais limpa e organizada.
targetCountry	feedLabel	O nome do recurso agora usa feedLabel em vez de targetCountry para se alinhar à funcionalidade do Merchant Center.
feedId	dataSource (parâmetro de consulta)	Agora, um nome de dataSource é um parâmetro de consulta obrigatório para todos os métodos de gravação productInputs (insert, update, delete).
channel	Indisponível. Use legacy_local para produtos disponíveis apenas na loja física.	O campo channel não está mais presente na API Merchant. Os produtos com o canal LOCAL na API Content for Shopping precisam definir o campo legacy_local como verdadeiro.
Indisponível	versionNumber	Um novo campo opcional em ProductInput que pode ser usado para evitar inserções fora de ordem nas fontes de dados principais.
Campos do tipo string com um conjunto definido de valores	Campos do tipo enum com um conjunto definido de valores	Os campos nos atributos do produto com um conjunto definido de valores (por exemplo, excluded_destinations, availability) agora são do tipo enum.