物件中繼資料

管理

本頁面將說明與 Cloud Storage 物件一併儲存的常用中繼資料欄位。

簡介

儲存在 Cloud Storage 中的物件會與中繼資料建立關聯。 中繼資料會識別物件的屬性，並指定存取物件時應如何處理物件。中繼資料以「鍵:值組合」的形式存在。舉例來說，物件的儲存空間級別由中繼資料項目「storageClass:STANDARD」表示。其中 storageClass 就是中繼資料的「鍵」，而所有的物件都會有這樣一個相關聯的鍵。STANDARD 則指定這個特定物件具有的「值」，這個值會隨物件的不同而異。

中繼資料的易變性也不盡相同；有些中繼資料可以隨時編輯，有些中繼資料只能在建立物件時設定，而有些中繼資料只能查看。舉例來說，您隨時可以編輯 Cache-Control 中繼資料的值，但只能在建立或重寫物件時指派 storageClass 中繼資料，且無法直接編輯 generation 中繼資料的值，不過 generation 值會在物件替換時變更。

可編輯的中繼資料

使用者可變更的物件中繼資料有兩種：

  • 固定鍵中繼資料：雖已設定鍵、但可指定值的中繼資料。

  • 自訂中繼資料：藉由同時指定鍵及與此鍵關聯的值而新增的中繼資料。

編輯中繼資料時，一般應避免使用非 ASCII 字元，因為 XML API 使用的 HTTP 標頭不允許使用這類字元。

固定鍵中繼資料

您可以編輯物件的下列中繼資料，但必須具備足夠的權限。如要透過單一工作，大量更新數百萬或數十億個物件的固定鍵中繼資料，請使用 儲存空間批次作業。

存取控管中繼資料

Cloud Storage 使用身分與存取權管理 (IAM) 和存取控制清單 (ACL) 來控管物件的存取權。請點選這些連結，瞭解存取控管方法和相關中繼資料。

快取控制

Cache-Control 中繼資料可指定從 Cloud Storage 提供資料方法的兩種思考方向：是否可快取資料，以及是否可轉換資料。

快取資料

Cache-Control 中繼資料可讓您控管快取是否可快取物件，以及快取時間長度，以便在日後滿足要求。快取可能包括瀏覽器和網際網路快取，以及 Cloud Storage 內建快取。

如果適用物件沒有 Cache-Control 中繼資料項目，Cloud Storage 會使用以下預設值：

如果允許快取，即使上傳了新版物件，下載作業仍可能繼續接收舊版物件。這是因為這類早期版本在快取中仍會保持「最新」狀態，時間長度由 max-age 決定。此外，由於可在網際網路上的各種位置快取物件，因此沒有方法可強制快取過的物件在全球過期。也就是說，如果您撤銷物件的公開存取權，系統仍可從快取提供該物件，具體取決於上次存取時間和 Cache-Control 設定。舉例來說，如果物件是以 public, max-age=3600 的 Cache-Control 提供，則可在快取中保留一小時。如要避免提供公開可讀物件的快取版本，請在物件上設定 Cache-Control: no-store。

轉換資料

Cache-Control 中繼資料也可讓您提供儲存的物件，而不必對資料套用任何轉換，例如為不相容的用戶端移除 gzip 內容編碼。如要提供原狀的物件，請設定 Cache-Control:no-transform。

Content-Disposition

Content-Disposition 中繼資料指定轉換中資料的呈現資訊。設定 Content-Disposition 可讓您控制內容的呈現風格，例如決定是否應自動顯示附件，還是應該要求使用者執行某些動作來開啟該附件。如需 Content-Disposition 規格，請參閱 https://datatracker.ietf.org/doc/html/rfc6266。

Content-Encoding

Content-Encoding 中繼資料可用來表示物件已經過壓縮，同時仍保有物件的基礎 Content-Type。例如，以 gzip 壓縮的文字檔，可在 Content-Type 中指出它是文字檔，以及在 Content-Encoding 中指出它是使用 gzip 壓縮的。上傳檔案前，請務必確認檔案確實已使用指定的 Content-Encoding 壓縮，否則嘗試下載物件時可能會發生非預期的行為。詳情請參閱轉碼頁面。

