快速入門：Azure Blob 儲存體 適用於 Node.js 的客戶端連結庫

注意

[ 從頭 建置] 選項會逐步引導您逐步完成建立新專案、安裝套件、撰寫程序代碼，以及執行基本控制台應用程式的程式。 如果您想要瞭解建立連線到 Azure Blob 儲存體 的應用程式所涉及的所有詳細數據，建議使用此方法。 如果您想要將部署工作自動化，並從已完成的項目開始，請選擇 [從範本開始]。

注意

[ 開始使用範本 ] 選項會使用 Azure 開發人員 CLI 將部署工作自動化，並使用已完成的項目開始。 如果您想要儘快探索程序代碼，而不需完成設定工作，建議您使用此方法。 如果您想要逐步指示來建置應用程式，請選擇 [從頭開始建置]。

開始使用 Azure Blob 儲存體 客戶端連結庫，Node.js來管理 Blob 和容器。

在本文中，您會遵循步驟來安裝套件，並試用基本工作的範例程序代碼。

在本文中，您會使用 Azure 開發人員 CLI 來部署 Azure 資源，並使用幾個命令來執行已完成的控制台應用程式。

API 參考 | 連結庫原始程式碼 | 套件 （npm）範例 |

必要條件

• 具有使用中訂用帳戶的 Azure 帳戶 - 免費建立帳戶
• Azure 儲存體 帳戶 - 建立記憶體帳戶
• Node.js LTS

• Azure 訂用帳戶 - 建立免費帳戶
• Node.js LTS
• Azure Developer CLI

設定

本節將逐步引導您準備專案，以使用 Azure Blob 儲存體 客戶端連結庫進行Node.js。

建立 Node.js 專案

建立名為 blob-quickstart 的 JavaScript 應用程式。

1. 在主控台視窗中（例如 cmd、PowerShell 或 Bash），為專案建立新的目錄：

   mkdir blob-quickstart
   

2. 切換至新建立 的 blob-quickstart 目錄：

   cd blob-quickstart
   

3. 建立 package.json 檔案：

   npm init -y
   

4. 在 Visual Studio Code 中開啟專案：

   code .
   

安裝套件

從項目目錄中，使用 npm install 命令安裝下列套件。

1. 安裝 npm 套件 Azure 儲存體：

   npm install @azure/storage-blob
   

2. 安裝無密碼連線的 Azure Identity npm 套件：

   npm install @azure/identity
   

3. 安裝本快速入門中使用的其他相依性：

   npm install uuid dotenv
   

設定應用程式架構

從專案目錄：

1. 建立名為 的新檔案 index.js

2. 將下列程式碼複製至檔案：

   const { BlobServiceClient } = require("@azure/storage-blob");
   const { v1: uuidv1 } = require("uuid");
   require("dotenv").config();
   
   async function main() {
     try {
       console.log("Azure Blob storage v12 - JavaScript quickstart sample");
   
       // Quick start code goes here
   
   
   
     } catch (err) {
       console.err(`Error: ${err.message}`);
     }
   }
   
   main()
     .then(() => console.log("Done"))
     .catch((ex) => console.log(ex.message));
   

安裝 Azure 開發人員 CLI 後，您可以建立記憶體帳戶，並只使用幾個命令來執行範例程式代碼。 您可以在本機開發環境中或 DevContainer 中執行專案。

初始化 Azure 開發人員 CLI 範本並部署資源

從空目錄，遵循下列步驟來初始化 azd 範本、建立 Azure 資源，以及開始使用程式代碼：

• 從 GitHub 複製快速入門存放庫資產，並在本機初始化範本：

  azd init --template blob-storage-quickstart-nodejs
  

  系統會提示您輸入下列資訊：

  • 環境名稱：此值會作為 Azure 開發人員 CLI 所建立之所有 Azure 資源的前置詞。 名稱在所有 Azure 訂用帳戶中都必須是唯一的，且長度必須介於 3 到 24 個字元之間。 名稱只能包含數位和小寫字母。

• 登入 Azure：

  azd auth login
  

• 布建資源並將其部署至 Azure：

  azd up
  

  系統會提示您輸入下列資訊：

  • 訂用帳戶：您的資源部署至的 Azure 訂用帳戶。
  • 位置：部署資源的 Azure 區域。

  部署可能需要幾分鐘的時間才能完成。 命令的 azd up 輸出包含新建立的記憶體帳戶名稱，稍後您將需要執行程序代碼。

