Google Apps Script

Class File

This class contains methods to get information about the file and modify its contents.

 
// This example logs the file type of the first file
 var file = DocsList.getAllFiles()[0];
 Logger.log(file.getFileType());
 

Methods

MethodReturn typeBrief description
addEditor(emailAddress)FileAdds the given user to the list of editors for the File.
addEditor(user)FileAdds the given user to the list of editors for the File.
addEditors(emailAddresses)FileAdds the given array of users to the list of editors for the File.
addToFolder(parent)voidAdds the item to the given folder.
addViewer(emailAddress)FileAdds the given user to the list of viewers for the File.
addViewer(user)FileAdds the given user to the list of viewers for the File.
addViewers(emailAddresses)FileAdds the given array of users to the list of viewers for the File.
append(contents)voidAppends the given string to the existing contents of the file.
clear()voidClears all the contents of a document that is not of a Google Docs format.
getAs(contentType)BlobReturn the data inside this object as a blob converted to the specified content type.
getBlob()BlobReturn the data inside this object as a blob.
getContentAsString()StringReturns the contents of any file that isn't a Google document type as a string.
getDateCreated()DateGets the date that this item was created.
getDescription()StringReturns the description of the item or null if a description doesn't exist.
getEditors()User[]Gets the list of editors for this File.
getFileType()FileTypeReturns the FileType of the file.
getId()StringReturns the document ID associated with the item.
getLastUpdated()DateGets the date that this item was last updated.
getName()StringReturns the name of the item.
getOwner()UserGets the owner of the item.
getParents()Folder[]Returns the parent folders.
getSize()IntegerReturns the amount of disk space used by the item.
getThumbnail()BlobReturns the thumbnail image associated with this item, or null if no thumbnail exists.
getUrl()StringReturns a URL to access the particular item.
getViewers()User[]Gets the list of viewers and commenters for this File.
isStarred()BooleanGets whether the item is starred.
isTrashed()BooleanChecks whether the item is trashed.
makeCopy()FileMakes a copy of the file with a default name (i.e.
makeCopy(newName)FileReturns a copy of the current file with the given name.
removeEditor(emailAddress)FileRemoves the given user from the list of editors for the File.
removeEditor(user)FileRemoves the given user from the list of editors for the File.
removeFromFolder(parent)voidRemoves this object from the given folder.
removeViewer(emailAddress)FileRemoves the given user from the list of viewers and commenters for the File.
removeViewer(user)FileRemoves the given user from the list of viewers and commenters for the File.
rename(newName)voidRename the item.
replace(contents)voidReplaces the contents of the file with the contents provided.
setDescription(description)voidUpdate's the item's description.
setStarred(starred)voidSets the item's starred status in drive.
setTrashed(trash)voidSets the trashed status of an item but does not permanently delete it.

Detailed documentation

addEditor(emailAddress)

Adds the given user to the list of editors for the File. If the user was already on the list of viewers, this method promotes the user out of the list of viewers.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to add

Return

File — this File, for chaining


addEditor(user)

Adds the given user to the list of editors for the File. If the user was already on the list of viewers, this method promotes the user out of the list of viewers.

Parameters

NameTypeDescription
userUsera representation of the user to add

Return

File — this File, for chaining


addEditors(emailAddresses)

Adds the given array of users to the list of editors for the File. If any of the users were already on the list of viewers, this method promotes them out of the list of viewers.

Parameters

NameTypeDescription
emailAddressesString[]an array of email addresses of the users to add

Return

File — this File, for chaining


addToFolder(parent)

Adds the item to the given folder.

 
// This example creates a new file and adds it to a folder
 // Note: This can also be used on a folder to add it to another folder
 var file = DocsList.createFile('my test file', 'test file contents');
 var folder = DocsList.createFolder('My Test Folder');
 file.addToFolder(folder);
 Logger.log(file.getParents()[0].getName()); // logs 'My Test Folder'
 

Parameters

NameTypeDescription
parentFolderthe folder to add the item to

addViewer(emailAddress)

Adds the given user to the list of viewers for the File. If the user was already on the list of editors, this method has no effect.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to add

Return

File — this File, for chaining


addViewer(user)

Adds the given user to the list of viewers for the File. If the user was already on the list of editors, this method has no effect.

Parameters

NameTypeDescription
userUsera representation of the user to add

Return

File — this File, for chaining


addViewers(emailAddresses)

Adds the given array of users to the list of viewers for the File. If any of the users were already on the list of editors, this method has no effect for them.

Parameters

NameTypeDescription
emailAddressesString[]an array of email addresses of the users to add

Return

File — this File, for chaining


append(contents)

Appends the given string to the existing contents of the file.

 
// This example creates a file called "log.txt" and appends to it.
 var file = DocsList.createFile("log.txt", "My Log File");
 file.append("\nFirst log entry");
 

Parameters

NameTypeDescription
contentsStringthe string to append to the file

clear()

Clears all the contents of a document that is not of a Google Docs format. It's permissible to use any document that returns FileType.OTHER to getFileType().

 
// Creates a file and logs its contents before and after clear is invoked
 var file = DocsList.createFile('my new file', 'sample file contents');
 Logger.log('content before clear: ' + file.getContentAsString());
 file.clear();
 Logger.log('content after clear: ' + file.getContentAsString());
 // This logs the following:
 // content before clear: sample file contents
 // content after clear:
 

getAs(contentType)

Return the data inside this object as a blob converted to the specified content type. This method adds the appropriate extension to the filename — for example, "myfile.pdf". However, it assumes that the part of the filename that follows the last period (if any) is an existing extension that should be replaced. Consequently, "ChristmasList.12.25.2014" will become "ChristmasList.12.25.pdf".

Parameters

NameTypeDescription
contentTypeStringthe MIME type to convert to. For most blobs, 'application/pdf' is the only valid option. For images in BMP, GIF, JPEG, or PNG format, any of 'image/bmp', 'image/gif', 'image/jpeg', or 'image/png' are also valid.

Return

Blob — the data as a blob


getBlob()

Return the data inside this object as a blob.

Return

Blob — the data as a blob


getContentAsString()

Returns the contents of any file that isn't a Google document type as a string.

 
// Creates a new file and logs its content
 var file = DocsList.createFile('my new file', 'sample file contents');
 Logger.log(file.getContentAsString()); // logs 'sample file contents'
 

Return

String — the content of the file


getDateCreated()

Gets the date that this item was created.

 
// This example logs the date the first file was created.
 // Note: This can also be used on a folder
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getDateCreated());
 