對於可壓縮的內容如文字等，使用 Content-Encoding: gzip 可節省網路和儲存費用，並可改善內容提供效能。但是對於本身已經壓縮的內容，如封存和許多媒體格式等，如將其他壓縮層級套用到這類內容並在 Content-Encoding 中繼資料中標示，通常不利於物件大小和效能，因此應該避免。

Content-Language

Content-Language 中繼資料表示物件主要用於哪些語言。如需這項中繼資料的典型值，請參閱 ISO 639-1 語言代碼。

Cloud Storage 支援長度最多 100 個字元的 Content-Language 值。

Content-Type

最常設定的中繼資料是 Content-Type (也稱為媒體類型)，可讓瀏覽器正確轉譯物件。所有物件的 Content-Type 中繼資料都指定了值，但這個值不一定要與物件的基礎類型相符。舉例來說，如果上傳者未指定 Content-Type，且系統無法判斷，則會根據您上傳物件的方式，將其設為 application/octet-stream 或 application/x-www-form-urlencoded。如需有效內容類型清單，請參閱「IANA 媒體類型」頁面。

自訂時間

Custom-Time 中繼資料是使用者指定的日期和時間，以 RFC 3339 格式 YYYY-MM-DD'T'HH:MM:SS.SS'Z' 或 YYYY-MM-DD'T'HH:MM:SS'Z' (毫秒為零時) 表示。通常會設定這項中繼資料，以便在物件生命週期管理中使用 DaysSinceCustomTime 條件。

Custom-Time 設定至物件後即無法移除。此外，Custom-Time 的值不得減少。也就是說，您無法將 Custom-Time 設為早於現有 Custom-Time 的日期/時間。不過，您可以透過重寫物件，有效移除或重設 Custom-Time。

物件結構定義

物件脈絡資料是使用者定義的鍵/值組合。您可以將這些標記附加至物件，以便管理及探索資料。修改物件內容會更新物件的中繼資料版本編號和 ETag。詳情請參閱「物件背景資訊」。

物件訴訟保留

使用中繼資料標記設定物件保留機制，防止物件遭到刪除或取代。詳情請參閱「物件保留頁面」。

保留設定

物件的保留設定會定義日期和時間，在該日期和時間之前，物件無法刪除或替換。如要透過單一工作更新數百萬或數十億個物件的保留設定，請使用儲存空間批次作業。詳情請參閱「物件保留鎖定」。

自訂中繼資料

自訂中繼資料是指您同時定義鍵和值的中繼資料。如要建立自訂中繼資料，請同時指定鍵和值。建立自訂中繼資料 key:value 組合後，您可以刪除鍵或變更值。如要透過單一工作更新數百萬或數十億個物件的自訂中繼資料，請使用 儲存空間批次作業。

自訂中繼資料有大小限制。

「查看及編輯中繼資料」頁面包含設定自訂中繼資料的相關資訊。

x-goog-meta- 前置字串

XML API 會使用要求標頭設定及擷取物件中繼資料，而 JSON API 則允許在支援續傳的上傳作業的最終要求中，使用要求標頭設定自訂中繼資料。為清楚區分自訂中繼資料標頭與標準要求標頭，這兩個 API 都會為這類自訂中繼資料標頭加上 x-goog-meta- 前置字元。

不能編輯的中繼資料

有些中繼資料無法直接編輯，這種中繼資料會在建立或重寫物件時設定。建立或重寫物件時，您可以設定部分中繼資料，例如物件的儲存空間級別或客戶自行管理的加密金鑰。系統會自動新增其他中繼資料，且只能查看，例如物件的生成編號或建立時間。

世代和中繼資料版本編號

每個 Cloud Storage 物件的中繼資料都包含數值 generation 屬性和數值 metageneration 屬性，可專門用來識別物件：

屬性 說明
generation或version ID 識別物件版本，無論值區是否使用物件版本控管，每個物件都有這個屬性。在 Amazon S3 相容 API (例如多物件刪除 XML API) 的情境中，這個 ID 稱為 version ID。
  • 物件版本的 generation 值不重複。同名的新物件可以取代現有物件，但新物件的 generation 值不同。
  • 未來版本可能不會增加世代編號，但每個新版本都有專屬的世代編號。
  • 即使是同一個值區內的物件，不相關物件的產生編號也毫無關聯。
