Biblioteca de clientes do Compartilhamento de Arquivos do Armazenamento do Azure para JavaScript – versão 12.24.0

Os Arquivos do Azure oferecem compartilhamentos de arquivos totalmente gerenciados na nuvem que podem ser acessados por meio do protocolo SMB (Bloco de Mensagens do Servidor) padrão do setor. Os compartilhamentos de arquivos do Azure podem ser montados simultaneamente por implantações locais ou de nuvem do Windows, Linux e macOS. Além disso, os compartilhamentos de arquivos do Azure podem ser armazenados em cache nos Windows Servers 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 clientes em JavaScript que facilita o consumo do serviço de Armazenamento de Arquivos do Microsoft Azure.

Use as bibliotecas de cliente neste pacote para:

• Propriedades do Serviço de Arquivo Get/Set
• Criar/listar/excluir compartilhamentos de arquivos
• Criar/listar/excluir diretórios de arquivos
• Criar/Ler/Listar/Atualizar/Excluir Arquivos

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

Links de chave:

• código-fonte
• do pacote (npm)
• documentação de referência da API
• documentação do produto
• exemplos de
• APIs REST do Arquivo de Armazenamento do Azure

Introdução

Ambientes com suporte no momento

• versões lts do Node.js
• Versões mais recentes do Safari, Chrome, Edge e Firefox.

Consulte nossa 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 clientes do Armazenamento de Arquivos do Azure para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela de 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 do 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.

• chave compartilhada
• assinaturas de acesso compartilhado

Compatibilidade

Essa biblioteca é compatível com Node.js e navegadores e validada em versões de Node.js LTS (>=8.16.0) e versões mais recentes do Chrome, Firefox e Edge.

Web Workers

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

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

Essa biblioteca depende das seguintes APIs do DOM que precisam de polyfills externos carregados quando usados em trabalhos Web:

• document
• DOMParser
• Node
• XMLSerializer

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o runtime dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "SOMENTE DISPONÍVEL EM NODE.JS RUNTIME" ou "SOMENTE DISPONÍVEL EM NAVEGADORES".

• Se um arquivo mantiver dados compactados no formato gzip ou deflate e sua codificação de conteúdo for definida adequadamente, o comportamento de download será diferente entre Node.js e navegadores. Em Node.js 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 no Node.js

• Autorização de chave compartilhada com base no nome da conta e na chave da conta
  • StorageSharedKeyCredential
• Geração de SAS (Assinatura de Acesso Compartilhado)
  • generateAccountSASQueryParameters()
  • generateFileSASQueryParameters()
• Carregamento 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 clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

CORS

Você precisa configurar regras de CORS (Compartilhamento de Recursos entre Origens) para sua conta de armazenamento se precisar desenvolver para navegadores. Acesse o portal do Azure e o Gerenciador de Armazenamento do Azure, localize 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. Porém, personalize as configurações cuidadosamente de acordo com seus requisitos 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

Principais conceitos

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, representada por um ShareClient
• Uma hierarquia opcional de diretórios no compartilhamento de arquivos, representada por instâncias de ShareDirectoryClient
• Um arquivo dentro do compartilhamento de arquivos, que pode ter até 1 TiB de tamanho, representado por um ShareFileClient

Exemplos

• Importar o pacote
• Criar o cliente de serviço de compartilhamento
• Listar compartilhamentos na conta
• Criar um novo compartilhamento e um diretório
• Criar um arquivo do azure e carregar nele
• Listar arquivos e diretórios em um diretório
• Baixar um arquivo e convertê-lo em uma cadeia de caracteres (Node.js)
• Baixar um arquivo e convertê-lo em uma cadeia de caracteres (Navegadores)

Importar o pacote

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

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

Como alternativa, importe seletivamente apenas os tipos necessários:

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. Opcionalmente, ele também aceita algumas configurações no parâmetro options.

usando a cadeia de conexão

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

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Passe uma StorageSharedKeyCredential com o nome da conta e a chave da conta. (O nome da conta e a chave de conta podem ser obtidos no portal do 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 criar uma instância de um ShareServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS no 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 compartilhamentos 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();

Como alternativa, 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();

Criar um arquivo do azure e carregar 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 em 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();

Como alternativa, 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 de iteração, consulte samples/v12/typescript/src/listFilesAndDirectories.ts.

Baixar um arquivo e convertê-lo em uma cadeia de caracteres (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 cadeia de caracteres (Navegadores)

Consulte a seção Pacote JavaScript 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 de ShareServiceClient simples está em exemplos/v12/typescript/src/shareSerivceClient.ts.

Solucionando 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 runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximas etapas

Mais exemplos de código

• de Exemplos de Armazenamento de Compartilhamento de Arquivos (JavaScript)
• exemplos de armazenamento de compartilhamento de arquivos (TypeScript)
• casos de teste de armazenamento de compartilhamento de arquivos

Contribuindo

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

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

impressões