Class DriveApp

DriveApp

允许脚本创建、查找和修改 Google 云端硬盘中的文件和文件夹。要访问文件或 文件夹中的文件，请使用高级云端硬盘服务。

// Logs the name of every file in the user's Drive.
var files = DriveApp.getFiles();
while (files.hasNext()) {
  var file = files.next();
  console.log(file.getName());
}

属性

属性	类型	说明
Access	Access	表示可以访问文件或文件夹的各类用户的枚举，除任何个人之外 已被明确授予访问权限的用户
Permission	Permission	一个枚举，表示向可以访问文件或文件夹的用户授予的权限， 任何被明确授予访问权限的单个用户。

方法

方法	返回类型	简介
continueFileIterator(continuationToken)	FileIterator	使用来自上一个迭代器的继续令牌恢复文件迭代。
continueFolderIterator(continuationToken)	FolderIterator	使用来自上一个迭代器的继续令牌恢复文件夹迭代。
createFile(blob)	File	基于给定 Blob 的任意数据在用户云端硬盘的根目录下创建一个文件。
createFile(name, content)	File	使用指定名称和内容在用户云端硬盘的根目录下创建一个文本文件。
createFile(name, content, mimeType)	File	使用指定名称、内容和 MIME 类型在用户的云端硬盘根目录中创建文件。
createFolder(name)	Folder	使用指定名称在用户云端硬盘的根目录下创建文件夹。
createShortcut(targetId)	File	创建指向所提供的云端硬盘内容 ID 的快捷方式，并将其返回。
createShortcutForTargetIdAndResourceKey(targetId, targetResourceKey)	File	为提供的云端硬盘内容 ID 和资源密钥创建快捷方式，并将其返回。
enforceSingleParent(value)	void	为影响项父级的所有调用启用或停用 forceSingleParent 行为。
getFileById(id)	File	获取具有指定 ID 的文件。
getFileByIdAndResourceKey(id, resourceKey)	File	获取具有指定 ID 和资源密钥的文件。
getFiles()	FileIterator	获取用户云端硬盘中所有文件的集合。
getFilesByName(name)	FileIterator	获取用户云端硬盘中具有指定名称的所有文件的集合。
getFilesByType(mimeType)	FileIterator	获取用户云端硬盘中具有指定 MIME 类型的所有文件的集合。
getFolderById(id)	Folder	获取具有指定 ID 的文件夹。
getFolderByIdAndResourceKey(id, resourceKey)	Folder	获取具有指定 ID 和资源密钥的文件夹。
getFolders()	FolderIterator	获取用户云端硬盘中所有文件夹的集合。
getFoldersByName(name)	FolderIterator	获取用户云端硬盘中具有指定名称的所有文件夹的集合。
getRootFolder()	Folder	获取用户云端硬盘根目录下的文件夹。
getStorageLimit()	Integer	获取允许用户在云端硬盘中存储的字节数。
getStorageUsed()	Integer	获取用户当前在云端硬盘中存储的字节数。
getTrashedFiles()	FileIterator	获取用户云端硬盘回收站中所有文件的集合。
getTrashedFolders()	FolderIterator	获取用户云端硬盘回收站中所有文件夹的集合。
searchFiles(params)	FileIterator	获取用户云端硬盘中与指定搜索匹配的所有文件的集合 条件。
searchFolders(params)	FolderIterator	获取用户云端硬盘中与指定搜索匹配的所有文件夹的集合 条件。

已弃用的方法

方法	返回类型	简介
addFile(child)	Folder	将指定文件添加到用户云端硬盘的根目录。
addFolder(child)	Folder	将指定文件夹添加到用户云端硬盘的根目录。
removeFile(child)	Folder	从用户云端硬盘的根目录中移除指定文件。
removeFolder(child)	Folder	从用户的云端硬盘根目录中移除指定文件夹。

详细文档

continueFileIterator(continuationToken)

使用来自上一个迭代器的继续令牌恢复文件迭代。此方法 在一次执行中处理迭代器超过最长执行时间时非常有用。 接续令牌的有效期通常为一周。

// Continues getting a list of all 'Untitled document' files in the user's Drive.
// Creates a file iterator named 'previousIterator'.
const previousIterator = DriveApp.getFilesByName('Untitled document');

// Gets continuation token from the previous file iterator.
const continuationToken = previousIterator.getContinuationToken();

// Creates a new iterator using the continuation token from the previous file iterator.
const newIterator = DriveApp.continueFileIterator(continuationToken);

