Introducción a Azure Blob Storage y JavaScript o TypeScript

• .NET
• Java
• JavaScript
• Python
• Go

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

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

Prerrequisitos

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• LTS de Node.js
• TypeScript, si procede
• Para las aplicaciones cliente (explorador), necesita herramientas de agrupación.

Configuración del proyecto

Esta sección le guiará a través de la preparación de un proyecto para trabajar con la biblioteca de cliente Azure Blob Storage para JavaScript.

Abra un símbolo del sistema y vaya a la carpeta del proyecto. Cambie <project-directory> al nombre de la carpeta:

cd <project-directory>

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

npm init -y

Desde el directorio de su proyecto, instale los paquetes para las bibliotecas cliente Azure Blob Storage y Azure Identity utilizando los comandos npm install o yarn add. El paquete @azure/identity es necesario para las conexiones sin contraseña a los servicios de Azure.

JavaScript

npm install @azure/storage-blob @azure/identity

TypeScript

npm install typescript @azure/storage-blob @azure/identity

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

Para conectar una aplicación a Blob Storage, cree una instancia de la clase BlobServiceClient. Este objeto es el punto inicial para interactuar con los recursos de datos en el nivel de cuenta de almacenamiento. Puede usarlo para operar en la cuenta de almacenamiento y sus contenedores. También puede usar el cliente de servicio para crear clientes de contenedor o clientes de blobs, en función del recurso con el que necesite trabajar.

Para obtener más información sobre cómo crear y administrar objetos de cliente, incluidos los procedimientos recomendados, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Puede autorizar un objeto BlobServiceClient mediante un token de autorización de Microsoft Entra, una clave de acceso de cuenta o una firma de acceso compartido. Para una seguridad óptima, Microsoft recomienda usar Microsoft Entra ID con identidades administradas para autorizar solicitudes contra datos de blobs. Para más información, vea Autorización del acceso a blobs mediante Microsoft Entra ID.

Microsoft Entra ID (recomendado)

Para autorizar con Microsoft Entra ID, debe usar una entidad de seguridad. El tipo de entidad de seguridad que necesita depende de dónde se ejecute la aplicación. Use la siguiente tabla como guía:

Dónde se ejecuta la aplicación	Entidad de seguridad	Guía
Máquina local (desarrollo y pruebas)	Entidad de servicio	Con el fin de descubrir cómo registrar la aplicación, configurar un grupo de Microsoft Entra, asignar roles y configurar variables de entorno, consulte Autorización del acceso mediante entidades de servicio para desarrolladores
Máquina local (desarrollo y pruebas)	Identidad del usuario	Con el fin de descubrir cómo configurar un grupo de Microsoft Entra, asignar roles e iniciar sesión en Azure, consulte Autorización del acceso mediante credenciales para desarrolladores
Hospedado en Azure	Identidad administrada	Para descubrir cómo habilitar la identidad administrada y asignar roles, vea Autorización del acceso desde aplicaciones hospedadas en Azure mediante una identidad administrada.
Hospedado fuera de Azure (por ejemplo, aplicaciones locales)	Entidad de servicio	Para descubrir cómo registrar la aplicación, asignar roles y configurar variables de entorno, vea Autorización del acceso desde aplicaciones locales mediante una entidad de servicio de aplicación.

Autorización del acceso mediante DefaultAzureCredential

Una manera fácil y segura de autorizar el acceso y conectarse a Blob Storage es obtener un token de OAuth mediante la creación de una instancia de DefaultAzureCredential. A continuación, puede utilizar esa credencial para crear un objeto BlobServiceClient.

En el ejemplo siguiente, se crea un objeto BlobServiceClient con DefaultAzureCredential:

const accountName = "<account-name>";
const accountURL = `https://${accountName}.blob.core.windows.net`;
const blobServiceClient = new BlobServiceClient(
  accountURL,
  new DefaultAzureCredential()
);

Este ejemplo de código se puede utilizar para proyectos JavaScript o TypeScript.

Token de SAS

Para utilizar un token de firma de acceso compartido (SAS), agregue el token a la cadena URL de la cuenta separado por un delimitador ?. A continuación, cree un objeto BlobServiceClient con la dirección URL.

