A Vertex AI para Pesquisa no varejo vai substituir a plataforma Retail. Estamos atualizando o conteúdo para refletir o novo branding.

Esta página foi traduzida pela API Cloud Translation.

Exportar suas métricas de análise para o BigQuery

Esta página descreve como exportar as métricas de análise da Vertex AI Search para o varejo para o BigQuery. A exportação de métricas de análise permite reter as métricas e escrever SQL para sua própria análise.

As métricas de análise da Vertex AI para Pesquisa no varejo são geradas automaticamente. Para mais informações sobre como medir o impacto comercial da Vertex AI Search for Retail com métricas de análise, consulte Analisar a métrica.

A exportação de dados de métricas para o BigQuery tem as seguintes limitações:

Os dados exportados para tabelas do BigQuery no seu projeto de pesquisa da Vertex AI para varejo são visualizações autorizadas, não visualizações materializadas.
Não é possível mudar ou atualizar os dados nessas tabelas. Se você precisar mudar ou atualizar seus dados, exporte ou copie a visualização para outro destino.
Não é possível exportar métricas de eventos do usuário com mais de 180 dias ou métricas geradas há mais de 180 dias. As métricas geradas antes da janela de 180 dias não podem ser recuperadas.

Antes de começar

Antes de exportar suas métricas para o BigQuery, você precisa concluir os procedimentos em Antes de começar. Isso inclui a importação de eventos do usuário e, opcionalmente, das informações do catálogo.

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

Criar um conjunto de dados no BigQuery

Você precisa criar um conjunto de dados no BigQuery para armazenar os dados das métricas de análise.

É necessário criar os conjuntos de dados no mesmo projeto em que você implementou a Vertex AI para Pesquisa para varejo.

Se você nunca usou o BigQuery no seu projeto, ative a API BigQuery e verifique se tem o papel do IAM que permite criar conjuntos de dados e tabelas.

Consulte Antes de começar e Controle de acesso com o IAM.

na documentação do BigQuery.
Crie um conjunto de dados no BigQuery na multirregião US (várias regiões nos Estados Unidos). Por exemplo, chame-o de retail_data. Se você criar o conjunto de dados em uma região diferente, a exportação para o BigQuery vai falhar. Não é possível usar CMEK (CMEK) no conjunto de dados. Ativar essa opção faz com que a exportação falhe.

Para saber como criar um conjunto de dados, consulte Como criar conjuntos de dados 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.

Exportar as métricas de análise para uma tabela do BigQuery

Use o método exportAnalyticsMetrics para exportar seu catálogo de varejo para uma tabela do BigQuery.

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_metrics_data.
TABLE_ID_PREFIX: um prefixo para o ID da tabela. Esse prefixo não pode ser uma string vazia. Um sufixo de retail_analytics_metrics é adicionado para completar o nome da tabela. Por exemplo, se o prefixo for test, a tabela será chamada test_retail_analytics_metrics.

Corpo JSON da solicitação:

