This document covers important considerations for naming files and working with
metadata like indexable text and thumbnails. To insert and retrieve files, see
the
files
resource.
Specify file names and extensions
Apps should specify a file extension in the title property when inserting files
with the Google Drive API. For example, an operation to insert a JPEG file should
specify something like
"name": "cat.jpg"
in the metadata.
Subsequent
GET
responses can include the read-only
fileExtension
property
populated with the extension originally specified in the
name
property. When a
Google Drive user requests to download a file, or when the file is downloaded
through the sync client, Drive builds a full filename (with
extension) based on the title. In cases where the extension is missing,
Drive attempts to determine the extension based on the file's
MIME type.
Save indexable text
Drive automatically indexes documents for search when it
recognizes the file type, including text documents, PDFs, images with text, and
other common types. If your app saves other types of files (such as drawings,
video, and shortcuts), you can improve the discoverability by supplying
indexable text in the
contentHints.indexableText
field of the file.
Indexable text is indexed as HTML. If you save the indexable text string
<section attribute="value1">Here's some text</section>
, then "Here's some
text" is indexed, but "value1" isn't. Because of this, saving XML as indexable
text isn't as useful as saving HTML.
When specifying
indexableText
, also keep in mind:
- The size limit for
contentHints.indexableText
is 128 KB.
- Capture the key terms and concepts that you expect a user to search.
- Don't try to sort text in order of importance because the indexer does that
efficiently for you.
- Your application should update the indexable text with each save.
- Make sure the text is related to the file's content or metadata.
This last point might seem obvious, but it's important. It's not a good idea to
add commonly searched terms to force a file to appear in search results. This
can frustrate users, and might even motivate them to delete the file.
Upload thumbnails
Drive automatically generates thumbnails for many common file
types, such as Google Docs, Sheets, and Slides.
Thumbnails help the user to better identify Drive files.
For file types that Drive can't generate a standard thumbnail
for, you can provide a thumbnail image generated by your application. During
file creation or update, upload a thumbnail by setting the
contentHints.thumbnail
field on the
files
resource.
Specifically:
- Set the
contentHints.thumbnail.image
field to the URL and filename safe
base64-encoded image (see
RFC 4648 section
5
).
- Set the
contentHints.thumbnail.mimeType
field to the appropriate MIME type
for the thumbnail.
If Drive can generate a thumbnail from the file, it uses the
automatically generated one and ignores any you might have uploaded. If it can't
generate a thumbnail, it uses the one you provide.
Thumbnails should adhere to these rules:
- Can be uploaded in PNG, GIF, or JPG formats.
- The recommended width is 1600 pixels.
- The minimum width is 220 pixels.
- The maximum file size is 2 MB.
- They should be updated by your application with each save.
For more information, see the
files
resource.
Retrieve thumbnails
You can retrieve metadata, including thumbnails, for Drive files.
Thumbnail information is housed in the
thumbnailLink
field of the
files
resource.
Return a specific thumbnail
The following code sample shows a
files.get
method request with
multiple fields as a query parameter to return the
thumbnailLink
metadata for
a specific file. For more information, see
Return specific fields for a
file
.
GET https://www.googleapis.com/drive/v3/files/
FILE_ID
?fields=id,name,mimeType,thumbnailLink
Replace
FILE_ID
with the
fileId
of the file that you want to
find.
If available, the request returns a short-lived URL to the file's thumbnail.
Typically, the link lasts for several hours. The field is only populated when
the requesting app can access the file's content. If the file isn't shared
publicly, the URL returned in
thumbnailLink
must be fetched using a
credentialed request
.
Return a list of thumbnails
The following code sample shows a
files.list
method request with
multiple fields as a query parameter to return the
thumbnailLink
metadata for
a list of files. For more information, see
Search for files and
folders
.
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
To restrict the search results to a specific file type, apply a query string to
set the MIME type. For example, the following code sample shows how to limit the
list to Google Sheets files. For more information on MIME types, see
Google Workspace and Google Drive supported MIME
types
.
GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)