借助 Google Drive API,您可以在创建或更新
File时上传文件数据。如需了解如何创建
仅包含元数据的文件(例如文件夹),请参阅创建仅包含元数据的文件。
您可以执行以下三种类型的上传:
简单上传 (
uploadType=media) :使用此上传类型传输小型媒体文件(5 MB 或更小),无需提供元数据。如需执行 简单上传,请参阅执行简单上传。分段上传 (
uploadType=multipart) :使用此上传类型在单个请求中传输小型文件(5 MB 或更小)以及描述该文件的元数据。如需执行分段上传,请参阅执行 分段上传。可续传上传 (
uploadType=resumable) :对于大型文件(大于 5 MB)以及网络中断的可能性较高的情况(例如从移动应用创建文件时),请使用此上传类型。对于大多数应用来说,可续传上传也是一种很好的方式,因为该方式也适用于小型文件(只不过每次上传时都要多发出一个 HTTP 请求,成本很低)。 如需执行可续传上传,请参阅执行可续传 上传。
Google API 客户端库至少实现了其中一种上传类型。如需详细了解如何使用每种类型,请参阅客户端库 文档。
使用 PATCH 与 PUT
提醒一下,HTTP 动词 PATCH 支持部分文件资源更新,而 HTTP 动词 PUT 支持完整资源替换。请注意,向现有资源添加新字段时,PUT 可能会引入重大更改。
上传文件资源时,请遵循以下准则:
- 对于可续传上传的初始请求,或简单上传或分段上传的唯一请求,请使用 API 参考文档中记录的 HTTP 动词。
- 对于可续传上传的所有后续请求,请在请求开始后使用
PUT。无论调用哪种方法,这些请求都会上传内容。
执行简单上传
如需执行简单上传,请对 files 资源使用 create
方法,并将
uploadType=media。
以下展示了如何执行简单上传:
HTTP
使用查询参数
uploadType=media,对该方法的 /upload URI 创建POST请求:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media将文件的数据添加到请求正文。
添加以下 HTTP 标头:
Content-Type。设置为要上传的对象的 MIME 媒体类型。Content-Length。设置为您上传的字节数。如果您使用分块传输编码,则不需要此标头。
发送请求。如果请求成功,服务器将返回
HTTP 200 OK状态代码以及文件的元数据。{HTTP}
执行简单上传时,系统会创建基本元数据,并从文件中推断出一些属性,例如 MIME 类型或 modifiedTime。如果您有小型文件,并且文件元数据并不重要,则可以使用简单上传。
执行分段上传
借助分段上传请求,您可以在同一请求中上传元数据和数据。如果您发送的数据足够小,可以在连接失败时重新上传整个数据,请使用此选项。
如需执行分段上传,请对 files 资源使用
create 方法,并将 uploadType=multipart。
以下展示了如何执行分段上传:
Java
Python
Node.js
PHP
.NET
HTTP
使用查询参数
uploadType=multipart,对该方法的 /upload URI 创建POST请求:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart创建请求的正文。根据 多部分/相关内容类型 RFC 2387 设置正文的格式,其中包含两个部分:
- 元数据。元数据必须位于第一部分,并且必须将
Content-Type标头设置为application/json;charset=UTF-8。以 JSON 格式添加文件的元数据。 - 媒体。媒体必须位于第二部分,并且必须具有任何 MIME 类型的
Content-Type标头。将文件的数据添加到媒体部分。
使用定界字符串(前面加两个连字符)标识每个部分。此外,在最后一个定界字符串后添加两个连字符。
- 元数据。元数据必须位于第一部分,并且必须将
添加以下顶级 HTTP 标头:
Content-Type。设置为multipart/related,并在其中添加您要用于标识请求各个部分的定界字符串。例如:Content-Type: multipart/related; boundary=foo_bar_bazContent-Length。设置为请求正文中的字节总数。
发送请求。
如果只想创建或更新元数据部分,而不上传相关数据,请向标准资源端点 https://www.googleapis.com/drive/v3/files 发送 POST 或 PATCH 请求。如果请求成功,服务器将返回 HTTP 200 OK 状态代码以及文件的元数据。
创建文件时,应在文件的 name 字段中指定文件扩展名。例如,在创建照片 JPEG 文件时,您可以在元数据中指定类似
的内容"name": "photo.jpg"。随后对 get 方法的调用会返回只读 fileExtension
属性,其中包含最初在 name 字段中指定的扩展名。
执行可续传上传
当数据流因通信故障而中断后,您可以利用可续传上传恢复上传操作。由于您不必重新开始从头进行大型文件上传,因此出现网络故障时,可续传上传还可以减少带宽占用。
当文件大小可能差异很大,或者请求有固定时间限制(例如移动操作系统后台任务和某些 App Engine 请求)时,可续传上传非常有用。在您想要显示上传进度条的情况下,也可以使用可续传上传。
可续传上传包含以下几个简要步骤:
- 发送初始请求并检索可续传会话 URI。
- 上传数据并监控上传状态。
- (可选)如果上传中断,请恢复上传。
发送初始请求
如需启动可续传上传,请对 files 资源使用
create 方法,并将 uploadType=resumable。
HTTP
使用查询参数
uploadType=resumable,对该方法的 /upload URI 创建POST请求:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable如果启动请求成功,响应将包含
200 OKHTTP 状态代码。此外,它还包含一个Location标头,该标头指定可续传会话 URI:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0保存可续传会话 URI,以便您可以上传文件数据并查询上传状态。可续传会话 URI 的有效期为一周。
如果您有文件的元数据,请以 JSON 格式向请求正文添加元数据, 否则,请将请求正文留空。
添加以下 HTTP 标头:
X-Upload-Content-Type。可选。设置为后续请求中传输的文件数据的 MIME 类型。如果未在元数据中或通过此标头指定数据的 MIME 类型 , 则对象将以application/octet-stream.的形式提供。X-Upload-Content-Length。可选。设置为后续请求中传输的文件数据的字节数。Content-Type。如果您有文件的元数据,则需要添加此标头。设置为application/json;charset=UTF-8。Content-Length。除非您使用分块传输编码,否则需要添加此标头。 设置为此初始请求正文中的字节数。
发送请求。如果会话启动请求成功,响应将包含
200 OK HTTP状态代码。此外,响应还包含一个Location标头,该标头指定可续传会话 URI。 使用可续传会话 URI 上传文件数据并查询上传状态。可续传会话 URI 的有效期为一周。复制并保存可续传会话网址。
继续上传内容。
上传内容
借助以下两种方法,您可以使用可续传会话上传文件:
- 在单个请求中上传内容:如果可以在一个请求中上传文件,并且任何单个请求都没有固定时间限制,或者您不需要显示上传进度指示器,请使用此方法。此方法是最佳方法,因为它需要的请求较少,并且性能更好。
将内容分成多个数据块上传:如果您必须 减少单个请求中传输的数据量,请使用此方法。当单个请求有固定时间限制时(例如某些类别的 App Engine 请求),您可能需要减少传输的数据量。如果您必须提供自定义指示器来显示上传进度,此方法也很有用。
HTTP - 单个请求
- 对可续传会话 URI 创建
PUT请求。 - 将文件的数据添加到请求正文。
- 添加一个 Content-Length HTTP 标头,并将其设置为文件中的字节数。
- 发送请求。如果上传请求中断或者您收到
5xx响应,请按照恢复中断的上传中的步骤操作。
HTTP - 多个请求
对可续传会话 URI 创建
PUT请求。将数据块的数据添加到请求正文。除了结束上传的最后一个数据块之外,数据块的大小应该是 256 KB(256 x 1024 字节)的整数倍。请尽可能保持数据块大小,以提高上传效率。
添加以下 HTTP 标头:
Content-Length。设置为当前数据块中的字节数。Content-Range。设置为显示您上传的文件中的字节。例如,Content-Range: bytes 0-524287/2000000表示您在 2,000,000 字节的文件中上传了前 524,288 字节 (256 x 1024 x 2)。
发送请求并处理响应。如果上传请求 中断或者您收到
5xx响应,请按照 恢复中断的上传中的步骤操作。对文件中剩余的每个数据块重复执行第 1 到 4 步。使用响应中的
Range标头确定下一个数据块的起始位置。 请勿假定服务器收到了上一个请求中发送的所有字节。
整个文件上传完成后,您会收到 200 OK 或 201 Created 响应,以及与资源关联的任何元数据。
恢复中断的上传
如果上传请求在收到响应之前终止,或者您收到 503
Service Unavailable 响应,则必须恢复中断的上传。
HTTP
如需查询上传状态,请创建一个针对可续传会话 URI 的空
PUT请求。添加
Content-Range标头,以表明文件中的当前位置未知。例如,如果您的文件总长度为 2,000,000 字节,请将Content-Range设置为*/2000000。如果您不知道文件的完整大小,请将Content-Range设置为*/*。发送请求。
处理响应:
200 OK或201 Created响应表明上传已完成,无需执行进一步操作。308 Resume Incomplete响应表明您必须继续上传文件。404 Not Found响应表明上传会话已过期,必须从头开始重新上传。
如果您收到
308 Resume Incomplete响应,请处理响应的Range标头,以确定服务器收到了哪些字节。如果响应没有Range标头,则表示未收到任何字节。 例如,Range标头bytes=0-42表示收到了文件的前 43 个字节,并且要上传的下一个数据块将从第 44 个字节开始。现在,您已知道从何处恢复上传,请从下一个字节开始继续上传文件。添加
Content-Range标头,以表明您发送的文件部分。例如,Content-Range: bytes 43-1999999表示您发送了第 44 个字节到第 2,000,000 个字节。
处理媒体上传错误
上传媒体时,请遵循以下最佳实践来处理错误:
- 对于
5xx错误,请恢复或重试因连接中断而失败的上传。如需详细了解如何处理5xx错误,请参阅 500、502、503、504 错误。 - 对于
403 rate limit错误,请重试上传。如需详细了解如何处理403 rate limit错误,请参阅403 错误:rateLimitExceeded。 - 对于可续传上传期间出现的任何
4xx错误(包括403),请重新开始上传。这些错误表明上传会话已过期,必须 通过请求新的会话 URI来重新开始。上传会话也会在闲置一周后过期。
导入到 Google 文档类型
在 Drive 中创建文件时,您可能需要将文件转换为 Google Workspace 文件类型,例如 Google 文档或表格。例如,您可能需要将自己喜欢的字处理软件中的文档转换为 Google 文档,以便利用其功能。
如需将文件转换为特定的 Google Workspace 文件类型,请在创建文件时指定 Google Workspace mimeType。
以下展示了如何将 CSV 文件转换为 Google Workspace 表格:
Java
Python
Node.js
PHP
.NET
如需查看转换是否可用,请在创建文件之前检查 importFormats 资源的 about 字段。此数组中会动态提供受支持的转换。一些常见的导入格式包括:
| 发件人 | 收件人 |
|---|---|
| Microsoft Word、OpenDocument 文本、HTML、RTF、纯文本 | Google 文档 |
| Microsoft Excel、OpenDocument 电子表格、CSV、TSV、纯文本 | Google 表格 |
| Microsoft PowerPoint、OpenDocument 演示文稿 | Google 幻灯片 |
| JPEG、PNG、GIF、BMP、PDF | Google 文档(将图片嵌入到 Google 文档中) |
| 纯文本(特殊 MIME 类型)、JSON | Google Apps 脚本 |
在对 Google 文档、表格或幻灯片文件发出 update 请求期间上传和转换媒体时,文档的完整内容会被替换。
将图片转换为 Google 文档时,Drive 会使用光学字符识别 (OCR) 将图片转换为文本。您可以通过在 ocrLanguage 参数中指定适用的 BCP
47 语言代码来
提高 OCR 算法的质量。
提取的文本会显示在文档中,与嵌入的图片并列。
使用预生成的 ID 上传文件
借助 Drive API,您可以检索预生成的文件 ID 列表,这些 ID 可用于创建、复制和上传资源。如需了解详情,请参阅 生成要与文件搭配使用的 ID。
如果出现不确定的服务器错误或超时,您可以使用预生成的 ID 安全地重试上传。如果文件操作成功,后续重试会返回 409 Conflict HTTP 状态代码响应,并且不会创建重复文件。
请注意,除了 application/vnd.google-apps.drive-sdk
和 application/vnd.google-apps.folder MIME
类型之外,预生成的 ID 不受支持用于创建
Google Workspace 文件。同样,引用转换为 Google Workspace 文件格式的上传也不受支持。
为未知文件类型定义可编入索引的文本
用户可以使用 Drive 界面查找文档内容。您还可以
对 files 资源使用 list 方法和 fullText 字段,以搜索应用中的内容。如需了解详情,请参阅搜索文件和
文件夹。
当 Drive 识别文件类型(包括文本文档、PDF、包含文本的图片和其他常见类型)时,会自动为文档编入索引以供搜索。如果您的应用保存其他类型的文件(例如绘图、
视频和快捷方式),您可以在文件的
contentHints.indexableText
字段中提供可编入索引的文本,以提高可发现性。
如需详细了解可编入索引的文本,请参阅管理文件元数据。