Carregar uma imagem em um blob de Armazenamento do Azure com JavaScript

Artigo
12/06/2023

Use um aplicativo Web estático para carregar um arquivo em um blob de Armazenamento do Azure usando um pacote npm de @azure/storage-blob do Armazenamento do Azure com um token SAS de Armazenamento do Azure.

Pré-requisitos

Uma assinatura do Azure; se ainda não tiver uma, inscreva-se para uma conta gratuita do Azure.
Conta do GitHub para bifurcar e enviar por push para um repositório.

Arquitetura do aplicativo

Essa arquitetura de aplicativo inclui dois recursos do Azure:

Aplicativos Web Estáticos do Azure para o aplicativo cliente gerado estaticamente. O recurso também fornece a API gerenciada do Azure Functions. Gerenciado significa que o recurso Aplicativos Web Estáticos gerencia o recurso de API para seu próprio uso.
Armazenamento do Azure para o armazenamento de blob.

Diagram showing how a customer interacts from their computer to use the website to upload a file to Azure Storage directly.

Etapa	Descrição
1	O cliente se conecta ao site gerado estaticamente. O site é hospedado em Aplicativos Web Estáticos do Azure.
2	O cliente usa esse site para selecionar um arquivo a ser carregado. Para este tutorial, a estrutura front-end é o Vite React e o arquivo carregado é um arquivo de imagem.
3	O site chama a API `sas` do Azure Functions para obter um token SAS com base no nome exato do arquivo a ser carregado. A API sem servidor usa o SDK de Armazenamento de Blobs do Azure para criar o token SAS. A API retorna a URL completa a ser usada para carregar o arquivo, que inclui o token SAS como a cadeia de caracteres de consulta. `https://YOUR-STORAGE-NAME.blob.core.windows.net/YOUR-CONTAINER/YOUR-FILE-NAME?YOUR-SAS-TOKEN`
4	O site front-end usa a URL do token SAS para carregar o arquivo diretamente no Armazenamento de Blobs do Azure.

Ambientes locais e de construção

Este tutorial usa os seguintes ambientes:

Desenvolvimento local com GitHub Codespaces ou Visual Studio Code.
Crie e implante com o GitHub Actions.

1. Repositório de aplicativos de exemplo de fork com o GitHub

Este tutorial usa ações do GitHub para implantar o aplicativo de exemplo no Azure. Você precisa de uma conta do GitHub e uma bifurcação do repositório de aplicativos de exemplo para concluir essa implantação.

Em um navegador da Web, use o link a seguir para iniciar a bifurcação para sua própria conta do repositório de exemplo: Azure-Samples/azure-typescript-e2e-apps.
Conclua as etapas para bifurcar a amostra somente com a ramificação principal .

2. Configurar o ambiente de desenvolvimento

Um ambiente de contêiner de desenvolvimento está disponível com todas as dependências necessárias para concluir todos os exercícios deste projeto. Você pode executar o contêiner de desenvolvimento no GitHub Codespaces ou localmente usando o Visual Studio Code.

Codespaces do GitHub
Visual Studio Code

O GitHub Codespaces executa um contêiner de desenvolvimento gerenciado pelo GitHub com o Visual Studio Code para Web como interface do usuário. Para o ambiente de desenvolvimento mais simples, use o GitHub Codespaces para que você tenha as ferramentas de desenvolvedor e dependências corretas pré-instaladas para concluir esse módulo de treinamento.

Importante

Todas as contas do GitHub podem usar Codespaces por até 60 horas gratuitas por mês com 2 instâncias principais. Para saber mais, confira Armazenamento e horas por núcleo incluídos mensalmente no GitHub Codespaces.

Em um navegador da Web, na bifurcação do GitHub do repositório de exemplo, inicie o processo para criar um novo Codespace do GitHub na main ramificação do fork selecionando o botão CODE .
Na guia Codespaces, selecione as reticências, ....
Selecione + Novo com opções para selecionar um contêiner de desenvolvimento Codespaces específico.
Selecione as opções a seguir e, em seguida, selecione Criar espaço de código.
- Ramo: main
- Configuração do contêiner de desenvolvimento: Tutorial: Upload file to storage with SAS Token
- Região: aceitar padrão
- Tipo de máquina: aceitar padrão
Aguarde até que o codespace seja iniciado. Esse processo de inicialização pode levar alguns minutos.
Abra um novo terminal no codespace.