{
  "catalog": "projects/PROJECT_ID/locations/global/catalogs/default_catalog",
  "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: 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. . É possível verificar a conta ativa atual executando gcloud auth list.

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'
{
  "catalog": "projects/PROJECT_ID/locations/global/catalogs/default_catalog",
  "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 print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog:exportAnalyticsMetrics"

PowerShell (Windows)

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 . É possível verificar a conta ativa atual executando gcloud auth list.

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:

@'
{
  "catalog": "projects/PROJECT_ID/locations/global/catalogs/default_catalog",
  "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 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/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog:exportAnalyticsMetrics" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

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

Definições de métricas

As métricas exportadas são as métricas de contagem. Pode haver uma pequena variação para algumas métricas de contagem, porque a filtragem de bots pode excluir alguns eventos da computação de métricas. A filtragem de bots pode ajudar a fornecer medições de desempenho mais precisas. Isso não afeta os testes A/B, que dependem da dimensão external_experiment_ids, enquanto a filtragem de bots é aplicada a todo o tráfego.

Dimensões de métricas

As métricas de contagem são as contagens brutas agregadas diretamente de eventos de usuário relevantes com as mesmas dimensões. Para interpretar as métricas, você precisa saber em quais dimensões elas se baseiam. Para fins de métricas do Google Analytics, os eventos de pesquisa e navegação são chamados de eventos de impressão, e os eventos detail_page_view, add_to_cart e purchase são chamados de eventos de conversão. A tabela a seguir define as dimensões das métricas.

Dimensão métrica	Descrição
data	A data dos eventos relevantes que geraram as métricas. Para métricas de impressão, essa é a data dos eventos de impressão. Para métricas de sessão e visitante, essa é a data do evento de primeira impressão da sessão/visitante.
external_experiment_ids	Os IDs de experimento dos eventos relevantes que geraram as métricas. Para métricas de impressão, é o ID do experimento do evento de impressão. Para métricas de sessão e visitante, essa é a concatenação dos IDs de experimentos externos exclusivos de todos os eventos de impressão que aparecem na sessão/visitante. Por exemplo, se houver dois eventos de pesquisa em uma sessão/visitante, o primeiro evento de pesquisa tem external_experiment_ids 'test_arm_1,test_arm_2', e o segundo evento de pesquisa tem external_experiment_ids 'test_arm_1,test_arm_3', então external_experiment_ids da sessão/visitante é 'test_arm_1,test_arm_2,test_arm_3'.
device_type	O tipo de dispositivo dos eventos relevantes que geraram as métricas, por exemplo, se o evento foi gerado em um dispositivo móvel ou computador. Para métricas de impressão, esse é o tipo de dispositivo do evento de impressão. Para métricas de sessão e visitante, esse campo fica vazio se a sessão/visitante tiver mais de um tipo de dispositivo distinto ou se houver apenas um tipo de dispositivo para toda a sessão/visitante.
serving_config	A configuração de exibição dos eventos relevantes que geraram as métricas. Para métricas de impressão, essa é a configuração de veiculação do evento de impressão. Para métricas de sessão e visitante, esse campo fica vazio se a sessão/visitante tiver mais de uma configuração de exibição distinta ou se houver apenas uma configuração de exibição para toda a sessão/visitante.
traffic_destination	A origem dos eventos relevantes que geraram as métricas. Para métricas de impressão, é "Google" se a impressão for veiculada pelo Google ou "Não Google" se a impressão for veiculada pela sua própria solução. Para métricas de sessão e visitante, isso é "Misto" se a sessão/visitante tiver os dois eventos de impressão veiculados pelo Google e pela sua própria solução. "Google" se os eventos de impressão forem veiculados apenas pelo Google ou "Não Google" se os eventos de impressão forem veiculados apenas pela sua solução durante toda a sessão/visitante.
entidade	Esse recurso é usado por varejistas que atendem vários sites de marca ou regiões com um catálogo de produtos. A entidade geralmente representa as marcas ou locais. Para métricas de impressão, essa é a entidade do evento de impressão. Para métricas de sessão e visitante, são as cinco principais entidades contabilizadas dos eventos de impressão da sessão/visitante.

Métricas de impressões

As métricas de impressão são calculadas de acordo com os pré-requisitos. Os eventos de conversão (detail_page_view, add_to_cart e purchase) só podem ser atribuídos a um evento de impressão se corresponderem aos seguintes critérios.

O evento de impressão e o evento de conversão têm o mesmo visitante.
O ID do produto do evento de conversão precisa aparecer nos resultados do evento de impressão.

O evento de conversão está dentro da janela de tempo necessária após a ocorrência do evento de impressão. Janelas de conversão diferentes se aplicam a diferentes tipos de eventos de conversão.

Caminho de conversão	Janela de conversão
Impressão -> Visualização da página de detalhes	60 segundos
Impressão -> Adicionar ao carrinho	24 horas
Impressão -> compra	48 horas

Métricas de impressões de pesquisa

Nome da métrica	Descrição
search_event	Contagem de eventos de pesquisa
detail_page_view_from_search	Contagem de eventos de visualização da página de detalhes da pesquisa
add_to_cart_unit_from_search	Adicionar ao carrinho a contagem de unidades da pesquisa
purchase_unit_from_search	Contagem de unidades de compra na pesquisa
revenue_from_search	Receita da pesquisa
search_event_without_result	Contagem de eventos de pesquisa que não geram resultados
search_request_personalization_enabled	Contagem de solicitações de pesquisa com a personalização ativada
search_request_personalization_result_served	Contagem de solicitações de pesquisa que são exibidas com resultados personalizados

Procurar métricas de impressões

Nome da métrica	Descrição
browse_event	Contagem de eventos de navegação
detail_page_view_from_browse	Contagem de eventos de visualização da página de detalhes da navegação
add_to_cart_unit_from_browse	Contagem de unidades "Adicionar ao carrinho" da navegação
purchase_unit_from_browse	Contagem de unidades compradas na navegação
revenue_from_browse	Receita de navegação
browse_event_without_result	Contagem de eventos de navegação que não gera resultados
browse_request_personalization_enabled	Contagem de solicitações de navegação com a personalização ativada
browse_request_personalization_result_served	Contagem de solicitações de navegação que são exibidas com resultados personalizados

Métricas de sessão

Uma sessão é definida como um período contínuo de interação entre um usuário e o sistema. Qualquer evento do usuário marca o início de uma sessão, e o fim de uma sessão é marcado quando nenhum outro evento ocorre nos próximos 30 minutos. A sessão é estendida por mais 30 minutos sempre que um evento de usuário ocorre em uma sessão iniciada. Depois que uma sessão termina, uma nova sessão começa quando o usuário interage com o sistema novamente.

As dimensões que caracterizam as métricas da sessão são definidas em conjunto por todos os eventos do usuário na sessão. Consulte dimensões de métricas para saber como os valores de dimensões são definidos para a sessão.

Nome da métrica	Descrição
sessão	Contagem de sessões

Métricas de sessão de pesquisa

Uma sessão de pesquisa é uma sessão que contém pelo menos um evento de pesquisa. Uma sessão de pesquisa também pode ser uma sessão de navegação, conforme definido pelas métricas de sessão de navegação.

Nome da métrica	Descrição
search_session	Contagem de sessões que envolvem uma pesquisa
search_event_in_search_session	Contagem de eventos de pesquisa nas sessões de pesquisa
browse_event_in_search_session	Contagem de eventos de navegação nas sessões de pesquisa
detail_page_view_in_search_session	Contagem de visualizações de página de detalhes nas sessões de pesquisa
add_to_cart_in_search_session	Contagem de eventos de adição ao carrinho nas sessões de pesquisa
add_to_cart_unit_in_search_session	Contagem de unidades de "Adicionar ao carrinho" nas sessões de pesquisa
purchase_order_in_search_session	Contagem de ordens de compra em sessões de pesquisa
purchase_unit_in_search_session	Contagem de unidades de compra em sessões de pesquisa
revenue_in_search_session	Receita em sessões de pesquisa
bounce_count_in_search_session	Contagem de sessões do visitante que sai do site após visualizar apenas uma página nas sessões de pesquisa

Procurar métricas da sessão

Uma sessão de navegação é uma sessão que contém pelo menos um evento de navegação. Uma sessão de navegação também pode ser uma sessão de pesquisa, conforme definido pelas métricas de sessão de pesquisa.

Nome da métrica	Descrição
browse_session	Contagem de sessões que envolvem navegação
search_event_in_browse_session	Contagem de eventos de pesquisa nas sessões de navegação
browse_event_in_browse_session	Contagem de eventos de navegação nas sessões de navegação
detail_page_view_in_browse_session	Contagem de visualizações de página de detalhes nas sessões de navegação
add_to_cart_in_browse_session	Contagem de eventos de adição ao carrinho nas sessões de navegação
add_to_cart_unit_in_browse_session	Contagem de unidades "Adicionar ao carrinho" nas sessões de navegação
purchase_order_in_browse_session	Contagem de ordens de compra nas sessões de navegação
purchase_unit_in_browse_session	Contagem de unidades de compra nas sessões de navegação
revenue_in_browse_session	Receita nas sessões de navegação
bounce_count_in_browse_session	Contagem de sessões do visitante que saiu do site após visualizar apenas uma página nas sessões de navegação

Métricas de visitantes

Um visitante é identificado de forma exclusiva pelo ID. As métricas de visitantes agregam todas as informações de eventos do usuário para o visitante.

As dimensões que caracterizam as métricas do visitante são definidas em conjunto por todos os eventos do usuário para o visitante. Consulte dimensões de métricas para saber como os valores de dimensões são definidos para o visitante.

Nome da métrica	Descrição
visitante	Contagem de visitantes

Métricas de visitantes da pesquisa

Um visitante de pesquisa é aquele que realiza pelo menos um evento de pesquisa. Um visitante de pesquisa também pode ser um visitante de navegação, conforme definido pelas métricas de visitante de navegação.

Nome da métrica	Descrição
search_visitor	Contagem de visitantes que fazem pelo menos uma pesquisa
search_event_from_search_visitor	Contagem de eventos de pesquisa de visitantes da pesquisa
browse_event_from_search_visitor	Contagem de eventos de navegação dos visitantes da pesquisa
detail_page_view_from_search_visitor	Contagem de visualizações da página de detalhes dos visitantes da pesquisa
add_to_cart_from_search_visitor	Contagem de eventos de adição ao carrinho dos visitantes da pesquisa
add_to_cart_unit_from_search_visitor	Contagem de unidades "Adicionar ao carrinho" de visitantes que pesquisam
purchase_order_from_search_visitor	Contagem de ordens de compra de visitantes da pesquisa
purchase_unit_from_search_visitor	Unidade de contagem de compras de visitantes da pesquisa
revenue_from_search_visitor	Receita de visitantes da pesquisa

Procurar métricas de visitantes

Um visitante de navegação é aquele que realiza pelo menos um evento de navegação. Um visitante de navegação também pode ser um visitante de pesquisa, conforme definido pelas métricas de visitantes de pesquisa.

Nome da métrica	Descrição
browse_visitor	Contagem de visitantes que realizam pelo menos uma navegação
search_event_from_browse_visitor	Contagem de eventos de pesquisa de visitantes de navegação
browse_event_from_browse_visitor	Contagem de eventos de navegação dos visitantes
detail_page_view_from_browse_visitor	Contagem de visualizações da página de detalhes dos visitantes da navegação
add_to_cart_from_browse_visitor	Contagem de eventos "Adicionar ao carrinho" de visitantes que navegaram pelo site
add_to_cart_unit_from_browse_visitor	Contagem de unidades "Adicionar ao carrinho" de visitantes que navegaram
purchase_order_from_browse_visitor	Contagem de pedidos de compra de visitantes de navegação
purchase_unit_from_browse_visitor	Contagem de unidades de compra de visitantes que navegam
revenue_from_browse_visitor	Receita de visitantes que navegam

Exemplo de uso

Se você copiar ou exportar os dados de métricas para outro destino, poderá usar o SQL para receber informações gerais ou específicas sobre as métricas exportadas. Algumas maneiras comuns de analisar as métricas exportadas usando SQL são fornecidas nas seções a seguir.

Calcular a taxa de cliques (CTR)

Calcule a CTR da pesquisa por data, tipo de dispositivo e destino de tráfego.

SELECT
  `date`,
  device_type,
  traffic_destination,
  SUM(detail_page_view_from_search) / SUM(search_event) as search_CTR
FROM copied_table
GROUP BY `date`, device_type, traffic_destination

Conferir a contagem de visualizações da página de detalhes com base na navegação

Receba eventos de visualização de página detalhada que vêm de eventos de navegação para tráfego do Google com external_experiment_ids contendo test_arm e mostre todas as informações de dimensão. external_experiment_ids é repetido string.

SELECT
  `date`,
  external_experiment_ids,
  device_type,
  serving_config,
  traffic_destination,
  entity,
  detail_page_view_from_browse
FROM copied_table
WHERE
  traffic_destination = 'Google' AND 'test_arm' in UNNEST(external_experiment_ids)

Acessar as configurações de veiculação mais usadas

Receba as configurações de exibição mais usadas entre "2023-10-01" e "2023-11-01" para o tráfego do Google. Cada evento de pesquisa precisa ter uma configuração de veiculação associada.

SELECT
  serving_config,
  SUM(search_event) as total_search_count
FROM copied_table
WHERE `date` between '2023-10-01' and '2023-11-01' AND traffic_destination = 'Google'
GROUP BY serving_config
ORDER BY total_search_count