Introducción a Azure Blob Storage y JavaScript
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
- Una suscripción a Azure: cree una cuenta gratuita
- Una cuenta de Azure Storage: cree una cuenta de almacenamiento
- LTS de Node.js
- Para las aplicaciones cliente (explorador), necesita herramientas de agrupación.
Configuración del proyecto
Abra un símbolo del sistema y cambie a la carpeta del proyecto. Cambie
YOUR-DIRECTORY
al nombre de la carpeta:cd YOUR-DIRECTORY
Si aún no tiene un archivo
package.json
en el directorio, inicialice el proyecto para crearlo:npm init -y
Instale la biblioteca cliente de Azure Blob Storage para JavaScript:
npm install @azure/storage-blob
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.
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.