教學課程：在 Azure Static Web Apps (預覽版中新增 Azure Cosmos DB 資料庫連線)
在本教學課程中，您將瞭解如何將適用于 NoSQL 的 Azure Cosmos DB 資料庫連線到靜態 Web 應用程式。 設定之後，您可以對內 /data-api 建端點提出 GraphQL 要求，以運算元據，而不需要撰寫後端程式碼。
為了簡單起見，本教學課程說明如何針對本機開發目的使用 Azure 資料庫，但您也可以針對本機開發需求使用本機資料庫伺服器。
注意
本教學課程說明如何使用適用于 NoSQL 的 Azure Cosmos DB。 如果您想要使用另一個資料庫，請參閱Azure SQL、MySQL或PostgreSQL教學課程。
您會在本教學課程中學到：
- 將適用于 NoSQL 的 Azure Cosmos DB 資料庫連結至靜態 Web 應用程式
- 建立、讀取、更新及刪除資料
必要條件
若要完成本教學課程，您必須擁有適用于 NoSQL 資料庫和靜態 Web 應用程式的現有 Azure Cosmos DB。
| 資源 | 描述 |
|---|---|
| 適用于 NoSQL 資料庫的 Azure Cosmos DB | 如果您還沒有 Azure Cosmos DB 資料庫指南中的步驟，請遵循 建立 Azure Cosmos DB 資料庫 指南中的步驟。 |
| 現有的靜態 Web 應用程式 | 如果您還沒有帳戶，請遵循 快速入門 指南中的步驟來建立 No Framework 靜態 Web 應用程式。 |
首先，設定資料庫以使用Azure Static Web Apps資料庫連線功能。
設定資料庫連線能力
Azure Static Web Apps必須具有資料庫的網路存取權，資料庫連線才能運作。 此外，若要使用 Azure 資料庫進行本機開發，您必須設定資料庫以允許來自您自己的 IP 位址的要求。
移至Azure 入口網站中的適用于 NoSQL 的 Azure Cosmos DB 帳戶。
在 [ 設定] 區段下，選取 [ 網路]。
在 [ 公用存取] 區段下，選取 [所有網路]。 此動作可讓您使用雲端資料庫進行本機開發，您的已部署Static Web Apps資源可以存取資料庫，而且您可以從入口網站查詢資料庫。
選取 [儲存]。
取得本機開發的資料庫連接字串
若要使用 Azure 資料庫進行本機開發，您需要擷取資料庫的連接字串。 如果您打算將本機資料庫用於開發目的，您可以略過此步驟。
移至Azure 入口網站中的適用于 NoSQL 的 Azure Cosmos DB 帳戶。
在 [ 設定] 區段下，選取 [ 金鑰]。
從 [ 主要連接字串 ] 方塊中，複製連接字串，並將它放在文字編輯器中。
建立範例資料
建立範例資料表，並植入範例資料以符合教學課程。
在左側導覽視窗中，選取[Data Explorer]。
選取 [新增容器]。 輸入 [資料庫識別碼] 作為
Create new，然後輸入MyTestPersonDatabase作為值。輸入 的容器識別碼
MyTestPersonContainer。輸入 (此值的分割區索引鍵
id前面加上/) 。選取 [確定]。
選取 MyTestPersonContainer 容器。
選取其 [專案]。
選取 [新增專案 ]，然後輸入下列值：
{ "id": "1", "Name": "Sunny" }
設定靜態 Web 應用程式
本教學課程的其餘部分著重于編輯靜態 Web 應用程式的原始程式碼，以在本機使用資料庫連線。
重要
下列步驟假設您使用 快速入門手冊中建立的靜態 Web 應用程式。 如果您使用不同的專案，請務必調整下列 git 命令，以符合您的分支名稱。
切換至
main分支。git checkout main使用
git pull同步處理本機版本與 GitHub 上的功能。git pull origin main
建立資料庫組態檔
接下來，建立靜態 Web 應用程式用來與資料庫進行介面的組態檔。
開啟終端機並建立新的變數來保存連接字串。 特定語法可能會因您使用的殼層類型而有所不同。
export DATABASE_CONNECTION_STRING='<YOUR_CONNECTION_STRING>'請務必將 取代
<YOUR_CONNECTION_STRING>為您在文字編輯器中設定的連接字串值。使用 npm 來安裝或更新 Static Web Apps CLI。 選取最適合您情況的命令。
若要安裝，請使用
npm install。npm install -g @azure/static-web-apps-cli若要更新，請使用
npm update。npm updateswa db init使用 命令來產生資料庫組態檔。swa db init --database-type cosmosdb_nosql --cosmosdb_nosql-database MyTestPersonDatabase此命令
init會在swa-db-connections資料夾中建立staticwebapp.database.config.json檔案。將此範例架構貼到您產生的 staticwebapp.database.schema.gql 檔案中。
由於適用于 NoSQL 的 Cosmos DB 與架構無關的資料庫，因此Azure Static Web Apps資料庫連線無法擷取資料庫的架構。 staticwebapp.database.schema.gql檔案可讓您針對 Static Web Apps 指定 Cosmos DB for NoSQL 資料庫的架構。
type Person @model { id: ID Name: String }將此範例組態貼到您產生的 檔案staticwebapp.database.config.json 。 請注意，適用于 NoSQL 的
data-sourceCosmos DB 在 物件中有更多選項，可指出資料庫連接所需的 Cosmos DB 資料庫和架構檔案，以瞭解資料庫的架構。
{
"$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
"data-source": {
"database-type": "cosmosdb_nosql",
"options": {
"database": "MyTestPersonDatabase",
"schema": "staticwebapp.database.schema.gql"
},
"connection-string": "@env('DATABASE_CONNECTION_STRING')"
},
"runtime": {
"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": "MyTestPersonContainer",
"permissions": [
{
"actions": ["*"],
"role": "anonymous"
}
]
}
}
}
在繼續進行下一個步驟之前，請檢閱下表，以說明組態檔的不同層面。 如需組態檔和功能的完整檔，例如專案層級安全性的關聯性和原則，請參閱 資料 API 產生器檔。
| 特徵 | 說明 |
|---|---|
| 資料庫連接 | 在開發中，執行時間會從組態檔中連接字串的值讀取連接字串。 雖然您可以直接在組態檔中指定連接字串，但最佳做法是將連接字串儲存在本機環境變數中。 您可以透過 @env('DATABASE_CONNECTION_STRING') 標記法參考組態檔中的環境變數值。 當您連接資料庫時所收集的資訊，Static Web Apps部署的月臺，即可覆寫連接字串的值。 |
| API 端點 | GraphQL 端點可透過此組態檔中所設定的方式取得 /data-api/graphql 。 您可以設定 GraphQL 路徑，但無法設定前置 /data-api 詞。 |
| API 安全性 | 這些 runtime.host.cors 設定可讓您定義可對 API 提出要求之允許的來源。 在此情況下，組態會反映開發環境，並允許列出 http://localhost:4280 位置。 |
| 實體模型 | 將透過路由公開的實體定義為 GraphQL 架構中的類型。 在此情況下， Name Person是公開至端點的名稱，而 entities.<NAME>.source 是資料庫架構和資料表對應。 請注意，API 端點名稱不需要與資料表名稱相同。 |
| 實體安全性 | 陣列中列出的 entity.<NAME>.permissions 許可權規則會控制實體的授權設定。 您可以使用與角色 保護路由相同的方式來保護具有角色的實體。 |
注意
當您部署月臺時，會覆寫組態檔的 connection-string 、 host.mode 和 graphql.allow-introspection 屬性。 當您將資料庫連線到您的Static Web Apps資源時，系統會以收集的驗證詳細資料覆寫連接字串。 屬性 host.mode 設定為 production ，而 設定 graphql.allow-introspection 為 false 。 這些覆寫可在開發與生產工作負載之間提供組態檔的一致性，同時確保您的Static Web Apps資源已啟用資料庫連線安全且可供生產環境使用。
將靜態 Web 應用程式設定為連線到資料庫後，您現在可以驗證連線。
更新首頁
以下列 HTML 取代index.html檔案中標記之間的 body 標記。
<h1>Static Web Apps Database Connections</h1>
<blockquote>
Open the console in the browser developer tools to see the API responses.
</blockquote>
<div>
<button id="list" onclick="list()">List</button>
<button id="get" onclick="get()">Get</button>
<button id="update" onclick="update()">Update</button>
<button id="create" onclick="create()">Create</button>
<button id="delete" onclick="del()">Delete</button>
</div>
<script>
// add JavaScript here
</script>
在本機啟動應用程式
現在您可以執行您的網站，並直接運算元據庫中的資料。
使用 npm 來安裝或更新 Static Web Apps CLI。 選取最適合您情況的命令。
若要安裝，請使用
npm install。npm install -g @azure/static-web-apps-cli若要更新，請使用
npm update。npm update使用資料庫組態啟動靜態 Web 應用程式。
swa start ./src --data-api-location swa-db-connections
現在，CLI 已啟動，您可以透過 staticwebapp.database.config.json 檔案中所定義的端點來存取資料庫。
端點 http://localhost:4280/data-api/graphql 接受 GraphQL 查詢和變動。
操作資料
下列與架構無關的命令示範如何在您的資料庫上執行完整的 CRUD 作業。
每個函式的輸出會出現在瀏覽器的主控台視窗中。
按CMD/CTRL + SHIFT + I開啟開發人員工具，然後選取[主控台] 索引標籤。
列出所有專案
在index.html中的標記之間 script 新增下列程式碼。
async function list() {
const query = `
{
people {
items {
id
Name
}
}
}`;
const endpoint = "/data-api/graphql";
const response = await fetch(endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ query: query })
});
const result = await response.json();
console.table(result.data.people.items);
}
在此範例中：
- GraphQL 查詢會
Id從資料庫選取 和Name欄位。 - 傳遞至伺服器的要求需要屬性保存查詢定義的承載
query。 - 在 屬性中找到回應承載中的資料
data.people.items。
重新整理頁面，然後選取 [ 清單] 按鈕。
瀏覽器的主控台視窗現在會顯示資料表，其中列出資料庫中的所有記錄。
| id | 名稱 |
|---|---|
| 1 | 晴朗 |
| 2 | Dheeraj |
以下是瀏覽器中看起來應該像的螢幕擷取畫面。
依識別碼取得
在index.html中的標記之間 script 新增下列程式碼。
async function get() {
const id = '1';
const gql = `
query getById($id: ID!) {
person_by_pk(id: $id) {
id
Name
}
}`;
const query = {
query: gql,
variables: {
id: id,
},
};
const endpoint = "/data-api/graphql";
const response = await fetch(endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(query),
});
const result = await response.json();
console.table(result.data.person_by_pk);
}
在此範例中：
- GraphQL 查詢會
id從資料庫選取 和Name欄位。 - 傳遞至伺服器的要求需要屬性保存查詢定義的承載
query。 - 在 屬性中找到回應承載中的資料
data.person_by_pk。
重新整理頁面，然後選取 [ 取得] 按鈕。
瀏覽器的主控台視窗現在會顯示資料表，其中列出從資料庫要求的單一記錄。
| id | 名稱 |
|---|---|
| 1 | 晴朗 |
更新
在index.html中的標記之間 script 新增下列程式碼。
async function update() {
const id = '1';
const data = {
id: id,
Name: "Molly"
};
const gql = `
mutation update($id: ID!, $_partitionKeyValue: String!, $item: UpdatePersonInput!) {
updatePerson(id: $id, _partitionKeyValue: $_partitionKeyValue, item: $item) {
id
Name
}
}`;
const query = {
query: gql,
variables: {
id: id,
_partitionKeyValue: id,
item: data
}
};
const endpoint = "/data-api/graphql";
const res = await fetch(endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(query)
});
const result = await res.json();
console.table(result.data.updatePerson);
}
在此範例中：
- GraphQL 查詢會
id從資料庫選取 和Name欄位。 - 物件
query會在 屬性中query保存 GraphQL 查詢。 - GraphQL 函式的引數值會透過
query.variables屬性傳入。 - 傳遞至伺服器的要求需要屬性保存查詢定義的承載
query。 - 在 屬性中找到回應承載中的資料
data.updatePerson。
重新整理頁面，然後選取 [ 更新] 按鈕。
瀏覽器的主控台視窗現在會顯示顯示更新資料的資料表。
| id | 名稱 |
|---|---|
| 1 | 莫莉 |
建立
在index.html中的標記之間 script 新增下列程式碼。
async function create() {
const data = {
id: "3",
Name: "Pedro"
};
const gql = `
mutation create($item: CreatePersonInput!) {
createPerson(item: $item) {
id
Name
}
}`;
const query = {
query: gql,
variables: {
item: data
}
};
const endpoint = "/data-api/graphql";
const result = await fetch(endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(query)
});
const response = await result.json();
console.table(response.data.createPerson);
}
在此範例中：
- GraphQL 查詢會
id從資料庫選取 和Name欄位。 - 物件
query會在 屬性中query保存 GraphQL 查詢。 - GraphQL 函式的引數值會透過
query.variables屬性傳入。 - 傳遞至伺服器的要求需要屬性保存查詢定義的承載
query。 - 在 屬性中找到回應承載中的資料
data.updatePerson。
重新整理頁面，然後選取 [ 建立] 按鈕。
瀏覽器的主控台視窗現在會顯示資料表，其中顯示資料庫中的新記錄。
| id | 名稱 |
|---|---|
| 3 | 佩德羅 |
刪除
在index.html中的標記之間 script 新增下列程式碼。
async function del() {
const id = '3';
const gql = `
mutation del($id: ID!, $_partitionKeyValue: String!) {
deletePerson(id: $id, _partitionKeyValue: $_partitionKeyValue) {
id
}
}`;
const query = {
query: gql,
variables: {
id: id,
_partitionKeyValue: id
}
};
const endpoint = "/data-api/graphql";
const response = await fetch(endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(query)
});
const result = await response.json();
console.log(`Record deleted: ${ JSON.stringify(result.data) }`);
}
在此範例中：
- GraphQL 查詢會
Id從資料庫選取欄位。 - 物件
query會在 屬性中query保存 GraphQL 查詢。 - GraphQL 函式的引數值會透過
query.variables屬性傳入。 - 傳遞至伺服器的要求需要屬性保存查詢定義的承載
query。 - 在 屬性中找到回應承載中的資料
data.deletePerson。
重新整理頁面，然後選取 [ 刪除] 按鈕。
瀏覽器的主控台視窗現在會顯示資料表，其中顯示來自刪除要求的回應。
已刪除記錄：2
現在您已在本機使用網站，您現在可以將其部署至 Azure。
部署您的網站
若要將此月臺部署到生產環境，您只需要認可組態檔，並將變更推送至伺服器。
認可組態變更。
git commit -am "Add database configuration"將您的變更推送至伺服器。
git push origin main等候 Web 應用程式建置。
在瀏覽器中移至您的靜態 Web 應用程式。
選取 [ 清單] 按鈕以列出所有專案。
輸出應該類似此螢幕擷取畫面中顯示的內容。
將資料庫連線到靜態 Web 應用程式
使用下列步驟來建立月臺實例與資料庫Static Web Apps實例之間的連線。
在 Azure 入口網站中開啟您的靜態 Web 應用程式。
在 [ 設定] 區段中，選取 [ 資料庫連線]。
在 [ 生產] 區段下，選取 [ 連結現有的資料庫 ] 連結。
在 [ 連結現有的資料庫 ] 視窗中，輸入下列值：
屬性 值 資料庫類型 從下拉式清單中選取您的資料庫類型。 訂用帳戶 從下拉式清單中選取您的 Azure 訂用帳戶。 資料庫名稱 選取您要連結至靜態 Web 應用程式的資料庫名稱。 驗證類型 選取 [連接字串]。 選取 [確定]。
確認您的資料庫已連線到您的Static Web Apps資源
將資料庫連線到靜態 Web 應用程式並完成網站建置之後，請使用下列步驟來驗證資料庫連線。
在 Azure 入口網站中開啟您的靜態 Web 應用程式。
在 [基本資訊]區段中，選取Static Web Apps資源的URL，以流覽至靜態 Web 應用程式。
選取 [ 清單 ] 按鈕以列出所有專案。
輸出應該類似此螢幕擷取畫面中顯示的內容。
清除資源
如果您想要移除本教學課程期間建立的資源，您必須取消連結資料庫並移除範例資料。
取消連結資料庫：在Azure 入口網站中開啟靜態 Web 應用程式。 在 [ 設定] 區段下，選取 [ 資料庫連線]。 在連結的資料庫旁邊，選取 [ 檢視詳細資料]。 在 [ 資料庫連線詳細資料] 視窗中，選取 [ 取消連結 ] 按鈕。
移除範例資料：在您的資料庫中，刪除名為 的
MyTestPersonContainer資料表。