すべてのプロダクト
Search
ドキュメントセンター

Object Storage Service:PutObject

最終更新日:Feb 23, 2024

オブジェクトをアップロードします。

使用上の注意

  • この操作を使用して、サイズが5 GBを超えるオブジェクトをアップロードすることはできません。

  • デフォルトでは、バケット内の既存のオブジェクトの名前がアップロードするオブジェクトと同じで、既存のオブジェクトに対するアクセス権限がある場合、アップロード操作は既存のオブジェクトを上書きしてOK 200を返します。

  • Object Storage Service (OSS) は、階層構造ではなく、すべてのリソースにフラット構造を使用して、これらのリソースをオブジェクトとして格納します。 ただし、名前がスラッシュ (/) で終わる空のオブジェクトを作成することで、シミュレートされたディレクトリを作成できます。

バージョン管理

PutObject操作を呼び出してバージョン管理が有効なバケットにオブジェクトをアップロードすると、アップロードされたオブジェクトの一意のバージョンIDが生成され、レスポンスのx-OSS-version-IDヘッダーの値としてバージョンidが返されます。

PutObject操作を呼び出してバージョン管理が一時停止されたバケットにオブジェクトをアップロードすると、アップロードされたオブジェクトのバージョンIDはnullになります。 オブジェクトは、IDがnullのバージョンを1つだけ持つことができます。

リクエスト構文

PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
ホスト: BucketName.oss-cn-hangzhou.aliyuncs.com
日付: GMT日付
権限付与: SignatureValue 

リクエストヘッダー

OSSは、次のHTTPリクエストヘッダーをサポートしています: キャッシュ制御、期限切れ、コンテンツエンコード、コンテンツ配置、およびコンテンツタイプ。 オブジェクトのアップロード時にこれらのヘッダーを指定すると、オブジェクトのダウンロード時にヘッダーが指定された値に自動的に設定されます。

ヘッダー

データ型

必須

説明

権限付与

String

任意

OSS lkojgn8y1exic6e:6 **** + BuuEqzI1tAMW0wgIyl ****

リクエストが許可されることを指定します。 承認ヘッダーの計算方法の詳細については、「承認ヘッダーにV1署名を含める」をご参照ください。

ほとんどの場合、Authorizationヘッダーを指定する必要があります。 ただし、PutObjectリクエストで署名付きURLを使用する場合は、Authorizationヘッダーを指定する必要はありません。 詳細については、「署名V1を使用した署名付きURLの作成」をご参照ください。

デフォルトでは、このヘッダーは空のままです。

キャッシュ制御

String

任意

no-cache

オブジェクトがダウンロードされたときのwebページのキャッシュ動作。 有効な値:

  • no-cache: キャッシュされたコンテンツを直接使用することはできません。 オブジェクトコンテンツが更新されているかどうかを確認するには、キャッシュコンテンツをサーバーで検証する必要があります。 オブジェクトコンテンツが更新されると、キャッシュされたコンテンツは期限切れになり、オブジェクトはサーバーから再びダウンロードされます。 オブジェクトコンテンツが更新されない場合、キャッシュは期限切れにならず、オブジェクトはキャッシュから直接利用可能になります。

  • no-store: オブジェクトのすべてのコンテンツはキャッシュされません。

  • public: オブジェクトのすべてのコンテンツがキャッシュされます。

  • private: オブジェクトのすべてのコンテンツはクライアントにのみキャッシュされます。

  • max-age=<seconds>: キャッシュされたコンテンツの有効期間。 単位は秒です。 このオプションは、HTTP 1.1でのみ使用できます。

デフォルトでは、このヘッダーは空のままです。

コンテンツ処理

String

任意

添付ファイル

オブジェクトにアクセスするために使用されるメソッド。 有効な値:

  • Content-Disposition:inline: コンテンツプレビュー用にブラウザにオブジェクトが表示されます。

  • Content-Disposition:attachment: オブジェクトは、元のオブジェクト名でブラウザの指定されたダウンロードパスにダウンロードされます。

  • Content-Disposition:attachment; filename="yourFileName": オブジェクトは、カスタムオブジェクト名でブラウザの指定されたダウンロードパスにダウンロードされます。

    yourFileNameは、ダウンロードしたオブジェクトのカスタム名 (example.jpgなど) を指定します。

