跳至主要内容

管理 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}

认证​

Prisma Postgres API 支持两种认证方法

  • 服务令牌 — 用于访问您自己工作区中的资源
  • 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 和 Redirect URI（用户授权后将被重定向到的 URL）。
  5. 点击 Continue，然后复制并将您的 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：授权码
    • Redirect URI：您的应用程序的重定向 URI（必须与您在 OAuth 凭据中配置的匹配）
    • Auth URL：https://auth.prisma.io/authorize
    • Client ID / Secret：来自您的 OAuth 应用程序
    • Scope：workspace:admin offline_access（根据需要）
  3. 完成流程并在请求中使用令牌。
SwaggerUI 中的认证

使用服务令牌​

  1. 点击 Authorize。
  2. 将服务令牌粘贴到相关输入框中。
  3. 再次点击 Authorize。

Swagger 规范通过 Authorization 标头支持 Bearer 令牌。

使用 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 未授权

POST /projects​

创建一个新项目。

  • 请求正文: 
    {
      "region": "us-east-1",
      "name": "My Project"
    }
  • 响应:
    • 201 Created：项目已创建
    • 401 未授权

GET /projects/{id}​

按 ID 检索特定项目。

  • 路径参数:
    • id：项目 ID
  • 响应:
    • 200 OK
    • 401 未授权
    • 404 未找到

DELETE /projects/{id}​

删除项目。

  • 路径参数:
    • id：项目 ID
  • 响应:
    • 204 无内容
    • 400 Bad Request：依赖关系阻止删除
    • 401 未授权
    • 404 未找到

POST /projects/{id}/transfer​

将项目转移到新的工作区所有者。

  • 路径参数:
    • id：项目 ID
  • 请求正文: 
    {
      "recipientAccessToken": "string"
    }
  • 响应:
    • 200 OK
    • 401 未授权
    • 404 未找到

数据库​

GET /projects/{projectId}/databases​

检索项目的所有数据库。

  • 路径参数:
    • projectId：项目 ID
  • 查询参数:
    • cursor（可选）：用于分页的游标
    • limit（可选，默认值：100）：限制结果数量
  • 响应:
    • 200 OK
    • 401 未授权
    • 404 未找到

POST /projects/{projectId}/databases​

创建一个新数据库。

  • 路径参数:
    • projectId：项目 ID
  • 请求正文: 
    {
      "region": "us-east-1",
      "name": "My Database",
      "isDefault": false,
      "fromDatabase": { 
        "id": "databaseId", 
        "backupId": "string"
      }
    }
    注意

    仅当从现有数据库或备份创建数据库时才使用 fromDatabase。

  • 响应:
    • 201 已创建
    • 400 默认数据库已存在
    • 401 未授权
    • 403 禁止访问

GET /databases/{databaseId}​

检索特定数据库。

  • 路径参数:
    • databaseId：数据库 ID
  • 响应:
    • 200 OK
    • 401 未授权
    • 404 未找到

DELETE /databases/{databaseId}​

删除数据库。

  • 路径参数:
    • databaseId：数据库 ID
  • 响应:
    • 200 OK
    • 401 未授权
    • 403 无法删除默认环境
    • 404 未找到

连接字符串​

GET /databases/{databaseId}/connections​

检索所有数据库连接字符串。

  • 路径参数:
    • databaseId：数据库 ID
  • 查询参数:
    • cursor（可选）：用于分页的游标
    • limit（可选，默认值：100）：限制结果数量
  • 响应:
    • 200 OK
    • 401 未授权

POST /databases/{databaseId}/connections​

创建一个新连接字符串。

  • 路径参数:

    • databaseId：数据库 ID

  • 请求正文:

    {
      "name": "Connection Name"
    }

  • 响应:

    • 200 OK
    • 401 未授权
    • 404 未找到

DELETE /connections/{id}​

删除连接字符串。

  • 路径参数:
    • id：连接 ID
  • 响应:
    • 204 无内容
    • 401 未授权
    • 404 未找到

备份​

GET /databases/{databaseId}/backups​

检索数据库备份。

  • 路径参数:
    • databaseId：数据库 ID
  • 查询参数:
    • limit（可选，默认值：25）：限制结果数量
  • 响应:
    • 200 OK
    • 401 未授权
    • 404 未找到

集成​

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 未授权
打开方式
复制为 Markdown
在 Claude 中打开
在 ChatGPT 中打开
在 T3.chat 中打开
在 GitHub 中编辑
© . This site is unofficial and not affiliated with Prisma Data, Inc.