執行範例程式碼

此時，資源會部署至 Azure，而且程式代碼幾乎已準備好執行。 請遵循下列步驟來安裝套件、更新程式碼中的記憶體帳戶名稱，然後執行範例主控台應用程式：

1. 安裝套件：流覽至本機 blob-quickstart 目錄。 使用下列命令，安裝 Azure Blob 儲存體 和 Azure 身分識別用戶端連結庫的套件，以及快速入門中使用的其他套件：

   npm install @azure/storage-blob @azure/identity uuid dotenv
   

2. 更新記憶體帳戶名稱：在本機 blob-quickstart 目錄中，編輯名為 index.js 的檔案。 <storage-account-name>尋找佔位元，並將它取代為命令所azd up建立之記憶體帳戶的實際名稱。 儲存變更。
3. 執行項目：執行下列命令以執行應用程式：

   node index.js
   

4. 觀察輸出：此應用程式會建立容器，並將文字字串當做 Blob 上傳至容器。 然後，此範例會列出容器中的 Blob，並下載 Blob 並顯示 Blob 內容。 然後，應用程式會刪除容器及其所有 Blob。

若要深入瞭解範例程式代碼的運作方式，請參閱 程式代碼範例。

當您完成程式代碼測試后，請參閱 清除資源 一節，以刪除命令所 azd up 建立的資源。

物件模型

Azure Blob 記憶體已針對儲存大量非結構化數據進行優化。 「非結構化資料」是指不符合特定資料模型或定義的資料，例如文字或二進位資料。 Blob 儲存體提供三種類型資源：

• 儲存體帳戶
• 儲存體帳戶中的容器
• 容器中的 Blob

下圖顯示資源之間的關係。

使用下列 JavaScript 類別來與這些資源互動：

• BlobServiceClient：類別BlobServiceClient可讓您操作 Azure 儲存體 資源和 Blob 容器。
• ContainerClient：類別ContainerClient可讓您操作 Azure 儲存體 容器及其 Blob。
• BlobClient：類別BlobClient可讓您操作 Azure 儲存體 Blob。

程式碼範例

這些範例代碼段示範如何使用適用於 JavaScript 的 Azure Blob 儲存體 用戶端連結庫來執行下列工作：

• 向 Azure 驗證並授權 Blob 數據的存取權
• 建立容器
• 將 Blob 上傳至容器
• 列出容器中的 Blob
• 下載 Blob
• 刪除容器

GitHub 上也提供範例程序代碼。

注意

Azure 開發人員 CLI 樣本包含已就緒範例程式代碼的檔案。 下列範例提供範例程式代碼每個部分的詳細數據。 此範本會實作建議的無密碼驗證方法，如驗證至 Azure 一節所述。 連接字串 方法會顯示為替代方法，但不會在範本中使用，不建議用於生產程序代碼。

驗證 Azure，並授權存取 Blob 資料

應用程式向 Azure Blob 儲存體提出的要求必須經過授權。 DefaultAzureCredential使用 Azure 身分識別客戶端連結庫所提供的類別，是在您的程式代碼中實作無密碼連線的建議方法，包括 Blob 儲存體。

您也可以使用帳戶存取金鑰，以授權對 Azure Blob 儲存體的要求。 不過，應該謹慎使用此方法。 開發人員必須盡可能避免在不安全的地方公開存取金鑰。 具有存取金鑰的任何人都可以授權對儲存體帳戶的要求，而且實際上可以存取所有資料。 DefaultAzureCredential 提供優於帳戶金鑰的管理和安全性優點，允許無密碼驗證。 下列範例示範這兩個選項。

無密碼 （建議）

DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應該使用哪個方法。 此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法，而不需要實作環境特有的程式碼。

您可以在 Azure 身分識別連結庫概觀中找到尋找認證的順序和位置DefaultAzureCredential。

例如，應用程式在本機開發時可以使用 Azure CLI 登入認證進行驗證。 您的應用程式接著可以在部署至 Azure 之後使用 受控識別 。 此轉換不需要變更程序代碼。

將角色指派給 Microsoft Entra 使用者帳戶

