适用于 JavaScript 的 Azure 存储文件共享客户端库

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

项目
11/20/2024

Azure 文件存储提供云中完全托管的文件共享，可通过行业标准服务器消息块（SMB）协议进行访问。 Azure 文件共享可由云或 Windows、Linux 和 macOS 的本地部署同时装载。此外，可以使用 Azure 文件同步在 Windows Server 上缓存 Azure 文件共享，以便在使用数据的位置附近快速访问。

此项目在 JavaScript 中提供了一个客户端库，方便使用 azure 文件存储服务Microsoft。

使用此包中的客户端库可以：

获取/设置文件服务属性
创建/列出/删除文件共享
创建/列出/删除文件目录
创建/读取/列表/更新/删除文件

注意：此包以前以名称 @azure/storage-file发布。它已重命名为 @azure/storage-file-share，以便更好地与即将推出的 Azure 存储文件 DataLake 的新包保持一致，并提供一组一致的 API 来处理 Azure 上的文件。

关键链接：

开始

当前支持的环境

LTS 版本的 Node.js
Safari、Chrome、Edge 和 Firefox 的最新版本。

有关详细信息，请参阅我们的支持策略。

先决条件

安装包

安装适用于 JavaScript 的 Azure 文件存储客户端库的首选方法是使用 npm 包管理器。在终端窗口中键入以下内容：

npm install @azure/storage-file-share

对客户端进行身份验证

Azure 存储支持多种方式进行身份验证。若要与 Azure 存储文件共享服务交互，需要创建存储客户端的实例-ShareServiceClient、ShareClient或 ShareDirectoryClient 例如。请参阅示例，了解如何创建 ShareServiceClient，了解有关身份验证的详细信息。

共享密钥
共享访问签名

兼容性

此库与 Node.js 和浏览器兼容，并针对 LTS Node.js 版本（>=8.16.0）和最新版本的 Chrome、Firefox 和 Edge 进行验证。

Web 辅助角色

此库要求某些 DOM 对象在浏览器中使用时全局可用，Web 辅助角色默认不提供这些对象。需要填充这些内容以使此库在 Web 辅助角色中正常工作。

有关详细信息，请参阅我们的文档，了解如何在 Web 辅助角色中使用 Azure SDK for JS

此库依赖于以下 DOM API，这些 API 需要在 Web 辅助角色中使用时加载外部填充：

Node.js 和浏览器之间的差异

Node.js 和浏览器运行时之间存在差异。开始使用此库时，请注意标有 “仅在NODE.JS运行时中可用”的 API 或类 或 “仅在浏览器中可用”。

如果文件保存 gzip 或 deflate 格式的压缩数据，并且其内容编码设置相应，则下载行为在 Node.js 和浏览器之间有所不同。在 Node.js 存储客户端将以压缩格式下载文件，而在浏览器中，数据将以非压缩格式下载。

以下功能、接口、类或函数仅在 Node.js 中可用

基于帐户名称和帐户密钥的共享密钥授权
- StorageSharedKeyCredential
共享访问签名（SAS）生成
- generateAccountSASQueryParameters()
- generateFileSASQueryParameters()
并行上传和下载。请注意，Node.js 和浏览器都提供了 ShareFileClient.uploadData()。
- ShareFileClient.uploadFile()
- ShareFileClient.uploadStream()
- ShareFileClient.downloadToBuffer()
- ShareFileClient.downloadToFile()

以下功能、接口、类或函数仅在浏览器中可用

N/A

JavaScript 捆绑包

若要在浏览器中使用此客户端库，首先需要使用捆绑程序。有关如何执行此操作的详细信息，请参阅我们的捆绑文档。

CORS

如果需要为浏览器进行开发，则需要为存储帐户设置跨域资源共享（CORS）规则。转到 Azure 门户和 Azure 存储资源管理器，找到存储帐户，为 Blob/队列/文件/表服务创建新的 CORS 规则。

例如，可以创建以下 CORS 设置进行调试。但请根据生产环境中的要求仔细自定义设置。

允许的源： *
允许的谓词：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允许的标头： *
公开的标头： *
最大年龄（秒）：86400

关键概念

以下组件及其相应的客户端库构成了 Azure 存储文件共享服务：

存储帐户本身，由 ShareServiceClient 表示
存储帐户中的 文件共享，由 ShareClient 表示
文件共享中目录的可选层次结构，由实例表示
文件共享中的文件，大小可能高达 1 TiB，由 ShareFileClient 表示

导入包

若要使用客户端，请将包导入文件：

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

with `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 令牌

此外，还可以使用共享访问签名（SAS）实例化 ShareServiceClient。可以从 Azure 门户获取 SAS 令牌，也可以使用 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 方案的完整示例是 samples/v12/typescript/src/shareSerivceClient.ts。

故障排除

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，可以通过在 setLogLevel中调用 @azure/logger 在运行时启用日志记录：

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

setLogLevel("info");

后续步骤

更多代码示例

贡献

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

另请参阅存储特定指南，了解有关为存储库设置测试环境的其他信息。

通过

适用于 JavaScript 的 Azure 存储文件共享客户端库 - 版本 12.26.0

开始