Dica

Você pode usar o menu principal para navegar até a opção de menu Terminal e, em seguida, selecionar a opção Novo Terminal.
Verifique as versões das ferramentas que você usa neste tutorial.
```
node --version
npm --version
func --version
```
Este tutorial requer as seguintes versões de cada ferramenta, que são pré-instaladas em seu ambiente:

Ferramenta Versão

Node.js ≥ 18

npm ≥ 9.5

Azure Functions Core Tools ≥ 4.5098
Feche o terminal.
As etapas restantes deste tutorial ocorrem no contexto desse contêiner de desenvolvimento.

Ferramenta	Versão
Node.js	≥ 18
npm	≥ 9.5
Azure Functions Core Tools	≥ 4.5098

A extensão Contêiner de Desenvolvimento para o Visual Studio Code exige que o Docker esteja instalado no seu computador local. A extensão hospeda o contêiner de desenvolvimento localmente usando o host do Docker com as ferramentas do desenvolvedor e as dependências corretas pré-instaladas para concluir esse módulo de treinamento.

Abra o Visual Studio Code no contexto de um diretório vazio.
Verifique se a extensão Dev Containers está instalada no Visual Studio Code.
Abrir um novo terminal no editor.

Dica

Você pode usar o menu principal para navegar até a opção de menu Terminal e, em seguida, selecionar a opção Novo Terminal.
Clone seu fork no diretório atual. Substitua YOUR-ACCOUNT no comando a seguir pelo nome da sua conta.
```
git clone https://github.com/YOUR-ACCOUNT/azure-typescript-e2e-apps
```
Abra a Paleta de comandos, procure os comandos Dev Containers e selecione Dev Containers: reabrir no contêiner.

Dica

O Visual Studio Code pode solicitar automaticamente que você reabra a pasta existente em um contêiner de desenvolvimento. Essa funcionalidade equivale a usar a paleta de comandos para reabrir o espaço de trabalho atual em um contêiner.
Verifique as versões das ferramentas que você usa neste tutorial.
```
node --version
npm --version
func --version
```
Este tutorial requer as seguintes versões de cada ferramenta, que são pré-instaladas em seu ambiente:

Ferramenta Versão

Node.js ≥ 18

npm ≥ 9.5

Azure Functions Core Tools ≥ 4.5098
Feche o terminal.
As etapas restantes deste tutorial ocorrem no contexto desse contêiner de desenvolvimento.

Ferramenta	Versão
Node.js	≥ 18
npm	≥ 9.5
Azure Functions Core Tools	≥ 4.5098

3. Instalar dependências

O aplicativo de exemplo para este tutorial está na azure-upload-file-to-storage pasta. Você não precisará usar nenhuma outra pasta no projeto.

No Visual Studio Code, abra um terminal e mova para a pasta do projeto.
```
cd azure-upload-file-to-storage
```
Divida o terminal para que você tenha dois terminais, um para o aplicativo cliente e outro para o aplicativo API.
Em um dos terminais, execute o seguinte comando para instalar as dependências do aplicativo de API e executá-lo.
```
cd api && npm install
```
No outro terminal, execute o comando para instalar o aplicativo cliente.
```
cd app && npm install
```

4. Criar um recurso de Armazenamento com a extensão do Visual Studio

Crie o recurso de armazenamento a ser usado com o aplicativo de exemplo. O armazenamento é usado para:

Gatilhos no aplicativo Azure Functions
Armazenamento de blobs (arquivo)

Navegue até a extensão do Armazenamento do Azure.
Entre no Azure, se necessário.
Clique com o botão direito do mouse na assinatura e selecione Create Resource....
Selecione Criar conta de armazenamento na lista.

Siga os prompts usando a tabela a seguir para entender como criar seu recurso de armazenamento.

