Notion数据库查询API概览
notion api提供了强大的数据库查询能力，允许开发者通过post /v1/databases/{database_id}/query端点获取特定数据库中的数据。这个端点支持复杂的过滤、排序和分页操作，使得数据检索高度灵活。然而，正确构建请求体是成功执行这些操作的关键。
常见问题：过滤条件未生效
许多开发者在使用PHP cURL向Notion API发送数据库查询请求时，可能会遇到一个普遍问题：尽管请求成功并返回了数据，但预期的过滤条件似乎没有生效，API返回了整个数据库的内容，而非筛选后的结果。
例如，开发者可能尝试直接将过滤条件（如按property和title进行匹配）作为请求体的主体发送：
// 错误的过滤条件构建方式
$data_array =
[
"property"=>"DataElement",
"title"=>["equals"=>"bigHouse"]
];
$data = json_encode($data_array);
// 此时 $data 的 JSON 形式为：
// {"property":"DataElement","title":{"equals":"bigHouse"}}在这种情况下，尽管JSON格式看起来正确，并且包含所需的过滤信息，但Notion API并不会将其识别为有效的过滤指令，因为它不符合API的预期结构。
解决方案：正确构建过滤请求体
Notion API明确规定，所有用于筛选数据库数据的条件都必须封装在一个名为filter的顶层键下。这意味着，您定义的property、title（或其他属性类型）以及它们的匹配规则，都应该作为filter键的值。
立即学习“PHP免费学习笔记（深入）”；
正确的请求体结构应如下所示：
// 正确的过滤条件构建方式
$data_array =
[
'filter' =>
[
"property"=>"DataElement",
"title"=>["equals"=>"bigHouse"]
]
];
$data = json_encode($data_array);
// 此时 $data 的 JSON 形式为：
// {"filter":{"property":"DataElement","title":{"equals":"bigHouse"}}}通过将过滤逻辑嵌套在filter键中，Notion API才能正确解析并应用您的筛选条件。
完整的PHP cURL查询示例
以下是一个完整的PHP cURL代码示例，演示了如何正确构建请求体并向Notion API发送查询：
[
"property"=>"DataElement", // 您的Notion数据库中标题列的名称
"title"=>["equals"=>"bigHouse"] // 筛选条件：标题等于 "bigHouse"
]
];
$data = json_encode($data_array);
// 初始化cURL
$ch = curl_init();
// 设置cURL选项
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 返回响应内容而不是直接输出
curl_setopt($ch, CURLOPT_POST, true); // 设置为POST请求
curl_setopt($ch, CURLOPT_POSTFIELDS, $data); // 设置POST请求体数据
// 设置HTTP头，包括认证信息和API版本
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $token,
'Content-Type: application/json', // 明确指定请求体为JSON
'Notion-Version: ' . $version
));
// 禁用SSL证书验证 (在生产环境中不推荐，仅用于开发或调试)
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
// 执行cURL请求
$resp = curl_exec($ch);
// 检查cURL错误
if ($e = curl_error($ch)) {
echo "cURL Error: " . $e;
} else {
// 解码JSON响应
$decoded = json_decode($resp, true);
var_dump($decoded); // 打印解码后的数据
}
// 关闭cURL句柄
curl_close($ch);
?>Notion API过滤条件的更多细节
Notion API支持多种属性类型的过滤，包括：
- title: 针对标题属性。
- text: 针对富文本属性。
- number: 针对数字属性，支持equals, greater_than, less_than等。
- checkbox: 针对复选框属性，支持equals。
- select / multi_select: 针对选择/多选属性，支持equals, contains等。
- date: 针对日期属性，支持on_or_before, on_or_after, past_week等。
- 以及更多其他属性类型，如people, files, url等。
每种属性类型都有其特定的过滤操作符。强烈建议查阅Notion官方API文档中关于查询数据库的部分，以获取最详细和最新的过滤选项。
注意事项与最佳实践
- API版本控制: 在HTTP头中指定Notion-Version非常重要，这确保您的请求与特定版本的API行为兼容。
- 认证令牌: Authorization: Bearer YOUR_NOTION_INTEGRATION_TOKEN是必需的。请确保您的集成令牌具有访问目标数据库的权限。
- Content-Type: 虽然cURL在发送JSON数据时通常会自动设置Content-Type: application/json，但显式指定可以避免潜在问题。
- 错误处理: 始终检查curl_exec的返回值和curl_error，以便及时发现并解决网络或请求配置问题。
- JSON解码: Notion API响应是JSON格式，使用json_decode($resp, true)将其转换为PHP关联数组便于处理。
- SSL验证: 在生产环境中，应启用SSL证书验证（移除CURLOPT_SSL_VERIFYHOST和CURLOPT_SSL_VERIFYPEER的设置或将其设为默认值），以确保数据传输的安全性。
- 其他查询参数: 除了filter，Notion API还支持sorts（排序）、start_cursor（分页起始点）和page_size（每页结果数量）等参数，它们也应作为filter的同级键放置在请求体的顶层。
总结
正确构建Notion API数据库查询的POST请求体，特别是将过滤条件封装在filter键下，是成功获取所需数据的关键。通过遵循Notion API的规范，并结合PHP cURL的强大功能，开发者可以高效、精确地与Notion数据库进行交互，构建出功能丰富的应用程序。务必参考官方文档，以充分利用Notion API提供的所有高级查询特性。
