Incorporar o Looker com as Análises de conversação

1. Antes de começar

Este codelab vai orientar você na integração de um painel do Looker incorporado com um chat de análise de conversação para criar uma experiência de dados unificada com tecnologia de linguagem natural. Para aproveitar ao máximo, você precisa conhecer a incorporação do Looker, a análise de conversas, o JavaScript e o React.

O que você vai aprender

Depois de seguir este codelab, você vai aprender:

• Como configurar o aplicativo de referência de incorporação do Looker localmente
• Como criar um componente de chat do React com a biblioteca de componentes do Looker
• Como enviar o filtro do painel incorporado como contexto para as Análises de Conversação
• Como ativar o chat com tecnologia de Análises de Conversação para controlar os filtros do painel incorporado

O que é necessário

Para concluir este codelab, você vai precisar de:

• Uma instância do Looker com o Looker Block de dados demográficos da ASC instalado e a incorporação de SSO ativada
• Acesso de API e desenvolvedor à sua instância do Looker
• Um ambiente local com Node v18, yarn, Git e gcloud instalados
• Um projeto na nuvem com estes papéis do IAM configurados para sua conta de usuário:
• roles/bigquery.dataViewer Leitor de dados do BigQuery
• roles/bigquery.user Usuário do BigQuery
• roles/looker.instanceUser Usuário da instância do Looker

2. Configurar as Análises de Conversação

Vamos configurar o agente de dados das Análises de conversação que o chat do painel incorporado vai usar para responder a perguntas em linguagem natural.

Autenticação com gcloud

1. Autentique com sua conta de usuário no ambiente local:

gcloud auth login

2. Defina o Application Default Credentials (ADC) e o projeto de faturamento na gcloud:

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Ativar as APIs Análises de conversação

3. Ative as APIs do projeto na nuvem. Substitua YOUR_PROJECT_ID pelo ID do seu projeto do Google Cloud:

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

Criar o agente de dados

4. Abra o Google Colab.
5. No Google Colab, carregue este notebook do repositório de referência de incorporação do Looker.
6. Execute todas as etapas do notebook. Você vai precisar do ID do projeto na nuvem e do URI da instância do Looker com uma barra invertida no final, como "https://my.looker.app/". Você vai ter um resultado positivo no final do notebook.

Agora você tem um agente de dados da Análise de conversação disponível e pronto para aceitar mensagens de chat, consultar as análises detalhadas do Looker no painel integrado do Looker e retornar resultados e visualizações.

3. Configurar a referência de incorporação do Looker

Vamos configurar o aplicativo de referência de incorporação do Looker no seu ambiente local para que você possa testar o exemplo de integração do chat de Análises de conversação com um painel do Looker incorporado.

Clonar o repositório

1. Clone o repositório do GitHub no seu ambiente local. Confira o exemplo de comando abaixo:

git clone "https://github.com/looker-open-source/LookerEmbedReference.git"

2. Navegue até o diretório LookerEmbedReference que você clonou:

cd LookerEmbedReference

Configurar e executar o servidor de front-end local

3. Instale as dependências no diretório Frontend.

cd Frontend
yarn install

4. Configure um arquivo .env na raiz do diretório Frontend com credenciais. YOUR_LOOKER_INSTANCE_URI precisa ser o URI da sua instância do Looker sem barra final. O conteúdo do arquivo deve ser o seguinte:

PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI

Use o seguinte comando de exemplo para criar o arquivo:

cat > .env <<'EOF'
PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
EOF

5. Execute o servidor de desenvolvimento de front-end:

yarn run dev

Configurar e executar o servidor de back-end localmente

6. Abra um novo shell, terminal, console ou guia. Acesse o diretório Backend-Node e instale as dependências. Mantenha o shell/terminal anterior com o servidor de front-end em execução.

cd ../Backend-Node
yarn install

7. Configure um arquivo .env na raiz do diretório Backend-Node com credenciais:

• YOUR_LOOKER_CLIENT_ID é o ID do cliente do Looker.
• YOUR_LOOKER_CLIENT_SECRET é a chave secreta do cliente do Looker.
• YOUR_LOOKER_EMBED_SECRET é seu segredo de incorporação.
• YOUR_PROJECT_ID é seu ID do projeto do Cloud.
• YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH é o URI da sua instância do Looker com uma barra invertida no final.
• YOUR_LOOKER_INSTANCE_URI é o URI da sua instância do Looker sem barra no final.

