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

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

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

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

• Получение и задание свойств службы файлов
• Создание и удаление общих папок
• Создание и удаление каталогов файлов
• Create/Read/List/Update/Delete Files

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

Key links:

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

Getting started

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

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

See our support policy for more details.

Prerequisites

• An Azure subscription
• A Storage Account

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

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

npm install @azure/storage-file-share

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

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

• Shared Key
• подписей общего доступа

Compatibility

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

Web Workers

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

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

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

• document
• DOMParser
• Node
• XMLSerializer

Различия между 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 Bundle

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. For details on how to do this, please refer to our bundling documentation.

CORS

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

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

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

Key concepts

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

• The storage account itself, represented by a ShareServiceClient
• A file share within the storage account, represented by a ShareClient
• Необязательная иерархия каталогов в общей папке, представленная экземплярами ShareDirectoryClient
• A file within the file share, which may be up to 1 TiB in size, represented by a 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++;
}

For a complete sample on iterating please see 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);
  });
}

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

Please refer to the JavaScript Bundle section for more information on using this library in the browser.

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

A complete example of simple ShareServiceClient scenarios is at samples/v12/typescript/src/shareSerivceClient.ts.

Troubleshooting

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

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

setLogLevel("info");

Next steps

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

• примеры хранилища общих папок (JavaScript)
• примеры хранилища общих папок (TypeScript)
• тестовые случаи хранения общих папок

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

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