Propriedade	Valor
Insira um nome globalmente exclusivo para o novo aplicativo Web.	Insira um valor exclusivo, como `fileuploadstor`, para o nome do recurso de armazenamento. Esse nome exclusivo é o nome do recurso usado na próxima seção. Use apenas caracteres e números, com até 24 caracteres de comprimento. Você precisa desse nome de conta para uso posterior.
Selecione uma localização para novos recursos.	Use o local recomendado.

Quando o processo de criação do aplicativo é concluído, uma notificação é exibida com informações sobre o novo recurso.

5. Configurar o CORS de armazenamento

Como o navegador é usado para carregar o arquivo, a conta de Armazenamento do Azure precisa configurar o CORS para permitir solicitações entre origens.

Navegue até a extensão do Armazenamento do Azure. Clique com o botão direito do mouse no recurso de armazenamento e selecione Abrir no Portal.
Na seção Configurações da conta de armazenamento do portal do Azure, selecione Compartilhamento de recursos (CORS).
Use as propriedades a seguir para definir o CORS para este tutorial.
- Origens permitidas: *
- Métodos permitidos: Todos, exceto patch
- Cabeçalhos permitidos: *
- Cabeçalhos expostos: *
- Idade máxima: 86400
Essas configurações são usadas para este tutorial para simplificar as etapas e não devem indicar práticas recomendadas ou segurança. Saiba mais sobre o CORS para o Armazenamento do Azure.
Selecione Salvar.

6. Conceder acesso anônimo ao armazenamento

O carregamento do arquivo é protegido do cliente quando você cria um token SAS com tempo limitado e permissão. No entanto, depois que o arquivo for carregado, neste cenário de tutorial, você deseja que qualquer pessoa o veja. Para fazer isso, você precisa alterar a permissão de armazenamento para ser acessível publicamente.

Mesmo que a conta seja acessível publicamente, cada contêiner e cada blob podem ter acesso privado. Um método mais seguro, mas muito complicado para este tutorial, é carregar para uma conta de armazenamento com o token SAS e, em seguida, mover o blob para outra conta de armazenamento com acesso público.

Para habilitar o acesso público no portal do Azure, selecione a página Visão geral da sua conta de armazenamento, na seção Propriedades, selecione Acesso anônimo de blob e selecione Desabilitado.
Na página Configuração, habilite Permitir acesso anônimo de Blob.

7. Criar contêiner de upload

Ainda na conta de armazenamento do portal do Azure, na seção Armazenamento de dados, selecione Contêineres.
Selecione + Contêiner para criar seu upload contêiner com as seguintes configurações:
- Nome: upload
- Nível de acesso público: Blob
Selecione Criar.

8. Conceda a si mesmo acesso aos Dados de Blob

Enquanto você criou o recurso, você não tem permissão para exibir o conteúdo do contêiner. Isso é reservado para funções específicas do IAM. Adicione sua conta para que você possa exibir os blobs nos contêineres.

Ainda na conta de armazenamento do portal do Azure, selecione Controle de Acesso (IAM).
Selecione Adicionar atribuições de função.
Pesquise e selecione Storage Blob Data Contributor. Selecione Avançar.
Selecione + Selecionar membros.
Pesquise e selecione sua conta.
Selecione Examinar + atribuir.
Selecione Contêineres e, em seguida, o contêiner de carregamento . Você deve ser capaz de ver que não há blobs no contêiner sem erros de autorização.

9. Obter credenciais de recursos de armazenamento

As credenciais do recurso de armazenamento são usadas no aplicativo API do Azure Functions para se conectar ao recurso de armazenamento.

Ainda no portal do Azure, na seção Segurança + rede , selecione Chaves de acesso.
Lembre-se de que os arquivos de API são encontrados em ./workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/api.
Na pasta API, renomeie o arquivo de local.settings.json.sample para local.settings.json. O arquivo é ignorado pelo Git para que não seja verificado no controle do código-fonte.

Atualize as configurações para local.settings.json usar a tabela a seguir.

Propriedade	Valor	Descrição
Azure_Storage_AccountName	Nome da conta do Armazenamento do Azure, por exemplo: `fileuploadstor`.	Usado no código-fonte para se conectar ao recurso de armazenamento.
Azure_Storage_AccountKey	Chave de conta de Armazenamento do Microsoft Azure	Usado no código-fonte para se conectar ao recurso de armazenamento.
AzureWebJobsStorage	Cadeia de conexão da conta do Armazenamento do Azure	Use o tempo de execução do Azure Functions para armazenar o estado e os logs.

