이 자습서에서는 @azure/storage-blob 패키지를 사용하여 정적 웹앱을 통해 Azure Storage Blob에 파일을 직접 업로드합니다. API는 전체 자격 증명을 노출하지 않고 제한된 액세스를 안전하게 위임할 수 있는 발레 키 패턴따라 SAS 토큰을 생성합니다.
주의
이 자습서에서는 소비 계획에서 함수 앱을 호스트하는 방법을 보여 줍니다. 관리 ID와 함께 Microsoft Entra ID를 사용하여 연결을 보호하려는 경우 대신 Flex Consumption 계획앱을 호스팅하는 것이 좋습니다. Flex Consumption 계층은 관리 ID와 가상 네트워크와의 통합을 지원하여 보안을 최적화합니다.
필수 구성 요소
- Azure 구독; Azure 구독이 아직 없는 경우 무료 Azure 계정등록할 수 있습니다.
- GitHub 계정을 사용하여 리포지토리를 포크하고 푸시하세요.
애플리케이션 아키텍처
이 애플리케이션 아키텍처에는 다음 두 가지 Azure 리소스가 포함됩니다.
- Azure Static Web Apps는 서비스가 API 리소스를 자동으로 관리하는 정적 클라이언트와 연결된 Azure Functions API를 모두 호스팅합니다.
- Blob Storage에 대한 Azure Storage입니다.
로컬 및 빌드 환경
이 자습서에서는 다음 환경을 사용합니다.
- GitHub Codespaces 또는 Visual Studio Code를 사용한 로컬 개발
- GitHub Actions를 사용하여 빌드 및 배포합니다.
GitHub를 사용하여 샘플 애플리케이션 리포지토리를 포크하기
이 자습서에서는 GitHub 작업을 사용하여 샘플 애플리케이션을 Azure에 배포합니다. 배포를 완료하려면 GitHub 계정과 샘플 애플리케이션 리포지토리의 포크가 필요합니다.
- 웹 브라우저에서 다음 링크를 사용하여 샘플 리포지토리의 고유한 계정에 대한 포크를 시작합니다. Azure-Samples/azure-typescript-e2e-apps.
- 기본 분기만 사용하여 샘플을 분기하는 단계를 완료합니다.
개발 환경 구성
개발 컨테이너 환경은 이 프로젝트의 모든 연습을 완료하는 데 필요한 모든 종속성에서 사용할 수 있습니다. GitHub Codespaces 또는 Visual Studio Code를 사용하여 로컬로 개발 컨테이너를 실행할 수 있습니다.
GitHub Codespaces는 GitHub에서 관리하는 개발 컨테이너를 실행하며, 사용자 인터페이스로 웹용 Visual Studio Code를 사용합니다. 가장 간단한 개발 환경의 경우 이 학습 모듈을 완료하기 위해 올바른 개발자 도구 및 종속성이 미리 설치되도록 GitHub Codespaces를 사용합니다.
중요하다
모든 GitHub 계정은 2개의 핵심 인스턴스를 사용하여 매월 최대 60시간 동안 Codespaces를 무료로 사용할 수 있습니다. 자세한 내용은 GitHub Codespaces 월별 포함된 스토리지 및 코어 시간참조하세요.
웹 브라우저의 샘플 리포지토리의 GitHub 포크에서
main단추를 선택하여 포크의 분기에 새 GitHub Codespace를 만드는 프로세스를 시작합니다.
Codespaces 탭에서 줄임표를 선택합니다
....줄임표 컨트롤이 강조 표시된 Codespaces 탭의 GitHub 스크린샷
+ 새로 만들기 옵션을 선택하여 특정 Codespaces 개발 컨테이너를 선택합니다.
다음 옵션을 선택한 다음, 코드스페이스만듭니다.
- 분기:
main - 개발 컨테이너 구성:
Tutorial: Upload file to storage with SAS Token - 지역: 기본값 적용
- 컴퓨터 유형: 기본값 적용
- 분기:
코드스페이스가 시작될 때까지 기다립니다. 이 시작 프로세스는 몇 분 정도 걸릴 수 있습니다.
코드스페이스에서 새 터미널을 엽니다.
팁
주 메뉴를 사용하여 터미널 메뉴 옵션으로 이동한 다음 새 터미널 옵션을 선택할 수 있습니다.
이 자습서에서 사용하는 도구의 버전을 확인합니다.
node --version npm --version func --version이 자습서에는 사용자 환경에 미리 설치된 각 도구의 다음 버전이 필요합니다.
도구 버전 Node.js ≥ 18 npm ≥ 9.5 Azure Functions 핵심 도구 ≥ 4.5098 터미널을 닫습니다.
이 자습서의 나머지 단계는 이 개발 컨테이너의 컨텍스트에서 수행합니다.
종속성 설치
이 자습서의 샘플 앱은 azure-upload-file-to-storage 폴더에 있습니다. 프로젝트의 다른 폴더는 사용할 필요가 없습니다.
Visual Studio Code에서 터미널을 열고 프로젝트 폴더로 이동합니다.
cd azure-upload-file-to-storage클라이언트 앱용과 API 앱용 터미널을 하나씩 두 개의 터미널이 있도록 터미널을 분할합니다.
터미널 중 하나에서 다음 명령을 실행하여 API 앱의 종속성을 설치하고 앱을 실행합니다.
cd api && npm install다른 터미널에서 명령을 실행하여 클라이언트 앱설치합니다.
cd app && npm install
Visual Studio 확장을 사용하여 스토리지 리소스 만들기
샘플 앱과 함께 사용할 Azure Storage 리소스를 만듭니다. 스토리지는 다음 용도로 사용됩니다.
- Azure Functions 앱의 트리거
- 블롭(파일) 저장소
Azure Storage 확장으로 이동합니다.
필요한 경우 Azure에 로그인합니다.
구독을 마우스 오른쪽 단추로 클릭한 다음
Create Resource...선택합니다.
목록에서 스토리지 계정 만들기을 선택합니다.
다음 표를 사용하여 프롬프트에 따라 Storage 리소스를 만드는 방법을 이해합니다.
재산 값 새 웹앱의 전역적으로 고유한 이름을 입력합니다. 스토리지 리소스 이름에 fileuploadstor같은 고유한 값을 입력합니다.
이 고유한 이름 은(는) 다음 섹션에서 사용되는 리소스 이름입니다. 최대 24자의 영숫자 길이를 사용합니다. 나중에 사용하려면 이 계정 이름 필요합니다.새 리소스의 위치를 선택합니다. 권장 위치를 사용합니다. 앱 만들기 프로세스가 완료되면 새 리소스에 대한 정보와 함께 알림이 나타납니다.
스토리지 CORS 구성
브라우저가 파일을 업로드하는 데 사용되므로 Azure Storage 계정은 원본 간 요청을 허용하도록 CORS를 구성해야 합니다. 이러한 CORS 설정은 단계를 간소화하기 위해 이 자습서에 사용되며 모범 사례 또는 보안을 나타내기 위한 것이 아닙니다. Azure Storage 대한CORS에 대해 자세히 알아봅니다.
Azure Storage 확장으로 이동합니다. 스토리지 리소스를 마우스 오른쪽 단추로 클릭하고 포털 열기를 선택합니다.
Azure Portal 스토리지 계정 설정 섹션에서 CORS(리소스 공유)선택합니다.
다음 속성을 사용하여 이 자습서의 CORS를 설정합니다.
- 허용된 출처:
* - 허용되는 메서드: 패치를 제외한 모든 메서드
- 허용되는 헤더:
* - 노출된 헤더:
* - 최대 연령: 86400
- 허용된 출처:
저장을 선택합니다.
스토리지에 대한 익명 액세스 권한 부여
파일을 업로드한 후 자습서 시나리오에서는 보기를 위해 Blob에 대한 공용 액세스 권한이 필요합니다. 간단히 하기 위해 이 가이드에서는 업로드된 파일에 익명으로 액세스할 수 있습니다.
- Azure Portal에서 공용 액세스를 사용하도록 설정하려면 스토리지 계정에 대한 개요 페이지를 선택하고 속성 섹션에서 Blob 익명 액세스 선택한 다음, 사용 안 함선택합니다.
- 구성 페이지에서 Blob 익명 액세스 허용을사용하도록 설정합니다.
업로드 컨테이너 만들기
공개적으로 읽을 수 있는 Blob이 있는 프라이빗 컨테이너를 만듭니다.
Azure Portal 스토리지 계정에 있는 동안 Data Storage 섹션에서 컨테이너선택합니다.
+ 컨테이너 선택하여 다음 설정을 사용하여
upload컨테이너를 만듭니다.- 이름:
upload - 공용 액세스 수준:
Blob
- 이름:
만들기선택합니다.
자신에게 Blob 데이터 액세스 권한 부여
리소스를 만드는 동안 컨테이너의 내용을 볼 수 있는 권한이 없습니다. 이 권한 부여는 특정 IAM 역할에 대해 예약됩니다. 컨테이너에서 Blob을 볼 수 있도록 계정을 추가합니다.
- Azure Portal 스토리지 계정에서 액세스 제어(IAM)를 선택합니다.
- 역할 할당추가를 선택합니다.
- Storage Blob 데이터 기여자을 검색한 후 선택합니다. 다음 선택합니다.
- 을 선택하고 멤버을 선택합니다.
- 계정을 검색하고 선택합니다.
- 리뷰를 선택하고할당하십시오.
- 컨테이너 선택한 다음, 컨테이너를 업로드합니다. 권한 부여 오류 없이 컨테이너에 Blob이 없는 것을 볼 수 있어야 합니다.
Storage 리소스 자격 증명 가져오기
Storage 리소스 자격 증명은 Azure Functions API 앱에서 스토리지 리소스에 연결하는 데 사용됩니다.
Azure Portal에 있는 동안 보안 + 네트워킹 섹션에서 액세스 키 선택합니다.
Key키를 복사합니다.Visual Studio Code에서
./workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/api폴더 내의 파일을 에서local.settings.json.sample로local.settings.json이름을 바꾸세요. 파일이 Git에서 무시되므로 소스 제어에 체크 인되지 않습니다.다음 표를 사용하여
local.settings.json설정을 업데이트합니다.재산 값 묘사 Azure_저장소_계정이름 Azure Storage 계정 이름(예: fileuploadstor.소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다. Azure_Storage_계정키 Azure Storage 계정 키 소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다. AzureWebJobs스토리지 Azure Storage 계정 연결 문자열 Azure Functions 런타임에서 상태 및 로그를 저장하는 데 사용합니다.
동일한 계정 자격 증명을 키로 한 번, 연결 문자열로 한 번 입력한 것처럼 보일 수 있습니다. 당신은 그렇게 했지만, 이 간단한 자습서를 위해 특별히 그렇게 했습니다. 일반적으로 Azure Functions 앱에는 다른 용도로 다시 사용되지 않는 별도의 Storage 리소스가 있어야 합니다. 자습서의 뒷부분에서 Azure Function 리소스를 만들 때 클라우드 리소스에 대한 AzureWebJobsStorage 값을 설정할 필요가 없습니다. 소스 코드에서 사용되는 Azure_Storage_AccountName 및 Azure_Storage_AccountKey 값을 설정해야 합니다.
API 앱 실행
Functions 앱을 실행하여 Azure에 배포하기 전에 올바르게 작동하는지 확인합니다.
API 앱의 터미널에서 다음 명령을 실행하여 API 앱을 시작합니다.
npm run startAzure 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아래쪽 창에서 포트 탭을 선택한 다음 7071 포트를 마우스 오른쪽 단추로 클릭하고 포트 표시 유형 선택한 다음 공용선택합니다.
이 앱을 퍼블릭으로 노출하지 않으면 클라이언트 앱에서 API를 사용할 때 오류가 발생합니다.
API가 작동하고 스토리지에 연결하는지 테스트하려면 아래쪽 창의 포트 탭에서 포트 7071의 로컬 주소 영역에서 지구본 아이콘을 선택합니다. 그러면 함수 앱에 대한 웹 브라우저가 열립니다.
URL 주소 표시줄에 API 경로를 추가합니다.
/api/sas?container=upload&file=test.png. 파일이 아직 컨테이너에 없는 것은 괜찮습니다. API는 업로드할 위치에 따라 SAS 토큰을 만듭니다.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..." }다음 단계에서 사용할 브라우저 주소 표시줄(JSON 개체의 SAS 토큰 URL 아님)에서 API URL의 기본을 복사합니다. 기본 URL은
/api/sas전의 모든 항목입니다. 이 기본 URL을 다음 섹션의 클라이언트 앱 환경 변수 파일에 붙여넣습니다.
클라이언트 앱 구성 및 실행
./azure-upload-file-to-storage/app/.env.sample파일의 이름을.env로 변경하세요..env파일을 열고 이전 섹션의 기본 URL을VITE_API_SERVER값으로 붙여넣습니다.예를 들어 Codespaces 환경은
VITE_API_SERVER=https://improved-space-fishstick-pgvxvxjpqgrh6qxp-7071.app.github.dev과 비슷할 수 있습니다.다른 분할 터미널에서 다음 명령을 사용하여 클라이언트 앱을 시작합니다.
npm run dev터미널에서 포트 5173앱을 사용할 수 있다는 다음 알림이 반환될 때까지 기다립니다.
VITE v4.4.4 ready in 410 ms ➜ Local: https://localhost:5173/ ➜ Network: use --host to expose ➜ press h to show help아래쪽 창에서 포트 탭을 선택한 다음 5173 포트를 마우스 오른쪽 단추로 클릭하고 지구본 아이콘을 선택합니다.
웹앱을 확인해야 합니다.
웹앱과 상호 작용:
- 업로드할 로컬 컴퓨터에서 이미지 파일(*.jpg 또는 *.png)을 선택합니다.
- SAS 가져오기 단추를 선택하여 API 앱에서 SAS 토큰을 요청합니다. 응답은 스토리지에 파일을 업로드하는 데 사용할 전체 URL을 보여 줍니다.
- 업로드 단추를 선택하여 이미지 파일을 Storage로 직접 보냅니다.
클라이언트 앱과 API 앱은 컨테이너화된 개발자 환경에서 함께 작동했습니다.
코드 변경 내용 커밋
- Visual Studio Code에서 소스 제어 탭을 엽니다.
-
+ 아이콘을 선택하여 모든 변경 내용을 준비합니다. 이러한 변경 내용은 이 자습서의
app및api폴더에 대한 새 package-lock.json 파일만 포함해야 합니다.
Azure에 정적 웹앱 배포
Azure Functions 앱은 미리 보기 기능을 사용하고 있습니다. 제대로 작동하려면 미국 서부 2 에 배포해야 합니다.
Visual Studio Code에서 Azure 탐색기를 선택합니다.
Azure 탐색기에서 구독 이름을 마우스 오른쪽 단추로 클릭한 다음
Create Resource...선택합니다.목록에서 정적 웹 앱 만들기을 선택합니다.
다음 표를 사용하여 프롬프트에 따라 정적 웹앱 리소스를 만드는 방법을 이해합니다.
재산 값 새 웹앱의 전역적으로 고유한 이름을 입력합니다. 스토리지 리소스 이름에 fileuploadstor같은 고유한 값을 입력합니다.
이 고유한 이름 은(는) 다음 섹션에서 사용되는 리소스 이름입니다. 최대 24개의 문자와 숫자만 사용합니다. 나중에 사용하려면 이 계정 이름 필요합니다.새 리소스의 위치를 선택합니다. 권장 위치를 사용합니다. 프롬프트에 따라 다음 정보를 제공합니다.
프롬프트 입력하세요 새 리소스에 대한 리소스 그룹을 선택합니다. 스토리지 리소스에 대해 만든 리소스 그룹을 사용합니다. 새 정적 웹앱의 이름을 입력합니다. 기본 이름을 적용합니다. SKU를 선택 이 자습서의 무료 SKU를 선택합니다. 구독에 무료 Static Web App 리소스가 이미 있는 경우 다음 가격 책정 계층을 선택합니다. 빌드 사전 설정을 선택하여 기본 프로젝트 구조를 구성합니다. 사용자 지정선택합니다. 애플리케이션 코드의 위치를 선택하세요 azure-upload-file-to-storage/appAzure Functions 코드의 위치 선택 azure-upload-file-to-storage/api빌드 출력의 경로를 입력합니다. dist
값은 앱에서 정적(생성된) 파일로의 경로입니다.새 리소스의 위치를 선택합니다. 가까운 지역을 선택합니다. 프로세스가 완료되면 알림 팝업이 표시됩니다. 보기/편집 워크플로을 선택합니다.
원격 포크에는 Static Web Apps에 배포하기 위한 새 워크플로 파일이 있습니다. 터미널에서 다음 명령을 사용하여 해당 파일을 사용자 환경으로 끌어오세요.
git pull origin main/.github/workflows/있는 워크플로 파일을 엽니다.이 자습서의 정적 웹앱과 관련된 워크플로 섹션이 다음과 같은지 확인합니다.
###### 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 ######샘플의 GitHub 포크로 이동하여
https://github.com/<YOUR-ACCOUNT>/azure-typescript-e2e-apps/actions빌드 및 배포 작업(Azure Static Web Apps CI/CD)이 성공적으로 완료되었는지 확인합니다. 이 작업을 완료하는 데 몇 분 정도 걸릴 수 있습니다.앱에 대한 Azure Portal로 이동하여 설정API 섹션을 봅니다. 프로덕션 환경에서 백엔드 리소스 이름은 API가 성공적으로 배포되었음을 나타내는
(managed)입니다.(관리) 선택하여 앱에 로드된 API 목록을 확인합니다.
- 목록
- SAS는
- 상태
개요 페이지로 이동하여 배포된 앱의 URL을 찾으세요.
앱 배포가 완료되었습니다.
Storage 리소스 이름 및 키를 사용하여 API 구성
API가 제대로 작동하려면 앱에 Azure Storage 리소스 이름 및 키가 필요합니다. Azure Static Web Apps에 배포된 경우 클라이언트 앱과 API는 동일한 도메인에서 호스트되어 클라이언트 앱의 환경 변수를 VITE_API_SERVER 설정할 필요가 없습니다.
Azure 탐색기 내에서 Static Web App 리소스 마우스 오른쪽 버튼으로 클릭하고 포털에서 열기 를 선택합니다.
설정 섹션에서 구성 선택합니다.
다음 표를 사용하여 애플리케이션 설정을 추가합니다.
재산 값 묘사 Azure_저장소_계정이름 Azure Storage 계정 이름(예: fileuploadstor.소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다. Azure_Storage_계정키 Azure Storage 계정 키 소스 코드에서 스토리지 리소스에 연결하는 데 사용됩니다. 구성 페이지에서 저장을 선택하여 두 설정을 모두 저장합니다.
Azure에서 배포한 정적 웹앱 사용
웹 사이트를 사용하여 배포 및 구성이 성공했는지 확인합니다.
- Visual Studio Code에서, Azure 탐색기에서 정적 웹 앱을 오른쪽 클릭하고 사이트 찾아보기를 선택합니다.
- 새 웹 브라우저 창에서 파일 선택한 다음 업로드할 이미지 파일(*.png 또는 *.jpg)을 선택합니다.
- 선택 sas 토큰가져오기 이 작업은 파일 이름을 API에 전달하고 파일을 업로드하는 데 필요한 SAS 토큰 URL을 받습니다.
- 파일 업로드을 선택하여 SAS 토큰 URL을 사용하여 파일을 업로드합니다. 브라우저에 업로드된 파일의 썸네일 및 URL이 표시됩니다.
리소스 정리
Visual Studio Code에서 리소스 그룹에 대한 Azure 탐색기를 사용합니다. 리소스 그룹을 마우스 오른쪽 단추로 클릭한 다음 삭제를 선택합니다.
이 작업은 스토리지 및 정적 웹앱 리소스를 포함하여 그룹의 모든 리소스를 삭제합니다.
문제 해결
GitHub 리포지토리에서 이 샘플과 관련된 문제를 보고합니다. 문제에 다음을 포함합니다.
- 문서의 URL
- 문제가 있는 문서 내의 단계 또는 컨텍스트
- 개발 환경
샘플 코드
관련 콘텐츠
- Azure Blob Storage 설명서
- @azure/storage-blob
- Azure Static Web App