Biblioteca cliente de Recurso compartido de archivos de Azure Storage para JavaScript

Azure Files ofrece recursos compartidos de archivos totalmente administrados en la nube a los que se puede acceder mediante el protocolo estándar del bloque de mensajes del servidor (SMB) estándar del sector. Los recursos compartidos de archivos de Azure se pueden montar simultáneamente mediante implementaciones locales o en la nube de Windows, Linux y macOS. Además, los recursos compartidos de archivos de Azure se pueden almacenar en caché en servidores windows con Azure File Sync para un acceso rápido cerca de dónde se usan los datos.

Este proyecto proporciona una biblioteca cliente en JavaScript que facilita el consumo del servicio Microsoft Azure File Storage.

Use las bibliotecas cliente de este paquete para:

Obtener o establecer propiedades del servicio de archivos
Crear, enumerar o eliminar recursos compartidos de archivos
Crear, enumerar y eliminar directorios de archivos
Crear/Leer/Enumerar/Actualizar/Eliminar archivos

Nota: Este paquete se publicó anteriormente con el nombre @azure/storage-file. Se ha cambiado el nombre de @azure/storage-file-share para alinearse mejor con el próximo paquete nuevo para DataLake de Azure Storage Files y proporcionar un conjunto coherente de API para trabajar con archivos en Azure.

Vínculos clave:

Cómo empezar

Entornos admitidos actualmente

versiones ltS de Node.js
Versiones más recientes de Safari, Chrome, Edge y Firefox.

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerequisites

Instalación del paquete

La manera preferida de instalar la biblioteca cliente de Azure File Storage para JavaScript es usar el administrador de paquetes npm. Escriba lo siguiente en una ventana de terminal:

npm install @azure/storage-file-share

Autenticación del cliente

Azure Storage admite varias maneras de autenticarse. Para interactuar con el servicio recurso compartido de archivos de Azure Storage, deberá crear una instancia de un cliente de Storage: ShareServiceClient, ShareCliento ShareDirectoryClient, por ejemplo. Consulte ejemplos para crear el ShareServiceClient para obtener más información sobre la autenticación.

Clave compartida
firmas de acceso compartido

Compatibility

Esta biblioteca es compatible con Node.js y exploradores, y se valida con versiones de Node.js LTS (>=8.16.0) y las versiones más recientes de Chrome, Firefox y Edge.

Trabajadores web

Esta biblioteca requiere que determinados objetos DOM estén disponibles globalmente cuando se usan en el explorador, que los trabajos 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 de para usar Azure SDK para JS en Web Workers

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 "SOLO DISPONIBLE EN NODE.JS RUNTIME" o "SOLO DISPONIBLE EN EXPLORADORES".

Si un archivo contiene datos comprimidos en formato gzip o deflate 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 archivo en su formato comprimido, mientras que en los exploradores los datos se descargarán en formato des comprimido.

Las siguientes características, interfaces, clases o funciones solo están 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()
- generateFileSASQueryParameters()
Carga y descarga en paralelo. Tenga en cuenta que ShareFileClient.uploadData() está disponible tanto en Node.js como en exploradores.
- ShareFileClient.uploadFile()
- ShareFileClient.uploadStream()
- ShareFileClient.downloadToBuffer()
- ShareFileClient.downloadToFile()

Las siguientes características, interfaces, clases o funciones solo están disponibles en exploradores

N/A

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

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 al Explorador de Azure Storage, busque la cuenta de almacenamiento y 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

Los siguientes componentes y sus bibliotecas cliente correspondientes componen el servicio Recurso compartido de archivos de Azure Storage:

La propia cuenta de almacenamiento , representada por un ShareServiceClient
Un recurso compartido de archivos dentro de la cuenta de almacenamiento, representado por un ShareClient
Jerarquía opcional de directorios dentro del recurso compartido de archivos, representado por instancias de ShareDirectoryClient
Un archivo dentro del recurso compartido de archivos, que puede tener un tamaño de hasta 1 TiB, representado por un ShareFileClient

Examples

Importar el paquete
Creación del de cliente del servicio de recursos compartidos
Enumerar recursos compartidos de la cuenta
Crear un recurso compartido y un directorio
Crear un archivo de Azure y, a continuación, cargarlo en él
Enumerar archivos y directorios en un directorio
Descargar un archivo y convertirlo en una cadena (Node.js)
Descargar un archivo y convertirlo en una cadena (Exploradores)

Importación del paquete

Para usar los clientes, importe el paquete en el archivo:

import * as AzureStorageFileShare from "@azure/storage-file-share";

Como alternativa, importe de forma selectiva solo los tipos que necesita:

import { ShareServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-share";

El ShareServiceClient requiere una dirección URL para el servicio de recurso compartido de archivos y una credencial de acceso. También acepta algunas opciones de configuración en el parámetro options.

uso de la cadena de conexión

Como alternativa, puede crear una instancia de un ShareServiceClient mediante el método estático fromConnectionString() con la cadena de conexión completa como argumento. (La cadena de conexión se puede obtener desde azure Portal).

import { ShareServiceClient } from "@azure/storage-file-share";

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

con `StorageSharedKeyCredential`

Pase un StorageSharedKeyCredential con el nombre de la cuenta y la clave de cuenta. (El nombre de cuenta y la clave de cuenta se pueden obtener en Azure Portal).

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

// 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 credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  // When using AnonymousCredential, following url should include a valid SAS
  `https://${account}.file.core.windows.net`,
  credential,
);

con token de SAS

Además, puede crear instancias de un ShareServiceClient con firmas de acceso compartido (SAS). Puede obtener el token de SAS desde Azure Portal o generar uno mediante generateAccountSASQueryParameters().

import { ShareServiceClient } from "@azure/storage-file-share";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new ShareServiceClient(
  `https://${account}.file.core.windows.net?${sas}`,
);

Enumeración de recursos compartidos en la cuenta

Use ShareServiceClient.listShares() para los recursos compartidos de iterador en esta cuenta, con la nueva sintaxis de for-await-of:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

let i = 1;
for await (const share of serviceClient.listShares()) {
  console.log(`Share${i++}: ${share.name}`);
}

Como alternativa, sin for-await-of:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareIter = serviceClient.listShares();
let i = 1;
let { value, done } = await shareIter.next();
while (!done) {
  console.log(`Share ${i++}: ${value.name}`);
  ({ value, done } = await shareIter.next());
}

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = `newshare${+new Date()}`;
const shareClient = serviceClient.getShareClient(shareName);
await shareClient.create();
console.log(`Create share ${shareName} successfully`);

const directoryName = `newdirectory${+new Date()}`;
const directoryClient = shareClient.getDirectoryClient(directoryName);
await directoryClient.create();
console.log(`Create directory ${directoryName} successfully`);

Cree un archivo de Azure y cárguelo en él.

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const content = "Hello World!";
const fileName = `newdirectory${+new Date()}`;
const fileClient = directoryClient.getFileClient(fileName);
await fileClient.create(content.length);
console.log(`Create file ${fileName} successfully`);

// Upload file range
await fileClient.uploadRange(content, 0, content.length);
console.log(`Upload file range "${content}" to ${fileName} successfully`);

Enumerar archivos y directorios en un directorio

Use DirectoryClient.listFilesAndDirectories() para iterador en archivos y directorios, con la nueva sintaxis de for-await-of. La propiedad kind se puede usar para identificar si un iterm es un directorio o un archivo.

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let i = 1;
for await (const item of directoryClient.listFilesAndDirectories()) {
  if (item.kind === "directory") {
    console.log(`${i} - directory\t: ${item.name}`);
  } else {
    console.log(`${i} - file\t: ${item.name}`);
  }
  i++;
}

Como alternativa, sin usar for-await-of:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let i = 1;
const iter = directoryClient.listFilesAndDirectories();
let { value, done } = await iter.next();
while (!done) {
  if (value.kind === "directory") {
    console.log(`${i} - directory\t: ${value.name}`);
  } else {
    console.log(`${i} - file\t: ${value.name}`);
  }
  ({ value, done } = await iter.next());
  i++;
}

Para obtener un ejemplo completo sobre la iteración, consulte samples/v12/typescript/src/listFilesAndDirectories.ts.

Descargar un archivo y convertirlo en una cadena (Node.js)

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const fileName = "<file name>";
const fileClient = serviceClient
  .getShareClient(shareName)
  .rootDirectoryClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadFileResponse.readableStreamBody
const downloadFileResponse = await fileClient.download();
if (downloadFileResponse.readableStreamBody) {
  const buffer = await streamToBuffer(downloadFileResponse.readableStreamBody);
  console.log(`Downloaded file content: ${buffer.toString()}`);
}

// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
async function streamToBuffer(readableStream: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

Descargar un archivo y convertirlo 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 navegador.

import { ShareServiceClient } from "@azure/storage-file-share";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClient = new ShareServiceClient(`https://${account}.file.core.windows.net?${sas}`);

const shareName = "<share name>";
const fileName = "<file name>";
const fileClient = serviceClient
  .getShareClient(shareName)
  .rootDirectoryClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In browsers, get downloaded data by accessing downloadFileResponse.blobBody
const downloadFileResponse = await fileClient.download(0);
if (downloadFileResponse.blobBody) {
  console.log(`Downloaded file content: ${(await downloadFileResponse.blobBody).text()}`);
}

Un ejemplo completo de escenarios simples ShareServiceClient está en samples/v12/typescript/src/shareSerivceClient.ts.

Troubleshooting

Habilitar el registro puede ayudar a descubrir información útil sobre 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 el @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Pasos siguientes

Más ejemplos de código

Contributing

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.

Consulte también guía específica de Storage para obtener información adicional sobre cómo configurar el entorno de prueba para las bibliotecas de almacenamiento.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-10-17