Incorpore componentes visuais do Amazon Quick Sight em aplicativos web usando a automação do Amazon Cognito e do IaC - Recomendações da AWS
ResumoPré-requisitos e limitaçõesArquiteturaFerramentasPráticas recomendadasÉpicosSolução de problemasRecursos relacionados

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Incorpore componentes visuais do Amazon Quick Sight em aplicativos web usando a automação do Amazon Cognito e do IaC

Ishita Gupta e Srishti Wadhwa, Amazon Web Services

Resumo

Esse padrão fornece uma abordagem especializada para incorporar componentes visuais do Amazon Quick Sight em aplicativos React usando a incorporação de usuários registrados com autenticação simplificada do Amazon Cognito. Esses recursos são então implantados por meio de um modelo de infraestrutura como código (IaC). Diferentemente da incorporação tradicional de painéis, essa solução isola tabelas e gráficos específicos para integração direta aos aplicativos React, o que melhora drasticamente o desempenho e a experiência do usuário.

A arquitetura estabelece um fluxo de autenticação eficiente entre o gerenciamento de usuários do Amazon Cognito e as permissões do Quick Sight: os usuários se autenticam por meio do Amazon Cognito e acessam suas visualizações autorizadas com base nas regras de compartilhamento do painel no Quick Sight. Essa abordagem simplificada elimina a necessidade de acesso direto ao console do Quick Sight, mantendo controles de segurança robustos.

O ambiente completo é implantado por meio de um único AWS CloudFormation modelo que provisiona todos os componentes de infraestrutura necessários, incluindo:

  • Um back-end sem servidor que usa o Amazon API AWS Lambda Gateway

  • Hospedagem de front-end segura por meio da Amazon CloudFront, Amazon Simple Storage Service (Amazon S3) e AWS WAF

  • Gerenciamento de identidade usando o Amazon Cognito

Todos os componentes são configurados seguindo as melhores práticas de segurança com políticas, AWS WAF proteção e criptografia de privilégios mínimos AWS Identity and Access Management (IAM). end-to-end

Essa solução é ideal para equipes de desenvolvimento e organizações que desejam integrar análises seguras e interativas em seus aplicativos, mantendo um controle refinado sobre o acesso do usuário. A solução usa serviços AWS gerenciados e automação para simplificar o processo de incorporação, aprimorar a segurança e garantir a escalabilidade para atender às necessidades comerciais em evolução.

Público-alvo e casos de uso:

  • Desenvolvedores de front-end que desejam incorporar análises em aplicativos React

  • Equipes de produtos de software como serviço (SaaS) que desejam oferecer visualizações de dados por usuário ou baseadas em função

  • Arquitetos de soluções interessados em integrar AWS análises em portais personalizados

  • Desenvolvedores de business intelligence (BI) que desejam expor imagens a usuários autenticados sem precisar de acesso total ao painel

  • Equipes corporativas que desejam incorporar gráficos interativos do Quick Sight em ferramentas internas

Pré-requisitos e limitações

Pré-requisitos

Para implementar esse padrão com sucesso, certifique-se de que o seguinte esteja em vigor:

  • Ativo Conta da AWS — e Conta da AWS com permissões para implantar CloudFormation pilhas e criar recursos do Lambda, do API Gateway, do Amazon Cognito CloudFront e do Amazon S3.

  • Conta Amazon Quick Sight — Uma conta ativa do Quick Sight com pelo menos um painel que contém imagens. Para obter instruções de configuração, consulte Tutorial: Crie um painel do Amazon Quick Sight usando dados de amostra na documentação do Amazon Quick Suite.

  • Um ambiente de desenvolvimento que consiste em:

    • Node.js (versão 16 ou posterior)

    • npm ou yarn instalado

    • Vite como a ferramenta de construção do React

    • React (versão 19.1.1)

  • Compartilhamento do painel — Os painéis devem ser compartilhados no Quick Sight e o implementador deve fazer login para acessar os visuais ou painéis incorporados.

