Escolher entre feeds de arquivos e a API Merchant

É possível fazer upload de dados de produtos para o Merchant Center usando feeds baseados em arquivos, a API Merchant ou uma combinação de ambos:

  • Feeds de produtos baseados em arquivos: faça upload de arquivos CSV, TSV ou XML usando SFTP, Google Cloud Storage, Planilhas Google ou buscas programadas.
  • API Merchant: envie solicitações programáticas diretamente do seu back-end para atualizações incrementais à medida que os dados do produto mudam, além de sincronizações periódicas do catálogo completo.

Este guia compara as duas abordagens, explica quando usar uma em vez da outra (ou as duas juntas) e fornece um manual de migração detalhado se você decidir mover alguns ou todos os seus produtos de feeds de arquivos para a API.

Escolher sua abordagem de fonte de dados

Avalie a volatilidade do catálogo, a arquitetura de back-end e os fluxos de trabalho operacionais para decidir se você vai usar a API Merchant, os feeds de arquivos ou uma configuração híbrida.

Quando usar a API Merchant

Use uma fonte de dados principal de API se:

  • Integração programática direta: você prefere chamar uma API diretamente do back-end em vez de gerar arquivos e gerenciar pipelines de transferência de arquivos (como SFTP ou Google Cloud Storage).
  • Alta volatilidade de preços e inventário: os preços ou níveis de estoque dos seus produtos mudam com frequência ao longo do dia.
  • Atualizações imediatas quando os dados mudam: você quer enviar as mudanças de produtos para o Google assim que elas acontecem no seu back-end, em vez de esperar pela próxima geração de arquivo e upload programados.
  • Atualizações incrementais do catálogo: você quer inserir, atualizar ou excluir produtos individuais conforme eles mudam, sem precisar reenviar todo o catálogo todas as vezes.
  • Atualizações parciais de atributos: você quer atualizar campos específicos de um produto (como price ou availability usando productInputs.patch) sem reenviar o payload completo do produto.

Quando usar feeds de arquivos

Use uma fonte de dados principal baseada em arquivos se:

  • Catálogo estático: os dados do produto mudam com pouca frequência (por exemplo, uma vez por dia ou menos).
  • Back-end somente de snapshot sem rastreamento delta: seu back-end exporta apenas snapshots de catálogo completos e não pode rastrear mudanças no nível do item ou exclusões explícitas de produtos.
  • Fluxos de trabalho baseados em planilhas: as equipes que não são de engenharia selecionam ou substituem dados de produtos diretamente no Google Planilhas ou em arquivos CSV.
  • Operações de baixa manutenção: você prefere uma exportação de arquivos programada em que o Merchant Center lida com a busca e o processamento de snapshots, em vez de operar uma integração de API com ritmo de solicitação, tratamento de novas tentativas e sincronizações periódicas de catálogo completo.

Quando usar ambos

É possível combinar feeds de arquivos e a API Merchant na mesma conta do Merchant Center nos seguintes cenários:

  • Catálogos de produtos particionados: use a API Merchant para produtos que mudam rapidamente (como ofertas relâmpago ou inventário de alta rotatividade) e feeds de arquivos para segmentos de catálogo estáticos ou linhas de produtos separadas. Verifique se cada produto é enviado por apenas uma fonte de dados principal (consulte Uso paralelo e propriedade da fonte de dados principal).
  • Dados principais da API com feeds complementares baseados em arquivos: você gerencia os dados principais do produto usando uma fonte de dados principal da API, enquanto equipes não técnicas ou parceiros terceirizados fornecem atributos adicionais usando feeds complementares baseados em arquivos (como arquivos do Google Planilhas ou CSV) combinados com regras de atributos ou vice-versa.
  • Migração parcial ou em fases: você faz a transição de mercados, categorias ou subcontas específicos para a API, mantendo o restante do catálogo em feeds de arquivos.

Se você decidir mover alguns ou todos os seus produtos dos feeds de arquivos para a API Merchant, siga o manual de migração detalhado.

Principais diferenças de arquitetura

Os feeds de arquivos e a API Merchant baseada em push diferem na forma como o Google processa e gerencia os dados de produtos:

