使用 Google Drive API 插入檔案時，應用程式應在 title 屬性中指定副檔名。舉例來說，插入 JPEG 檔案的作業應在 metadata 中指定類似 "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"]],["上次更新時間：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)"]]
