使用PHP和cURL调用Dropbox API列出文件夹文件-php教程-PHP中文网

使用PHP和cURL调用Dropbox API列出文件夹文件

心靈之曲

发布： 2025-09-21 11:34:01

原创

692人浏览过

使用PHP和cURL调用Dropbox API列出文件夹文件

本教程详细阐述如何使用PHP的cURL库与Dropbox API的files/list_folder接口进行交互，以列出指定文件夹的文件和子文件夹。核心内容聚焦于正确构建和发送JSON请求体，以及设置HTTP头部，确保API调用成功并有效处理响应。

理解Dropbox API的files/list_folder接口

dropbox api的files/list_folder是一个post请求，用于获取指定路径下文件夹的内容（文件和子文件夹）。它需要一个json格式的请求体来定义查询参数，例如目标路径、是否递归搜索、是否包含媒体信息等。

标准的curl命令示例如下：

curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header "Authorization: Bearer <ACCESS_TOKEN>" \
    --header "Content-Type: application/json" \
    --data "{\"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}"

登录后复制

其中，--header用于设置HTTP请求头，包括授权令牌（Authorization）和内容类型（Content-Type）。--data则用于发送请求体，其内容必须是符合JSON规范的字符串。

使用PHP cURL调用Dropbox API

在PHP中，我们可以利用cURL扩展来模拟上述curl命令。核心挑战在于如何正确设置请求头和发送JSON格式的请求体。

1. 初始化cURL会话

首先，需要初始化一个cURL会话：

立即学习“PHP免费学习笔记（深入）”；

$ch = curl_init();

登录后复制

2. 设置请求URL和方法

指定API的URL，并将其设置为POST请求：

curl_setopt($ch, CURLOPT_URL, 'https://api.dropboxapi.com/2/files/list_folder');
curl_setopt($ch, CURLOPT_POST, 1); // 明确指定为POST请求
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // 将API响应作为字符串返回，而不是直接输出

登录后复制

3. 设置HTTP请求头

HTTP请求头包括Authorization（授权令牌）和Content-Type（内容类型）。Authorization头部的Bearer后面需要紧跟你的Dropbox访问令牌。

$accessToken = 'YOUR_DROPBOX_ACCESS_TOKEN'; // 替换为你的实际访问令牌
$headers = array(
    'Authorization: Bearer ' . $accessToken,
    'Content-Type: application/json'
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

登录后复制

重要提示： 务必将YOUR_DROPBOX_ACCESS_TOKEN替换为你在Dropbox开发者平台获取的有效访问令牌。

华文笔杆

写材料用华文，华文笔杆帮你搞定公文写作

491

查看详情

4. 构建并发送JSON请求体

这是许多开发者容易出错的地方。CURLOPT_POSTFIELDS选项用于发送POST请求的数据。当Content-Type设置为application/json时，CURLOPT_POSTFIELDS期望接收一个原始的JSON字符串。

错误示例（常见的误解）：

// 错误示例：这不会发送正确的JSON数据
// curl_setopt($ch, CURLOPT_POSTFIELDS, "Data: {\"path\": \"/Homework/math\", ...}");
// 错误示例：直接传递PHP数组，cURL会默认编码为application/x-www-form-urlencoded
// curl_setopt($ch, CURLOPT_POSTFIELDS, ['path' => '/Homework/math', ...]);

登录后复制

正确的方法是先构建一个PHP数组，然后使用json_encode()将其转换为JSON字符串，再传递给CURLOPT_POSTFIELDS。

$data = array(
    "path" => "/Homework/math", // 要列出内容的Dropbox路径
    "recursive" => false,
    "include_media_info" => false,
    "include_deleted" => false,
    "include_has_explicit_shared_members" => false,
    "include_mounted_folders" => true,
    "include_non_downloadable_files" => true
);

$jsonData = json_encode($data); // 将PHP数组转换为JSON字符串
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);

登录后复制

5. 执行请求并处理响应

执行cURL请求，并检查可能发生的错误。如果请求成功，API的响应将是JSON格式的字符串，需要使用json_decode()进行解析。

