使用 JavaScript 將影像上傳至 Azure 儲存體 Blob

  • 發行項

使用靜態 Web 應用程式，使用具有 Azure 儲存體 SAS 令牌的 Azure 儲存體 @azure/storage-blob npm 套件，將檔案上傳至 Azure 儲存體 Blob。

必要條件

應用程式架構

此應用程式架構包含兩個 Azure 資源：

  • 靜態產生的用戶端應用程式的 Azure Static Web Apps。 資源也會提供受控 Azure Functions API。 Managed 表示靜態 Web Apps 資源會管理 API 資源以供自己使用。
  • blob 記憶體 Azure 儲存體。

Diagram showing how a customer interacts from their computer to use the website to upload a file to Azure Storage directly.

步驟 描述:
1 客戶會連線到靜態產生的網站。 網站裝載於 Azure Static Web Apps 中。
2 客戶使用該網站來選取要上傳的檔案。 在本教學課程中，前端架構是 Vite React ，而上傳的檔案是圖像檔。
3 網站會呼叫 Azure Functions API sas ，以根據要上傳之檔案的確切 檔名 來取得 SAS 令牌。 無伺服器 API 會使用 Azure Blob 儲存體 SDK 來建立 SAS 令牌。 API 會傳回用來上傳檔案的完整 URL，其中包含 SAS 令牌作為查詢字串。
https://YOUR-STORAGE-NAME.blob.core.windows.net/YOUR-CONTAINER/YOUR-FILE-NAME?YOUR-SAS-TOKEN
4 前端網站會使用SAS令牌 URL，將檔案直接上傳至 Azure Blob 儲存體。

本機和建置環境

本教學課程使用下列環境：

  • 使用 GitHub Codespaces 或 Visual Studio Code 進行本機開發。
  • 使用 GitHub Actions 建置和部署。

1.使用 GitHub 分支範例應用程式存放庫

本教學課程使用 GitHub 動作將範例應用程式部署至 Azure。 您需要 GitHub 帳戶和範例應用程式存放庫分支，才能完成該部署。

  1. 在網頁瀏覽器中，使用下列鏈接開始範例存放庫帳戶的分支： Azure-Samples/azure-typescript-e2e-apps。
  2. 請完成步驟，以僅使用 主要 分支分叉範例。

2.設定開發環境

開發容器環境可供完成此專案中每個練習所需的所有相依性使用。 您可以在 GitHub Codespaces 中或使用 Visual Studio Code 在本機執行開發容器。

GitHub Codespaces 會使用網頁版 Visual Studio Code 作爲使用者介面，執行由 GitHub 管理的開發容器。 針對最直接的開發環境，請使用 GitHub Codespaces，讓您已預先安裝正確的開發人員工具和相依性來完成此訓練課程模組。

重要

所有 GitHub 帳戶每個月最多可以使用 Codespaces 60 小時，且有 2 個核心執行個體。 如需詳細資訊，請參閱 GitHub Codespaces 每月包含的儲存體和核心時數。

  1. 在網頁瀏覽器中，於範例存放庫的 GitHub 分支上，選取 [程序代碼] 按鈕，開始在分支分支上main建立新的 GitHub Codespace 程式。

    GitHub screenshot of Code Spaces buttons for a repository.

  2. 在 [Codespaces] 索引標籤上，選取省略號 。 ...

    GitHub screenshot of Code Spaces tab with ellipsis control highlighted.

  3. 選取 [+ 新增] 選項 ，以選取特定的 Codespaces 開發容器。

    GitHub screenshot of Codespaces New with options menu item highlighted.

  4. 選取下列選項，然後選取 [ 建立程式代碼空間]。

    • 分公司： main
    • 開發容器組態： Tutorial: Upload file to storage with SAS Token
    • 區域：接受預設值
    • 機器類型：接受預設值

    GitHub screenshot of Codespaces New with options menu with the following dev container highlighted, Tutorial: Upload file to storage with SAS Token.

  5. 等候 Codespace 開始。 此啟動程序可能需要幾分鐘的時間。

  6. 在 Codespace 中開啟新的終端機。

    提示

    您可以使用主功能表瀏覽至 [終端機] 功能表選項，然後選取 [新終端機] 選項。

    Screenshot of the codespaces menu option to open a new terminal.

  7. 檢查您在本教學課程中使用的工具版本。

    node --version
