Importar informações do catálogo

Esta página descreve como importar as informações do seu catálogo e mantê-las data.

Os procedimentos de importação nesta página se aplicam às duas recomendações e pesquisar. Depois de importar os dados, os dois serviços podem usar esses dados, então você não precisa importar os mesmos dados duas vezes se você usar os dois serviços.

Importar dados do catálogo do BigQuery

Neste tutorial, mostramos como usar uma tabela do BigQuery para importar grandes quantidades de dados de catálogo sem limites.

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

Orientações

Importar dados do catálogo do Cloud Storage

Neste tutorial, mostramos como importar um grande número de itens para um catálogo.

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

Orientações

Importar dados do catálogo inline

Neste tutorial, mostramos como importar produtos para um catálogo inline.

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

Orientações

Antes de começar

Antes de importar as informações do seu catálogo, é preciso concluir as instruções Antes de começar, especificamente Como configurar seu projeto, Como criar uma conta de serviço e Como adicionar a conta de serviço ao seu ambiente local.

É necessário ter o papel do IAM de administrador de varejo para realizar a importação.

Práticas recomendadas de importação de catálogo

Dados de alta qualidade são necessários para gerar resultados de alta qualidade. Se seus dados forem campos ausentes ou tiver valores de marcador em vez de valores reais, a qualidade das previsões e dos resultados de pesquisa é prejudicado.

Ao importar dados do catálogo, implemente as seguintes práticas recomendadas:

  • Pense com cuidado ao determinar quais produtos ou grupos de produtos são principais e quais são variantes. Antes de fazer o upload de quaisquer dados, consulte os Níveis de produto.

    Alterar a configuração no nível do produto depois de importar todos os dados exige um esforço significativo.

    Os itens principais são retornados como resultados de pesquisa ou recomendações. Variante itens não são.

    Por exemplo, se o grupo principal de SKUs for "camisa com gola em V", o de recomendação retorna um item de camisa de gola em V e, talvez, um camisa de gola redonda e uma camisa de gola redonda. No entanto, se as variantes não forem usadas e cada SKU for principal, todas as combinações de cor e tamanho de camisa de gola em V é retornado como um item distinto no painel de recomendações: "Decote em V marrom camiseta, tamanho XG", "Camisa de gola V marrom, tamanho G", até "Decote branco branco" camiseta, tamanho M", "Camisa branca de gola V, tamanho P".

  • Observe os limites de importação de itens do produto.

    Para a importação em massa do Cloud Storage, o tamanho de cada arquivo precisa ser 2 GB ou menor. É possível incluir até 100 arquivos por vez em uma única solicitação de importação em massa.

    Para realizar a importação in-line, importe no máximo 5 mil itens de cada vez.

  • Verifique se todas as informações de catálogo necessárias estão incluídas e corretas.

    Não use valores de marcador.

  • Inclua o máximo possível de informações opcionais do catálogo.

  • Verifique se todos os seus eventos usam uma única moeda, especialmente se você planeja usá-la Console do Google Cloud para acessar métricas de receita. A API Vertex AI para Pesquisa para Retail não é compatível com o uso várias moedas por catálogo.

  • Mantenha seu catálogo atualizado.

    O ideal é atualizar o catálogo diariamente. A programação de importações periódicas de catálogo evita que a qualidade do modelo diminua com o tempo. Você pode agendar importações automáticas e recorrentes quando você importa seu catálogo usando o Pesquise o console de varejo. Se preferir, use o Google Cloud Scheduler para automatizar importações.

  • Não registre eventos de usuário de itens de produtos que ainda não foram importados.

  • Depois de importar as informações do catálogo, revise os relatórios de erros e as informações de geração de registros do seu projeto.

    Alguns erros são esperados, mas, se você tiver um grande número de erros, revise-os e corrija os problemas de processo que os levaram.

Sobre a importação de dados do catálogo

É possível importar os dados do produto do Merchant Center, do Cloud Storage, do BigQuery ou especificar os dados in-line na solicitação. Cada um desses procedimentos são importações únicas com exceto na vinculação do Merchant Center. Agendar importações regulares de catálogo (de preferência, diariamente) para garantir que ele esteja atualizado; Consulte Manter seu catálogo atualizado.

Também é possível importar itens de produtos individuais. Para mais informações, consulte Faça upload de um produto.

Considerações sobre importação de catálogo

Nesta seção, descrevemos os métodos que podem ser usados para importação em lote dos dados de catálogo, quando você usa cada método e algumas das limitações deles.