O conteúdo do arquivo deve ser o seguinte:

PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID

Use o exemplo de comando a seguir para criar o arquivo. Substitua todas as credenciais conforme necessário:

cat > .env <<'EOF'
PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID
EOF

8. Execute o servidor de desenvolvimento de back-end:

yarn run dev

Agora você tem o servidor de desenvolvimento front-end em execução, atendendo ao JavaScript do aplicativo da Web. Você também precisa ter o servidor de desenvolvimento de back-end em execução para cuidar das solicitações de URL de incorporação do SSO e das solicitações de proxy para os endpoints de Análises de conversação.

4. Teste o exemplo

Vamos testar seu aplicativo da Web agora em execução localmente no seu ambiente.

Iniciar uma conversa

1. Abra o endereço https://localhost:3001 no navegador de sua preferência.
2. Acesse a página Painel incorporado com chat na navegação principal à esquerda.
3. Quando o componente de chat à direita for carregado, digite: "Olá, quem é você?"
4. Observe a resposta.

O aplicativo criou automaticamente um objeto de Análises de conversação conversa para rastrear o histórico de chat e carregou a interface de chat. Quando você fez uma pergunta à interface de chat, o front-end enviou uma mensagem do usuário ao servidor de back-end local do Node. Em seguida, ele encaminhou a solicitação e a resposta para o endpoint de chat das Análises de conversação.

Filtrar o painel incorporado

Agora, conheça o painel incorporado e interaja com ele.

5. Role o painel incorporado. Ele abrange dados do censo em várias dimensões e métricas.
6. Você pode filtrar o painel por Estado e Condado no canto superior esquerdo. Defina o filtro no painel como Texas. Em seguida, selecione o botão de seta circular destacado em azul para executar o painel de novo.
7. Observe como todos os dados de visualizações são filtrados no estado do Texas.

Fazer uma pergunta com o contexto do painel

Agora que filtramos o painel, vamos continuar investigando os dados nele.

8. Envie "Quais são os cinco municípios com os aluguéis mais baratos?" no chat.
9. Sua solicitação para a Análise de Conversação agora contém as palavras adicionais "Filtrar na dimensão 'state.state_name' sendo Texas".
10. Agora, observe que a consulta e os dados da resposta são filtrados no estado do Texas.
11. Além disso, depois que os resultados dos dados foram retornados, o painel incorporado foi executado novamente com o filtro Condado definido como os cinco condados definidos nos dados do resultado.

Agora você pode continuar investigando os dados do censo com os cinco condados filtrados para você.

Parabéns! Você configurou e testou um exemplo simples de um painel incorporado integrado a um chat do Análises de conversação.

5. Criar um componente de chat

Vamos entender o que está acontecendo nos bastidores. Primeiro, vamos analisar o componente Chat. Presumimos que você sabe como incorporar um painel do Looker com o SDK Embed do Looker.

Usar a biblioteca de componentes do Looker

1. Abra o arquivo de componente Chat em Frontend/src/components/EmbedChat/components/chat.js no seu IDE ou terminal preferido.
2. O componente Chat é criado com componentes React da interface do Looker padrão do pacote Biblioteca de componentes do Looker.

A biblioteca de componentes do Looker permite a integração perfeita entre o conteúdo do Looker e seu aplicativo. Ela oferece componentes React pré-criados que se alinham aos estilos e componentes em um painel do Looker incorporado.

Enviar uma mensagem para um usuário

A interface de chat precisa enviar um comando do usuário para a análise de conversas.

3. Perto da parte de baixo do arquivo de componente Chat, o componente Chat contém o subcomponente ChatInput, que fornece o campo de entrada para um comando do usuário.
4. Ao enviar, o método showAndSendUserPrompt envia o comando do usuário para a Análise de conversação (proxy pelo back-end do Node).

Fazer streaming e mostrar mensagens do sistema

Depois que o usuário enviar uma mensagem para o Análises de conversação, precisamos mostrar a resposta.

5. Perto da parte de baixo do arquivo de componente Chat, o componente Chat contém o subcomponente MessageList, que tem a lógica para mostrar as mensagens da análise de conversas com base no tipo da mensagem.
6. O método streamAndParseResponse processa a resposta tentando analisar constantemente mensagens válidas do sistema na resposta JSON de streaming. Sempre que uma mensagem válida do sistema é analisada com sucesso, ela aparece no MessageList.

