Notion API数据库查询：PHP cURL过滤参数的正确实践
Notion API 为开发者提供了强大的能力，以编程方式与 Notion 页面和数据库进行交互。其中，数据库查询（Query a database）是最核心的功能之一，它允许我们根据特定条件筛选和排序数据库中的条目。在PHP中，我们通常使用cURL库来发起HTTP请求。本文将深入探讨如何正确构建和使用cURL请求，特别是如何设置复杂的过滤参数（filter）来精准地查询Notion数据库。
一、准备工作
在开始之前，请确保你已具备以下条件：
一个Notion集成（Integration），并已获取其内部集成令牌（Internal Integration Token）。
一个已与你的集成共享的Notion数据库ID。
PHP环境已启用cURL扩展。
二、理解Notion API的过滤参数结构
Notion API的数据库查询端点 POST https://api.notion.com/v1/databases/{database_id}/query 接受一个JSON格式的请求体。过滤逻辑主要通过 filter 和 sorts 属性实现。 filter 属性是一个对象，其结构取决于你要过滤的属性类型。
常见的过滤类型包括：
按文本属性过滤：使用
contains,does_not_contain,equals,does_not_equal,starts_with,ends_with等条件。按数字/选择属性过滤：使用
equals,does_not_equal,greater_than,less_than等条件。按日期属性过滤：使用
equals,before,after,on_or_before,on_or_after,past_week,next_month等条件。复合过滤：使用
and或or来组合多个条件。
三、使用PHP cURL构建查询请求
核心步骤是构建正确的请求头、请求体（包含过滤参数），并使用cURL发送POST请求。
<?php
// 配置信息
$notionApiKey = '你的Notion集成密钥_secret_xxx';
$databaseId = '你的数据库ID';
$apiUrl = "https://api.notion.com/v1/databases/{$databaseId}/query";
// 定义过滤条件：查找“状态”为“进行中”且“优先级”为“高”的条目
$filterPayload = [
'filter' => [
'and' => [
[
'property' => '状态',
'select' => [
'equals' => '进行中'
]
],
[
'property' => '优先级',
'select' => [
'equals' => '高'
]
]
]
],
// 可选：排序规则
'sorts' => [
[
'property' => '最后编辑时间',
'direction' => 'descending'
]
]
];
// 初始化cURL会话
$ch = curl_init();
// 设置cURL选项
curl_setopt_array($ch, [
CURLOPT_URL => $apiUrl,
CURLOPT_RETURNTRANSFER => true, // 将响应作为字符串返回
CURLOPT_POST => true, // 使用POST方法
CURLOPT_POSTFIELDS => json_encode($filterPayload), // 将过滤参数编码为JSON
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $notionApiKey,
'Notion-Version: 2022-06-28', // 使用稳定的API版本
'Content-Type: application/json'
],
]);
// 执行请求并获取响应
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// 检查cURL错误
if (curl_errno($ch)) {
echo 'cURL错误: ' . curl_error($ch);
curl_close($ch);
exit;
}
// 关闭cURL资源
curl_close($ch);
// 处理响应
if ($httpCode >= 200 && $httpCode < 300) {
$data = json_decode($response, true);
// 处理查询结果 $data['results']
echo "查询成功，找到 " . count($data['results']) . " 条记录。n";
// 可以遍历 $data['results'] 来处理每条页面数据
} else {
echo "API请求失败，状态码: {$httpCode}n";
echo "响应内容: {$response}n";
}
?>四、复杂过滤条件示例
下面是一个更复杂的例子，它组合了多种过滤类型和逻辑运算符。
<?php
// ... (cURL初始化和头部配置与上例相同)
// 复杂过滤：查找标题包含“报告”，且（截止日期在今天之后 或 状态不是“已完成”）的条目
$complexFilter = [
'filter' => [
'and' => [
[
'property' => '标题',
'title' => [
'contains' => '报告'
]
],
[
'or' => [
[
'property' => '截止日期',
'date' => [
'after' => date('Y-m-d') // 今天之后
]
],
[
'property' => '状态',
'select' => [
'does_not_equal' => '已完成'
]
]
]
]
]
]
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($complexFilter));
// ... (执行请求和处理响应的代码与上例相同)
?>五、关键注意事项与最佳实践
1. API版本
务必在请求头中指定 Notion-Version。Notion API仍在演进中，使用固定版本（如 2022-06-28）可以确保代码的稳定性，避免因API更新而意外失效。
2. 属性名称与类型
过滤条件中的 property 值必须是数据库中属性（列）的确切名称。内部的 type（如 title, select, date, number）必须与Notion中该属性的类型完全匹配。你可以先调用 GET https://api.notion.com/v1/databases/{database_id} 来获取数据库的完整结构。
3. JSON编码与转义
使用 json_encode 将PHP数组转换为JSON字符串。确保你的PHP数组结构完全符合Notion API的规范。对于包含特殊字符的属性名或值， json_encode 会自动处理转义。
4. 分页处理
Notion API的查询结果可能分页返回。如果响应中包含 has_more: true 和 next_cursor，你需要在后续请求的请求体中添加 start_cursor 参数来获取下一页数据。
// 分页查询示例片段 $payload = [ 'filter' => [...], 'start_cursor' => $nextCursorFromPreviousResponse // 从上一轮响应中获取 ];
5. 错误处理
始终检查HTTP状态码和响应内容。Notion API会返回描述性的错误信息，例如无效的属性名或过滤条件格式错误，这对于调试至关重要。
六、总结
通过PHP cURL调用Notion API进行数据库查询，关键在于正确构造表示过滤逻辑的JSON请求体。理解Notion属性类型与过滤操作符的对应关系，并熟练使用 and/or 进行条件组合，能够实现极其灵活的数据检索。遵循设置正确的请求头、使用稳定的API版本、进行充分的错误处理等最佳实践，可以构建出健壮、高效的Notion集成应用。