Gerenciar informações do catálogo

Nesta página, descrevemos como gerenciar as informações do produto depois de importar um catálogo para a Vertex AI para Pesquisa para o varejo. É possível ler, gravar e excluir produtos no seu catálogo.

Para manter seu catálogo atualizado conforme as informações do produto são alteradas, importe seu catálogo da mesma forma que na primeira vez. Para receber ajuda sobre como importar seu catálogo, consulte Como importar informações de catálogo.

Tutorial de criação, recebimento, atualização e exclusão de produtos

Neste tutorial, mostramos como usar os métodos da API, que executam as seguintes ações:

  • Criar um produto
  • Receber um produto
  • Atualizar um produto
  • Excluir um produto

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de criação de produtos

Neste tutorial, mostramos como criar um único produto.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de recebimento de produtos

Neste tutorial, mostramos como recuperar um item de produto.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de atualização de produtos

Neste tutorial, mostramos como atualizar um produto em um catálogo.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de exclusão de produtos

Neste tutorial, mostramos como excluir um produto de um catálogo.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Fazer upload de um produto

curl

Crie um único item de produto usando o método REST products.create.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
      "title": "PRODUCT_TITLE",
      "categories": "CATEGORY"
    }' \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products?productId=PRODUCT_ID"

Se a solicitação for bem-sucedida, o objeto do produto será retornado, como no exemplo a seguir.

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "CATEGORY"
  ],
  "title": "PRODUCT_TITLE",
  "availability": "IN_STOCK"
}

Java

public static Product createProduct(Product productToCreate, String productId)
    throws IOException {
  return getProductServiceClient().createProduct(
      DEFAULT_BRANCH_NAME, productToCreate, productId
  );
}

Atualizar informações do produto

É possível atualizar seu catálogo fazendo upload de alterações em produtos como novos produtos, preços e status de estoque em tempo real, conforme seu produto muda. Somente é possível fazer upload de produtos adicionados ou alterados: não é necessário atualizar todo o catálogo.

curl

Atualize as informações do produto usando o método products.patch.

O exemplo a seguir atualiza o título de um produto específico:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
       "title": "new-title-value"
    }" \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID?updateMask=title"

Se a solicitação for bem-sucedida, o objeto do produto será retornado, como no exemplo a seguir.

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID",
  "id": "PRODUCT_ID",
  "primaryProductId": "PRODUCT_ID",
  "type": "PRIMARY",
  "categories": [
    "Parent category > Child category"
  ],
  "title": "new product title",
  "availability": "IN_STOCK"
}

Java

public static Product updateProduct(Product productToUpdate) throws IOException {
  return getProductServiceClient().updateProduct(productToUpdate, FieldMask.getDefaultInstance());
}

Excluir informações do produto

Embora a API forneça uma maneira de excluir produtos do seu catálogo, lembre-se de que, se você registrar um evento de usuário relacionado a um item de produto que foi excluído, a API não poderá processar o evento de usuário corretamente e ele poderá ser excluído. Além disso, incluir dados históricos de catálogo melhora a qualidade do modelo e é fundamental para boas recomendações e resultados da pesquisa.

Defina o availability de produtos obsoletos como OUT_OF_STOCK em vez de excluí-los.

curl

Exclua um produto usando o método delete, substituindo PRODUCT_ID pelo ID do produto que você quer excluir.

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

Java

public static void deleteProduct(String productName) throws IOException {
  getProductServiceClient().deleteProduct(productName);
}

Recuperar um item de produto

curl

Para recuperar um item do produto, faça uma solicitação GET para o endpoint products, substituindo PRODUCT_ID pelo ID do produto que você quer recuperar:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"  \
    "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"

A saída será semelhante a esta:

{
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/PRODUCT_ID"
    "id": "PRODUCT_ID",
    "primaryProductId": "PRODUCT_ID",
    "type": "PRIMARY",
    "categories": [
      "Parent category > Child category"
    ],
    "title": "product title",
    "availability": "IN_STOCK"
}

Java

public static Product getProduct(String productName) throws IOException {
  return getProductServiceClient().getProduct(productName);
}

Conferir informações agregadas sobre o catálogo

É possível ver informações agregadas sobre seu catálogo e visualizar os produtos enviados por upload na guia Catálogo da página Dados do console do Search for Retail.

Avaliar a qualidade dos dados do catálogo

Para avaliar a qualidade dos dados do catálogo, faça o seguinte:

  1. Acesse a página Qualidade de dados no console da Pesquisa for Retail.

    Acessar a página "Qualidade de dados"

    A página Qualidade de dados avalia se você precisa atualizar os dados do catálogo para melhorar a qualidade dos resultados da pesquisa e desbloquear os níveis de desempenho da pesquisa.

Para saber mais sobre como verificar a qualidade dos dados e conferir os níveis de desempenho da pesquisa, consulte Desbloquear níveis de desempenho de pesquisa.

Para um resumo das métricas de catálogo disponíveis, consulte Métricas de qualidade do catálogo.

Alterar tipos de produto

Ao importar um produto, é possível especificar se o tipo do produto é principal, variante ou uma coleção. Se o tipo de um produto mudar ou tiver sido especificado incorretamente, será necessário excluir o produto e criá-lo com o tipo atualizado especificado.

Um tipo de produto pode ser definido como TYPE_UNSPECIFIED, PRIMARY, VARIANT ou COLLECTION. Para mais detalhes, consulte product.Type na documentação de referência.

Mudar a configuração no nível do produto

Ao importar um catálogo com o Merchant Center, é necessário especificar se os produtos são principais ou variantes. Se esses níveis do produto mudarem ou forem especificados incorretamente, use o procedimento abaixo para corrigir a configuração deles. É necessário ter o papel do IAM de administrador de varejo para concluir este procedimento.

  1. Verifique se nenhuma importação está ocorrendo enquanto você reconfigura os níveis do produto. Isso garante que os dados não sejam enviados no nível errado.

  2. Exclua todos os itens do produto. Veja products.delete. O catálogo precisa estar completamente vazio antes de passar para a próxima etapa.

  3. Importe novamente seus dados para alterar a configuração no nível do produto.

    Este procedimento depende da sua importação. Siga o procedimento apropriado em Importar informações do catálogo para definir os níveis de produtos para a nova configuração.

  4. Conclua a importação do novo catálogo com a configuração de nível modificada usando o procedimento escolhido em Importar informações do catálogo.

  5. Ajuste todos os modelos existentes.

    Para ajustar um modelo, acesse a página "Modelos": clique no nome do modelo para ver a respectiva página de detalhes e, em seguida, clique em Ajuste manual na barra de botões.

    Acessar a página "Modelos"

    Para ajustar os detalhes de custo, consulte Preços.