Limitações

  • Esse padrão usa o método de incorporação de usuário registrado, que exige que os implementadores tenham uma conta ativa do Quick Sight.

  • O acesso é restrito aos painéis e recursos visuais que são explicitamente compartilhados com o usuário autenticado do Quick Sight que está implementando esse padrão. Se o implementador não tiver os direitos de acesso corretos, a geração do URL incorporado falhará e as imagens não serão carregadas.

  • A CloudFormation pilha deve ser implantada em um Região da AWS local onde o Quick Sight, o API Gateway e o Amazon Cognito sejam compatíveis. Para conferir a disponibilidade de uma região, consulte Serviços da AWS by Region.

Versões do produto

Arquitetura

Arquitetura de destino

O diagrama apresentado a seguir ilustra a arquitetura e o fluxo de trabalho para este padrão.

Arquitetura e fluxo de trabalho para incorporar imagens do Quick Sight em um aplicativo React.

Nesse fluxo de trabalho:

  1. O usuário acessa o aplicativo. O usuário abre o aplicativo web React usando um navegador. A solicitação é roteada para uma CloudFront distribuição, que atua como uma rede de entrega de conteúdo para o aplicativo.

  2. AWS WAF filtra solicitações maliciosas. Antes que a solicitação chegue CloudFront, ela passa AWS WAF. AWS WAF inspeciona o tráfego e bloqueia todas as solicitações maliciosas ou suspeitas com base nas regras de segurança.

  3. O Amazon S3 serve arquivos estáticos. Se a solicitação estiver limpa, CloudFront recupera os ativos estáticos de front-end (HTML, JS, CSS) de um bucket S3 privado usando o controle de acesso de origem (OAC) e os entrega ao navegador.

  4. O usuário faz login. Depois que o aplicativo é carregado, o usuário faz login por meio do Amazon Cognito, que autentica o usuário e retorna um token web JSON (JWT) seguro para acesso autorizado à API.

  5. O aplicativo faz uma solicitação de API. Após o login, o aplicativo React faz uma chamada segura para o /get-embed-url endpoint no API Gateway e passa o token JWT no cabeçalho da solicitação para autenticação.

  6. O token está validado. O API Gateway valida o token usando um autorizador do Amazon Cognito. Se o token for válido, a solicitação prosseguirá; caso contrário, ela será negada com uma resposta 401 (não autorizada).

  7. A solicitação é direcionada à Lambda para processamento. A solicitação validada é então encaminhada para uma função Lambda de back-end. Essa função é responsável por gerar o URL de incorporação para o visual do Quick Sight solicitado.

  8. O Lambda gera o URL de incorporação do Quick Sight. O IAM usa uma função do IAM com as permissões apropriadas para chamar a GenerateEmbedUrlForRegisteredUser API Quick Sight para gerar uma URL visual segura e com escopo de usuário.

  9. O Lambda retorna o URL incorporado ao API Gateway. O Lambda envia o URL de incorporação gerado de volta ao API Gateway como parte de uma resposta JSON. Essa resposta é então preparada para entrega no frontend.

  10. O URL de incorporação é enviado para o navegador. O URL incorporado é retornado ao navegador como resposta da API.

  11. O visual é exibido para o usuário. O aplicativo React recebe a resposta e usa o SDK do Quick Sight Embedding para renderizar o visual específico para o usuário.

Automação e escala

As implantações de back-end e front-end são totalmente automatizadas usando CloudFormation, que provisiona todos os AWS recursos necessários, incluindo Amazon Cognito, Lambda, API Gateway, Amazon S3,, CloudFront AWS WAF, funções do IAM e Amazon em uma única implantação. CloudWatch

Essa automação garante uma infraestrutura consistente e repetível em todos os ambientes. Todos os componentes são dimensionados automaticamente: o Lambda se ajusta às invocações de funções, CloudFront fornece conteúdo em cache globalmente e o API Gateway se adapta às solicitações recebidas.

Ferramentas

