使用 Azure Static Web Apps 連接資料庫（預覽）

這很重要

退休通知：靜態網頁應用程式的資料庫連線將於 2025 年 11 月 30 日結束。 立即遷移以避免中斷。

Azure 靜態網頁應用資料庫連線功能允許您從靜態網頁應用程式存取資料庫，而無需撰寫自訂伺服器端程式碼。

一旦你建立網路應用程式與資料庫的連結，就能完全支援 CRUD 操作、內建授權與關聯，來操作資料。

基於 Data API 建構器，Azure 靜態 Web Apps 會接收 REST 和 GraphQL 請求，並將其轉換成資料庫查詢。

資料庫連接所支援的功能包括：

特徵 / 功能 Description
整合安全 內建與 Azure 靜態 Web Apps 認證與授權安全模型的整合。 與 API 端點相同的基於角色的安全性同樣適用於路由安全。
完整的基於CRUD的操作 參考 Azure Cosmos DB、 Azure SQL、 MySQL 或 PostgreSQL 的教學，了解如何操作應用程式中的資料。
支援 SQL 與 NoSQL 你可以用關聯式和文件式資料庫作為應用程式的資料庫。
無伺服器架構 連線的範圍在預覽時從 0 擴展至 1 個工作者。
資料庫關係 僅支援 GraphQL 端點。
CLI 支援 使用 靜態網頁應用程式 CLI 在本地開發。 使用 --data-api-location 選項來處理開發中的資料 API 請求，就像在雲端中那樣處理。

支援的資料庫

下表顯示對不同關聯式與 NoSQL 資料庫的支援。

名稱 類型 Description REST GraphQL
Azure Cosmos DB 標準 全球分布式資料庫平台，適用於任何規模的 NoSQL 與關聯式資料庫。

除了 標準設定外，GraphQL 端點還需要一個 gql 結構檔案 。		 ✔
Azure SQL 標準 一系列管理型、安全且智慧型的產品，使用 Azure 雲端的 SQL Server 資料庫引擎。 ✔ ✔
適用於 MySQL 的 Azure 資料庫 彈性 基於 MySQL 社群版的 Microsoft 雲端關聯式資料庫服務 ✔ ✔
適用於 PostgreSQL 的 Azure 資料庫 彈性 全託管的 PostgreSQL 資料庫即服務，能以可預測的效能與動態擴展性處理關鍵任務工作負載。 ✔ ✔
Azure Database for PostgreSQL （single） Single 完全管理的 PostgreSQL 資料庫。 ✔ ✔

你可以使用以下連線類型來存取資料庫：

  • 連線字串
  • 使用者指派的受控識別
  • 系統指派的受管理身份識別

端點位置

資料端點可透過 /data-api 路徑存取。

下表顯示請求如何路由到靜態網頁應用程式的不同部分：

路徑 Description
example.com/api/* API 函式
example.com/data-api/* 支援 REST 與 GraphQL 請求的資料庫連線端點。
example.com/* 靜態內容

當你在網站上設定資料庫連線時，可以設定路由的 /data-api/* REST 或 GraphQL 後綴。 前 /data-api 綴是靜態網頁應用程式的慣例，無法更改。

設定

在靜態網頁應用程式中，設定資料庫連線有兩個步驟。 你需要將資料庫連接到 Azure 入口網站的靜態網頁應用程式，並更新資料庫連線的設定檔。

詳情請參閱 Azure 靜態網頁應用中的資料庫連線設定 。

本地開發

Azure 靜態網頁應用 CLI（SWA 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， ， updatedelete， ）。

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

當您呼叫需要角色的端點時，需符合以下條件：

  1. 目前的使用者必須經過認證。

  2. 目前使用者必須是所需角色的成員。

  3. REST 或 GraphQL 請求必須包含一個標頭，鍵值為 ， X-MS-API-ROLE 且角色名稱值與實體設定規則中列出的值相符。

    例如，以下片段說明如何在請求標頭中傳遞 管理員 角色。

    {
  method: "POST",
  headers: { 
    "Content-Type": "application/json",
    "X-MS-API-ROLE": "admin"
  },
  body: JSON.stringify(requestPayload)
}

Constraints

  • 資料庫必須能被 Azure 的基礎架構存取。
  • 在公開預覽期間，資料庫連線的規模從 0 擴展到 1 個資料庫工作者。

後續步驟

設定你的資料庫

  • Last updated on