Pode parecer que você inseriu as mesmas credenciais de conta duas vezes, uma como uma chave e outra como uma cadeia de conexão. Você fez, mas especificamente para este tutorial simples. De modo geral, os aplicativos do Azure Functions devem ter um recurso de armazenamento separado que não seja reutilizado para outra finalidade. Ao criar o recurso Função do Azure posteriormente no tutorial, você não precisará definir o valor AzureWebJobsStorage para o recurso de nuvem. Você só precisará definir os valores Azure_Storage_AccountName e Azure_Storage_AccountKey que são usados no código-fonte .

10. Execute o aplicativo de API

Execute o Aplicativo Functions para garantir que ele funcione corretamente antes de implantá-lo no Azure.

No terminal do aplicativo de API, execute o seguinte comando para iniciar o aplicativo de API.
```
npm run start
```
Aguarde até que o aplicativo Azure Functions seja iniciado. Você receberá um aviso de que a porta do aplicativo Azure Functions, 7071, já está disponível. Você também deve ver as APIs listadas no terminal do aplicativo de API.
```
Functions:

        list: [POST,GET] http://localhost:7071/api/list

        sas: [POST,GET] http://localhost:7071/api/sas

        status: [GET] http://localhost:7071/api/status
```
Selecione a guia Portas no painel inferior, clique com o botão direito do mouse na porta 7071 e selecione Visibilidade da porta e, em seguida, selecione Público.

Se você não expor esse aplicativo como público, receberá um erro ao usar a API do aplicativo cliente.
Para testar se a API funciona e se conecta ao armazenamento, na guia Portas no painel inferior, selecione o ícone de globo na área Endereço Local da porta 7071. Isso abre um navegador da Web para o aplicativo de funções.
Adicione a rota da API à barra de endereços URL: /api/sas?container=upload&file=test.png. Tudo bem que o arquivo ainda não está no contêiner. A API cria o token SAS com base em onde você deseja que ele seja carregado.

A resposta JSON deve ser semelhante à seguinte:

{
    "url":"https://YOUR-STORAGE-RESOURCE.blob.core.windows.net/upload/test.png?sv=2023-01-03&spr=https&st=2023-07-26T22%3A15%3A59Z&se=2023-07-26T22%3A25%3A59Z&sr=b&sp=w&sig=j3Yc..."
}

Copie a base da URL da API na barra de endereços do navegador (não a URL do token SAS no objeto JSON) para usar na próxima etapa. A URL base é tudo antes /api/sasdo .

11. Configurar e executar o aplicativo cliente

Renomear o arquivo ./azure-upload-file-to-storage/app/.env.sample para .env.
Abra o arquivo e cole a URL base da seção anterior como o .env valor do VITE_API_SERVER.

Um exemplo para um ambiente Codespaces pode se parecer com algo como VITE_API_SERVER=https://improved-space-fishstick-pgvxvxjpqgrh6qxp-7071.app.github.dev
No outro terminal dividido, inicie o aplicativo cliente com o seguinte comando:
```
npm run dev
```

Aguarde até que o terminal retorne o seguinte aviso de que o aplicativo está disponível na porta 5173.

  VITE v4.4.4  ready in 410 ms

  ➜  Local:   https://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

Selecione a guia Portas no painel inferior, clique com o botão direito do mouse na porta 5173 e selecione o ícone de globo.
Você deve ver o aplicativo Web simples.
Interaja com o aplicativo Web:
- Selecione um arquivo de imagem (*.jpg ou *.png) do computador local para carregar.
- Selecione o botão Obter uma SAS para solicitar um token SAS do aplicativo de API. A resposta mostra a URL completa a ser usada para carregar o arquivo no Armazenamento.
- Selecione o botão Carregar para enviar o arquivo de imagem diretamente para o Armazenamento.
O aplicativo cliente e o aplicativo de API trabalharam juntos com êxito em um ambiente de desenvolvedor conteinerizado.

12. Confirmar alterações de código

