合作夥伴資料庫配置與使用者領取流程

簡介

本指南將引導您如何使用 Prisma Postgres 管理 API (Management API) 來支援各類體驗，例如 npx create-db 指令。

您將學會如何以合作夥伴身分在您的工作空間中配置 Prisma Postgres 資料庫，以及如何將其轉移至其他使用者的工作空間，以便他們能「領取」(claim) 該資料庫。我們將說明如何使用 OAuth2 保障此流程的安全，並在指南結束時，您將完整理解整個流程，以及如何將其整合至您自己的產品體驗中。

本指南引用了 npx create-db CLI 和 Cloudflare Workers 的實際實作作為現實範例。npx create-db 的儲存庫位於此處，您可以將其作為在自己專案中使用管理 API 的參考。

這如何整合到您的應用程式中？

本指南中的兩個 Cloudflare Workers 僅為參考範例。通常您會將此邏輯建置在您自己的後端或無伺服器函式 (serverless functions) 中。

同樣地，npx create-db CLI 是一個簡單的展示。在您的產品中，您可以從自己的 UI 或註冊流程中觸發相同的 API 呼叫，為您的使用者創造無縫的體驗。

核心概念

在深入實作之前，讓我們釐清管理 API 整合所涉及的主要概念：

管理 API (Management API)：一組端點，允許您以程式化方式配置和管理 Prisma Postgres 資料庫。
專案與資料庫：專案是一個容器，可以容納多個資料庫。您可以用它來組織您建立的資料庫（例如按使用者分類）。專案可以轉移給使用者，包含其中所有的資料庫。
驗證 (Authentication)：所有 API 請求都需要經過驗證。作為合作夥伴，您使用工作空間的「服務權杖」(service token) 來驗證配置請求，並在領取流程中使用 OAuth 2 來獲取使用者的存取權杖。
權杖 (Tokens)：主要有兩種類型的權杖
- 服務權杖 (Service token)：發給您的合作夥伴整合，範圍限於在您自己的工作空間中配置和管理資料庫。
- OAuth 2 存取權杖 (OAuth 2 access token)：當使用者透過您的應用程式進行身分驗證時，透過 OAuth 2 獲得；其範圍限於使用者的工作空間，用於將專案/資料庫的所有權轉移給該工作空間。

如何成為合作夥伴

要使用 Prisma Postgres 管理 API，您首先需要設定為合作夥伴。

申請管理 API 的存取權限：請透過 Prisma 合作夥伴頁面聯繫 Prisma 團隊以申請管理 API 的存取權。我們將引導您完成加入流程。
獲取 OAuth 憑證：您可以在此處獲取您的 OAuth 憑證：。詳細資訊請參閱下一節。

如需可用端點的完整列表以及請求/回應格式的詳細資訊，請參閱 Prisma 管理 API 文件。

獲取 OAuth 憑證

要獲取客戶端 ID (client ID) 和客戶端密鑰 (client secret)，您需要執行此流程：

開啟.
點擊側邊欄中的 🧩 整合 (Integrations) 標籤。
在 已發布的應用程式 (Published Applications) 區塊中，點擊 新增應用程式 (New Application) 按鈕以開始建立新的 OAuth 應用程式流程。
輸入 OAuth 應用程式的 名稱 (Name)、描述 (Description) 和 回呼 URL (Callback URL)。
點擊 繼續 (Continue)。

在下一個畫面上，您可以存取並儲存您的 OAuth 應用程式的客戶端 ID 和客戶端密鑰。

以合作夥伴身分配置資料庫

要以合作夥伴身分協助使用者配置新的 Prisma Postgres 資料庫，請遵循以下步驟：

收集必要資訊：準備配置所需的詳細資訊，例如區域、資料庫名稱以及您的應用程式所需的任何其他選項。這些資訊可能來自使用者的輸入，或是由您的應用程式邏輯所決定。
驗證您的整合：使用您的服務權杖來驗證來自後端的 API 請求。此權杖能將您的應用程式驗證為授權的合作夥伴。

傳送資料庫配置請求：對管理 API 端點發送 POST 請求，以建立一個包含預設資料庫的新專案。例如：

