A file in Google Drive. Files can be accessed or created from DriveApp
.
// Trash every untitled spreadsheet that hasn't been updated in a week. var files = DriveApp.getFilesByName('Untitled spreadsheet'); while (files.hasNext()) { var file = files.next(); if (new Date() - file.getLastUpdated() > 7 * 24 * 60 * 60 * 1000) { file.setTrashed(true); } }
Methods
Method | Return type | Brief description |
---|---|---|
addCommenter(emailAddress) | File | Add the given user to the list of commenters for the File . |
addCommenter(user) | File | Add the given user to the list of commenters for the File . |
addCommenters(emailAddresses) | File | Add the given array of users to the list of commenters for the File . |
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 . |
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 . |
getAccess(email) | Permission | Gets the permission granted to the given user. |
getAccess(user) | Permission | Gets the permission granted to the given user. |
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. |
getDateCreated() | Date | Gets the date the File was created. |
getDescription() | String | Gets the description for the File . |
getDownloadUrl() | String | Gets the URL that can be used to download the file. |
getEditors() | User[] | Gets the list of editors for this File . |
getId() | String | Gets the ID of the File . |
getLastUpdated() | Date | Gets the date the File was last updated. |
getMimeType() | String | Gets the MIME type of the file. |
getName() | String | Gets the name of the File . |
getOwner() | User | Gets the owner of the File . |
getParents() | FolderIterator | Gets a collection of folders that are immediate parents of the File . |
getSharingAccess() | Access | Gets which class of users can access the File , besides any individual
users who have been explicitly given access. |
getSharingPermission() | Permission | Gets the permission granted to those users who can access the File ,
besides any individual users who have been explicitly given access. |
getSize() | Integer | Gets the number of bytes used to store the File in Drive. |
getThumbnail() | Blob | Gets a thumbnail image for the file, or null if no thumbnail exists. |
getUrl() | String | Gets the URL that can be used to open the File in a Google App like
Drive or Docs. |
getViewers() | User[] | Gets the list of viewers and commenters for this File . |
isShareableByEditors() | Boolean | Determines whether users with edit permissions to the File are allowed to
share with other users or change the permissions. |
isStarred() | Boolean | Determines whether the File has been starred in the user's Drive. |
isTrashed() | Boolean | Determines whether the File is in the trash of the user's Drive. |
makeCopy() | File | Creates a copy of the file. |
makeCopy(destination) | File | Creates a copy of the file in the destination directory. |
makeCopy(name) | File | Creates a copy of the file and names it with the name provided. |
makeCopy(name, destination) | File | Creates a copy of the file in the destination directory and names it with the name provided. |
removeCommenter(emailAddress) | File | Removes the given user from the list of commenters for the File . |
removeCommenter(user) | File | Removes the given user from the list of commenters for the File . |
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 . |
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 . |
revokePermissions(user) | File | Revokes the access to the File granted to the given user. |
revokePermissions(user) | File | Revokes the access to the File granted to the given user. |
setContent(content) | File | Overwrites the content of the file with a given replacement. |
setDescription(description) | File | Sets the description for the File . |
setName(name) | File | Sets the name of the File . |
setOwner(emailAddress) | File | Changes the owner of the File . |
setOwner(user) | File | Changes the owner of the File . |
setShareableByEditors(shareable) | File | Sets whether users with edit permissions to the File are allowed to share
with other users or change the permissions. |
setSharing(accessType, permissionType) | File | Sets which class of users can access the File and what permissions
those users are granted, besides any individual users who have been explicitly given access. |
setStarred(starred) | File | Sets whether the File is starred in the user's Drive. |
setTrashed(trashed) | File | Sets whether the File is in the trash of the user's Drive. |
Detailed documentation
addCommenter(emailAddress)
Add the given user to the list of commenters 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
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
addCommenter(user)
Add the given user to the list of commenters 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
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
addCommenters(emailAddresses)
Add the given array of users to the list of commenters 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
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to add. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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
Name | Type | Description |
---|---|---|
user | User | A representation of the user to add. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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
Name | Type | Description |
---|---|---|
emailAddresses | String[] | An array of email addresses of the users to add. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to add. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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
Name | Type | Description |
---|---|---|
user | User | A representation of the user to add. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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
Name | Type | Description |
---|---|---|
emailAddresses | String[] | An array of email addresses of the users to add. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
getAccess(email)
Gets the permission granted to the given user.
Parameters
Name | Type | Description |
---|---|---|
email | String | the email address of the user whose permissions should be checked |
Return
Permission
— the permissions granted to the user
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getAccess(user)
Gets the permission granted to the given user.
Parameters
Name | Type | Description |
---|---|---|
user | User | a representation of the user whose permissions should be checked |
Return
Permission
— the permissions granted to the user
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
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, "ShoppingList.12.25.2014" becomes "ShoppingList.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()
getDateCreated()
getDescription()
getDownloadUrl()
Gets the URL that can be used to download the file. Only users with permission to open the file in Google Drive can access the URL.
Return
String
— the URL that can be used to download the file
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
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 returns an empty array.
Return
User[]
— An array of users with edit permission.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getId()
getLastUpdated()
getMimeType()
Gets the MIME type of the file.
Return
String
— the MIME type of the file
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getName()
getOwner()
getParents()
Gets a collection of folders that are immediate parents of the File
.
Return
FolderIterator
— a collection of folders that are immediate parents of the File
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getSharingAccess()
Gets which class of users can access the File
, besides any individual
users who have been explicitly given access.
Return
Access
— which class of users can access the File
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getSharingPermission()
Gets the permission granted to those users who can access the File
,
besides any individual users who have been explicitly given access.
Return
Permission
— the permissions granted to users who can access the File
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getSize()
Gets the number of bytes used to store the File
in Drive. Note that G
Suite application files do not count toward Drive storage limits and thus return 0
bytes.
Return
Integer
— the number of bytes used to store the File
in Drive
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getThumbnail()
Gets a thumbnail image for the file, or null
if no thumbnail exists.
Return
Blob
— the thumbnail image for the file
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
getUrl()
Gets the URL that can be used to open the File
in a Google App like
Drive or Docs.
Return
String
— the URL that can be used to view this File
in a Google App like
Drive or Docs
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
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
returns an empty array.
Return
User[]
— An array of users with view or comment permission.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
isStarred()
Determines whether the File
has been starred in the user's Drive.
Return
Boolean
— true
if the File
is starred in the user's Drive; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
isTrashed()
Determines whether the File
is in the trash of the user's Drive.
Return
Boolean
— true
if the File
is in the trash of the user's Drive;
false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive.readonly
-
https://www.googleapis.com/auth/drive
makeCopy()
makeCopy(destination)
Creates a copy of the file in the destination directory.
Parameters
Name | Type | Description |
---|---|---|
destination | Folder | the directory to copy the file into. |
Return
File
— the new copy
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
makeCopy(name)
Creates a copy of the file and names it with the name provided.
Parameters
Name | Type | Description |
---|---|---|
name | String | the filename that should be applied to the new copy |
Return
File
— the new copy
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
makeCopy(name, destination)
Creates a copy of the file in the destination directory and names it with the name provided.
Parameters
Name | Type | Description |
---|---|---|
name | String | the filename that should be applied to the new copy |
destination | Folder | the directory to copy the file into. |
Return
File
— the new copy
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
removeCommenter(emailAddress)
Removes the given user from the list of commenters for the File
. This method
does not block users from access 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
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
removeCommenter(user)
Removes the given user from the list of commenters for the File
. This method
does not block users from access 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
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
removeEditor(emailAddress)
Removes the given user from the list of editors for the File
. This method doesn't
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, or if the File
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to remove. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
removeEditor(user)
Removes the given user from the list of editors for the File
. This method doesn't
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, or if the File
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to remove. |
Return
File
— This File
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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
doesn't 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, or if the File
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of editors.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to remove. |
Return
File
— This File
for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
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 doesn't 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, or
if the File
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of editors.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to remove. |
Return
File
— This File
for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
revokePermissions(user)
Revokes the access to the File
granted to the given user. 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 |
---|---|---|
user | String | the email address of the user whose access should be revoked |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
revokePermissions(user)
Revokes the access to the File
granted to the given user. 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 |
---|---|---|
user | User | a representation of the user whose access should be revoked |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
setContent(content)
Overwrites the content of the file with a given replacement. Throws an exception if content
is larger than 10MB.
Parameters
Name | Type | Description |
---|---|---|
content | String | the new content for the file |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
setDescription(description)
setName(name)
setOwner(emailAddress)
Changes the owner of the File
. This method also gives the previous owner
explicit edit access to the File
.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | the email address of the user who should become the new owner |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
setOwner(user)
Changes the owner of the File
. This method also gives the previous owner
explicit edit access to the File
.
Parameters
Name | Type | Description |
---|---|---|
user | User | a representation of the user who should become the new owner |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
setSharing(accessType, permissionType)
Sets which class of users can access the File
and what permissions
those users are granted, besides any individual users who have been explicitly given access.
// Creates a folder that anyone on the Internet can read from and write to. (Domain // administrators can prohibit this setting for users of a G Suite domain.) var folder = DriveApp.createFolder('Shared Folder'); folder.setSharing(DriveApp.Access.ANYONE, DriveApp.Permission.EDIT);
Parameters
Name | Type | Description |
---|---|---|
accessType | Access | which class of users should be able to access the File |
permissionType | Permission | the permissions that should be granted to users who can access the File |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
setStarred(starred)
Sets whether the File
is starred in the user's Drive. The default for
new File
s is false
.
Parameters
Name | Type | Description |
---|---|---|
starred | Boolean | true if the File should be starred in the user's
Drive; false if not |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive
setTrashed(trashed)
Sets whether the File
is in the trash of the user's Drive. Only the
owner may trash the File
. The default for new File
s is false
.
Parameters
Name | Type | Description |
---|---|---|
trashed | Boolean | true if the File should be moved to the trash of
the user's Drive; false if not |
Return
File
— this File
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/drive