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

Статья
11/20/2024

Файлы 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
документации по продукту
Примеры
REST API файлов службы хранилища Azure

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

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

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

Дополнительные сведения см. в политике поддержки .

Необходимые условия

подписки Azure
учетной записи хранения

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

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

npm install @azure/storage-file-share

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

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

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

Совместимость

Эта библиотека совместима с 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:

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

Примеры

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

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

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

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

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

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

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

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

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

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

с `StorageSharedKeyCredential`

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

с маркером SAS

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

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

Используйте ShareServiceClient.listShares() для общих папок итератора в этой учетной записи с новым синтаксисом 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() {
  const shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

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

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

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

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

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

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

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

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

main();

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

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

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

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

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

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

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

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

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

setLogLevel("info");

Дальнейшие действия

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

Способствует

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

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

Поделиться через

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

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

Необходимые условия

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

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

Совместимость

Веб-рабочие роли

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

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

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

Пакет JavaScript

CORS

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

Примеры

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

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

с `StorageSharedKeyCredential`

с маркером SAS

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

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

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

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

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

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

Дальнейшие действия

Способствует

Дополнительные ресурсы

Поделиться через

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

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

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

Необходимые условия

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

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

Совместимость

Веб-рабочие роли

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

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

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

Пакет JavaScript

CORS

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

Примеры

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

Создание клиента службы общего доступа

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

с StorageSharedKeyCredential

с маркером SAS

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

Создание общего ресурса и каталога

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

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

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

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

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

Дальнейшие действия

Способствует

Дополнительные ресурсы

с `StorageSharedKeyCredential`