Partilhar via

Biblioteca de cliente do Compartilhamento de Arquivos de Armazenamento do Azure para JavaScript - versão 12.24.0

  • Artigo

O Azure Files oferece compartilhamentos de arquivos totalmente gerenciados na nuvem que podem ser acessados por meio do protocolo SMB (Server Message Block) padrão do setor. Os compartilhamentos de arquivos do Azure podem ser montados simultaneamente por implantações na nuvem ou locais do Windows, Linux e macOS. Além disso, os compartilhamentos de arquivos do Azure podem ser armazenados em cache nos Servidores Windows com a Sincronização de Arquivos do Azure para acesso rápido perto de onde os dados estão sendo usados.

Este projeto fornece uma biblioteca de cliente em JavaScript que facilita o consumo do serviço de Armazenamento de Arquivos do Microsoft Azure.

Use as bibliotecas de cliente neste pacote para:

  • Obter/Definir Propriedades do Serviço de Arquivo
  • Criar/Listar/Excluir compartilhamentos de arquivos
  • Criar/Listar/Excluir Diretórios de Arquivos
  • Criar/Ler/Listar/Atualizar/Excluir Arquivos

Nota: Este pacote foi publicado anteriormente sob o nome @azure/storage-file. Ele foi renomeado para @azure/storage-file-share para se alinhar melhor com o novo pacote para o DataLake de Arquivos de Armazenamento do Azure e fornecer um conjunto consistente de APIs para trabalhar com arquivos no Azure.

Ligações principais:

Primeiros passos

Ambientes atualmente suportados

Consulte o nosso de política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure
  • Uma conta de armazenamento

Instalar o pacote

A maneira preferida de instalar a biblioteca de cliente do Armazenamento de Arquivos do Azure para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela do terminal:

npm install @azure/storage-file-share

Autenticar o cliente

O Armazenamento do Azure dá suporte a várias maneiras de autenticação. Para interagir com o serviço de Compartilhamento de Arquivos de Armazenamento do Azure, você precisará criar uma instância de um cliente de Armazenamento - ShareServiceClient, ShareClientou ShareDirectoryClient por exemplo. Consulte exemplos para criar o ShareServiceClient para saber mais sobre autenticação.

Compatibilidade

Esta biblioteca é compatível com Node.js e navegadores, e validada em relação às versões LTS Node.js (>= 8.16.0) e versões mais recentes do Chrome, Firefox e Edge.

Trabalhadores da Web

Essa biblioteca requer que determinados objetos DOM estejam disponíveis globalmente quando usados no navegador, que os Web workers não disponibilizam por padrão. Você precisará polipreenchê-los para fazer essa biblioteca funcionar em web workers.

Para obter mais informações, consulte nossa documentação de para usar o SDK do Azure para JS em Web Workers

Essa biblioteca depende das seguintes APIs DOM que precisam de polipreenchimentos externos carregados quando usados em web workers:

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o tempo de execução dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "APENAS DISPONÍVEL EM TEMPO DE EXECUÇÃO NODE.JS" ou "DISPONÍVEL APENAS EM NAVEGADORES".

  • Se um arquivo contiver dados compactados em formato gzip ou deflate e sua codificação de conteúdo for definida de acordo, o comportamento de download será diferente entre Node.js e navegadores. Em Node.js os clientes de armazenamento baixarão o arquivo em seu formato compactado, enquanto nos navegadores os dados serão baixados em formato descompactado.
Os seguintes recursos, interfaces, classes ou funções só estão disponíveis em Node.js
  • Autorização de chave compartilhada com base no nome da conta e na chave da conta
    • StorageSharedKeyCredential
  • Geração de Assinatura de Acesso Compartilhado (SAS)
    • generateAccountSASQueryParameters()
    • generateFileSASQueryParameters()
  • Upload e download paralelos. Observe que ShareFileClient.uploadData() está disponível em Node.js e navegadores.
    • ShareFileClient.uploadFile()
    • ShareFileClient.uploadStream()
    • ShareFileClient.downloadToBuffer()
    • ShareFileClient.downloadToFile()
