Клиентская библиотека файлового ресурса службы хранилища Azure для JavaScript

Файлы Azure предлагают полностью управляемые общие папки в облаке, доступные через стандартный протокол SMB. Общие папки Azure можно подключить одновременно с помощью облачных или локальных развертываний Windows, Linux и macOS. Кроме того, общие папки Azure можно кэшировать на серверах Windows с помощью службы "Синхронизация файлов Azure" для быстрого доступа к месту использования данных.

Этот проект предоставляет клиентскую библиотеку в JavaScript, которая упрощает использование службы хранилища файлов Microsoft Azure.

Используйте клиентские библиотеки в этом пакете, чтобы:

Получение и задание свойств службы файлов
Создание и удаление общих папок
Создание и удаление каталогов файлов
Создание/Чтение/Список/Обновление/Удаление файлов

Примечание. Этот пакет был ранее опубликован под именем @azure/storage-file. Оно было переименовано в @azure/storage-file-share, чтобы лучше соответствовать предстоящему новому пакету для файлов хранилища Azure DataLake и предоставить согласованный набор API для работы с файлами в Azure.

Ключевые ссылки:

исходный код.
Пакет (npm)
Справочная документация по API
документации по продукту
Samples
REST API файлов службы хранилища Azure

Начало работы

Поддерживаемые в настоящее время среды

LTS версии Node.js
Последние версии Safari, Chrome, Edge и Firefox.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Prerequisites

Установка пакета

Предпочтительный способ установки клиентской библиотеки хранилища файлов Azure для JavaScript — использовать диспетчер пакетов npm. Введите следующее в окно терминала:

npm install @azure/storage-file-share

Проверка подлинности клиента

Служба хранилища Azure поддерживает несколько способов проверки подлинности. Чтобы взаимодействовать со службой файлового ресурса службы хранилища Azure, необходимо создать экземпляр клиента хранилища — ShareServiceClient, ShareClientили ShareDirectoryClient. Дополнительные сведения о проверке подлинности см. в примерах для создания ShareServiceClient.

Общий ключ
подписей общего доступа

Compatibility

Эта библиотека совместима с Node.js и браузерами и проверена на основе версий LTS Node.js (>=8.16.0) и последних версий Chrome, Firefox и Edge.

Веб-воркеры

Эта библиотека требует, чтобы некоторые объекты DOM были глобально доступны при использовании в браузере, которые веб-работники по умолчанию не делают доступными. Эти библиотеки необходимо заполнить, чтобы эта библиотека работала в веб-рабочих нагрузках.

Дополнительные сведения см. в нашей документации по использованию пакета SDK Azure для JS в веб-рабочих

Эта библиотека зависит от следующих API-интерфейсов DOM, которые нуждаются во внешних полизаполнениях, загруженных при использовании в веб-рабочих нагрузках:

Различия между Node.js и браузерами

Существуют различия между средой выполнения Node.js и браузерами. При начале работы с этой библиотекой обратите внимание на API-интерфейсы или классы, помеченные "ТОЛЬКО ДОСТУПНО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS" или "ТОЛЬКО ДОСТУПНЫ В БРАУЗЕРАХ".

Если файл содержит сжатые данные в gzip или deflate формате, а его кодировка содержимого задана соответствующим образом, то поведение загрузки отличается от Node.js и браузеров. В Node.js клиенты хранилища скачивают файл в сжатом формате, а в браузерах данные будут скачаны в не сжатый формат.

Следующие функции, интерфейсы, классы или функции доступны только в Node.js

Авторизация общего ключа на основе имени учетной записи и ключа учетной записи
- StorageSharedKeyCredential
Создание подписанного URL-адреса (SAS)
- generateAccountSASQueryParameters()
- generateFileSASQueryParameters()
Параллельная отправка и скачивание. Обратите внимание, что ShareFileClient.uploadData() доступна как в Node.js, так и в браузерах.
- ShareFileClient.uploadFile()
- ShareFileClient.uploadStream()
- ShareFileClient.downloadToBuffer()
- ShareFileClient.downloadToFile()

