Biblioteca cliente de recursos compartidos de Azure Storage para JavaScript

Artículo
11/10/2023

Azure Files ofrece recursos compartidos de archivos totalmente administrados en la nube a los que se puede acceder mediante el protocolo estándar del sector Bloque de mensajes del servidor (SMB). Los recursos compartidos de Azure se pueden montar simultáneamente en implementaciones de Windows, Linux y macOS en la nube o locales. Además, los recursos compartidos de archivos de Azure Files se pueden almacenar en la caché de los servidores de Windows Server con Azure File Sync, lo que permite un acceso rápido allí donde se utilizan 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 las propiedades del servicio de archivos
Crear, enumerar o eliminar recursos compartidos de archivos
Crear, enumerar o 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 para @azure/storage-file-share alinearse mejor con el próximo paquete nuevo para Azure Storage Files DataLake y proporcionar un conjunto coherente de API para trabajar con archivos en Azure.

Vínculos principales:

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

Autenticar el 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 para obtener más información sobre la ShareServiceClient autenticación.

Clave compartida
Firmas de acceso compartido

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 archivo contiene datos comprimidos en gzip formato 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/D

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

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 ShareDirectoryClient instancias
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
Creación del cliente de servicio compartido
Enumeración de recursos compartidos en la cuenta
Creación de un recurso compartido y un directorio
Cree un archivo de Azure y, a continuación, cárguelo en él.
Enumerar archivos y directorios en un directorio
Descargue un archivo y conviértalo 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:

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");

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

usar cadena de conexión

Como alternativa, puede crear una ShareServiceClient 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).

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

Con `StorageSharedKeyCredential`

Pase un StorageSharedKeyCredential elemento 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 ShareServiceClient 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 { 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 for-await-of sintaxis:

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() {
  let 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() {
  let 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();

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, a continuación, 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 sobre archivos y directorios, con la nueva for-await-of sintaxis. La kind propiedad se puede usar para identificar si un valor de 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);

  let 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);

  let 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}`);
    }
    item = await dirIter.next();
  }
}

main();

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

Descargue un archivo y conviértalo 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 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 simples ShareServiceClient se encuentra en samples/v12/typescript/src/shareSerivceClient.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

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.

Introducción

Entornos admitidos actualmente

Requisitos previos

Instalar el paquete

Autenticar el cliente

Compatibilidad

Trabajos web

Diferencias entre Node.js y exploradores

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

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

Paquete de JavaScript

CORS

Conceptos clave

Ejemplos

Importación del paquete

usar cadena de conexión

Con `StorageSharedKeyCredential`

con token de SAS

Enumeración de recursos compartidos en la cuenta

Cree un archivo de Azure y, a continuación, cárguelo en él.

Enumerar archivos y directorios en un directorio

Descargue un archivo y conviértalo en una cadena (Node.js)

Descargar un archivo y convertirlo en una cadena (exploradores)

Solución de problemas

Pasos siguientes

Contribuciones

Comentarios

Recursos adicionales

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

Introducción

Entornos admitidos actualmente

Requisitos previos

Instalar el paquete

Autenticar el cliente

Compatibilidad

Trabajos web

Diferencias entre Node.js y exploradores

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

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

Paquete de JavaScript

CORS

Conceptos clave

Ejemplos

Importación del paquete

Creación del cliente de servicio compartido

usar cadena de conexión

Con StorageSharedKeyCredential

con token de SAS

Enumeración de recursos compartidos en la cuenta

Creación de un recurso compartido y un directorio

Cree un archivo de Azure y, a continuación, cárguelo en él.

Enumerar archivos y directorios en un directorio

Descargue un archivo y conviértalo en una cadena (Node.js)

Descargar un archivo y convertirlo en una cadena (exploradores)

Solución de problemas

Pasos siguientes

Contribuciones

Comentarios

Recursos adicionales

Con `StorageSharedKeyCredential`