No Visual Studio Code, abra a guia Controle do código-fonte .
Selecione o + ícone para preparar todas as alterações. Essas alterações devem incluir apenas novos arquivos package-lock.json para as app pastas e api para este tutorial.

13. Implantar aplicativo Web estático no Azure

O aplicativo Azure Functions está usando um recurso de visualização, ele deve ser implantado no oeste dos EUA 2 para funcionar corretamente.

No Visual Studio Code, selecione o Azure Explorer.
No Azure Explorer, clique com o botão direito do mouse no nome da assinatura e selecione Create Resource....
Selecione Criar aplicativo Web estático na lista.

Siga os prompts usando a tabela a seguir para entender como criar seu recurso de Aplicativo Web Estático.

Propriedade	Valor
Insira um nome globalmente exclusivo para o novo aplicativo Web.	Insira um valor exclusivo, como `fileuploadstor`, para o nome do recurso de armazenamento. Esse nome exclusivo é o nome do recurso usado na próxima seção. Use apenas caracteres e números, com até 24 caracteres de comprimento. Você precisa desse nome de conta para uso posterior.
Selecione uma localização para novos recursos.	Use o local recomendado.

Siga os avisos para fornecer as seguintes informações:

Prompt	Digite
Selecione um grupo de recursos para novos recursos.	Use o grupo de recursos que você criou para o recurso de armazenamento.
Insira o nome para o novo aplicativo Web estático.	Aceite o nome padrão.
Selecione uma SKU	Selecione o SKU gratuito para este tutorial. Se você já tiver um recurso gratuito de Aplicativo Web Estático em sua assinatura, selecione a próxima camada de preços.
Escolha a predefinição de compilação para configurar a estrutura padrão do projeto.	selecione Personalizado.
Selecione o local do código do aplicativo	`azure-upload-file-to-storage/app`
Selecione a localização do código do Azure Functions	`azure-upload-file-to-storage/api`
Insira o caminho da sua saída de compilação...	`dist` Esse é o caminho do seu aplicativo aos seus arquivos estáticos (gerados).
Selecione uma localização para novos recursos.	Selecione uma região próxima a você.

Quando o processo é concluído, um pop-up de notificação é exibido. Selecione Exibir/Editar Fluxo de Trabalho.
Sua bifurcação remota tem um novo arquivo de fluxo de trabalho para implantação em Aplicativos Web Estáticos. Puxe esse arquivo para o seu ambiente com o seguinte comando no terminal:
```
git pull origin main
```
Abra o arquivo de fluxo de trabalho localizado em /.github/workflows/.

Verifique se a seção do fluxo de trabalho específica do aplicativo Web estático deste tutorial deve se parecer com:

###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "/azure-upload-file-to-storage/app" # App source code path
api_location: "/azure-upload-file-to-storage/api" # Api source code path - optional
output_location: "dist" # Built app content directory - optional
###### End of Repository/Build Configurations ######

Vá para o fork do GitHub do exemplo https://github.com/YOUR-ACCOUNT/azure-typescript-e2e-apps/actions para verificar a ação de compilação e implantação, chamada Azure Static Web Apps CI/CD, concluída com êxito. Isso pode demorar alguns minutos para ser concluído.
Vá para o portal do Azure para seu aplicativo e exiba a seção APIs de Configurações. O Nome do recurso de back-end no ambiente de produção está (managed) indicando que suas APIs foram implantadas com êxito.
Selecione (gerenciado) para ver a lista de APIs carregadas no aplicativo:
- lista
- Sas
- status
Vá para a página Visão geral para localizar a URL do seu aplicativo implantado.
A implantação do aplicativo está concluída.

14. Configurar a API com o nome e a chave do recurso de armazenamento

O aplicativo precisa do nome e da chave do recurso de Armazenamento do Azure antes que a API funcione corretamente.

Ainda no Azure Explorer, clique com o botão direito do mouse no recurso Aplicativo Web Estático e selecione Abrir no Portal.
Selecione Configuração na seção Configurações.

Adicione configurações de aplicativo usando a tabela a seguir.

