Biblioteca cliente de Blob de Azure Storage para JavaScript: versión 12.17.0
Azure Storage Blob es la solución de almacenamiento de objetos de Microsoft para la nube. El almacenamiento de blobs está optimizado para almacenar grandes cantidades de datos no estructurados. Los datos no estructurados son datos que no cumplen un modelo de datos o definición concreta, como texto o datos binarios.
Este proyecto proporciona una biblioteca cliente en JavaScript que facilita el consumo de Microsoft Azure Storage Blob Service.
Use las bibliotecas cliente de este paquete para:
- Obtener o establecer propiedades de Blob Service
- Crear, enumerar y eliminar contenedores
- Crear,leer/enumerar/actualizar/eliminar blobs en bloques
- Crear,leer/enumerar/actualizar/eliminar blobs en páginas
- Crear,leer/enumerar/actualizar/eliminar blobs en anexos
Vínculos clave
- Código fuente
- Paquete (npm)
- Documentación de referencia de API
- Documentación del producto
- Muestras
- API REST de Blob de Azure Storage
Introducción
Entornos admitidos actualmente
- Versiones de LTS de Node.js
- Versiones más recientes de Safari, Chrome, Edge y Firefox.
Para más información, consulte la directiva de compatibilidad.
Requisitos previos
Instalar el paquete
La manera preferida de instalar la biblioteca cliente de Blob de Azure Storage para JavaScript es usar el administrador de paquetes npm. Escriba lo siguiente en una ventana de terminal:
npm install @azure/storage-blob
Autenticar el cliente
Azure Storage admite varias maneras de autenticarse. Para interactuar con el servicio Azure Blob Storage, deberá crear una instancia de un cliente de Storage: BlobServiceClient
, ContainerClient
o BlobClient
por ejemplo. Consulte ejemplos para crear para obtener más información sobre la BlobServiceClient
autenticación.
Azure Active Directory
El servicio Azure Blob Storage admite el uso de Azure Active Directory para autenticar las solicitudes en sus API. El paquete @azure/identity
proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. Consulte el archivo Léame para @azure/identity
obtener más detalles y ejemplos para empezar.
Compatibilidad
Esta biblioteca es compatible con Node.js y exploradores, y se valida con las versiones de ltS Node.js (>=8.16.0) y las versiones más recientes de Chrome, Firefox y Edge.
Trabajos web
Esta biblioteca requiere que determinados objetos DOM estén disponibles globalmente cuando se usan en el explorador, que los trabajadores web no están disponibles de forma predeterminada. Tendrá que polirrellenar estos elementos para que esta biblioteca funcione en trabajos web.
Para más información, consulte nuestra documentación sobre el uso del SDK de Azure para JS en trabajos web.
Esta biblioteca depende de las siguientes API DOM que necesitan polirrellenes externos cargados cuando se usan en trabajos web:
Diferencias entre Node.js y exploradores
Hay diferencias entre Node.js y el entorno de ejecución de exploradores. Al empezar a trabajar con esta biblioteca, preste atención a las API o clases marcadas con "ONLY AVAILABLE IN NODE.JS RUNTIME" o "ONLY AVAILABLE IN BROWSER" (SOLO DISPONIBLE EN EXPLORADORES).
- Si un blob contiene datos comprimidos en
gzip
formato odeflate
y su codificación de contenido se establece en consecuencia, el comportamiento de descarga es diferente entre Node.js y exploradores. En Node.js los clientes de almacenamiento descargarán el blob en su formato comprimido, mientras que en los exploradores los datos se descargarán en formato des comprimido.
Características, interfaces, clases o funciones solo disponibles en Node.js
- Autorización de clave compartida basada en el nombre de cuenta y la clave de cuenta
StorageSharedKeyCredential
- Generación de firmas de acceso compartido (SAS)
generateAccountSASQueryParameters()
generateBlobSASQueryParameters()
- Carga y descarga en paralelo. Tenga en cuenta que
BlockBlobClient.uploadData()
está disponible tanto en Node.js como en exploradores.BlockBlobClient.uploadFile()
BlockBlobClient.uploadStream()
BlobClient.downloadToBuffer()
BlobClient.downloadToFile()
Características, interfaces, clases o funciones solo disponibles en exploradores
- Carga y descarga en paralelo
BlockBlobClient.uploadBrowserData()
Paquete de JavaScript
Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.
CORS
Debe configurar reglas de uso compartido de recursos entre orígenes (CORS) para la cuenta de almacenamiento si necesita desarrollar para exploradores. Vaya a Azure Portal y Explorador de Azure Storage, busque la cuenta de almacenamiento, cree nuevas reglas de CORS para blob/queue/file/table service(s).
Por ejemplo, puede crear la siguiente configuración de CORS para la depuración. Pero personalice cuidadosamente la configuración según sus requisitos en el entorno de producción.
- Orígenes permitidos: *
- Verbos permitidos: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
- Encabezados permitidos: *
- Encabezados expuestos: *
- Antigüedad máxima (segundos): 86400
Conceptos clave
Blob Storage está diseñado para:
- Visualización de imágenes o documentos directamente en un explorador.
- Almacenamiento de archivos para acceso distribuido.
- Streaming de audio y vídeo.
- Escribir en archivos de registro.
- Almacenamiento de datos para copia de seguridad y restauración, recuperación ante desastres y archivado.
- Almacenamiento de datos para el análisis en local o en un servicio hospedado de Azure.
Blob Storage ofrece tres tipos de recursos:
- La cuenta de almacenamiento usada a través de
BlobServiceClient
- Un contenedor de la cuenta de almacenamiento que se usa a través de
ContainerClient
- Un blob en un contenedor usado a través de
BlobClient
Ejemplos
- Importación del paquete
- Creación del cliente de Blob service
- Creación de un contenedor
- Enumeración de los contenedores
- Creación de un blob mediante la carga de datos
- Enumeración de blobs dentro de un contenedor
- Descargue un blob y conviértalo en una cadena (Node.js)
- Descargue un blob y conviértalo en una cadena (exploradores)
Importación del paquete
Para usar los clientes, importe el paquete en el archivo:
const AzureStorageBlob = require("@azure/storage-blob");
Como alternativa, importe selectivamente solo los tipos que necesita:
const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");
Creación del cliente de Blob service
BlobServiceClient
requiere una dirección URL para blob service y una credencial de acceso. También acepta opcionalmente algunas opciones de configuración en el options
parámetro .
con DefaultAzureCredential
desde @azure/identity
el paquete
Manera recomendada de crear una instancia de un BlobServiceClient
Configuración: Referencia: autorización del acceso a blobs y colas con Azure Active Directory desde una aplicación cliente: /azure/storage/common/storage-auth-aad-app
Registro de una nueva aplicación de AAD y concesión de permisos para acceder a Azure Storage en nombre del usuario que ha iniciado sesión
- Registro de una nueva aplicación en Azure Active Directory (en azure-portal): /azure/active-directory/develop/quickstart-register-app
- En la
API permissions
sección , seleccioneAdd a permission
y elijaMicrosoft APIs
. - Seleccione
Azure Storage
y active la casilla situada junto a y, auser_impersonation
continuación, haga clic enAdd permissions
. Esto permitiría que la aplicación acceda a Azure Storage en nombre del usuario que ha iniciado sesión.
Concesión de acceso a datos de blobs de Azure con RBAC en Azure Portal
- Roles RBAC para blobs y colas: /azure/storage/common/storage-auth-aad-rbac-portal.
- En Azure Portal, vaya a la cuenta de almacenamiento y asigne el rol Colaborador de datos de Storage Blob a la aplicación de AAD registrada desde
Access control (IAM)
la pestaña (en la barra de navegación del lado izquierdo de la cuenta de almacenamiento en azure-portal).
Configuración del entorno para el ejemplo
- En la página de información general de la aplicación de AAD, anote y
CLIENT ID
TENANT ID
. En la pestaña "Certificados & secretos", cree un secreto y anote eso. - Asegúrese de que tiene AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET como variables de entorno para ejecutar correctamente el ejemplo(Puede aprovechar process.env).
- En la página de información general de la aplicación de AAD, anote y
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
Consulte el ejemplo de autenticación de Azure AD para obtener un ejemplo completo con este método.
[Nota: Los pasos anteriores solo son para Node.js]
usar cadena de conexión
Como alternativa, puede crear una BlobServiceClient
instancia de mediante el fromConnectionString()
método estático con el cadena de conexión completo como argumento. (La cadena de conexión se puede obtener de Azure Portal). [SOLO DISPONIBLE EN NODE.JS RUNTIME]
const { BlobServiceClient } = require("@azure/storage-blob");
const connStr = "<connection string>";
const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);
Con StorageSharedKeyCredential
Como alternativa, cree una BlobServiceClient
instancia de con un StorageSharedKeyCredential
mediante el paso de account-name y account-key como argumentos. (El nombre de cuenta y la clave de cuenta se pueden obtener en Azure Portal). [SOLO DISPONIBLE EN NODE.JS RUNTIME]
const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");
// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
sharedKeyCredential
);
con token de SAS
Además, puede crear BlobServiceClient
una instancia de con una firma de acceso compartido (SAS). Puede obtener el token de SAS desde Azure Portal o generar uno mediante generateAccountSASQueryParameters()
.
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);
Crear un contenedor nuevo
Use BlobServiceClient.getContainerClient()
para obtener una instancia de cliente de contenedor y, a continuación, cree un nuevo recurso de contenedor.
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}
main();
Enumeración de los contenedores
Use BlobServiceClient.listContainers()
la función para iterar los contenedores, con la nueva for-await-of
sintaxis:
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
let containers = blobServiceClient.listContainers();
for await (const container of containers) {
console.log(`Container ${i++}: ${container.name}`);
}
}
main();
Como alternativa, sin usar for-await-of
:
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
let iter = blobServiceClient.listContainers();
let containerItem = await iter.next();
while (!containerItem.done) {
console.log(`Container ${i++}: ${containerItem.value.name}`);
containerItem = await iter.next();
}
}
main();
Además, la paginación también se admite para enumerar a través de byPage()
:
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
async function main() {
let i = 1;
for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
if (response.containerItems) {
for (const container of response.containerItems) {
console.log(`Container ${i++}: ${container.name}`);
}
}
}
}
main();
Para obtener un ejemplo completo sobre la iteración de contenedores, consulte samples/v12/typescript/src/listContainers.ts.
Creación de un blob mediante la carga de datos
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const content = "Hello world!";
const blobName = "newblob" + new Date().getTime();
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}
main();
Enumeración de blobs dentro de un contenedor
Similar a enumerar contenedores.
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
let i = 1;
let blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
console.log(`Blob ${i++}: ${blob.name}`);
}
}
main();
Para obtener un ejemplo completo sobre la iteración de blobs, consulte samples/v12/typescript/src/listBlobsFlat.ts.
Descargue un blob y conviértalo en una cadena (Node.js)
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();
const blobServiceClient = new BlobServiceClient(
`https://${account}.blob.core.windows.net`,
defaultAzureCredential
);
const containerName = "<container name>";
const blobName = "<blob name>";
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);
// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = (
await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
).toString();
console.log("Downloaded blob content:", downloaded);
// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
async function streamToBuffer(readableStream) {
return new Promise((resolve, reject) => {
const chunks = [];
readableStream.on("data", (data) => {
chunks.push(data instanceof Buffer ? data : Buffer.from(data));
});
readableStream.on("end", () => {
resolve(Buffer.concat(chunks));
});
readableStream.on("error", reject);
});
}
}
main();
Descargue un blob y conviértalo en una cadena (exploradores).
Consulte la sección Paquete de JavaScript para obtener más información sobre el uso de esta biblioteca en el explorador.
const { BlobServiceClient } = require("@azure/storage-blob");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";
const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);
async function main() {
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);
// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
console.log("Downloaded blob content", downloaded);
// [Browsers only] A helper method used to convert a browser Blob into string.
async function blobToString(blob) {
const fileReader = new FileReader();
return new Promise((resolve, reject) => {
fileReader.onloadend = (ev) => {
resolve(ev.target.result);
};
fileReader.onerror = reject;
fileReader.readAsText(blob);
});
}
}
main();
Un ejemplo completo de escenarios simples se encuentra en samples/v12/typescript/src/sharedKeyAuth.ts.
Solución de problemas
La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL
en info
. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel
en @azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Pasos siguientes
Más ejemplos de código:
- Ejemplos de Blob Storage (JavaScript)
- Ejemplos de Blob Storage (TypeScript)
- Casos de prueba de Blob Storage
Contribuciones
Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.
Consulte también la guía específica del almacenamiento para obtener información adicional sobre cómo configurar el entorno de prueba para las bibliotecas de almacenamiento.
Azure SDK for JavaScript
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de