跳至主要內容

管理 API

總覽​

本頁面涵蓋了 Prisma 管理 API，讓您能夠以程式設計方式管理平台資源（例如專案或 Prisma Postgres 執行個體）。.

OpenAPI

您可以在此處查閱互動式的 OpenAPI 3.1 規格，探索端點、請求/回應主體以及詳細範例。

指南

我們提供三份指南，協助您將管理 API 應用於常見情境：

基礎 URL​

Prisma Postgres API 請求的基礎 URL 為：

https://api.prisma.io/v1

將端點路徑附加至基礎 URL，即可建構完整的請求 URL。例如：

https://api.prisma.io/v1/projects/{projectId}

身分驗證 (Authentication)​

Prisma Postgres API 支援兩種驗證方式：

  • 服務權杖 (Service tokens) — 用於存取您自有工作區中的資源
  • OAuth 2.0 存取權杖 — 用於代表使用者存取或管理資源

服務權杖​

服務權杖需在您的工作區中手動建立。它們非常適合伺服器對伺服器的整合，或是在您自己的工作區中佈建資料庫。

若要使用服務權杖進行驗證，請將其包含在 Authorization 標頭中。

Authorization: Bearer $TOKEN

建立服務權杖​

  1. 開啟.
  2. 導覽至您的工作區。
  3. 前往工作區的 設定 (Settings) 頁面，然後選擇 服務權杖 (Service Tokens)。
  4. 點擊 新增服務權杖 (New Service Token) 並複製產生的權杖以備日後使用。

OAuth 2.0 驗證​

如果您希望代表使用者行事，並直接在他們的工作區中建立或管理資料庫，請使用 OAuth 2.0。

建立 OAuth 憑證​

若要取得用戶端 ID 和用戶端密鑰：

  1. 開啟.
  2. 點擊 🧩 整合 (Integrations) 分頁。
  3. 在 已發布的應用程式 (Published Applications) 下，點擊 新增應用程式 (New Application)。
  4. 輸入 名稱 (Name)、描述 (Description) 和 重新導向 URI (Redirect URI)（即使用者授權後將被導向的 URL）。
  5. 點擊 繼續 (Continue)，然後將您的 用戶端 ID (Client ID) 和 用戶端密鑰 (Client Secret) 複製並儲存至安全的地方。

OAuth 授權流程​

若要使用 OAuth 2.0，您的應用程式必須：

  1. 將使用者重新導向至授權 URL，並附上您的用戶端 ID 和重新導向 URI。

    https://auth.prisma.io/authorize?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&response_type=code&scope=workspace:admin

  2. 接收授權碼：使用者授權您的應用程式後，他們將被重新導向至您的重新導向 URI，並帶有 code 參數。

    https://your-app.com/callback?code=abc123...

  3. 將授權碼兌換為存取權杖：在下一個請求中使用步驟 2 取得的程式碼：

curl -X POST https://auth.prisma.io/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "code=$CODE" \
  -d "grant_type=authorization_code" \
  -d "redirect_uri=$REDIRECT_URI"
注意

$CODE 是在上述步驟 2 中收到的授權碼。$REDIRECT_URI 必須與您建立 OAuth 憑證時設定的完全一致。

從回應中取得存取權杖後，請將其包含在對管理 API 的請求中。

curl --location "https://api.prisma.io/v1/projects" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "my_project",
    "region": "us-east-1"
  }'

說明​

在 Postman 中進行驗證

使用服務權杖​

  1. 建立一個新請求。
  2. 前往 Authorization 分頁。
  3. 將類型設為 Bearer Token。
  4. 貼上您的服務權杖。

使用 OAuth 2​

  1. 在 Authorization 分頁中，將類型設為 OAuth 2.0。
  2. 點擊 取得新存取權杖 (Get New Access Token) 並填寫詳細資料：
    • 權杖名稱 (Token Name)：任意名稱
    • 授權類型 (Grant Type)：Authorization Code
    • 重新導向 URI (Redirect URI)：您應用程式的重新導向 URI（必須與 OAuth 憑證設定一致）
    • 授權 URL (Auth URL)：https://auth.prisma.io/authorize
    • 用戶端 ID / 密鑰 (Client ID / Secret)：來自您的 OAuth 應用程式
    • 範圍 (Scope)：workspace:admin offline_access（視需要）
  3. 完成流程並在請求中使用該權杖。
在 SwaggerUI 中進行驗證

使用服務權杖​

  1. 點擊 Authorize。
  2. 將服務權杖貼入相關輸入欄位。
  3. 再次點擊 Authorize。

Swagger 規格支援透過 Authorization 標頭使用 Bearer token。

使用 OAuth 2​

  1. 點擊 Authorize。
  2. 選擇 OAuth2 流程。
  3. 提供您的 clientId、clientSecret 和重新導向 URI。
  4. 完成授權流程以取得存取權。

端點​

工作區​

GET /workspaces​

