Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Varejo. Para usar a pesquisa de varejo na fase GA restrita, entre em contato com a equipe de vendas do Cloud.

Se você estiver usando apenas o Recommendations AI, permaneça no Console do Recommendations e consulte a documentação do Recommendations AI.

Como importar informações de catálogo

Nesta página, descrevemos como importar as informações do seu catálogo para a API Retail e mantê-las atualizadas.

Os procedimentos de importação nesta página aplicam-se ao Recommendations AI e à pesquisa de varejo. Depois que você importar dados para a API Retail, ambos os serviços poderão usar esses dados. Portanto, não é necessário importar os mesmos dados duas vezes se você usar os dois serviços.

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

A API Retail requer dados de alta qualidade para gerar resultados de alta qualidade. Se os dados não tiverem campos ou tiverem valores de marcador em vez de valores reais, a qualidade das previsões e dos resultados da pesquisa será prejudicada.

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

  • Revise as informações sobre níveis de produto antes de fazer upload de dados.

    Alterar os níveis de produto depois de importar todos os dados requer um esforço significativo.

  • 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 fictícios ou de marcador.

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

  • Certifique-se de que todos os seus eventos usem uma única moeda, principalmente se você pretende usar o Console do Cloud para ver métricas de receita. A API Retail não é compatível com o uso de 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. É possível programar importações automáticas e recorrentes ao importar o catálogo usando o Console do Cloud. 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 exceção da vinculação do Merchant Center à API Retail. Programe importações de catálogo regulares (de preferência, diariamente), para garantir que seu catálogo esteja atualizado. Consulte Como manter seu catálogo atualizado.

Também é possível importar itens de produtos individuais. Para mais informações, consulte Como fazer o upload de um item de 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.

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 Cloud ou o 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.
BigQuery Descrição Importe dados de uma tabela do BigQuery carregada anteriormente que use o esquema de varejo. Pode ser realizado usando o Console do Cloud ou o curl.
Quando usar Se você tiver catálogos de produtos com muitos atributos. A importação do BigQuery usa o esquema de varejo, que tem mais atributos de produto do que outras opções de importação, incluindo atributos personalizados de chave-valor.

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 criação de uma tabela do BigQuery que é mapeada para o esquema de varejo.
Sincronização no Merchant Center Descrição Importa dados de catálogo pelo Merchant Center vinculando a conta à API Retail. Após a vinculação, as atualizações nos dados do catálogo no Merchant Center são sincronizadas com a API Retail em tempo real.
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.
Importação in-line Descrição Importação usando uma chamada para o método Product.import. Usa o objeto ProductInlineSource, que tem menos atributos de catálogo de produtos do que o esquema de varejo, mas é compatível com atributos personalizados.
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.

Como importar dados de 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.

É possível importar dados de catálogo do Merchant Center das seguintes maneiras:

  • Importação em massa como um procedimento único (apenas no AI Recommendations).

  • Vincular sua conta do Merchant Center à API Retail Depois da vinculação, as alterações na sua conta do Merchant Center são continuamente sincronizadas com a API Retail.

Importação em massa do Merchant Center

É possível importar dados de catálogo do Merchant Center usando o Console do Cloud do varejo ou o método products.import. A importação em massa é um procedimento único e só é compatível com o Recommendations AI.

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 as permissões necessárias para que a API Retail possa acessar o conjunto de dados do BigQuery. Saiba mais.

  3. Importe os dados do catálogo do BigQuery para a API Retail.

    Console

    1. Acesse a página "Dados de varejo" no Console do Google Cloud.

      Acessar a página "Dados"

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

    3. Escolha Catálogo de produtos.

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

    5. Selecione Merchant Center como sua fonte de dados e BigQuery como o método de upload.

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

    7. (Opcional) Insira o local de um bucket do Cloud Storage no 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.

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

    9. 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.

      Alterar os níveis de produto depois de importar todos os dados requer um esforço significativo.

    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. 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 usa o Merchant Center, não é necessário definir esse campo.
      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 esse campo em branco para permitir que a API Retail crie automaticamente um diretório temporário (recomendado).
      • ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erros sobre a importação. Deixe esse campo em branco para permitir que a API Retail crie automaticamente um 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 preparo ou erro para que a API Retail possa criar automaticamente um bucket do Cloud Storage com novos diretórios de preparo e erro. Eles são criados na mesma região que o conjunto de dados do BigQuery e são exclusivos para cada importação, o que impede que vários jobs de importação organizem dados para o mesmo diretório e, possivelmente, reimportam os mesmos dados. de 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"
    

