借助 Google Drive API,您可以在创建或更新 File
时上传文件数据。如需了解如何创建仅包含元数据的 File
,请参阅创建文件。
您可以执行 3 种类型的上传操作:
Simple upload (
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
标头。将文件的数据添加到媒体部分。
使用定界字符串标识每个部分,并在前面加上 2 个连字符。此外,请在最后的定界字符串后添加 2 个连字符。
- 元数据。元数据必须排在最前面,并且必须将
添加以下顶级 HTTP 标头:
Content-Type
。请将此项设为multipart/related
,并在其中添加您要用于标识请求不同部分的定界字符串。例如:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
。请将此项设为请求正文包含的字节总数。
发送请求。
如果只想创建或更新元数据部分,而不带关联数据,请向标准资源端点发送 POST
或 PATCH
请求:https://www.googleapis.com/drive/v3/files
。如果请求成功,服务器将返回 HTTP 200 OK
状态代码以及文件的元数据。
创建文件时,他们应在文件的 name
字段中指定文件扩展名。例如,创建照片 JPEG 文件时,您可以在元数据中指定类似 "name": "photo.jpg"
的内容。对 files.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 OK
HTTP 状态代码。此外,它还包含一个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 的有效期为一周。复制并保存可续传会话网址。
继续上传内容。
上传内容
您可以通过以下 2 种方式上传使用可续传会话的文件:
- 在单个请求中上传内容 - 如果可以通过一个请求上传文件,或者对于任何单个请求没有固定的时间限制,或者您不需要显示上传进度指示器,请使用此方法。这是最佳方法,因为它需要的请求更少,并且性能更高。
分块上传内容 - 如果您必须减少任何单个请求中传输的数据量,请使用此方法。当各个请求有固定的时间限制时,您可能需要减少传输的数据,某些类别的 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
表示您要上传某个 200 万字节文件中的前 524288 个字节 (256 x 1024 x 2)。
发送请求并处理响应。如果上传请求中断或者您收到
5xx
响应,请按照恢复中断的上传中的步骤进行操作。对文件中剩余的每个数据块重复执行第 1 步到第 4 步。使用响应中的
Range
标头来确定从何处开始上传下一个分块。请勿假定服务器已收到上一个请求中发送的所有字节。
当整个文件上传完毕后,您会收到 200 OK
或 201 Created
响应,以及与资源关联的所有元数据。
恢复中断的上传
如果上传请求在响应前终止,或者您收到 503 Service Unavailable
响应,则必须恢复中断的上传。
HTTP
如需查询上传状态,请创建一个针对可续传会话 URI 的空
PUT
请求。添加
Content-Range
标头,以指示文件中的当前位置未知。例如,如果您的文件总长度为 200 万字节,请将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 至 2000000 个字节。
处理媒体上传错误
上传媒体内容时,请遵循以下最佳实践来处理错误:
- 对于
5xx
错误,请恢复或重试由于连接中断而失败的上传。如需详细了解如何处理5xx
错误,请参阅解决5xx
错误。 - 如果发生
403 rate limit
错误,请重新尝试上传。如需详细了解如何处理403 rate limit
错误,请参阅解析403 error: Rate limit exceeded
。 - 如果可续传上传期间出现任何
4xx
错误(包括403
),请重新开始上传。这些错误表示上传会话已过期,必须通过请求新的会话 URI 重新启动。上传会话也会在闲置一周后过期。
导入到 Google 文档类型
在云端硬盘中创建文件时,您可能希望将文件转换为 Google Workspace 文件类型,例如 Google 文档或 Google 表格。例如,您可能希望将文档从您喜爱的文字处理程序转换为 Google 文档,以充分利用其功能。
如需将文件转换为特定的 Google Workspace 文件类型,请在创建文件时指定 Google Workspace mimeType
。
下文展示了如何将 CSV 文件转换为 Google Workspace 表格:
Java
Python
Node.js
PHP
.NET
如需了解是否存在转换,请先查看关于资源的 importFormats
数组,然后再创建文件。此数组中动态提供支持的转化。一些常见的导入格式如下:
发件人 | 到 |
---|---|
Microsoft Word、OpenDocument 文本、HTML、RTF、纯文本 | Google 文档 |
Microsoft Excel、OpenDocument 电子表格、CSV、TSV、纯文本 | Google 表格 |
Microsoft PowerPoint、OpenDocument 演示文稿 | Google 幻灯片 |
JPEG、PNG、GIF、BMP、PDF | Google 文档(将图片嵌入到文档中) |
纯文本(特殊 MIME 类型)、JSON | Google Apps 脚本 |
在向文档、表格或幻灯片发出 update
请求期间,上传并转换媒体时,文档的全部内容都会被替换。
当您将图片转换为文档时,云端硬盘会使用光学字符识别 (OCR) 将图片转换为文本。您可以通过在 ocrLanguage
参数中指定适用的 BCP 47 语言代码来提高 OCR 算法的质量。提取的文本会显示在文档中的嵌入图片旁边。
使用预先生成的 ID 上传文件
借助 Drive API,您可以检索用于上传和创建资源的预生成文件 ID 列表。上传请求和文件创建请求可以使用这些预先生成的 ID。在文件元数据中设置 id
字段。
要创建预先生成的 ID,请使用要创建的 ID 数量调用 file.generateIds。
如果出现不确定的服务器错误或超时,您可以放心地使用预先生成的 ID 重新尝试上传。如果文件已成功创建,则后续重试会返回 HTTP 409
错误,并且不会创建重复的文件。
为未知文件类型定义可编入索引的文本
用户可以使用云端硬盘界面搜索文档内容。您还可以使用 files.list 和 fullText
字段搜索您的应用中的内容。如需了解详情,请参阅搜索文件和文件夹。
云端硬盘在识别出文件类型(包括文本文档、PDF、带文本的图片和其他常见类型)后,会自动将文档编入索引以进行搜索。如果您的应用保存其他类型的文件(如绘图、视频和快捷方式),您可以通过在文件的 contentHints.indexableText
字段中提供可编入索引的文本来提高其曝光度。
如需详细了解可编入索引的文本,请参阅管理文件元数据。