Serviços da AWS

  • O Amazon Quick Sight é um serviço de inteligência de negócios nativo da nuvem que ajuda você a criar, gerenciar e incorporar painéis e recursos visuais interativos.

  • O Amazon API Gateway gerencia APIs esses serviços que atuam como a ponte entre o aplicativo React e os serviços de back-end.

  • AWS Lambdaé um serviço de computação sem servidor que esse padrão usa para gerar o Quick Sight seguro, incorporado URLs dinamicamente e escalável automaticamente com base nas solicitações.

  • O Amazon Cognito fornece autenticação e autorização para usuários e emite tokens seguros para acesso à API.

  • O Amazon S3 hospeda ativos de front-end estáticos para esse padrão e os serve com segurança por meio dele. CloudFront

  • A Amazon CloudFront fornece conteúdo de front-end globalmente com baixa latência e se integra à filtragem AWS WAF de tráfego.

  • AWS WAFprotege o aplicativo da web contra tráfego malicioso aplicando regras de segurança e limitação de taxa.

  • AWS CloudFormationautomatiza o provisionamento e a configuração de todos os recursos do aplicativo em uma única implantação.

  • A Amazon CloudWatch coleta registros e métricas do Lambda, do API Gateway AWS WAF e para monitoramento e solução de problemas.

Ferramentas de desenvolvimento

  • O React JS é uma estrutura de front-end que esse padrão usa para criar o aplicativo web e integrar visuais incorporados do Quick Sight.

  • O Vite é uma ferramenta de construção usada para desenvolvimento rápido e compilações de produção otimizadas do aplicativo React.

  • O Quick Sight Embedding SDK facilita a incorporação de visuais do Quick Sight no aplicativo React e permite uma interação perfeita entre o aplicativo e os recursos visuais.

Repositório de código

O código desse padrão está disponível no repositório GitHub Amazon Quick Sight Visual Embedding in React.

Práticas recomendadas

Esse padrão implementa automaticamente as seguintes melhores práticas de segurança:

  • Usa grupos de usuários do Amazon Cognito para autenticação baseada em JWT, com autenticação multifator (MFA) opcional.

  • Protege APIs com autorizadores do Amazon Cognito e aplica políticas de IAM com privilégios mínimos em todos os serviços.

  • Implementa a incorporação de usuários registrados do Quick Sight e provisiona automaticamente os usuários com a função de leitor.

  • Aplica criptografia em trânsito que suporta TLS 1.2 e versões posteriores por meio CloudFront de HTTPS.

  • Criptografa dados em repouso usando AES-256 para Amazon S3 com controle de versão e OAC.

  • Configura os planos de uso do API Gateway com limitação e cotas.

  • Protege o Lambda com simultaneidade reservada e proteção de variáveis de ambiente.

  • Permite o registro em log para Amazon S3, CloudFront Lambda e API Gateway; monitora serviços usando. CloudWatch

  • Criptografa registros, aplica controles de acesso e aplica políticas de negação para uploads não HTTPS ou não criptografados.

Além disso, recomendamos o seguinte:

  • Use CloudFormation para automatizar implantações e manter configurações consistentes em todos os ambientes.

  • Certifique-se de que cada usuário tenha as permissões corretas do Quick Sight para acessar imagens incorporadas.

  • Proteja os endpoints do API Gateway com os autorizadores do Amazon Cognito e aplique o princípio do privilégio mínimo para todas as funções do IAM.

  • Armazene informações confidenciais, como Amazon Resource Names (ARNs) e IDs em variáveis de ambiente, em vez de codificá-las permanentemente.

  • Otimize as funções do Lambda reduzindo dependências e melhorando o desempenho da inicialização a frio. Para obter mais informações, consulte a postagem do AWS blog Otimizando o desempenho da inicialização a frio do AWS Lambda uso de estratégias avançadas de preparação com. SnapStart

  • Adicione seu CloudFront domínio à lista de permissões do Quick Sight para permitir a incorporação visual segura.

  • Monitore o desempenho e a segurança usando CloudWatch e AWS WAF para registros, alertas e proteção de tráfego.

