Class DriveApp

DriveApp

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

// Logs the name of every file in the user's Drive.
const files = DriveApp.getFiles();
while (files.hasNext()) {
  const 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	为影响项父项的所有调用启用或停用 enforceSingleParent 行为。
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 在用户云端硬盘的根目录中创建文件。

参数

名称	类型	说明
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 和资源键的快捷方式，并返回该快捷方式。资源键是需要传递的附加参数，用于访问已使用链接共享的目标文件或文件夹。

// 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)

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

如需了解详情，请参阅 简化 Google 云端硬盘的文件夹结构和共享模式博文。

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

参数

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

授权

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

• 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 版云端硬盘 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.""
const files = DriveApp.searchFiles(
    'modifiedDate > "2022-02-28" and title contains "untitled"');
while (files.hasNext()) {
  const 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 版云端硬盘 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.
const folders = DriveApp.searchFolders('starred = true and "me" in owners');
while (folders.hasNext()) {
  const 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