Return

Date — the date this item was created


getDescription()

Returns the description of the item or null if a description doesn't exist.

 
// Gets the first document's description.
 // Note: This can also be used on a folder
 var doc = DocsList.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 Logger.log(doc.getDescription());
 

Return

String — the item's description


getEditors()

Gets the list of editors for this File. If the user who executes the script does not have edit access to the File, this method throws an exception.

Return

User[] — an array of users with edit permission


getFileType()

Returns the FileType of the file.

 
// Logs the name and file type of the first file in drive.
 var file = DocsList.getAllFiles()[0];
 Logger.log('Name: ' + file.getName() + ', Type: ' + file.getFileType());
 

Return

FileType — the type of the file

See also


getId()

Returns the document ID associated with the item.

 
// Logs the first file's document ID.
 // Note: This can also be used on a folder.
 var file = DocsList.getAllFiles()[0];
 Logger.log(file.getId());
 

Return

String — the document ID of the item


getLastUpdated()

Gets the date that this item was last updated.

 
// This example logs the date the first file was last updated.
 // Note: This can also be used on a folder
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getLastUpdated());
 

Return

Date — the date this item was last updated


getName()

Returns the name of the item.

 
// Logs the first file's name.
 // Note: This can also be used on a folder.
 var file = DocsList.getAllFiles()[0];
 Logger.log(file.getName());
 

Return

String — the name of the item


getOwner()

Gets the owner of the item.

 
// This example creates a file and logs the owner's email address
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 Logger.log(file.getOwner().getEmail()); // logs your own email address
 

Return

User — the owner of the item


getParents()

Returns the parent folders. If called on a top level item, it returns the root folder. An item can be placed in multiple folders in drive. See the drive documentation.

 
// This example logs the name of the parent folder of the first doc.
 // Note: This can also be used on a folder to get its parent
 var file = DocsList.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 Logger.log(file.getParents()[0].getName());
 

Return

Folder[] — the parent folders containing the item


getSize()

Returns the amount of disk space used by the item. Note that it returns zero if called on an item that does not consume disk space, such as a Google document type file.

 
// This example logs the first file's size in bytes
 // Note: This can also be used on a folder to get the size of its contents
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getSize());
 

Return

Integer — the item's size in bytes, or zero if the item is a Google document type or does not consume space


getThumbnail()

Returns the thumbnail image associated with this item, or null if no thumbnail exists.

 
// This example sends an email to the active user with a thumbnail of the
 // first kitten picture in drive as an attachment.
 var file = DocsList.find("kitten.jpeg")[0];
 var thumbnail = file.getThumbnail();
 MailApp.sendEmail(Session.getActiveUser(), 'Kitten!',
                   'A picture of a kitten.', { attachments: thumbnail });
 

Return

Blob — the thumbnail image of this file


getUrl()

Returns a URL to access the particular item.

 
// This example logs the first file's URL
 // Note: This can also be used on a folder
 var file = DocsList.getAllFiles[0];
 Logger.log(file.getUrl());
 

Return

String — the item's URL


getViewers()

Gets the list of viewers and commenters for this File. If the user who executes the script does not have edit access to the File, this method throws an exception.

