Retrieve object metadata - Object Storage Service - Alibaba Cloud ドキュメントセンター

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

バージョン管理

versionId を指定せずに HeadObject 操作を呼び出すと、オブジェクトの現在のバージョンのメタデータが返されます。オブジェクトの現在のバージョンが削除マーカーの場合、404 NoSuchKey が返されます。
HeadObject 操作を呼び出して versionId を指定すると、指定されたバージョンのオブジェクトのメタデータが返されます。削除マーカーの versionId は指定できません。指定した場合、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	いいえ	このヘッダーで指定された時刻がオブジェクトの実際の変更時刻より前の場合、操作は 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- で始まらないカスタムヘッダー	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	オブジェクトのタイプ。 Normal: PutObject 操作または CreateDirectory 操作を使用してアップロードまたは作成されたオブジェクト。 Appendable: AppendObject 操作を使用してアップロードされたオブジェクト。 Multipart: マルチパートアップロード機能を使用してアップロードされたオブジェクト。
x-oss-next-append-position	String	追加可能オブジェクトに対して返されます。その値は、次の追加操作の開始位置を指定します。
x-oss-hash-crc64ecma	String	オブジェクトの 64 ビット巡回冗長検査 (CRC) 値。値は ECMA-182 規格に従って計算されます。このヘッダーは、OSS が CRC64 チェックサムサポートを実装する前に作成されたオブジェクトに対しては返されない場合があります。
x-oss-sealed-time	String	このヘッダーは、シール済み追加可能オブジェクトに対して返されます。値はオブジェクトがシールされた時刻を示します。時刻は 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	オブジェクトのストレージクラスがアーカイブ、コールドアーカイブ、またはディープコールドアーカイブであり、`RestoreObject` リクエストを送信した場合、このヘッダーはオブジェクトの復元ステータスを示すために返されます。次のケースが発生する可能性があります。 `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 イベント通知を設定した場合、このヘッダーは一致するルールをトリガーする操作に対して返されます。値は、JSON 形式の Base64 エンコードされたイベント通知結果です。
x-oss-request-charged	String	オブジェクトのバケットがリクエスター支払いモードであり、リクエストがバケット所有者によって行われていない場合、このヘッダーは値 requester とともに返されます。
Content-Md5	String	通常オブジェクトの場合、これは RFC 1864 に従って計算された、メッセージ本文 (ヘッダーを除く) の Base64 エンコードされた 128 ビット MD5 ハッシュです。このヘッダーは、マルチパートオブジェクトまたは追加可能オブジェクトに対しては返されません。
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 ルールと一致する場合、このヘッダーはレスポンスに含まれます。
x-oss-tagging-count	String	オブジェクトに関連付けられたタグの数。このヘッダーは、リクエスターがタグを読み取る権限を持っている場合にのみ返されます。
x-oss-object-worm-mode	String	オブジェクトの保持ポリシーモードを示します。このヘッダーは、バケットで ObjectWorm が有効になっており、オブジェクトに保持ポリシーが設定されており、呼び出し元が `GetObjectRetention` 権限を持っている場合にのみ、値 `COMPLIANCE` とともに返されます。
x-oss-object-worm-retain-until-date	String	オブジェクトの保持有効期限。この日付より前にオブジェクトを削除または上書きすることはできません。このヘッダーは、バケットで ObjectWorm が有効になっており、呼び出し元が `GetObjectRetention` 権限を持っており、オブジェクトに保持ポリシーが設定されている場合にのみ返されます。

レスポンスには、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/jpeg
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

レスポンス (シール済み追加可能オブジェクトの場合)

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/jpeg
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/jpeg
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/jpeg
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 と同じではない場合。