Outras melhores práticas recomendadas

  • Use domínios personalizados com certificados SSL da AWS Certificate Manager para fornecer uma experiência de usuário segura e de marca.

  • CloudWatch Criptografe dados e registros do Amazon S3 usando chaves AWS Key Management Service gerenciadas pelo cliente AWS KMS() para maior controle sobre a criptografia.

  • Estenda AWS WAF as regras com bloqueio geográfico, injeção de SQL (SQLi), proteção de script entre sites (XSS) e filtros personalizados para melhorar a prevenção de ameaças.

  • Ative CloudWatch alarmes e AWS CloudTrail para monitoramento AWS Config, auditoria e conformidade de configuração em tempo real.

  • Aplique políticas granulares de IAM, imponha a rotação de chaves de API e permita o acesso entre contas somente quando for absolutamente necessário.

  • Realize avaliações regulares de segurança para garantir o alinhamento com estruturas de conformidade, como Controles Organizacionais 2 (SOC 2), Regulamento Geral de Proteção de Dados (GDPR) e Lei de Portabilidade e Responsabilidade de Seguros de Saúde (HIPAA).

Épicos

TarefaDescriptionHabilidades necessárias

Clonar o repositório.

Clone o GitHub repositório dessa solução em seu sistema local e navegue até o diretório do projeto:

git clone https://github.com/aws-samples/sample-quicksight-visual-embedding.git

cd sample-quicksight-visual-embedding

Esse repositório contém o CloudFormation modelo e o código-fonte do React necessários para implantar a solução.

Desenvolvedor de aplicativos
TarefaDescriptionHabilidades necessárias

Implante o modelo.

  1. Faça login no Console de gerenciamento da AWS e abra o AWS CloudFormation console.

  2. Na página Pilhas, escolha Criar pilha no canto superior direito e escolha Com novos recursos (padrão).

  3. Na página Criar pilha, em Pré-requisito — Preparar modelo, escolha Escolher um modelo existente.

  4. Em Specify template (Especificar modelo), escolha Upload a template file (Fazer upload de um arquivo de modelo).

  5. Carregue o template.yaml arquivo do seu GitHub repositório local e escolha Avançar.

  6. Na página Especificar detalhes da pilha, insira o nome da pilha (por exemplo,quicksight-embedding-stack).

  7. Na página Configurar opções de pilha, mantenha as configurações padrão e marque a caixa para confirmar a criação dos recursos do IAM. Escolha Próximo.

  8. Na página Revisar e criar, escolha Enviar.

 Para obter mais informações, consulte Criação e gerenciamento de pilhas na CloudFormation documentação.

Administrador da AWS

Monitore a criação da pilha.

Monitore a pilha na guia Eventos até que seu status seja CREATE_COMPLETE.

Administrador da AWS

Recupere as saídas da pilha.

  1. Quando a implantação estiver concluída, escolha a guia Saídas.

  2. Observe as principais saídas: ApiGatewayUrlUserPoolId,UserPoolClientId,CloudFrontDomainName, e. S3BucketName Você usará essas informações nas etapas subsequentes.

Administrador da AWS
TarefaDescriptionHabilidades necessárias

Recupere identificadores visuais do Quick Sight.

  1. Abra o painel do Quick Sight.

  2. Anote o ID do painel, o ID da planilha e o ID visual de cada visual que você planeja incorporar ao seu aplicativo web.

Administrador do Quick Sight

Configure seu ambiente React local.

Para configurar seu ambiente React local e vinculá-lo aos AWS recursos, crie um .env arquivo na my-app/ pasta do seu GitHub repositório local. Preencha o arquivo com:

  • Seu Região da AWS

  • Informações do pool do Amazon Cognito (das saídas da CloudFormation pilha)

  • Endpoint do API Gateway (a partir de saídas da CloudFormation pilha)

  • Visualização rápida IDs (DashboardId,SheetId,VisualId)

Aqui está um exemplo de .env arquivo:

VITE_AWS_REGION=us-east-1

# Cognito Configuration (from CloudFormation outputs)
VITE_USER_POOL_ID=us-east-1_xxxxxxxxx VITE_USER_POOL_WEB_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx

