创建数据库

适用场景

当你要新建数据库并同时定义字段 schema 时使用这个接口。它适合先搭建数据结构，再开始写入记录。你可以把数据库创建在某个页面下，也可以省略 parent 创建到当前工作区根目录。

接口信息

权限要求

需要 databases.write。

请求参数

请求头

请求体

请求体示例：

{
  "parent": {
    "page_id": "55555555-5555-4555-8555-555555555555"
  },
  "title": [
    {
      "type": "text",
      "text": {
        "content": "任务看板"
      }
    }
  ],
  "properties": {
    "Name": {
      "name": "Name",
      "type": "title"
    },
    "Status": {
      "name": "Status",
      "type": "select",
      "select": {
        "options": [
          { "name": "To Do", "color": "grey" },
          { "name": "Doing", "color": "yellow" },
          { "name": "Done", "color": "green" }
        ]
      }
    }
  }
}

响应结果

{
  "object": "database",
  "id": "66666666-6666-4666-8666-666666666666",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "任务看板",
        "link": null
      },
      "plain_text": "任务看板",
      "href": null
    }
  ],
  "parent": {
    "type": "page_id",
    "page_id": "55555555-5555-4555-8555-555555555555"
  },
  "properties": {
    "Name": {
      "id": "title",
      "type": "title",
      "name": "Name"
    },
    "Status": {
      "id": "16161616-1616-4616-8616-161616161616",
      "type": "select",
      "name": "Status"
    }
  },
  "in_trash": false,
  "is_inline": false
}

行为说明或限制

• 要在页面内创建数据库，请显式传入 parent.page_id。
• 不传 parent 时，会在当前 token 所属工作区的根目录下创建数据库。
• properties 是必填项，并且必须包含至少一个标题属性。
• properties 描述的是 schema，不是记录值。
• is_inline 决定数据库是内嵌形式还是独立页面形式。

错误提示

• 400 validation_error：properties 为空，或缺少标题属性。
• 401 unauthorized：token 无效或已过期。
• 403 forbidden：缺少 databases.write 或无权访问父页面。
• 404 not_found：父页面不存在。

相关文档

前置阅读

• 获取页面

下一步

• 获取数据库
• 查询数据库

相关参考

• 页面属性模型