JavaScript e SDK: Como sua aplicação web pode falar com a nuvem

Em artigos passados, falei sobre o que é SDK e por que ele é importante e construímos uma aplicação back-end para conversão de documentos usando o SDK da AWS. Vamos usar o SDK mais uma vez, mas agora para construir nosso front-end!

---

O que é SDK mesmo?

Podemos pensar SDK (Software Development Kit) como uma caixa de ferramentas para construir aplicações sobre uma plataforma, sistema operacional ou linguagem de programação. Ele pode incluir bibliotecas, APIs, documentação, exemplos de código, debuggers, entre outras coisas. Caso queira saber mais sobre SDK e sua diferença para APIs e bibliotecas, veja esse artigo.

O SDK da AWS para JavaScript permite fácil acesso a serviços da AWS a partir de seu código JS. Você verá como com algumas importações e comandos rápidos podemos conversar diretamente com a nuvem!

Tudo que construiremos nesse tutorial, assim como o tutorial do back-end, pode ser reproduzido com uma conta Free Tier da AWS. Com ela, você ganha 100 dólares em créditos na conta e pode ganhar até 100 dólares adicionais ao explorar os diferentes serviços da AWS e não será cobrado a não ser que explicitamente escolha trocar de plano. Se quiser saber mais sobre como criar sua conta e as melhores configurações de segurança, veja esse artigo.

O que vamos construir

No nosso backend, temos uma função Lambda que converte arquivos CSV para JSON. Ela é acionada quando colocamos um arquivo no bucket S3 de input e coloca os arquivos convertidos em um outro bucket do S3 de output. Como queremos fazer o front-end para essa aplicação, vamos construir uma tela que rodará no navegador. Ela será dividida em duas partes: uma seção para fazer o upload de arquivos CSV e outra para o download dos arquivos JSON.

Primeiros passos: rodando a página web

Para esse projeto, vamos usar React, uma biblioteca do JavaScript para criação de interfaces. Para isso, é preciso ter o node.js. Caso não tenha node na sua máquina, comece baixando no site oficial. Selecione "Get Node.js" para baixar.

Nesse repositório você encontrará o código completo do front-end na pasta "front", assim como o back-end que já construímos. Para começar a reproduzir a aplicação, clone ele para editar o código. Siga os passos:

1. Crie uma pasta no seu computador para o projeto
2. No terminal, navegue até a pasta criada através do comando cd <caminho-ate-a-pasta>
3. Clone o repositório com o comando git clone https://github.com/gi-armani/CSV-JSON-Converter-sample-for-aws-SDK
4. Para rodar a aplicação, navegue até a raiz do projeto com o comando cd <caminho-ate-a-pasta-criada>/CSV-JSON-Converter-sample-for-aws-SDK/front
5. Execute npm install para instalar as dependências e npm start para iniciar

Você deverá ver uma mensagem parecida com a mensagem abaixo:

Agora você pode abrir http://localhost:3000/ no seu navegador de preferência e ver os elementos visuais da aplicação. Lembre-se que ela ainda não está conectada na nuvem, mas vamos cuidar disso!

Entendendo a estrutura da página

Quando iniciamos um projeto React, o principal arquivo da aplicação estará localizado em CSV-JSON-Converter-sample-for-aws-SDK/front/src/App.js que contém a seguinte estrutura:

// importação de bibliotecas, imagens e outros elementos
import logo from './logo.svg';
import './App.css';

function App() {
  // Aqui colocamos a lógica (variáveis e funções que precisaremos usar)

  return (
    // Aqui estarão os diferentes elementos do site, declarados em componentes similares ao html
  );
}

export default App;

O trecho de código acima tem indicativos de onde estarão os nossos elementos visuais (textos, inputs, botões, etc) e onde estará a lógica dos processos. Veja que no código que você clonou tudo isso já está criado, mas ainda vamos precisar substituir algumas constantes para conectar com a nuvem.

Configurando permissões