在本機開發時，請確定存取 Blob 資料的使用者帳戶具有正確的權限。 您需要儲存體 Blob 資料參與者才能讀取和寫入 Blob 資料。 若要指派此角色給您自己，您需要被指派使用者存取管理員角色，或另一個包含 Microsoft.Authorization/roleAssignments/write 動作的角色。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell，將 Azure RBAC 角色指派給使用者。 您可以在範圍概觀頁面上深入了解角色指派的可用範圍。

在此案例中，您會將權限指派給使用者帳戶 (以儲存體帳戶為範圍)，以遵循最低權限原則。 此做法只為使用者提供所需的最低權限，並建立更安全的實際執行環境。

下列範例將儲存體 Blob 資料參與者角色指派給使用者帳戶，以針對儲存體帳戶中的 Blob 資料提供讀取和寫入存取權。

重要

在大部分情況下，角色指派在 Azure 中傳播只需要一兩分鐘，但在罕見情況下，可能需要長達八分鐘。 如果您第一次執行程式碼時收到驗證錯誤，請稍候片刻再試一次。

Azure 入口網站

1. 在 Azure 入口網站中，使用主要搜尋列或左側導覽找出您的儲存體帳戶。

2. 在儲存體帳戶概觀頁面上，從左側功能表中選取 [存取控制 (IAM)]。

3. 在 [存取控制 (IAM)] 頁面上，選取 [角色指派] 索引標籤。

4. 從頂端功能表選取 [+ 新增]，然後從產生的下拉功能表中選取 [新增角色指派]。

   

5. 使用搜尋方塊，從結果篩選出所需的角色。 在此範例中，搜尋「儲存體 Blob 資料參與者」，選取相符的結果，然後選擇 [下一步]。

6. 在 [存取權指派對象為] 下，選取 [使用者、群組或服務主體]，然後選擇 [+ 選取成員]。

7. 在對話方塊中，搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址)，然後在對話方塊底部選擇 [選取]。

8. 選取 [檢閱 + 指派] 以移至最終頁面，然後再次選取 [檢閱 + 指派] 以完成此程序。

Azure CLI

若要使用 Azure CLI 在資源層級指派角色，您必須先使用 az storage account show 命令擷取資源識別碼。 您可以使用 --query 參數來篩選輸出屬性。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

複製上述命令的輸出 Id。 接著，您可以使用 Azure CLI 的 az role 命令來指派角色。

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

若要使用 Azure PowerShell 在資源層級指派角色，您必須先使用 Get-AzResource 命令擷取資源識別碼。

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

複製上述命令輸出的 Id 值。 接著，您可以在 PowerShell 中使用 New-AzRoleAssignment 命令來指派角色。

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

使用DefaultAzureCredential登入應用程式程式碼並連線到 Azure

您可以使用下列步驟來授權存取儲存體帳戶中的資料：

1. 請確定使用您在 Blob 儲存體帳戶上指派角色的相同 Microsoft Entra 帳戶進行驗證。 您可以透過 Azure CLI、Visual Studio Code 或 Azure PowerShell 進行驗證。

   Azure CLI

   使用下列命令透過 Azure CLI 登入 Azure：

   az login
   

   Visual Studio Code

   安裝 Azure CLI 以透過 Visual Studio Code 使用 DefaultAzureCredential 。

   在 Visual Studio Code 的主功能表上，流覽至 [ 終端 > 機] [新增終端機]。

   使用下列命令透過 Azure CLI 登入 Azure：

   az login
   

   PowerShell

   使用 PowerShell 透過下列命令登入 Azure：

   Connect-AzAccount
   

2. 若要使用 DefaultAzureCredential，請確定已安裝 @azure\identity 套件，並匯入 類別：

   const { DefaultAzureCredential } = require('@azure/identity');
   

3. 在區塊內 try 新增此程序代碼。 當您的本機工作站上執行程式碼時， DefaultAzureCredential 會使用您登入以向 Azure 進行驗證之優先順序工具的開發人員認證。 這些工具的範例包括 Azure CLI 或 Visual Studio Code。

   const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
   if (!accountName) throw Error('Azure Storage accountName not found');
   
   const blobServiceClient = new BlobServiceClient(
     `https://${accountName}.blob.core.windows.net`,
     new DefaultAzureCredential()
   );
   