npm --version
func --version

    本教學課程需要下列版本的每個工具，這些工具會預安裝在您的環境中：

    工具 版本
    Node.js ≥ 18
    npm \(英文\) ≥ 9.5
    Azure Functions 核心工具 ≥ 4.5098

  8. 關閉終端機。

  9. 本教學課程中的其餘步驟會在此開發容器的內容中進行。

3.安裝相依性

本教學課程的範例應用程式位於 azure-upload-file-to-storage 資料夾中。 您不需要在專案中使用任何其他資料夾。

  1. 在 Visual Studio Code 中，開啟終端機，然後移至項目資料夾。

    cd azure-upload-file-to-storage

  2. 分割終端機，以便您有兩個終端機，一個用於用戶端應用程式，另一個用於API 應用程式。

  3. 在其中一個終端機中，執行下列命令來安裝 API 應用程式的相依性，並執行應用程式。

    cd api && npm install

  4. 在其他終端機中，執行命令以安裝 用戶端應用程式。

    cd app && npm install

4.使用 Visual Studio 擴充功能建立 儲存體 資源

建立要與範例應用程式搭配使用的 儲存體 資源。 儲存體會用於：

  • Azure Functions 應用程式中的觸發程式
  • Blob （檔案） 記憶體

  1. 流覽至 Azure 儲存體 延伸模組。

  2. 如有必要，請登入 Azure。

  3. 以滑鼠右鍵按下訂用帳戶，然後選取 Create Resource...。

    Screenshot of Visual Studio Code in the Azure Explorer with the right-click menu showing the Create Resource item highlighted.

  4. 從清單中選取 [建立 儲存體 帳戶]。

  5. 請遵循使用下表的提示，瞭解如何建立 儲存體 資源。

    屬性 值
    輸入新 Web 應用程式的全域唯一名稱。 針對您的 儲存體 資源名稱，輸入唯一的值，例如 fileuploadstor。

    此唯一名稱是 下一節中使用的資源名稱 。 只使用字元和數位，長度最多 24 個字元。 您稍後需要此 帳戶名稱 才能使用。
    選取新資源的位置。 使用建議的位置。

  6. 當應用程式建立程式完成時，會出現通知，其中包含新資源的相關信息。

    Screenshot of Visual Studio Code showing the Azure Activity Bar and the notification that the storage account was successfully created.

5.設定 儲存體 CORS

因為瀏覽器是用來上傳檔案，Azure 儲存體 帳戶必須設定 CORS 以允許跨原始來源要求。

  1. 流覽至 Azure 儲存體 延伸模組。 以滑鼠右鍵按下您的記憶體資源，然後選取 [在入口網站中開啟]。

  2. 在 [Azure 入口網站 儲存體帳戶 設定] 區段中，選取 [資源分享] [CORS]。

  3. 使用下列屬性來設定本教學課程的CORS。

    • 允許的來源： *
    • 允許的方法：修補程式以外的所有方法
    • 允許的標頭： *
    • 公開的標頭： *
    • 最大年齡：86400

    本教學課程會使用這些設定來簡化步驟，並非用來指出最佳做法或安全性。 深入瞭解 CORS for Azure 儲存體。

  4. 選取 [儲存]。

6.將匿名存取權授與記憶體

當您建立限時和許可權有限的 SAS 令牌時，檔案上傳會受到客戶端保護。 不過，上傳檔案之後，在本教學課程案例中，您希望任何人看到它。 若要這樣做，您必須將記憶體許可權變更為可公開存取。

雖然帳戶可公開存取，但每個容器和每個 Blob 都可以有私人存取權。 較安全的方法，但本教學課程過於複雜，就是使用 SAS 令牌上傳至一個記憶體帳戶，然後將 Blob 移至具有公用存取權的另一個記憶體帳戶。

  1. 若要在 Azure 入口網站 中啟用公用存取，請選取記憶體帳戶的 [概觀] 頁面，在 [屬性] 區段中，選取 [Blob 匿名存取]，然後選取 [已停用]。
  2. 在 [ 組態 ] 頁面上，啟用 [允許 Blob 匿名存取]。

