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

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

バージョン管理

HeadObject 操作を呼び出す際に versionId を指定しない場合、現在のオブジェクトバージョンのメタデータが返されます。現在のオブジェクトバージョンが削除マーカーの場合、404 NoSuchKey が返されます。
HeadObject 操作を呼び出す際に versionId を指定した場合、指定されたオブジェクトバージョンのメタデータが返されます。削除マーカーの versionId は指定しないでください。指定した場合、405 MethodNotAllowed が返されます。

権限

デフォルトでは、Alibaba Cloud アカウントは完全な権限を持っています。Alibaba Cloud アカウントに属する Resource Access Management (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	いいえ	指定された時刻がオブジェクトの実際の変更時刻より前の場合、200 OK とオブジェクトのメタデータが返されます。それ以外の場合は、304 Not Modified が返されます。デフォルト値：なし
If-Unmodified-Since	String	いいえ	指定された時刻がオブジェクトの実際の変更時刻と同じかそれ以降の場合、200 OK とオブジェクトのメタデータが返されます。それ以外の場合は、412 Precondition Failed が返されます。デフォルト値：なし
If-Match	String	いいえ	指定された ETag がオブジェクトの ETag と一致する場合、200 OK とオブジェクトのメタデータが返されます。それ以外の場合は、412 Precondition Failed が返されます。デフォルト値：なし
If-None-Match	String	いいえ	指定された ETag がオブジェクトの ETag と一致しない場合、200 OK とオブジェクトのメタデータが返されます。それ以外の場合は、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-persistent-headers:`key1:base64_encode(value1),key2:base64_encode(value2)...` のように x-oss-meta- で始まらないカスタムヘッダーを指定した場合、対応するカスタムヘッダーがレスポンスに追加されます。
x-oss-server-side-encryption	String	オブジェクトがサーバー側暗号化で保存されている場合、このヘッダーがレスポンスで返されます。このヘッダーの値は、オブジェクトに使用されているサーバー側暗号化アルゴリズムを示します。
x-oss-server-side-encryption-key-id	String	オブジェクト作成時にサーバー側暗号化が使用され、暗号化方式が KMS の場合、このヘッダーがレスポンスに含まれます。このヘッダーは、ユーザーの KMS キーの ID を示します。
x-oss-storage-class	String	オブジェクトのストレージクラス。有効値：Standard、IA、Archive、ColdArchive、DeepColdArchive。詳細については、「ストレージクラス」をご参照ください。
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-64) 値。値は CRC-64/XZ アルゴリズムに基づいて計算されます。 OSS が CRC-64 をサポートする前に作成されたオブジェクトに対して HeadObject 操作を呼び出すと、このレスポンスヘッダーは返されない場合があります。
x-oss-sealed-time	String	このヘッダーは、封印された Appendable オブジェクトに対して返されます。このヘッダーの値は、オブジェクトが封印された時刻を示します。時刻は HTTP 1.1 で指定された GMT 形式で、Sat, 11 Oct 2025 06:41:42 GMT のようになります。
x-oss-transition-time	String	ライフサイクルルールによってオブジェクトがコールドアーカイブまたはディープコールドアーカイブストレージクラスに変換された時刻。説明コールドアーカイブまたはディープコールドアーカイブオブジェクトを変換後 180 日を超えて削除した場合、早期削除料金は発生しません。変換後 180 日以内にオブジェクトを削除した場合、早期削除料金が発生します。このフィールドは、ライフサイクルルールによってオブジェクトが IA またはアーカイブストレージクラスに変換された時刻を判断するために使用することはできません。IA またはアーカイブオブジェクトが最低保管期間の要件を満たすかどうかは、`Last-Modified` 時刻に依存します。
x-oss-expiration	String	ライフサイクルルールが設定されているバケット内のオブジェクトの有効期限。バケットでバージョン管理が有効になっている場合 versionId なしでリクエストが送信されます。リクエストされたオブジェクトがライフサイクル設定の削除ルールに一致する場合、レスポンスで x-oss-expiration ヘッダーが返され、オブジェクトの現在のバージョンの有効期限を示します。 versionId 付きでリクエストが送信されます。リクエストされたオブジェクトがライフサイクル設定の削除ルールに一致するかどうかに関わらず、レスポンスで x-oss-expiration ヘッダーは返されません。バケットでバージョン管理が無効になっている場合リクエストされたオブジェクトがライフサイクル設定の削除ルールに一致する場合、レスポンスで x-oss-expiration ヘッダーが返されます。リクエストされたオブジェクトがライフサイクル設定の削除ルールに一致しない場合、レスポンスで x-oss-expiration ヘッダーは返されません。
x-oss-restore	String	オブジェクトのストレージクラスが Archive、ColdArchive、または DeepColdArchive であり、Restore リクエストを送信した場合、オブジェクトの解凍ステータスが x-oss-restore レスポンスヘッダーで返されます。次のケースが発生する可能性があります： Restore リクエストが送信されていないか、解凍されたオブジェクトの有効期限が切れている場合、このヘッダーは返されません。 Restore リクエストは送信されたが、解凍タスクが完了していない場合、x-oss-restore の値は ongoing-request="true" です。 Restore リクエストが送信され、解凍タスクが完了した場合、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 オブジェクトの場合、メッセージコンテンツ (ヘッダーを除く) の 128 ビット MD5 値が RFC 1864 に基づいて計算されます。この値は Base64 エンコードされて Content-Md5 値が取得されます。このヘッダーは、Multipart または Appendable オブジェクトには返されません。
Last-Modified	String	オブジェクトが最後に変更された日付。形式は HTTP 1.1 で指定された GMT 時刻です。説明低頻度アクセスストレージクラスのオブジェクトの最低保管期間は 30 日です。期間はオブジェクトの Last-Modified 時刻から計算されます。Last-Modified 時刻から 30 日を超えてオブジェクトを削除した場合、早期削除料金は発生しません。アーカイブストレージクラスのオブジェクトの最低保管期間は 60 日です。期間はオブジェクトの Last-Modified 時刻から計算されます。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

解凍タスクが進行中

リクエスト例

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

解凍タスクが完了

リクエスト例

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 と同じではありません。