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

屬性

屬性類型說明
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針對影響項目父項的所有呼叫,啟用或停用 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取得使用者 Google 雲端硬碟垃圾桶中的所有檔案集合。
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,在使用者雲端硬碟的根目錄中建立檔案。

參數

名稱類型說明
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 大於 10 MB,就會擲回例外狀況。

// 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 和資源金鑰建立捷徑,然後傳回。資源金鑰是額外參數,必須傳遞這個參數,才能存取透過連結共用的目標檔案或資料夾。

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

針對影響項目父項的所有呼叫,啟用或停用 enforceSingleParent 行為。

詳情請參閱「 簡化 Google 雲端硬碟的資料夾結構和共用模式」網誌。

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

參數

名稱類型說明
valueBooleanenforceSingleParent 旗標的新狀態。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權:

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

取得使用者 Google 雲端硬碟垃圾桶中的所有檔案。

// 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 說明文件。請注意,Google 雲端硬碟服務使用的是 Drive API 第 2 版,因此部分查詢欄位與第 3 版不同。查看 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());
}

參數

名稱類型說明
paramsString搜尋條件,詳情請參閱 Google 雲端硬碟 SDK 說明文件

回攻員

FileIterator:使用者雲端硬碟中符合搜尋條件的所有檔案。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權:

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

searchFolders(params)

取得使用者雲端硬碟中符合指定搜尋條件的所有資料夾集合。如需搜尋條件的詳細資訊,請參閱 Google 雲端硬碟 SDK 說明文件。請注意,Google 雲端硬碟服務使用的是 Drive API 第 2 版,因此部分查詢欄位與第 3 版不同。查看 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());
}

參數

名稱類型說明
paramsString搜尋條件,詳情請參閱 Google 雲端硬碟 SDK 說明文件

回攻員

FolderIterator:使用者雲端硬碟中符合搜尋條件的所有資料夾。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權:

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

已淘汰的方法