Esta é a documentação apenas do Recommendations AI. Para testar a pesquisa de varejo e o console unificado de varejo na fase restrita do GA, entre em contato com a equipe de vendas do Cloud. Se você não quiser usar a pesquisa de varejo, permaneça no console de recomendações até novo aviso.

Se você estiver usando a versão v1beta do Recommendations AI, migre para a versão da API Retail.

Como importar informações de catálogo

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

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.

Você precisa escolher os níveis do produto antes de importar o catálogo e precisa ter o papel do IAM de Administrador de varejo para realizar a importação.

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

O Recommendations AI requer dados de alta qualidade para fazer previsões 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 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. Use o Google Cloud Scheduler para automatizar essa tarefa.

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

Como importar dados de catálogo

Importe os dados dos seus produtos do Merchant Center, do Cloud Storage, do BigQuery ou especifique os dados in-line na solicitação. Cada um desses procedimentos são importações únicas. Recomendamos importar o catálogo diariamente para garantir que ele 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.

Como importar dados de catálogo do Merchant Center

É possível importar dados de catálogo do Merchant Center usando o Console do Cloud ou a API Retail.

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 o Recommendations AI possa acessar o conjunto de dados do BigQuery. Saiba mais.

  3. Importe os dados de catálogo do BigQuery para o Recommendations AI.

    Console

    1. Acesse a página "Dados de Recommendations AI" no Console do Google Cloud.
      Acessar a página "Dados de Recommendations AI"
    2. Clique em Importar para abrir o painel Importar catálogo.
    3. Insira os IDs do conjunto de dados e da tabela do BigQuery em que os dados estão localizados.
    4. Insira o local de um bucket do Cloud Storage no projeto.

      Esse bucket é usado como um local temporário para seus dados.

    5. Se esta for a primeira vez que você está importando seu catálogo ou se estiver importando novamente um após a limpeza, selecione os níveis do produto para upload (gravação de eventos do usuário) e previsão.

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

    6. Clique em Importar.

    cURL

    1. Se esta for a primeira vez que você está fazendo upload do catálogo ou se estiver reimportando um após a limpeza, defina o níveis do produto usando o Catalog.patch. Essa operação requer o papel de Administrador de varejo.

      • 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 o Recommendations AI 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 o Recommendations AI 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 o Recommendations AI 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 importando os mesmos dados novamente. 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_recommendations_ai). 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 importar dados de catálogo do BigQuery

Para importar dados do catálogo no formato correto do BigQuery, use o esquema do Recommendations AI para criar uma tabela do BigQuery com o formato correto e carregue a tabela vazia com os dados do catálogo. Em seguida, faça upload dos seus dados para o Recommendations AI.

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.

curl

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

  2. Se esta for a primeira vez que você está carregando seu catálogo, ou se estiver importando novamente o catálogo após a limpeza, defina os níveis do produto usando o . Catalog.patch. Essa operação requer o papel de administrador da Recommendations AI.

    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"
    
  3. Crie um arquivo de dados para os parâmetros de entrada para a importação. Os valores do parâmetro de entrada dependem da importação do Cloud Storage ou do BigQuery.

    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 a origem do BigQuery está. Se não for especificado, o ID do projeto será herdado da solicitação pai.
    • staging-directory: opcional. Um diretório do Cloud Storage usado como um local temporário para seus dados antes de serem importados para o BigQuery. Deixe esse campo em branco para permitir que o Recommendations AI crie automaticamente um diretório temporário (recomendado).
    • error-directory: opcional. Um diretório do Cloud Storage para informações de erro sobre a importação. Deixe esse campo em branco para permitir que o Recommendations AI crie automaticamente um diretório temporário (recomendado).
    • dataSchema: para a propriedade dataSchema, use o valor product (padrão). Você usará o esquema do Recommendations AI.

    Recomendamos que você não especifique diretórios de preparo ou erro para que o Recommendations AI 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 importando os mesmos dados novamente. 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_recommendations_ai). 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"}
      }
    }
    
  4. Importe as informações do seu catálogo para o Recommendations AI fazendo uma solicitação POST ao método REST Products:import, fornecendo o nome do arquivo de dados (presente em 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 sua 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. Para solicitar o status desse objeto, 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/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"
    }
    }
    

    Inspecione os arquivos no diretório de erros no Cloud Storage para ver que tipo de erros ocorreu 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 Recommendations AI, 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 do Recommendations AI.

  3. Encontre a conta de serviço com o nome Conta de serviço do AutoML Recommendations.

    Se você ainda não iniciou uma operação de importação com o Recommendations AI, essa conta de serviço poderá 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-recommendationengine.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 Recommendations AI e selecione o papel BigQuery > 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 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í, é possível importá-lo para o Recommendations AI.

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.

curl

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

    A conta de serviço do Recommendations AI está listada na página do IAM no Console do Cloud com o nome Conta de serviço de varejo. Use o identificador, 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. Se esta for a primeira vez que você está carregando seu catálogo, ou se estiver importando novamente o catálogo após a limpeza, defina os níveis do produto usando o . Catalog.patch.

    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"
    
  3. 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, o Recommendations AI o criará. O bucket já precisa existir.

    {
    "inputConfig":{
     "gcsSource": {
       "inputUris": ["input-file1", "input-file2"]
     }
    },
    "errorsConfig":{"gcsPrefix":"error-directory"}
    }
    
  4. Importe as informações do seu catálogo para o Recommendations AI fazendo uma solicitação POST ao método REST Products:import, fornecendo o nome do arquivo de dados (presente em 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 sua 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 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"
    }
    }
    

    Inspecione 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 o Recommendations AI inline. Faça uma solicitação POST ao método REST Products:import usando o productInlineSource para especificar os dados do 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"
    

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 de produto inteiro 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://foobar",
  "images": [{"uri": "http://foobar/img1", "height": 320, "width": 320 }]
}

Como manter seu catálogo atualizado

O Recommendations AI depende das informações atuais do produto para fornecer as melhores recomendações. Recomendamos que você importe o catálogo diariamente para garantir que ele esteja atualizado. Use o Google Cloud Scheduler para programar importações.

É 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

É importante manter seu catálogo atualizado para receber recomendações 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 para problemas de upload de dados.

A seguir