Sincronização no Merchant Center Descrição Importa dados de catálogo pelo Merchant Center ao vincular a conta com a Vertex AI para Pesquisa para Retail. Após a vinculação, a página os dados de catálogo no Merchant Center são sincronizados em tempo real para Vertex AI para Pesquisa para Retail.
Quando usar Se você tiver uma integração com o Google Merchant Center.
Limitações Suporte limitado a esquemas. Por exemplo, as coleções de produtos não são compatíveis com o Merchant Center. O Merchant Center se tornará a fonte da verdade para os dados até que eles sejam desvinculados. Por isso, os atributos personalizados necessários precisam ser adicionados aos dados do Merchant Center.

Controle limitado. Não é possível especificar determinados campos ou conjuntos de itens para importar do Merchant Center. todos os itens e campos existentes no Merchant Center são importados.
BigQuery Descrição Importe dados de uma tabela do BigQuery já carregada que usa o esquema da Vertex AI para Pesquisa para Retail ou o esquema do Merchant Center. Isso pode ser feito usando o console do Google Cloud ou curl.
Quando usar Se você tiver catálogos de produtos com muitos atributos. Google BigQuery usa o esquema da Vertex AI para Pesquisa para Retail, que tem mais opções do que outras opções de importação, incluindo chaves-valor personalizadas atributos.

Se você tiver grandes volumes de dados. A importação do BigQuery não tem um limite de dados.

Se você já usa o BigQuery.
Limitações Exige a etapa extra de criar uma tabela do BigQuery que é mapeado para o esquema da Vertex AI para Pesquisa para Retail.
Cloud Storage Descrição Importe dados em um formato JSON de arquivos carregados em um bucket do Cloud Storage. Cada arquivo precisa ter 2 GB ou menos e até 100 arquivos por vez são importados. A importação pode ser feita usando o console do Google Cloud. ou curl. Usa o formato de dados JSON Product, que permite atributos personalizados.
Quando usar Se você precisa carregar uma grande quantidade de dados em uma única etapa
Limitações Não é ideal para catálogos com atualizações frequentes de inventário e preços, já que as alterações não são refletidas imediatamente.
Importação in-line Descrição Importação usando uma chamada para o método Product.import. Usos o objeto ProductInlineSource, que tem menos produtos de catálogo do que o esquema da Vertex AI para Pesquisa para Retail, mas oferece suporte atributos.
Quando usar Se você tem dados de catálogo planos e não relacionais ou uma alta frequência de atualizações de quantidade ou preço.
Limitações Apenas 100 itens do catálogo podem ser importados por vez. No entanto, muitas etapas de carregamento podem ser executadas: não há limite de itens.

Limpar ramificações do catálogo

Se você estiver importando novos dados de catálogo para uma ramificação existente, é importante que a ramificação do catálogo esteja vazia. Isso garante a integridade dos dados importados ao a ramificação. Quando a ramificação estiver vazia, será possível importar novos dados do catálogo e vincular a ramificação a uma conta de comerciante.

Se você estiver veiculando tráfego de previsão ou pesquisa em tempo real e planeja limpar o tráfego padrão especifique primeiro outra como padrão antes da limpeza. Como a ramificação padrão exibe resultados vazios após a limpeza, a limpeza uma ramificação padrão ativa pode causar uma interrupção do serviço.

Para limpar dados de uma ramificação de catálogo, siga estas etapas:

  1. Acesse Dados> no console da Pesquisa para varejo.

    Acessar a página "Dados"

  2. Selecione uma ramificação de catálogo no campo Nome da ramificação.

  3. No menu de três pontos ao lado do campo Nome da ramificação, escolha Limpar ramificação.

    Uma mensagem será exibida avisando que você está prestes a excluir todos os dados do a ramificação e os atributos criados para ela.

  4. Insira a ramificação e clique em Confirmar para limpar os dados do catálogo ramificação.

    Uma operação de longa duração é iniciada para limpar os dados da ramificação de catálogo. Quando a operação de limpeza for concluída, o status da limpeza será exibido em da lista Catálogo de produtos no campo Status da atividade janela.

Sincronizar o Merchant Center com a Vertex AI para Pesquisa para Retail

Para sincronização contínua entre o Merchant Center e o Com a Vertex AI para Pesquisa para Retail, é possível vincular sua conta do Merchant Center à Vertex AI para Pesquisa para Retail. Após a vinculação, as informações do catálogo na sua a conta do Merchant Center é importada imediatamente para Vertex AI para Pesquisa para Retail.

Ao configurar uma sincronização do Merchant Center para a Vertex AI para Pesquisa para varejo, você precisa ter a função de administrador atribuída no Merchant Center. Embora um papel de acesso padrão permita a leitura dos feeds do Merchant Center na UI, ao tentar sincronizar o Merchant Center com a Vertex AI para Pesquisa para Retail, você recebe uma mensagem de erro. Portanto, antes de sincronizar o Merchant Center com a Vertex AI para Pesquisa para Retail, faça o upgrade da sua função.

