Compartir a través de

Biblioteca cliente de Recurso compartido de archivos de Azure Storage para JavaScript: versión 12.25.0

  • Artículo

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:

Empezar

Entornos admitidos actualmente

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

Prerrequisitos

  • Un de suscripción de Azure de
  • Una cuenta de almacenamiento de

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.

Compatibilidad

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.

Trabajos 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 cuenta de almacenamiento , representada por un ShareServiceClient
  • Un de recursos compartidos de archivos dentro de la cuenta de almacenamiento, representada 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

Ejemplos

Importación del paquete

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

const AzureStorageFileShare = require("@azure/storage-file-share");

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

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

Creación del cliente del servicio de recursos compartidos

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).

const { ShareServiceClient } = require("@azure/storage-file-share");

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

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).

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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().

const { ShareServiceClient } = require("@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:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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
);

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

main();

Como alternativa, sin for-await-of:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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
);

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

main();

Creación de un recurso compartido y un directorio

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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
);

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

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

main();

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

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const content = "Hello World!";
  const fileName = "newfile" + new Date().getTime();
  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`);
}

main();

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.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

main();

Como alternativa, sin usar for-await-of:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

main();

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)

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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>";

// [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);
  });
}

async function main() {
  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();
  console.log(
    `Downloaded file content: ${(
      await streamToBuffer(downloadFileResponse.readableStreamBody)
    ).toString()}`
  );
}

main();

Descargar un archivo y convertirlo en una cadena (Exploradores)

Consulte la sección paquete de JavaScript de para obtener más información sobre el uso de esta biblioteca en el explorador.

const { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const shareName = "<share name>";
const fileName = "<file name>";

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

async function main() {
  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);
  console.log(
    `Downloaded file content: ${await blobToString(await downloadFileResponse.blobBody)}`
  );
}

// [Browser 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 de ShareServiceClient simples se encuentra en samples/v12/typescript/src/shareSerivceClient.ts.

Solución de problemas

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:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Pasos siguientes

Más ejemplos de código

Contribuyendo

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.

impresiones