オブジェクトのメタデータを取得する - Object Storage Service

HeadObject 操作は、オブジェクトのメタデータを取得します。この操作はオブジェクトのコンテンツを返しません。

バージョン管理

リクエストで `versionId` を指定せずに HeadObject 操作を呼び出すと、オブジェクトの現在のバージョンのメタデータが返されます。現在のバージョンが削除マーカーの場合、OSS は 404 NoSuchKey を返します。
リクエストで `versionId` を指定して HeadObject 操作を呼び出すと、指定されたバージョンのメタデータが返されます。削除マーカーの `versionId` は指定できません。指定した場合、OSS は 405 MethodNotAllowed を返します。

権限

デフォルトでは、Alibaba Cloud アカウントは完全な権限を持っています。Alibaba Cloud アカウント下の RAM ユーザーまたは RAM ロールは、デフォルトでは何の権限も持っていません。Alibaba Cloud アカウントまたはアカウント管理者は、RAM ポリシーまたはバケットポリシーを通じて操作権限を付与する必要があります。

API	アクション	定義
HeadObject	`oss:GetObject`	オブジェクトのメタデータをクエリします。

リクエスト構文

HEAD /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

リクエストヘッダー

名前	タイプ	必須	説明
If-Modified-Since	String	No	このヘッダーで指定された時刻がオブジェクトの実際の変更時刻より前の場合、OSS は 200 OK とオブジェクトメタデータを返します。それ以外の場合、OSS は 304 Not Modified を返します。デフォルト: なし
If-Unmodified-Since	String	No	このヘッダーで指定された時刻がオブジェクトの実際の変更時刻と同じかそれ以降の場合、OSS は 200 OK とオブジェクトメタデータを返します。それ以外の場合、OSS は 412 Precondition Failed を返します。デフォルト: なし
If-Match	String	No	このヘッダーで指定された ETag がオブジェクトの ETag と一致する場合、OSS は 200 OK とオブジェクトメタデータを返します。それ以外の場合、OSS は 412 Precondition Failed を返します。デフォルト: なし
If-None-Match	String	No	このヘッダーで指定された ETag がオブジェクトの ETag と一致しない場合、OSS は 200 OK とオブジェクトメタデータを返します。それ以外の場合、OSS は 304 Not Modified を返します。デフォルト: なし

この操作では、Host や Date などの共通リクエストヘッダーも使用します。詳細については、「共通リクエストヘッダー」をご参照ください。

レスポンスヘッダー

リクエストされたオブジェクトがシンボリックリンクの場合、レスポンスヘッダーは次のようになります:

Content-Length、ETag、x-oss-storage-class、および Content-Md5 は、ターゲットオブジェクトのメタデータです。
Last-Modified は、シンボリックリンクの最終変更時刻とターゲットオブジェクトの最終変更時刻のうち、より新しい方です。
その他のレスポンスヘッダーは、シンボリックリンクのメタデータを示します。

