適用於 JavaScript 的 Azure 儲存體 Blob 用戶端程式庫 - 12.29.1 版

Azure 記憶體 Blob 是雲端Microsoft的物件記憶體解決方案。 Blob 記憶體已針對儲存大量非結構化數據進行優化。非結構化數據是不符合特定數據模型或定義的數據，例如文字或二進位數據。

此專案提供 JavaScript 中的用戶端連結庫，可讓您輕鬆地取用 azure 記憶體 Blob 服務Microsoft。

使用此套件中的用戶端連結庫來：

取得/設定 Blob 服務屬性
建立/列出/刪除容器
建立/讀取/清單/更新/刪除區塊 Blob
建立/讀取/清單/更新/刪除分頁 Blob
建立/讀取/清單/更新/刪除附加 Blob

關鍵鏈接

入門指南

目前支持的環境

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

如需詳細資訊，請參閱我們的支援原則。

Prerequisites

安裝套件

安裝適用於 JavaScript 的 Azure 記憶體 Blob 用戶端連結庫的慣用方式是使用 npm 套件管理員。在終端機視窗中輸入下列內容：

npm install @azure/storage-blob

驗證用戶端

Azure 記憶體支援數種方式進行驗證。為了與 Azure Blob 儲存服務交互，您需要建立儲存客戶端的實體 - BlobServiceClient、 ContainerClient或 BlobClient 例如。請參閱創建BlobServiceClient的範例以瞭解有關身份驗證的更多資訊。

Azure Active Directory
共用金鑰
共用存取簽章

Azure Active Directory

Azure Blob 記憶體服務支援使用 Azure Active Directory 來驗證其 API 的要求。 @azure/identity 套件提供應用程式可用來執行這項作業的各種認證類型。請參閱 README 瞭解更多 @azure/identity 詳細資訊和範例，以説明您入門。

Compatibility

此庫與 Node.js 和瀏覽器相容，並針對 LTS Node.js 版本（>=8.16.0）和最新版本的 Chrome、Firefox 和 Edge 進行了驗證。

Web Workers

此連結庫需要某些 DOM 對象在瀏覽器中使用時全域可用，Web 背景工作角色預設不會提供這些物件。您必須進行聚合填入，才能讓此連結庫在 Web 背景工作。

此連結庫取決於下列 DOM API，這些 API 需要在 Web 背景工作角色中使用時載入外部 polyfill：

Node.js 和瀏覽器之間的差異

Node.js 和 browsers 運行時之間存在差異。開始使用此庫時，請注意標有 “僅在 NODE.JS 運行時可用” 或 “僅在瀏覽器中可用”的 API 或類。

如果 blob 以 gzip OR deflate 格式保存壓縮數據，並且其內容編碼已相應地設置，則 Node.js 和瀏覽器之間的下載行為會有所不同。在 Node.js 儲存用戶端將以壓縮格式下載 blob，而在瀏覽器中，數據將以解壓縮格式下載。

功能、介面、類或函數僅在 Node.js 中可用

根據帳戶名稱和帳戶金鑰的共用金鑰授權
- StorageSharedKeyCredential
共用存取簽章（SAS）產生
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
平行上傳和下載。請注意，這在 BlockBlobClient.uploadData() Node.js 和瀏覽器中都可用。
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

功能、介面、類別或函式僅適用於瀏覽器

平行上傳和下載
- BlockBlobClient.uploadBrowserData()

JavaScript 套件組合

若要在瀏覽器中使用此用戶端連結庫，您必須先使用配套程式。有關如何執行此操作的詳細信息，請參閱我們的捆綁文件。

CORS

如果需要針對瀏覽器進行開發，則需要為存儲帳戶設置跨域資源分享（CORS）規則。移至 Azure 入口網站和 Azure 記憶體總管，尋找您的記憶體帳戶，為 Blob/佇列/檔案/資料表服務建立新的 CORS 規則。

例如，您可以建立下列 CORS 設定以進行偵錯。但請根據您的生產環境中的需求，仔細自定義設定。

允許的來源： *
允許的動詞：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允許的標頭： *
公開的標頭： *
年齡上限（秒）：86400

重要概念

Blob 記憶體是專為：

將影像或檔直接提供至瀏覽器。
儲存檔案以進行分散式存取。
串流視訊和音訊。
寫入記錄檔。
儲存備份和還原、災害復原和封存的數據。
儲存數據以供內部部署或 Azure 裝載的服務進行分析。

