PHP cURL 集成 Dropbox 获取文件列表

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 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. 代码解析与注意事项

1. $accessToken: 这是您从 Dropbox 开发者控制台获取的访问令牌。请务必替换为您的实际令牌。
2. $apiUrl: Dropbox API files/list_folder 端点的 URL。
3. $postData:
   • 这里我们使用 json_encode() 函数将 PHP 关联数组转换为 JSON 格式的字符串。这是一个最佳实践，因为它能确保生成正确的 JSON 格式，避免手动拼接字符串时可能出现的错误。
   • CURLOPT_POSTFIELDS 选项在发送 application/json 类型的请求时，其值必须是一个完整的 JSON 字符串。
4. CURLOPT_RETURNTRANSFER: 设置为 1 (true) 会使 curl_exec() 返回请求结果作为字符串，而不是直接输出到浏览器。
5. CURLOPT_POST: 设置为 1 (true) 明确指示这是一个 POST 请求。
6. CURLOPT_HTTPHEADER: 这是一个数组，用于设置请求头。
   • Authorization: Bearer ：用于身份验证， 替换为您的实际令牌。
   • Content-Type: application/json：告知服务器请求体是 JSON 格式。
7. 错误处理: curl_errno($ch) 和 curl_error($ch) 用于检查 cURL 本身是否发生错误（例如网络问题、SSL 证书问题等）。
8. API 响应处理: Dropbox API 的响应也是 JSON 格式。使用 json_decode($result, true) 可以将其解码为 PHP 关联数组，方便进一步处理。务必检查 json_last_error() 以确保解码成功。
9. 安全性: 访问令牌是敏感信息，不应直接硬编码在生产代码中。应通过环境变量、配置文件或密钥管理服务来安全存储和加载。
10. 路径动态化: 示例中的 path 是硬编码的 /Homework/math。在实际应用中，您会根据用户输入或其他逻辑动态生成此路径。
11. 更复杂的场景: 对于更复杂的 Dropbox 集成，例如文件上传、下载、删除、共享等，建议考虑使用官方或社区维护的 Dropbox PHP SDK，它们通常提供了更高级的抽象和更简便的错误处理机制。

总结

通过上述 PHP cURL 示例，您可以清晰地了解如何正确地向 Dropbox API 发送包含 JSON 数据的 POST 请求，从而获取指定文件夹的文件列表。关键在于使用 json_encode() 生成正确的 JSON 字符串，并将其赋值给 CURLOPT_POSTFIELDS，同时设置正确的 Content-Type 请求头。掌握这一方法，将为您的 PHP 应用集成 Dropbox 的文件管理功能奠定坚实基础。