7.建立上傳容器

  1. 在 Azure 入口網站 記憶體帳戶中，在 [數據記憶體] 區段中，選取 [容器]。

  2. 選取 [+ 容器 ] 以使用下列設定建立您的 upload 容器：

    • 名稱：upload
    • 公用存取層級： Blob

  3. 選取 建立。

8.將 Blob 資料存取權授與自己

建立資源時，您沒有檢視容器內容的許可權。 這是保留給特定 IAM 角色。 新增您的帳戶，以便檢視容器中的 Blob。

  1. 仍在Azure 入口網站儲存體帳戶中，選取 [存取控制 ][IAM]。
  2. 選取 [新增角色指派]。
  3. 搜尋並選取 [儲存體 Blob 資料參與者 ]。 選取 [下一步] 。
  4. 選取 + 選取成員。
  5. 搜尋並選取您的帳戶。
  6. 選取檢閱+指派。
  7. 選取 [容器 ]，然後選取 上傳 容器。 您應該能夠在沒有授權錯誤的情況下看到容器中沒有 Blob。

9.取得儲存體資源認證

azure Functions API 應用程式中會使用儲存體資源認證來連線到儲存體資源。

  1. 仍在Azure 入口網站中，請在 [安全性 + 網路] 區段中，選取 [ 存取金鑰 ]。

  2. 請記住，API 檔案位於 ./workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/api 。

  3. 在 API 資料夾中， 將 檔案從 local.settings.json.sample 重新命名 為 local.settings.json 。 Git 會忽略檔案，因此不會簽入原始檔控制。

  4. 使用下表更新 的 local.settings.json 設定。

    屬性 數值 Description
    Azure_儲存體_AccountName Azure 儲存體帳戶名稱，例如： fileuploadstor 。 在原始程式碼中用來連線到儲存體資源。
    Azure_儲存體_AccountKey Azure 儲存體帳戶金鑰 在原始程式碼中用來連線到儲存體資源。
    AzureWebJobsStorage Azure 儲存體帳戶連接字串 使用 Azure Functions 執行時間來儲存狀態和記錄。

您似乎輸入了相同的帳號憑證兩次，一次做為金鑰，一次做為連接字串。 您確實這麼做，但特別針對這個簡單的教學課程。 一般而言，Azure Functions 應用程式應該有個別的儲存體資源，不會再用於其他用途。 當您稍後在教學課程中建立 Azure Function 資源時，您不需要設定 雲端資源的 AzureWebJobs儲存體 值。 您只需要設定 原始程式碼中使用的Azure_儲存體_AccountName 和 Azure_儲存體_AccountKey 值。

10.執行 API 應用程式

執行 Functions 應用程式，確定其可正常運作，再將其部署至 Azure。

  1. 在 API 應用程式的終端機中，執行下列命令來啟動 API 應用程式。

    npm run start

  2. 等候 Azure Functions 應用程式啟動。 您會看到 Azure Functions 應用程式的埠 7071 現已可供使用。 您也應該會看到 API 應用程式終端機中列出的 API。

    Functions:

        list: [POST,GET] http://localhost:7071/api/list

        sas: [POST,GET] http://localhost:7071/api/sas

        status: [GET] http://localhost:7071/api/status

  3. 選取底部窗格中的 [埠 ] 索引標籤，然後以滑鼠右鍵按一下 7071 埠，然後選取 [埠可見度 ]，然後選取 [ 公用 ]。

    如果您未將此應用程式公開為公用，當您從用戶端應用程式使用 API 時，就會收到錯誤。

  4. 若要測試 API 是否運作並聯機到儲存體，請在 底部窗格的 [埠 ] 索引標籤中，選取埠 7071 之 [本機位址 ] 區域中的地球圖示。 這會開啟函式應用程式的網頁瀏覽器。

  5. 將 API 路由新增至 URL 網址列： /api/sas?container=upload&file=test.png 。 檔案還不在容器中是可以的。 API 會根據您想要上傳的 SAS 權杖建立位置。

  6. JSON 回應看起來應該如下所示：

    {
    "url":"https://YOUR-STORAGE-RESOURCE.blob.core.windows.net/upload/test.png?sv=2023-01-03&spr=https&st=2023-07-26T22%3A15%3A59Z&se=2023-07-26T22%3A25%3A59Z&sr=b&sp=w&sig=j3Yc..."
}

  7. 複製瀏覽器網址列中 API URL 的基底（不是 JSON 物件中的 SAS 權杖 URL），以在下一個步驟中使用。 基底 URL 是 之前 /api/sas 的所有專案。

