dropbox api 提供了强大的文件管理能力，其中 files/list_folder 端点允许开发者获取指定路径下的文件和文件夹列表。在 php 环境中，通常通过 curl 扩展来与外部 api 进行通信。然而，正确构造和发送包含 json 数据的 post 请求是关键所在。
1. 理解 Dropbox API files/list_folder 请求
files/list_folder API 端点要求通过 POST 请求发送 JSON 格式的数据。其基本结构如下：
{
"path": "/Homework/math",
"recursive": false,
"include_media_info": false,
"include_deleted": false,
"include_has_explicit_shared_members": false,
"include_mounted_folders": true,
"include_non_downloadable_files": true
}同时，请求头中必须包含 Authorization 令牌和 Content-Type: application/json，以告知服务器请求体是 JSON 格式。
2. PHP cURL 实现文件列表获取
在使用 PHP cURL 发送此类请求时，核心挑战在于如何将上述 JSON 数据作为 POST 请求体正确传递。许多开发者可能会尝试将 JSON 字符串作为关联数组的一部分发送，例如 ['Data' => '{"path":...}']，但这会导致服务器无法正确解析 JSON 数据，从而返回 "Error in call to API function 'files/list_folder': request body: could not decode input as JSON" 错误。
正确的做法是使用 CURLOPT_POSTFIELDS 选项，并直接将完整的 JSON 字符串作为其值。
立即学习“PHP免费学习笔记（深入）”；
以下是使用 PHP cURL 列出 Dropbox 文件夹内容的完整示例代码：
'/Homework/math', // 要列出的文件夹路径
'recursive' => false, // 是否递归列出子文件夹
'include_media_info' => false, // 是否包含媒体信息
'include_deleted' => false, // 是否包含已删除文件
'include_has_explicit_shared_members' => false, // 是否包含显式共享成员信息
'include_mounted_folders' => true, // 是否包含挂载的文件夹
'include_non_downloadable_files' => true // 是否包含不可下载的文件
]);
// 初始化 cURL 会话
$ch = curl_init();
// 设置 cURL 选项
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // 将响应作为字符串返回，而不是直接输出
curl_setopt($ch, CURLOPT_POST, 1); // 设置为 POST 请求
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); // 设置 POST 请求体，必须是 JSON 字符串
// 设置 HTTP 请求头
$headers = [
'Authorization: Bearer ' . $accessToken, // 授权令牌
'Content-Type: application/json' // 声明请求体是 JSON 格式
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
// 执行 cURL 请求并获取结果
$result = curl_exec($ch);
// 检查是否有 cURL 错误
if (curl_errno($ch)) {
echo 'cURL Error: ' . curl_error($ch);
} else {
// 打印或处理 API 响应
echo "Dropbox API Response:\n";
echo $result;
// 如果响应是 JSON，可以解码它
$responseDecoded = json_decode($result, true);
if (json_last_error() === JSON_ERROR_NONE) {
echo "\n\nDecoded Response:\n";
print_r($responseDecoded);
// 遍历文件和文件夹
if (isset($responseDecoded['entries']) && is_array($responseDecoded['entries'])) {
echo "\n\nFiles and Folders:\n";
foreach ($responseDecoded['entries'] as $entry) {
echo "- " . $entry['.tag'] . ": " . $entry['name'] . " (ID: " . $entry['id'] . ")\n";
}
}
} else {
echo "\n\nFailed to decode JSON response.\n";
}
}
// 关闭 cURL 会话
curl_close($ch);
?>3. 代码解析与注意事项
- $accessToken: 这是您从 Dropbox 开发者控制台获取的访问令牌。请务必替换为您的实际令牌。
- $apiUrl: Dropbox API files/list_folder 端点的 URL。
-
$postData:
- 这里我们使用 json_encode() 函数将 PHP 关联数组转换为 JSON 格式的字符串。这是一个最佳实践，因为它能确保生成正确的 JSON 格式，避免手动拼接字符串时可能出现的错误。
- CURLOPT_POSTFIELDS 选项在发送 application/json 类型的请求时，其值必须是一个完整的 JSON 字符串。
- CURLOPT_RETURNTRANSFER: 设置为 1 (true) 会使 curl_exec() 返回请求结果作为字符串，而不是直接输出到浏览器。
- CURLOPT_POST: 设置为 1 (true) 明确指示这是一个 POST 请求。
-
CURLOPT_HTTPHEADER: 这是一个数组，用于设置请求头。
- Authorization: Bearer
：用于身份验证， 替换为您的实际令牌。 - Content-Type: application/json：告知服务器请求体是 JSON 格式。
- Authorization: Bearer
- 错误处理: curl_errno($ch) 和 curl_error($ch) 用于检查 cURL 本身是否发生错误（例如网络问题、SSL 证书问题等）。
- API 响应处理: Dropbox API 的响应也是 JSON 格式。使用 json_decode($result, true) 可以将其解码为 PHP 关联数组，方便进一步处理。务必检查 json_last_error() 以确保解码成功。
- 安全性: 访问令牌是敏感信息，不应直接硬编码在生产代码中。应通过环境变量、配置文件或密钥管理服务来安全存储和加载。
- 路径动态化: 示例中的 path 是硬编码的 /Homework/math。在实际应用中，您会根据用户输入或其他逻辑动态生成此路径。
- 更复杂的场景: 对于更复杂的 Dropbox 集成，例如文件上传、下载、删除、共享等，建议考虑使用官方或社区维护的 Dropbox PHP SDK，它们通常提供了更高级的抽象和更简便的错误处理机制。
总结
通过上述 PHP cURL 示例，您可以清晰地了解如何正确地向 Dropbox API 发送包含 JSON 数据的 POST 请求，从而获取指定文件夹的文件列表。关键在于使用 json_encode() 生成正确的 JSON 字符串，并将其赋值给 CURLOPT_POSTFIELDS，同时设置正确的 Content-Type 请求头。掌握这一方法，将为您的 PHP 应用集成 Dropbox 的文件管理功能奠定坚实基础。
