使用 Azurite 模擬器進行本機 Azure 儲存體開發

Azurite 開放原始碼模擬器提供免費的本機環境,可用來測試您的 Azure Blod、佇列儲存體,以及資料表儲存體應用程式。 如果您滿意應用程式在本機的運作表現,就可以切換成使用雲端的 Azure 儲存體帳戶。 模擬器提供 Windows、Linux 和 macOS 的跨平台支援。

Azurite 是未來的儲存體模擬器平台。 Azurite 會取代 Azure 儲存體模擬器。 Azurite 將繼續更新以支援最新版本的 Azure 儲存體 API。

您有多種方式可以在本機系統上安裝和執行 Azurite。 選取任一個索引標籤。

安裝 Azurite

Azurite 會自動提供 Visual Studio 2022。 如果您執行的是舊版 Visual Studio,則必須使用 Node 套件管理員、DockerHub,或複製 Azurite GitHub 存放庫來安裝 Azurite。

執行 Azurite

透過幾個設定,Azure Functions 或 ASP.NET 專案會自動啟動 Azurite。 針對所有其他專案類型,您必須從命令列啟動 Azurite。

從命令列執行 Azurite

您可以在 Visual Studio 安裝的延伸模組資料夾中找到 Azurite 可執行檔。 具體位置可能會因安裝的 Visual Studio 版本而有所不同。 例如,如果已在 Windows 電腦或虛擬機器 (VM) 上安裝 Visual Studio 2022 專業版,您會在下列位置找到 Azurite 可執行檔:C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\IDE\Extensions\Microsoft\Azure Storage Emulator

執行可執行檔之後,Azurite 會接聽連線。

Azurite command-line output

從 Azure Functions 專案執行 Azurite

在 Visual Studio 2022 中建立 Azure Functions 專案。 當您建立專案時,請選擇儲存體模擬器

Storage emulator option in Azure Functions project

建立專案之後,Azurite 就會自動啟動。

Azurite command-line output in Azure Functions project

從 ASP.NET 專案執行 Azurite

在 Visual Studio Code 2022 中建立 ASP.NET Core Web 應用程式專案。 然後,開啟 [已連線的服務] 對話方塊,選取 [新增服務相依性],然後選取 [儲存體 Azurite 模擬器]。

Connected services dialog box in ASP.NET Core Web App project

在 [設定儲存體 Azurite 模擬器] 對話方塊中,將 [連接字串名稱] 欄位設定為 StorageConnectionString,然後選取 [完成]。

Configure Storage Azurite emulator dialog box

設定完成時,請選取 [關閉]。 Azurite 模擬器會自動啟動。

Azurite command-line output in ASP.NET project

命令列選項

本節將詳細說明啟動 Azurite 時可用的命令列參數。

說明

選用 - 使用 -h--help 參數取得命令列說明。

azurite -h
azurite --help

Blob 接聽主機

選用 - 根據預設,Azurite 會接聽 127.0.0.1 作為本機伺服器。 使用 --blobHost 參數設定所需的位址。

僅接受本機電腦上的要求:

azurite --blobHost 127.0.0.1

允許遠端要求:

azurite --blobHost 0.0.0.0

警告

允許遠端要求可能會讓您的系統容易遭受外部攻擊。

Blob 接聽連接埠設定

選用 - 根據預設,Azurite 會接聽連接埠 10000 上的 Blob 服務。 使用 --blobPort 參數來指定所需的接聽連接埠。

注意

使用自訂連接埠之後,您需要更新 Azure 儲存體工具或 SDK 中的連接字串或對應設定。

自訂 Blob 服務接聽連接埠:

azurite --blobPort 8888

讓系統自動選取可用的連接埠:

azurite --blobPort 0

使用中的連接埠會在 Azurite 啟動期間顯示。

佇列接聽主機

選用 - 根據預設,Azurite 會接聽 127.0.0.1 作為本機伺服器。 使用 --queueHost 參數設定所需的位址。

僅接受本機電腦上的要求:

azurite --queueHost 127.0.0.1

允許遠端要求:

azurite --queueHost 0.0.0.0

警告

允許遠端要求可能會讓您的系統容易遭受外部攻擊。

佇列接聽連接埠設定

選用 - 根據預設,Azurite 會接聽連接埠 10001 上的佇列服務。 使用 --queuePort 參數來指定所需的接聽連接埠。

注意

使用自訂連接埠之後,您需要更新 Azure 儲存體工具或 SDK 中的連接字串或對應設定。

自訂佇列服務接聽連接埠:

azurite --queuePort 8888