// Resumes the file iteration using a continuation token from 'firstIterator' and
// logs the file name.
if (newIterator.hasNext()) {
  const file = newIterator.next();
  console.log(file.getName());
}

参数

名称	类型	说明
continuationToken	String	来自上一个文件迭代器的延续令牌。

返回

FileIterator - 当继续令牌出现时保留在上一个迭代器中的文件集合 已生成。

---

continueFolderIterator(continuationToken)

使用来自上一个迭代器的继续令牌恢复文件夹迭代。此方法 在一次执行中处理迭代器超过最长执行时间时非常有用。 接续令牌的有效期通常为一周。

// Continues getting a list of all folders in user's Drive.
// Creates a folder iterator named 'previousIterator'.
const previousIterator = DriveApp.getFolders();

// Gets continuation token from the previous folder iterator.
const continuationToken = previousIterator.getContinuationToken();

// Creates a new iterator using the continuation token from the previous folder iterator.
const newIterator = DriveApp.continueFolderIterator(continuationToken);

// Resumes the folder iteration using a continuation token from the previous iterator and logs
// the folder name.
if (newIterator.hasNext()) {
  const folder = newIterator.next();
  console.log(folder.getName());
}

参数

名称	类型	说明
continuationToken	String	来自上一个文件夹迭代器的延续令牌。

返回

FolderIterator - 接续时保留在上一个迭代器中的文件夹集合 已生成令牌。

---

createFile(blob)

基于给定 Blob 的任意数据在用户云端硬盘的根目录下创建一个文件。

// Create an image file in Google Drive using the Maps service.
var blob = Maps.newStaticMap().setCenter('76 9th Avenue, New York NY').getBlob();
DriveApp.createFile(blob);

参数

名称	类型	说明
blob	BlobSource	新文件的数据。

返回

File - 新文件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

createFile(name, content)

使用指定名称和内容在用户云端硬盘的根目录下创建一个文本文件。抛出 异常（如果 content 大于 50 MB）。

// Create a text file with the content "Hello, world!"
DriveApp.createFile('New Text File', 'Hello, world!');

参数

名称	类型	说明
name	String	新文件的名称。
content	String	新文件的内容。

返回

File - 新文件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

createFile(name, content, mimeType)

使用指定名称、内容和 MIME 类型在用户的云端硬盘根目录中创建文件。抛出 如果 content 大于 10MB，则会发生异常。

// Create an HTML file with the content "Hello, world!"
DriveApp.createFile('New HTML File', '<b>Hello, world!</b>', MimeType.HTML);

参数

名称	类型	说明
name	String	新文件的名称。
content	String	新文件的内容。
mimeType	String	新文件的 MIME 类型。

返回

File - 新文件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

createFolder(name)

使用指定名称在用户云端硬盘的根目录下创建文件夹。

参数

名称	类型	说明
name	String	新文件夹的名称。

返回

Folder - 新文件夹。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

createShortcut(targetId)

创建指向所提供的云端硬盘内容 ID 的快捷方式，并将其返回。

参数

名称	类型	说明
targetId	String	目标文件或文件夹的文件 ID。

返回

File - 新的快捷方式。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

createShortcutForTargetIdAndResourceKey(targetId, targetResourceKey)

为提供的云端硬盘内容 ID 和资源密钥创建快捷方式，并将其返回。资源 key 是一个附加参数，需要传递该参数，以访问 已通过链接共享。

// Creates shortcuts for all folders in the user's drive that have a specific name.
// TODO(developer): Replace 'Test-Folder' with a valid folder name in your drive.
const folders = DriveApp.getFoldersByName('Test-Folder');

// Iterates through all folders named 'Test-Folder'.
while (folders.hasNext()) {
  const folder = folders.next();

  // Creates a shortcut to the provided Drive item ID and resource key, and returns it.
  DriveApp.createShortcutForTargetIdAndResourceKey(folder.getId(), folder.getResourceKey());
}

参数

名称	类型	说明
targetId	String	目标文件或文件夹的 ID。
targetResourceKey	String	目标文件或文件夹的资源密钥。

返回

File - 新的快捷方式。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

enforceSingleParent(value)

为影响项父级的所有调用启用或停用 forceSingleParent 行为。

请参阅 简化 Google 云端硬盘的文件夹结构和共享模型博客，了解 。

// Enables enforceSingleParent behavior for all calls affecting item parents.
DriveApp.enforceSingleParent(true);