Embora a Vertex AI para Pesquisa para Retail esteja vinculada ao Merchant Center mudanças nos dados dos produtos no Merchant Center são atualizadas automaticamente em minutos na Vertex AI para Pesquisa para varejo. Se você não quiser que as alterações no Merchant Center sejam sincronizadas à Vertex AI para Pesquisa para Retail, é possível desvincular na sua conta do Merchant Center.

Desvincular sua conta do Merchant Center não exclui nenhuma produtos na Vertex AI para Pesquisa para Retail. Para excluir produtos importados, consulte Excluir informações do produto.

Para sincronizar sua conta do Merchant Center, conclua as etapas a seguir.

Console

  1. Acesse Dados> no console da Pesquisa para varejo.

    Acessar a página "Dados"
  2. Clique em Importar para abrir o painel Importar dados.
  3. Escolha Catálogo de produtos.
  4. Selecione Merchant Center Sync como sua fonte de dados.
  5. Selecione sua conta do Merchant Center. Verifique Acesso do usuário se não encontrar sua conta.
  6. Opcional: selecione o filtro de feeds do Merchant Center para importar somente ofertas de feeds selecionados.

    Se essa opção não for especificada, as ofertas de todos os feeds serão importadas, incluindo feeds futuros.
  7. Opcional: para importar somente ofertas segmentadas para determinados países ou idiomas, expanda Mostrar opções avançadas e selecione os países de venda e os idiomas do Merchant Center que você quer filtrar.
  8. Selecione a ramificação para fazer o upload do catálogo.
  9. Clique em Importar.

curl

  1. Verifique se a conta de serviço no seu ambiente local tem acesso tanto à conta do Merchant Center Vertex AI para Pesquisa para Retail. Para verificar quais contas têm acesso à sua conta do Merchant Center, consulte Acesso do usuário para o Merchant Center.

  2. Use o método MerchantCenterAccountLink.create para estabelecer a vinculação.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
  "merchantCenterAccountId": MERCHANT_CENTER_ID,
  "branchId": "BRANCH_ID",
  "feedFilters": [
    {"primaryFeedId": PRIMARY_FEED_ID_1}
    {"primaryFeedId": PRIMARY_FEED_ID_2}
  ],
  "languageCode": "LANGUAGE_CODE",
  "feedLabel": "FEED_LABEL",
 }' \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
    • MERCHANT_CENTER_ID: o ID do na sua conta do Merchant Center.
    • BRANCH_ID: o ID da ramificação para estabelecer a vinculação com Aceita os valores "0", "1" ou "2".
    • LANGUAGE_CODE: (OPCIONAL) o código de idioma de duas letras de os produtos que você quer importar. Conforme visto em Merchant Center na coluna Language das produto. Se ela não for definida, todos os idiomas serão importados.
    • FEED_LABEL: (OPCIONAL) o rótulo do feed. dos produtos que você quer importar. Confira o rótulo do feed Merchant Center no rótulo do feed do produto do produto da coluna. Se ela não for definida, todos os rótulos do feed serão importados.
    • FEED_FILTERS: (OPCIONAL) lista de feeds principais dos quais os produtos serão importadas. Se não selecionar feeds, Os feeds da conta do Merchant Center são compartilhados. Os IDs podem ser encontradas no recurso de feeds de dados da API Content ou acessar o Merchant Center, selecionar um feed acessar o ID do feed do parâmetro dataSourceId na o URL do site. Por exemplo, mc/products/sources/detail?a=MERCHANT_CENTER_ID&dataSourceId=PRIMARY_FEED_ID.

Para acessar sua conta do Merchant Center vinculada, acesse Pesquise a página Dados do console do Retail e clique no Merchant Center no canto superior direito da página. A página Vinculado do Merchant Center Contas. Também é possível adicionar outros contas deste painel.

Consulte Visualizar informações agregadas sobre seu catálogo para instruções sobre como visualizar os produtos que foram importados.

Liste as vinculações da sua conta do Merchant Center.

Console

  1. Acesse Dados> no console da Pesquisa para varejo.

    Acessar a página "Dados"

  2. Clique no botão Merchant Center no canto superior direito da página para abrir uma lista das suas contas vinculadas do Merchant Center.

curl

Usar o método MerchantCenterAccountLink.list para listar o recurso de links.

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

Desvincular sua conta do Merchant Center interrompe o uso dela sincronizar dados de catálogo com a Vertex AI para Pesquisa para Retail. Esse procedimento não excluir os produtos na Vertex AI para Pesquisa para Retail que já foram enviado.

