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());
}

属性

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

方法

方法返回类型简介
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获取用户云端硬盘中与指定搜索匹配的所有文件夹的集合 条件。

详细文档

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());
}

参数

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

返回

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());
}

参数

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

返回

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

参数

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

返回

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!');

参数

名称类型说明
nameString新文件的名称。
contentString新文件的内容。

返回

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

参数

名称类型说明
nameString新文件的名称。
contentString新文件的内容。
mimeTypeString新文件的 MIME 类型。

返回

File - 新文件。

授权

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

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

createFolder(name)

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

参数

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

返回

Folder - 新文件夹。

授权

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

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

createShortcut(targetId)

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

参数

名称类型说明
targetIdString目标文件或文件夹的文件 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());
}

参数

名称类型说明
targetIdString目标文件或文件夹的 ID。
targetResourceKeyString目标文件或文件夹的资源密钥。

返回

File - 新的快捷方式。

授权

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

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

enforceSingleParent(value)

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

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

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

参数

名称类型说明
valueBooleanEnforcementSingleParent 标志的新状态。

授权

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

  • 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());
}

参数

名称类型说明
idString文件的 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());
}

参数

名称类型说明
idString文件的 ID。
resourceKeyString文件夹的资源密钥。

返回

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)

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

参数

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

返回

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

授权

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

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

getFilesByType(mimeType)

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

参数

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

返回

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

授权

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

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

getFolderById(id)

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

参数

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

返回

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

授权

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

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

getFolderByIdAndResourceKey(id, resourceKey)

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

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

参数

名称类型说明
idString文件夹的 ID。
resourceKeyString文件夹的资源密钥。

返回

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)

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

参数

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

返回

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());
}

参数

名称类型说明
paramsString搜索条件,如 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());
}

参数

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

返回

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

授权

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

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

已弃用的方法