Следующие функции, интерфейсы, классы или функции доступны только в браузерах

N/A

Пакет JavaScript

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. Дополнительные сведения о том, как это сделать, см. в нашей документации по .

CORS

Необходимо настроить правила совместного использования ресурсов (CORS) для учетной записи хранения, если необходимо разработать для браузеров. Перейдите на портал Azure и обозреватель службы хранилища Azure, найдите свою учетную запись хранения, создайте новые правила CORS для больших двоичных объектов, очередей, файлов и таблиц.

Например, можно создать следующие параметры CORS для отладки. Но настройте параметры тщательно в соответствии с вашими требованиями в рабочей среде.

Допустимые источники: *
Разрешенные команды: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Разрешенные заголовки: *
Открытые заголовки: *
Максимальный возраст (в секундах): 86400

Основные понятия

Следующие компоненты и соответствующие клиентские библиотеки составляют службу файлового ресурса службы хранилища Azure:

Сама учетная запись хранения , представленная атрибутом ShareServiceClient
Общая папка в учетной записи хранения, представленнаяShareClient
Необязательная иерархия каталогов в общей папке, представленная экземплярами ShareDirectoryClient
Файл в общей папке, размер которого может достигать 1 ТиБ, представленный символомShareFileClient

Examples

Импорт пакета
создание клиента службы общего доступа
Список общих папок в учетной записи
Создание общего ресурса и каталога
Создайте файл Azure, а затем отправьте в него
Список файлов и каталогов в каталоге
Скачайте файл и преобразуйте его в строку (Node.js)
Скачайте файл и преобразуйте его в строку (браузеры)

Импорт пакета

Чтобы использовать клиенты, импортируйте пакет в файл:

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

Кроме того, выборочно импортируйте только необходимые типы:

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

Для ShareServiceClient требуется URL-адрес службы общих папок и учетные данные доступа. Он также при необходимости принимает некоторые параметры в параметре options.

использование строки подключения

Кроме того, можно создать экземпляр ShareServiceClient с помощью статического метода fromConnectionString() с полной строкой подключения в качестве аргумента. (Строка подключения может быть получена на портале Azure.)

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

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

с `StorageSharedKeyCredential`

Передайте StorageSharedKeyCredential с именем учетной записи и ключом учетной записи. (Имя учетной записи и ключ учетной записи можно получить на портале 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,
);

с маркером SAS

Кроме того, можно создать экземпляр ShareServiceClient с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure или создать его с помощью 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}`,
);

Вывод списка общих папок в учетной записи

Используйте ShareServiceClient.listShares() для общих папок итератора в этой учетной записи с новым синтаксисом 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}`);
}

Кроме того, без 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());
}

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

Создайте файл Azure и отправьте его в него.

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

Вывод списка файлов и каталогов в каталоге

Итератор по файлам и каталогам используйте DirectoryClient.listFilesAndDirectories() с новым синтаксисом for-await-of. Свойство kind можно использовать для определения того, является ли итерм каталогом или файлом.

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++;
}

Кроме того, без использования 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++;
}

Полный пример итерации можно найти в samples/v12/typescript/src/listFilesAndDirectories.ts.

Скачайте файл и преобразуйте его в строку (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);
  });
}

Скачайте файл и преобразуйте его в строку (браузеры)

Пожалуйста, обратитесь к разделу JavaScript Bundle для получения дополнительной информации об использовании этой библиотеки в браузере.

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

Полный пример простых ShareServiceClient сценариев можно найти по адресу samples/v12/typescript/src/shareSerivceClient.ts.

Troubleshooting

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

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

setLogLevel("info");

Дальнейшие шаги

Дополнительные примеры кода

Contributing

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по созданию и тестированию кода.

Дополнительные сведения о настройке тестовой среды для библиотек хранилища см. в руководстве по хранилища.

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-10-17