Share via

JavaScript를 사용하여 Azure Storage Blob에 이미지 업로드

  • 아티클

정적 웹앱을 사용하여 Azure Storage SAS 토큰과 함께 Azure Storage @azure/storage-blob npm 패키지를 사용하여 Azure Storage Blob 에 파일을 업로드합니다.

필수 조건

애플리케이션 아키텍처

이 애플리케이션 아키텍처에는 다음 두 가지 Azure 리소스가 포함됩니다.

  • 정적으로 생성된 클라이언트 애플리케이션에 대한 Azure Static Web Apps입니다. 또한 리소스는 관리되는 Azure Functions API를 제공합니다. 관리된다는 것은 Static Web Apps 리소스가 자체적으로 사용하기 위해 API 리소스를 관리한다는 것을 의미합니다.
  • Blob Storage에 대한 Azure Storage입니다.

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

단계 Description
1 고객은 정적으로 생성된 웹 사이트에 연결합니다. 웹 사이트는 Azure Static Web Apps에서 호스트됩니다.
2 고객은 해당 웹 사이트를 사용하여 업로드할 파일을 선택합니다. 이 자습서의 경우 프런트 엔드 프레임워크는 Vite React이고 업로드된 파일은 이미지 파일입니다.
3 웹 사이트는 Azure Functions API sas 를 호출하여 업로드할 파일의 정확한 파일 이름을 기반으로 SAS 토큰을 가져옵니다. 서버리스 API는 Azure Blob Storage SDK를 사용하여 SAS 토큰을 만듭니다. API는 SAS 토큰을 쿼리 문자열로 포함하는 파일을 업로드하는 데 사용할 전체 URL을 반환합니다.
https://YOUR-STORAGE-NAME.blob.core.windows.net/YOUR-CONTAINER/YOUR-FILE-NAME?YOUR-SAS-TOKEN
4 프런트 엔드 웹 사이트는 SAS 토큰 URL을 사용하여 Azure Blob Storage에 파일을 직접 업로드합니다.

로컬 및 빌드 환경

이 자습서에서는 다음 환경을 사용합니다.

  • 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 계정은 2개의 코어 인스턴스를 사용하여 매월 최대 60시간 동안 Codespaces를 무료로 사용할 수 있습니다. 자세한 내용은 GitHub Codespaces 월별 포함 스토리지 및 코어 시간을 참조하세요.

  1. 웹 브라우저의 샘플 리포지토리의 GitHub 포크에서 CODE 단추를 선택하여 포크 분기에 새 GitHub Codespace main 를 만드는 프로세스를 시작합니다.

    GitHub screenshot of Code Spaces buttons for a repository.

  2. 코드 영역 탭에서 줄임표를 ...선택합니다.

    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 확장을 사용하여 스토리지 리소스 만들기

