理解Notion API数据库查询
notion api提供了强大的数据库查询能力，允许开发者通过post /v1/databases/{database_id}/query端点检索数据库中的页面。这个端点支持复杂的过滤和排序逻辑，但前提是请求体（request body）的结构必须严格遵循notion api文档的规定。
当我们需要根据特定属性（如标题、文本、数字等）来筛选数据库条目时，所有的过滤条件都必须嵌套在一个名为filter的顶级键之下。如果过滤条件直接作为请求体的根元素，Notion API可能会将其忽略，从而返回数据库中的所有数据，而不是期望的过滤结果。
错误的请求体结构示例
在尝试查询Notion数据库时，一个常见的错误是将过滤条件直接放置在请求体的根级别，例如：
// 错误的请求数据结构示例
$data_array =
[
"property"=>"DataElement",
"title"=>["equals"=>"bigHouse"]
];
$data = json_encode($data_array);
// 此时 $data 的输出可能为：{"property":"DataElement","title":{"equals":"bigHouse"}}
// 这种结构不符合Notion API的过滤要求尽管json_encode后的字符串看起来是有效的JSON，并且包含了property和title等过滤关键字，但由于它们没有被filter键包裹，Notion API会将其视为无效的过滤参数，从而返回数据库中的所有条目。
正确的请求体结构
根据Notion API的文档，所有过滤条件都必须封装在filter键之下。对于一个简单的属性过滤，例如查询名为"DataElement"的标题属性等于"bigHouse"的条目，正确的$data_array结构应该如下：
立即学习“PHP免费学习笔记（深入）”；
// 正确的请求数据结构
$data_array =
[
'filter' =>
[
"property"=>"DataElement",
"title"=>["equals"=>"bigHouse"]
]
];
$data = json_encode($data_array);
// 此时 $data 的输出为：{"filter":{"property":"DataElement","title":{"equals":"bigHouse"}}}
// 这种结构才能被Notion API正确解析并执行过滤PHP cURL实现Notion数据库查询与过滤
下面是一个完整的PHP cURL示例，展示了如何使用正确的请求体结构来查询并过滤Notion数据库：
[
"property"=>"DataElement", // 要过滤的属性名称
"title"=>["equals"=>"bigHouse"] // 过滤条件：标题等于 "bigHouse"
]
];
$data = json_encode($data_array); // 将PHP数组编码为JSON字符串
// 初始化cURL会话
$ch = curl_init();
// 设置cURL选项
curl_setopt($ch, CURLOPT_URL, $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, // API认证令牌
'Notion-Version: ' . $version, // 指定Notion API版本
'Content-Type: application/json' // 声明请求体为JSON格式
));
// 注意：以下两行用于禁用SSL证书验证，仅在开发或特定环境下使用，
// 生产环境中强烈建议启用并正确配置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);
echo "查询结果:
";
var_dump($decoded); // 打印解码后的数据
}
// 打印发送的原始JSON数据（用于调试）
echo "
发送的JSON数据:
";
echo $data;
// 关闭cURL会话
curl_close($ch);
?>注意事项与最佳实践
- API文档是黄金法则： 始终参考Notion官方API文档（https://developers.notion.com/reference/post-database-query）来了解最新的请求体结构、过滤选项和数据类型。Notion API支持多种复杂的过滤条件，如组合过滤（and/or）、数字过滤、日期过滤、复选框过滤等，所有这些都应嵌套在filter键下。
- 安全性：
- 错误处理：
- Content-Type头： 确保在HTTP头部中设置Content-Type: application/json，告知Notion API请求体是JSON格式。
- Notion-Version头： 指定Notion-Version头是最佳实践，它确保您的请求与特定API版本兼容，避免未来API更新可能导致的不兼容问题。
总结
通过Notion API查询数据库并实现过滤的关键在于正确构造请求体。核心要点是将所有过滤条件封装在一个名为filter的顶级JSON键中。遵循Notion API文档的规范，并结合PHP cURL的正确使用，开发者可以高效且精确地从Notion数据库中检索所需数据。同时，在实际应用中，务必重视API令牌的安全性以及SSL证书的验证，以构建健壮和安全的集成方案。
