Much of the information you'll need to get started inserting and retrieving files is detailed in the Files reference. Here are a few more important considerations for naming files and working with metadata like thumbnails and indexable text.
Specifying file names and extensions
Apps should specify a file extension in the title property when inserting files with the API. For example, an operation to insert a JPEG file should specify something like
"name": "cat.jpg" in the metadata.
GET requests 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, Google Drive attempts to determine the extension based on the file's MIME type.
Saving indexable text
Drive automatically indexes documents for search when it recognizes the file type. This includes text documents, PDFs, images with text, and other common types. If your app saves other types of files (drawings, video, shortcuts), you can improve the discoverability by supplying indexable text.
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" is not. Because of this, saving XML as indexable text isn't as useful as saving HTML.
Also keep in mind:
- The size limit for
- Don't try to sort text in order of importance; the indexer does that very efficiently for you.
- Indexable text should be updated by your application with each save.
- Make sure the text is related to the content of the file.
This last point may seem obvious, but it is quite important. It's not a good idea to add commonly searched terms to try and force a file to show up in search results. This can frustrate users, and might even motivate them to delete the file.
Drive automatically generates thumbnails for many common file types. For
shortcuts and other file types that Drive can't render, you can provide a
thumbnail image generated by your application. Upload a thumbnail by setting
contentHints.thumbnail property on the File resource
during an insert or update call as follows:
contentHints.thumbnail.imageto the URL-safe Base64-encoded image (see RFC 4648 section 5)
contentHints.thumbnail.mimeTypeto the appropriate type for the image format
If Drive can generate a thumbnail from the file, then it will use the generated one and ignore any you may have uploaded. If it can't generate a thumbnail, it will always use yours if you provided one. Things to keep in mind:
- Thumbnails may be uploaded in PNG, GIF, or JPG formats.
- The recommended width is 1600px.
- The maximum file size for a thumbnail is 2mb.
- The minimum width for thumbnails is 220px.
- Thumbnails should be updated by your application with each save.
For more information, see the Files reference.