docs/docs/cn/integration/api-keys/usage.md
本指南通过实际的"待办事项"示例，演示如何在 NocoBase 中使用 API 密钥来获取数据。请按照以下分步说明理解完整的工作流程。
API 密钥是一种安全令牌，用于验证来自授权用户的 API 请求。它作为凭据，在通过 Web 应用程序、移动应用或后端脚本访问 NocoBase 系统时验证请求者的身份。
在 HTTP 请求头中的格式：
Authorization: Bearer {API 密钥}
"Bearer" 前缀表示后面跟随的是用于验证请求者权限的已认证 API 密钥。
API 密钥通常用于以下场景：
API 密钥提供多重安全优势：身份验证、使用监控、请求速率限制和威胁防范，确保 NocoBase 的稳定和安全运行。
确保已启用内置的认证：API 密钥插件。启用后，系统设置中将出现新的 API 密钥配置页面。
为演示目的，创建一个名为 todos 的数据表，包含以下字段：
id标题（title）是否完成（completed）向数据表中添加一些示例记录：
API 密钥绑定到用户角色，系统根据分配的角色确定请求权限。在创建 API 密钥之前，必须创建角色并配置适当的权限。创建名为"待办 API 角色"的角色，并授予其对 todos 数据表的完全访问权限。
如果创建 API 密钥时"待办 API 角色"不可用，请确保当前用户已被分配此角色：
分配角色后，刷新页面并导航到 API 密钥管理页面。点击"添加 API 密钥"以验证"待办 API 角色"出现在角色选择中。
为了更好的访问控制，可以考虑创建专用的用户账号（例如"待办 API 用户"）专门用于 API 密钥管理和测试。将"待办 API 角色"分配给此用户。
提交表单后，系统将显示确认消息和新生成的 API 密钥。重要提示：立即复制并安全存储此密钥，出于安全原因，该密钥不会再次显示。
API 密钥示例：
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M
APP_KEY 环境变量。请勿修改此变量，否则将使系统中所有现有 API 密钥失效。打开 API 文档插件，查看每个 API 端点的请求方法、URL、参数和请求头。
NocoBase 提供标准的 CRUD（创建、读取、更新、删除）API 用于数据操作：
列表查询（list 接口）：
GET {baseURL}/{collectionName}:list
请求头：
- Authorization: Bearer <API密钥>
新增记录（create 接口）：
POST {baseURL}/{collectionName}:create
请求头：
- Authorization: Bearer <API密钥>
请求体（JSON格式），例如：
{
"title": "123"
}
修改记录（update 接口）：
POST {baseURL}/{collectionName}:update?filterByTk={id}
请求头：
- Authorization: Bearer <API密钥>
请求体（JSON格式），例如：
{
"title": "123",
"completed": true
}
删除记录（delete 接口）：
POST {baseURL}/{collectionName}:destroy?filterByTk={id}
请求头：
- Authorization: Bearer <API密钥>
其中：
{baseURL}：NocoBase 系统 URL{collectionName}：数据表名称示例：本地实例 localhost:13000，数据表名称 todos：
http://localhost:13000/api/todos:list
在 Postman 中创建 GET 请求，配置如下：
http://localhost:13000/api/todos:list）Authorization 请求头，值为：Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M
成功响应：
{
"data": [
{
"createdAt": "2025-03-03T09:57:36.728Z",
"updatedAt": "2025-03-03T09:57:36.728Z",
"completed": null,
"createdById": 1,
"id": 1,
"title": "eat food",
"updatedById": 1
}
],
"meta": {
"count": 1,
"page": 1,
"pageSize": 20,
"totalPage": 1
}
}
错误响应（无效/过期的 API 密钥）：
{
"errors": [
{
"message": "Your session has expired. Please sign in again.",
"code": "INVALID_TOKEN"
}
]
}
故障排除：如果认证失败，请验证角色权限、API 密钥绑定和令牌格式。
Postman 允许以各种格式导出请求。cURL 命令示例：
curl --location 'http://localhost:13000/api/todos:list' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M'
NocoBase 2.0 支持在页面中使用 JS 区块直接编写原生 JavaScript 代码。此示例演示如何使用 API 密钥获取外部 API 数据。
在 NocoBase 页面中添加 JS 区块，使用以下代码获取待办事项数据：
// 使用 API 密钥获取待办事项数据
async function fetchTodos() {
try {
// 显示加载提示
ctx.message.loading('正在获取数据...');
// 加载 axios 库用于 HTTP 请求
const axios = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/[email protected]/dist/axios.min.js');
if (!axios) {
ctx.message.error('加载 HTTP 库失败');
return;
}
// API 密钥（替换为您实际的 API 密钥）
const apiKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M';
// 发起 API 请求
const response = await axios.get('http://localhost:13000/api/todos:list', {
headers: {
'Authorization': `Bearer ${apiKey}`
}
});
// 显示结果
console.log('待办事项列表:', response.data);
ctx.message.success(`成功获取 ${response.data.data.length} 条数据`);
// 您可以在此处理数据
// 例如：显示到表格、更新表单字段等
} catch (error) {
console.error('获取数据出错:', error);
ctx.message.error('获取数据失败: ' + error.message);
}
}
// 执行函数
fetchTodos();
Authorization 请求头中传递 API 密钥，使用 Bearer 前缀本指南涵盖了在 NocoBase 中使用 API 密钥的完整工作流程：
其他资源：