すべてのプロダクト
Search

このプロダクト

    Object Storage Service:PutObject

    ドキュメントセンター

    Object Storage Service:PutObject

    最終更新日:Sep 30, 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
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    リクエストヘッダー

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

    ヘッダー

    タイプ

    必須

    例

    説明

    権限付与

    String

    任意

    OSS qn6q ****************: 77Dv ***********************

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

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

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

    キャッシュ制御

    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 *.jpgはexample_.jpgとしてエスケープされます。

    • オブジェクト名に漢字が含まれているオブジェクトをダウンロードしても、ファイル名に文字化けしたローカルファイルが作成されないようにするには、オブジェクト名に漢字をURLエンコードする必要があります。 例えば、ことを保障するため测量. txtOSSのオブジェクトは、元のオブジェクト名を持つローカルファイルとしてダウンロードされます。测量. 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

    グリニッジ標準時 (GMT) のキャッシュの絶対有効期限。

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

    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

    オブジェクトが作成されたときに、OSSサーバー上でアップロードされたオブジェクトを暗号化するために使用されるメソッド。

    有効な値：AES256 と KMS.

    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) 。

    有効な値：

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

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

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

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

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

    x-oss-storage-class

    String

    任意

    標準

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

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

    有効な値：

    • 標準

      説明

      CloudBoxでOSSを使用する場合、標準ストレージクラスのみがサポートされます。

    • IA

    • アーカイブ

    • ColdArchive

    • DeepColdArchive

      重要

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

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

    x-oss-meta-*

    String

    任意

    x-oss-meta-location

    オブジェクトのメタデータを指定します。 x-oss-meta- パラメーターを含むパラメーターを設定すると、パラメーターにメタデータが指定されます。 例: 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など) の詳細については、「一般的なHTTPヘッダー」をご参照ください。

    例

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

      リクエストの例

      PUT /test.txt HTTP/1.1
Host: test.oss-cn-zhangjiakou.aliyuncs.com
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: */*
Connection: keep-alive
Content-Type: text/plain
date: Tue, 04 Dec 2018 15:56:37 GMT
authorization: OSS qn6q**************:77Dv****************
Transfer-Encoding: chunked

      正常に処理された場合のレスポンス例 

      HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 04 Dec 2018 15:56:38 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5C06A3B67B8B5A3DA422299D
ETag: "D41D8CD98F00B204E9800998ECF8****"
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
x-oss-server-time: 7

    • オブジェクトをアップロードし、オブジェクトのストレージクラスをArchiveに設定します。

      リクエストの例

      PUT /oss.jpg HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com Cache-control: no-cache 
Expires: Fri, 28 Feb 2012 05:38:42 GMT 
Content-Encoding: utf-8
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Fri, 24 Feb 2012 06:03:28 GMT 
Content-Type: image/jpg 
Content-Length: 344606 
x-oss-storage-class: Archive
Authorization: OSS qn6q**************:77Dv**************** 
[344606 bytes of object data]

      正常に処理された場合のレスポンス例 

      HTTP/1.1 200 OK
Server: AliyunOSS
Date: Sat, 21 Nov 2015 18:52:34 GMT
Content-Type: image/jpg
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5650BD72207FB30443962F9A
ETag: "A797938C31D59EDD08D86188F6D5B872"

    • バージョン管理が有効なバケットにオブジェクトをアップロードする

      リクエストの例

      PUT /test HTTP/1.1
Content-Length: 362149
Content-Type: text/html
Host: versioning-put.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:53:24 GMT
Authorization: OSS qn6q**************:77Dv****************

      正常に処理された場合のレスポンス例 

      HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 02:53:24 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5CAC0A3DB7AEADE01700****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****
ETag: "4F345B1F066DB1444775AA97D5D2****"

    SDK

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

    エラーコード

    エラーコード

    HTTPステータスコード

    説明

    MissingContentLength

    411

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

    InvalidEncryptionAlgorithmError

    400

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

    有効な値：AES256 と KMS.

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

    なぜExpiresヘッダーの指定された値が無効なのですか?

    • ヘッダーの優先度

      ExpiresヘッダーとCache-Controlヘッダーの両方を指定すると、Cache-Controlヘッダーの値がExpiresヘッダーの値よりも優先されます。 ブラウザは、Cache-Controlヘッダーが設定されているかどうかを確認し、Expiresヘッダーの指定された値は、Cache-Controlヘッダーに有効な値が指定されていない場合にのみ有効になります。 Cache-Controlヘッダーにcache-Control:max-age=3600などのキャッシュ管理命令が含まれている場合、Expiresヘッダーは無視されます。

    • Expiresヘッダーの無効な値

      Expiresヘッダーは、GMTでのキャッシュの絶対有効期限を指定し、その値は将来の有効な時点である必要があります。 Expiresヘッダーの指定された値が期限切れまたは無効な形式の場合、ヘッダーは無効と見なされます。 次のサンプルコードは、OSS SDK for Node.jsを使用してExpiresヘッダーを指定する方法の例を示しています。

      const OSS = require('ali-oss');

// Create an OSS client instance.
const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'examplebucket',
});

async function setExpires(objectName, expiresDate) {
  try {
    const result = await client.copy(objectName, objectName, {
      meta: {
        'Expires': expiresDate.toGMTString()
      }
    });
    console.log('Expires header set successfully.');
  } catch (error) {
    console.error('Error setting Expires header:', error);
  }
}

// Specify the absolute expiration time of the cache. 
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);