$result = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL Error: ' . curl_error($ch);
} else {
    // 解析JSON响应
    $response = json_decode($result, true); // true表示返回关联数组
    if (isset($response['entries'])) {
        echo "Dropbox 文件夹内容:\n";
        foreach ($response['entries'] as $entry) {
            echo " - " . $entry['name'] . " (" . $entry['.tag'] . ")\n";
        }
    } else {
        echo "API 响应错误或无内容: " . $result . "\n";
    }
}

// 关闭cURL会话
curl_close($ch);

登录后复制

完整示例代码

将以上步骤整合，形成一个完整的PHP脚本：

<?php

// 替换为你的Dropbox访问令牌
$accessToken = 'YOUR_DROPBOX_ACCESS_TOKEN'; 

// 检查访问令牌是否已设置
if (empty($accessToken) || $accessToken === 'YOUR_DROPBOX_ACCESS_TOKEN') {
    die("错误：请在 \$accessToken 变量中设置你的Dropbox访问令牌。\n");
}

$ch = curl_init();

// 设置请求URL
curl_setopt($ch, CURLOPT_URL, 'https://api.dropboxapi.com/2/files/list_folder');
// 设置为POST请求
curl_setopt($ch, CURLOPT_POST, 1);
// 将API响应作为字符串返回，而不是直接输出
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// 构建请求数据
$data = array(
    "path" => "/Homework/math", // 指定要列出内容的Dropbox路径
    "recursive" => false, // 是否递归列出子文件夹
    "include_media_info" => false, // 是否包含媒体信息
    "include_deleted" => false, // 是否包含已删除文件
    "include_has_explicit_shared_members" => false,
    "include_mounted_folders" => true,
    "include_non_downloadable_files" => true
);

// 将PHP数组转换为JSON字符串
$jsonData = json_encode($data);
// 设置POST请求体
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);

// 设置HTTP请求头
$headers = array(
    'Authorization: Bearer ' . $accessToken,
    'Content-Type: application/json'
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// 执行cURL请求
$result = curl_exec($ch);

// 检查cURL错误
if (curl_errno($ch)) {
    echo 'cURL Error: ' . curl_error($ch) . "\n";
} else {
    // 解析JSON响应
    $response = json_decode($result, true); // true表示返回关联数组

    if (json_last_error() !== JSON_ERROR_NONE) {
        echo "JSON 解析错误: " . json_last_error_msg() . "\n";
        echo "原始响应: " . $result . "\n";
    } elseif (isset($response['error_summary'])) {
        // Dropbox API返回错误
        echo "Dropbox API 错误: " . $response['error_summary'] . "\n";
        if (isset($response['error'])) {
            echo "详细错误: " . json_encode($response['error'], JSON_PRETTY_PRINT) . "\n";
        }
    } elseif (isset($response['entries'])) {
        echo "Dropbox 文件夹 '/Homework/math' 内容:\n";
        if (empty($response['entries'])) {
            echo " - 文件夹为空。\n";
        } else {
            foreach ($response['entries'] as $entry) {
                $type = ($entry['.tag'] === 'folder') ? '文件夹' : '文件';
                echo " - " . $entry['name'] . " (" . $type . ")\n";
            }
        }
    } else {
        echo "未知 API 响应格式: " . $result . "\n";
    }
}

// 关闭cURL会话
curl_close($ch);

?>

登录后复制

注意事项与最佳实践

访问令牌安全： 你的Dropbox访问令牌是敏感信息。在生产环境中，不应将其硬编码在代码中，而应通过环境变量、配置文件或密钥管理服务进行安全存储和加载。
错误处理： 务必检查curl_errno()以捕获cURL层面的错误，并解析API响应中的错误信息（如error_summary字段），以便更好地调试和处理异常情况。
JSON编码： 始终使用json_encode()将PHP数组转换为JSON字符串，避免手动拼接可能导致的格式错误。
API响应解析： Dropbox API的响应通常是JSON格式。使用json_decode($result, true)将其解析为PHP关联数组，便于数据访问。
路径与权限： 确保path参数指向的路径在你的Dropbox账户中存在，并且你的访问令牌具有足够的权限来访问该路径。