PHP cURL查询Notion数据库：掌握正确的过滤条件构建方法-php教程-PHP中文网

PHP cURL查询Notion数据库：掌握正确的过滤条件构建方法

霞舞

发布： 2025-10-08 10:35:00

原创

731人浏览过

PHP cURL查询Notion数据库：掌握正确的过滤条件构建方法

本教程详细阐述了使用PHP cURL向Notion API查询数据库时，如何正确构建包含过滤条件的POST请求体。核心问题在于，过滤条件必须嵌套在请求载荷的filter键下，而非直接作为顶级属性。文章通过对比错误与正确的代码示例，指导开发者精确地筛选Notion数据库数据，避免获取冗余信息，从而提高API交互效率和准确性。

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免费学习笔记（深入）”；

正确的请求体结构应如下所示：

Notion Sites

Notion 推出的AI网站构建工具，允许用户将 Notion 页面直接发布为完整网站。

查看详情

// 正确的过滤条件构建方式
$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发送查询：

<?php

// 您的Notion数据库ID和集成令牌
$databaseId = "YOUR_DATABASE_ID"; // 替换为您的数据库ID
$token = 'YOUR_NOTION_INTEGRATION_TOKEN'; // 替换为您的集成令牌
$version = '2021-08-16'; // Notion API版本

$url = "https://api.notion.com/v1/databases/$databaseId/query"; // API端点

// 正确构建的POST数据，将过滤条件放在 'filter' 键下
$data_array =
[
    'filter' =>
    [
      "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提供的所有高级查询特性。

以上就是PHP cURL查询Notion数据库：掌握正确的过滤条件构建方法的详细内容，更多请关注php中文网其它相关文章！