샘플 앱과 함께 사용할 Storage 리소스를 만듭니다. 스토리지는 다음 용도로 사용됩니다.

  • Azure Functions 앱의 트리거
  • Blob(파일) 스토리지

  1. Azure Storage 확장으로 이동합니다.

  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. 다음 표를 사용하여 프롬프트에 따라 Storage 리소스를 만드는 방법을 이해합니다.

    속성 값
    새 웹앱에 대한 전역 고유 이름을 입력합니다. 스토리지 리소스 이름에 고유한 값(예: 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 Storage 계정은 원본 간 요청을 허용하도록 CORS를 구성해야 합니다.

  1. Azure Storage 확장으로 이동합니다. 스토리지 리소스를 마우스 오른쪽 단추로 클릭하고 포털에서 열기를 선택합니다.

  2. Azure Portal 스토리지 계정 설정 섹션에서 CORS(리소스 공유)를 선택합니다.

  3. 다음 속성을 사용하여 이 자습서의 CORS를 설정합니다.

    • 허용된 원본: *
    • 허용되는 메서드: 패치를 제외한 모든 메서드
    • 허용되는 헤더: *
    • 노출된 헤더: *
    • 최대 연령: 86400

    이러한 설정은 이 자습서에서 단계를 간소화하는 데 사용되며 모범 사례 또는 보안을 나타내기 위한 것이 아닙니다. Azure Storage용 CORS에 대해 자세히 알아봅니다.

  4. 저장을 선택합니다.

6. 스토리지에 익명 액세스 권한 부여

시간 제한 및 권한 제한 SAS 토큰을 만들 때 파일 업로드는 클라이언트에서 보호됩니다. 그러나 파일이 업로드되면 이 자습서 시나리오에서는 누구나 볼 수 있습니다. 이렇게 하려면 공개적으로 액세스할 수 있도록 스토리지 권한을 변경해야 합니다.

계정에 공개적으로 액세스할 수 있더라도 각 컨테이너와 각 Blob은 프라이빗 액세스를 가질 수 있습니다. 이 자습서에서는 더 안전한 방법이지만 너무 복잡하기 때문에 SAS 토큰을 사용하여 하나의 스토리지 계정에 업로드한 다음, 공용 액세스 권한이 있는 다른 스토리지 계정으로 Blob을 이동합니다.

  1. Azure Portal에서 공용 액세스를 사용하도록 설정하려면 스토리지 계정에 대한 개요 페이지를 선택하고 속성 섹션에서 Blob 익명 액세스를 선택한 다음 사용 안 함으로 선택합니다.
  2. 구성 페이지에서 Blob 익명 액세스 허용을 사용하도록 설정합니다.

7. 업로드 컨테이너 만들기

  1. Azure Portal 스토리지 계정에 있는 동안 데이터 스토리지 섹션에서 컨테이너를 선택합니다.

  2. + 컨테이너를 선택하여 다음 설정을 사용하여 컨테이너를 만듭니 upload 다.

    • 이름: upload
    • 공용 액세스 수준: Blob

  3. 만들기를 실행합니다.

8. 자신에게 Blob 데이터 액세스 권한 부여

리소스를 만드는 동안 컨테이너의 내용을 볼 수 있는 권한이 없습니다. 이는 특정 IAM 역할에 예약되어 있습니다. 컨테이너에서 Blob을 볼 수 있도록 계정을 추가합니다.

  1. Azure Portal 스토리지 계정에서 IAM(Access Control)을 선택합니다.
  2. 역할 할당 추가를 선택합니다.
  3. Storage Blob 데이터 참가자를 검색하고 선택합니다. 다음을 선택합니다.
  4. + 구성원 선택을 선택합니다.
  5. 계정을 검색하고 선택합니다.
  6. 검토 + 할당을 선택합니다.
  7. 컨테이너를 선택한 다음, 컨테이너 업로드를 선택합니다. 권한 부여 오류 없이 컨테이너에 Blob이 없는 것을 볼 수 있어야 합니다.

9. 스토리지 리소스 자격 증명 가져오기

Storage 리소스 자격 증명은 Azure Functions API 앱에서 스토리지 리소스에 연결하는 데 사용됩니다.

  1. Azure Portal에 있는 동안 보안 + 네트워킹 섹션에서 액세스 키를 선택합니다.

  2. API 파일은 .에서 찾을 수 있습니다../workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/api

  3. API 폴더에서 파일 이름을 .로 local.settings.json.samplelocal.settings.json바꿉니다. 파일이 Git에서 무시되므로 소스 제어에 검사 않습니다.

  4. 다음 표를 사용하기 위한 local.settings.json 설정을 업데이트합니다.

    속성 값 설명
    Azure_Storage_AccountName Azure Storage 계정 이름(예: fileuploadstor. 소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다.
    Azure_Storage_AccountKey Azure Storage 계정 키 소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다.
    AzureWebJobsStorage Azure Storage 계정 연결 문자열 Azure Functions 런타임에서 상태 및 로그를 저장하는 데 사용합니다.

동일한 계정 자격 증명을 키로 한 번, 연결 문자열 한 번 입력한 것처럼 보일 수 있습니다. 이 간단한 자습서를 위해 특별히 수행했습니다. 일반적으로 Azure Functions 앱에는 다른 용도로 다시 사용되지 않는 별도의 Storage 리소스가 있어야 합니다. 자습서의 뒷부분에서 Azure Function 리소스를 만들 때 클라우드 리소스에 대한 AzureWebJobsStorage 값을 설정할 필요가 없습니다. 소스 코드에서 사용되는 Azure_Storage_AccountName 및 Azure_Storage_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. URL 주소 표시줄에 API 경로를 추가합니다 /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. 다음 단계에서 사용할 브라우저 주소 표시줄(JSON 개체의 SAS 토큰 URL 아님)에서 API 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. 간단한 웹앱이 표시됩니다.

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

  7. 웹앱과 상호 작용:

    • 업로드할 로컬 컴퓨터에서 이미지 파일(*.jpg 또는 *.png)을 선택합니다.
    • SAS 가져오기 단추를 선택하여 API 앱에서 SAS 토큰을 요청합니다. 응답은 스토리지에 파일을 업로드하는 데 사용할 전체 URL을 보여 줍니다.
    • 업로드 단추를 선택하여 이미지 파일을 Storage로 직접 보냅니다.

    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. 아이콘을 + 선택하여 모든 변경 내용을 스테이징합니다. 이러한 변경 내용은 이 자습서의 폴더 및 api 폴더에 대한 app 새 package-lock.json 파일만 포함해야 합니다.

13. Azure에 정적 웹앱 배포

Azure Functions 앱은 미리 보기 기능을 사용하고 있으며 제대로 작동하려면 미국 서부 2 에 배포해야 합니다.

  1. Visual Studio Code에서 Azure 탐색기를 선택합니다.

  2. Azure 탐색기에서 구독 이름을 마우스 오른쪽 단추로 클릭한 다음 Create Resource...선택합니다.

  3. 목록에서 정적 웹앱 만들기를 선택합니다.

  4. 다음 표를 사용하여 프롬프트에 따라 정적 웹앱 리소스를 만드는 방법을 이해합니다.

    속성 값
    새 웹앱에 대한 전역 고유 이름을 입력합니다. 스토리지 리소스 이름에 고유한 값(예: fileuploadstor)을 입력합니다.

    이 고유한 이름은 다음 섹션에서 사용되는 리소스 이름입니다. 최대 24개의 문자와 숫자만 사용합니다. 나중에 사용하려면 이 계정 이름이 필요합니다.
    새 리소스의 위치 선택 권장 위치를 사용합니다.

  5. 프롬프트에 따라 다음 정보를 제공합니다.

    프롬프트 Enter
    새 리소스에 대한 리소스 그룹을 선택합니다. 스토리지 리소스에 대해 만든 리소스 그룹을 사용합니다.
    새 정적 웹앱의 이름을 입력하세요. 기본 이름을 적용합니다.
    SKU 선택 이 자습서에서는 무료 SKU를 선택합니다. 구독에 무료 Static Web App 리소스가 이미 있는 경우 다음 가격 책정 계층을 선택합니다.
    빌드 사전 설정을 선택하여 기본 프로젝트 구조를 구성합니다. 사용자 지정을 선택합니다.
    애플리케이션 코드의 위치 선택 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. 이 자습서의 정적 웹앱과 관련된 워크플로의 섹션이 다음과 같은지 확인합니다.

    ###### 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. 샘플 https://github.com/YOUR-ACCOUNT/azure-typescript-e2e-apps/actions 의 GitHub 포크로 이동하여 빌드 및 배포 작업(명명됨 Azure Static Web Apps CI/CD)이 성공적으로 완료되었는지 확인합니다. 완료하는 데 몇 분 정도 걸릴 수 있습니다.

  11. 앱에 대한 Azure Portal로 이동하여 설정 API 섹션을 봅니다. 프로덕션 환경 (managed) 의 백 엔드 리소스 이름은 API가 성공적으로 배포되었음을 나타냅니다.

  12. (관리됨)을 선택하여 앱에 로드된 API 목록을 확인합니다.

    • list
    • Sas
    • status

  13. 개요 페이지로 이동하여 배포된 앱의 URL 을 찾습니다.

  14. 앱 배포가 완료되었습니다.

14. Storage 리소스 이름 및 키를 사용하여 API 구성

API가 제대로 작동하려면 앱에 Azure Storage 리소스 이름 및 키가 필요합니다.

  1. Azure 탐색기에서 정적 웹앱 리소스를 마우스 오른쪽 단추로 클릭하고 포털에서 열기를 선택합니다.

  2. 설정 섹션에서 구성을 선택합니다.

  3. 다음 표를 사용하여 애플리케이션 설정을 추가합니다.

    속성 값 설명
    Azure_Storage_AccountName Azure Storage 계정 이름(예: fileuploadstor. 소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다.
    Azure_Storage_AccountKey Azure Storage 계정 키 소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다.

  4. 구성 페이지에서 저장을 선택하여 두 설정을 모두 저장합니다.

참고 항목

클라이언트 앱과 API가 동일한 작업에서 호스트되므로 클라이언트 앱의 env 변수 VITE_API_SERVER 설정할 필요가 없습니다기본.

15. Azure에서 배포한 정적 웹앱 사용

웹 사이트를 사용하여 배포 및 구성이 성공했는지 확인합니다.

  1. Visual Studio Code에서 Azure 탐색기에서 정적 웹앱을 마우스 오른쪽 단추로 클릭하고 사이트 찾아보기를 선택합니다.
  2. 새 웹 브라우저 창에서 파일 선택을 선택한 다음 업로드할 이미지 파일(*.png 또는 *.jpg)을 선택합니다.
  3. sas 토큰 가져오기를 선택합니다. 이 작업은 파일 이름을 API에 전달하고 파일을 업로드하는 데 필요한 SAS 토큰 URL을 받습니다.
  4. SAS 토큰 URL을 사용하여 파일을 업로드하려면 파일 업로드를 선택합니다. 브라우저에 업로드된 파일의 썸네일 및 URL이 표시됩니다.

16. 리소스 정리

Visual Studio Code에서 리소스 그룹에 대한 Azure 탐색기를 사용하고 리소스 그룹을 마우스 오른쪽 단추로 클릭한 다음 삭제를 선택합니다.

그러면 스토리지 및 정적 웹앱 리소스를 포함하여 그룹의 모든 리소스가 삭제됩니다.

문제 해결

아래에 설명된 GitHub 리포지토리에서 이 샘플과 관련된 문제를 보고합니다. 문제에 다음을 포함합니다.

  • 문서의 URL
  • 문제가 있는 문서 내의 단계 또는 컨텍스트
  • 개발 환경

샘플 코드

관련 콘텐츠

이 앱을 계속 사용하려면 다음 선택 항목 중 하나를 사용하여 호스팅을 위해 Azure에 앱을 배포하는 방법을 알아봅니다.