Recomendamos que você mostre as mensagens do sistema da Análise de conversas assim que elas chegarem para uma experiência do usuário mais responsiva.

A resposta da análise de conversa a um comando do usuário consiste em várias mensagens do sistema, que abrangem as origens de dados consultadas, a consulta, os resultados, as visualizações e muito mais. A espera de todas as mensagens do sistema pode levar o usuário a presumir problemas de desempenho ou de aplicativo.

Agora você aprendeu como o componente Chat, criado com a biblioteca de componentes do Looker, envia uma mensagem do usuário e transmite a resposta.

6. Enviar filtros do painel para as Análises de Conversação

Agora vamos entender como incluir os filtros do painel em um comando do usuário para que a Análise de dados de conversação possa filtrar a consulta com o contexto do painel (os filtros dele).

Detectar o evento de mudança de filtro do painel

1. Abra o arquivo do componente EmbedChat em Frontend/src/components/EmbedChat/EmbedChat.js,, que representa a página do aplicativo com o painel incorporado integrado ao componente Chat analisado anteriormente.
2. O componente EmbedChat detecta o evento "dashboard:filters:changed" do painel incorporado com o método .on(...) do SDK Embed. Em seguida, o componente armazena os filtros atuais no estado do filtro.

Enviar o estado do filtro para as Análises de Conversação

3. O componente EmbedChat transmite os filtros para o componente Chat, que converte cada filtro em uma string como "Filter on dimension '...' being ..." no método showAndSendUserPrompt para ser adicionado ao comando do usuário.

O nome ou a chave de um filtro de painel não é necessariamente o mesmo que o nome da dimensão real. É necessário mapear a chave do filtro para o nome real da dimensão para que a Análise de conversas entenda quais dimensões filtrar.

Nesse caso, por exemplo, no componente Chat, o objeto FIELD_FILTER_MAP mapeia o nome da dimensão "state.state_name" para a chave do filtro "State 📍". Em seguida, o método showAndSendUserPrompt usa o mapa para determinar o nome da dimensão a ser filtrada.

7. Controlar filtros do painel pelo chat

Por fim, vamos conferir como ativar o componente Chat para controlar os filtros do painel incorporado.

Determine quais filtros definir

1. O método streamAndParseResponse do componente Chat sempre verifica uma mensagem do sistema com os resultados de dados das Análises de conversação.
2. Sempre que o método streamAndParseResponse analisa uma mensagem do sistema com resultados de dados, ele verifica se alguma dimensão nos dados corresponde às dimensões nos filtros.
3. Se sim, o método streamAndParseResponse converte as colunas de dados em filtros do painel. Desta vez, o método usa FIELD_FILTER_MAP novamente, mas ao contrário, convertendo do nome da dimensão para a chave do filtro. Os valores do filtro são os valores na coluna de dados.

Enviar evento de mudança de filtro para o painel incorporado

4. Com os filtros de painel desejados, o método streamAndParseResponse chama o método setFilters do componente Chat com os filtros desejados.
5. Isso chama o método setDashboardFilters do componente EmbedChat, que envia dois eventos, "dashboard:filters:update" com os filtros e "dashboard:run" para o painel incorporado em sucessão imediata usando o método send do SDK de incorporação.
6. O evento "dashboard:filters:update" muda os filtros do painel incorporado, enquanto o evento "dashboard:run" executa novamente as consultas do painel com os novos filtros.

É preciso enviar o "dashboard:run" depois do evento "dashboard:filters:update". O evento "dashboard:filters:update" não executa novamente as consultas do painel automaticamente.

8. Conclusão e principais pontos

Você configurou seu próprio exemplo funcional de um painel do Looker incorporado integrado ao chat das Análises de Conversação. Você aprendeu a ativar a análise de dados com linguagem natural usando o painel do Looker incorporado e as Análises de conversação.

• Você criou um componente de chat com a biblioteca de componentes do Looker.
• Você transmitiu o contexto do painel incorporado do Looker para as Análises de Conversação e facilitou a análise de dados.
• Você ativou as Análises de conversação para controlar os filtros do painel incorporado e ter mais contexto ao analisar os dados.

A seguir

• Saiba mais sobre os recursos da Análise de conversação.
• Atualize o app de exemplo Referência de incorporação do Looker para trabalhar com seus próprios painéis incorporados do Looker.
• Teste os outros casos de uso de incorporação disponíveis no app de exemplo Referência de incorporação do Looker em execução local.