# API Configuration (from CloudFormation outputs)
VITE_API_URL=https:/your-api-id.execute-api.us-east-1.amazonaws.com/prod

# QuickSight Visual Configuration
VITE_DASHBOARD_ID=your-dashboard-id 
VITE_SHEET_ID=your-sheet-id 
VITE_VISUAL_ID=your-visual-id
Desenvolvedor de aplicativos
TarefaDescriptionHabilidades necessárias

Criar ou gerenciar usuários no Cognito

Para permitir que usuários autenticados acessem imagens incorporadas do Quick Sight, primeiro você cria usuários no Amazon Cognito:

  1. No console do Amazon Cognito, escolha Grupos de usuários e, em seguida, escolha o pool correspondente UserPoolId (das CloudFormation saídas).

  2. Adicione usuários ao pool. Você pode escolher entre duas opções:

Administrador da AWS

Forneça acesso ao painel do Quick Sight

Para fornecer acesso aos recursos visuais do Quick Sight, forneça permissão de acesso ao Visualizador aos usuários autenticados:

  1. No console do Quick Sight, escolha Painéis.

  2. Selecione o painel que você deseja compartilhar escolhendo seu nome.

  3. No canto superior direito da página do painel, escolha Compartilhar.

  4. No painel de compartilhamento, escolha Compartilhar com usuários específicos.

  5. Para adicionar novos usuários, escolha Convidar usuários ou o ícone de adição (+).

  6. No campo de e-mail, insira o endereço de e-mail completo do destinatário. (Esse e-mail deve corresponder exatamente ao login do usuário no Amazon Cognito)

  7. No menu Permissão ao lado do campo de e-mail, escolha Visualizador.

  8. Para enviar o convite e conceder acesso, escolha Compartilhar.

Cada usuário receberá um e-mail com um link para o painel. Você pode modificar as permissões a qualquer momento por meio do menu Compartilhar.

Para obter mais informações, consulte Conceder a usuários e grupos individuais do Amazon Quick Sight acesso a um painel no Amazon Quick Sight na documentação do Amazon Quick Suite.

Administrador do Quick Sight
TarefaDescriptionHabilidades necessárias

Instale dependências e construa o projeto.

No diretório do aplicativo React, execute os seguintes comandos para gerar arquivos de produção otimizados:

cd my-app
npm install
npm run build
Desenvolvedor de aplicativos

Faça o upload dos arquivos de compilação para o Amazon S3.

Faça upload de todos os arquivos do my-app/dist/ diretório para o bucket do S3 provisionado por CloudFormation (não faça upload da pasta em si).

Desenvolvedor de aplicativos

Crie uma CloudFront invalidação.

