共用方式為

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

  • 發行項

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

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

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

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

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

組態

您可以在檔案中 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 端點。 如需組態檔及其支援功能的完整詳細數據，請參閱 數據 API 產生器檔。

{
  "$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 用來解譯組態檔的資料庫 API 產生器 版本。
data-source 目標資料庫特定的組態設定。 屬性 database-type 接受 mssql、 postgresql、 cosmosdb_nosql或 mysql。

當資料庫連線到靜態 Web Apps 資源時，會在部署時覆寫 連接字串。 在本機開發期間，組態檔中定義的 連接字串 是用來連線到資料庫的內容。
runtime 定義公開端點的 區段。 rest和 graphql 屬性會控制用來存取個別 API 通訊協定的 URL 片段。 組 host 態區段會定義開發環境特定的設定。 請確定 origins 陣列包含您的localhost位址和埠。 當資料庫連線到靜態 Web Apps 資源時，會覆寫 production host.mode。
entities 將 URL 路徑對應至資料庫實體和數據表的區段。 用來保護路徑的相同 角色型驗證規則 也會保護資料庫實體，而且可用來定義每個實體的許可權。 entities 物件也會指定實體之間的關聯性。

產生組態檔

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 時，建立網站與資料庫之間的生產連線。

  1. 在 Azure 入口網站中開啟您的靜態 Web 應用程式。

  2. 在 [設定] 區段中，選取 [資料庫連線]。

  3. 在 [生產] 區段下，選取 [鏈接現有的資料庫連結]。

  4. 在 [ 鏈接現有的資料庫] 視窗中，輸入下列值：

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

相關內容

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

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