程式碼研究室簡介
1. 總覽
Cloud Run 是一個全代管運算平台,讓您能直接在可擴充的 Google 基礎架構上執行程式碼。本程式碼研究室將示範如何將 Cloud Run 上的 Next.js 應用程式連結至 PostgreSQL 適用的 Cloud SQL 資料庫。
本實驗室的學習內容包括:
- 建立 PostgreSQL 適用的 Cloud SQL 執行個體 (已設定為使用 Private Service Connect)
- 將可連線至 Cloud SQL 資料庫的應用程式部署至 Cloud Run
- 使用 Gemini Code Assist 為應用程式新增功能
2. 必要條件
- 如果您還沒有 Google 帳戶,請務必建立 Google 帳戶。
- 請改用個人帳戶,而非公司或學校帳戶。工作和學校帳戶可能有限制,導致您無法啟用本實驗室所需的 API。
3. 專案設定
- 登入 Google Cloud 控制台。
- 在 Cloud 控制台中啟用帳單。
- 完成本研究室所需的 Cloud 資源費用應低於 $1 美元。
- 您可以按照本實驗室課程結尾的步驟刪除資源,避免產生其他費用。
- 新使用者可享有價值 $300 美元的免費試用期。
- 建立新專案或選擇重複使用現有專案。
4. 開啟 Cloud Shell 編輯器
- 前往 Cloud Shell 編輯器
- 如果終端機未顯示在畫面底部,請按照下列步驟開啟:
- 按一下漢堡選單
- 按一下「Terminal」
- 按一下「New Terminal」
- 按一下漢堡選單
- 在終端機中,使用以下指令設定專案:
- 格式:
gcloud config set project [PROJECT_ID]
- 範例:
gcloud config set project lab-project-id-example
- 如果您不記得專案 ID:
- 您可以使用下列指令列出所有專案 ID:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- 您可以使用下列指令列出所有專案 ID:
- 格式:
- 如果出現授權提示訊息,請點選「授權」繼續操作。
- 您應該會看到下列訊息:
如果您看到Updated property [core/project].
WARNING
並收到Do you want to continue (Y/N)?
要求,表示您可能輸入的專案 ID 有誤。按下N
和Enter
鍵,然後再次嘗試執行gcloud config set project
指令。
5. 啟用 API
在終端機中啟用 API:
gcloud services enable \
compute.googleapis.com \
sqladmin.googleapis.com \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
networkconnectivity.googleapis.com \
servicenetworking.googleapis.com \
cloudaicompanion.googleapis.com
如果出現授權提示訊息,請點選「授權」繼續操作。
這個指令可能需要幾分鐘才能完成,但最終應該會顯示類似以下的成功訊息:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
6. 設定服務帳戶
建立並設定 Cloud Run 可使用的 Google Cloud 服務帳戶,讓該帳戶具備連線至 Cloud SQL 的正確權限。
- 請執行以下
gcloud iam service-accounts create
指令,建立新的服務帳戶:gcloud iam service-accounts create quickstart-service-account \
--display-name="Quickstart Service Account" - 執行以下 gcloud projects add-iam-policy-binding 指令,將「Log Writer」角色新增至您剛才建立的 Google Cloud 服務帳戶。
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
--member="serviceAccount:quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--role="roles/logging.logWriter"
7. 建立 Cloud SQL 執行個體
- 建立服務連線政策,透過 Private Service Connect 允許 Cloud Run 與 Cloud SQL 之間的網路連線
gcloud network-connectivity service-connection-policies create quickstart-policy \
--network=default \
--project=${GOOGLE_CLOUD_PROJECT} \
--region=us-central1 \
--service-class=google-cloud-sql \
--subnets=https://www.googleapis.com/compute/v1/projects/${GOOGLE_CLOUD_PROJECT}/regions/us-central1/subnetworks/default - 為資料庫產生專屬密碼
export DB_PASSWORD=$(openssl rand -base64 20)
- 執行
gcloud sql instances create
指令建立 Cloud SQL 執行個體gcloud sql instances create quickstart-instance \
--project=${GOOGLE_CLOUD_PROJECT} \
--root-password=${DB_PASSWORD} \
--database-version=POSTGRES_17 \
--tier=db-perf-optimized-N-2 \
--region=us-central1 \
--ssl-mode=ENCRYPTED_ONLY \
--no-assign-ip \
--enable-private-service-connect \
--psc-auto-connections=network=projects/${GOOGLE_CLOUD_PROJECT}/global/networks/default
這個指令可能需要幾分鐘才能完成。
- 執行
gcloud sql databases create
指令,在quickstart-instance
中建立 Cloud SQL 資料庫。gcloud sql databases create quickstart_db \
--instance=quickstart-instance
8. 準備申請
準備可回應 HTTP 要求的 Next.js 應用程式。
- 如要建立名為
task-app
的新 Next.js 專案,請使用下列指令:npx create-next-app@15.0.3 task-app \
--ts \
--eslint \
--tailwind \
--no-src-dir \
--turbopack \
--app \
--no-import-alias - 如果系統要求安裝
create-next-app
,請按下Enter
繼續操作:Need to install the following packages:
create-next-app@15.0.3
Ok to proceed? (y) - 將目錄變更為
task-app
:cd task-app
- 安裝
pg
與 PostgreSQL 資料庫互動。npm install pg
- 安裝
@types/pg
做為開發依附元件,以便使用 TypeScript Next.js 應用程式。npm install --save-dev @types/pg
- 建立
actions.ts
檔案。touch app/actions.ts
- 在 Cloud Shell 編輯器中開啟
actions.ts
檔案: 畫面頂端應該會顯示空白檔案。您可以在這裡編輯cloudshell edit app/actions.ts
actions.ts
檔案。 - 複製下列程式碼,並貼到已開啟的
actions.ts
檔案中:'use server'
import pg from 'pg';
type Task = {
id: string;
title: string;
status: 'IN_PROGRESS' | 'COMPLETE';
};
const { Pool } = pg;
const pool = new Pool({
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
ssl: {
// @ts-expect-error require true is not recognized by @types/pg, but does exist on pg
require: true,
rejectUnauthorized: false, // required for self-signed certs
// https://node-postgres.com/features/ssl#self-signed-cert
}
});
const tableCreationIfDoesNotExist = async () => {
await pool.query(`CREATE TABLE IF NOT EXISTS visits (
id SERIAL NOT NULL,
created_at timestamp NOT NULL,
PRIMARY KEY (id)
);`);
await pool.query(`CREATE TABLE IF NOT EXISTS tasks (
id SERIAL NOT NULL,
created_at timestamp NOT NULL,
status VARCHAR(255) NOT NULL default 'IN_PROGRESS',
title VARCHAR(1024) NOT NULL,
PRIMARY KEY (id)
);`);
}
// CREATE
export async function addNewTaskToDatabase(newTask: string) {
await tableCreationIfDoesNotExist();
await pool.query(`INSERT INTO tasks(created_at, status, title) VALUES(NOW(), 'IN_PROGRESS', $1)`, [newTask]);
return;
}
// READ
export async function getTasksFromDatabase() {
await tableCreationIfDoesNotExist();
const { rows } = await pool.query(`SELECT id, created_at, status, title FROM tasks ORDER BY created_at DESC LIMIT 100`);
console.table(rows); // logs the last 5 visits on the server
return rows; // sends the last 5 visits to the client
}
// UPDATE
export async function updateTaskInDatabase(task: Task) {
await tableCreationIfDoesNotExist();
await pool.query(
`UPDATE tasks SET status = $1, title = $2 WHERE id = $3`,
[task.status, task.title, task.id]
);
return;
}
// DELETE
export async function deleteTaskFromDatabase(taskId: string) {
await tableCreationIfDoesNotExist();
await pool.query(`DELETE FROM tasks WHERE id = $1`, [taskId]);
return;
} - 在 Cloud Shell 編輯器中開啟
page.tsx
檔案: 畫面頂端應該會顯示現有的檔案。您可以在這裡編輯cloudshell edit app/page.tsx
page.tsx
檔案。 - 刪除
page.tsx
檔案的現有內容。 - 複製下列程式碼,並貼到已開啟的
page.tsx
檔案中:'use client'
import React, { useEffect, useState } from "react";
import { addNewTaskToDatabase, getTasksFromDatabase, deleteTaskFromDatabase, updateTaskInDatabase } from "./actions";
type Task = {
id: string;
title: string;
status: 'IN_PROGRESS' | 'COMPLETE';
};
export default function Home() {
const [newTaskTitle, setNewTaskTitle] = useState('');
const [tasks, setTasks] = useState<Task[]>([]);
async function getTasks() {
const updatedListOfTasks = await getTasksFromDatabase();
setTasks(updatedListOfTasks);
}
useEffect(() => {
getTasks();
}, []);
async function addTask() {
await addNewTaskToDatabase(newTaskTitle);
await getTasks();
setNewTaskTitle('');
}
async function updateTask(task: Task, newTaskValues: Partial<Task>) {
await updateTaskInDatabase({ ...task, ...newTaskValues });
await getTasks();
}
async function deleteTask(taskId: string) {
await deleteTaskFromDatabase(taskId);
await getTasks();
}
return (
<main className="p-4">
<h2 className="text-2xl font-bold mb-4">To Do List</h2>
<div className="flex mb-4">
<form onSubmit={handleSubmit} className="flex mb-8">
<input
type="text"
placeholder="New Task Title"
value={newTaskTitle}
onChange={(e) => setNewTaskTitle(e.target.value)}
className="flex-grow border border-gray-400 rounded px-3 py-2 mr-2 bg-inherit"
/>
<button
type="submit"
className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded text-nowrap"
>
Add New Task
</button>
</form>
</div>
<table className="w-full">
<tbody>
{tasks.map(function (task) {
const isComplete = task.status === 'COMPLETE';
return (
<tr key={task.id} className="border-b border-gray-200">
<td className="py-2 px-4">
<input
type="checkbox"
checked={isComplete}
onClick={() => updateTask(task, { status: isComplete ? 'IN_PROGRESS' : 'COMPLETE' })}
className="transition-transform duration-300 ease-in-out transform scale-100 checked:scale-125 checked:bg-green-500"
/>
</td>
<td className="py-2 px-4">
<span className={`transition-all duration-300 ease-in-out ${isComplete ? 'line-through text-gray-400 opacity-50' : 'opacity-100'}`}>
{task.title}
</span>
</td>
<td className="py-2 px-4">
<button
onClick={() => deleteTask(task.id)}
className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded"
>
Delete
</button>
</td>
</tr>
);
})}
</tbody>
</table>
</main>
);
}
應用程式現在已準備好部署。
9. 將應用程式部署至 Cloud Run
- 執行 gcloud projects add-iam-policy-binding 指令,如以下所示,將「Network User」角色新增至 Cloud Run 服務帳戶,以便為您要建立的 Cloud Run 服務建立政策。
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
--member "serviceAccount:service-$(gcloud projects describe ${GOOGLE_CLOUD_PROJECT} --format="value(projectNumber)")@serverless-robot-prod.iam.gserviceaccount.com" \
--role "roles/compute.networkUser"
- 執行下列指令,將應用程式部署至 Cloud Run:
gcloud run deploy helloworld \
--region=us-central1 \
--source=. \
--set-env-vars DB_NAME="quickstart_db" \
--set-env-vars DB_USER="postgres" \
--set-env-vars DB_PASSWORD=${DB_PASSWORD} \
--set-env-vars DB_HOST="$(gcloud sql instances describe quickstart-instance --project=${GOOGLE_CLOUD_PROJECT} --format='value(settings.ipConfiguration.pscConfig.pscAutoConnections.ipAddress)')" \
--service-account="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--network=default \
--subnet=default \
--allow-unauthenticated - 如有提示,請按下
Y
和Enter
鍵,確認要繼續操作:Do you want to continue (Y/n)? Y
幾分鐘後,應用程式應會提供網址供您造訪。
前往該網址,查看應用程式的運作情形。每次造訪網址或重新整理網頁時,都會看到工作應用程式。
10. 使用 Gemini Code Assist 新增功能
您現在已部署含有資料庫的網頁應用程式。接下來,我們將利用 AI 輔助功能,為 next.js 應用程式新增一項新功能。
- 返回 Cloud Shell 編輯器
- 再次開啟
page.tsx
cd ~/task-app
cloudshell edit app/page.tsx - 在 Cloud Shell 編輯器中前往 Gemini Code Assist:
- 按一下畫面左側工具列中的 Gemini 圖示
- 如果出現提示,請使用 Google 帳戶憑證登入
- 如果系統提示您選取專案,請選取您為本程式碼研究室建立的專案
- 按一下畫面左側工具列中的 Gemini 圖示
- 輸入提示:
Add the ability to update the title of the task. The code in your output should be complete and working code.
。回應內容應包含類似下列程式碼片段,以便新增handleEditStart
和handleEditCancel
函式:const [editingTaskId, setEditingTaskId] = useState<string>('');
const [editedTaskTitle, setEditedTaskTitle] = useState('');
const handleEditStart = (task: Task) => {
setEditingTaskId(task.id);
setEditedTaskTitle(task.title);
};
const handleEditCancel = () => {
setEditingTaskId('');
setEditedTaskTitle('');
};<td className="py-2 px-4">
{editingTaskId === task.id ? (
<form onSubmit={(e) => {
e.preventDefault();
updateTask(task, { title: editedTaskTitle });
}}>
<input
type="text"
value={editedTaskTitle}
onChange={(e) => setEditedTaskTitle(e.target.value)}
onBlur={() => handleEditCancel} // Handle clicking outside input
className="border border-gray-400 rounded px-3 py-1 mr-2"
/>
<button type="submit" className="text-green-600 hover:text-green-900 mr-1">Save</button>
</form>
) : (
<span onClick={() => handleEditStart(task)} className="cursor-pointer">
{task.title}
</span>
)}
</td> - 將
page.tsx
替換為 Gemini Code Assist 的輸出內容。以下提供可運作的範例:'use client'
import React, { useEffect, useState } from "react";
import { addNewTaskToDatabase, getTasksFromDatabase, deleteTaskFromDatabase, updateTaskInDatabase } from "./actions";
type Task = {
id: string;
title: string;
status: 'IN_PROGRESS' | 'COMPLETE';
};
export default function Home() {
const [newTaskTitle, setNewTaskTitle] = useState('');
const [tasks, setTasks] = useState<Task[]>([]);
const [editingTaskId, setEditingTaskId] = useState<string>('');
const [editedTaskTitle, setEditedTaskTitle] = useState('');
async function getTasks() {
const updatedListOfTasks = await getTasksFromDatabase();
setTasks(updatedListOfTasks);
}
useEffect(() => {
getTasks();
}, []);
async function addTask() {
await addNewTaskToDatabase(newTaskTitle);
await getTasks();
setNewTaskTitle('');
}
async function updateTask(task: Task, newTaskValues: Partial<Task>) {
await updateTaskInDatabase({ ...task, ...newTaskValues });
await getTasks();
setEditingTaskId(''); // Clear editing state after update
setEditedTaskTitle('');
}
async function deleteTask(taskId: string) {
await deleteTaskFromDatabase(taskId);
await getTasks();
}
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
addTask();
};
const handleEditStart = (task: Task) => {
setEditingTaskId(task.id);
setEditedTaskTitle(task.title);
};
const handleEditCancel = () => {
setEditingTaskId('');
setEditedTaskTitle('');
};
return (
<main className="p-4">
<h2 className="text-2xl font-bold mb-4">To Do List</h2>
<form onSubmit={handleSubmit} className="flex mb-8">
<input
type="text"
placeholder="New Task Title"
value={newTaskTitle}
onChange={(e) => setNewTaskTitle(e.target.value)}
className="flex-grow border border-gray-400 rounded px-3 py-2 mr-2 bg-inherit"
/>
<button
type="submit"
className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded text-nowrap"
>
Add New Task
</button>
</form>
<table className="w-full">
<tbody>
{tasks.map(task => {
const isComplete = task.status === 'COMPLETE';
return (
<tr key={task.id} className="border-b border-gray-200">
<td className="py-2 px-4">
<input
type="checkbox"
checked={isComplete}
onClick={() => updateTask(task, { status: isComplete ? 'IN_PROGRESS' : 'COMPLETE' })}
className="transition-transform duration-300 ease-in-out transform scale-100 checked:scale-125 checked:bg-green-500"
/>
</td>
<td className="py-2 px-4">
{editingTaskId === task.id ? (
<form
onSubmit={(e) => {
e.preventDefault();
updateTask(task, { title: editedTaskTitle });
}}
className="flex"
>
<input
type="text"
value={editedTaskTitle}
onChange={(e) => setEditedTaskTitle(e.target.value)}
onBlur={() => handleEditCancel()} // Handle clicking outside input
className="flex-grow border border-gray-400 rounded px-3 py-1 mr-2 bg-inherit"
/>
<button
type="submit"
className="bg-green-600 hover:bg-green-900 m-1 text-white font-bold py-2 px-4 rounded"
>
Save
</button>
</form>
) : (
<span
onClick={() => handleEditStart(task)}
className={`transition-all duration-300 ease-in-out cursor-pointer ${isComplete ? 'line-through text-gray-400 opacity-50' : 'opacity-100'}`}
>
{task.title}
</span>
)}
</td>
<td className="py-2 px-4">
<button
onClick={() => deleteTask(task.id)}
className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded float-right"
>
Delete
</button>
</td>
</tr>
);
})}
</tbody>
</table>
</main>
);
}
11. 將應用程式重新部署至 Cloud Run
- 執行下列指令,將應用程式部署至 Cloud Run:
gcloud run deploy helloworld \
--region=us-central1 \
--source=. \
--set-env-vars DB_NAME="quickstart_db" \
--set-env-vars DB_USER="postgres" \
--set-env-vars DB_PASSWORD=${DB_PASSWORD} \
--set-env-vars DB_HOST="$(gcloud sql instances describe quickstart-instance --project=${GOOGLE_CLOUD_PROJECT} --format='value(settings.ipConfiguration.pscConfig.pscAutoConnections.ipAddress)')" \
--service-account="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--network=default \
--subnet=default \
--allow-unauthenticated - 如有提示,請按下
Y
和Enter
鍵,確認要繼續操作:Do you want to continue (Y/n)? Y
12. 恭喜
在本實驗室中,您已學習如何執行下列操作:
- 建立 PostgreSQL 適用的 Cloud SQL 執行個體 (已設定為使用 Private Service Connect)
- 將可連線至 Cloud SQL 資料庫的應用程式部署至 Cloud Run
- 使用 Gemini Code Assist 為應用程式新增功能
清除所用資源
Cloud SQL 沒有免費方案,如果您繼續使用,我們會向您收費。您可以刪除 Cloud 專案,避免產生額外費用。
不使用服務時,Cloud Run 不會收費,但您可能仍須支付儲存容器映像檔至 Artifact Registry 的費用。刪除 Cloud 專案後,系統就會停止對專案使用的所有資源收取費用。
如有需要,請刪除專案:
gcloud projects delete $GOOGLE_CLOUD_PROJECT
您也可以從雲端磁碟中刪除不必要的資源。您可以:
- 刪除 Codelab 專案目錄:
rm -rf ~/task-app
- 警告!這項操作無法復原!如要刪除 Cloud Shell 中的所有內容來釋出空間,您可以刪除整個主目錄。請務必將所有要保留的內容儲存在其他位置。
sudo rm -rf $HOME