metageneration 識別中繼資料版本，並在每次更新特定 generation 的中繼資料時增加。
  • metageneration每個物件的新 generation 都會從 1 開始。
  • metageneration 屬性必須與 generation 屬性搭配使用，否則沒有任何意義。比較兩個物件版本的中繼資料世代沒有任何意義。

在下列情況中，會使用 generation 和 metageneration 屬性：

檢查碼機制

核對和是根據相關聯物件的資料計算而得的中繼資料。核對和可用於驗證物件資料是否損毀。Cloud Storage 物件有數個總和檢查碼中繼資料欄位。

CRC32C

所有 Cloud Storage 物件都有 CRC32C 雜湊。用於計算 CRC32C 的程式庫包括：

Base64 編碼的 CRC32C 採用大端序位元組順序。

MD5

如果 Cloud Storage 物件符合下列條件，就會有 MD5 雜湊：

如果要求中含有 Content-MD5 標頭，Cloud Storage 會比較提供的 MD5 雜湊與上傳物件的計算雜湊，驗證物件資料的完整性。如果雜湊值不相符，系統會拒絕要求。

ETag

所有 Cloud Storage 物件都有 ETag。不過，如果透過 XML API 要求同一個物件，其 ETag 值可能會與透過 JSON API 要求時不同。在大多數情況下，使用者不應對 ETag 中使用的值做出任何假設，除非基礎資料或中繼資料發生變更，則根據規格，該值也會隨之變更。

如果符合下列所有條件，物件的 ETag 標頭會傳回物件的 MD5 值：

時間戳記

Cloud Storage 物件的中繼資料可能包含下列時間戳記。欄位名稱會因您用來處理物件的工具或 SDK 語言而異。如需 SDK，請參閱相關用戶端程式庫說明文件。

指令列

欄位名稱 說明
creation_time 物件的建立時間。這個時間戳記不會變更。
update_time 物件中繼資料的最近修改時間。這個值最初會設為物件的建立時間，之後只要物件的任何中繼資料變更，系統就會更新這個值。這包括要求者所做的變更 (例如修改自訂中繼資料)，以及 Cloud Storage 代表要求者所做的變更 (例如根據物件生命週期設定變更儲存空間級別)。
noncurrent_time 物件的刪除時間。只有在物件版本不再是使用中版本，但仍以非現行版本的形式保留在 bucket 中時，才會傳回這個值。
soft_delete_time 物件虛刪除的時間。僅適用於設有虛刪除政策的 bucket 中的物件。
hard_delete_time 虛刪除物件永久刪除且無法再還原的時間。這個值是虛刪除時間和值區保留政策中設定的保留時長總和。僅適用於設有虛刪除政策的 bucket 中的物件。請注意，永久刪除時間的值一經設定即永久有效，不會因保留時間長度變更而改變。
retention_settings.retainUntilTime 物件最早可刪除或替換的時間。這個值與物件所在值區設定的任何資料保留政策無關。最大值為 3,155,760,000 秒 (100 年)，從目前日期和時間算起。
retention_expiration 可刪除物件的最早時間。這個值取決於為物件設定的保留設定，以及為包含物件的值區設定的保留政策。
storage_class_update_time 上次變更物件儲存空間級別的時間。物件最初建立時，這個值會設為物件的建立時間。
finalize_time 物件的完成時間。
contexts.KEY.createTime 首次將這個物件內容索引鍵新增至物件的時間。
contexts.KEY.updateTime 上次更新這個物件脈絡資料鍵的時間。
custom_time 使用者指定的物件時間戳記。為物件設定自訂時間後，就無法移除或設為較早的日期時間。如要進一步瞭解如何使用自訂時間，請參閱「自訂時間中繼資料」。

API

JSON API