No CloudFront console, crie uma invalidação do caminho /* para atualizar o conteúdo em cache após a implantação. Para obter instruções, consulte Invalidar arquivos na CloudFront documentação.

Administrador da AWS
TarefaDescriptionHabilidades necessárias

Adicione o CloudFront domínio à lista de permissões do Quick Sight.

Para permitir que seu CloudFront domínio incorpore com segurança os recursos visuais do Quick Sight:

  1. No console do Quick Sight, escolha Gerenciar Quick Sight, Domínios e Incorporação.

  2. Adicione o CloudFront domínio à caixa Domínio (por exemplo,https://d1234567890abc.cloudfront.net).

  3. Escolha Adicionar domínio.

Administrador do Quick Sight
TarefaDescriptionHabilidades necessárias

Abra o aplicativo React.

Use o CloudFront domínio (das CloudFormation saídas) para abrir o aplicativo web React implantado em um navegador.

Proprietário do App

Verifique a autenticação.

Faça login no aplicativo usando as credenciais do Amazon Cognito para verificar o fluxo de autenticação e a validação do JWT por meio do API Gateway.

Proprietário do App

Verifique os recursos visuais incorporados.

Confirme se os visuais do Quick Sight são carregados corretamente no aplicativo com base nas permissões de acesso específicas do usuário.

Proprietário do App

Valide a conectividade da API e do Lambda.

Confirme se o aplicativo pode chamar a /get-embed-url API com sucesso e recuperar a incorporação válida do Quick Sight URLs sem erros.

Proprietário do App
TarefaDescriptionHabilidades necessárias

Monitore usando CloudWatch.

Você pode usar ferramentas AWS de observabilidade para monitorar o aplicativo e manter um desempenho seguro e escalável na produção.

Analise os registros do Lambda, as métricas do API Gateway e os eventos CloudWatch de autenticação do Amazon Cognito para garantir a integridade do aplicativo e detectar anomalias.

Administrador da AWS

AWS WAF Rastreamento e CloudFront registros.

Inspecione AWS WAF os registros em busca de solicitações bloqueadas ou suspeitas e CloudFront acesse os registros para ver as métricas de desempenho e armazenamento em cache.

Administrador da AWS

Solução de problemas

ProblemaSolução

Erro “Domínio não permitido”

  1. No console do Quick Sight, escolha Gerenciar Quick Sight, Domínios e Incorporação.

  2. Adicione seu CloudFront domínio (por exemplo,https://d1234567890abc.cloudfront.net).

  3. Salve a configuração e recarregue o aplicativo.

Erros de autenticação

Causas possíveis:

  • ID incorreta do grupo de usuários do Amazon Cognito ou ID do cliente do aplicativo no .env arquivo.

  • O usuário não foi confirmado no grupo de usuários do Amazon Cognito.

  • Token JWT inválido ou ausente nas solicitações de API.

Soluções:

  • Verifique os valores de configuração do Amazon Cognito no .env arquivo.

  • No console do Amazon Cognito, verifique a guia Usuários para verificar se o usuário está ativo.

  • Confirme se o cabeçalho de autorização contém um token JWT válido.

  • No console do API Gateway, marque Autorizadores para verificar se o API Gateway está usando o autorizador do Amazon Cognito para autenticação.

Erros do API Gateway

Causas possíveis:

  • Autorizador do Amazon Cognito ausente ou configurado incorretamente no API Gateway.

  • Permissões Lambda insuficientes para chamar a API Quick Sight.

  • Incompatibilidade de URL da API entre .env e CloudFormation saídas.

Soluções:

  • Reconfirme se o URL de invocação do API Gateway está em seu .env arquivo.

  • No console do API Gateway, marque Autorizadores para verificar a configuração do Amazon Cognito.

  • Anexe a política do IAM necessária quicksight:GenerateEmbedUrlForRegisteredUser à função de execução do Lambda.

  • Analise CloudWatch os registros para ver erros detalhados de API ou permissão. Para obter mais informações, consulte a documentação do API Gateway.

Os visuais do Quick Sight não carregam

Causas possíveis:

  • ID incorreta do painel do Quick Sight, ID da planilha ou ID visual na configuração do ambiente.

  • Sem acesso do usuário do Quick Sight ao visual ou ao painel.

  • Falta a configuração de compartilhamento de recursos de origem cruzada (CORS) no API Gateway.

Soluções:

  • Confirme o Quick Sight no IDs menu de três pontos no canto superior direito do visual do painel.

  • Confirme se o usuário do Quick Sight tem a função de Visualizador no painel compartilhado.

  • Ative o CORS no API Gateway e reimplante a API. Para obter mais informações, consulte a documentação do API Gateway.

  • Inspecione o console do navegador em busca de CORS em busca de erros relacionados à rede.

Erro “O usuário não tem acesso”

Causas possíveis:

  • O e-mail do usuário não foi compartilhado com o painel do Quick Sight.

  • Permissão ou função de usuário incorreta no Quick Sight.

Solução:

  1. No console do Quick Sight, abra seu painel e escolha Compartilhar, Compartilhar painel.

  2. Adicione o endereço de e-mail do usuário (correspondente ao e-mail de login do Amazon Cognito).

  3. Atribua a função de permissão de Visualizador.

  4. Peça ao usuário que se desconecte e entre novamente para atualizar as permissões.

Recursos relacionados

AWS documentação

Tutoriais e vídeos