Partilhar via

Guia de início rápido: gerenciar blobs com o JavaScript v12 SDK em um navegador

  • Artigo

O armazenamento de Blob do Azure é otimizado para armazenar grandes quantidades de dados não estruturados. Blobs são objetos que podem conter texto ou dados binários, incluindo imagens, documentos, streaming de mídia e dados de arquivamento. Neste guia de início rápido, você aprende a gerenciar blobs usando JavaScript em um navegador. Você carregará e listará blobs e criará e excluirá contêineres.

O código de exemplo mostra como realizar as seguintes tarefas com a biblioteca de cliente de armazenamento de Blob do Azure para JavaScript:

Recursos adicionais:

Referência | da API Pacote de código-fonte | da biblioteca (npm)Exemplos |

Pré-requisitos

Modelo de objeto

O armazenamento de Blob oferece três tipos de recursos:

  • A conta de armazenamento
  • Um contêiner na conta de armazenamento
  • Uma bolha no recipiente

O diagrama seguinte mostra a relação entre estes recursos.

Diagrama da arquitetura de armazenamento de Blob

Neste início rápido, você usará as seguintes classes JavaScript para interagir com esses recursos:

  • BlobServiceClient: A BlobServiceClient classe permite manipular recursos de Armazenamento do Azure e contêineres de blob.
  • ContainerClient: A ContainerClient classe permite manipular contêineres de Armazenamento do Azure e seus blobs.
  • BlockBlobClient: A BlockBlobClient classe permite manipular blobs de Armazenamento do Azure.

Configurar conta de armazenamento para acesso ao navegador

Para acessar programaticamente sua conta de armazenamento a partir de um navegador da Web, você precisa configurar o acesso CORS e criar uma cadeia de conexão SAS.

Criar uma regra CORS

Antes que seu aplicativo Web possa acessar o armazenamento de blob do cliente, você deve configurar sua conta para habilitar o compartilhamento de recursos entre origens ou CORS.

No portal do Azure, selecione sua conta de armazenamento. Para definir uma nova regra CORS, navegue até a seção Configurações e selecione CORS. Para este início rápido, você cria uma regra CORS totalmente aberta:

Definições de CORS da Conta de Armazenamento de Blobs do Azure

A tabela seguinte descreve cada definição de CORS e explica os valores utilizados para definir a regra.

Definição valor Description
ORIGENS PERMITIDAS * Aceita uma lista delimitada por vírgulas de domínios definidos como origens aceitáveis. Definir o valor como * permite que todos os domínios acedam à conta de armazenamento.
MÉTODOS PERMITIDOS DELETE, GET, HEAD, MERGE, POST, OPTIONS e PUT Apresenta uma lista dos verbos HTTP que podem ser executados na conta de armazenamento. Para efeitos deste início rápido, selecione todas as opções disponíveis.
CABEÇALHOS PERMITIDOS * Define uma lista de cabeçalhos de pedidos (incluindo cabeçalhos com prefixo) que a conta de armazenamento permite. Definir o valor como * permite acesso a todos os cabeçalhos.
CABEÇALHOS EXPOSTOS * Apresenta uma lista dos cabeçalhos de resposta que a conta permite. Definir o valor como * permite à conta enviar qualquer cabeçalho.
IDADE MÁXIMA 86400 A quantidade máxima de tempo que o navegador armazena em cache a solicitação OPTIONS de comprovação em segundos. Um valor de 86400 permite que a cache permaneça por um dia completo.

Depois de preencher os campos com os valores desta tabela, selecione o botão Salvar .

Importante

Certifique-se de que todas as configurações usadas na produção exponham a quantidade mínima de acesso necessária à sua conta de armazenamento para manter o acesso seguro. As definições de CORS descritas aqui são adequadas para um início rápido, porque definem uma política de segurança permissiva. No entanto, não são recomendadas para um contexto do mundo real.

Criar uma cadeia de conexão SAS

A assinatura de acesso compartilhado (SAS) é usada pelo código em execução no navegador para autorizar solicitações de armazenamento de Blob do Azure. Ao utilizar o SAS, o cliente pode autorizar o acesso aos recursos de armazenamento sem a chave de acesso da conta ou sem a cadeia de ligação. Para obter mais informações, veja Using shared access signatures (SAS) (Utilizar assinaturas de acesso partilhado [SAS]).

