CKBox REST API

CKBox 提供了 REST API，以便更方便地与您的应用程序集成并实现工作流自动化。它在从其他数字资产管理器迁移、大规模上传或修改资产及其元数据，或您希望在不使用 UI 的情况下与资产交互时非常有用。

使用 REST API，您可以

• 上传和管理 CKBox 中的资产。
• 下载资产。
• 管理您的文件夹。
• 创建资产类别并更改其配置。
• 在文件夹之间移动和复制资产。
• 调整图像大小并自动将其转换为任何支持的格式 (webp、jpeg、png、gif、tiff)。
• 控制 CKBox 生成的图像质量。
• 获取给定用户的最近使用的资产列表。
• 获取和修改资产元数据，例如标签、描述、名称或任何自定义属性。
• 在您的资产中搜索。

参考 CKBox REST API 文档 以了解可用的 REST API 端点。

# 连接到 REST API

# 认证

对 CKBox REST API 的请求认证需要 JWT 令牌。此令牌必须包含在请求的 Authorization 标头中。

要创建用于认证的 JWT 令牌，请使用与在 CKBox 中认证用户的令牌相同的算法。有关令牌、可用字段以及生成 JWT 令牌的算法示例的更多信息，请参考 认证 指南。

在 CKBox REST API 中，某些端点要求令牌中存在 admin 用户角色。要使用所有可用的端点与 API 通信，您应该使用在令牌有效负载中将 auth.ckbox.role 设置为 admin 的令牌。

以下是一个令牌有效负载示例，该示例用于认证发送到 CKBox REST API 的请求，该请求授予对所有端点的访问权限，包括执行管理员用户操作的端点

{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "sub": "example-user-id",
    "iat": 1511963669,
    "auth": {
        "ckbox": {
            "role": "admin"
        }
    }
}

# 有效负载属性

您**必须**在 JWT 令牌有效负载中包含以下属性

• aud – 环境 ID。这是在 CKEditor 生态系统控制面板 中创建的环境的标识符。
• sub – 用户 ID。这是为其签发令牌的用户 的唯一标识符。
• iat – 令牌签发时的时间戳。确保 iat 存在且包含以秒为单位的正确时间。某些 JWT 实现默认情况下不包含它。系统时间也可能无效，导致令牌出现奇怪问题（例如，请参见 Docker for Mac 时间漂移）。
• auth – 定义用户角色的对象。允许的值是 user（用于普通用户）和 admin（用于管理员用户）。

# 发送请求

要与 CKBox 服务交互，请将所有请求发送到 https://api.ckbox.io/ 域。此外，令牌有效负载包含在 aud 字段中传递的有关您的环境 ID 的信息。它使 CKBox 服务能够识别针对您的特定 CKBox 环境的请求。

在本示例中，假设您想要获取 CKBox 实例中可用的所有资产类别的列表。要获取此信息，您可以使用 GET /categories 端点。假设您已经创建了有效的 JWT 令牌来认证请求，则您的请求应如下所示

curl 'https://api.ckbox.io/categories' -H 'Authorization: <jwt_token>'

将 <jwt_token> 占位符替换为您的 JWT 令牌，并将请求发送到 CKBox API 端点。它应该返回一个包含您的 CKBox 环境中的资产类别列表的 JSON。

# 示例应用程序

以下是一段 Node.js 示例代码。该代码使用所需的有效负载签署 JWT 令牌，然后将请求发送到 CKBox REST API 以获取资产类别列表。

在运行此代码之前，请将 <environment_id> 和 <access_key> 替换为在 CKEditor 生态系统控制面板 中获得的环境 ID 和访问密钥。

const jwt = require('jsonwebtoken');
const axios = require('axios');

const ENVIRONMENT_ID = '<your_environment_id>'; // Provide your environment ID.
const ACCESS_KEY = '<your_access_key>';         // Provide your access key.

const getToken = (userId, role) => {
    return jwt.sign(
        {
            aud: ENVIRONMENT_ID,
            sub: userId,
            auth: {
                ckbox: {
                    role
                }
            }
        },
        ACCESS_KEY,
        {
            algorithm: 'HS256'
        }
    );
};

axios.get('https://api.ckbox.io/categories', {
        headers: {
            Authorization: getToken('dummy-admin-id', 'admin')
        }
    })
    .then(response => console.dir(response.data, { depth: 5 }))
    .catch(error => console.error(error.response.data));

有关完整的可运行示例，请参考 CKBox 代码示例存储库。