讓系統自動選取可用的連接埠:

azurite --queuePort 0

使用中的連接埠會在 Azurite 啟動期間顯示。

資料表接聽主機

選用 - 根據預設,Azurite 會接聽 127.0.0.1 作為本機伺服器。 使用 --tableHost 參數設定所需的位址。

僅接受本機電腦上的要求:

azurite --tableHost 127.0.0.1

允許遠端要求:

azurite --tableHost 0.0.0.0

警告

允許遠端要求可能會讓您的系統容易遭受外部攻擊。

資料表接聽連接埠設定

選用 - 根據預設,Azurite 會接聽連接埠 10002 上的資料表服務。 使用 --tablePort 參數來指定所需的接聽連接埠。

注意

使用自訂連接埠之後,您需要更新 Azure 儲存體工具或 SDK 中的連接字串或對應設定。

自訂資料表服務接聽連接埠:

azurite --tablePort 11111

讓系統自動選取可用的連接埠:

azurite --tablePort 0

使用中的連接埠會在 Azurite 啟動期間顯示。

工作區路徑

選用 - Azurite 會在執行期間將資料儲存至本機磁碟。 使用 -l--location 參數將路徑指定為工作區位置。 根據預設,將會使用目前的處理序工作目錄。 請注意小寫的 'l'。

azurite -l c:\azurite
azurite --location c:\azurite

存取記錄檔

選用 - 依預設,存取記錄會顯示在主控台視窗中。 使用 -s--silent 參數停用存取記錄的顯示。

azurite -s
azurite --silent

偵錯記錄

選用 - 偵錯記錄包含每個要求和例外狀況堆疊追蹤的詳細資訊。 透過為 -d--debug 參數提供有效的本機檔案路徑,以啟用偵錯記錄。

azurite -d path/debug.log
azurite --debug path/debug.log

鬆散模式

選用 - 根據預設,Azurite 會套用 strict 模式來封鎖不支援的要求標頭和參數。 使用 -L--loose 參數以停用 strict 模式。 請注意大寫的 'L'。

azurite -L
azurite --loose

版本

選用 - 使用 -v--version 參數顯示已安裝的 Azurite 版本號碼。

azurite -v
azurite --version

憑證組態 (HTTPS)

選用 - 根據預設,Azurite 會使用 HTTP 通訊協定。 向 --cert 參數提供隱私權增強郵件 (.pem) 或個人資訊交換 (.pfx) 憑證檔案的路徑,藉此啟用 HTTPS 模式。

當針對 PEM 檔案提供 --cert 時,您必須提供對應的 --key 參數。

azurite --cert path/server.pem --key path/key.pem

當針對 PFX 檔案提供 --cert 時,您必須提供對應的 --pwd 參數。

azurite --cert path/server.pfx --pwd pfxpassword

如需建立 PEM 和 PFX 檔案的詳細資訊,請參閱 HTTPS 設定

OAuth 組態

選用 - 使用 --oauth 參數啟用 Azurite 的 OAuth 驗證。

azurite --oauth basic --cert path/server.pem --key path/key.pem

注意

OAuth 需要 HTTPS 端點。 提供 --cert 參數和 --oauth 參數以確定已啟用 HTTPS。

Azurite 藉由為 --oauth 開關指定 basic 參數以支援基本驗證。 Azurite 將會進行基本驗證,例如驗證傳入的持有人權杖、檢查簽發者、對象和到期日。 Azurite 不會檢查權杖簽章或權限。

略過 API 版本檢查

選用 - 啟動時,Azurite 會檢查要求的 API 版本是否有效。 下列命令會略過 API 版本檢查:

azurite --skipApiVersionCheck

工具和 SDK 的授權

使用任何驗證策略,從 Azure 儲存體 SDK 或工具 (例如Azure 儲存體總管) 連線至 Azurite。 需要驗證。 Azurite 支援使用 OAuth、共用金鑰和共用存取簽章 (SAS) 的授權。 Azurite 也支援對公用容器的匿名存取。

如果您使用的是 Azure SDK,請使用 --oauth basic and --cert --key/--pwd 選項來啟動 Azurite。

已知的儲存體帳戶和金鑰

Azurite 會接受舊版 Azure 儲存體模擬器使用的相同已知帳戶和金鑰。

  • 帳戶名稱:devstoreaccount1
  • 帳戶金鑰:Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

自訂儲存體帳戶和金鑰

Azurite 支援自訂的儲存體帳戶名稱和金鑰,方法是用下列格式設定 AZURITE_ACCOUNTS 環境變數:account1:key1[:key2];account2:key1[:key2];...

