Exportar seus dados para o BigQuery

Esta página descreve como fazer upload de dados de produtos de varejo e eventos do usuário no BigQuery. Depois que os dados estiverem no BigQuery, usá-lo para realizar previsões de vendas com a Vertex AI e para visualizar os dados em painéis pré-criados do Looker.

Se seus dados de varejo já estiverem nas tabelas de eventos de produtos e usuários em No BigQuery, no formato da Vertex AI para Pesquisa para Retail, você pode pular esta parte página e acessar diretamente Acessar painéis que mostram os principais indicadores e Gerar previsões de vendas do varejo dados. Para mais informações sobre o formato, consulte Esquema do produto e Sobre os eventos do usuário.

Antes de começar

Antes de exportar seus dados de varejo para o BigQuery, você precisa ter concluído os procedimentos em Antes de começar. Isso inclui importando as informações do catálogo e os eventos do usuário.

Para mais informações sobre importação, consulte:

• Importar informações do catálogo
• Registrar eventos do usuário em tempo real
• Importar eventos históricos do usuário

Criar um conjunto de dados no BigQuery

Você precisa criar um ou dois conjuntos de dados no BigQuery para manter seu dados de eventos do produto e do usuário. Você pode usar um conjunto de dados para armazenar os dois tipos de dados ou criar dois conjuntos de dados, um para cada tipo de dados.

Você precisa criar os conjuntos de dados no mesmo projeto em que os implementou. Vertex AI para Pesquisa para Retail.

1. Se você ainda não usou o BigQuery na sua antes, ative a API BigQuery e verifique se você ter o papel do IAM que permite a criação de conjuntos de dados e tabelas.

   Consulte Antes de começar e Controle de acesso com o IAM na documentação do BigQuery.

2. Crie um conjunto de dados no BigQuery nos EUA (várias regiões em Estados Unidos) (link em inglês). Por exemplo, nome retail_data. Se você criar o conjunto de dados em uma região diferente, a exportação para o BigQuery vai falhar.

   Para obter informações sobre como criar um conjunto de dados, consulte Como criar conjuntos de dados na na documentação do BigQuery.

   Esse conjunto de dados será usado para armazenar as tabelas de dados exportadas. Os procedimentos a seguir descrevem como exportar.

3. Opcional: para colocar os dados de eventos do usuário em um conjunto de dados separado do os dados do produto, crie um segundo conjunto. Por exemplo, dê um nome retail_user_event_data:

Exportar o catálogo da Vertex AI para Pesquisa no varejo para uma tabela do BigQuery

Use o método ExportProducts para exportar seu catálogo de varejo para um Tabela do BigQuery.

Observação: O comando a seguir presume que você fez login no a CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando Cloud Shell, que conecta você automaticamente à CLI gcloud.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: o ID do projeto da API Vertex AI Search for Retail em que você criou o conjunto de dados do BigQuery.
• BRANCH_ID: o ID da ramificação do catálogo. Use default_branch para receber dados da ramificação padrão. Para mais informações, consulte Filiais do catálogo.
• DATASET_ID: o nome do conjunto de dados que você criou em Criar um conjunto de dados no BigQuery. Por exemplo, use retail_data ou retail_product_data. O conjunto de dados precisa estar no mesmo projeto. Não adicione o ID do projeto ao campo datasetId.
• TABLE_ID_PREFIX: um prefixo para o ID da tabela. Esse prefixo não pode ser uma string vazia. Um sufixo de retail_products é adicionado para completar o nome da tabela. Por exemplo, se o prefixo for test, a tabela será chamada test_retail_products.

Corpo JSON da solicitação:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS no caminho do arquivo de chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST:

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

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS no caminho do arquivo de chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/branches/BRANCH_ID/products:export" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/operations/17986570020347019923",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportProductsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_products"
        }
      ]
    }
  }
}

Exportar os eventos do usuário para uma tabela do BigQuery

Use o método userEvents.export para exportar seus eventos de usuário de varejo para um Tabela do BigQuery:

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: o ID do projeto da API Vertex AI Search for Retail em que você criou o conjunto de dados do BigQuery.
• DATASET_ID: o nome do conjunto de dados que você criou em Criar um conjunto de dados no BigQuery. Por exemplo, use retail_data ou retail_product_data.
• TABLE_ID_PREFIX: um prefixo para o ID da tabela. Esse prefixo não pode ser uma string vazia. Um sufixo de retail_products é adicionado para completar o nome da tabela. Por exemplo, se o prefixo for test, a tabela será chamada test_retail_products.

Corpo JSON da solicitação:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS no caminho do arquivo de chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export"

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS no caminho do arquivo de chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/17203443067109586170",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportUserEventsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_user_events"
        }
      ]
    }
  }
}

Sobre os dados exportados

Confira algumas informações importantes sobre os dados de varejo para onde você exporta Tabelas do BigQuery:

• Os dados exportados para as tabelas do BigQuery no seu projeto são visualizações autorizadas, não visualizações materializadas.

• Não é possível alterar ou atualizar os dados nessas tabelas.

• Os produtos são atualizados a cada hora.

• Os eventos do usuário são atualizados quase em tempo real.

Sobre os dados de eventos do usuário exportados

Confira algumas informações importantes sobre as informações do produto incluídas no dados de eventos do usuário exportados.

Informações de preço do produto

A forma como as informações de preço do produto são retornadas pelo método userEvents.export depende do seguinte:

• Você incluiu informações de preço nos dados de eventos do usuário no momento a ingestão de streaming. Quando você chamar userEvents.export , o preço retornado com um evento de usuário é o preço do produto no o horário do evento.

• Você não incluiu informações de preço com os dados de eventos dos usuários, mas você incluiu informações de preço nos dados de seus produtos no momento a ingestão de streaming. Quando você chamar userEvents.export , o preço retornado com um evento do usuário não será necessariamente o preço do produto no momento do evento. É o preço encontrado no dados do produto no momento da ingestão.

• Você não incluiu informações de preço nos dados de eventos do usuário e não há informações de preço disponíveis nos dados do produto. Quando você chama o método userEvents.export, nenhum preço é retornado com eventos de usuário.

Outras informações do produto

Todas as informações do produto (exceto o preço) são combinadas com as informações do evento do usuário no momento em que você chama o método userEvents.export. Os valores do produto podem mudar de da hora do evento do usuário até a hora que você chama userEvents.export. Por esse motivo, os valores de produtos que não são de preço retornados na tabela de eventos do usuário podem ser diferentes dos valores do produto no momento do evento do usuário.

Opcional: confirmar se as novas tabelas estão no BigQuery

Depois de exportar os dados de produtos e de eventos do usuário para o BigQuery, verifique se as novas tabelas estão presentes.

1. No BigQuery, navegue até o conjunto de dados que você criou em Criar conjunto de dados no BigQuery.

2. Abra o(s) conjunto(s) de dados e verifique se as duas tabelas que você exportou estão aparecendo. Por exemplo, procure tabelas com nomes que terminam em retail_products e retail_user_events.