4. 請務必更新檔案或您環境變數中的.env記憶體帳戶名稱AZURE_STORAGE_ACCOUNT_NAME、 。 您可以在 Azure 入口網站 的概觀頁面上找到記憶體帳戶名稱。

   

   注意

   部署至 Azure 時，這個相同的程式代碼可用來授權要求從 Azure 中執行的應用程式 Azure 儲存體。 不過，您必須在 Azure 中的應用程式中啟用受控識別。 然後將記憶體帳戶設定為允許該受控識別連線。 如需在 Azure 服務之間設定此連線的詳細指示，請參閱從 Azure 託管應用程式進行驗證教學課程。

連接字串

連接字串 包含記憶體帳戶存取金鑰，並用它來授權要求。 請務必小心，不要在不安全的位置公開密鑰。

注意

若要使用記憶體帳戶存取密鑰來授權資料存取，您需要下列 Azure RBAC 動作的許可權：Microsoft.儲存體/storageAccounts/listkeys/action。 具有此動作許可權的最低特殊許可權內建角色是 讀取器和數據存取，但包含此動作的任何角色都能夠運作。

Azure 入口網站

1. 登入 Azure 入口網站。

2. 找出您的儲存體帳戶。

3. 在 [儲存體帳戶] 功能表窗格的 [安全性 + 網路] 下方，選取 [存取金鑰]。 在此處，您可以檢視帳戶存取金鑰，和每個金鑰的完整連接字串。

4. 在 [存取金鑰] 窗格中，選取 [顯示金鑰]。

5. 在 [金鑰 1] 區段中，找出連接字串值。 選取 [複製到剪貼簿] 圖示以複製連接字串。 在下一小節中，您會將該連接字串值新增至環境變數。

   

Azure CLI

您可以使用 az storage account show-connection-string 命令來查看記憶體帳戶的 連接字串。

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

您可以使用 Get-Az 儲存體 Account 和 Get-Az 儲存體 AccountKey 命令，使用 PowerShell 組合 連接字串。

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

設定儲存體連接字串

在複製連接字串後，請在執行應用程式的本機電腦上，將該字串寫入至新的環境變數中。 若要設定環境變數，請開啟主控台視窗，並遵循您的作業系統所適用的指示。 將 <yourconnectionstring> 用實際的連接字串取代。

Windows：

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

在 Windows 中新增環境變數之後，您必須啟動新的命令視窗執行個體。

Linux：

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

.env 檔案：

AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

下列程式代碼會從稍早建立的環境變數擷取記憶體帳戶的 連接字串，並使用 連接字串 來建構服務客戶端物件。

在區塊內 try 新增此程式碼：

const AZURE_STORAGE_CONNECTION_STRING = 
  process.env.AZURE_STORAGE_CONNECTION_STRING;

if (!AZURE_STORAGE_CONNECTION_STRING) {
  throw Error('Azure Storage Connection string not found');
}

// Create the BlobServiceClient object with connection string
const blobServiceClient = BlobServiceClient.fromConnectionString(
  AZURE_STORAGE_CONNECTION_STRING
);

重要

應該謹慎使用帳戶存取金鑰。 如果帳戶存取金鑰遺失或意外放在不安全的地方，您的服務可能變得易受攻擊。 具有存取金鑰的任何人都可以授權對儲存體帳戶的要求，並有效地存取所有資料。 DefaultAzureCredential 會提供增強的安全性功能和權益，建議用來管理對 Azure 服務的授權。

建立容器

在記憶體帳戶中建立新的容器。 下列程式代碼範例會採用 BlobServiceClient 物件，並呼叫 getContainerClient 方法來取得容器的參考。 然後，程式代碼會呼叫 create 方法，以實際在記憶體帳戶中建立容器。

將此程式代碼新增至 區塊的 try 結尾：

// Create a unique name for the container
const containerName = 'quickstart' + uuidv1();

console.log('\nCreating container...');
console.log('\t', containerName);