11.設定和執行用戶端應用程式

  1. 將檔案 ./azure-upload-file-to-storage/app/.env.sample 重新命名為 .env。

  2. 開啟 檔案， .env 並將上一節的基底 URL 貼上為 的值 VITE_API_SERVER 。

    Codespaces 環境的範例可能看起來像這樣 VITE_API_SERVER=https://improved-space-fishstick-pgvxvxjpqgrh6qxp-7071.app.github.dev

  3. 在其他分割終端機中，使用下列命令啟動用戶端應用程式：

    npm run dev

  4. 等候終端機傳回下列通知，指出應用程式可在埠 5173 上使用。

      VITE v4.4.4  ready in 410 ms

  ➜  Local:   https://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

  5. 選取底部窗格中的 [ 埠 ] 索引標籤， 然後以滑鼠右鍵按一下 5173 埠，然後選取地球圖示。

  6. 您應該會看到簡單的 Web 應用程式。

    Screenshot of web browser showing web app with Select File button available.

  7. 與 Web 應用程式互動：

    • 從本機電腦選取要上傳的映射檔 （*.jpg 或 *.png）。
    • 選取 [ 取得 SAS ] 按鈕，從 API 應用程式要求 SAS 權杖。 回應會顯示用來將檔案上傳至儲存體的完整 URL。
    • 選取 [ 上傳] 按鈕，將影像檔直接傳送至儲存體。

    Screenshot of web browser showing web app with the image file uploaded and a thumbnail of the file displayed.

  8. 用戶端應用程式和 API 應用程式已成功在容器化開發人員環境中一起運作。

12.認可程式碼變更

  1. 在 Visual Studio Code 中，開啟 [ 原始檔控制 ] 索引標籤。
  2. +選取圖示以暫存所有變更。 這些變更應該只包含本教學課程中 app 和 api 資料夾的新 package-lock.json 檔案。

13.將靜態 Web 應用程式部署至 Azure

Azure Functions 應用程式使用預覽功能，必須部署到 美國西部 2 才能正常運作。

  1. 在 Visual Studio Code 中，選取 [Azure 總管]。

  2. 在 Azure Explorer 中，以滑鼠右鍵按一下訂用帳戶名稱，然後選取 Create Resource... 。

  3. 從清單中選取 [建立靜態 Web 應用程式 ]。

  4. 請遵循使用下表的提示，瞭解如何建立靜態 Web 應用程式資源。

    屬性 值
    輸入新 Web 應用程式的全域唯一名稱。 針對您的儲存體資源名稱，輸入唯一的值，例如 fileuploadstor 。

    此唯一名稱是 下一節中使用的資源名稱 。 只使用字元和數位，長度最多 24 個字元。 您稍後需要此 帳戶名稱 才能使用。
    選取新資源的位置。 使用建議的位置。

  5. 請依照提示提供下列資訊：

    提示 Enter
    選取新資源的資源群組。 使用您為儲存體資源建立的資源群組。
    輸入新靜態 Web 應用程式的名稱。 接受預設名稱。
    選取 SKU 選取本教學課程的免費 SKU。 如果您的訂用帳戶中已經有免費的靜態 Web 應用程式資源，請選取下一個定價層。
    選擇 [建置預設] 來設定預設專案結構。 選取自訂。
    選取應用程式程式碼的位置 azure-upload-file-to-storage/app
    選取 Azure Functions 程式碼的位置 azure-upload-file-to-storage/api
    輸入組建輸出的路徑... dist

    這是從您的應用程式到靜態 （產生的） 檔案的路徑。
    選取新資源的位置。 選取接近您的區域。

  6. 程式完成時，會顯示通知快顯。 選取 [ 檢視/編輯工作流程 ]。

  7. 您的遠端分支有新的工作流程檔案，可用來部署至 Static Web Apps。 使用終端機中的下列命令，將該檔案向下提取到您的環境：

    git pull origin main

  8. 開啟位於 /.github/workflows/ 的工作流程檔案。

  9. 確認本教學課程靜態 Web 應用程式專屬工作流程的區段看起來應該像這樣：

    ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "/azure-upload-file-to-storage/app" # App source code path