Return

User[] — an array of users with view or comment permission


isStarred()

Gets whether the item is starred.

 
// This example creates a new file, stars it, and tests whether it is starred.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setStarred(true); // the file should be starred in drive
 Logger.log(file.isStarred()); // logs true
 

Return

Boolean — true if the item is starred


isTrashed()

Checks whether the item is trashed.

 
// This example creates a new file and then sets it trashed.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setTrashed(true); // the file should be trashed in drive
 Logger.log(file.isTrashed()); // logs true
 

Return

Boolean — true if the item is trashed


makeCopy()

Makes a copy of the file with a default name (i.e. 'Copy of...')

 
// This example makes a copy of a file called "My Document" and logs its
 // name.
 var file = DocsList.find("My Document")[0];
 var copy = file.makeCopy();
 Logger.log(copy.getName());
 // There should now be a new file called "Copy of My Document".
 

Return

File — the file copy just created


makeCopy(newName)

Returns a copy of the current file with the given name.

 
// This example copies a file called "My Document" and names it
 // "My New Document".
 var file = DocsList.find("My Document")[0];
 var copy = file.makeCopy("My New Document");
 

Parameters

NameTypeDescription
newNameStringthe name of the file copy

Return

File — the file copy just created


removeEditor(emailAddress)

Removes the given user from the list of editors for the File. This method does not block users from accessing the File if they belong to a class of users who have general access — for example, if the File is shared with the user's entire domain.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to remove

Return

File — this File, for chaining


removeEditor(user)

Removes the given user from the list of editors for the File. This method does not block users from accessing the File if they belong to a class of users who have general access — for example, if the File is shared with the user's entire domain.

Parameters

NameTypeDescription
userUsera representation of the user to remove

Return

File — this File, for chaining


removeFromFolder(parent)

Removes this object from the given folder. If the item does not belong to the folder, this does nothing.

 
// This example creates a new file, adds it to a folder, and then removes
  // it from the folder.
 // Note: This can also be used on a folder to remove it from another folder
 var file = DocsList.createFile('my test file', 'test file contents');
 var folder = DocsList.createFolder('My Test Folder');
 file.addToFolder(folder);
 Logger.log(folder.getFiles().length); // logs 1
 file.removeFromFolder(folder);
 Logger.log(folder.getFiles().length); // logs 0
 

Parameters

NameTypeDescription
parentFolderthe folder to remove the item from

removeViewer(emailAddress)

Removes the given user from the list of viewers and commenters for the File. This method has no effect if the user is an editor, not a viewer or commenter. This method also does not block users from accessing the File if they belong to a class of users who have general access — for example, if the File is shared with the user's entire domain.

Parameters

NameTypeDescription
emailAddressStringthe email address of the user to remove

Return

File — this File for chaining


removeViewer(user)

Removes the given user from the list of viewers and commenters for the File. This method has no effect if the user is an editor, not a viewer. This method also does not block users from accessing the File if they belong to a class of users who have general access — for example, if the File is shared with the user's entire domain.

Parameters

NameTypeDescription
userUsera representation of the user to remove

Return

File — this File for chaining


rename(newName)

Rename the item.

 
// Creates a file called 'Old File' and renames it 'New File'.
 // Note: This can also be used on a folder
 var oldFile = DocsList.createFile('Old File', '');
 oldFile.rename('New File');
 Logger.log(oldFile.getName()); // This should log "New File"
 

Parameters

NameTypeDescription
newNameStringthe new name of the item

replace(contents)

Replaces the contents of the file with the contents provided.

 
// This example creates a file called "log.txt" and replaces its contents.
 var file = DocsList.createFile("log.txt", "My Log File");
 file.replace("New log content");
 

Parameters

NameTypeDescription
contentsStringthe string with which to replace the file contents

setDescription(description)

Update's the item's description.

 
// This example sets the first document's description
 // Note: This can also be used on a folder
 var doc = DocsList.getFilesByType(DocsList.FileType.DOCUMENT)[0];
 doc.setDescription('My First Doc');
 Logger.log(doc.getDescription()); // logs 'My First Doc'
 

Parameters

NameTypeDescription
descriptionStringthe item's description

setStarred(starred)

Sets the item's starred status in drive.

 
// This example creates a new file and stars it.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setStarred(true); // the file should be starred in drive
 

Parameters

NameTypeDescription
starredBooleanstars the item if true; unstars it if false

setTrashed(trash)

Sets the trashed status of an item but does not permanently delete it.

 
// This example creates a new file and then sets it trashed.
 // Note: This can also be used on a folder
 var file = DocsList.createFile('my test file', 'test file contents');
 file.setTrashed(true); // the file should be trashed in drive
 Logger.log(file.isTrashed()); // logs true
 

Parameters

NameTypeDescription
trashBooleantrashes the item if true; untrashes it if false

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.