Como sincronizar o Merchant Center com a API Retail

Para a sincronização contínua entre o Merchant Center e a API Retail, vincule sua conta do Merchant Center à API Retail. Após a vinculação, as informações do catálogo na sua conta do Merchant Center são importadas imediatamente para a API Retail.

Embora a API Retail esteja vinculada à conta do Merchant Center, as alterações nos dados dos produtos dela são atualizadas automaticamente em minutos na API Retail. Se você quiser impedir que as alterações do Merchant Center sejam sincronizadas com a API Retail, desvincule sua conta do Merchant Center.

Desvincular sua conta do Merchant Center não exclui nenhum produto na API Retail. Para excluir produtos importados, consulte Como excluir informações do produto.

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

Console

  1. Acesse a página "Dados de varejo" no Console do Google Cloud.

    Acessar a página "Dados"

  2. Clique em Importar para abrir o painel Importar.

  3. Escolha Catálogo de produtos.

  4. Selecione Merchant Center Sync como sua fonte de dados.

  5. Selecione sua conta do Merchant Center.

  6. Selecione os destinos do Merchant Center de onde importar.

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

  8. Clique em Importar.

curl

  1. Verifique se a conta de serviço no seu ambiente local tem acesso à conta do Merchant Center e à API 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 Catalog.patch para estabelecer a vinculação.

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
     --data '{
        "merchantCenterLinkingConfig": {
          "links": [{
             merchantCenterAccountId: MERCHANT_CENTER_ID,
             destinations: ["DESTINATION_1", "DESTINATION_2", ...]
             branchId: "BRANCH_ID"
          }]
        }
     }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog?updateMask=merchantCenterLinkingConfig"
    
    • MERCHANT_CENTER_ID: o ID da conta do Merchant Center.
    • BRANCH_ID: o ID da ramificação com que você quer estabelecer a vinculação. Aceita os valores "0", "1" ou "2".
    • DESTINATION: o destino do Merchant Center. Ao menos um valor de destino é obrigatório Você pode usar qualquer combinação de valores compatíveis listados na documentação de destinos do Merchant Center.

Para ver seu Merchant Center vinculado, acesse a página Dados do Console do Cloud e clique no botão Merchant Center no canto superior direito. Isso abre o painel Contas do Merchant Center vinculadas. Também é possível adicionar outras contas do Merchant Center nesse painel.

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

Desvincular sua conta do Merchant Center impede que ela sincronize os dados de catálogo com a API Retail. Esse procedimento não exclui nenhum produto na API Retail que já tenha sido enviado.

Console

  1. Acesse a página "Dados de varejo" no Console do Google Cloud.

    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

Use o método Catalog.patch para remover a configuração de vinculação do recurso Catalog.

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

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.

  • 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.

  • As modificações de produtos que usam os métodos da API Retail são desativadas 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 alterações são sincronizadas automaticamente com a API 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 uma ramificação de catálogo, consulte Como excluir informações do produto.

Como importar dados de catálogo do BigQuery

Para importar dados do catálogo no formato correto do BigQuery, use o esquema de varejo para criar 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 para a API 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 importar seu catálogo:

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

  2. Importe os dados do seu catálogo para a API Retail.

    Console

    1. Acesse a página "Dados de varejo" no Console do Google Cloud.

      Acessar a página "Dados"

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

    3. Escolha Catálogo de produtos.

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

    5. Selecione BigQuery como a fonte de dados e Esquema de catálogos de produtos de varejo como o esquema.

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

    7. (Opcional) Insira o local de um bucket do Cloud Storage no 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.

    8. (Opcional) Escolha se você quer programar um upload recorrente do seu catálogo.

      Essa opção só estará disponível se você tiver importado o catálogo para a API Retail pelo menos uma vez.

    9. 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.

      Alterar os níveis de produto depois de importar todos os dados requer um esforço significativo.

    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 esse campo em branco para permitir que a API Retail crie automaticamente um diretório temporário (recomendado).
      • ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erros sobre a importação. Deixe esse campo em branco para permitir que a API Retail crie automaticamente um diretório temporário (recomendado).
      • dataSchema: para a propriedade dataSchema, use o valor product (padrão). Você usará o esquema de varejo.

      Recomendamos que você não especifique diretórios de preparo ou erro para que a API Retail possa criar automaticamente um bucket do Cloud Storage com novos diretórios de preparo e erro. Eles são criados na mesma região que o conjunto de dados do BigQuery e são exclusivos para cada importação, o que impede que vários jobs de importação organizem dados para o mesmo diretório e, possivelmente, reimportam os mesmos dados. de 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 para a API Retail fazendo uma solicitação POST para o método 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"
      

      É 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.