api_location: "/azure-upload-file-to-storage/api" # Api source code path - optional
output_location: "dist" # Built app content directory - optional
###### End of Repository/Build Configurations ######

  10. 移至範例的 GitHub 分支， https://github.com/YOUR-ACCOUNT/azure-typescript-e2e-apps/actions 確認名為 Azure Static Web Apps CI/CD 的組建和部署動作已成功完成。 這可能需要幾分鐘的時間才能完成。

  11. 移至應用程式的Azure 入口網站，並檢視 設定 的 API 區段。 生產環境中的後端資源名稱 表示 (managed) 您的 API 已成功部署。

  12. 選取 [受控] 以查看應用程式中載入的 API 清單：

    • 清單
    • Sas
    • status

  13. 移至 [概觀] 頁面，以尋找 已部署應用程式的 URL 。

  14. 應用程式的部署已完成。

14.使用 儲存體 資源名稱和金鑰設定 API

在 API 正常運作之前，應用程式需要 Azure 儲存體 資源名稱和金鑰。

  1. 仍在 Azure 總管中，以滑鼠右鍵按兩下 靜態 Web 應用程式資源 ，然後選取 [在入口網站中開啟]。

  2. 在 [設定] 區段中選取 [組態]。

  3. 使用下表新增應用程式設定。

    屬性 數值 Description
    Azure_儲存體_AccountName Azure 儲存體 帳戶名稱，例如：fileuploadstor。 在原始碼中用來連線到 儲存體 資源。
    Azure_儲存體_AccountKey Azure 儲存體帳戶金鑰 在原始碼中用來連線到 儲存體 資源。

  4. 選取 [組態] 頁面上的 [儲存 ]，以儲存這兩個設定。

注意

您不需要設定用戶端應用程式的 env 變數 VITE_API_SERVER ，因為用戶端應用程式和 API 是從相同的網域裝載。

15.使用 Azure 部署的靜態 Web 應用程式

使用網站確認部署和設定成功。

  1. 在 Visual Studio Code 中，以滑鼠右鍵按兩下 Azure 總管中的靜態 Web 應用程式，然後選取 [ 瀏覽網站]。
  2. 在新的網頁瀏覽器視窗中，選取 [ 選擇檔案 ]，然後選取要上傳的影像檔 （*.png 或 *.jpg）。
  3. 選取 [ 取得 sas 令牌]。 此動作會將檔名傳遞至 API，並接收上傳檔案所需的 SAS 令牌 URL。
  4. 選取 [上傳檔案 ] 以使用 SAS 令牌 URL 來上傳檔案。 瀏覽器會顯示已上傳檔案的縮圖和URL。

16.清除資源

在 Visual Studio Code 中，使用資源群組的 Azure 總管，以滑鼠右鍵按兩下您的資源群組，然後選取 [ 刪除]。

這會刪除群組中的所有資源，包括您的 儲存體和靜態 Web 應用程式資源。

疑難排解

在下列 GitHub 存放庫中回報 此範例的問題 。 包含下列問題：

  • 發行項的 URL
  • 文章中有問題的步驟或內容
  • 您的開發環境

範例指令碼

相關內容

如果您要繼續進行此應用程式，請瞭解如何使用下列其中一個選項，將應用程式部署至 Azure 以進行裝載：