オブジェクトをアップロードします。
使用上の注意
この操作を使用して、サイズが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ページのキャッシュ動作。 有効な値:
デフォルトでは、このヘッダーは空のままです。 |
コンテンツ処理 | String | 任意 | 添付ファイル | オブジェクトにアクセスするために使用されるメソッド。 有効な値:
ブラウザの指定されたダウンロードパスにオブジェクトをダウンロードする前に、次の項目に注意してください。 説明
オブジェクトURLを使用してオブジェクトにアクセスするときに、オブジェクトを添付ファイルとしてプレビューまたはダウンロードするかどうかは、オブジェクトが保存されているバケットの作成時間、OSSのアクティブ化時間、およびドメイン名の種類によって決まります。 詳細については、「画像オブジェクトが添付ファイルとしてダウンロードされても、URLを使用して画像オブジェクトにアクセスするとプレビューできない場合の対処方法」をご参照ください。 デフォルトでは、このヘッダーは空のままです。 |
コンテンツエンコーディング | String | 任意 | アイデンティティ | オブジェクトのエンコードに使用されるメソッド。 このヘッダーは、オブジェクトのエンコードタイプに基づいて指定する必要があります。 そうしないと、クライアントとして機能するブラウザがオブジェクトのエンコーディングタイプの解析に失敗するか、オブジェクトのダウンロードに失敗する可能性があります。 オブジェクトがエンコードされていない場合は、このヘッダーを空のままにします。 有効な値:
デフォルトでは、このヘッダーは空のままです。 |
コンテンツ-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は、オブジェクトのコンテンツを識別するために使用されます。
説明 オブジェクトの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ヘッダーを指定すると、OSSの1秒あたりのクエリ (QPS) パフォーマンスが低下します。 大量のリクエスト (QPS > 1,000) に対してx-oss-forbid-overwriteヘッダーを設定する場合は、チケットを起票してください。 デフォルト値: "false" |
x-oss-server-side-encryption | String | 任意 | AES256 | オブジェクトが作成されたときのサーバー側の暗号化方法。 有効な値: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」をご参照ください。 |
x-oss-storage-class | String | 任意 | 標準 | オブジェクトのストレージクラス。 オブジェクトをアップロードするときにx-oss-storage-classヘッダーを指定した場合、オブジェクトがアップロードされるバケットのストレージクラスに関係なく、アップロードされたオブジェクトのストレージクラスは指定された値になります。 たとえば、低頻度アクセス (IA) バケットにオブジェクトをアップロードするときにx-oss-storage-classヘッダーを標準に設定すると、オブジェクトは標準オブジェクトとして保存されます。 有効な値:
ストレージクラスの詳細については、「概要」をご参照ください。 |
x-oss-meta-* | String | 任意 | x-oss-meta-location | アップロードするオブジェクトのメタデータ。 例: メタデータヘッダーの名前には、英数字、ハイフン (-) を使用できます。 大文字は小文字に変換されます。 アンダースコア (_) などの他の文字はサポートされていません。 |
x-oss-tagging | String | 任意 | TagA=A&TagB=B | キーと値のペアを使用してオブジェクトに指定されたタグ。 オブジェクトに複数のタグを指定できます。 例: 説明 タグキーとタグ値はURLエンコードされている必要があります。 オブジェクトにタグを指定する場合、タグキーのみが必要で、タグ値はオプションです。 たとえば、このヘッダーの値を |
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ヘッダーの指定値が無効です。 有効な値:AES256 と KMS |
AccessDenied | 403 | オブジェクトをアップロードする指定されたバケットにアクセスする権限がありません。 |
NoSuchBucket | 404 | オブジェクトをアップロードする指定されたバケットが存在しません。 |
InvalidObjectName | 400 | 指定されたオブジェクトキーの長さが1,023バイトを超えています。 |
InvalidArgument | 400 | 考えられる原因:
|
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 | 考えられる原因:
|
FileImmutable | 409 | 削除または変更するデータは保護されています。 保護期間中、バケット内のデータは削除または変更できません。 |
よくある質問
アップロードされたオブジェクトのメタデータを変更できますか?
はい。OSSコンソール、OSS API、ossbrowser、さまざまなプログラミング言語のOSS SDK、またはossutilを使用して、アップロードされたオブジェクトのメタデータを変更できます。 たとえば、Content-Typeヘッダーの値をapplication/octet-streamからimage/jpegに変更できます。 詳細については、「オブジェクトメタデータの管理」をご参照ください。