[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-18。"],[],[],null,["# Metadata preservation\n\nThis document describes metadata that is preserved when you use\nStorage Transfer Service to transfer data between various sources and destinations.\n\nOverview\n--------\n\nStorage Transfer Service preserves the following metadata:\n\n- User-created [custom metadata](/storage/docs/metadata#custom-metadata) for\n transfers that originate from Cloud Storage, Amazon S3, or\n Microsoft Azure Blob Storage is preserved.\n\n- Transfers between Cloud Storage buckets can optionally preserve\n object ACLs, customer-managed encryption keys, storage class, object\n creation time (as the value of a `customTime` field), and temporary holds.\n\n- For transfers from any source to a Cloud Storage bucket, the object's\n storage class in the destination bucket can be set to any supported class as\n part of the transfer.\n\n- File size and last modified time (`mtime`) are preserved for\n transfers that originate from POSIX file systems. `mtime` is not\n preserved for folders.\n\n- Optionally, symlinks, numeric UID, numeric GID, and numeric MODE can be\n preserved for transfers to and from POSIX file systems.\n\n- For transfers between file systems only, if UID, GID, or MODE are preserved,\n that metadata is also preserved for folders. Cloud Storage recreates\n folders on the destination file system and restores UID, GID, and/or MODE.\n This includes empty folders. `mtime` is not preserved.\n\n Folder-level metadata is not preserved if the transfer is by\n [manifest](/storage-transfer/docs/manifest).\n\nMetadata fields that are not explicitly mentioned in this document are not\npreserved.\n\nMetadata preservation behavior\n------------------------------\n\nThe following sections list metadata examples from different source\nstorage systems and how Storage Transfer Service preserves\nmetadata from each. For an exhaustive list of metadata, refer to the source\nstorage system's documentation.\n\n### Amazon S3 or S3-compatible storage to Cloud Storage\n\n### Microsoft Azure Storage to Cloud Storage\n\n### Transfers between Cloud Storage buckets\n\nFor a list of metadata in Cloud Storage, see\n[Objects](/storage/docs/json_api/v1/objects).\n\n### URL list transfer to Cloud Storage\n\nFor more information about URL lists, see [Creating a URL\nlist](/storage-transfer/docs/create-url-list).\n\n### POSIX file system transfers\n\nWhen transferring files from POSIX file systems, Storage Transfer Service can optionally\npreserve certain attributes as custom metadata. If these files are later written\nback to a file system, Storage Transfer Service can convert the preserved metadata\nback to POSIX attributes.\n\n### Preserving optional POSIX metadata\n\nTo preserve one or more of numeric UID, numeric GID, numeric MODE,\nand symbolic links, specify a\n[`metadataOptions`](/storage-transfer/docs/reference/rest/v1/TransferOptions#MetadataOptions) object in the body of your transfer job.\n\nThese options apply to both POSIX-to-Cloud Storage transfers and\nCloud Storage-to-POSIX transfers. For the latter, the metadata must have\nbeen preserved when files were initially transferred to Cloud Storage. \n\n {\n \"description\": \"metadata-example\",\n \"projectId\": \"example-project-id\"\n \"transferSpec\": {\n ...\n \"transferOptions\": {\n \"metadataOptions\": {\n \"gid\": \"GID_NUMBER\", # Default is \"GID_SKIP\"\n \"uid\": \"UID_NUMBER\", # Default is \"UID_SKIP\"\n \"mode\": \"MODE_PRESERVE\", # Default is \"MODE_SKIP\"\n \"symlink\": \"SYMLINK_PRESERVE\" # Default is \"SYMLINK_SKIP\"\n }\n }\n }\n }\n\n#### POSIX to Cloud Storage\n\nPreserved metadata is stored in Cloud Storage as custom metadata\nkey:value pairs.\n\n- Numeric GID is stored as `goog-reserved-posix-gid`.\n- Numeric UID is stored as `goog-reserved-posix-uid`.\n- Numeric MODE is stored as `goog-reserved-posix-mode`.\n\nFor symbolic links, Storage Transfer Service preserves the target link as an object in\nCloud Storage with the following qualities:\n\n- Object key is composed of the destination prefix plus the path to the symlink, relative to the `root_directory`.\n- Object metadata:\n - Any symlink metadata is preserved as Cloud Storage object metadata.\n - A custom metadata entry is made: `goog-reserved-file-is-symlink:true`.\n- The object content is the target of the symlink. For example, for a symlink `sym-\u003e dir1/target`, the object's content is \"dir1/target\".\n\nStorage Transfer Service does not validate the link or copy the target file.\n\n#### Cloud Storage to POSIX\n\nIf metadata is preserved when files are transferred to Cloud Storage, that\nmetadata can be written back to the files when they are\n[transferred back to a POSIX file system](/storage-transfer/docs/download-from-cloud-storage).\n\nIf a metadata option is set to preserve, Storage Transfer Service takes the following\nactions:\n\n- Symbolic links: Storage Transfer Service creates a symlink file pointing to the target link. If the target file does not exist, the symlink will be broken.\n- GID, UID, and MODE: the values stored in Cloud Storage metadata are written back to the file.\n\n#### POSIX to POSIX\n\nTransfers between file systems can optionally preserve GID, UID, and MODE for\nfiles and folders.\n\nLast modified time is saved for files, but not for folders. `mtime`\nis set to the create time of the folder on the destination file system.\n\nStorage Transfer Service saves folder metadata by creating 0-byte folder objects in\nthe intermediate bucket, then copying that metadata back to the folder on the\ndestination file system. For this reason, the number of objects created in the\nintermediate bucket may be greater than the number of files being\ntransferred."]]
