Azure Static Web Apps(미리 보기)를 사용하여 데이터베이스에 연결

아티클
02/28/2024

Azure Static Web Apps 데이터베이스 연결 기능을 사용하면 사용자 지정 서버 쪽 코드를 작성하지 않고도 Static Web Apps에서 데이터베이스에 액세스할 수 있습니다.

웹 애플리케이션과 데이터베이스 간의 연결을 만들면 CRUD 작업, 기본 제공 권한 부여 및 관계를 완벽하게 지원하여 데이터를 조작할 수 있습니다.

Data API 빌더를 기반으로 하는 Azure Static Web Apps는 REST 및 GraphQL 요청을 받아 데이터베이스 쿼리로 변환합니다.

데이터베이스 연결에서 지원하는 기능은 다음과 같습니다.

기능	설명
통합 보안	Azure Static Web Apps 인증 및 권한 부여 보안 모델과 기본 제공 통합. 경로를 보호하는 데 사용되는 것과 동일한 역할 기반 보안을 API 엔드포인트에 사용할 수 있습니다.
전체 CRUD 기반 작업	애플리케이션에서 데이터를 조작하는 방법에 대한 예는 Azure Cosmos DB, Azure SQL, MySQL 또는 PostgreSQL에 대한 자습서를 참조하세요.
SQL 및 NoSQL 지원	관계형 및 문서 데이터베이스를 애플리케이션의 데이터베이스로 사용할 수 있습니다.
서버를 사용하지 않는 아키텍처	연결은 0에서 1 작업자까지 확장됩니다(미리 보기 중).
데이터베이스 관계	GraphQL 엔드포인트를 통해서만 지원됩니다.
CLI 지원	Static Web Apps CLI를 사용하여 로컬에서 개발합니다. `--data-api-location` 옵션을 사용하여 클라우드에서 처리되는 것처럼 개발 중인 데이터 API에 대한 요청을 처리합니다.

지원되는 데이터베이스

다음 표는 다양한 관계형 및 NoSQL 데이터베이스에 대한 지원을 보여 줍니다.

이름	형식	설명	REST	GraphQL
Azure Cosmos DB	Standard	NoSQL 및 모든 규모의 관계형 데이터베이스를 위한 전역적으로 분산 데이터베이스 플랫폼입니다. GraphQL 엔드포인트에는 표준 구성 외에도 `gql`스키마 파일이 필요합니다.		✔
Azure SQL	Standard	Azure 클라우드에서 SQL Server 데이터베이스 엔진을 사용하는 관리, 보안 및 지능형 제품 제품군입니다.	✔	✔
Azure Database for MySQL	Flex	MySQL Community Edition을 기반으로 하는 Microsoft 클라우드의 관계형 데이터베이스 서비스	✔	✔
Azure Database for PostgreSQL	Flex	예측 가능한 성능과 동적 확장성으로 중요 업무용 워크로드를 처리하는 완전 관리형 PostgreSQL Database-as-a-Service입니다.	✔	✔
Azure Database for PostgreSQL(단일 서버)	단일	완전 관리형 PostgreSQL 데이터베이스입니다.	✔	✔

데이터베이스 액세스에 다음 연결 형식을 사용할 수 있습니다.

Connection string
사용자가 할당한 관리 ID
시스템이 할당한 관리 ID

엔드포인트 위치

데이터 엔드포인트에 대한 액세스는 /data-api 경로에서 사용할 수 있습니다.

다음 표는 요청이 정적 웹앱의 다른 파트로 라우팅되는 방법을 보여 줍니다.

Path	설명
`example.com/api/*`	API 함수
`example.com/data-api/*`	REST 및 GraphQL 요청을 지원하는 데이터베이스 연결 엔드포인트입니다.
`example.com/*`	정적 콘텐츠

웹 사이트에서 데이터베이스 연결을 구성할 때 /data-api/* 경로의 REST 또는 GraphQL 접미사를 구성할 수 있습니다. /data-api 접두사는 Static Web Apps의 규칙이며 변경할 수 없습니다.

구성

Static Web Apps에서 데이터베이스 연결을 구성하는 데는 두 단계가 있습니다. Azure Portal에서 데이터베이스를 정적 웹앱에 연결하고 데이터베이스 연결 구성 파일을 업데이트해야 합니다.

자세한 내용은 Azure Static Web Apps의 데이터베이스 연결 구성을 참조하세요.

로컬 개발

Azure SWA CLI(Static Web Apps CLI)에는 로컬 개발 중 데이터베이스 연결 작업에 대한 지원이 포함되어 있습니다.

CLI는 로컬 /data-api 엔드포인트를 활성화하고 포트 4280의 요청을 데이터베이스 액세스를 위한 적절한 포트로 프록시합니다.

다음은 데이터베이스 연결로 SWA CLI를 시작하는 명령 예입니다.

swa start ./src --data-api-location swa-db-connections

이 명령은 src 디렉터리에서 SWA CLI를 시작합니다. --data-api-location 옵션은 CLI에 swa-db-connections라는 폴더에 staticwebapp.database.config.json 파일이 있음을 알려 줍니다.

참고 항목

개발 시 연결 문자열을 사용하여 인증하는 경우 env() 함수를 사용하여 환경 변수에서 연결 문자열을 읽습니다. env 함수에 전달된 문자열은 따옴표로 묶어야 합니다.

역할 기반 보안

staticwebapp.database.config.json 파일에서 항목을 정의할 때 항목 엔드포인트에 액세스하는 데 필요한 역할 목록을 지정할 수 있습니다.

다음 구성 조각에는 주문 엔터티의 모든 작업(create, read, update, delete)에 액세스하려면 관리자 역할이 필요합니다.

{
...
"entities": { 
  "Orders": { 
    "source": "dbo.Orders", 
    "permissions": [ 
      { 
        "actions": ["*"], 
        "role": "admin" 
      }
    ]
 }
}
...
}

역할이 필요한 엔드포인트를 호출할 때 다음 조건이 필요합니다.

현재 사용자는 인증을 받아야 합니다.
현재 사용자는 필수 역할의 멤버여야 합니다.
REST 또는 GraphQL 요청에는 키가 X-MS-API-ROLE인 헤더와 엔터티 구성 규칙에 나열된 것과 일치하는 역할 이름 값이 포함되어야 합니다.

예를 들어, 다음 코드 조각은 요청 헤더에서 관리자 역할을 전달하는 방법을 보여 줍니다.
```
{
  method: "POST",
  headers: { 
    "Content-Type": "application/json",
    "X-MS-API-ROLE": "admin"
  },
  body: JSON.stringify(requestPayload)
}
```

제약 조건

데이터베이스는 Azure의 인프라에서 액세스할 수 있어야 합니다.
공개 미리 보기 동안 데이터베이스 연결은 0에서 1 데이터베이스 작업자로 확장됩니다.

다음 단계

데이터베이스 구성

다음을 통해 공유