Console

  1. Acesse Dados> no console da Pesquisa para varejo.

    Acessar a página "Dados"

  2. Clique no botão Merchant Center no canto superior direito da página para abrir uma lista das suas contas vinculadas do Merchant Center.

  3. Clique em Desvincular ao lado da conta do Merchant Center que você quer desvincular e confirme sua escolha na caixa de diálogo exibida.

curl

Usar o MerchantCenterAccountLink.delete para remover o recurso MerchantCenterAccountLink.

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

Limitações ao vincular ao Merchant Center

  • Uma conta do Merchant Center pode ser vinculada a qualquer número de ramificações de catálogo, mas uma única ramificação de catálogo só pode ser vinculada a uma conta do Merchant Center.

  • Uma conta do Merchant Center não pode ser conta de múltiplos clientes (MCA). No entanto, você pode vincular subcontas.

  • A primeira importação depois de vincular sua conta do Merchant Center pode levar horas para ser concluída. O tempo depende do número de ofertas na conta do Merchant Center.

  • Qualquer modificação de produto usando métodos da API é desativado para ramificações vinculadas a uma conta do Merchant Center. Qualquer alteração nos dados do catálogo de produtos nessas ramificações precisa ser feita usando o Merchant Center. Essas mudanças são sincronizadas automaticamente à Vertex AI para Pesquisa para Retail.

  • O tipo de produto da coleção não é compatível com ramificações que usam o Merchant Center.

  • Sua conta do Merchant Center só pode ser vinculada a ramificações de catálogo vazias para garantir a correção dos dados. Para excluir produtos de um catálogo consulte Excluir informações do produto.

Importar dados do catálogo do Merchant Center

O Merchant Center é uma ferramenta que você pode usar para disponibilizar os dados da sua loja e dos seus produtos para anúncios do Shopping e outros serviços do Google.

Você pode importar em massa os dados do catálogo do Merchant Center como um procedimento único do BigQuery usando o Esquema do Merchant Center (somente recomendações).

Importação em massa do Merchant Center

É possível importar os dados do catálogo do Merchant Center usando o Pesquise o console do Retail ou o método products.import. Em lote a importação é um procedimento único e só é compatível com recomendações.

Para importar seu catálogo do Merchant Center, siga estas etapas:

  1. Usando as instruções nas transferências do Merchant Center, configure uma transferência do Merchant Center para o BigQuery.

    Use o esquema da tabela de produtos do Google Merchant Center. Configure a transferência para que ela se repita diariamente, mas defina o prazo de validade do conjunto de dados em dois dias.

  2. Se o conjunto de dados do BigQuery estiver em outro projeto, configure o as permissões necessárias para que a Vertex AI para Pesquisa para Retail possa acessar conjunto de dados do BigQuery. Saiba mais.

  3. Importe os dados do seu catálogo do BigQuery para o Vertex AI para Pesquisa para Retail.

    Console

    1. Acesse Dados> no console da Pesquisa para varejo.

      Acessar a página "Dados"

    2. Clique em Importar para abrir o painel "Importar".

    3. Escolha Catálogo de produtos.

    4. Selecione BigQuery como sua fonte de dados.

    5. Selecione a ramificação para fazer o upload do catálogo.

    6. Selecione Merchant Center como o esquema de dados.

    7. Insira a tabela do BigQuery em que seus dados estão localizados.

    8. Opcional: insira o local de um bucket do Cloud Storage em seu projeto como um local temporário para seus dados.

      Se não for especificado, um local padrão será usado. Caso seja especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.

    9. Escolha se você quer programar um upload recorrente dos dados do seu catálogo.

    10. Se esta for a primeira vez que você está importando o catálogo ou se estiver importando o catálogo novamente depois de limpá-lo, selecione os níveis do produto. Saiba mais sobre os níveis de produto.

      Altere a configuração no nível do produto depois de importar exige um esforço significativo.

    11. Clique em Importar.

    curl

    1. Se esta for a primeira vez que você está carregando o catálogo ou se estiver importando o catálogo novamente após a limpeza, defina os níveis do produto usando o método Catalog.patch. Essa operação requer o papel de Administrador de varejo. Saiba mais sobre os níveis de produto.

      • ingestionProductType: compatível com os valores primary (padrão) e variant.
      • merchantCenterProductIdField: compatível com os valores offerId (padrão) e itemGroupId. Se você não usar Merchant Center, definido com o valor padrão offerId.
      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
