適用於 JavaScript 的 Azure 記憶體 Blob 用戶端連結庫 - 12.17.0 版

發行項
01/10/2024

Azure 記憶體 Blob 是 Microsoft 的雲端物件記憶體解決方案。 Blob 儲存體已針對儲存大量非結構化資料進行最佳化。非結構化資料是指不遵守特定資料模型或定義的資料，例如文字或二進位資料。

此專案在 JavaScript 中提供用戶端連結庫，可讓您輕鬆地取用 Microsoft Azure 儲存體 Blob 服務。

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

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

重要連結

開始使用

目前支援的環境

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

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

必要條件

安裝套件

安裝適用於 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 提供各種認證類型，可供您的應用程式用來執行此動作。如需詳細資訊和範例，請參閱自述檔 @azure/identity 以開始使用。

相容性

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

Web 背景工作

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

如需詳細資訊，請參閱我們的檔，以在 Web 背景工作角色中使用適用於 JS 的 Azure SDK

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

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

Node.js 和瀏覽器運行時間之間有差異。開始使用此連結庫時，請留意標示為 「僅適用於 NODE.JS 運行時間」 或 「僅適用於瀏覽器」的 API 或類別。

如果 Blob 保存或deflate格式的壓縮數據gzip，且其內容編碼會據以設定，則下載行為在 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/queue/file/table 服務建立新的 CORS 規則， (s) 。

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

允許的來源： *
允許的動詞：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允許的標頭： *
公開標頭：*
最長 (秒) ：86400

重要概念

Blob 儲存體旨在：

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

Blob 儲存體提供三種類型資源：

透過使用的記憶體帳戶BlobServiceClient
透過使用的記憶體帳戶中的容器ContainerClient
透過使用的容器中的 BlobBlobClient

匯入封裝

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

const AzureStorageBlob = require("@azure/storage-blob");

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

建立 Blob 服務用戶端

BlobServiceClient需要 Blob 服務的 URL 和存取認證。它也選擇性地接受參數中的 options 某些設定。

`@azure/identity`從套件使用`DefaultAzureCredential`

具現化的建議方式 BlobServiceClient

設定：參考 - 從用戶端應用程式授權對 Blob 和佇列的存取權 - /azure/storage/common/storage-auth-aad-app

註冊新的 AAD 應用程式，並授與代表登入使用者存取 Azure 記憶體的許可權
- 在 azure-portal) - /azure/active-directory/develop/quickstart-register-app 的 Azure Active Directory (中註冊新的應用程式
- 在區 API permissions 段中，選取 Add a permission 並選擇 Microsoft APIs。
- 挑選 Azure Storage 並選取旁邊的 user_impersonation 複選框，然後按下 Add permissions。這可讓應用程式代表登入的使用者存取 Azure 記憶體。
在 Azure 入口網站中使用 RBAC 授與 Azure Blob 數據的存取權
- Blob 和佇列的 RBAC 角色 - /azure/storage/common/storage-auth-aad-rbac-portal。
- 在 Azure 入口網站中，移至您的記憶體帳戶，並從) azure 入口網站中記憶體帳戶左側導覽列中的索引卷標 (，將記憶體 Blob 數據參與者 角色指派給已註冊的 AAD 應用程式 Access control (IAM) 。
範例的環境設定
- 從 AAD 應用程式的 [概觀] 頁面，記下 CLIENT ID 和 TENANT ID。在 [憑證 & 秘密] 索引標籤中，建立秘密並記下。
- 請確定您有AZURE_TENANT_ID、AZURE_CLIENT_ID AZURE_CLIENT_SECRET作為環境變數，以順利執行範例 (可以利用 process.env) 。

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@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]

使用連接字串

或者，您可以使用靜態方法具現化 BlobServiceClientfromConnectionString() ，並將完整連接字串作為自變數。 (您可以從 azure 入口網站取得連接字串。) [僅適用於 NODE.JS RUNTIME]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

with `StorageSharedKeyCredential`

或者，您可以藉由傳遞 account-name 和 account-key 作為自變數來具現化 BlobServiceClientStorageSharedKeyCredential 。 (您可以從 azure 入口網站取得帳戶名稱和帳戶密鑰。) [僅適用於 NODE.JS RUNTIME]

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

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

使用SAS令牌

此外，您也可以使用共用存取簽章 (SAS) 具現化 BlobServiceClient 。您可以從 Azure 入口網站取得 SAS 令牌，或使用來產生。generateAccountSASQueryParameters()

const { BlobServiceClient } = require("@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() 來取得容器用戶端實例，然後建立新的容器資源。

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  // 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);
}

main();

列出容器

使用函式 BlobServiceClient.listContainers() 來逐一查看容器，並使用新的 for-await-of 語法：

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

或者，不使用 for-await-of：

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

此外，也支援透過 byPage()列出分頁：

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

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

上傳數據以建立 Blob

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

列出容器內的 Blob

類似於列出容器。

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

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

下載 Blob 並將其轉換成字串 (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  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();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [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);
    });
  }
}

main();

下載 Blob 並將其轉換成字串 (瀏覽器) 。

如需在瀏覽器中使用此連結庫的詳細資訊，請參閱 JavaScript 套件組合一節。

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

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

async function main() {
  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 downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers 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();

簡單案例的完整範例位於 samples/v12/typescript/src/sharedKeyAuth.ts。

疑難排解

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

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

setLogLevel("info");

後續步驟

其他程式代碼範例：

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

另請參閱記憶體特定指南，以取得設定記憶體連結庫測試環境的其他資訊。

曝光數

適用於 JavaScript 的 Azure 記憶體 Blob 用戶端連結庫 - 12.17.0 版

開始使用

目前支援的環境

必要條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

功能、介面、類別或函式僅適用於 Node.js

功能、介面、類別或函式只能在瀏覽器中使用

JavaScript 套件組合

CORS

重要概念

範例

匯入封裝

建立 Blob 服務用戶端

`@azure/identity`從套件使用`DefaultAzureCredential`

使用連接字串

with `StorageSharedKeyCredential`

使用SAS令牌

建立新的容器

列出容器

上傳數據以建立 Blob

列出容器內的 Blob

下載 Blob 並將其轉換成字串 (Node.js)

下載 Blob 並將其轉換成字串 (瀏覽器) 。

疑難排解

後續步驟

參與

意見反應

其他資源

適用於 JavaScript 的 Azure 記憶體 Blob 用戶端連結庫 - 12.17.0 版

開始使用

目前支援的環境

必要條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

功能、介面、類別或函式僅適用於 Node.js

功能、介面、類別或函式只能在瀏覽器中使用

JavaScript 套件組合

CORS

重要概念

範例

匯入封裝

建立 Blob 服務用戶端

@azure/identity從套件使用DefaultAzureCredential

使用 連接字串

with StorageSharedKeyCredential

使用SAS令牌

建立新的容器

列出容器

上傳數據以建立 Blob

列出容器內的 Blob

下載 Blob 並將其轉換成字串 (Node.js)

下載 Blob 並將其轉換成字串 (瀏覽器) 。

疑難排解

後續步驟

參與

意見反應

其他資源

`@azure/identity`從套件使用`DefaultAzureCredential`

使用連接字串

with `StorageSharedKeyCredential`