名前	タイプ	説明
x-oss-meta-*	String	x-oss-meta- で始まるパラメーターは、ユーザー定義のメタデータヘッダーです。PutObject 操作を呼び出すときに x-oss-meta- で始まるカスタムメタデータを設定すると、レスポンスにこれらのカスタムメタデータヘッダーが含まれます。
x-oss-meta- で始まらないカスタムヘッダー	String	PutObject 操作中に `x-oss-meta-` プレフィックスで始まらないカスタムヘッダー (例: `x-oss-persistent-headers`:`key1:base64_encode(value1),key2:base64_encode(value2)...`) を指定すると、レスポンスにこれらのヘッダーが含まれます。
x-oss-server-side-encryption	String	オブジェクトがサーバー側暗号化で保存されている場合、このヘッダーがレスポンスで返されます。このヘッダーの値は、オブジェクトに使用されるサーバー側暗号化アルゴリズムを示します。
x-oss-server-side-encryption-key-id	String	オブジェクトの作成時に KMS を使用したサーバー側暗号化を使用する場合、レスポンスにこのヘッダーが含まれます。これは、暗号化に使用された KMS キーの ID を示します。
x-oss-storage-class	String	オブジェクトのストレージクラス。有効な値: 標準、低頻度アクセス (IA)、アーカイブストレージ、コールドアーカイブ、およびディープコールドアーカイブ。詳細については、「ストレージクラス」をご参照ください。
x-oss-object-type	String	オブジェクトのタイプ。 PutObject を呼び出してアップロードされたオブジェクトまたは CreateDirectory を呼び出して作成されたオブジェクトは、Normal タイプです。 AppendObject を呼び出してアップロードされたオブジェクトは、Appendable タイプです。 MultipartUpload を呼び出してアップロードされたオブジェクトは、Multipart タイプです。
x-oss-next-append-position	String	このヘッダーは Appendable オブジェクトに対して返されます。次の追加操作を開始する位置を指定します。
x-oss-hash-crc64ecma	String	オブジェクトの 64 ビット CRC 値。値は CRC-64/XZ アルゴリズムに基づいて計算されます。 OSS が CRC-64 チェックをサポートする前に作成されたオブジェクトの場合、HeadObject 操作を呼び出すときにこのレスポンスヘッダーが返されないことがあります。
x-oss-sealed-time	String	このヘッダーは、Sealed 状態の Appendable オブジェクトに対して返されます。オブジェクトがシールされた時刻を示します。時刻は、HTTP 1.1 で指定されている GMT 形式です (例: Sat, 11 Oct 2025 06:41:42 GMT)。
x-oss-transition-time	String	ライフサイクルルールによってオブジェクトがコールドアーカイブまたはディープコールドアーカイブストレージクラスに移行された時刻。説明ストレージクラスが変換されてから 180 日を超えてコールドアーカイブまたはディープコールドアーカイブオブジェクトを削除した場合、早期削除料金は請求されません。変換から 180 日以内にオブジェクトを削除した場合、早期削除料金が請求されます。このヘッダーを使用して、ライフサイクルルールに基づいてオブジェクトのストレージクラスが低頻度アクセスまたはアーカイブに変換された時刻をクエリすることはできません。オブジェクトが最小保存期間を超えて保存されているかどうかは、`Last-Modified` 時刻に基づいて判断できます。
x-oss-expiration	String	ライフサイクルルールが構成されているバケット内のオブジェクトの有効期限。バージョン管理が有効なバケット versionId なしのリクエストリクエストされたオブジェクトがライフサイクル構成の削除ルールに一致する場合、x-oss-expiration ヘッダーがレスポンスで返されます。このヘッダーは、オブジェクトの現在のバージョンの有効期限を示します。 versionId ありのリクエストリクエストされたオブジェクトがライフサイクル構成の削除ルールに一致するかどうかに関係なく、x-oss-expiration ヘッダーはレスポンスで返されません。バージョン管理が無効なバケットリクエストされたオブジェクトがライフサイクル構成の削除ルールに一致する場合、x-oss-expiration ヘッダーがレスポンスで返されます。リクエストされたオブジェクトがライフサイクル構成の削除ルールに一致しない場合、x-oss-expiration ヘッダーはレスポンスで返されません。
x-oss-restore	String	オブジェクトのストレージクラスがアーカイブストレージ、コールドアーカイブ、またはディープコールドアーカイブであり、RestoreObject リクエストを送信した場合、x-oss-restore ヘッダーがレスポンスで返され、オブジェクトの復元ステータスが示されます。ステータスは次のいずれかです。 RestoreObject リクエストが送信されていないか、復元されたオブジェクトの有効期限が切れている場合、このヘッダーは返されません。 RestoreObject リクエストが送信されたが復元が完了していない場合、x-oss-restore の値は ongoing-request="true" です。 RestoreObject リクエストが送信され、復元が完了した場合、x-oss-restore の値は ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT" です。expiry-date は、復元されたオブジェクトが読み取りできなくなる日時を示します。
x-oss-process-status	String	Simple Message Queue (SMQ) を使用して OSS イベント通知を作成した後、OSS 操作がイベント通知ルールに一致する場合、レスポンスにこのヘッダーが含まれます。値は、JSON 形式のイベント通知の Base64 エンコードされた結果です。
x-oss-request-charged	String	オブジェクトが属するバケットがリクエスト元支払いモードに設定されており、リクエスタがバケットの所有者でない場合、レスポンスには値が requester のこのヘッダーが含まれます。
Content-Md5	String	Normal オブジェクトの場合、これは RFC 1864 に従って計算されたメッセージコンテンツ (ヘッダーを除く) の Base64 エンコードされた 128 ビット MD5 ハッシュです。このヘッダーは、Multipart または Appendable オブジェクトには返されません。
Last-Modified	String	オブジェクトが最後に変更された日時。形式は HTTP 1.1 で指定されている GMT です。説明低頻度アクセス (IA) オブジェクトの最小保存期間は 30 日で、オブジェクトの Last-Modified 時刻から計算されます。最終変更から 30 日を超えて IA オブジェクトを削除した場合、早期削除料金は請求されません。アーカイブストレージオブジェクトの最小保存期間は 60 日で、オブジェクトの Last-Modified 時刻から計算されます。最終変更から 60 日を超えてアーカイブストレージオブジェクトを削除した場合、早期削除料金は請求されません。
Access-Control-Allow-Origin	String	オブジェクトを含むバケットに CORS ルールが構成されており、リクエストのオリジンが指定された CORS ルールに一致する場合、このオリジンがレスポンスに含まれます。
Access-Control-Allow-Methods	String	オブジェクトを含むバケットに CORS ルールが構成されており、リクエストの Access-Control-Request-Method が指定された CORS ルールに一致する場合、許可されたメソッドがレスポンスに含まれます。
Access-Control-Max-Age	String	オブジェクトを含むバケットに CORS ルールが構成されており、リクエストが CORS ルールに一致する場合、MaxAgeSeconds がレスポンスに含まれます。
Access-Control-Allow-Headers	String	オブジェクトを含むバケットに CORS ルールが構成されており、リクエストが指定された CORS ルールに一致する場合、これらのヘッダーがレスポンスに含まれます。
Access-Control-Expose-Headers	String	クライアント側の JavaScript プログラムがアクセスを許可されているヘッダーのリスト。オブジェクトを含むバケットに CORS ルールが構成されており、リクエストが指定された CORS ルールに一致する場合、ExposeHeader がレスポンスに含まれます。
x-oss-tagging-count	String	オブジェクトに関連付けられているタグの数。このヘッダーは、タグを読み取る権限がある場合にのみ返されます。

