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

發行項
07/24/2024

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

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

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

取得/設定 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。請參閱建立的範例，以深入了解驗證。

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

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

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

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

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

如果 Blob 會以 gzip 或 deflate 格式保存壓縮的數據，且其內容編碼會據以設定，則下載行為在 Node.js 和瀏覽器之間會有所不同。在 Node.js 記憶體用戶端會以壓縮格式下載 Blob，而在瀏覽器中，數據會以解壓縮格式下載。

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

根據帳戶名稱和帳戶金鑰的共用金鑰授權
- StorageSharedKeyCredential
共用存取簽章（SAS）產生
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
平行上傳和下載。請注意，Node.js 和瀏覽器都提供 BlockBlobClient.uploadData()。
- 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 使用的記憶體帳戶中的容器
透過 BlobClient 使用的容器中 blob

匯入套件

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

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

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

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

建立 Blob 服務用戶端

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

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

具現化 BlobServiceClient 的建議方式

安裝程序：參考 - 授權從用戶端應用程式使用 Azure Active Directory 存取 Blob 和佇列 - /azure/storage/common/storage-auth-aad-app

註冊新的 AAD 應用程式，並授與代表登入使用者存取 Azure 記憶體的許可權
- 在 Azure Active Directory 中註冊新的應用程式（在 azure-portal 中） - /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 角色 - /azure/storage/common/storage-auth-aad-rbac-portal。
- 在 Azure 入口網站中，移至您的記憶體帳戶，並將 儲存體 Blob 數據參與者 角色指派給已註冊的 AAD 應用程式，從 [Access control (IAM)] 索引標籤（在 azure-portal 中記憶體帳戶的左側導覽列中）。
範例的環境設定
- 從 AAD 應用程式的概觀頁面，記下 CLIENT ID 和 TENANT ID。在 [憑證 & 秘密] 索引標籤中，建立秘密並記下。
- 請確定您有AZURE_TENANT_ID、AZURE_CLIENT_ID AZURE_CLIENT_SECRET作為環境變數，才能成功執行範例（Can 利用 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]

使用連接字串

或者，您可以使用具有完整連接字串做為自變數的 fromConnectionString() 靜態方法，具現化 BlobServiceClient。（您可以從 Azure 入口網站取得連接字串。[僅適用於NODE.JS運行時間]

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

搭配 `StorageSharedKeyCredential`

或者，您可以藉由傳遞 account-name 和 account-key 作為自變數，以 StorageSharedKeyCredential 具現化 BlobServiceClient。（帳戶名稱和帳戶密鑰可以從 Azure 入口網站取得。[僅適用於NODE.JS運行時間]

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

此外，您可以使用共用存取簽章來具現化 BlobServiceClient（SAS）。您可以從 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.24.0 版

開始

目前支持的環境

先決條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

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

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

JavaScript 套件組合

CORS

重要概念

例子

匯入套件

建立 Blob 服務用戶端

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

使用連接字串

搭配 `StorageSharedKeyCredential`

使用SAS令牌

建立新的容器

列出容器

上傳數據以建立 Blob

列出容器內的 Blob

下載 Blob 並將它轉換成字串（Node.js）

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

故障排除

後續步驟

貢獻

其他資源

共用方式為

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

開始

目前支持的環境

先決條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

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

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

JavaScript 套件組合

CORS

重要概念

例子

匯入套件

建立 Blob 服務用戶端

從 @azure/identity 套件使用 DefaultAzureCredential

使用連接字串

搭配 StorageSharedKeyCredential

使用SAS令牌

建立新的容器

列出容器

上傳數據以建立 Blob

列出容器內的 Blob

下載 Blob 並將它轉換成字串 （Node.js）

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

故障排除

後續步驟

貢獻

其他資源

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

搭配 `StorageSharedKeyCredential`

下載 Blob 並將它轉換成字串（Node.js）