--data '{
"productLevelConfig": {
  "ingestionProductType": "PRODUCT_TYPE",
  "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
}
}' \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

    2. Importe o catálogo usando o método Products.import.

      • DATASET_ID: o ID do conjunto de dados do BigQuery.
      • TABLE_ID: o ID da tabela do BigQuery que contém os dados.
      • STAGING_DIRECTORY: opcional. Um diretório do Cloud Storage usado como um local temporário para seus dados antes de importá-los para o BigQuery. Deixe este campo em branco para criar automaticamente (recomendado).
      • ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erros sobre a importação. Sair deste campo vazio para criar automaticamente uma diretório temporário (recomendado).
      • dataSchema: para a propriedade dataSchema, use o valor product_merchant_center. Veja o esquema da tabela de produtos do Merchant Center.

      Recomendamos que você não especifique diretórios de teste ou erro. Dessa forma, um É possível criar um bucket do Cloud Storage com novos diretórios de teste e criadas automaticamente. Esses diretórios são criados no mesmo regional como o conjunto de dados do BigQuery e são exclusivos para cada importação (o que impede que vários jobs de importação preparem dados no mesmo diretório, e possivelmente reimportar os mesmos dados). Após três dias, o bucket e os diretórios são excluídos automaticamente para reduzir os custos de armazenamento.

      Um nome de bucket criado automaticamente inclui o ID do projeto, a região do bucket e o nome do esquema de dados, separados por sublinhados (por exemplo, 4321_us_catalog_retail). Os diretórios criados automaticamente são chamados de staging ou errors, anexados por um número (por exemplo, staging2345 ou errors5678).

      Se você especificar diretórios, o bucket do Cloud Storage precisará estar na mesma região do conjunto de dados do BigQuery. Caso contrário, a importação falhará. Forneça os diretórios de preparo e erro no formato gs://<bucket>/<folder>/. cada uma delas deve ser diferente. 

      curl -X POST \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "inputConfig":{
            "bigQuerySource": {
              "datasetId":"DATASET_ID",
              "tableId":"TABLE_ID",
              "dataSchema":"product_merchant_center"
            }
          }
      }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Importar dados do catálogo do BigQuery

Para importar dados do catálogo no formato correto do BigQuery, use o esquema da Vertex AI para Pesquisa para Retail para Crie uma tabela do BigQuery com o formato correto e carregue a tabela vazia com os dados do seu catálogo. Em seguida, faça o upload dos seus dados à Vertex AI para Pesquisa para Retail.

Para mais ajuda com as tabelas do BigQuery, consulte Introdução às tabelas. Para ajuda com as consultas do BigQuery, consulte Visão geral da consulta de dados do BigQuery.

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

Orientações