// Get a reference to a container
const containerClient = blobServiceClient.getContainerClient(containerName);
// Create the container
const createContainerResponse = await containerClient.create();
console.log(
  `Container was created successfully.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
);

若要深入瞭解如何建立容器，以及探索更多程式碼範例，請參閱 使用 JavaScript 建立 Blob 容器。

重要

容器名稱必須是小寫字母。 如需命名容器和 Blob 的詳細資訊，請參閱 命名和參考容器、Blob 和元數據。

將 Blob 上傳至容器

將 Blob 上傳到該容器。 下列程式代碼會從 [建立容器] 區段呼叫 ContainerClient 上的 getBlockBlobClient 方法，以取得 BlockBlobClient 對象的參考。

程式代碼會藉由呼叫 upload 方法，將文字字串數據上傳至 Blob。

將此程式代碼新增至 區塊的 try 結尾：

// Create a unique name for the blob
const blobName = 'quickstart' + uuidv1() + '.txt';

// Get a block blob client
const blockBlobClient = containerClient.getBlockBlobClient(blobName);

// Display blob name and url
console.log(
  `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
);

// Upload data to the blob
const data = 'Hello, World!';
const uploadBlobResponse = await blockBlobClient.upload(data, data.length);
console.log(
  `Blob was uploaded successfully. requestId: ${uploadBlobResponse.requestId}`
);

若要深入瞭解上傳 Blob，以及探索更多程式代碼範例，請參閱 使用 JavaScript 上傳 Blob。

列出容器中的 Blob

列出容器中的 Blob。 下列程式代碼會呼叫 listBlobsFlat 方法。 在此情況下，容器中只有一個 Blob，因此清單作業只會傳回該 Blob。

將此程式代碼新增至 區塊的 try 結尾：

console.log('\nListing blobs...');

// List the blob(s) in the container.
for await (const blob of containerClient.listBlobsFlat()) {
  // Get Blob Client from name, to get the URL
  const tempBlockBlobClient = containerClient.getBlockBlobClient(blob.name);

  // Display blob name and URL
  console.log(
    `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
  );
}

若要深入瞭解列出 Blob，以及探索更多程式代碼範例，請參閱 使用 JavaScript 列出 Blob。

下載 Blob

下載 Blob 並顯示內容。 下列程式代碼會呼叫 download 方法來下載 Blob。

將此程式代碼新增至 區塊的 try 結尾：

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blockBlobClient.download(0);
console.log('\nDownloaded blob content...');
console.log(
  '\t',
  await streamToText(downloadBlockBlobResponse.readableStreamBody)
);

下列程式代碼會將數據流轉換回字串，以顯示內容。

在函main式之後新增此程式碼：

// Convert stream to text
async function streamToText(readable) {
  readable.setEncoding('utf8');
  let data = '';
  for await (const chunk of readable) {
    data += chunk;
  }
  return data;
}

若要深入瞭解如何下載 Blob，以及探索更多程式代碼範例，請參閱 使用 JavaScript 下載 Blob。

刪除容器

刪除容器和容器內的所有 Blob。 下列程式代碼會使用 delete 方法移除整個容器，以清除應用程式所建立的資源。

將此程式代碼新增至 區塊的 try 結尾：

// Delete container
console.log('\nDeleting container...');

const deleteContainerResponse = await containerClient.delete();
console.log(
  'Container was deleted successfully. requestId: ',
  deleteContainerResponse.requestId
);

若要深入瞭解如何刪除容器，以及探索更多程式碼範例，請參閱 使用 JavaScript 刪除和還原 Blob 容器。

執行程式碼

從 Visual Studio Code 終端機執行應用程式。

node index.js

應用程式的輸出類似下列範例：

Azure Blob storage - JavaScript quickstart sample

Creating container...
    quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
    Hello, World!

Deleting container...
Done

逐步執行調試程式中的程序代碼，並檢查整個程式 Azure 入口網站。 檢查是否已建立容器。 您可以在容器內開啟 Blob，並檢視內容。

清除資源

1. 當您完成本快速入門時，請刪除 blob-quickstart 目錄。
2. 如果您使用 Azure 儲存體 資源完成，請使用 Azure CLI 來移除 儲存體 資源。

當您完成快速入門時，您可以執行下列命令來清除您所建立的資源：

azd down

系統會提示您確認刪除資源。 輸入 y 以確認。

下一步

在本快速入門中，您已瞭解如何使用 JavaScript 上傳、下載及列出 Blob。

若要查看 Blob 儲存體範例應用程式，請繼續查看：

適用於 JavaScript 範例的 Azure Blob 儲存體 連結庫

• 若要深入瞭解，請參閱適用於 JavaScript 的 Azure Blob 儲存體 客戶端連結庫。
• 如需教學課程、範例、快速入門和其他檔，請流覽 適用於JavaScript的 Azure 和Node.js開發人員。