Como configurar o acesso ao conjunto de dados do BigQuery

Para configurar o acesso quando o conjunto de dados do BigQuery estiver em um projeto diferente do serviço de varejo, conclua as etapas a seguir.

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

    Abrir a página do IAM

  2. Selecione seu projeto de varejo.

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

    Se você ainda não iniciou uma operação de importação com a API Retail, 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 seu projeto do BigQuery (na mesma página IAM e Admin) e clique em Adicionar.

  6. Insira o identificador da conta de serviço do Retail e selecione o papel BigQuery > BigQuery User.

  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 Save.

Como importar dados de 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. A partir daí, você pode importá-lo para a API Retail.

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

Para ajuda sobre o upload de arquivos para o Cloud Storage, consulte Como fazer o upload de objetos.

  1. Verifique se a conta de serviço de varejo tem permissão para ler e gravar no bucket.

    A conta de serviço de varejo está listada na página do IAM no Console do Cloud com o nome 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 para a API Retail.

    Console

    1. Acesse a página "Dados de varejo" no Console do Google Cloud.

      Acessar a página "Dados"

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

    3. Escolha Catálogo de produtos.

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

    5. Selecione Cloud Storage como origem de dados e Esquema de catálogos de produtos de varejo como esquema.

    6. Insira o local dos seus dados no Cloud Storage.

    7. (Opcional) Insira o local de um bucket do Cloud Storage no 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.

    8. (Opcional) Escolha se você quer programar um upload recorrente do seu catálogo.

      Essa opção só estará disponível se você tiver importado o catálogo para a API Retail pelo menos uma vez.

    9. 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 seus níveis do produto. Saiba mais sobre os níveis de produto.

      Alterar os níveis de produto depois de importar todos os dados requer um esforço significativo.

    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. 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, a API Retail o criará. 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 para a API Retail fazendo uma solicitação POST para o método 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 é usar o Console do Cloud. Para mais informações, consulte Como ver 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.

Como importar dados de catálogo in-line

curl

Importe as informações do seu catálogo para a API Retail in-line. Para isso, faça umaPOST solicitação paraProducts:import REST, usando o métodoproductInlineSource para especificar os dados do seu catálogo.

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": [
        {
          <product1>
        },
        {
          <product2>
        },
        ....
      ]
    }
    }
    }
    
  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. As quebras de linha são para facilitar a leitura. Você precisa fornecer um item inteiro do produto em uma única linha. Cada item precisa estar em uma 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 }]
}

Dados históricos do catálogo

A API Retail oferece suporte para importação e gerenciamento de dados históricos 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. A API Retail pode usar informações anteriores do produto 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. Defina a disponibilidade do produto como OUT_OF_STOCK para evitar que o Recommendations AI seja afetado.

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

Chamando 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 às da importação regular in-line, exceto pelo fato de os produtos precisam ter os campos expireTime definidos como um carimbo de data/hora passado.

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

{
"inputConfig": {
  "productInlineSource": {
      "products": [
        {
          "name": "historical product 001"
          "id": "historical_product_001"
          "name": "A historical product"
          "expire_time": {
            "second": 1000000000  // a past timestamp
          }
        },
        {
          <Another product>
        },
        ....
      ]
    }
  }
}

Importar produtos expirados do BigQuery ou do Cloud Storage

Esse procedimento é semelhante à importação de produtos comuns do BigQuery ou do Cloud Storage. No entanto, defina o campo expireTime como um carimbo de data/hora no passado.

Como manter seu catálogo atualizado

A API Retail depende de informações atualizadas do produto para fornecer os melhores resultados. Recomendamos importar o catálogo diariamente para garantir que ele esteja atualizado. Use o Google Cloud Scheduler para programar importações ou escolha uma opção de programação automática ao importar dados usando o Console do 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 catálogo.

Atualização em lote

Você pode usar o método de importação para atualizar seu catálogo em lote. Isso é feito da mesma maneira que a importação inicial; siga as etapas em Como importar dados de catálogo.

Como monitorar a integridade da importação

Para garantir que não haja erros para os dados importados, verifique as métricas de carregamento de dados do seu catálogo na página Dados do varejo. A página "Dados de varejo" também mostra as métricas de qualidade para os dados do produto no seu catálogo.

É importante manter seu catálogo atualizado para conseguir resultados de alta qualidade. Monitore as taxas de erro de importação e tome as medidas necessárias. Para mais informações, consulte Como configurar alertas.

A seguir