参数

名称	类型	说明
value	Boolean	EnforcementSingleParent 标志的新状态。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

getFileById(id)

获取具有指定 ID 的文件。如果文件不存在或 用户无权访问这些数据。

// Gets a list of all files in Google Drive with the given name.
// TODO(developer): Replace 'Test' with your file name.
const files = DriveApp.getFilesByName('Test');

if (files.hasNext()) {
  // Gets the ID of each file in the list.
  const fileId = files.next().getId();

  // Gets the file name using its ID and logs it to the console.
  console.log(DriveApp.getFileById(fileId).getName());
}

参数

名称	类型	说明
id	String	文件的 ID。

返回

File - 具有指定 ID 的文件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFileByIdAndResourceKey(id, resourceKey)

获取具有指定 ID 和资源密钥的文件。资源键是附加参数 需要传递该字段，才能访问通过链接共享的文件。

如果文件不存在或用户没有权限，会抛出脚本异常 访问它。

// Gets a list of all files in Drive with the given name.
// TODO(developer): Replace 'Test' with your file name.
const files = DriveApp.getFilesByName('Test');
if (files.hasNext()) {

  // Gets the first file in the list.
  const file = files.next();

  // Gets the ID and resource key.
  const key = file.getResourceKey();
  const id = file.getId();

  // Logs the file name to the console using its ID and resource key.
  console.log(DriveApp.getFileByIdAndResourceKey(id, key).getName());
}

参数

名称	类型	说明
id	String	文件的 ID。
resourceKey	String	文件夹的资源密钥。

返回

File - 具有指定 ID 的文件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFiles()

获取用户云端硬盘中所有文件的集合。

返回

FileIterator - 用户云端硬盘中所有文件的集合。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFilesByName(name)

获取用户云端硬盘中具有指定名称的所有文件的集合。

参数

名称	类型	说明
name	String	要查找的文件的名称。

返回

FileIterator - 用户云端硬盘中具有指定名称的所有文件的集合。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFilesByType(mimeType)

获取用户云端硬盘中具有指定 MIME 类型的所有文件的集合。

参数

名称	类型	说明
mimeType	String	要查找的文件的 MIME 类型。

返回

FileIterator - 用户云端硬盘中具有指定 MIME 的所有文件的集合 类型。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFolderById(id)

获取具有指定 ID 的文件夹。如果文件夹不存在或 该用户无权访问这些数据。

参数

名称	类型	说明
id	String	文件夹的 ID。

返回

Folder - 具有指定 ID 的文件夹。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFolderByIdAndResourceKey(id, resourceKey)

获取具有指定 ID 和资源密钥的文件夹。资源键是附加参数 需要传递该字段，才能访问已使用链接共享的文件夹。

如果文件夹不存在或用户没有权限，会抛出脚本异常 访问它。

参数

名称	类型	说明
id	String	文件夹的 ID。
resourceKey	String	文件夹的资源密钥。

返回

Folder - 具有指定 ID 的文件夹。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFolders()

获取用户云端硬盘中所有文件夹的集合。

返回

FolderIterator - 用户云端硬盘中所有文件夹的集合。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getFoldersByName(name)

获取用户云端硬盘中具有指定名称的所有文件夹的集合。

参数

名称	类型	说明
name	String	要查找的文件夹的名称。

返回

FolderIterator - 用户云端硬盘中具有给定名称的所有文件夹的集合。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getRootFolder()

获取用户云端硬盘根目录下的文件夹。

// Gets the user's My Drive folder and logs its name to the console.
console.log(DriveApp.getRootFolder().getName());

// Logs the Drive owner's name to the console.
console.log(DriveApp.getRootFolder().getOwner().getName());

返回

Folder - 用户云端硬盘的根文件夹。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getStorageLimit()

获取允许用户在云端硬盘中存储的字节数。

// Gets the number of bytes the user can store in Drive and logs it to the console.
console.log(DriveApp.getStorageLimit());

返回

Integer - 允许用户在云端硬盘中存储的字节数。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getStorageUsed()

获取用户当前在云端硬盘中存储的字节数。

// Gets the number of bytes the user is currently storing in Drive and logs it to the console.
console.log(DriveApp.getStorageUsed());

返回

Integer - 用户目前在云端硬盘中存储的字节数。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getTrashedFiles()

获取用户云端硬盘回收站中所有文件的集合。

// Gets a list of all the files in the trash of the user's Drive.
const trashFiles = DriveApp.getTrashedFiles();

