Google Apps Script

Class DocsList

The DocsList service contains methods to create and retrieve files and folders. The get*ForPaging methods allow retrieval of large sets by providing a Token to paginate with.

 
// This example creates a file called 'example file'
 DocsList.createFile('example file', 'example file contents');
 

Properties

PropertyTypeDescription
DEFAULT_RESULT_SIZEIntegerThe default number of items returned in functions such as getAllFiles().
FileTypeFileType
MAX_RESULT_SIZEIntegerThe maximum number of items returned in functions such as getAllFilesForPaging(number).

Methods

MethodReturn typeBrief description
createFile(blob)FileCreates a file using the data stored in this blob.
createFile(name, contents)FileCreates a file with the given name and contents in the current folder.
createFile(name, contents, mimeType)FileCreates a file with the given name and contents in the current folder with the given MIME type.
createFolder(name)FolderCreates a sub-folder with the given name in the current folder.
find(query)File[]Returns an array of all the files in the container that contain the given string.
findForPaging(query, number)FilesResultReturns the next number files maching the search query and a paging token.
findForPaging(query, number, token)FilesResultReturns the next number files maching the search query, picking up from where the token from the previous lookup left off.
getAllFiles()File[]Returns all the files in the user's drive (up to a maximum of DEFAULT_RESULT_SIZE).
getAllFilesForPaging(number)FilesResultReturns the first number files in drive (up to a maximum of MAX_RESULT_SIZE) and a paging token.
getAllFilesForPaging(number, token)FilesResultReturns the next number files in the user's drive, picking up from where the token from the previous lookup left off.
getAllFolders()Folder[]Returns all the folders in the user's drive (up to a maximum of DEFAULT_RESULT_SIZE).
getAllFoldersForPaging(number)FoldersResultReturns the first number folders in drive and a paging token.
getAllFoldersForPaging(number, token)FoldersResultReturns the next number folders in the user's drive, picking up from where the token from the previous lookup left off.
getFileById(id)FileGets the file with the given ID.
getFilesByType(type)File[]Returns all files of a given type.
getFilesByTypeForPaging(type, number)FilesResultReturns the next number files of the given type in this container and a paging token.
getFilesByTypeForPaging(type, number, token)FilesResultReturns the next number files of the given type in this container, picking up from where the token from the previous lookup left off.
getFolder(path)FolderReturns the folder at a given path.
getFolderById(id)FolderGets the folder with the given ID.
getRootFolder()FolderReturns the root folder.

Detailed documentation

createFile(blob)

Creates a file using the data stored in this blob.

 
// Fetches the Google logo and saves it to a folder
 var url = 'https://www.google.com/images/srpr/logo3w.png';
 var imageBlob = UrlFetchApp.fetch(url).getBlob();
 var folder = DocsList.createFolder('my folder');
 folder.createFile(imageBlob);
 

Parameters

NameTypeDescription
blobBlobSourcethe blob to create the file from

Return

File — the newly created file


createFile(name, contents)

Creates a file with the given name and contents in the current folder. If the file name does not contain an extension, it defaults to plain text.

 
// Creates a file called 'new kitten' in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 folder.createFile('new kitten', 'meow');
 

Parameters

NameTypeDescription
nameStringthe name of the new file
contentsStringthe contents of the new file

Return

File — the newly created file


createFile(name, contents, mimeType)

Creates a file with the given name and contents in the current folder with the given MIME type. If the file name does not contain an extension, it defaults to plain text.

 
// Creates a simple XML file in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var contents = '<kitten><name>Tiny</name><age>1</age></kitten>';
 folder.createFile('kittens.xml', contents, 'application/xml');
 

Parameters

NameTypeDescription
nameStringthe name of the new file
contentsStringthe new file contents
mimeTypeStringthe mime-type of the new file

Return

File — the newly created file


createFolder(name)