例如,使用具有一個金鑰的自訂儲存體帳戶:

set AZURITE_ACCOUNTS="account1:key1"
export AZURITE_ACCOUNTS="account1:key1"

或使用多個儲存體帳戶,每個帳戶都有兩個金鑰:

set AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"
export AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"

Azurite 預設每分鐘會從環境變數重新整理自訂帳戶名稱和金鑰。 透過這項功能,您可以動態輪替帳戶金鑰或新增儲存體帳戶,而不需重新啟動 Azurite。

注意

當您設定自訂的儲存體帳戶時,預設 devstoreaccount1 儲存體帳戶會停用。

連接字串

從您的應用程式連線到 Azurite 最簡單的方法,就是在應用程式參照捷徑 UseDevelopmentStorage=true 的組態檔中設定連接字串。 以下是 app.config 檔案中的連接字串範例:

<appSettings>
  <add key="StorageConnectionString" value="UseDevelopmentStorage=true" />
</appSettings>

HTTPS 連接字串

您可以將下列連接字串傳遞給 Azure sdk 或工具,例如 Azure CLI 2.0 或儲存體總管。

完整的連接字串為:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;TableEndpoint=http://127.0.0.1:10002/devstoreaccount1;

若要只連接到 Blob 服務,連接字串為:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;

若要只連接到佇列服務,連接字串為:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;

若要只連接到資料表服務,連接字串為:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;TableEndpoint=http://127.0.0.1:10002/devstoreaccount1;

HTTPS 連接字串

完整的 HTTPS 連接字串為:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;TableEndpoint=https://127.0.0.1:10002/devstoreaccount1;

若只要使用 Blob 服務,HTTPS 連接字串為:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;

若只要使用佇列服務,HTTPS 連接字串為:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;

若只要使用資料表服務,HTTPS 連接字串為:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;TableEndpoint=https://127.0.0.1:10002/devstoreaccount1;

如果您使用 dotnet dev-certs 來產生自我簽署的憑證,請使用下列連接字串。

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://localhost:10000/devstoreaccount1;QueueEndpoint=https://localhost:10001/devstoreaccount1;TableEndpoint=https://localhost:10002/devstoreaccount1;

使用自訂儲存體帳戶和金鑰時,請更新連接字串。

如需詳細資訊,請參閱設定 Azure 儲存體連接字串

Azure SDK

若要搭配使用 Azurite 與 Azure SDK,請使用 OAuth 和 HTTPS 選項:

azurite --oauth basic --cert certname.pem --key certname-key.pem

Azure Blob 儲存體

然後,您可以具現化 BlobContainerClient、BlobServiceClient 或 Blobclient。

// With container URL and DefaultAzureCredential
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new BlobContainerClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;", "container-name"
  );

// With account name and key
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

Azure 佇列儲存體

您也可以具現化 QueueClient 或 QueueServiceClient。