Para importar seu catálogo:

  1. Se o conjunto de dados do BigQuery estiver em outro projeto, configure o as permissões necessárias para que a Vertex AI para Pesquisa para Retail possa acessar conjunto de dados do BigQuery. Saiba mais.

  2. Importe os dados do seu catálogo para a Vertex AI para Pesquisa para Retail.

    Console

    1. Acesse Dados> no console da Pesquisa para varejo.

      Acessar a página "Dados"
    2. Clique em Importar para abrir o painel Importar dados.
    3. Escolha Catálogo de produtos.
    4. Selecione BigQuery como sua fonte de dados.
    5. Selecione a ramificação para fazer o upload do catálogo.
    6. Escolha Esquema de catálogos de produtos de varejo. Este é o Esquema de produto da Vertex AI para Pesquisa para Retail.
    7. Insira a tabela do BigQuery em que seus dados estão localizados.
    8. Opcional: em Mostrar opções avançadas, digite a localização de um bucket do Cloud Storage no projeto como um local temporário para os dados.

      Se não for especificado, um local padrão será usado. Se especificado, as instâncias do BigQuery O bucket do Cloud Storage precisa estar na mesma região.
    9. Se a pesquisa não estiver ativada e você estiver usando esquema do Merchant Center, selecione o nível do produto.

      Você precisa selecione o nível do produto se esta for a primeira vez que você importa seu catálogo ou se estiver reimportar o catálogo depois de limpá-lo. Saiba mais. sobre os níveis dos produtos. Alterando níveis de produto após a importação dos dados exige um esforço significativo.

      Importante:não é possível ativar a pesquisa de projetos com do catálogo de produtos que foi ingerido como variantes.
    10. Clique em Importar.

    curl

    1. Se esta for a primeira vez que você está carregando o catálogo ou se estiver importando o catálogo novamente após a limpeza, defina os níveis do produto usando o método Catalog.patch. Essa operação requer o papel de Administrador de varejo.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
   "productLevelConfig": {
     "ingestionProductType": "PRODUCT_TYPE",
     "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
   }
 }' \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

    2. Crie um arquivo de dados para os parâmetros de entrada para a importação.

      Use o objeto BigQuerySource para apontar para o conjunto de dados do BigQuery.

      • DATASET_ID: o ID do conjunto de dados do BigQuery.
      • TABLE_ID: o ID da tabela do BigQuery que contém os dados.
      • PROJECT_ID: o ID do projeto em que está a origem do BigQuery. Se não for especificado, o ID do projeto será herdado da solicitação principal.
      • STAGING_DIRECTORY: opcional. Um diretório do Cloud Storage usado como um local temporário para seus dados antes de importá-los para o BigQuery. Deixe este campo em branco para criar automaticamente (recomendado).
      • ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erros sobre a importação. Sair deste campo vazio para criar automaticamente uma diretório temporário (recomendado).
      • dataSchema: para a propriedade dataSchema, use o valor product (padrão). Você vai usar o Esquema da Vertex AI para Pesquisa para Retail

      Recomendamos que você não especifique diretórios de teste ou erro. Dessa forma, um É possível criar um bucket do Cloud Storage com novos diretórios de teste e criadas automaticamente. Esses diretórios são criados no mesmo regional como o conjunto de dados do BigQuery e são exclusivos para cada importação (o que impede que vários jobs de importação preparem dados no mesmo diretório, e possivelmente reimportar os mesmos dados). Após três dias, o bucket e os diretórios são excluídos automaticamente para reduzir os custos de armazenamento.

      Um nome de bucket criado automaticamente inclui o ID do projeto, a região do bucket e o nome do esquema de dados, separados por sublinhados (por exemplo, 4321_us_catalog_retail). Os diretórios criados automaticamente são chamados de staging ou errors, anexados por um número (por exemplo, staging2345 ou errors5678).

      Se você especificar diretórios, o bucket do Cloud Storage precisará estar na mesma região do conjunto de dados do BigQuery. Caso contrário, a importação falhará. Forneça os diretórios de preparo e erro no formato gs://<bucket>/<folder>/. cada uma delas deve ser diferente. 

      {
   "inputConfig":{
     "bigQuerySource": {
       "projectId":"PROJECT_ID",
       "datasetId":"DATASET_ID",
       "tableId":"TABLE_ID",
       "dataSchema":"product"}
      }
}

    3. Importe as informações do seu catálogo por fazendo uma solicitação POST ao Products:import. método REST, fornecendo o nome do arquivo de dados (aqui, mostrado como input.json).

      curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" -d @./input.json \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      É possível verificar o status de maneira programática usando a API. Você receberá um objeto de resposta com esta aparência:

      {
"name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"done": false
}

      O campo de nome é o ID do objeto de operação. Para solicitar o status desse objeto, substitua o campo de nome pelo valor retornado pelo método import, até o campo done retornar como true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"

      Quando a operação for concluída, o objeto retornado terá um valor done de true e incluirá um objeto Status semelhante ao exemplo a seguir:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
  "createTime": "2020-01-01T03:33:33.000001Z",
  "updateTime": "2020-01-01T03:34:33.000001Z",
  "successCount": "2",
  "failureCount": "1"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
},
"errorsConfig": {
  "gcsPrefix": "gs://error-bucket/error-directory"
}
}

      Você pode inspecionar os arquivos no diretório de erros no Cloud Storage para ver se ocorreram erros durante a importação.

Configurar o acesso ao conjunto de dados do BigQuery

Para configurar o acesso quando seu conjunto de dados do BigQuery estiver em um projeto do que o serviço da Vertex AI para Pesquisa para Retail, conclua as etapas a seguir.

  1. Abra a página "IAM" no console do Google Cloud.

    Abrir a página do IAM

  2. Selecione seu projeto da Vertex AI para Pesquisa para Retail.

  3. Encontre a conta de serviço com o nome Conta de serviço de varejo.

    Se você não tiver iniciado uma operação de importação anteriormente, esta conta de serviço pode não estar listada. Se essa conta de serviço não for exibida, retorne à tarefa de importação e inicie a importação. Quando ela falhar devido a erros de permissão, volte aqui e conclua esta tarefa.

  4. Copie o identificador da conta de serviço, que se parece com um endereço de e-mail (por exemplo, service-525@gcp-sa-retail.iam.gserviceaccount.com).

  5. Alterne para o projeto do BigQuery (no mesmo IAM e administrador página) e clique em  Permitir acesso.

  6. Em Novos principais, insira o identificador da Vertex AI para Pesquisa para Retail. conta de serviço e selecione a caixa de seleção BigQuery > papel Usuário do BigQuery.

  7. Clique em Adicionar outro papel e selecione BigQuery > Editor de dados do BigQuery.

    Se você não quiser fornecer o papel de editor de dados a todo o projeto, adicione esse papel diretamente ao conjunto de dados. Saiba mais.

  8. Clique em Salvar.

Importar dados do catálogo do Cloud Storage

Para importar dados do catálogo no formato JSON, crie um ou mais arquivos JSON que contenham os dados do catálogo que você quer importar e faça o upload deles para o Cloud Storage. Depois, é possível importá-los para a Vertex AI para Pesquisa para Retail.