// Logs the trash file names to the console.
while (trashFiles.hasNext()) {
  const file = trashFiles.next();
  console.log(file.getName());
}

返回

FileIterator - 回收站中的一系列文件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

getTrashedFolders()

获取用户云端硬盘回收站中所有文件夹的集合。

// Gets a collection of all the folders in the trash of the user's Drive.
const trashFolders = DriveApp.getTrashedFolders();

// Logs the trash folder names to the console.
while (trashFolders.hasNext()) {
  const folder = trashFolders.next();
  console.log(folder.getName());
}

返回

FolderIterator - 回收站中的文件夹集合。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

searchFiles(params)

获取用户云端硬盘中与指定搜索匹配的所有文件的集合 条件。Google 云端硬盘 SDK 文档中详细说明了搜索条件。请注意，云端硬盘 服务使用 v2 的 Drive API，并且某些查询字段与 v3 不同。查看字段 v2 和 v3 之间的差异。

params 参数是一个可以包含字符串值的查询字符串，因此请务必小心 正确转义引号（例如 "title contains 'Gulliver\\'s Travels'" 或 'title contains "Gulliver\'s Travels"'）。

// Logs the name of every file in the user's Drive that modified after February 28,
// 2022 whose name contains "untitled.""
var files = DriveApp.searchFiles(
    'modifiedDate > "2022-02-28" and title contains "untitled"');
while (files.hasNext()) {
  var file = files.next();
  console.log(file.getName());
}

参数

名称	类型	说明
params	String	搜索条件，如 Google 云端硬盘 SDK 文档中所述。

返回

FileIterator - 用户云端硬盘中与搜索条件匹配的所有文件的集合 条件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

---

searchFolders(params)

获取用户云端硬盘中与指定搜索匹配的所有文件夹的集合 条件。Google 云端硬盘 SDK 文档中详细说明了搜索条件。请注意，云端硬盘 服务使用 v2 的 Drive API，并且某些查询字段与 v3 不同。查看字段 v2 和 v3 之间的差异。

params 参数是一个可以包含字符串值的查询字符串，因此请务必小心 正确转义引号（例如 "title contains 'Gulliver\\'s Travels'" 或 'title contains "Gulliver\'s Travels"'）。

// Logs the name of every folder in the user's Drive that you own and is starred.
var folders = DriveApp.searchFolders('starred = true and "me" in owners');
while (folders.hasNext()) {
  var folder = folders.next();
  console.log(folder.getName());
}

参数

名称	类型	说明
params	String	搜索条件，如 Google 云端硬盘 SDK 文档中所述。

返回

FolderIterator - 用户云端硬盘中与搜索条件匹配的所有文件夹的集合 条件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive

已弃用的方法

addFile(child)

已弃用。请改用 File.moveTo(destination) 或 Folder.createShortcut(targetId)。

将指定文件添加到用户云端硬盘的根目录。此方法不会将文件从 现有父级文件夹；一个文件可以同时有多个父级文件。

参数

名称	类型	说明
child	File	要添加的子文件。

返回

Folder - 作为子文件添加的文件的新父文件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

addFolder(child)

已弃用。请改用 Folder.moveTo(destination) 或 Folder.createShortcut(targetId)。

将指定文件夹添加到用户云端硬盘的根目录。此方法不会将文件夹移出 现有的父级文件夹；一个文件夹可以同时有多个父级文件夹。

参数

名称	类型	说明
child	Folder	要添加的子文件夹。

返回

Folder - 作为子文件夹添加的文件夹的新父文件夹。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

removeFile(child)

已弃用。而应使用 File.moveTo(destination)。

从用户云端硬盘的根目录中移除指定文件。此方法不会删除文件， 如果将某个文件从其所有父级中移除，那么除非搜索，否则您将无法在云端硬盘中查看该文件 或使用“所有项”视图。

参数

名称	类型	说明
child	File	要移除的子文件。

返回

Folder - 子级的上一个父级。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive

---

removeFolder(child)

已弃用。而应使用 Folder.moveTo(destination)。

从用户的云端硬盘根目录中移除指定文件夹。此方法不会删除文件夹 或其内容，但如果文件夹从其所有父级文件夹中移除，则无法在云端硬盘中查看该文件夹 不过，您可以进行搜索或使用“所有项”视图。

参数

名称	类型	说明
child	Folder	要移除的子文件夹。

返回

Folder - 子级的上一个父级。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/drive