Conceito Feeds de arquivos API Merchant
Modelo de integração Despejo de arquivos off-line: você exporta seu catálogo para um arquivo e o transfere usando SFTP, Google Cloud Storage, Planilhas Google ou buscas programadas. Integração programática direta: seu back-end envia solicitações diretamente para o endpoint de API.
Granularidade da mutação Processamento em massa: para modificar um item, geralmente é necessário reprocessar o arquivo inteiro. Transações granulares: é possível inserir, corrigir ou excluir apenas os produtos que mudaram.
Tempo de sincronização Sincronização em lote: as mudanças aguardam no back-end até o próximo ciclo programado de exportação e transferência de arquivos. Chamadas imediatas ou programadas: é possível enviar mudanças incrementais imediatamente conforme elas ocorrem, além de sincronizações completas periódicas.
Comportamento de exclusão Implícita (snapshot): cada arquivo é um snapshot completo. Remover uma linha do arquivo principal exclui o produto. Explícito: não há conceito de snapshot. Chame productInputs.delete para remover um produto descontinuado.
Representação de recursos Estado único: as linhas do arquivo representam a entrada bruta. Separação de dados brutos e processados: a API divide os dados em ProductInput (sua entrada bruta) e Product (o estado final processado).
Regras de atributos (feed) Aplicado às colunas de arquivos brutos na interface do Merchant Center. Compatível com a interface do Merchant Center. Obrigatório ao mesclar dados da API com arquivos complementares de terceiros. Opcional para transformações de fonte única se processadas no back-end.

Uso paralelo e propriedade da fonte de dados principal ("a última atualização vence")

Embora seja possível usar feeds de arquivos e a API na mesma conta do Merchant Center, recomendamos usar apenas um método para inserir um determinado produto.

O Merchant Center opera em um modelo de "última atualização vence". A fonte de dados principal (API ou feed de arquivos) que enviou a inserção de produto mais recente ganha a propriedade principal dos dados desse produto:

  • Quando a fonte de dados do arquivo é proprietária do produto: omitir o produto de um upload de arquivo subsequente aciona a exclusão implícita, removendo o produto do Merchant Center.
  • Quando a fonte de dados da API é proprietária do produto: omitir o produto de um upload de arquivo não tem efeito porque o feed de arquivos não é mais o proprietário do produto. Você precisa chamar accounts.productInputs.delete para removê-lo.
  • Risco de reatribuição acidental de propriedade: se um feed de arquivos atualizado for executado após um push da API e contiver o produto, a fonte de dados do arquivo vai recuperar a propriedade. As omissões subsequentes do arquivo vão excluir o produto de forma inesperada.

Para evitar exclusões inesperadas ou perda de atualizações da API, não faça atualizações simultâneas nos mesmos produtos usando as fontes de dados principais da API e do arquivo.

Principais considerações sobre a API

Entenda estes comportamentos importantes da API Merchant antes de iniciar sua implementação:

Fontes de dados flexíveis (sem idioma ou rótulo)

Ao contrário dos feeds de arquivos, que exigem que você defina um rótulo de feed de destino e um idioma específicos com antecedência, a API Merchant permite criar fontes de dados principais sem especificar um feedLabel ou contentLanguage.

  • Uploads flexíveis: permite fazer upload de produtos com qualquer combinação de idioma ou rótulo do feed para uma única fonte de dados.
  • Gerenciamento simplificado: não é necessário criar e gerenciar fontes de dados separadas para cada mercado de destino. Observação: para mais detalhes sobre como escolher uma estratégia de fonte de dados, consulte Escolher uma estratégia de fonte de dados.

Estratégia de sincronização e cotas