Creates a sub-folder with the given name in the current folder.

 
// Creates a subfolder in a folder called 'cats'
 var folder = DocsList.createFolder('cats');
 folder.createFolder('cool cats');
 

Parameters

NameTypeDescription
nameStringthe name of the new folder

Return

Folder — the newly created folder


find(query)

Returns an array of all the files in the container that contain the given string.

 
// Logs the name of all the files resulting from a search for 'cool cats'
 var folder = DocsList.getFolder('cats');
 var coolCats = folder.find('cool cats');
 for (var i in coolCats) {
   Logger.log(coolCats[i].getName());
 }
 

Parameters

NameTypeDescription
queryStringthe search string

Return

File[] — the matching files


findForPaging(query, number)

Returns the next number files maching the search query and a paging token. If the requested number of files do not exist, it returns the available files.

 
// Logs the name of the first 3 files resulting from a search for 'cool cats'
 var folder = DocsList.getFolder('cats');
 var filesResult = folder.findForPaging('cool cats', 3);
 var files = FilesResult.getFiles();
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
queryStringthe search string
numberIntegerthe number of objects to return

Return

FilesResult — the requested number of matching files and a paging token


findForPaging(query, number, token)

Returns the next number files maching the search query, picking up from where the token from the previous lookup left off. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 6 file names resulting from a search but does it 3 at
 // a time.
 var folder = DocsList.getFolder('cats');
 var filesResult = folder.findForPaging('cool cats', 3);
 var files = filesResult.getFiles();
 var token = filesResult.getToken();
 // log the first 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 filesResult = folder.findForPaging('cool cats', 3, token); // pass in previous token
 files = filesResult.getFiles();
 // log the next 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
queryStringthe search string
numberIntegerthe number of objects to return
tokenTokenthe token from the previous lookup

Return

FilesResult — the requested number of matching files and a paging token


getAllFiles()

Returns all the files in the user's drive (up to a maximum of DEFAULT_RESULT_SIZE).

 
// Logs the first file's name.
 var file = DocsList.getAllFiles()[0];
 Logger.log(file.getName());
 

Return

File[] — the requested files


getAllFilesForPaging(number)

Returns the first number files in drive (up to a maximum of MAX_RESULT_SIZE) and a paging token. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 3 file names
 var filesResult = DocsList.getAllFilesForPaging(3);
 var files = filesResult.getFiles();
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of files to return

Return

FilesResult — the requested files


getAllFilesForPaging(number, token)

Returns the next number files in the user's drive, picking up from where the token from the previous lookup left off. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 6 file names but does it 3 at a time.
 var filesResult = DocsList.getAllFilesForPaging(3);
 var files = filesResult.getFiles();
 var token = filesResult.getToken();
 // log the first 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 fileResult = DocsList.getAllFilesForPaging(3, token); // pass in previous token
 files = filesResult.getFiles();
 // log the next 3 file names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of files to return
tokenTokenthe paging token from a previous request

Return

FilesResult — the requested files


getAllFolders()

Returns all the folders in the user's drive (up to a maximum of DEFAULT_RESULT_SIZE).

 
// Logs the first folder's URL.
 var folder = DocsList.getAllFolders()[0];
 Logger.log(folder.getUrl());
 

Return

Folder[] — the requested folders


getAllFoldersForPaging(number)