ブラウザの指定されたダウンロードパスにオブジェクトをダウンロードする前に、次の項目に注意してください。

説明
  • オブジェクトの名前にアスタリスク (*) やスラッシュ (/) などの特殊文字が含まれている場合、ダウンロードしたオブジェクトの名前をエスケープできます。 たとえば、example *.jpgをローカルコンピューターにダウンロードした場合、example *.jpgexample_.jpgとしてエスケープされます。

  • オブジェクト名に漢字が含まれているオブジェクトをダウンロードしても、ファイル名に文字化けしたローカルファイルが作成されないようにするには、オブジェクト名に漢字をURLエンコードする必要があります。 例えば、ことを保障するためtest.txtOSSのオブジェクトは、元のオブジェクト名を持つローカルファイルとしてダウンロードされます。test.txtContent-Dispositionヘッダーをattachment;filename=%E6%B5%8B%E8%AF%95.txt;filename *=UTF-8 ''%E6%B5%8B%E8%AF%95.txtから派生します。"attachment;filename=" + URLEncoder.encode("テスト" 、"UTF-8")+ ".txt;filename *=UTF-8" "+ URLEncoder.encode(" テスト "、" UTF-8 ")+".txt ").

オブジェクトURLを使用してオブジェクトにアクセスするときに、オブジェクトを添付ファイルとしてプレビューまたはダウンロードするかどうかは、オブジェクトが保存されているバケットの作成時間、OSSのアクティブ化時間、およびドメイン名の種類によって決まります。 詳細については、「画像オブジェクトが添付ファイルとしてダウンロードされても、URLを使用して画像オブジェクトにアクセスするとプレビューできない場合の対処方法」をご参照ください。

デフォルトでは、このヘッダーは空のままです。

コンテンツエンコーディング

String

任意

アイデンティティ

オブジェクトのエンコードに使用されるメソッド。 このヘッダーは、オブジェクトのエンコードタイプに基づいて指定する必要があります。 そうしないと、クライアントとして機能するブラウザがオブジェクトのエンコーディングタイプの解析に失敗するか、オブジェクトのダウンロードに失敗する可能性があります。 オブジェクトがエンコードされていない場合は、このヘッダーを空のままにします。 有効な値:

  • identity (デフォルト): OSSはオブジェクトを圧縮またはエンコードしません。

  • gzip: OSSは、LempelとZivが1977で作成したLZ77圧縮アルゴリズムと32ビットの巡回冗長検査 (CRC) を使用してオブジェクトをエンコードします。

  • compress: OSSはLempel-Ziv-Welch (LZW) 圧縮アルゴリズムを使用してオブジェクトをエンコードします。

  • deflate: OSSは、zlibライブラリとdeflateアルゴリズムを使用してオブジェクトをエンコードします。

  • br: OSSはBrotliアルゴリズムを使用してオブジェクトをエンコードします。

デフォルトでは、このヘッダーは空のままです。

コンテンツ-MD5

String

任意

eB5eJF1ptWaXm4bijSPyxw==

アップロードするオブジェクトのMD5ハッシュ。 Content-MD5値は、MD5アルゴリズムを用いて計算される。 PutObjectリクエストでContent-MD5ヘッダーを指定した場合、OSSはメッセージ本文に基づいてContent-MD5値を計算し、計算されたContent-MD5値がリクエストヘッダーで指定されたContent-MD5値と同じかどうかを確認します。 詳細については、「Content-MD5の計算」をご参照ください。

データの整合性を確保するために、アップロードするデータのMD5ハッシュを確認する複数の方法があります。 Content-MD5ヘッダーに基づいてアップロードするオブジェクトのMD5ハッシュを確認するには、Content-MD5ヘッダーをリクエストに追加します。

デフォルトでは、このヘッダーは空のままです。

コンテンツ長

String

任意

344606

HTTPメッセージ本文のデータのサイズ。 単位:バイト

リクエストのContent-Lengthヘッダーの値がリクエスト本文のデータサイズよりも小さい場合でも、オブジェクトを作成できます。 ただし、データはContent-Lengthヘッダーで指定されたオブジェクトサイズに切り捨てられます。

ETag

String

任意

D41D8CD98F00B204E9800998ECF8 ****

