合作伙伴数据库供应和用户声明流程

介绍

本指南将引导您了解如何使用 Prisma Postgres 管理 API，以支持像 npx create-db 命令这样的体验。

您将学习如何以合作伙伴身份在您的工作区中配置 Prisma Postgres 数据库，以及如何将其传输到其他用户的工作区，以便他们可以“声明”该数据库。我们将介绍如何使用 OAuth2 保护此过程，最后，您将了解整个流程以及如何将其集成到您自己的产品体验中。

本指南引用了 npx create-db CLI 和 Cloudflare Workers 中的实际实现作为真实世界的示例。npx create-db 的仓库在这里，可以作为您自己在项目中使用管理 API 的参考。

这如何融入您的应用程序？

本指南中的两个 Cloudflare Workers 只是参考示例。您通常会将此逻辑构建到您自己的后端或无服务器函数中。

同样，npx create-db CLI 是一个简单的演示。在您的产品中，您可以从您自己的 UI 或入职流程中触发相同的 API 调用，为您的用户创建无缝体验。

核心概念

在深入实施之前，让我们澄清管理 API 集成中涉及的主要概念

管理 API：一组允许您以编程方式配置和管理 Prisma Postgres 数据库的端点。
项目与数据库：项目是一个可以容纳多个数据库的容器。您可以使用它来组织您创建的数据库，例如按用户。然后，项目可以转移给用户，包括它们包含的所有数据库。
身份验证：所有 API 请求都需要身份验证。作为合作伙伴，您可以使用服务令牌对配置调用进行身份验证，以便在您的工作区中进行，并在声明流程中使用 OAuth 2 获取用户的访问令牌。
令牌：有两种主要类型的令牌
- 服务令牌：颁发给您的合作伙伴集成，用于在您自己的工作区中配置和管理数据库。
- OAuth 2 访问令牌：当用户通过您的应用程序进行身份验证时，通过 OAuth 2 获取；它仅限于用户的工作区，用于将项目/数据库所有权转移到该工作区。

如何成为合作伙伴

要使用 Prisma Postgres 管理 API，您首先需要设置为合作伙伴

请求访问管理 API：从Prisma 合作伙伴页面联系 Prisma 团队以请求访问管理 API。您将获得入职流程的指导。
获取 OAuth 凭据：您可以在中获取您的 OAuth 凭据。有关详细信息，请参阅下一节。

有关可用端点和请求/响应格式详细信息的完整列表，请参阅Prisma 管理 API 文档。

获取 OAuth 凭据

要获取客户端 ID 和客户端密钥，您需要通过此流程

打开.
点击侧边导航栏中的 🧩 集成选项卡。
在已发布应用程序部分，点击新应用程序按钮以开始创建新 OAuth 应用程序的流程。
为您的 OAuth 应用程序输入名称、描述和回调 URL。
点击继续。

在下一个屏幕上，您可以访问并保存您的 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 工作区中管理它，并超出免费数据库使用限制。这通过声明流程完成，该流程包括三个主要步骤

概述：声明流程的工作原理

当用户想要声明数据库时，您的应用程序将

触发 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 上参与加星收藏存储库、报告问题或为问题做出贡献。

我们真诚地感谢你的参与，并期待你成为我们社区的一部分！

介绍​

核心概念​

如何成为合作伙伴​

获取 OAuth 凭据​

作为合作伙伴供应数据库​

数据库声明流程​

概述：声明流程的工作原理​

1. 触发声明流程​

2. 验证用户​

3. 完成声明流程​

结论​