Siga estas etapas para obter a URL SAS do serviço Blob:

  1. No portal do Azure, selecione sua conta de armazenamento.
  2. Navegue até a seção Segurança + rede e selecione Assinatura de acesso compartilhado.
  3. Analise os serviços permitidos para entender que o token SAS terá acesso a todos os serviços da sua conta de armazenamento:
    • Blobs
    • Ficheiro
    • Queue
    • Tabela
  4. Selecione os tipos de recursos permitidos para incluir:
    • Serviço
    • Contentor
    • Object
  5. Analise a data/hora de início e expiração para entender que o token SAS tem um tempo de vida limitado por padrão.
  6. Role para baixo e selecione o botão Gerar SAS e cadeia de conexão .
  7. Role mais para baixo e localize o campo URL SAS do serviço Blob
  8. Selecione o botão Copiar para a área de transferência na extremidade direita do campo URL SAS do serviço de Blob.
  9. Salve o URL copiado em algum lugar para uso em uma próxima etapa.

Nota

O token SAS retornado pelo portal não inclui o caractere delimitador ('?') para a cadeia de caracteres de consulta de URL. Se você estiver anexando o token SAS a uma URL de recurso, lembre-se de acrescentar o caractere delimitador à URL do recurso antes de anexar o token SAS.

Criar o projeto JavaScript

Crie um aplicativo JavaScript chamado blob-quickstart-v12.

  1. Em uma janela de console (como cmd, PowerShell ou Bash), crie um novo diretório para o projeto.

    mkdir blob-quickstart-v12

  2. Alterne para o diretório blob-quickstart-v12 recém-criado.

    cd blob-quickstart-v12

  3. Crie um package.json.

    npm init -y

  4. Abra o projeto no Visual Studio Code:

    code .

Instalar o pacote npm para armazenamento de blob

  1. Em um terminal do Visual Studio Code, instale o pacote npm do Armazenamento do Azure:

    npm install @azure/storage-blob

  2. Instale um pacote bundler para agrupar os arquivos e o pacote para o navegador:

    npm install parcel

    Se você planeja usar um bundler diferente, saiba mais sobre como agrupar o SDK do Azure.

Configurar a agregação de navegadores

  1. No Visual Studio Code, abra o arquivo package.json e adicione um browserlistarquivo . Isso browserlist tem como alvo a versão mais recente de navegadores populares. O arquivo de package.json completo agora deve ter esta aparência:

    "browserslist": [
  "last 1 Edge version",
  "last 1 Chrome version",
  "last 1 Firefox version",
  "last 1 safari version",
  "last 1 webkit version"
],

  2. Adicione um script de início para agrupar o site:

    "scripts": {
  "start": "parcel ./index.html"
},

Criar o arquivo HTML

  1. Crie index.html e adicione o seguinte código HTML:

    <!-- index.html -->
<!DOCTYPE html>
<html>

<body>
    <button id="create-container-button">Create container</button>
    <button id="select-button">Select and upload files</button>
    <input type="file" id="file-input" multiple style="display: none;" />
    <button id="list-button">List files</button>
    <button id="delete-button">Delete selected files</button>
    <button id="delete-container-button">Delete container</button>
    <p><b>Status:</b></p>
    <p id="status" style="height:160px; width: 593px; overflow: scroll;" />
    <p><b>Files:</b></p>
    <select id="file-list" multiple style="height:222px; width: 593px; overflow: scroll;" />
</body>

<script type="module" src="./index.js"></script>

</html>

Criar o arquivo JavaScript

No diretório do projeto:

  1. Crie um novo ficheiro com o nome index.js.

  2. Adicione o pacote npm do Armazenamento do Azure.

    const { BlobServiceClient } = require("@azure/storage-blob");

Declarar campos para elementos da interface do usuário

Adicione elementos DOM para interação do usuário:

const createContainerButton = document.getElementById("create-container-button");
const deleteContainerButton = document.getElementById("delete-container-button");
const selectButton = document.getElementById("select-button");
const fileInput = document.getElementById("file-input");
const listButton = document.getElementById("list-button");
const deleteButton = document.getElementById("delete-button");
const status = document.getElementById("status");
const fileList = document.getElementById("file-list");