オブジェクトの作成時に生成されるETag。 ETagは、オブジェクトのコンテンツを識別するために使用されます。

  • PutObject操作を呼び出してオブジェクトが作成された場合、オブジェクトのETag値はオブジェクトコンテンツのMD5ハッシュになります。

  • オブジェクトが別のメソッドを使用して作成された場合、ETag値はオブジェクトコンテンツのMD5ハッシュではなく、特定のルールに基づいて計算された一意の値になります。

説明

オブジェクトのETagを使用して、オブジェクトの内容が変更されているかどうかを確認できます。 データの整合性を検証するには、オブジェクトのETag値ではなく、オブジェクトのMD5ハッシュを使用することをお勧めします。

デフォルトでは、このヘッダーは空のままです。

有効期限

String

任意

2022-10-12T00:00:00.000Z

UTCのキャッシュの有効期限。

デフォルトでは、このヘッダーは空のままです。

x-oss-forbid-overwrite

String

任意

false

PutObject操作を呼び出してアップロードされるオブジェクトが、同じ名前の既存のオブジェクトを上書きするかどうかを指定します。 オブジェクトをアップロードするバケットのバージョン管理が有効または一時停止されている場合、x-oss-forbid-overwriteヘッダーは有効になりません。 この場合、PutObject操作を呼び出してアップロードされたオブジェクトは、同じ名前の既存のオブジェクトを上書きします。

  • x-oss-forbid-overwriteヘッダーを指定しない場合、またはx-oss-forbid-overwriteヘッダーをfalseに設定した場合、PutObject操作を呼び出してアップロードされたオブジェクトは、同じ名前の既存のオブジェクトを上書きします。

  • x-oss-forbid-overwriteヘッダーをtrueに設定した場合、アップロードされたオブジェクトは、同じ名前の既存のオブジェクトを上書きできません。

x-oss-forbid-overwriteヘッダーを指定すると、OSSの1秒あたりのクエリ (QPS) パフォーマンスが低下します。 大量のリクエスト (QPS > 1,000) に対してx-oss-forbid-overwriteヘッダーを設定する場合は、チケットを起票してください。

デフォルト値: "false"

x-oss-server-side-encryption

String

任意

AES256

オブジェクトが作成されたときのサーバー側の暗号化方法。

有効な値:AES256KMS.

x-oss-server-side-encryptionヘッダーを指定した場合、レスポンスでx-oss-server-side-encryptionヘッダーが返されます。 OSSは、このヘッダーで指定されたメソッドを使用して、アップロードされたオブジェクトを暗号化します。 オブジェクトをダウンロードすると、x-oss-server-side-encryptionヘッダーがレスポンスに含まれます。 レスポンスのヘッダーの値は、オブジェクトの暗号化に使用されるアルゴリズムです。

x-oss-server-side-encryption-key-id

String

任意

9468da86-3509-4f8d-a61e-6eab1eac ****

key Management Service (KMS) によって管理されるカスタマーマスターキー (CMK) のID。

このヘッダーは、x-oss-server-side-encryptionヘッダーがKMSに設定されている場合にのみ有効です。

x-oss-object-acl

String

任意

default

オブジェクトのアクセス制御リスト (ACL) 。

有効な値:

  • default (デフォルト): オブジェクトのACLは、オブジェクトが格納されているバケットのACLと同じです。

  • private: オブジェクトのACLがprivateです。 オブジェクトの読み取りおよび書き込み権限を持つのは、オブジェクトの所有者および許可されたユーザーのみです。

  • public-read: オブジェクトのACLはpublic-readです。 オブジェクトの読み取りおよび書き込み権限を持つのは、オブジェクトの所有者および許可されたユーザーのみです。 他のユーザーには、オブジェクトに対する読み取り権限のみがあります。 オブジェクトACLをこの値に設定する場合は注意してください。

  • public-read-write: オブジェクトのACLはpublic-read-writeです。 すべてのユーザーは、オブジェクトに対する読み取りおよび書き込み権限を持っています。 オブジェクトACLをこの値に設定する場合は注意してください。

ACLの詳細については、「オブジェクトACL」をご参照ください。

x-oss-storage-class

String

任意

標準

オブジェクトのストレージクラス。