Returns the first number folders in drive and a paging token. If the requested number of folders do not exist, it returns the available folders.

 
// Logs the first 3 folder URLs (or less if there are fewer
 // than 3 folders)
 var foldersResult = DocsList.getAllFoldersForPaging(3);
 var folders = foldersResult.getFolders();
 for (var i in folders) {
   Logger.log(folders[i].getUrl());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of folders to return

Return

FoldersResult — the requested folders and a paging token


getAllFoldersForPaging(number, token)

Returns the next number folders in the user's drive, picking up from where the token from the previous lookup left off. If the requested number of folders do not exist, it returns the available folders.

 
// Logs the first 6 folder URLs but does it 3 at a time.
 var foldersResult = DocsList.getAllFoldersForPaging(3);
 var folders = foldersResult.getFolders();
 var token = foldersResult.getToken();
 // log the first 3 folder URLs
 for (var i in folders) {
   Logger.log(folders[i].getUrl());
 }
 folderResult = DocsList.getAllFoldersForPaging(3, token); // pass in previous token
 folders = foldersResult.getFolders();
 // log the next 3 folder URLs
 for (var i in folders) {
   Logger.log(folders[i].getUrl());
 }
 

Parameters

NameTypeDescription
numberIntegerthe number of folders to return
tokenTokenthe token from a previous request

Return

FoldersResult — the requested folders and a paging token


getFileById(id)

Gets the file with the given ID.

 
// Gets a file by its ID and logs its name
 var file = DocsList.getFileById('1234567890abcdefghijklmnopqrstuvwxyz');
 Logger.log('File name: ' + file.getName());
 

Parameters

NameTypeDescription
idStringthe ID of the file to be fetched

Return

File — the file with the given ID


getFilesByType(type)

Returns all files of a given type. See FileType for the list of possible file types.

 
// Logs the names of the first document in the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var file = folder.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 Logger.log(file.getName());
 

Parameters

NameTypeDescription
typeFileTypethe type of files to get

Return

File[] — the requested files

See also


getFilesByTypeForPaging(type, number)

Returns the next number files of the given type in this container and a paging token. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 3 document names (or less if there are fewer
 // than 3 documents) from the 'kittens' folder
 var folder = DocsList.getFolder('kittens');
 var filesResult = folder.getFilesForPaging(DocsList.FileType.DOCUMENT, 3);
 var files = FilesResult.getFiles();
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
typeFileTypethe type of files to get
numberIntegerthe number of files to get

Return

FilesResult — the requested files and a paging token

See also


getFilesByTypeForPaging(type, number, token)

Returns the next number files of the given type in this container, picking up from where the token from the previous lookup left off. If the requested number of files do not exist, it returns the available files.

 
// Logs the first 6 document names in the 'kittens' folder but does it 3 at
 // a time.
 var folder = DocsList.getFolder('kittens');
 var filesResult = folder.getFilesForPaging(DocsList.FileType.DOCUMENT, 3);
 var files = filesResult.getFiles();
 var token = filesResult.getToken();
 // log the first 3 document names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 // pass in previous token
 filesResult = folder.getFilesForPaging(DocsList.FileType.DOCUMENT, 3, token);
 files = filesResult.getFiles();
 // log the next 3 document names
 for (var i in files) {
   Logger.log(files[i].getName());
 }
 

Parameters

NameTypeDescription
typeFileTypethe type of files to return
numberIntegerthe number of files to return
tokenTokenthe token from the previous lookup

Return

FilesResult — the requested files and paging token


getFolder(path)

Returns the folder at a given path. Folders in a path are separated by a /. An example of a valid path is: "folder1/sub folder 2". An error occurs if the path provided is not valid.

 
// Gets a folder called 'kittens' and logs the number of files
 // it contains.
 var folder = DocsList.getFolder('kittens');
 Logger.log(folder.getFiles().length);
 

Parameters

NameTypeDescription
pathStringthe path of the folder

Return

Folder — the requested folder at that path


getFolderById(id)

Gets the folder with the given ID.

 
// Gets a folder by its ID and logs its name
 var folder = DocsList.getFolderById('1234567890abcdefghijklmnopqrstuvwxyz');
 Logger.log('Folder name: ' + folder.getName());
 

Parameters

NameTypeDescription
idStringthe ID of the folder to be fetched

Return

Folder — the folder with the given ID


getRootFolder()

Returns the root folder.

 
// Logs the number of items in the root folder
 var folder = DocsList.getRootFolder();
 Logger.log(folder.getFiles().length);
 

Return

Folder — the root folder

Deprecated methods




Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.