Compartilhar via

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

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:

Como começar

Ambientes com suporte no momento

Consulte nossa política de suporte para obter mais detalhes.

Prerequisites

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.

Compatibility

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.

Trabalhadores da Web

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:

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

Conceitos principais

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

  • A própria conta de armazenamento , representada por um ShareServiceClient
  • Um compartilhamento de arquivos na conta de armazenamento, representado 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

Examples

Importar o pacote

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

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

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

import { ShareServiceClient, StorageSharedKeyCredential } from "@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.)

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

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

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

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

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

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}`,
);

Listar compartilhamentos na conta

Use ShareServiceClient.listShares() para iterar compartilhamentos nesta conta, com a nova sintaxe 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, sem 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());
}

Criar um novo compartilhamento e um diretório

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

Criar um arquivo do azure e carregar nele

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

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.

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

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

Baixar um arquivo e convertê-lo em uma cadeia de caracteres (Navegadores)

Consulte a seção JavaScript Bundle para obter mais informações sobre como usar essa biblioteca no 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()}`);
}

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

Troubleshooting

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:

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

setLogLevel("info");

Próximas etapas

Mais exemplos de código

Contributing

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.

  • Last updated on