オブジェクトをアップロードするときにx-oss-storage-classヘッダーを指定した場合、オブジェクトがアップロードされるバケットのストレージクラスに関係なく、アップロードされたオブジェクトのストレージクラスは指定された値になります。 たとえば、低頻度アクセス (IA) バケットにオブジェクトをアップロードするときにx-oss-storage-classヘッダーを標準に設定すると、オブジェクトは標準オブジェクトとして保存されます。

有効な値:

  • 標準

  • IA

  • アーカイブ

  • ColdArchive

  • DeepColdArchive

    重要

    多数のオブジェクトをアップロードし、オブジェクトのストレージクラスをDeep Cold Archiveに設定する場合は、高いPUTリクエスト料金が請求されます。 オブジェクトのアップロード時にオブジェクトのストレージクラスを標準に設定し、標準オブジェクトのストレージクラスをDeep Cold Archiveに変換するようにライフサイクルルールを設定することを推奨します。 これにより、PUTリクエスト料金が削減されます。

ストレージクラスの詳細については、「概要」をご参照ください。

x-oss-meta-*

String

任意

x-oss-meta-location

アップロードするオブジェクトのメタデータ。 例: x-oss-meta-location オブジェクトに複数の同様のヘッダーを指定できます。 ただし、オブジェクトのメタデータのサイズは8 KBを超えることはできません。

メタデータヘッダーの名前には、英数字、ハイフン (-) を使用できます。 大文字は小文字に変換されます。 アンダースコア (_) などの他の文字はサポートされていません。

x-oss-tagging

String

任意

TagA=A&TagB=B

キーと値のペアを使用してオブジェクトに指定されたタグ。 オブジェクトに複数のタグを指定できます。 例: TagA=A&TagB=B

説明

タグキーとタグ値はURLエンコードされている必要があります。 オブジェクトにタグを指定する場合、タグキーのみが必要で、タグ値はオプションです。 たとえば、このヘッダーの値をTagA&TagB=Bに設定できます。

PutObjectリクエストの一般的なリクエストヘッダー (HostやDateなど) の詳細については、「一般的なリクエストヘッダー」をご参照ください。

レスポンスヘッダー

ヘッダー

データ型

説明

Content-MD5

String

1B2M2Y8AsgTpgAmY7PhC ****

オブジェクトのMD5ハッシュ。

重要

オブジェクトのMD5ハッシュは、クライアントがオブジェクトをアップロードした後に取得されます。 オブジェクトのMD5ハッシュは、レスポンスボディのMD5ハッシュではありません。

x-oss-hash-crc64ecma

String

316181249502703 ****

オブジェクトのCRC-64値。

x-oss-version-id

String

CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0 ****

オブジェクトのバージョンIDを示します。 このヘッダーは、バージョン管理が有効なバケットにオブジェクトをアップロードした場合にのみ返されます。