Ao contrário de um feed de arquivos em que você faz upload de todo o catálogo em um único lote, projete sua integração com a API Merchant em torno de atualizações incrementais e sincronizações completas em ritmo acelerado:

  • Combine atualizações incrementais com sincronizações completas periódicas: envie solicitações productInputs.insert ou productInputs.patch conforme os atributos do produto mudam no back-end. Como depender apenas de atualizações incrementais pode fazer com que seus dados fiquem dessincronizados com o tempo, também execute sincronizações completas periódicas para reconciliar seu catálogo com sua fonte de informações (que também atualiza a validade do produto de 30 dias). A frequência com que você executa uma sincronização completa depende do tamanho do catálogo e da cota de API disponível.
  • Ritmo das solicitações para respeitar as cotas da API: não chame a API para todos os seus produtos de uma só vez. Embora as mudanças incrementais possam ser enviadas conforme ocorrem, distribua as solicitações de sincronização completa de maneira uniforme ao longo do dia para não ultrapassar as cotas de chamadas de método por minuto e diárias. Para mais detalhes, consulte Cotas e limites e Fazer atualizações frequentes nos seus produtos.

Como testar sua integração

Valide sua lógica de integração em um ambiente seguro antes de passar para a produção.

Use contas de teste

Antes de fazer mudanças na produção, recomendamos executar as etapas iniciais da migração em uma conta de teste de sandbox:

  1. Crie uma conta de teste: configure uma conta de teste isolada para fazer experimentos com segurança sem afetar os anúncios ativos ou as listagens sem custo financeiro.
  2. Criar uma fonte de dados de API: pratique a criação da sua fonte de dados principal de API.
  3. Testar regras de atributos: verifique as transformações de dados e as junções de feeds complementares.
  4. Validar payloads e chaves de produto: envie produtos de amostra para verificar o uso de maiúsculas e minúsculas, a codificação e o tratamento de erros de SKUs.

Para mais detalhes, consulte Etapa 1: criar contas de teste e o guia Contas de teste.

Validar o alinhamento da chave do produto

Verifique se a chave do produto do payload programático corresponde exatamente aos SKUs do feed de arquivos. O Google identifica os produtos combinando:

  • offerId (chamado de id em feeds de arquivos, com diferenciação de maiúsculas e minúsculas)
  • contentLanguage (por exemplo, en)
  • feedLabel (por exemplo, US)

Caracteres especiais e codificação

Se os identificadores de produto tiverem caracteres como /, % ou ~, use o formato codificado (codificação base64url sem preenchimento) nas chamadas de API. Para mais informações, consulte ProductInput.name.

Controle de simultaneidade

Em uma integração em tempo real, as atualizações podem chegar fora de ordem devido à latência da rede. Para evitar que atualizações mais antigas substituam dados mais recentes, use o campo versionNumber no recurso ProductInput.

Manual de migração detalhado

Se você decidir mover alguns ou todos os seus produtos de feeds de arquivos para a API Merchant, siga este manual para fazer a transição sem perder impressões ou histórico de veiculação.

1. Ensaiar a migração em uma conta de teste

Antes de fazer mudanças na produção, crie uma conta de teste em sandbox usando o método accounts.createTestAccount (consulte o guia Contas de teste). As contas de teste oferecem um ambiente isolado em que as ofertas são aprovadas por padrão, a verificação de domínio não é necessária e os dados nunca são veiculados publicamente.

Use sua conta de teste para espelhar a configuração de produção e ensaiar a migração de ponta a ponta:

  1. Espelhe a configuração do feed de arquivos: crie uma fonte de dados principal de arquivos (e todas as fontes de dados complementares) na conta de teste e faça upload de uma amostra do arquivo de feed de produção.
  2. Crie uma fonte de dados de API de teste e regras: crie uma fonte de dados principal de API e configure as regras de atributos necessárias ou as junções de feed complementares.
  3. Teste a transferência de propriedade e o alinhamento de chaves: envie solicitações productInputs.insert para os produtos de exemplo e verifique se a fonte de dados da API assume a propriedade dos itens atuais sem criar produtos duplicados.
  4. Verifique as atualizações e exclusões: teste as atualizações parciais com productInputs.patch e as remoções com productInputs.delete, além de inspecionar os recursos resultantes com products.get.

2. Criar fontes de dados da API Products

Antes de enviar dados, crie uma fonte de dados principal do tipo API na sua conta.

Criar sua fonte de dados principal da API

Para criar uma fonte de dados que aceite pushes de API, envie uma solicitação POST para o endpoint dataSources. Para mais detalhes, consulte Criar uma fonte de dados de produtos principal.