const prismaResponse = await fetch('https://api.prisma.io/v1/projects', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer <YOUR_SERVICE_TOKEN>`,
  },
  body: JSON.stringify({ region, name }),
});

處理回應：如果成功，API 將會回傳新專案的詳細資訊，包括資料庫連接字串和 project_id。請妥善儲存這些資訊，並根據需要展示給您的使用者。
（選填）儲存專案元數據：您可能希望將 project_id 與您的使用者關聯並儲存在您自己的資料庫中，以供日後參考。

資料庫領取流程

資料庫配置完成後，您可能希望在稍後的某個時間點將所有權轉移給使用者，以便他們能在自己的 Prisma 工作空間中管理它，並突破免費資料庫的使用限制。這是透過「領取流程」(claim flow) 來完成的，該流程包含三個主要步驟：

總覽：領取流程如何運作

當使用者想要領取資料庫時，您的應用程式將：

觸發 OAuth2 流程，將使用者重新導向至 Prisma Auth。這是必要的步驟，以便您的應用程式擁有將資料庫轉移至使用者工作空間的權限。
使用者進行驗證並選擇一個工作空間。
您的後端會收到一個授權碼，將其兌換為使用者存取權杖，並同時使用您的整合權杖與使用者的權杖來呼叫管理 API 的轉移端點。

這確保了轉移過程是安全的，並且只有預期的使用者才能領取該資料庫。

1. 觸發領取流程

當您的使用者想要取得您為他們配置的資料庫所有權時，他們需要將其轉移到自己的 Prisma Postgres 工作空間。這能讓他們擁有對資料庫的完全控制權。

要啟動此流程，請在您的應用程式中提供按鈕或連結（例如「領取資料庫」或「轉移至我的工作空間」）。當點擊時，您的後端應該：

產生一個安全的 state 值來追蹤工作階段，並防止 CSRF 攻擊。
使用您的客戶端 ID、重新導向 URI 和所需的範圍建構 OAuth2 授權 URL。
將使用者重新導向至此 URL 以開始驗證流程。

範例

const authParams = new URLSearchParams({
  client_id: YOUR_CLIENT_ID,
  redirect_uri: 'https://your-app.com/auth/callback', // Your callback endpoint
  response_type: 'code',
  scope: 'workspace:admin', // The scope of the OAuth2 authorization
  state: generateState(), // Securely track the session
});
const authUrl = `https://auth.prisma.io/authorize?${authParams.toString()}`;
// Redirect the user to authUrl

2. 驗證使用者身分

系統會提示使用者登入（若尚未驗證）並選擇他們想要領取資料庫的工作空間。驗證並選擇工作空間成功後，Prisma Auth 將會帶有 code 和 state（以及在某些情況下，project_id）重新導向回您的回呼端點。

3. 完成領取流程

您的後端現在應該：

將授權碼兌換為使用者存取權杖。:

const tokenResponse = await fetch('https://auth.prisma.io/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: code, // The code received from the callback
    redirect_uri: 'https://your-app.com/auth/callback', // Must match the redirect_uri used in step 1
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET,
  }).toString(),
});
const tokenData = await tokenResponse.json();

呼叫管理 API 的轉移端點，將專案移至所選的工作空間。您將需要 project_id 以及使用者的存取權杖。

const transferResponse = await fetch(`https://api.prisma.io/v1/projects/${project_id}/transfer`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${PRISMA_SERVICE_TOKEN}`,
  },
  body: JSON.stringify({ recipientAccessToken: tokenData.access_token }),
});

如果轉移成功，資料庫現在就屬於該使用者的工作空間所有。

總結

透過遵循本指南，您已學會如何：

設定為 Prisma Postgres 合作夥伴並獲取必要憑證。
使用管理 API 為您的使用者配置新資料庫。
實作安全的領取流程，允許使用者使用 OAuth2 在他們自己的工作空間中取得資料庫所有權。

此流程使您能夠將 Prisma Postgres 的配置與轉移功能無縫整合至您自己的產品中，為您的使用者提供流暢的註冊與體驗流程。

如需更多詳細資訊，請參閱 create-db 儲存庫作為參考實作，或是查閱 Prisma 管理 API 文件。

與 Prisma 保持聯繫

透過以下方式與我們聯繫，繼續您的 Prisma 旅程：我們的活躍社群。保持資訊靈通、參與其中，並與其他開發者合作

在 X 上關注我們以獲取公告、現場活動和實用技巧。
加入我們的 Discord 提出問題、與社群對話，並透過對話獲得積極支援。
在 YouTube 上訂閱查看教學、演示和直播。
在 GitHub 上交流透過為存放庫加星標、報告問題或為 issue 做出貢獻。

我們衷心感謝您的參與，並期待您成為我們社群的一份子！

簡介​

核心概念​

如何成為合作夥伴​

獲取 OAuth 憑證​

以合作夥伴身分配置資料庫​

資料庫領取流程​

總覽：領取流程如何運作​

1. 觸發領取流程​

2. 驗證使用者身分​

3. 完成領取流程​

總結​