Notion API数据库查询基础
notion api提供了强大的功能，允许开发者通过编程方式与notion数据库进行交互。其中，查询数据库是获取特定数据集的关键操作。notion api通过 post /v1/databases/{database_id}/query 端点支持数据库查询，并允许在请求体中指定复杂的过滤条件和排序规则。
一个典型的Notion数据库查询请求体（Payload）通常包含以下主要部分：
- filter (可选): 用于定义查询结果的过滤条件。
- sorts (可选): 用于定义查询结果的排序规则。
- start_cursor (可选): 用于分页查询的起始游标。
- page_size (可选): 每页返回的条目数量。
本文将重点关注filter参数的正确使用，这是实现精确数据检索的核心。
常见问题：过滤条件未生效
在使用PHP cURL向Notion API发送数据库查询请求时，一个常见的误区是将过滤条件直接作为请求体的顶层属性发送，例如：
{
"property": "DataElement",
"title": {
"equals": "bigHouse"
}
}尽管上述JSON结构看起来符合Notion API文档中关于单个过滤对象的描述，但当它作为整个请求体发送时，Notion API会将其视为无效的过滤参数，并返回整个数据库的内容，而不是根据条件过滤后的数据。这是因为Notion API要求所有过滤逻辑都必须封装在一个顶层的filter参数内。
立即学习“PHP免费学习笔记（深入）”；
解决方案：正确封装过滤参数
要使Notion API的过滤条件生效，必须将所有的过滤规则嵌套在一个名为filter的JSON对象中。正确的请求体结构应如下所示：
{
"filter": {
"property": "DataElement",
"title": {
"equals": "bigHouse"
}
}
}在这个结构中，filter是顶层键，其值是一个包含实际过滤条件的JSON对象。property指定了要过滤的数据库属性名称，而其后的对象（例如"title": {"equals": "bigHouse"}）则定义了具体的过滤逻辑，这里是查找标题属性等于"bigHouse"的条目。
PHP cURL实现详解
在PHP中，我们可以使用cURL库来构建和发送HTTP请求。以下是构建一个正确过滤Notion数据库的PHP cURL请求的详细步骤和代码示例。
1. 构建请求数据
首先，我们需要构建一个PHP数组，它将转换为符合Notion API要求的JSON请求体。关键在于将过滤条件放在filter键下。
[
"property" => "DataElement", // 数据库属性名
"title" => [ // 属性类型为Title的过滤条件
"equals" => "bigHouse" // 标题等于"bigHouse"
]
]
];
// 将PHP数组转换为JSON字符串
$data = json_encode($data_array);
// ... (后续cURL请求代码)
?>2. 初始化并配置 cURL
接下来，初始化cURL会话并设置必要的请求选项，包括URL、请求方法、请求头和请求体。
3. 发送请求与错误处理
发送cURL请求并处理可能出现的错误，然后解析Notion API返回的JSON响应。
";
var_dump($decoded); // 打印解码后的响应数据
echo "";
} else {
echo "JSON Decode Error: " . json_last_error_msg();
echo "Raw Response: " . $resp;
}
}
// 关闭cURL会话
curl_close($ch);
?>完整代码示例
[
"property" => "DataElement", // 替换为您的Notion数据库属性名
"title" => [ // 假设 'DataElement' 属性类型为 'Title'
"equals" => "bigHouse" // 查找标题等于 "bigHouse" 的条目
]
]
];
// 将PHP数组转换为JSON字符串
$data = json_encode($data_array);
// --- 初始化并配置 cURL ---
$ch = curl_init();
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请求头
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $token, // 认证令牌
'Notion-Version: ' . $version, // API版本
'Content-Type: application/json' // 明确指定请求体为JSON
));
// --- SSL 验证设置 (生产环境强烈建议启用) ---
// 在开发环境中，为避免SSL证书验证问题，有时会禁用以下选项。
// 生产环境中应始终启用以确保安全。
// curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
// 如果您的环境SSL证书有问题，可以暂时禁用（不推荐在生产环境）：
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
// --- 执行请求并处理响应 ---
$resp = curl_exec($ch);
if ($e = curl_error($ch)) {
echo "cURL Error: " . $e;
} else {
$decoded = json_decode($resp, true);
if (json_last_error() === JSON_ERROR_NONE) {
echo "Notion API Query Result:
";
echo "";
var_dump($decoded);
echo "";
// 可以进一步处理 $decoded['results'] 来获取实际的数据库条目
} else {
echo "JSON Decode Error:
";
echo "Error: " . json_last_error_msg() . "
";
echo "Raw Response: " . htmlspecialchars($resp);
}
}
// --- 关闭 cURL 会话 ---
curl_close($ch);
?>注意事项与最佳实践
-
API 版本控制: Notion API会不断更新，请务必在Notion-Version请求头中指定您所使用的API版本。建议查阅Notion官方文档，使用最新的稳定版本。
-
API 密钥安全: 您的Notion集成令牌（$token）是敏感信息，切勿直接暴露在客户端代码或版本控制系统中。在生产环境中，应将其存储在环境变量、配置文件或密钥管理服务中。
-
错误诊断: 始终检查cURL执行结果 (curl_error) 和JSON解码结果 (json_last_error)，这对于调试至关重要。Notion API的响应体中通常会包含详细的错误信息。
-
SSL 验证: 在生产环境中，务必启用cURL的SSL验证 (CURLOPT_SSL_VERIFYHOST 和 CURLOPT_SSL_VERIFYPEER)。禁用SSL验证会使您的应用程序面临安全风险。
-
扩展过滤条件类型: Notion API支持多种过滤条件，例如text、number、checkbox、date、select、multi_select等。每种类型都有其特定的操作符（如equals, contains, greater_than, is_empty等）。您可以根据Notion官方文档构建更复杂的过滤逻辑。例如，过滤文本属性Description包含"important"的条目：
'filter' => [
"property" => "Description",
"text" => [
"contains" => "important"
]
]
-
分页处理: 当数据库包含大量数据时，Notion API会分页返回结果。您需要使用start_cursor和page_size参数来处理分页，以获取所有数据。
总结
通过本文的详细教程，您应该已经掌握了如何使用PHP cURL向Notion API查询数据库并正确应用过滤条件。核心要点在于将所有过滤逻辑封装在请求体中的filter参数内。遵循本文提供的代码示例和最佳实践，您将能够更有效地与Notion数据库进行交互，实现精确的数据检索，从而构建功能强大的Notion集成应用。