3. Regras de transição de atributos personalizados

As regras de atributos personalizadas estão vinculadas a fontes de dados específicas e não são transferidas automaticamente da sua fonte de dados de arquivo para a nova fonte de dados da API.

A forma como você faz a transição das regras de atributo depende da finalidade delas:

  • Mesclagem de várias fontes e feeds complementares de terceiros: se você combinar dados primários da API com fontes de dados complementares externas (como arquivos de fornecedores terceirizados, planilhas de inventário ou feeds de promoções), será necessário recriar as regras de atributos na interface do Merchant Center e anexá-las à nova fonte de dados da API. O pré-processamento do lado do cliente não pode substituir regras que mesclam dados de várias fontes independentes.
  • Transformações de dados de fonte única: para limpeza de fonte única, valores padrão ou formatação de string nos dados do catálogo principal, escolha entre:
    • Transformações de back-end (recomendado): aplique transformações no seu sistema antes de chamar a API. Isso oferece maior controle programático, testes mais fáceis e depuração simplificada.
    • Regras de atributo do Merchant Center: recrie as regras de transformação para sua nova fonte de dados da API na interface do Merchant Center se quiser que o Merchant Center continue gerenciando-as automaticamente.

4. Ativar a integração da API

Ative a integração da API Products para começar a inserir, atualizar e excluir produtos na nova fonte de dados principal da API:

  • Inserir e atualizar produtos (transferência de propriedade): envie solicitações productInputs.insert e productInputs.patch da sua integração. Quando você insere um produto usando a API com a mesma chave (offerId, contentLanguage, feedLabel) de um produto de feed de arquivos, a fonte de dados da API assume a propriedade desse produto e preserva o histórico de veiculação dele. Para mais orientações, consulte Inserir um produto e Adicionar e gerenciar produtos.

  • Excluir produtos descontinuados: configure sua integração para chamar explicitamente productInputs.delete sempre que um produto for removido do catálogo.

  • Implante gradualmente: para catálogos grandes, ative a integração em uma subconta do Merchant Center ou uma fonte de dados por vez.

  • Configurar a simultaneidade: se você estiver enviando muitas solicitações, configure o cliente para processar solicitações simultâneas e gerenciar várias conexões. Consulte o guia Refatorar código para solicitações simultâneas.

5. Pausar atualizações da fonte de dados de arquivos

Depois que a integração da API estiver ativa, interrompa as atualizações de arquivos antes da próxima execução programada para que a fonte de dados de arquivos não substitua as atualizações da API:

  1. Pare de fazer upload de novos arquivos para seu local de SFTP/FTP, Google Cloud Storage ou Google Planilhas.
  2. Na interface do Merchant Center, acesse a fonte de dados do arquivo e pause a busca programada.
  3. Os produtos atuais da fonte de dados de arquivos permanecem ativos por até 30 dias até que a integração da API os insira.

6. Aguardar a conclusão da migração e verificar

Aguarde até que todos os produtos ativos sejam migrados da fonte de dados de arquivo para a fonte de dados da API. As atualizações incrementais migram os produtos conforme eles mudam, mas executar uma sincronização completa do catálogo em ritmo acelerado usando sua integração regular acelera a migração de todo o catálogo (consulte Estratégia e cotas de sincronização).

Durante essa fase:

  1. Na interface do Merchant Center, monitore as contagens de itens. Aguarde até que a contagem de fontes de dados de arquivos diminua para 0 e a contagem de fontes de dados da API corresponda ao seu catálogo ativo.
  2. Use products.get para verificar se os atributos e as regras de atributos personalizados são mesclados conforme o esperado.
  3. Monitore a ferramenta de diagnóstico da API na interface do Merchant Center para acompanhar as taxas de erro e o desempenho da API.

7. Desativar a fonte de dados de arquivos

Depois que a transição for concluída e a contagem de itens do feed de arquivos for 0:

  1. Confirme se as atualizações estão sendo refletidas em tempo real.
  2. Exclua a fonte de dados de arquivos legada na interface do Merchant Center para evitar que atualizações acidentais baseadas em arquivos substituam os dados da API.
Anterior
Migrate Local Inventory Ads settings