Blob 記憶體提供三種類型的資源：

透過BlobServiceClient
儲存體帳戶中的容器，透過 ContainerClient
容器中的 blob 透過 BlobClient

匯入套件

若要使用用戶端，請將套件匯入您的檔案：

import * as AzureStorageBlob from "@azure/storage-blob";

或者，選擇性地只匯入您需要的類型：

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

建立 Blob 服務用戶端

這需要 BlobServiceClient blob 服務的 URL 和訪問憑據。它還可以選擇接受參數中的 options 一些設置。

與 `DefaultAzureCredential` from `@azure/identity` 包

實例化 BlobServiceClient

設定：參考 - 從用戶端應用程式使用 Azure Active Directory 授權訪問 blob 和佇列 - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

註冊新的 AAD 應用程式，並授與代表登入使用者存取 Azure 記憶體的許可權
- 在 Azure Active Directory 中註冊新應用程式（在 azure-portal 中） - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- 在該 API permissions 部分中，選擇 Add a permission 並選擇 Microsoft APIs。
- 選擇 Azure Storage 並選取旁邊的 user_impersonation 複選框，然後按下 Add permissions。這可讓應用程式代表登入的使用者存取 Azure 記憶體。
在 Azure 入口網站中使用 RBAC 授與 Azure Blob 數據的存取權
- blob 和佇列的 RBAC 角色 - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- 在 Azure 門戶中，轉到儲存帳戶，並從選項卡（在 Azure 門戶中存儲帳戶的左側導航欄中）將“Access control (IAM)”角色分配給已註冊的 AAD 應用程式。
範例的環境設定
- 在 AAD 應用程式的概述頁面中，記下 CLIENT ID 和 TENANT ID。在「證書和秘密」選項卡中，創建一個秘密並記下。
- 請確定您有AZURE_TENANT_ID、AZURE_CLIENT_ID AZURE_CLIENT_SECRET作為環境變數，才能成功執行範例（Can 利用 process.env）。

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential,
);

有關使用此方法的完整範例，請參閱 Azure AD 身份驗證範例。

[注意 - 以上步驟僅適用於 Node.js]

使用連接字串

或者，您可以使用 static 方法實例化 a BlobServiceClientfromConnectionString() ，並將完整的連接字串作為參數。（您可以從 Azure 入口網站取得連接字串。[僅適用於NODE.JS運行時間]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

跟 `StorageSharedKeyCredential`

或者，您可以通過將 account-name 和 account-key 作為參數傳遞來實例化 a BlobServiceClient 和 a StorageSharedKeyCredential 。（帳戶名稱和帳戶密鑰可以從 Azure 入口網站取得。[僅適用於NODE.JS運行時間]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

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 sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential,
);

使用SAS令牌

此外，還可以使用共用訪問簽名（SAS）實例化。BlobServiceClient 您可以從 Azure 門戶獲取 SAS 令牌，也可以使用生成一個 generateAccountSASQueryParameters()令牌。

import { BlobServiceClient } from "@azure/storage-blob";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net?${sas}`);

建立新的容器

用於 BlobServiceClient.getContainerClient() 獲取容器客戶端實例，然後創建新的容器資源。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);

列出容器

使用 BlobServiceClient.listContainers() function 迭代容器，使用新 for-await-of 語法：

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

或者不使用 for-await-of：

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

此外，也支持通過以下方式 byPage()列出分頁：

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

如需反覆專案容器的完整範例，請參閱 samples/v12/typescript/src/listContainers.ts。

上傳數據以建立 Blob

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

列出容器內的 Blob

類似於列出容器。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

如需反覆運算 Blob 的完整範例，請參閱 samples/v12/typescript/src/listBlobsFlat.ts。

下載 blob 並將轉換為字串（Node.js）

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

下載 Blob 並將它轉換成字串（瀏覽器）。

請參閱 JavaScript 套件組合區段，以取得有關在瀏覽器中使用此程式庫的詳細資訊。

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

簡單場景的完整示例位於 samples/v12/typescript/src/sharedKeyAuth.ts。

Troubleshooting

啟用記錄可能有助於找出有關失敗的實用資訊。若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在 setLogLevel 中呼叫 @azure/logger，以在執行階段啟用記錄：

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

setLogLevel("info");

後續步驟

其他程式代碼範例：

Contributing

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

另請參閱存儲特定指南以瞭解有關為存儲庫設置測試環境的更多資訊。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-17