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 Search para 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

Este tutorial mostra 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

Este tutorial mostra 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 ofereça uma maneira de excluir produtos do 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 do usuário corretamente e ele pode 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);
}

Extrair 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 resposta 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 seu catálogo

É possível conferir informações agregadas sobre seu catálogo e visualizar os produtos enviados na guia Catálogo na página Dados do console da Pesquisa para varejo.

Avaliar a qualidade dos dados do catálogo

Para avaliar a qualidade dos dados do catálogo:

  1. Acesse a página Qualidade dos dados no console da Pesquisa para varejo.

    Acesse a página "Qualidade dos dados"

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

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

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

Mudar 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 produto como 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.