const accountName = "<account-name>";
const sasToken = "<sas-token>";
const accountURL = `https://${accountName}.blob.core.windows.net?${sasToken}`;
const blobServiceClient = new BlobServiceClient(accountURL);

Este ejemplo de código se puede utilizar para proyectos JavaScript o TypeScript.

Para obtener más información sobre cómo generar y administrar los tokens de SAS, consulte los artículos siguientes:

• Grant limited access to Azure Storage resources using shared access signatures (SAS) (Otorgar acceso limitado a recursos de Azure Storage con firmas de acceso compartido [SAS])
• Cree una cuenta SAS con JavaScript
• Cree un servicio SAS con JavaScript
• Cree una delegación de usuarios SAS con JavaScript

Nota:

Para escenarios en los que se utilizan firmas de acceso compartido (SAS), Microsoft recomienda usar un SAS de delegación de usuario. Una SAS de delegación de usuarios está protegida con credenciales de Microsoft Entra en lugar de la clave de cuenta.

Clave de cuenta

Para utilizar una clave compartida de cuenta de almacenamiento, proporcione la clave como una cadena e inicialice un objeto BlobServiceClient.

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

Este ejemplo de código se puede utilizar para proyectos JavaScript o TypeScript.

También puede crear un objeto BlobServiceClient mediante una cadena de conexión.

const blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);

Para obtener información sobre cómo obtener claves de cuenta y directrices de procedimientos recomendados para administrar y proteger correctamente las claves, consulte Administración de claves de acceso de la cuenta de almacenamiento.

Importante

La clave de acceso de la cuenta debe usarse con precaución. Si la clave de acceso de la cuenta se pierde o se coloca por accidente en una ubicación no segura, el servicio puede volverse vulnerable. Cualquier persona que tenga la clave de acceso puede autorizar las solicitudes en la cuenta de almacenamiento y tiene acceso eficaz a todos los datos. DefaultAzureCredential proporciona características y ventajas de seguridad mejoradas y es el enfoque recomendado para administrar la autorización en los servicios de Azure.

Compilación de la aplicación

A medida que compila aplicaciones para trabajar con recursos de datos en Azure Blob Storage, el código interactúa principalmente con tres tipos de recursos: cuentas de almacenamiento, contenedores y blobs. Para más información sobre estos tipos de recursos, cómo se relacionan entre sí y cómo interactúan las aplicaciones con los recursos, consulte Descripción de cómo interactúan las aplicaciones con los recursos de datos de Blob Storage.

Las siguientes guías muestran cómo acceder a los datos y realizar acciones específicas utilizando la biblioteca de clientes de Azure Storage para JavaScript:

Guía	Descripción
Configuración de una directiva de reintentos	Implemente directivas de reintento para las operaciones de cliente.
Copia de blobs	Copie un blob de una ubicación a otra.
Creación de un contenedor	Cree contenedores de blobs.
Creación de una SAS de delegación de usuario	Creación de una SAS de delegación de usuarios para un contenedor o blob.
Creación y administración de concesiones de blobs	Establezca y administre un bloqueo en un blob.
Creación y administración de concesiones de contenedores	Establezca y administre un bloqueo en un contenedor.
Eliminar y restaurar	Elimine blobs y restaure los blobs eliminados temporalmente.
Eliminación y restauración de contenedores	Elimine contenedores y restaure los contenedores eliminados temporalmente.
Descarga de los blobs	Descargue blobs mediante cadenas, secuencias y rutas de acceso de archivo.
Búsqueda de blobs mediante etiquetas	Establezca y recupere etiquetas, además de usar etiquetas para buscar blobs.
Enumeración de blobs	Enumere los blobs de diferentes maneras.
Enumeración de contenedores	Enumere los contenedores de una cuenta y las distintas opciones disponibles para personalizar una lista.
Administración de propiedades y metadatos (blobs)	Obtenga y establezca las propiedades y los metadatos de los blobs.
Administración de propiedades y metadatos (contenedores)	Obtenga y establezca las propiedades y los metadatos de los contenedores.
Optimización del rendimiento de las transferencias de datos	Optimice el rendimiento de las transferencias de datos.
Establecer o cambiar el nivel de acceso de un blob	Establezca o cambie el nivel de acceso de un blob en bloques.
Carga de blobs	Aprenda a cargar blobs mediante cadenas, secuencias, rutas de acceso de archivo y otros métodos.