Para ver um exemplo do formato de item JSON do produto, consulte Formato de dados JSON do item do produto.

Para receber ajuda com o upload de arquivos para o Cloud Storage, consulte Faça o upload de objetos.

  1. Verifique se a conta de serviço da Vertex AI para Pesquisa para Retail tem permissão para ler e gravar no bucket.

    A conta de serviço da Vertex AI para Pesquisa para Retail está listada no Página do IAM no console do Google Cloud chamado Conta de serviço de varejo. Use o identificador da conta de serviço, que se parece com um endereço de e-mail (por exemplo, service-525@gcp-sa-retail.iam.gserviceaccount.com) ao adicionar a conta às permissões do bucket.

  2. Importe os dados do seu catálogo.

    Console

    1. Acesse Dados> no console da Pesquisa para varejo.

      Acessar a página "Dados"
    2. Clique em Importar para abrir o painel Importar dados.
    3. Escolha Catálogo de produtos como sua fonte de dados.
    4. Selecione a ramificação para fazer o upload do catálogo.
    5. Escolha Esquema de catálogos de produtos de varejo como esquema.
    6. Insira o local dos seus dados no Cloud Storage.
    7. Se a pesquisa não estiver ativada, selecione os níveis do produto.

      Você precisa selecione os níveis do produto se esta for a primeira vez que você importa seu catálogo ou se estiver reimportar o catálogo depois de limpá-lo. Saiba mais. sobre os níveis dos produtos. Alterando níveis de produto após a importação dos dados exige um esforço significativo.

      Importante:não é possível ativar a pesquisa de projetos com do catálogo de produtos que foi ingerido como variantes.
    8. Clique em Importar.

    curl

    1. Se esta for a primeira vez que você está carregando o catálogo ou se estiver importando o catálogo novamente após a limpeza, defina os níveis do produto usando o método Catalog.patch. Saiba mais sobre os níveis de produto.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
   "productLevelConfig": {
     "ingestionProductType": "PRODUCT_TYPE",
     "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
   }
 }' \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

    2. Crie um arquivo de dados para os parâmetros de entrada para a importação. Use o objeto GcsSource para apontar para o bucket do Cloud Storage.

      É possível fornecer vários arquivos ou apenas um. este exemplo usa dois arquivos.

      • INPUT_FILE: um ou mais arquivos no Cloud Storage que contêm os dados do catálogo.
      • ERROR_DIRECTORY: um diretório do Cloud Storage para informações de erro sobre a importação.

      Os campos do arquivo de entrada precisam estar no formato gs://<bucket>/<path-to-file>/. O diretório de erro precisa estar no formato gs://<bucket>/<folder>/. Se o diretório de erro não existir, ele será criado. O bucket já precisa existir.

      {
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
  }
},
"errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}

    3. Importe as informações do seu catálogo fazendo uma solicitação POST para o REST Products:import. , fornecendo o nome do arquivo de dados (aqui, mostrado como input.json).

      curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" -d @./input.json \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      A maneira mais fácil de verificar o status da operação de importação é use o console do Google Cloud. Para mais informações, consulte Consulte o status de uma operação de integração específica.

      Também é possível verificar o status de maneira programática usando a API. Você receberá um objeto de resposta com esta aparência:

      {
"name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"done": false
}

      O campo de nome é o ID do objeto de operação. Solicite o status desse objeto e substitua o campo de nome pelo valor retornado pelo método de importação, até que o campo done retorne como true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"

      Quando a operação for concluída, o objeto retornado terá um valor done de true e incluirá um objeto Status semelhante ao seguinte exemplo:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
  "createTime": "2020-01-01T03:33:33.000001Z",
  "updateTime": "2020-01-01T03:34:33.000001Z",
  "successCount": "2",
  "failureCount": "1"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
},
"errorsConfig": {
  "gcsPrefix": "gs://error-bucket/error-directory"
}
}

      É possível inspecionar os arquivos no diretório de erros no Cloud Storage para ver que tipo de erros ocorreu durante a importação.

Importar dados do catálogo inline

curl

Você importa as informações do seu catálogo inline fazendo uma solicitação POST ao método REST Products:import; usar o objeto productInlineSource para especificar seu catálogo; dados.

Forneça um produto inteiro em uma única linha. Cada produto deve estar sozinho linha

Para ver um exemplo do formato de item JSON do produto, consulte Formato de dados JSON do item do produto.

  1. Crie o arquivo JSON para seu produto e chame-o ./data.json:

    {
"inputConfig": {
"productInlineSource": {
  "products": [
    { PRODUCT_1 }
    { PRODUCT_2 }
  ]
}
}
}

  2. Chame o método POST:

    curl -X POST \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 --data @./data.json \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Java

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Formato de dados JSON do item do produto