Os seguintes recursos, interfaces, classes ou funções só estão disponíveis em navegadores

N/A

Pacote JavaScript

Para usar essa biblioteca de cliente no navegador, primeiro você precisa usar um bundler. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agregação de .

CORS

Você precisa configurar regras de de compartilhamento de recursos entre origens (Cross-Origin Resourcesharing) para sua conta de armazenamento se precisar desenvolver para navegadores. Vá para o portal do Azure e o Gerenciador de Armazenamento do Azure, encontre sua conta de armazenamento, crie novas regras CORS para serviços de blob/fila/arquivo/tabela.

Por exemplo, você pode criar as seguintes configurações de CORS para depuração. Mas por favor, personalize as configurações cuidadosamente de acordo com suas necessidades no ambiente de produção.

  • Origens permitidas: *
  • Verbos permitidos: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Cabeçalhos permitidos: *
  • Cabeçalhos expostos: *
  • Idade máxima (segundos): 86400

Conceitos-chave

Os seguintes componentes e suas bibliotecas de cliente correspondentes compõem o serviço de Compartilhamento de Arquivos de Armazenamento do Azure:

  • A conta de armazenamento em si, representada por um ShareServiceClient
  • Um compartilhamento de arquivos dentro da conta de armazenamento, representado por um ShareClient
  • Uma hierarquia opcional de diretórios dentro do compartilhamento de arquivos, representada por instâncias ShareDirectoryClient
  • Um arquivo dentro do compartilhamento de arquivos, que pode ter até 1 TiB de tamanho, representado por um ShareFileClient

Exemplos

Importar o pacote

Para usar os clientes, importe o pacote para o arquivo:

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

Alternativamente, importe seletivamente apenas os tipos que você precisa:

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

Criar o cliente de serviço de compartilhamento

O ShareServiceClient requer uma URL para o serviço de compartilhamento de arquivos e uma credencial de acesso. Ele também aceita opcionalmente algumas configurações no parâmetro options.

Usando a cadeia de conexão

Como alternativa, você pode instanciar um ShareServiceClient usando o método estático fromConnectionString() com a cadeia de conexão completa como argumento. (A cadeia de conexão pode ser obtida no portal azure.)

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Passe um StorageSharedKeyCredential com o nome e a chave da sua conta. (O nome da conta e a chave da conta podem ser obtidos no portal azure.)

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

com Token SAS

Além disso, você pode instanciar um ShareServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS do Portal do Azure ou gerar um usando 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}`
);

Listar ações na conta

Use ShareServiceClient.listShares() para iterar compartilhamentos nesta conta, com a nova sintaxe 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;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

Alternativamente, sem 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();

Criar um novo compartilhamento e um diretório

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

Crie um arquivo azure e carregue nele

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

Listar arquivos e diretórios em um diretório

Use DirectoryClient.listFilesAndDirectories() para iterar sobre arquivos e diretórios, com a nova sintaxe for-await-of. A propriedade kind pode ser usada para identificar se um iterm é um diretório ou um arquivo.

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

Alternativamente, sem 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 obter um exemplo completo sobre iteração, consulte samples/v12/typescript/src/listFilesAndDirectories.ts.

Baixe um arquivo e converta-o em uma string (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();

Baixar um arquivo e convertê-lo em uma string (Navegadores)

Consulte a seção JavaScript Bundle para obter mais informações sobre como usar essa biblioteca no navegador.

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

Um exemplo completo de cenários ShareServiceClient simples está em samples/v12/typescript/src/shareSerivceClient.ts.

Solução de problemas

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Mais exemplos de código

Contribuição

Se você quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Consulte também guia específico de armazenamento para obter informações adicionais sobre como configurar o ambiente de teste para bibliotecas de armazenamento.

Impressões