const reportStatus = message => {
    status.innerHTML += `${message}<br/>`;
    status.scrollTop = status.scrollHeight;
}

Este código declara campos para cada elemento HTML e implementa uma reportStatus função para exibir a saída.

Adicione as informações da sua conta de armazenamento

Adicione o seguinte código no final do arquivo de index.js para acessar sua conta de armazenamento. Substitua o <placeholder> pelo URL SAS do serviço de Blob que você gerou anteriormente. Adicione o seguinte código ao final do arquivo index.js .

// Update <placeholder> with your Blob service SAS URL string
const blobSasUrl = "<placeholder>";

Criar objetos de cliente

Crie objetos BlobServiceClient e ContainerClient para se conectar à sua conta de armazenamento. Adicione o seguinte código ao final do arquivo index.js .

// Create a new BlobServiceClient
const blobServiceClient = new BlobServiceClient(blobSasUrl);

// Create a unique name for the container by 
// appending the current time to the file name
const containerName = "container" + new Date().getTime();

// Get a container client from the BlobServiceClient
const containerClient = blobServiceClient.getContainerClient(containerName);

Criar e excluir um contêiner de armazenamento

Crie e exclua o contêiner de armazenamento ao selecionar o botão correspondente na página da Web. Adicione o seguinte código ao final do arquivo index.js .

const createContainer = async () => {
    try {
        reportStatus(`Creating container "${containerName}"...`);
        await containerClient.create();
        reportStatus(`Done. URL:${containerClient.url}`);
    } catch (error) {
        reportStatus(error.message);
    }
};

const deleteContainer = async () => {
    try {
        reportStatus(`Deleting container "${containerName}"...`);
        await containerClient.delete();
        reportStatus(`Done.`);
    } catch (error) {
        reportStatus(error.message);
    }
};

createContainerButton.addEventListener("click", createContainer);
deleteContainerButton.addEventListener("click", deleteContainer);

Listar blobs

Liste o conteúdo do contêiner de armazenamento ao selecionar o botão Listar arquivos . Adicione o seguinte código ao final do arquivo index.js .

const listFiles = async () => {
    fileList.size = 0;
    fileList.innerHTML = "";
    try {
        reportStatus("Retrieving file list...");
        let iter = containerClient.listBlobsFlat();
        let blobItem = await iter.next();
        while (!blobItem.done) {
            fileList.size += 1;
            fileList.innerHTML += `<option>${blobItem.value.name}</option>`;


            blobItem = await iter.next();
        }
        if (fileList.size > 0) {
            reportStatus("Done.");
        } else {
            reportStatus("The container does not contain any files.");
        }
    } catch (error) {
        reportStatus(error.message);
    }
};

listButton.addEventListener("click", listFiles);

Esse código chama a função ContainerClient.listBlobsFlat e, em seguida, usa um iterador para recuperar o nome de cada BlobItem retornado. Para cada BlobItem, ele atualiza a lista Arquivos com o valor da propriedade name .

Carregar blobs para um contêiner

Carregue arquivos para o contêiner de armazenamento ao selecionar o botão Selecionar e carregar arquivos . Adicione o seguinte código ao final do arquivo index.js .

const uploadFiles = async () => {
    try {
        reportStatus("Uploading files...");
        const promises = [];
        for (const file of fileInput.files) {
            const blockBlobClient = containerClient.getBlockBlobClient(file.name);
            promises.push(blockBlobClient.uploadBrowserData(file));
        }
        await Promise.all(promises);
        reportStatus("Done.");
        listFiles();
    }
    catch (error) {
            reportStatus(error.message);
    }
}

selectButton.addEventListener("click", () => fileInput.click());
fileInput.addEventListener("change", uploadFiles);

