Google 文档与文件 API调用手册

列出可访问的 Drive 文件

读取当前授权用户的文件元数据,用于文件选择、索引和归档清单。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 访问令牌包含 drive.metadata.readonly 或端点支持的其他范围;文件可见性以授权用户为准。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

GOOGLE_ACCESS_TOKEN
先执行本站本平台的获取与刷新用户令牌场景;令牌必须含当前场景要求的 scope,不能使用 API Key。
终端
export GOOGLE_ACCESS_TOKEN='replace_with_oauth_access_token'

以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    先完成本站获取与刷新 Google 用户令牌场景,GOOGLE_SCOPES 选 https://www.googleapis.com/auth/drive.metadata.readonly。

  2. 02

    把 access_token 放入 GOOGLE_ACCESS_TOKEN,运行下方请求;示例 q=trashed=false 排除回收站文件。

  3. 03

    保存 files[].id 作为后续文件操作的标识;若返回 nextPageToken,将它 URL 编码后作为下一次的 pageToken。

调用 01

列出文件元数据

只请求用得到的字段,避免下载正文或读取不需要的数据。

GEThttps://www.googleapis.com/drive/v3/files?q=trashed%3Dfalse&pageSize=20&fields=nextPageToken%2Cfiles%28id%2Cname%2CmimeType%2CmodifiedTime%2CwebViewLink%29

请求头

Authorization
Bearer ${GOOGLE_ACCESS_TOKEN}

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
qQuerystring可选Drive 搜索表达式;本例为 trashed=false,实际 HTTP 中已 URL 编码。
pageSizeQueryinteger可选本例 20;即使本页少于请求数,也以 nextPageToken 判断是否还有后续。
fieldsQuerystring可选本例保留分页令牌及 id/name/mimeType/modifiedTime/webViewLink。
pageTokenQuerystring可选从上一页 nextPageToken 取得,新增到下一次 URL。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://www.googleapis.com/drive/v3/files?q=trashed%3Dfalse&pageSize=20&fields=nextPageToken%2Cfiles%28id%2Cname%2CmimeType%2CmodifiedTime%2CwebViewLink%29" \
  --header "Authorization: Bearer ${GOOGLE_ACCESS_TOKEN}"
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://www.googleapis.com/drive/v3/files?q=trashed%3Dfalse&pageSize=20&fields=nextPageToken%2Cfiles%28id%2Cname%2CmimeType%2CmodifiedTime%2CwebViewLink%29")
headers = {
    "Authorization": expand("Bearer ${GOOGLE_ACCESS_TOKEN}"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
Node.js
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://www.googleapis.com/drive/v3/files?q=trashed%3Dfalse&pageSize=20&fields=nextPageToken%2Cfiles%28id%2Cname%2CmimeType%2CmodifiedTime%2CwebViewLink%29");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${GOOGLE_ACCESS_TOKEN}"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的响应结构示意,ID、文本和数字均为虚构,非接口实测结果。files 为当前页;返回 token 时继续翻页。 以下为结构示意,非本站实测结果。

JSON
{
  "nextPageToken": "example_next_page_token",
  "files": [
    {
      "id": "example_file_id",
      "name": "示例接入文档",
      "mimeType": "application/vnd.google-apps.document",
      "modifiedTime": "2026-10-01T08:00:00Z",
      "webViewLink": "https://docs.google.com/document/d/example_file_id/edit"
    }
  ]
}

常见错误与排查

HTTP 401访问令牌缺失、无效或已过期。
按本站授权场景使用 refresh_token 刷新;不要把 client_secret 或 API Key 当成 access_token。
HTTP 403权限不足、组织策略限制或达到用户配额。
读取 error.details/reason;核对已授权 scope、文件共享权限和项目配额,不能只重复授权同一个 scope。
HTTP 429达到服务请求频率限制。
采用带随机抖动的指数退避,限制重试次数,并减少批量轮询。

调用注意

  • 此请求列元数据,不读取文件正文;不是用户 Drive 全部内容的永久授权。
  • 本例不专门查询共享盘;共享盘完整查询需按 driveId、corpora、includeItemsFromAllDrives 等参数另行配置。

注意事项

  • 核验日官方仍说明标准 API 使用无额外费用,同时公告 2026 年晚些时候计划对超配额用量计费;不把当前规则写成永久免费承诺。以项目配额及官方生效通知为准。
  • Drive 自 2026-05-01 起新项目采用更新配额模型;旧项目可能保留原配额,不套用过时的固定请求次数。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
    Drive scopes 与逐文件权限核验日期 2026-10-15
  3. 03
  4. 04
    Drive files.list核验日期 2026-10-15
  5. 05

Google 文档与文件 API的其他调用手册

← 返回Google 文档与文件 API的全部功能