Propriedade	Valor	Descrição
Azure_Storage_AccountName	Nome da conta do Armazenamento do Azure, por exemplo: `fileuploadstor`.	Usado no código-fonte para se conectar ao recurso de armazenamento.
Azure_Storage_AccountKey	Chave de conta de Armazenamento do Microsoft Azure	Usado no código-fonte para se conectar ao recurso de armazenamento.

Selecione Salvar na página Configuração para salvar ambas as configurações.

Observação

Você não precisa definir a variável env do aplicativo cliente VITE_API_SERVER porque o aplicativo cliente e a API são hospedados no mesmo domínio.

15. Usar o aplicativo Web estático implantado pelo Azure

Verifique se a implantação e a configuração foram bem-sucedidas usando o site.

No Visual Studio Code, clique com o botão direito do mouse em seu aplicativo Web estático no Gerenciador do Azure e selecione Procurar site.
Na nova janela do navegador da Web, selecione Escolher arquivo e selecione um arquivo de imagem (*.png ou *.jpg) para carregar.
Selecione Obter token sas. Essa ação passa o nome do arquivo para a API e recebe a URL do token SAS necessária para carregar o arquivo.
Selecione Carregar arquivo para usar a URL do token SAS para carregar o arquivo . O navegador exibe a miniatura e a URL do arquivo carregado.

16. Limpar recursos

No Visual Studio Code, use o Azure explorer para Grupos de Recursos, clique com o botão direito do mouse no seu grupo de recursos e selecione Excluir.

Isso exclui todos os recursos no grupo, incluindo seus recursos de Armazenamento e de aplicativo Web Estáticos.

Solução de problemas

Relate problemas com este exemplo no repositório do GitHub observado abaixo. Inclua o seguinte com o problema:

A URL do artigo
A etapa ou contexto dentro do artigo que foi problemático
Seu ambiente de desenvolvimento

Código de exemplo

Repositório do GitHub: azure-upload-file-to-storage

Se você quiser continuar com este aplicativo, saiba como implantar o aplicativo no Azure para hospedagem usando uma das seguintes opções:

Documentação do Armazenamento de Blobs do Azure
@azure/storage-blob
- Pacote npm
Aplicativo Web Estático do Azure

Carregar uma imagem em um blob de Armazenamento do Azure com JavaScript

Pré-requisitos

Arquitetura do aplicativo

Ambientes locais e de construção

1. Repositório de aplicativos de exemplo de fork com o GitHub

2. Configurar o ambiente de desenvolvimento

3. Instalar dependências

4. Criar um recurso de Armazenamento com a extensão do Visual Studio

5. Configurar o CORS de armazenamento

6. Conceder acesso anônimo ao armazenamento

7. Criar contêiner de upload

8. Conceda a si mesmo acesso aos Dados de Blob

9. Obter credenciais de recursos de armazenamento

10. Execute o aplicativo de API

11. Configurar e executar o aplicativo cliente

12. Confirmar alterações de código

13. Implantar aplicativo Web estático no Azure

14. Configurar a API com o nome e a chave do recurso de armazenamento

15. Usar o aplicativo Web estático implantado pelo Azure

16. Limpar recursos

Solução de problemas

Código de exemplo

Comentários

Comentários

Recursos adicionais

Carregar uma imagem em um blob de Armazenamento do Azure com JavaScript

Pré-requisitos

Arquitetura do aplicativo

Ambientes locais e de construção

1. Repositório de aplicativos de exemplo de fork com o GitHub

2. Configurar o ambiente de desenvolvimento

3. Instalar dependências

4. Criar um recurso de Armazenamento com a extensão do Visual Studio

5. Configurar o CORS de armazenamento

6. Conceder acesso anônimo ao armazenamento

7. Criar contêiner de upload

8. Conceda a si mesmo acesso aos Dados de Blob

9. Obter credenciais de recursos de armazenamento

10. Execute o aplicativo de API

11. Configurar e executar o aplicativo cliente

12. Confirmar alterações de código

13. Implantar aplicativo Web estático no Azure

14. Configurar a API com o nome e a chave do recurso de armazenamento

15. Usar o aplicativo Web estático implantado pelo Azure

16. Limpar recursos

Solução de problemas

Código de exemplo

Conteúdo relacionado

Comentários

Comentários

Recursos adicionais