// With queue URL and DefaultAzureCredential
var client = new QueueClient(
    new Uri("https://127.0.0.1:10001/devstoreaccount1/queue-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new QueueClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;", "queue-name"
  );

// With account name and key
var client = new QueueClient(
    new Uri("https://127.0.0.1:10001/devstoreaccount1/queue-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

Azure 表格儲存體

您也可以具現化 TableClient 或 TableServiceClient。

// With table URL and DefaultAzureCredential
var client = new Client(
    new Uri("https://127.0.0.1:10002/devstoreaccount1/table-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new TableClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;TableEndpoint=https://127.0.0.1:10002/devstoreaccount1;", "table-name"
  );

// With account name and key
var client = new TableClient(
    new Uri("https://127.0.0.1:10002/devstoreaccount1/table-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

Microsoft Azure 儲存體總管

您可以使用儲存體總管來查看儲存在 Azurite 中的資料。

使用 HTTP 連線至 Azurite

在儲存體總管中,依照下列步驟連線到 Azurite:

  1. 選取 [管理帳戶] 圖示
  2. 選取 [新增帳戶]
  3. 選取 [連結至本機模擬器]
  4. 選取 [下一步]
  5. 將 [顯示名稱] 欄位編輯為您選擇的名稱
  6. 再次選取 [下一步]
  7. 選取 [連線]

使用 HTTPS 連線至 Azurite

依預設,儲存體總管不會開啟使用自我簽署憑證的 HTTPS 端點。 如果您是使用 HTTPS 執行 Azurite,則可能是使用自我簽署的憑證。 請在儲存體總管中,透過 [編輯] ->[SSL 憑證] ->[匯入憑證] 對話方塊匯入 SSL 憑證。

將憑證匯入儲存體總管
  1. 找到本機電腦上的憑證。
  2. 在儲存體總管中,移至 [編輯] ->[SSL 憑證] ->[匯入憑證] 並匯入您的憑證。

如果您未匯入憑證,將會收到錯誤:

unable to verify the first certificateself signed certificate in chain

透過 HTTPS 連接字串新增 Azurite

請依照下列步驟將 Azurite HTTPS 新增至儲存體總管:

  1. 選取 [切換瀏覽器]
  2. 選取 [本機 & 附加]
  3. 以滑鼠右鍵按一下 [儲存體帳戶],然後選取 [連線到 Azure 儲存體]。
  4. 選取 [使用連接字串]
  5. 選取 [下一步] 。
  6. 在 [顯示名稱] 欄位中輸入值。
  7. 輸入本文件上一節的 HTTPS 連接字串
  8. 選取 [下一步]
  9. 選取 [連線]

工作區結構

初始化 Azurite 時,可能會在工作區位置中建立下列檔案和資料夾。

  • __blobstorage__:此目錄包含 Azurite Blob 服務保存的二進位資料
  • __queuestorage__:此目錄包含 Azurite 佇列服務保存的二進位資料
  • __tablestorage__:此目錄包含 Azurite 資料表服務保存的二進位資料
  • __azurite_db_blob__.json:Azurite Blob 服務中繼資料檔案
  • __azurite_db_blob_extent__.json:Azurite Blob 服務範圍中繼資料檔案
  • __azurite_db_queue__.json:Azurite 佇列服務中繼資料檔案
  • __azurite_db_queue_extent__.json:Azurite 佇列服務範圍中繼資料檔案
  • __azurite_db_table__.json:Azurite 資料表服務中繼資料檔案
  • __azurite_db_table_extent__.jsonAzurite 資料表服務範圍中繼資料檔案

若要清除 Azurite,請刪除上述的檔案和資料夾,然後重新啟動模擬器。

Azure 與 Azure 儲存體之間的差異

Azurite 的本機執行個體與雲端中的 Azure 儲存體帳戶之間有一些功能上的差異。

端點和連接 URL

Azurite 的服務端點與 Azure 儲存體帳戶的端點不同。 本機電腦不會進行網域名稱解析,要求 Azurite 端點必須是本機位址。

當您定址 Azure 儲存體帳戶中的資源時,帳戶名稱會是 URI 主機名稱的一部分。 所定址的資源是 URI 路徑的一部分:

<http|https>://<account-name>.<service-name>.core.windows.net/<resource-path>

下列 URI 是 Azure 儲存體帳戶中的有效 Blob 位址:

https://myaccount.blob.core.windows.net/mycontainer/myblob.txt

因為本機電腦不會進行網域名稱解析,所以帳戶名稱是 URI 路徑的一部分,而不是主機名稱。 針對 Azurite 中的資源使用下列 URI 格式:

http://<local-machine-address>:<port>/<account-name>/<resource-path>

下列位址可能會用於存取 Azurite 中的 Blob:

http://127.0.0.1:10000/myaccount/mycontainer/myblob.txt

調整和效能

Azurite 不支援大量的連線用戶端。 沒有任何效能保證。 Azurite 適合用於開發和測試目的。

錯誤處理

Azurite 與 Azure 儲存體錯誤處理邏輯一致,但是有一些差異。 例如,錯誤訊息可能會不同,而錯誤狀態碼則會一致。

RA-GRS

Azurite 支援讀取權限異地備援複寫 (RA-GRS)。 針對儲存體資源,請將 -secondary 附加至帳戶名稱以存取次要位置。 例如,下列位址可能會用於在 Azurite 中使用唯讀的次要位置來存取 Blob:

http://127.0.0.1:10000/devstoreaccount1-secondary/mycontainer/myblob.txt

資料表支援

Azurite 中的資料表支援目前為預覽狀態。 如需詳細資訊,請參閱 Azurite V3 資料表專案。

長期函式的支援需要資料表。

重要

Azurite 對資料表儲存體的支援目前為預覽狀態。 請參閱 Microsoft Azure 預覽版增補使用規定,以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版,或尚未正式發行的版本) 的法律條款。

Azurite 是開放原始碼

歡迎為 Azurite 提供貢獻和建議。 移至 Azurite GitHub 專案頁面,或我們正在追蹤的里程碑和工作專案的 GitHub 問題,以瞭解即將推出的功能和錯誤修正。 您也可以在 GitHub 中追蹤詳細的工作項目。

下一步