使用 Google Drive API 插入文件时，应用应在 title 属性中指定文件扩展名。例如，插入 JPEG 文件的操作应在元数据中指定类似 "name": "cat.jpg" 的内容。
后续的 GET 响应可以包含只读 fileExtension 属性，该属性填充了 name 属性中最初指定的扩展名。当 Google 云端硬盘用户请求下载文件时，或者当文件通过同步客户端下载时，云端硬盘会根据标题构建完整的文件名（带扩展名）。如果扩展名缺失，Google 云端硬盘会尝试根据文件的 MIME 类型确定扩展名。
可编入索引的文本以 HTML 的形式编入索引。如果您保存可编入索引的文本字符串 <section attribute="value1">Here's some text</section>，则“Here's some text”会编入索引，但“value1”不会。因此，将 XML 保存为可编入索引的文本不如保存 HTML 有用。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-04。"],[],[],null,["# Manage file metadata\n\nThis document covers important considerations for naming files and working with\nmetadata like indexable text and thumbnails. To insert and retrieve files, see\nthe [`files`](/workspace/drive/api/reference/rest/v3/files) resource.\n\nSpecify file names and extensions\n---------------------------------\n\nApps should specify a file extension in the title property when inserting files\nwith the Google Drive API. For example, an operation to insert a JPEG file should\nspecify something like `\"name\": \"cat.jpg\"` in the metadata.\n\nSubsequent `GET` responses can include the read-only `fileExtension` property\npopulated with the extension originally specified in the `name` property. When a\nGoogle Drive user requests to download a file, or when the file is downloaded\nthrough the sync client, Drive builds a full filename (with\nextension) based on the title. In cases where the extension is missing,\nDrive attempts to determine the extension based on the file's\nMIME type.\n\nSave indexable text\n-------------------\n\n| **Note:** Beginning October 31, 2022, indexable text can be shown in result snippets and it will affect search results in more places, including Cloud Search and the search overlay in Drive and Gmail.\n\nDrive automatically indexes documents for search when it\nrecognizes the file type, including text documents, PDFs, images with text, and\nother common types. If your app saves other types of files (such as drawings,\nvideo, and shortcuts), you can improve the discoverability by supplying\nindexable text in the `contentHints.indexableText` field of the file.\n\nIndexable text is indexed as HTML. If you save the indexable text string\n`\u003csection attribute=\"value1\"\u003eHere's some text\u003c/section\u003e`, then \"Here's some\ntext\" is indexed, but \"value1\" isn't. Because of this, saving XML as indexable\ntext isn't as useful as saving HTML.\n\nWhen specifying `indexableText`, also keep in mind:\n\n- The size limit for `contentHints.indexableText` is 128 KB.\n- Capture the key terms and concepts that you expect a user to search.\n- Don't try to sort text in order of importance because the indexer does that efficiently for you.\n- Your application should update the indexable text with each save.\n- Make sure the text is related to the file's content or metadata.\n\nThis last point might seem obvious, but it's important. It's not a good idea to\nadd commonly searched terms to force a file to appear in search results. This\ncan frustrate users, and might even motivate them to delete the file.\n\nUpload thumbnails\n-----------------\n\nDrive automatically generates thumbnails for many common file\ntypes, such as Google Docs, Sheets, and Slides.\nThumbnails help the user to better identify Drive files.\n\nFor file types that Drive can't generate a standard thumbnail\nfor, you can provide a thumbnail image generated by your application. During\nfile creation or update, upload a thumbnail by setting the\n`contentHints.thumbnail` field on the [`files`](/workspace/drive/api/reference/rest/v3/files) resource.\n\nSpecifically:\n\n- Set the `contentHints.thumbnail.image` field to the URL and filename safe base64-encoded image (see [RFC 4648 section\n 5](https://datatracker.ietf.org/doc/html/rfc4648#section-5)).\n- Set the `contentHints.thumbnail.mimeType` field to the appropriate MIME type for the thumbnail.\n\nIf Drive can generate a thumbnail from the file, it uses the\nautomatically generated one and ignores any you might have uploaded. If it can't\ngenerate a thumbnail, it uses the one you provide.\n\nThumbnails should adhere to these rules:\n\n- Can be uploaded in PNG, GIF, or JPG formats.\n- The recommended width is 1600 pixels.\n- The minimum width is 220 pixels.\n- The maximum file size is 2 MB.\n- They should be updated by your application with each save.\n\n| **Important:** Thumbnails are invalidated each time the file content changes. When providing thumbnails, it's important to upload new thumbnails each time the content is modified. Metadata changes don't invalidate thumbnails.\n\nFor more information, see the [`files`](/workspace/drive/api/reference/rest/v3/files) resource.\n\nRetrieve thumbnails\n-------------------\n\nYou can retrieve metadata, including thumbnails, for Drive files.\nThumbnail information is housed in the `thumbnailLink` field of the\n[`files`](/workspace/drive/api/reference/rest/v3/files) resource.\n\n### Return a specific thumbnail\n\nThe following code sample shows a\n[`files.get`](/workspace/drive/api/reference/rest/v3/files/get) method request with\nmultiple fields as a query parameter to return the `thumbnailLink` metadata for\na specific file. For more information, see [Return specific fields for a\nfile](/workspace/drive/api/guides/fields-parameter). \n\n GET https://www.googleapis.com/drive/v3/files/\u003cvar translate=\"no\"\u003eFILE_ID\u003c/var\u003e?fields=id,name,mimeType,thumbnailLink\n\nReplace \u003cvar translate=\"no\"\u003eFILE_ID\u003c/var\u003e with the `fileId` of the file that you want to\nfind.\n\nIf available, the request returns a short-lived URL to the file's thumbnail.\nTypically, the link lasts for several hours. The field is only populated when\nthe requesting app can access the file's content. If the file isn't shared\npublicly, the URL returned in `thumbnailLink` must be fetched using a\n[credentialed request](/workspace/drive/api/guides/api-specific-auth).\n\n### Return a list of thumbnails\n\nThe following code sample shows a\n[`files.list`](/workspace/drive/api/reference/rest/v3/files/list) method request with\nmultiple fields as a query parameter to return the `thumbnailLink` metadata for\na list of files. For more information, see [Search for files and\nfolders](/workspace/drive/api/guides/search-files). \n\n GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)\n\nTo restrict the search results to a specific file type, apply a query string to\nset the MIME type. For example, the following code sample shows how to limit the\nlist to Google Sheets files. For more information on MIME types, see [Google Workspace and Google Drive supported MIME\ntypes](/workspace/drive/api/guides/mime-types). \n\n GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)"]]
