Azure Static Web Apps 中的資料庫聯機組態（預覽）

Azure 靜態 Web 應用程式資料庫連線可搭配各種 Azure 資料庫使用。

當您將資料庫連線到靜態 Web 應用程式時，您需要設定資料庫的防火牆，允許來自 Azure 資源的網路存取，以接受來自 Static Web Apps 背景工作角色的網路連線。不支援允許特定的靜態 Web Apps IP 位址。

如果您使用受控識別驗證類型，則必須設定靜態 Web 應用程式的受控識別配置檔來存取您的資料庫。

如需資料庫防火牆和受控身分識別設定的詳細數據，請使用下表。

名稱	類型	防火牆	受控識別
Azure Cosmos DB	標準	設定防火牆	設定受控識別
Azure SQL	標準	設定防火牆	設定受控識別
適用於 MySQL 的 Azure 資料庫	Flex	設定防火牆	不支援
適用於 PostgreSQL 的 Azure 資料庫	Flex	設定防火牆	不支援
適用於 PostgreSQL 的 Azure 資料庫（單一）	單身	設定防火牆	設定受控識別

組態

您會在staticwebapp.database.config.json檔案中定義資料庫連結的執行階段行為。將資料庫連結至靜態 Web 應用程式之前，您必須在存放庫內建立此檔案。依照慣例，此檔案存在於存放庫根目錄的 swa-db-connections 資料夾中，但您可以視需要重新放置它。

組態檔的目的是：

將/data-api端點上的路徑對應到您的資料庫資料表或實體
公開 REST 或 GraphQL 端點（或兩者）
定義實體安全性規則
控制開發設定組態設定

如果您使用 Azure Cosmos DB 搭配 GraphQL，您也需要提供 gql 結構描述檔案。

注意

靜態 Web Apps 資料庫連線需要包含組態檔的資料夾。此資料夾必須包含適用於所有資料庫類型的 staticwebapp.database.config.json 組態檔。針對 NoSQL 資料庫的 Cosmos DB，也需要 staticwebapp.database.schema.gql 架構檔案。

依照慣例，此資料夾名為 swa-db-connections ，並放在存放庫的根目錄。您可以使用 custom-configuration-folder 覆寫此慣例。

範例組態檔

下列範例組態檔示範如何連線到 Azure SQL 資料庫，並公開 REST 和 GraphQL 端點。如需組態檔及其支援功能的完整詳細資訊，請參閱 Data API Builder 文件。

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": false 
    },
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/rest"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "mode": "production",
      "cors": {
        "origins": ["http://localhost:4280"],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      }
    }
  },
  "entities": {
    "Person": {
      "source": "dbo.MyTestPersonTable",
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete"],
          "role": "anonymous"
        }
      ]
    }
  }
}

屬性	說明
`$schema`	Azure Static Web Apps 用來解譯組態檔時所使用的 Database API builder 版本。
`data-source`	目標資料庫特定的組態設定。屬性 `database-type` 接受 `mssql`、 `postgresql`、 `cosmosdb_nosql`或 `mysql`。當資料庫已連線到您的靜態 Web Apps 資源時，會在部署時覆寫連接字串。在本機開發期間，組態檔中定義的連接字串是用來連線到資料庫的內容。
`runtime`	定義公開端點的區段。 `rest`和 `graphql` 屬性會控制用來存取個別 API 通訊協定的 URL 片段。 `host` 設定區段會定義開發環境特定的設定。請確定 `origins` 陣列包含您的 localhost 位址和埠號。當資料庫已連線到您的 Static Web Apps 資源時，host.mode 會被覆寫為 `production`。
`entities`	將 URL 路徑對應至資料庫實體和資料表的區段。用來保護路徑的相同角色型驗證規則也會保護資料庫實體，而且可用來定義每個實體的許可權。 entities 物件也會指定實體之間的關聯性。

產生組態檔

Static Web Apps CLI 可讓您產生組態檔存根。

重要

為了提升從 Static Web Apps CLI 部署的安全性，引進了一項重大變更，要求您在 2025 年 1 月 15 日之前升級至最新版 (2.0.2) 的 Static Web Apps CLI。

使用 swa db init --database-type <YOUR_DATABASE_TYPE> 來產生組態檔。根據預設，CLI 會在名為 swa-db-connections 的資料夾中建立新的 staticwebapp.database.config.json。

支援的資料庫型態包括：

mssql
postgresql
cosmosdb_nosql
mysql

自訂組態資料夾

staticwebapp.database.config.json檔案的預設資料夾名稱是 swa-db-connections。如果您想要使用不同的資料夾，您必須更新工作流程檔案，以告訴靜態 Web 應用程式執行時間要在哪裡尋找您的組態檔。屬性 data_api_location 可讓您定義組態資料夾的位置。

注意

保存 staticwebapp.database.config.json 檔案的資料夾必須位於靜態 Web 應用程式存放庫的根目錄。

下列程式代碼示範如何針對資料庫組態檔使用名為 db-config 的資料夾。

app_location: "/src"
api_location: "api"
output_location: "/dist"
data_api_location: "db-config" # Folder holding the staticwebapp.database.config.json file

設定資料庫連線

Azure Static Web Apps 必須能透過網路存取您的資料庫，資料庫連線才能運作。此外，若要使用 Azure 資料庫進行本機開發，您必須設定資料庫以允許來自您自己的 IP 位址的要求。以下是適用於所有資料庫的一般步驟。如需針對您的資料庫類型的特定步驟，請參閱上述連結。

移至 Azure 入口網站中的資料庫。
移至 [網路] 索引標籤。
在 [防火牆規則] 區段底下，選取 [新增您的用戶端 IPv4 位址]。此步驟可確保您可以使用此資料庫進行本機開發。
選取 [ 允許 Azure 服務和資源存取此伺服器 ] 複選框。此步驟可確保已部署的 Static Web Apps 資源可以存取您的資料庫。
選取儲存。

連接資料庫

將資料庫連結至靜態 Web 應用程式會在發佈至 Azure 時，建立網站與資料庫之間的正式環境連線。

在 Azure 入口網站中開啟您的靜態 Web 應用程式。
在設定區段中，選取 資料庫連線。
在生產區段中，選取 連結現有資料庫 連結。

在 [ 連結現有資料庫] 視窗中，輸入下列值：

屬性	值
資料庫類型	從下拉式清單中選取您的資料庫類型。
訂閱	從下拉式清單中選取您的 Azure 訂用帳戶。
資源名稱	選取具有所需資料庫的資料庫伺服器名稱。
資料庫名稱	選取您要連結至靜態 Web 應用程式的資料庫名稱。
驗證類型	選取連線到資料庫所需的連接類型。

使用下列其中一個資料庫，將資料庫新增至靜態 Web 應用程式：

此外，您可以瞭解如何搭配 Azure Static Web Apps 使用數據 API 產生器。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-12