PutObjectリクエストへのレスポンスの一般的なレスポンスヘッダー (Dateやx-oss-request-idなど) の詳細については、「一般的なレスポンスヘッダー」をご参照ください。

  • シンプルアップロードを使用したオブジェクトのアップロード

    リクエストの例

    PUT /test.txt HTTP/1.1
    ホスト: test.oss-cn-zhangjiakou.aliyuncs.com
    ユーザーエージェント: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
    受け入れる: */*
    接続: キープアライブ
    Content-Type: text/plain
    日付: 12月4日火曜日2018 15:56:37 GMT
    承認: OSS qn6qrrqxo2oawuk53otf ****:kZoYNv66bsmc10 + dcGKw5x2P ****
    転送-エンコーディング: chunked 

    レスポンスの例

    HTTP/1.1 200 OK
    サーバー: AliyunOSS
    日付: 火曜日、4 12月2018日15:56:38 GMT
    コンテンツ長: 0
    接続: キープアライブ
    x-oss-request-id: 5C06A3B67B8B5A3DA422299D
    ETag: "D41D8CD98F00B204E9800998ECF8 ****"
    x-oss-hash-crc64ecma: 316181249502703 ****
    Content-MD5: 1B2M2Y8AsgTpgAmY7PhC ****
    x-oss-server-time: 7 
  • アーカイブオブジェクトのアップロード

    リクエストの例

    PUT /oss.jpg HTTP/1.1
    ホスト: oss-example.oss-cn-hangzhou.aliyuncs.comキャッシュ制御: no-Cache
    有効期限: 2月28日金曜日2012 05:38:42 GMT
    コンテンツエンコード: utf-8
    Content-Disposition: attachment;filename=oss_download.jpg
    日付: 2月24日金曜日2012 06:03:28 GMT
    コンテンツタイプ: image/jpg
    コンテンツ-長さ: 344606
    x-oss-storage-class: アーカイブ
    承認: OSS qn6qrrqxo2oawuk53otf ****:kZoYNv66bsmc10 + dcGKw5x2P ****
    [344606バイトのオブジェクトデータ] 

    レスポンスの例

    HTTP/1.1 200 OK
    サーバー: AliyunOSS
    日付: 11月21日 (土) 2015 18:52:34 GMT
    コンテンツタイプ: image/jpg
    コンテンツ長: 0
    接続: キープアライブ
    x-oss-request-id: 5650BD72207FB30443962F9A
    ETag: "A797938C31D59EDD08D86188F6D5B872" 
  • バージョン管理が有効なバケットにオブジェクトをアップロードする

    リクエストの例

    PUT /テストHTTP/1.1
    コンテンツ-長さ: 362149
    コンテンツタイプ: text/html
    ホスト: versioning-put.oss-cn-hangzhou.aliyuncs.com
    日付: 4月2019日火曜日02:53:24 GMT
    権限付与: OSS lkojgn8y1exic6e:6 **** + BuuEqzI1tAMW0wgIyl **** 

    レスポンスの例

    HTTP/1.1 200 OK
    サーバー: AliyunOSS
    日付: 4月2019日火曜日02:53:24 GMT
    コンテンツ長: 0
    接続: キープアライブ
    x-oss-request-id: 5CAC0A3DB7AEADE01700 ****
    x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0 ****
    ETag: "4F345B1F066DB1444775AA97D5D2 ****" 

OSS SDK

次のプログラミング言語のOSS SDKを使用して、PutObject操作を呼び出すことができます。

エラーコード

エラーコード

HTTPステータスコード

説明

MissingContentLength

411

リクエストヘッダーがチャンクエンコーディングを使用してエンコードされていないか、Content-Lengthヘッダーが指定されていません。

InvalidEncryptionAlgorithmError

400

x-oss-server-side-encryptionヘッダーの指定値が無効です。

有効な値:AES256KMS

AccessDenied

403

オブジェクトをアップロードする指定されたバケットにアクセスする権限がありません。

NoSuchBucket

404

オブジェクトをアップロードする指定されたバケットが存在しません。

InvalidObjectName

400

指定されたオブジェクトキーの長さが1,023バイトを超えています。

InvalidArgument

400

考えられる原因:

  • アップロードするオブジェクトのサイズが5 GBを超えています。

  • x-oss-storage-classなどのヘッダーの値が無効です。

RequestTimeout

400

リクエストにContent-Lengthヘッダーが指定されていますが、メッセージ本文が送信されないか、メッセージ本文のデータのサイズが指定された値未満です。 この場合、サーバーはリクエストがタイムアウトするまで待機します。

Bad Request

400

リクエストヘッダーで指定されているContent-MD5値は、OSSで計算されたMD5ハッシュとは異なります。 OSSは、メッセージ本文に基づいてMD5ハッシュを計算し、計算されたMD5ハッシュをリクエストヘッダーで指定されたContent-MD5値と比較します。

KmsServiceNotEnabled

403

x-oss-server-side-encryptionヘッダーはKMSに設定されていますが、KMSは事前に有効化されていません。

FileAlreadyExists

409

考えられる原因:

  • リクエストにはx-oss-forbid-overwrite=trueヘッダーが含まれ、バケットにはアップロードするオブジェクトと同じ名前のオブジェクトが含まれます。

  • バケットに対して階層名前空間機能が有効になり、アップロードするオブジェクトと同じ名前のディレクトリが現在のディレクトリレベルに存在します。

FileImmutable

409

削除または変更するデータは保護されています。 保護期間中、バケット内のデータは削除または変更できません。

よくある質問

アップロードされたオブジェクトのメタデータを変更できますか?

はい。OSSコンソール、OSS API、ossbrowser、さまざまなプログラミング言語のOSS SDK、またはossutilを使用して、アップロードされたオブジェクトのメタデータを変更できます。 たとえば、Content-Typeヘッダーの値をapplication/octet-streamからimage/jpegに変更できます。 詳細については、「オブジェクトメタデータの管理」をご参照ください。