Práticas recomendadas da API CSS

Este documento descreve algumas das práticas recomendadas para usar a API CSS. As recomendações nesta página não são obrigatórias para usar a API, mas podem ajudar a esclarecer alguns dos usos pretendidos.

Configure o ambiente

Para configurar o ambiente de desenvolvimento, siga as etapas da documentação de início rápido.

• Gerar um arquivo JSON de usuário e permissões no console do Google Cloud
• Ative a API CSS no console do Google Cloud
• Adicione esse usuário com permissões de administrador à sua conta do CSS (grupo ou domínio do CSS).
• Verifique se você está usando o escopo correto do OAuth: https://www.googleapis.com/auth/content

As bibliotecas de cliente agora estão nos repositórios padrão para a maioria das linguagens de programação. Confira uma lista delas na página da biblioteca de cliente.

Usar os IDs corretos

Use os IDs e endpoints de API corretos:

• API CSS (css.googleapis.com): use o ID do domínio do CSS ao interagir com produtos do CSS (por exemplo, accounts/{cssDomainId}/cssProductInputs:insert).
• API Merchant (merchantapi.googleapis.com): use a API Merchant para produtos padrão de comerciantes.

Misturar esses dois tipos vai causar erros. Consulte a visão geral da API CSS para mais detalhes.

Bons métodos para começar

Recomendamos testar com os seguintes métodos:

ListChildAccounts

ListChildAccounts é uma chamada somente leitura que lista todos os seus domínios do CSS (se chamada para um grupo do CSS) ou seus comerciantes (se chamada para um domínio do CSS). Portanto, é um bom método para testar se tudo está configurado corretamente.

Inserir/listar/atualizar/excluir um produto

Depois de saber que a API funciona, tente adicionar um produto. Use uma raw_provided_id que você consiga lembrar.

• Insira um produto de teste usando InsertCssProductInput. Temos um código de exemplo se você precisar de ajuda para saber quais atributos enviar.
• Liste todos os seus produtos usando ListCssProducts. Há um pequeno atraso no processamento antes que um produto apareça após a inserção. Se ele não aparecer, tente novamente depois de alguns segundos.
• Atualize um único produto usando UpdateCssProductInput com seu cssproductinput.name. Você precisa enviar apenas os atributos que precisam ser atualizados. Consulte o exemplo de código aqui.
• Exclua o produto de teste usando DeleteCssProductInput. Você vai precisar usar o raw_provided_id.

Usar Async para melhorar a performance

A API CSS foi projetada para chamadas paralelas. O desempenho de operações únicas pode ser lento, mas é muito mais rápido ao chamar a mesma operação várias vezes em paralelo. A melhor maneira de usar esse recurso é com a funcionalidade assíncrona da sua linguagem de programação.

Exemplos de algumas linguagens de programação:

• Em Java, use insertCssProductInputCallable().futureCall()
• Para Python, use CssProductInputsServiceAsyncClient
• Para C#, use InsertCssProductInputAsync

Encontre e use a funcionalidade assíncrona da sua linguagem de programação para inserir vários produtos ao mesmo tempo. Não é preciso se preocupar com a sobrecarga dos nossos sistemas. É para isso que servem os limites de cota.

Confira mais detalhes na nossa página de desempenho.

Validar seus payloads

Para evitar erros comuns, verifique se os payloads JSON estão formatados corretamente:

• Consulte a documentação oficial:sempre consulte a mais recente referência da API CSS para definições de campo, enums, tipos de dados e estrutura de payload.
• Analise exemplos de payloads:compare seus payloads com os exemplos de código fornecidos para identificar discrepâncias.
• Tipos de dados:use os tipos de dados corretos (por exemplo, strings, objetos, matrizes) conforme especificado na documentação.
• Teste incrementalmente:comece com payloads válidos mínimos para confirmar a conectividade básica e adicione mais atributos gradualmente.

Atualizar um produto

Depois que um produto é enviado, ele permanece no nosso sistema até ser atualizado, excluído ou expirar.

• É possível atualizar o produto completo enviando a solicitação InsertCssProductInput novamente, usando o mesmo raw_provided_id que você usou inicialmente. Por enquanto, você precisa enviar os dados completos do produto, mesmo que apenas alguns atributos (talvez apenas preço/disponibilidade) tenham mudado.
• É possível atualizar partes de um produto usando o método PATCH UpdateCssProductInput, especificando o nome do produto e um corpo JSON que contenha os dados que você quer atualizar. Ao contrário de InsertCssProductInput, que exige que todos os campos aplicáveis sejam fornecidos, UpdateCssProductInput exige apenas que você especifique os campos que quer mudar.
• Para excluir um produto, chame DeleteCssProductInput com o mesmo raw_provided_id.
• Os produtos expiram automaticamente cerca de um mês após a última atualização.

Modo de operação contínua

Um modo de operação contínua pode ser semelhante a este:

• Use seus próprios IDs internos como raw_provided_id.
• Faça o upload de todos os produtos regularmente, talvez semanalmente. Isso garante que os produtos ativos não expirem.
• Atualize os produtos individuais assim que receber os dados alterados dos seus comerciantes.
  • Se não for possível reagir às mudanças imediatamente, encontre todos os produtos alterados com frequência (talvez a cada hora) e faça upload apenas deles.
  • Para produtos que não estão mais disponíveis, use a chamada de exclusão ou defina o número de ofertas disponíveis como 0.
  • Não envie produtos sem alterações com frequência. Essas chamadas seriam descontadas da sua cota de API. Uma atualização semanal é suficiente.

Seleção de item principal

O item principal não precisa ser o melhor ou o mais barato do seu site, mas precisa estar em destaque. Você pode usar isso em casos em que sua principal oferta está mudando rapidamente. Nesse caso, selecione outra oferta mais estável.

Verifique este documento de vez em quando

Recebemos feedback sobre como melhorar essa API e estamos trabalhando para disponibilizar algumas dessas melhorias. Esta página será atualizada quando tivermos novos recursos disponíveis que vão simplificar o uso da API CSS.