欄位名稱 說明
timeCreated 物件的建立時間。這個時間戳記不會變更。
updated 物件中繼資料的最近修改時間。這個值一開始會設為物件的建立時間，之後只要物件的中繼資料有任何變更，就會更新。這包括要求者所做的變更 (例如修改自訂中繼資料)，以及 Cloud Storage 代表要求者所做的變更 (例如根據物件生命週期設定變更儲存空間級別)。
timeDeleted 物件的刪除時間。只有在這個物件版本不再是使用中版本，但仍以非現行版本的形式保留在 bucket 中時，才會傳回。
softDeleteTime 物件虛刪除的時間。僅適用於設有虛刪除政策的 bucket 中的物件。
hardDeleteTime 虛刪除物件永久刪除且無法再還原的時間。這個值是虛刪除時間和值區保留政策中設定的保留時長總和。僅適用於設有虛刪除政策的 bucket 中的物件。請注意，永久刪除時間的值一經設定即永久有效，不會因保留時間長度變更而改變。
retention.retainUntilTime 物件最早可刪除或替換的時間。這個值與物件所在值區設定的任何資料保留政策無關。最大值為 3,155,760,000 秒 (100 年)，從目前日期和時間算起。
retentionExpirationTime 可刪除物件的最早時間。這個值取決於為物件設定的保留設定，以及為包含物件的值區設定的保留政策。
timeStorageClassUpdated 上次變更物件儲存空間級別的時間。物件最初建立時，這個值會設為物件的建立時間。
timeFinalized 物件的完成時間。
contexts.custom.KEY.createTime 首次將這個物件內容索引鍵新增至物件的時間。
contexts.custom.KEY.updateTime 上次更新這個物件脈絡資料鍵的時間。
customTime 使用者指定的物件時間戳記。設定物件的自訂時間後，就無法移除，也無法設為較早的日期時間。如要進一步瞭解如何使用自訂時間，請參閱「自訂時間中繼資料」。

XML API

欄位名稱 說明
Created 物件的建立時間。這個時間戳記不會變更。
LastModified 物件中繼資料的最近修改時間。這個值最初會設為物件的建立時間，之後只要物件的任何中繼資料變更，系統就會更新這個值。包括要求者所做的變更 (例如修改自訂中繼資料)，以及 Cloud Storage 代表要求者所做的變更 (例如根據物件生命週期設定變更儲存空間類別)。
DeletedTime 物件的刪除時間。只有在物件版本不再是使用中版本，但仍以非現行版本的形式保留在 bucket 中時，才會傳回這個值。
x-goog-object-lock-retain-until-date 最早可刪除或取代物件的時間。這個值與物件所在值區設定的任何資料保留政策無關。最大值為目前日期和時間起算的 3,155,760,000 秒 (100 年)。
Finalized 物件的最終時間。
x-goog-custom-time 使用者指定的物件時間戳記。為物件設定自訂時間後，就無法移除或設為較早的日期時間。如要進一步瞭解如何使用自訂時間，請參閱「自訂時間中繼資料」。

RPC API

欄位名稱 說明
create_time 物件的建立時間。這個時間戳記不會變更。
update_time 物件中繼資料的最近修改時間。這個值最初會設為物件的建立時間，之後只要物件的任何中繼資料變更，系統就會更新這個值。這包括要求者所做的變更 (例如修改自訂中繼資料)，以及 Cloud Storage 代表要求者所做的變更 (例如根據物件生命週期設定變更儲存空間級別)。
delete_time 物件的刪除時間。只有在這個物件版本不再是使用中版本，但仍以非現行版本的形式保留在 bucket 中時，才會傳回。
soft_delete_time 物件虛刪除的時間。僅適用於設有虛刪除政策的 bucket 中的物件。
hard_delete_time 虛刪除物件永久刪除且無法再還原的時間。這個值是虛刪除時間和值區保留政策中設定的保留時長總和。僅適用於設有虛刪除政策的 bucket 中的物件。請注意，永久刪除時間的值一經設定即永久有效，不會因保留時間長度變更而改變。
retention.retain_until_time 物件最早可刪除或替換的時間。這個值與物件所在值區設定的任何資料保留政策無關。最大值為 3,155,760,000 秒 (100 年)，從目前日期和時間算起。
retention_expire_time 可刪除物件的最早時間。這個值取決於為物件設定的保留設定，以及為包含物件的值區設定的保留政策。
update_storage_class_time 上次變更物件儲存空間級別的時間。物件最初建立時，這個值會設為物件的建立時間。
finalize_time 物件的完成時間。
contexts.custom.KEY.createTime 首次將這個物件內容索引鍵新增至物件的時間。
contexts.custom.KEY.updateTime 上次更新這個物件脈絡資料鍵的時間。
custom_time 物件的使用者指定時間戳記。為物件設定自訂時間後，就無法移除或設為較早的日期時間。如要進一步瞭解如何使用自訂時間，請參閱「自訂時間中繼資料」。

後續步驟