擷取當前使用者可存取的工作區資訊。

  • 查詢參數:
    • cursor（選填）：分頁游標
    • limit（選填，預設：100）：限制結果數量
  • 回應:
    • 200 OK：工作區列表
    • 401 Unauthorized：驗證權杖無效或遺失

專案​

GET /projects​

擷取所有專案。

  • 查詢參數:
    • cursor（選填）：分頁游標
    • limit（選填，預設：100）：限制結果數量
  • 回應:
    • 200 OK：專案列表
    • 401 Unauthorized

POST /projects​

建立一個新專案。

  • 請求主體: 
    {
      "region": "us-east-1",
      "name": "My Project"
    }
  • 回應:
    • 201 Created：專案已建立
    • 401 Unauthorized

GET /projects/{id}​

透過 ID 擷取特定專案。

  • 路徑參數:
    • id：專案 ID
  • 回應:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /projects/{id}​

刪除專案。

  • 路徑參數:
    • id：專案 ID
  • 回應:
    • 204 No Content
    • 400 Bad Request：因相依性而無法刪除
    • 401 Unauthorized
    • 404 Not Found

POST /projects/{id}/transfer​

將專案轉移給新的工作區擁有者。

  • 路徑參數:
    • id：專案 ID
  • 請求主體: 
    {
      "recipientAccessToken": "string"
    }
  • 回應:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

資料庫​

GET /projects/{projectId}/databases​

擷取專案的所有資料庫。

  • 路徑參數:
    • projectId：專案 ID
  • 查詢參數:
    • cursor（選填）：分頁游標
    • limit（選填，預設：100）：限制結果數量
  • 回應:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

POST /projects/{projectId}/databases​

建立新資料庫。

  • 路徑參數:
    • projectId：專案 ID
  • 請求主體: 
    {
      "region": "us-east-1",
      "name": "My Database",
      "isDefault": false,
      "fromDatabase": { 
        "id": "databaseId", 
        "backupId": "string"
      }
    }
    注意

    僅在從現有資料庫或備份建立資料庫時使用 fromDatabase。

  • 回應:
    • 201 Created
    • 400 預設資料庫已存在
    • 401 Unauthorized
    • 403 Forbidden

GET /databases/{databaseId}​

擷取特定資料庫。

  • 路徑參數:
    • databaseId：資料庫 ID
  • 回應:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /databases/{databaseId}​

刪除資料庫。

  • 路徑參數:
    • databaseId：資料庫 ID
  • 回應:
    • 200 OK
    • 401 Unauthorized
    • 403 無法刪除預設環境
    • 404 Not Found

連線字串​

GET /databases/{databaseId}/connections​

擷取所有資料庫連線字串。

  • 路徑參數:
    • databaseId：資料庫 ID
  • 查詢參數:
    • cursor（選填）：分頁游標
    • limit（選填，預設：100）：限制結果數量
  • 回應:
    • 200 OK
    • 401 Unauthorized

POST /databases/{databaseId}/connections​

建立新的連線字串。

  • 路徑參數:

    • databaseId：資料庫 ID

  • 請求主體:

    {
      "name": "Connection Name"
    }

  • 回應:

    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /connections/{id}​

刪除連線字串。

  • 路徑參數:
    • id：連線 ID
  • 回應:
    • 204 No Content
    • 401 Unauthorized
    • 404 Not Found

備份​

GET /databases/{databaseId}/backups​

擷取資料庫備份。

  • 路徑參數:
    • databaseId：資料庫 ID
  • 查詢參數:
    • limit（選填，預設：25）：限制結果數量
  • 回應:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

整合​

GET /workspaces/{workspaceId}/integrations​

擷取指定工作區的整合資訊。

  • 路徑參數:
    • workspaceId：工作區 ID
  • 查詢參數:
    • cursor（選填）：分頁游標
    • limit（選填，預設：100）：限制結果數量
  • 回應:
    • 200 OK：整合清單與詳情
      • id：整合 ID
      • createdAt：建立時間戳記
      • scopes：已授權範圍陣列
      • client：包含 id、name、createdAt 的物件
      • createdByUser：包含 id、email、displayName 的物件
    • 401 Unauthorized：驗證權杖遺失或無效
    • 404 Not Found：找不到工作區

DELETE /workspaces/{workspaceId}/integrations/{clientId}​

撤銷具有指定用戶端 ID 的整合權杖。

  • 路徑參數:
    • workspaceId：工作區 ID（例如 wksp_1234）
    • clientId：整合用戶端 ID（例如 itgr_5678）
  • 回應:
    • 204 No Content：整合權杖已成功撤銷
    • 401 Unauthorized：驗證權杖遺失或無效
    • 404 Not Found：找不到工作區或整合

其他​

GET /regions/postgres​

擷取所有可用區域。

  • 回應:
    • 200 OK：傳回可用/不支援的區域列表
    • 401 Unauthorized
開啟於
複製為 Markdown
於 Claude 開啟
...在 ChatGPT 中開啟
...在 T3.chat 中開啟
在 GitHub 中編輯
© . This site is unofficial and not affiliated with Prisma Data, Inc.