Introducción a Azure Blob Storage y JavaScript

  • Artículo

En este artículo se muestra cómo conectarse a Azure Blob Storage mediante la biblioteca cliente de Azure Blob Storage v12 para JavaScript. Una vez conectado, el código puede funcionar en contenedores, blobs y características del servicio Blob Storage.

Los fragmentos de código de ejemplo están disponibles en GitHub como archivos de Node.js ejecutables.

Referencia de API | Paquete (npm) | Código fuente de la biblioteca | Muestras | Enviar comentarios

Prerrequisitos

Configuración del proyecto

  1. Abra un símbolo del sistema y cambie a la carpeta del proyecto. Cambie YOUR-DIRECTORY al nombre de la carpeta:

    cd YOUR-DIRECTORY

  2. Si aún no tiene un archivo package.json en el directorio, inicialice el proyecto para crearlo:

    npm init -y

  3. Instale la biblioteca cliente de Azure Blob Storage para JavaScript:

    npm install @azure/storage-blob

  4. Si quiere usar conexiones sin contraseña mediante Microsoft Entra ID, instale la biblioteca cliente de Azure Identity para JavaScript:

    npm install @azure/identity

Autorización del acceso y conexión a Blob Storage

Microsoft Entra ID proporciona la conexión más segura mediante la administración de la identidad de conexión (identidad administrada). Esta funcionalidad sin contraseña permite desarrollar una aplicación que no requiere tener secretos (claves o cadenas de conexión) almacenados en el código.

Configuración del acceso de identidad a la nube de Azure

Para conectarse a Azure sin contraseñas, debe configurar una identidad de Azure o usar una identidad existente. Una vez configurada la identidad, asegúrese de asignar los roles adecuados a la identidad.

Para llevar a cabo la autorización de acceso sin contraseña con Microsoft Entra ID, deberá usar una credencial de Azure. El tipo de credencial que necesita depende de dónde se ejecute la aplicación. Use esta tabla como guía.

Entorno Método
Entorno del desarrollador Visual Studio Code
Entorno del desarrollador Entidad de servicio
Aplicaciones hospedadas en Azure Configuración de aplicaciones hospedadas en Azure
Local Configuración de aplicaciones locales

Configuración de roles de cuenta de almacenamiento

El recurso de Storage debe tener uno o varios de los siguientes roles de Azure RBAC asignados al recurso de identidad con el que planea conectarse. Configure los roles de Azure Storage para cada identidad que creó en el paso anterior: nube de Azure y desarrollo local.

Después de completar la configuración, cada identidad necesita al menos uno de los roles adecuados:

  • Un rol de acceso a datos, por ejemplo:

    • Lector de datos de blobs de almacenamiento
    • Colaborador de datos de blobs de almacenamiento

  • Un rol de recurso, por ejemplo:

    • Lector
    • Colaborador

Compilación de la aplicación

A medida que compile la aplicación, el código interactuará principalmente con tres tipos de recursos:

  • La cuenta de almacenamiento, que es el espacio de nombres exclusivo para los objetos de datos de Azure Storage.
  • Contenedores, que organizan los datos de blob en la cuenta de almacenamiento.
  • Blobs, que almacenan datos no estructurados como texto y datos binarios.

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagram of Blob storage architecture

Cada tipo de recurso se representa mediante uno o varios clientes de JavaScript asociados:

Clase Descripción
BlobServiceClient Representa el punto de conexión de Blob Storage para la cuenta de almacenamiento.
ContainerClient Le permite manipular los contenedores de Azure Storage y sus blobs.
BlobClient Le permite manipular los blobs de Azure Storage.

Creación de un objeto BlobServiceClient

BlobServiceClient es el objeto principal del SDK. Este cliente permite manipular el servicio, los contenedores y los blobs.

Una vez configurados los roles de identidad de la cuenta de almacenamiento de Azure y el entorno local, cree un archivo JavaScript que incluya el paquete @azure/identity. Cree una credencial, como DefaultAzureCredential, para implementar conexiones sin contraseña en Blob Storage. Use esa credencial para autenticarse con un objeto BlobServiceClient.

// connect-with-default-azure-credential.js
const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error('Azure Storage accountName not found');

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

El paquete dotenv se usa para leer el nombre de la cuenta de almacenamiento de un archivo .env. No hace falta comprobar este archivo en el control de código fuente. Si usa una entidad de servicio local como parte de la configuración de DefaultAzureCredential, cualquier información de seguridad de esa credencial también entrará en el archivo .env.

Si tiene previsto implementar la aplicación en servidores y clientes que se ejecutan fuera de Azure, cree una de las credenciales que satisfagan sus necesidades.

Creación de un objeto ContainerClient

Puede crear el objeto ContainerClient desde BlobServiceClient o directamente.

Creación de un objeto ContainerClient desde BlobServiceClient

Cree el objeto ContainerClient a partir de BlobServiceClient.

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlobServiceClient,
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
  `${baseUrl}`,
  sharedKeyCredential
);

async function main() {
  try {
    // Create container client
    const containerClient = await blobServiceClient.getContainerClient(
      containerName
    );

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Creación de ContainerClient directamente

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Unique container name
const timeStamp = Date.now();
const containerName = `test`;

async function main() {
  try {
    
    // create container client from DefaultAzureCredential
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      new DefaultAzureCredential()
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }


  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

El paquete dotenv se usa para leer el nombre de la cuenta de almacenamiento de un archivo .env. No hace falta comprobar este archivo en el control de código fuente.

Creación de un objeto BlobClient

Puede crear cualquiera de los objetos BlobClient, que se enumeran a continuación, desde un ContainerClient o directamente.

Lista de clientes de blobs:

Creación de un objeto BlobClient desde ContainerClient

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

// Create ContainerClient
const containerClient = new ContainerClient(
  `${baseUrl}/${containerName}`,
  sharedKeyCredential
);  

async function main() {
  try {
  
    // Create BlobClient object
    const blobClient = containerClient.getBlobClient(blobName);

    // do something with blobClient...
    const properties = await blobClient.getProperties();
    console.log(`Blob ${blobName} properties:`);

    // get BlockBlobClient from blobClient
    const blockBlobClient = blobClient.getBlockBlobClient();

    // do something with blockBlobClient...
    const downloadResponse = await blockBlobClient.download(0);

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Creación de BlobClient directamente

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Container must exist prior to running this script
const containerName = `test`;

// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = "Hello there.";

async function main(){

  // Create a client that can authenticate with Azure Active Directory
  const client = new BlockBlobClient(
    `${baseUrl}/${containerName}/${blobName}`,
    new DefaultAzureCredential()
  );

  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${client.url}`);

  // Upload file contents
  const result = await client.upload(fileContentsAsString, fileContentsAsString.length);

  // Get results
  return result;
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

/*

Response looks like this:

{
  etag: '"0x8DAD247F1F4896E"',
  lastModified: 2022-11-29T20:26:07.000Z,
  contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
  clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
  requestId: '3580e726-201e-0045-1a30-0474f6000000',
  version: '2021-04-10',
  date: 2022-11-29T20:26:06.000Z,
  isServerEncrypted: true,
  'content-length': '0',
  server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
  'x-ms-content-crc64': 'BLv7vb1ONT8=',
  body: undefined
}
*/

El paquete dotenv se usa para leer el nombre de la cuenta de almacenamiento de un archivo .env. No hace falta comprobar este archivo en el control de código fuente.

Consulte también