As entradas Product no arquivo JSON devem ser semelhantes aos exemplos a seguir.

Forneça um produto inteiro em uma única linha. Cada produto deve estar sozinho linha

Campos obrigatórios mínimos:

  {
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers"
  }
  {
    "id": "5839",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt"
  }

Objeto completo:

  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
    "id": "1234",
    "categories": "Apparel & Accessories > Shoes",
    "title": "ABC sneakers",
    "description": "Sneakers for the rest of us",
    "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
    },
    "availableTime": "2020-01-01T03:33:33.000001Z",
    "availableQuantity": "1",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img1", "height": 320, "width": 320 }
    ]
  }
  {
    "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
    "id": "4567",
    "categories": "casual attire > t-shirts",
    "title": "Crew t-shirt",
    "description": "A casual shirt for a casual day",
    "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
    "language_code": "en",
    "tags": [ "black-friday" ],
    "priceInfo": {
      "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
    },
    "availableTime": "2020-02-01T04:44:44.000001Z",
    "availableQuantity": "2",
    "uri":"http://example.com",
    "images": [
      {"uri": "http://example.com/img2", "height": 320, "width": 320 }
    ]
  }

Dados históricos do catálogo

A Vertex AI para Pesquisa para Retail oferece suporte à importação e ao gerenciamento de os dados de catálogo. Os dados históricos do catálogo podem ser úteis quando você usa eventos históricos do usuário para treinar modelos. Informações anteriores do produto podem ser usadas para enriquecer dados históricos de eventos do usuário e melhorar a precisão do modelo.

Os produtos históricos são armazenados como expirados. Elas não são retornadas em respostas de pesquisa, mas são visíveis para as chamadas de API Update, List e Delete.

Importar dados históricos de catálogo

Quando o campo expireTime de um produto é definido como um carimbo de data/hora no passado, esse produto é considerado como histórico. Definir o produto availability [disponibilidade] como OUT_OF_STOCK para evitar o impacto recomendações.

Recomendamos o uso dos seguintes métodos para importar dados históricos de catálogo:

Chame o método Product.Create

Use o método Product.Create para criar uma entrada Product com o campo expireTime definido para um carimbo de data/hora no passado.

Produtos importados expirados

As etapas são idênticas à importação inline, com exceção dos produtos os campos expireTime precisam ter o passado definido carimbo de data/hora.

Forneça um produto inteiro em uma única linha. Cada produto deve estar sozinho linha

Um exemplo do ./data.json usado na solicitação de importação in-line:

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

Importar produtos expirados do BigQuery ou do Cloud Storage

Use os mesmos procedimentos documentados para importar dados de catálogo do BigQuery ou Como importar dados do catálogo do Cloud Storage. No entanto, defina o campo expireTime para um carimbo de data/hora no passado.

Mantenha seu catálogo atualizado

Para melhores resultados, seu catálogo precisa conter informações atualizadas. Recomendamos importar o catálogo diariamente para garantir que ele esteja atualizado. Você pode usar Google Cloud Scheduler para programar importações ou escolher uma opção de programação automática quando você importa dados usando o console do Google Cloud.

É possível atualizar apenas itens de produtos novos ou alterados ou importar todo o catálogo. Se você importar produtos que já estão no seu catálogo, eles não serão adicionados novamente. Todos os itens que foram alterados serão atualizados.

Para atualizar um único item, consulte Atualizar informações do produto.

Atualização em lote

Você pode usar o método de importação para atualizar seu catálogo em lote. Você faz isso da mesma forma que você faz a importação inicial. siga as etapas em Importar dados do catálogo.

Monitorar a integridade da importação

Para monitorar a ingestão e a integridade do catálogo:

  1. Acessar informações agregadas sobre o catálogo e a prévia enviada produtos na guia Catálogo da Pesquisa para varejo página Dados.

    Acessar a página "Dados"

  2. Avalie se você precisa atualizar os dados do catálogo para melhorar a qualidade do os resultados da pesquisa e desbloquear níveis de desempenho na Qualidade de dados.

    Saiba mais sobre como verificar a qualidade dos dados de pesquisa e conferir o desempenho dela níveis, consulte Desbloquear níveis de desempenho de pesquisa. Para um resumo disponíveis nesta página, consulte Métricas de qualidade do catálogo.

    Acessar a página "Qualidade de dados"

  3. Para criar alertas que informam se algo der errado com seus dados. uploads, siga os procedimentos em Configurar alertas do Cloud Monitoring.

    É importante manter seu catálogo atualizado para ter alta qualidade resultados. Use alertas para monitorar as taxas de erro de importação e tome medidas se: necessários.

A seguir