この操作では、ETag や x-oss-request-id などの共通レスポンスヘッダーも使用します。詳細については、「共通レスポンスヘッダー」をご参照ください。

例

バージョン管理が無効

リクエストの例

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例 (オブジェクトがファイルの場合)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

レスポンスの例 (オブジェクトがフォルダの場合)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Standard
Date: Wed, 31 Mar 2021 07:32:52 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "null"
Content-Length: 0
Content-Type: application/x-directory
Connection: keep-alive
Server: AliyunOSS

レスポンスの例 (シールされた Appendable オブジェクトの場合)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Appendable
x-oss-storage-class: Standard
x-oss-sealed-time: Sat, 11 Oct 2025 06:41:42 GMT
Date: Wed, 31 Mar 2021 07:32:52 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 100
Content-Type: text/plain
Connection: keep-alive
Server: AliyunOSS

オブジェクトの特定のバージョンをリクエストする (バージョン管理が有効)

リクエストの例

HEAD /example?versionId=CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy****
Host: versioning-test.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 06:27:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-versionId: CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy****
x-oss-request-id: 5CAC3B40B7AEADE01700****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 06:27:12 GMT
Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT
ETag: "A082B659EF78733A5A042FA253B1****"
Content-Length: 481827
Content-Type: text/html
Connection: keep-alive
Server: AliyunOSS

オブジェクトの最新バージョンをリクエストする (バージョン管理が有効)

リクエストの例

HEAD /example HTTP/1.1    
Host: versioning-test.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 06:27:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-versionId: CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx****
x-oss-request-id: 5CAC3B40B7AEADE01700****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 06:27:12 GMT
Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT
ETag: "3663F7B0B9D3153F884C821E7CF4****"
Content-Length: 485859
Content-Type: text/html
Connection: keep-alive
Server: AliyunOSS

RestoreObject リクエストが送信されましたが、復元は完了していません。

リクエストの例

HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-request-id: 58F71A164529F18D7F00****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-restore: ongoing-request="true"
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

RestoreObject リクエストが送信され、復元が完了しました。

リクエストの例

HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 09:35:51 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

応答サンプル

HTTP/1.1 200 OK
x-oss-request-id: 58F725344529F18D7F00****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
Date: Fri, 7 Aug 2020 09:35:51 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606

SSE-OSS を使用したサーバー側暗号化

リクエストの例

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-server-side-encryption: AES256
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

SSE-KMS を使用したサーバー側暗号化

リクエストの例

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-server-side-encryption: KMS
x-oss-server-side-encryption-key-id: 9468da86-3509-4f8d-a61e-6eab1eac****
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

SDK

この操作は、次の SDK で利用できます:

ossutil コマンドラインインターフェイス

HeadObject 操作に対応する ossutil コマンドについては、「head-object」をご参照ください。

エラーコード

エラーコード	HTTP ステータスコード	説明
NoSuchKey	404	リクエストされたオブジェクトは存在しません。
SymlinkTargetNotExist	404	リクエストされたファイルはシンボリックリンクです。
InvalidTargetType	400	リクエストされたオブジェクトはシンボリックリンクであり、そのターゲットオブジェクトもシンボリックリンクです。
NotModified	304	このエラーは、次のいずれかの理由で返されます。 If-Modified-Since リクエストヘッダーが指定されていますが、ソースオブジェクトは指定された時刻以降に変更されていません。 If-None-Match リクエストヘッダーが指定されており、ソースオブジェクトの ETag が指定した ETag と同じです。
PreconditionFailed	412	このエラーは、次のいずれかの理由で返されます。 If-Unmodified-Since ヘッダーが指定されていますが、指定された時刻はオブジェクトの実際の変更時刻より前です。 If-Match ヘッダーが指定されていますが、ソースオブジェクトの ETag が指定した ETag と同じではありません。