> This page is for Camera to Cloud.
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.
# 集成架构
## 前言
在开始发起 API 请求之前，您需要了解 C2C 集成的基本架构。 （别担心——在下一篇文章中，您将会在终端实际操作。 现在，我们先了解这些基本概念。）
您的集成所对应的简化数据模型大致如下所示：
```text
┌───────────────────┐ ┌─────────┐
│ Project Device 01 │ -> │ Project │
┌───────────┐ ┌──────────────┐ └───────────────────┘ └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘ └──────────────┘ ┌───────────────────┐ ┌─────────┐
│ Project Device 02 │ -> │ Project │
└───────────────────┘ └─────────┘
```
## OAuth 应用程序
您的集成由 OAuth 应用程序来定义，OAuth 应用程序是我们在后端注册的一个实体，它允许您的设备使用 [OAuth 2](https://oauth.net/2/) 向 Frame.io 进行授权。 您的 OAuth 应用程序定义了整个集成的授权策略。 用户连接到 Frame.io 的每台设备都将通过同一个 OAuth 应用程序进行授权（不过，拥有多条设备产品线的集成商可能希望为每条产品线分别配备一个 OAuth 应用程序）。
对于 C2C 集成，我们使用一种专门为 UI 功能有限的设备设计的专用 OAuth 流程。
### C2C 设备身份验证
C2C API 专为 UI 功能有限的设备而设计。 这些设备通过显示一个 6 位数字代码，让用户使用自己的浏览器在 Frame.io 网站上输入该代码，从而将设备连接到 Frame.io。
设备会收到一个 `client_secret`，必须将其提供给我们的后端，才能接收一个 6 位数的授权代码。 这种简化的方法确保了在所有 C2C 集成中都能获得一致且安全的身份验证体验。
## 设备模型
设备模型用于配置您的设备在与 C2C 后端交互时的行为方式，包括它所支持的功能。 以下设置由您的设备模型进行配置：
集成是使用低延迟套接字来传达其当前状态，还是使用高延迟的 REST 调用。
您的集成名称，将显示在任何已上传资产的路径中。
C2C 仅允许将资产上传到特定的根文件路径，但在此要求之下，您的设备可以配置为根据资产提供的元数据，将资产上传到动态计算得出的文件路径。
当您将资产上传到 Frame.io 时，需要哪些元数据，其中最重要的是为了支持令牌化文件路径。
集成是使用低延迟套接字来传达其当前状态，还是使用高延迟的 REST 调用。
您的设备所支持的功能可能会因固件版本不同而变化。 为了实现向后兼容性和干净的用户体验——设备的配置会根据检测到的固件版本动态选择。 在不久的将来，一个集成将能够拥有多个设备模型。 具体使用哪个设备模型，需通过将设备的固件版本与特定设备模型的最低固件版本要求进行比较来确定。
## 项目设备与标识
`ProjectDevice` 表示连接到 Frame.io 的每一个物理设备实例。 `ProjectDevice` 使用名为 `client_id` 的唯一标识值来标识自身。 此值应该保证不会在两台设备之间共享。 它可以是设备的序列号，也可以是设备生成一次并保存的随机字符串。 `client_id` 应该是您的设备拥有的值，例如计算机的 MAC 地址。
我们的后端会跟踪每个项目设备并保存相关信息，例如其当前的固件版本。
每个 `ProjectDevice` 都将关联一个特定的 Frame.io `Project` 以及一个 `OauthAuthorization`（用于授予设备对项目的访问权限），还有一组详细说明设备可以执行哪些操作的权限范围。 有关可用权限范围的更多信息，请参阅实施身份验证和授权的详细指南。 `ProjectDevice` 是由 `/me` 端点返回的内容。 一个 `Device` 一次只能主动关联到一个 `ProjectDevice`，因此一次也就只能关联到一个 `Project`。
## 固件版本
每当您调用 `https://api.frame.io` 上的端点时，您的设备都必须在 `x-client-version` HTTP 标头中提供当前的固件版本。 后续的 API 指南将在每个示例中包含此标头。 在某些情况下，我们的后端必须对多个固件版本进行排序，为了支持这一点，我们要求这些值必须是有效的[语义化版本](https://semver.org/)。 这些值包括 `0.1.2`、`2.1.3-preview.01` 和 `2.1.3-preview.01+build_19770504.01` 等。
如果固件版本值不是有效的语义化版本，将返回错误。 我们理解并非所有集成都使用语义化版本来跟踪其固件，在这种情况下，我们希望您为所创建的每个内部版本跟踪一个语义化版本，用于提供给我们的后端。
通过提供此标头，您固件的不同版本可以在 Frame.io 内部支持不同（有时甚至是相互冲突的）功能。
固件版本仅通过调用 https://api.frame.io 来处理，在调用 https://applications.frame.io 时，该标头不起作用。
`x-client-version` 现在是一个必需的 HTTP 标头，将由 Frame 服务器强制执行。
## 后续步骤
是时候发起一些 API 调用了！ 让我们了解如何使用 C2C 进行身份验证和授权。 请按照[设置指南](./implementing-c2c-setting-up)开始操作。