Esse código conecta o botão Selecionar e carregar arquivos ao elemento oculto file-input . O evento button click dispara o evento de entrada click de arquivo e exibe o seletor de arquivos. Depois de selecionar arquivos e fechar a caixa de diálogo, o input evento ocorre e a uploadFiles função é chamada. Essa função cria um objeto BlockBlobClient e, em seguida, chama a função uploadBrowserData somente do navegador para cada arquivo selecionado. Cada chamada retorna um Promisearquivo . Cada Promise um é adicionado a uma lista para que todos possam ser aguardados juntos, fazendo com que os arquivos sejam carregados em paralelo.

Eliminar blobs

Exclua arquivos do contêiner de armazenamento ao selecionar o botão Excluir arquivos selecionados . Adicione o seguinte código ao final do arquivo index.js .

const deleteFiles = async () => {
    try {
        if (fileList.selectedOptions.length > 0) {
            reportStatus("Deleting files...");
            for (const option of fileList.selectedOptions) {
                await containerClient.deleteBlob(option.text);
            }
            reportStatus("Done.");
            listFiles();
        } else {
            reportStatus("No files selected.");
        }
    } catch (error) {
        reportStatus(error.message);
    }
};

deleteButton.addEventListener("click", deleteFiles);

Esse código chama a função ContainerClient.deleteBlob para remover cada arquivo selecionado na lista. Em seguida, ele chama a listFiles função mostrada anteriormente para atualizar o conteúdo da lista Arquivos .

Executar o código

  1. Em um terminal do Visual Studio Code, execute o aplicativo.

    npm start

    Este processo agrupa os ficheiros e inicia um servidor web.

  2. Acesse o site com um navegador usando o seguinte URL:

    http://localhost:1234

Etapa 1: Criar um contêiner

  1. No aplicativo Web, selecione Criar contêiner. O status indica que um contêiner foi criado.
  2. No portal do Azure, verifique se seu contêiner foi criado. Selecione a sua conta de armazenamento. Em Serviço Blob, selecione Contentores. Verifique se o novo contêiner aparece. (Pode ser necessário selecionar Atualizar.)

Etapa 2: Carregar um blob para o contêiner

  1. No computador local, crie e salve um arquivo de teste, como test.txt.
  2. No aplicativo Web, selecione Selecionar e carregar arquivos.
  3. Navegue até o arquivo de teste e selecione Abrir. O status indica que o arquivo foi carregado e a lista de arquivos foi recuperada.
  4. No portal do Azure, selecione o nome do novo contêiner que você criou anteriormente. Verifique se o arquivo de teste aparece.

Etapa 3: Excluir o blob

  1. No aplicativo Web, em Arquivos, selecione o arquivo de teste.
  2. Selecione Excluir arquivos selecionados. O status indica que o arquivo foi excluído e que o contêiner não contém arquivos.
  3. No portal do Azure, selecione Atualizar. Verifique se você vê Nenhum blobs encontrado.

Etapa 4: Excluir o contêiner

  1. No aplicativo Web, selecione Excluir contêiner. O status indica que o contêiner foi excluído.
  2. No portal do Azure, selecione o nome> da <conta | Link de contêineres no canto superior esquerdo do painel do portal.
  3. Selecione Atualizar. O novo contentor desaparece.
  4. Feche o aplicativo Web.

Utilizar o emulador do Armazenamento do Azure

Este início rápido criou um contêiner e um blob na nuvem do Azure. Você também pode usar o pacote npm de armazenamento de Blob do Azure para criar esses recursos localmente no emulador de Armazenamento do Azure para desenvolvimento e teste.

Clean up resources (Limpar recursos)

  1. Quando terminar este início rápido, exclua o blob-quickstart-v12 diretório.
  2. Se você tiver terminado de usar seu recurso de Armazenamento do Azure, remova seu grupo de recursos usando qualquer um dos métodos:

Próximos passos

Neste guia de início rápido, você aprendeu como carregar, listar e excluir blobs usando JavaScript. Você também aprendeu como criar e excluir um contêiner de armazenamento de blob.

Para tutoriais, exemplos, inícios rápidos e outra documentação, visite:

Documentação do Azure para JavaScript

  • Para saber mais, consulte a biblioteca de cliente de armazenamento de Blob do Azure para JavaScript.
  • Para ver os aplicativos de exemplo de armazenamento de Blob, continue para Exemplos de JavaScript da biblioteca de cliente de armazenamento de Blob do Azure v12.