Class File

Deprecated. The DocsList service was deprecated on December 11, 2014. To work with files in Google Drive, use the Drive service instead.

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

Method	Return type	Brief description
`getAs(contentType)`	`Blob`	Return the data inside this object as a blob converted to the specified content type.
`getBlob()`	`Blob`	Return the data inside this object as a blob.

Deprecated methods

Method	Return type	Brief description
`addEditor(emailAddress)`	`File`	Adds the given user to the list of editors for the `File`.
`addEditor(user)`	`File`	Adds the given user to the list of editors for the `File`.
`addEditors(emailAddresses)`	`File`	Adds the given array of users to the list of editors for the `File`.
`addToFolder(parent)`	`void`	Adds the item to the given folder.
`addViewer(emailAddress)`	`File`	Adds the given user to the list of viewers for the `File`.
`addViewer(user)`	`File`	Adds the given user to the list of viewers for the `File`.
`addViewers(emailAddresses)`	`File`	Adds the given array of users to the list of viewers for the `File`.
`append(contents)`	`void`	Appends the given string to the existing contents of the file.
`clear()`	`void`	Clears all the contents of a document that is not of a Google Docs format.
`getContentAsString()`	`String`	Returns the contents of any file that isn't a Google document type as a string.
`getDateCreated()`	`Date`	Gets the date that this item was created.
`getDescription()`	`String`	Returns the description of the item or null if a description doesn't exist.
`getEditors()`	`User[]`	Gets the list of editors for this `File`.
`getFileType()`	`FileType`	Returns the `FileType` of the file.
`getId()`	`String`	Returns the document ID associated with the item.
`getLastUpdated()`	`Date`	Gets the date that this item was last updated.
`getName()`	`String`	Returns the name of the item.
`getOwner()`	`User`	Gets the owner of the item.
`getParents()`	`Folder[]`	Returns the parent folders.
`getSize()`	`Integer`	Returns the amount of disk space used by the item.
`getThumbnail()`	`Blob`	Returns the thumbnail image associated with this item, or `null` if no thumbnail exists.
`getType()`	`String`	Returns the file type.
`getUrl()`	`String`	Returns a URL to access the particular item.
`getViewers()`	`User[]`	Gets the list of viewers and commenters for this `File`.
`isStarred()`	`Boolean`	Gets whether the item is starred.
`isTrashed()`	`Boolean`	Checks whether the item is trashed.
`makeCopy()`	`File`	Makes a copy of the file with a default name (i.e.
`makeCopy(newName)`	`File`	Returns a copy of the current file with the given name.
`removeEditor(emailAddress)`	`File`	Removes the given user from the list of editors for the `File`.
`removeEditor(user)`	`File`	Removes the given user from the list of editors for the `File`.
`removeFromFolder(parent)`	`void`	Removes this object from the given folder.
`removeViewer(emailAddress)`	`File`	Removes the given user from the list of viewers and commenters for the `File`.
`removeViewer(user)`	`File`	Removes the given user from the list of viewers and commenters for the `File`.
`rename(newName)`	`void`	Rename the item.
`replace(contents)`	`void`	Replaces the contents of the file with the contents provided.
`setDescription(description)`	`void`	Update's the item's description.
`setStarred(starred)`	`void`	Sets the item's starred status in drive.
`setTrashed(trash)`	`void`	Sets the trashed status of an item but does not permanently delete it.

Detailed documentation

`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

Name	Type	Description
`contentType`	`String`	the 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

Deprecated methods

`addEditor(emailAddress)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`emailAddress`	`String`	the email address of the user to add

Return

File — this File, for chaining

`addEditor(user)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`user`	`User`	a representation of the user to add

Return

File — this File, for chaining

`addEditors(emailAddresses)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`emailAddresses`	`String[]`	an array of email addresses of the users to add

Return

File — this File, for chaining

`addToFolder(parent)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`parent`	`Folder`	the folder to add the item to

`addViewer(emailAddress)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`emailAddress`	`String`	the email address of the user to add

Return

File — this File, for chaining

`addViewer(user)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`user`	`User`	a representation of the user to add

Return

File — this File, for chaining

`addViewers(emailAddresses)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`emailAddresses`	`String[]`	an array of email addresses of the users to add

Return

File — this File, for chaining

`append(contents)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`contents`	`String`	the string to append to the file

`clear()`

Deprecated. This function is deprecated and should not be used in new scripts.

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:

`getContentAsString()`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

`getId()`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

`getType()`

Deprecated. This function is deprecated and should not be used in new scripts.

Returns the file type. For the Google file types, this will be one of "spreadsheet", "document" or "presentation".

Return

String — the file type

`getUrl()`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`newName`	`String`	the name of the file copy

Return

File — the file copy just created

`removeEditor(emailAddress)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`emailAddress`	`String`	the email address of the user to remove

Return

File — this File, for chaining

`removeEditor(user)`

Deprecated. This function is deprecated and should not be used in new scripts.

Parameters

Name	Type	Description
`user`	`User`	a representation of the user to remove

Return

File — this File, for chaining

`removeFromFolder(parent)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`parent`	`Folder`	the folder to remove the item from

`removeViewer(emailAddress)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`emailAddress`	`String`	the email address of the user to remove

Return

File — this File for chaining

`removeViewer(user)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`user`	`User`	a representation of the user to remove

Return

File — this File for chaining

`rename(newName)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`newName`	`String`	the new name of the item

`replace(contents)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`contents`	`String`	the string with which to replace the file contents

`setDescription(description)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`description`	`String`	the item's description

`setStarred(starred)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`starred`	`Boolean`	stars the item if true; unstars it if false

`setTrashed(trash)`

Deprecated. This function is deprecated and should not be used in new scripts.

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

Name	Type	Description
`trash`	`Boolean`	trashes the item if true; untrashes it if false

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Last updated February 26, 2015.

Class File

Methods

Deprecated methods

Detailed documentation

getAs(contentType)

Parameters

Return

getBlob()

Return

Deprecated methods

addEditor(emailAddress)

Parameters

Return

addEditor(user)

Parameters

Return

addEditors(emailAddresses)

Parameters

Return

addToFolder(parent)

Parameters

addViewer(emailAddress)

Parameters

Return

addViewer(user)

Parameters

Return

addViewers(emailAddresses)

Parameters

Return

append(contents)

Parameters

clear()

getContentAsString()

Return

getDateCreated()

Return

getDescription()

Return

getEditors()

Return

getFileType()

Return

See also

getId()

Return

getLastUpdated()

Return

getName()

Return

getOwner()

Return

getParents()

Return

getSize()

Return

getThumbnail()

Return

getType()

Return

getUrl()

Return

getViewers()

Return

isStarred()

Return

isTrashed()

Return

makeCopy()

Return

makeCopy(newName)

Parameters

Return

removeEditor(emailAddress)

Parameters

Return

removeEditor(user)

Parameters

Return

removeFromFolder(parent)

`getAs(contentType)`

`getBlob()`

`addEditor(emailAddress)`

`addEditor(user)`

`addEditors(emailAddresses)`

`addToFolder(parent)`

`addViewer(emailAddress)`

`addViewer(user)`

`addViewers(emailAddresses)`

`append(contents)`

`clear()`

`getContentAsString()`

`getDateCreated()`

`getDescription()`

`getEditors()`

`getFileType()`

`getId()`

`getLastUpdated()`

`getName()`

`getOwner()`

`getParents()`

`getSize()`

`getThumbnail()`

`getType()`

`getUrl()`

`getViewers()`

`isStarred()`

`isTrashed()`

`makeCopy()`

`makeCopy(newName)`

`removeEditor(emailAddress)`

`removeEditor(user)`

`removeFromFolder(parent)`

`removeViewer(emailAddress)`

`removeViewer(user)`

`rename(newName)`

`replace(contents)`

`setDescription(description)`

`setStarred(starred)`

`setTrashed(trash)`