Pausando um pouco no código e indo para a conexão com a nuvem, precisamos configurar permissões para nosso código conseguir acessar os arquivos. Agora vamos conectar o front-end com o back-end que criamos anteriormente. Caso você não tenha os buckets do S3 e a função Lambda na sua conta, recomendo criá-los primeiro usando as instruções do artigo anterior.

Para isso, vamos usar o IAM (AWS Identity and Access Management). Esse é um serviço da AWS que permite controlar acesso a permissões dentro da sua conta. Se quiser entender mais sobre como funciona o IAM e os diferentes tipos de permissão, veja esse artigo.

Na minha conta AWS, estou na região de us-west-2 (Estados Unidos Oregon). É importante criar todos os seus recursos na mesma região para evitar problemas de comunicação entre eles. Você pode identificar a região que você está a qualquer momento no menu superior da conta ao lado do nome e número da conta.

Criando a política de acesso ao S3

Vamos começar criando a política de acesso, ou seja, o documento que diz o que é permitido fazer e onde.

1. No console da AWS da sua conta Free Tier, navegue até a página do IAM e selecione "Políticas" no menu da esquerda
2. Clique em "Criar política"
3. No canto superior direito do editor de políticas, selecione a opção JSON e cole o conteúdo abaixo. Não se esqueça de substituir os locais indicados em "Resource" com os nomes dos seus buckets

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowWriteInput",
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::<NOME-DO-SEU-BUCKET-DE-INPUT>/*"
        },
        {
            "Sid": "AllowReadOutput",
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::<NOME-DO-SEU-BUCKET-DE-OUTPUT>/*"
        },
    {
      "Sid": "AllowListOutput",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::gio-csv-converter-output"
    }
    ]
}

Aqui temos uma política que permite subir arquivos no bucket de input (operação PutObject) e ler arquivos do bucket de output (operação GetObject). Temos também uma última permissão que permite listar os objetos de um bucket (operação ListBucket). Essa última é importante porque caso a conversão do json ainda não tenha sido terminada, fará com que o S3 retorne um erro mais amigável dizendo que o arquivo ainda não existe. Sem essa permissão, o S3 retornaria um erro de acesso negado.

Na opção "Visual" do editor de políticas, é possível construir essa mesma política de forma interativa selecionando os serviços e as operações que serão usadas (deixo para a curiosidade de quem quiser explorar 😉).

Para terminar a criação, basta selecionar "Próximo", dar um nome à sua política na próxima página (chamei a minha de "jsWebClientS3Access") e então selecionar "Criar política" no canto inferior direito.

Criando um identity pool

Para essa parte, vamos usar o Amazon Cognito, um serviço da AWS de autenticação para aplicações. Ele nos ajuda a identificar quem é o usuário que está acessando nossa aplicação e gerar credenciais de acesso que são atualizadas automaticamente.

Os Identity pools (ou grupos de identidade) são diretórios de identidades que podem ser usados para obter credenciais para acessar outros serviços da AWS através do nosso front-end. Para criá-lo, siga os passos abaixo:

1. Na sua conta Free Tier, navegue até o Amazon Cognito
2. Selecione "Grupos de identidades" no menu esquerdo e em seguida "Criar grupo de identidades" no botão laranja à direita
3. Na página de criação, selecione "Acesso de convidado". Isso permitirá que nosso código front-end acesse os recursos que queremos sem precisar de um login. Clique em "Próxima" para continuar
4. Em seguida, vamos criar um perfil do IAM que usaremos para declarar as permissões. Selecione "Criar um novo perfil do IAM" e dê um nome a ele. Chamei o meu de "jsWebClientRole". Clique em "Próxima" para continuar
5. Dê um nome ao grupo de identidades. Chamei o meu de "jsWebClientIdentity". Clique em "Próxima" para continuar
6. Revise os detalhes do grupo de identidade que estamos criando e selecione "Criar grupo de identidades" para concluir.

De volta na página dos Grupos de identidade do Amazon Cognito, você verá seu grupo de identidade criado. Salve o ID dele pois será usado logo mais para autenticação no código.

Por último, precisamos ligar a política de acesso que criamos na seção anterior ao grupo de identidade:

1. Navegue até o console de IAM
2. No menu esquerdo, selecione "Funções"
3. Busque pelo perfil que criamos junto ao Grupo de identidade. O meu é o "jsWebClientRole"
4. Na aba de "Permissões", selecione "Adicionar permissões" e "Anexar políticas"
5. Busque pela política de acesso ao S3 que criamos anteriormente e clique em "Adicionar permissão"

Configurando CORS

Um conceito clássico que vemos quando integramos aplicações, como integração entre front e back-end, é CORS. CORS significa Cross-Origin Resource Sharing, ou compartilhamento de recursos entre origens, e é um mecanismo para compartilhar conteúdo entre diferentes domínios de forma segura. Com ele, declaramos o que pode ser compartilhado e quais domínios podem enviar conteúdo. Precisamos configurar CORS para o bucket de input e de output.

1. No console da AWS, navegue até a página do S3
2. Selecione o nome do bucket de input que criamos no último tutorial quando construímos o back-end
3. Clique em "Permissões" e desça até o final da página onde encontrará "Compartilhamento de recursos de origem cruzada (CORS)"
4. Clique em editar e cole o conteúdo abaixo:

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "PUT"
        ],
        "AllowedOrigins": [
            "http://localhost:3000"
        ],
        "ExposeHeaders": [
            "ETag"
        ]
    }
]

⚠️ Note que adicionamos especificamente o localhost na porta 3000 em "AllowedOrigins" o que significa que o bucket aceitará receber recursos apenas desse domínio. A melhor prática de segurança é sempre restringir acesso para o mínimo necessário. Para um site que estivesse deployado na internet, adicionaríamos o domínio específico da aplicação que faz o envio.

Repita os mesmos passos para habilitar CORS no bucket de output.

Conectando tudo: chamando o SDK da AWS

Agora que temos as permissões configuradas na conta AWS, vamos fazer a conexão com o S3 no código.

No começo do arquivo App.js do repositório clonado, você encontrará o seguinte trecho:

const REGION = 'us-west-2';
const IDENTITY_POOL_ID = '';

const clienteS3 = new S3Client({
  region: REGION,
  credentials: fromCognitoIdentityPool({
    clientConfig: { region: REGION }, 
    identityPoolId: IDENTITY_POOL_ID
  })
});

O IdentityPoolId usado para criar o clienteS3 será o ID do Grupo de Identidades que criamos com Amazon Cognito. Preencha esse valor na constante IDENTITY_POOL_ID. Note que a constante REGION, que indica a região, está declarada como us-west-2. Caso seus recursos estejam em outra região da AWS, mude essa constante para a região correspondente.

⚠️ Essa é a forma recomendada pela AWS para obter credenciais para o navegador. Muito cuidado com expor suas credenciais abertamente, jamais publique elas na internet!

Por fim, preencha as constantes que representam os buckets de input e output com os nomes dos seus buckets:

const BUCKET_ENTRADA = '';
const BUCKET_SAIDA = '';

Pronto! Se seu back-end também estiver configurado, você terá um sistema completo incluindo front e back-end que utiliza o SDK da AWS para comunicação com os serviços em nuvem. Você pode usar esse csv de exemplo para testar a aplicação.

Conclusão

Agora você já sabe como construir uma aplicação front-end que se comunica diretamente com serviços da AWS. Nesse tutorial, você aprendeu a:

• Instalar e usar o AWS SDK para JavaScript para interagir com o S3
• Configurar permissões no IAM para que sua aplicação acesse serviços da AWS de forma segura
• Configurar CORS para permitir a comunicação entre seu front-end e a nuvem

Reproduza esse tutorial na sua máquina e dê seu próprio estilo ao design da página. Experimente trocar cores, fontes e layout, deixe com a sua carinha. Com o front-end e o back-end que construímos no artigo anterior, você tem uma aplicação serverless completa funcionando na AWS!