本指南包含与管理共享云端硬盘相关的任务,例如使用 Google Drive API 创建共享云端硬盘以及管理成员和权限。
如果您想指定要在响应中返回的字段,可以使用 drives
资源的任何方法设置 fields
系统参数。如果您未指定 fields
参数,服务器会返回特定于该方法的默认字段集。例如,list
方法仅返回每个共享云端硬盘的 kind
、id
和 name
字段。如需了解详情,请参阅返回特定字段。
如需详细了解共享云端硬盘的文件夹限制,请参阅共享云端硬盘的文件夹限制。
创建共享云端硬盘
如需创建共享云端硬盘,请对 drives
资源使用 create
方法,并提供 requestId
参数。
requestId
参数用于标识共享云端硬盘的幂等创建的逻辑尝试。如果请求超时或返回不确定的后端错误,则可以重复同一请求,而不会创建重复项。requestId
和请求正文必须保持不变。
以下代码示例展示了如何创建共享云端硬盘:
Java
Python
Node.js
PHP
.NET
对 create
方法的调用是幂等的。
如果共享云端硬盘已在之前的请求中成功创建,或者由于重试而成功创建,则该方法会返回 drives
资源的实例。有时,例如在长时间后或请求正文发生更改时,系统可能会返回 409
错误,表明必须舍弃 requestId
。
获取共享云端硬盘
如需获取共享云端硬盘的元数据,请对 drives
资源使用 get
方法,并提供 driveId
路径参数。如果您不知道云端硬盘 ID,可以使用 list
方法列出所有共享云端硬盘。
get
方法会以 drives
资源实例的形式返回共享云端硬盘。
如需以网域管理员身份发出请求,请将 useDomainAdminAccess
查询参数设置为 true
。如需了解详情,请参阅以网域管理员身份管理共享云端硬盘。
列出共享云端硬盘
如需列出用户的共享云端硬盘,请对 drives
资源使用 list
方法。该方法会返回一个共享云端硬盘列表。
传递以下查询参数可自定义共享云端硬盘的分页或过滤共享云端硬盘:
pageSize
:每页返回的共享云端硬盘数量上限。pageToken
:从之前的列表调用接收的页面令牌。提供此令牌可检索后续页面。q
:用于搜索共享云端硬盘的查询字符串。如需了解详情,请参阅搜索共享云端硬盘。useDomainAdminAccess
:设置为true
可将请求作为网域管理员发出,以返回请求者是管理员的网域中的所有共享云端硬盘。如需了解详情,请参阅以网域管理员身份管理共享云端硬盘。
更新共享云端硬盘
如需更新共享云端硬盘的元数据,请对 drives
资源使用 update
方法,并提供 driveId
路径参数。
该方法会以 drives
资源实例的形式返回共享云端硬盘。
如需以网域管理员身份发出请求,请将 useDomainAdminAccess
查询参数设置为 true
。如需了解详情,请参阅以网域管理员身份管理共享云端硬盘。
隐藏和取消隐藏共享云端硬盘
如需从默认视图中隐藏共享云端硬盘,请对 drives
资源使用 hide
方法,并提供 driveId
参数。
隐藏共享云端硬盘后,云端硬盘会将该共享云端硬盘资源标记为 hidden=true
。隐藏的共享云端硬盘不会显示在云端硬盘界面中,也不会显示在返回的文件列表中。
如需将共享云端硬盘恢复为默认视图,请对 drives
资源使用 unhide
方法,并提供 driveId
参数。
这两种方法都会返回一个共享云端硬盘,作为 drives
资源的实例。
删除共享云端硬盘
如需永久删除共享云端硬盘,请使用 drives
资源上的 delete
方法,并提供 driveId
参数。
删除共享云端硬盘之前,必须将该共享云端硬盘中的所有内容移至回收站或删除。用户还必须对共享云端硬盘文件夹具有 role=organizer
权限。如需了解详情,请参阅将文件和文件夹放入回收站或删除。
传递以下查询参数以过滤共享云端硬盘:
useDomainAdminAccess
:设置为true
可将请求作为网域管理员发出,以返回请求者是管理员的网域中的所有共享云端硬盘。如需了解详情,请参阅以网域管理员身份管理共享云端硬盘。allowItemDeletion
:设置为true
可删除共享云端硬盘中的内容。 仅当useDomainAdminAccess
也设置为true
时才受支持。
添加或移除共享云端硬盘成员
使用 permissions
资源添加或移除共享云端硬盘成员。
如需添加成员,请在共享云端硬盘中创建相应权限。权限方法也可用于共享云端硬盘中的单个文件,以授予成员更多权限或允许非成员协作处理特定项目。
如需了解详情和查看示例代码,请参阅共享文件、文件夹和云端硬盘。
以网域管理员身份管理共享云端硬盘
将 useDomainAdminAccess
参数与 drives
和 permissions
资源搭配使用,以管理组织中的共享云端硬盘。
如果用户使用 useDomainAdminAccess=true
调用这些方法,则必须具有 Drive and Docs
管理员权限。管理员可以搜索共享云端硬盘或更新其组织拥有的共享云端硬盘的权限,无论管理员是否是任何给定共享云端硬盘的成员。
使用服务账号时,您可能需要使用服务账号模拟来模拟经过身份验证的管理员。 请注意,与用户账号不同,服务账号不属于您的 Google Workspace 网域。如果您与整个 Google Workspace 网域共享 Google Workspace 资源(例如文档或活动),系统并不会与服务账号共享这些资源。如需了解详情,请参阅服务账号概览。
恢复没有组织者的共享云端硬盘
以下代码示例展示了如何恢复不再有组织者的共享云端硬盘。
Java
Python
Node.js
PHP
.NET
禁止用户下载、打印或复制您的文件
您可以限制用户在共享云端硬盘中下载、打印和复制文件的方式。
如需确定用户是否可以更改组织者为共享云端硬盘设置的下载限制,请检查 capabilities.canChangeDownloadRestriction
布尔值字段。如果 capabilities.canChangeDownloadRestriction
设置为 true
,则可以对共享云端硬盘应用下载限制。如需了解详情,请参阅了解文件功能。
drives
资源包含一组布尔值 restrictions
字段,用于指示是否可以对共享云端硬盘执行操作。限制适用于共享云端硬盘或共享云端硬盘中的内容。
可以使用 drives.update
方法设置限制。
如需对共享云端硬盘应用下载限制,共享云端硬盘管理员可以使用 DownloadRestriction
对象设置 drives
资源的 restrictions.downloadRestriction
字段。
将 restrictedForReaders
布尔值字段设置为 true
表示限制读者下载和复制。将 restrictedForWriters
布尔值字段设置为 true
可声明作者无法下载和复制。请注意,如果 restrictedForWriters
字段为 true
,则读者也无法下载和复制。同样,将 restrictedForWriters
设置为 true
并将 restrictedForReaders
设置为 false
,相当于将 restrictedForWriters
和 restrictedForReaders
都设置为 true
。
向后兼容性
随着 DownloadRestriction
对象的推出,restrictions.copyRequiresWriterPermission
布尔值字段的功能已更新。
现在,将 restrictions.copyRequiresWriterPermission
设置为 true
会将 DownloadRestriction
对象的 restrictedForReaders
布尔值字段更新为 true
,以声明读者无法下载和复制。
将 copyRequiresWriterPermission
字段设置为 false
会将 restrictedForWriters
和 restrictedForReaders
字段都更新为 false
。这意味着所有用户的下载或复制限制设置都会被移除。
用于控制下载、打印和复制功能的字段
下表列出了影响下载、打印和复制功能的 drives
资源字段:
字段 | 说明 | 版本 |
---|---|---|
capabilities.canCopy |
当前用户是否可以复制共享云端硬盘中的文件。 | v2 和 v3 |
capabilities.canDownload |
当前用户是否可以下载共享云端硬盘中的文件。 | v2 和 v3 |
capabilities.canChangeCopyRequiresWriterPermission |
当前用户是否可以更改共享云端硬盘的 copyRequiresWriterPermission 限制。 |
v2 和 v3 |
capabilities.canResetDriveRestrictions |
当前用户是否可以将共享云端硬盘限制重置为默认值。 | v2 和 v3 |
capabilities.canChangeDownloadRestriction |
当前用户是否可以更改共享云端硬盘的下载限制。 | 仅限 v3 |
restrictions.copyRequiresWriterPermission |
是否禁止读者和评论者复制、打印或下载共享云端硬盘中的文件。当 true 时,它会将此共享云端硬盘中任何文件的同名字段设置为 true 。 |
v2 和 v3 |
restrictions.downloadRestriction |
共享云端硬盘管理员应用的下载限制。 | 仅限 v3 |
文件夹限制
共享云端硬盘文件夹有一些存储空间限制。如需了解相关信息,请参阅 Google 云端硬盘的共享云端硬盘限制。
内容数量上限
每个用户的共享云端硬盘最多可包含 50 万项内容,包括文件、文件夹和快捷方式。
达到上限后,共享云端硬盘将无法再接受内容。如需继续接收文件,用户必须从共享云端硬盘中永久删除文件。请注意,回收站中的内容会计入此限制,但永久删除的内容不会计入。如需了解详情,请参阅将文件和文件夹放入回收站或删除。
文件夹深度限制
共享云端硬盘中的文件夹不得包含超过 100 级嵌套的文件夹。 这意味着,子文件夹不能存储在深度超过 99 级的文件夹下。此限制仅适用于子文件夹。
尝试添加超过 100 级的文件夹会返回 teamDriveHierarchyTooDeep
HTTP 状态代码响应。