深入理解Notion API数据库查询过滤
在使用php与notion api交互，特别是进行数据库查询（post /databases/{database_id}/query）时，开发者常会遇到一个常见问题：即使在请求体中包含了过滤条件，api却似乎忽略了这些条件，并返回了数据库中的所有数据。这通常不是连接问题，也不是认证问题，而是请求体（payload）结构不符合notion api规范所致。
Notion API的官方文档明确指出，对于数据库查询请求，任何过滤条件都必须嵌套在一个名为filter的顶级JSON键之下。如果过滤条件直接作为请求体的根元素，API将无法正确解析这些条件，从而导致过滤无效。
常见错误示例
以下是一个典型的错误请求体结构，它将导致过滤失败：
"DataElement", // 试图直接指定属性和过滤条件 "title" => ["equals" => "bigHouse"] ]; $data = json_encode($data_array); // ... cURL请求设置省略 ... // 此时，Notion API会返回数据库中所有条目，而不是只包含"bigHouse"的条目。 ?>
在上述代码中，"property"和"title"直接作为$data_array的根键。虽然从JSON语法上看是合法的，但Notion API要求这些过滤逻辑必须包裹在"filter"键内。
立即学习“PHP免费学习笔记（深入）”；
正确实现Notion API数据库过滤
要正确地向Notion API发送带有过滤条件的数据库查询请求，关键在于将所有过滤逻辑封装在一个名为filter的键中。
正确的过滤数据结构
根据Notion API文档，正确的请求体结构应如下所示：
{
"filter": {
"property": "Landmark",
"text": {
"contains": "Bridge"
}
}
}将其转换为PHP数组，并用于cURL请求时，应这样构造$data_array：
[ // 所有的过滤条件都必须嵌套在'filter'键下
"property" => "DataElement",
"title" => ["equals" => "bigHouse"] // 过滤条件：Title类型属性等于"bigHouse"
]
];
$data = json_encode($data_array);
// ... cURL请求设置省略 ...
?>这个修正确保了Notion API能够识别并应用你提供的过滤条件。
完整的PHP数据库查询示例
下面是一个完整的PHP代码示例，演示如何使用cURL向Notion API发送带有正确过滤条件的数据库查询请求：
[
"property" => "DataElement", // Notion数据库中的属性名称
"title" => ["equals" => "bigHouse"] // 过滤条件：Title类型属性等于"bigHouse"
]
// 可以添加其他参数，例如 "sorts", "start_cursor", "page_size" 等
];
$data = json_encode($data_array); // 将PHP数组编码为JSON字符串
// 3. 初始化cURL会话
$ch = curl_init();
// 4. 设置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头，包括认证令牌和Notion API版本
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $token,
'Notion-Version: ' . $version,
'Content-Type: application/json' // 明确指定请求体类型为JSON
));
// 针对开发环境，可以禁用SSL验证（不推荐在生产环境使用）
// curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
// 5. 执行cURL请求
$resp = curl_exec($ch);
// 6. 错误处理与结果解析
if ($e = curl_error($ch)) {
echo "cURL Error: " . $e;
} else {
$decoded = json_decode($resp, true);
// 打印或处理API响应数据
echo "";
var_dump($decoded);
echo "";
// 可以将结果保存到文件
// file_put_contents('notion_query_results.json', json_encode($decoded, JSON_PRETTY_PRINT));
}
// 7. 关闭cURL会话
curl_close($ch);
?>注意事项与最佳实践
-
filter 键的必要性：始终记住，所有的过滤条件都必须封装在请求体的顶级 filter 键中。这是Notion API的特定要求。
-
Notion-Version 头：在HTTP请求头中指定 Notion-Version 是非常重要的。它确保你的请求与特定版本的API行为保持一致，避免因API更新导致的不兼容问题。建议使用官方文档中推荐的最新稳定版本。
-
Content-Type 头：虽然cURL有时会自动设置，但明确指定 Content-Type: application/json 是一个良好的实践，它告知服务器请求体是JSON格式。
-
错误处理：务必使用 curl_error($ch) 来检查cURL执行过程中是否发生错误。这对于调试网络请求问题至关重要。
-
安全性：你的Notion集成令牌（$token）和数据库ID（$databaseId）是敏感信息。在生产环境中，切勿将其硬编码在公开可访问的代码中，应通过环境变量或其他安全配置方式进行管理。
-
过滤条件匹配：确保 property 的名称与Notion数据库中实际的属性名称完全匹配，并且其内部的过滤类型（如 title, text, number, checkbox 等）及其操作符（如 equals, contains, greater_than 等）与该属性的数据类型兼容。详细的过滤选项请参考Notion API官方文档。
-
Notion API文档：Notion API功能强大且不断更新。遇到任何疑问时，查阅官方文档（https://www.php.cn/link/8becabfd3781cac86c0988f11d76e690）是解决问题的最佳途径。
总结
通过本文的详细讲解和示例代码，我们明确了使用PHP与Notion API进行数据库查询时，正确实现数据过滤的关键在于将过滤条件封装在请求体中的 filter 顶级键下。遵循这一规范，并结合适当的cURL设置和错误处理，开发者可以有效地利用Notion API的强大过滤功能，精确地获取所需数据。
