PutObject 操作は、Object Storage Service (OSS) のバケットにオブジェクトをアップロードします。1 回のアップロードでアップロードできるオブジェクトのサイズは 5 GB を超えることはできません。
リクエスト構文
PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue注意事項
1 回の操作でアップロードできるオブジェクトの最大サイズは 5 GB です。5 GB を超えるオブジェクトをアップロードするには、マルチパートアップロードを使用してください。
デフォルトでは、既存のオブジェクトと同じ名前のオブジェクトをアップロードすると、OSS はオブジェクトを上書きし、200 OK ステータスコードを返します。パラメーターを設定して上書きを防止し、重要なオブジェクトが誤って上書きされるのを防ぐことができます。
OSS はフラットなストレージ構造を使用しており、従来のファイルシステムにあるようなディレクトリの概念はありません。名前がスラッシュ (/) で終わる空のオブジェクトを作成することで、フォルダ構造をシミュレートできます。
権限
バージョン管理
リクエストパラメーター
OSS は、Cache-Control、Expires、Content-Encoding、Content-Disposition、Content-Type などの標準的な HTTP リクエストヘッダーをサポートしています。アップロードリクエストでこれらのヘッダーを設定すると、オブジェクトのダウンロード時にその値が自動的に適用されます。
パラメーター | タイプ | 必須 | 例 | 説明 |
Authorization | String | いいえ | OSS qn6q**************:77Dv**************** | リクエストを認証および認可します。署名の計算方法の詳細については、「ヘッダーに署名を含める」をご参照ください。 通常、Authorization ヘッダーは必須です。ただし、署名が URL に含まれている場合は、このヘッダーを含める必要はありません。詳細については、「URL に署名を含める」をご参照ください。 デフォルト値：なし |
Cache-Control | String | いいえ | no-cache | オブジェクトのダウンロード時のキャッシュ動作を指定します。有効な値：
デフォルト値：なし |
Content-Disposition | String | いいえ | attachment | オブジェクトの表示方法を指定します。有効な値：
オブジェクトをブラウザの指定されたダウンロードパスにダウンロードする場合は、次の点に注意してください： 説明
オブジェクト URL を使用してオブジェクトにアクセスしたときに、オブジェクトがプレビューされるか、添付ファイルとしてダウンロードされるかは、オブジェクトが保存されているバケットの作成時間、OSS のアクティベーション時間、およびドメイン名のタイプによって決まります。詳細については、「画像オブジェクトの URL を使用してアクセスすると、プレビューできずに添付ファイルとしてダウンロードされるのはなぜですか？」をご参照ください。 デフォルト値：なし |
Content-Encoding | String | いいえ | identity | オブジェクトのエンコーディングを指定します。このヘッダーは、オブジェクトの実際のエンコーディングタイプに設定する必要があります。そうしないと、クライアント側の解析またはダウンロードエラーが発生する可能性があります。オブジェクトがエンコードされていない場合は、このヘッダーを空のままにします。有効な値：
デフォルト値：なし |
Content-MD5 | String | いいえ | eB5eJF1ptWaXm4bijSPyxw== | メッセージ本文の整合性をチェックするために使用されます。Content-MD5 ヘッダーは、MD5 アルゴリズムを使用して生成された値です。このヘッダーを設定すると、OSS はメッセージ本文の Content-MD5 値を計算し、指定した値と一致するかどうかを確認します。詳細については、「Content-MD5 値の計算」をご参照ください。 データ整合性を確保するために、OSS は MD5 ハッシュ値を検証するための複数のメソッドを提供しています。Content-MD5 を使用して検証する場合は、リクエストに Content-MD5 ヘッダーを含めてください。 デフォルト値：なし |
Content-Length | String | いいえ | 344606 | 転送される HTTP メッセージ本文のサイズ (バイト単位)。 Content-Length ヘッダーの値がリクエストボディの実際のデータサイズより小さい場合でも、OSS はオブジェクトを作成します。ただし、オブジェクトサイズは Content-Length で指定されたサイズと等しくなり、超過したデータは破棄されます。 |
Expires | String | いいえ | Wed, 08 Jul 2015 16:57:01 GMT | オブジェクトの有効期限を指定します。詳細については、「RFC2616」をご参照ください。 デフォルト値：なし |
x-oss-forbid-overwrite | String | いいえ | false | PutObject 操作中に同じ名前のオブジェクトを上書きするかどうかを指定します。宛先バケットでバージョン管理が有効または一時停止されている場合、x-oss-forbid-overwrite リクエストヘッダーは無視され、既存のオブジェクトを上書きできます。
x-oss-forbid-overwrite リクエストヘッダーを設定すると、QPS 処理パフォーマンスに影響します。x-oss-forbid-overwrite リクエストヘッダーを多数の操作 (QPS > 1000) で使用する場合は、ビジネス運用に影響を与えないようにテクニカルサポートにご連絡ください。 デフォルト値：false |
x-oss-server-side-encryption | String | いいえ | AES256 | オブジェクト作成時に使用するサーバー側暗号化メソッドを指定します。 有効な値：AES256、KMS このヘッダーを指定すると、レスポンスで返されます。OSS はアップロードされたオブジェクトを暗号化します。オブジェクトをダウンロードすると、レスポンスには x-oss-server-side-encryption ヘッダーが含まれ、その値はオブジェクトの暗号化アルゴリズムに設定されます。 |
x-oss-server-side-encryption-key-id | String | いいえ | 9468da86-3509-4f8d-a61e-6eab1eac**** | KMS によって管理されるカスタマーマスターキー (CMK) の ID。 このヘッダーは、x-oss-server-side-encryption が KMS に設定されている場合にのみ有効です。 |
x-oss-object-acl | String | いいえ | default | オブジェクト作成時のアクセス制御リスト (ACL) を指定します。 有効な値：
ACL の詳細については、「オブジェクト ACL」をご参照ください。 |
x-oss-storage-class | String | いいえ | Standard | オブジェクトのストレージクラスを指定します。 どのストレージクラスのバケットでも、オブジェクトのアップロード時にこのヘッダーを指定すると、オブジェクトは指定されたストレージクラスに保存されます。たとえば、低頻度アクセス (IA) バケットにオブジェクトをアップロードするときに x-oss-storage-class を Standard に設定すると、オブジェクトは標準オブジェクトとして保存されます。 有効な値：
詳細については、「ストレージクラス」をご参照ください。 |
x-oss-meta-* | String | いいえ | x-oss-meta-location | PutObject 操作を呼び出すとき、x-oss-meta- プレフィックスで始まるヘッダーはユーザー定義メタデータと見なされます。たとえば、 ユーザー定義メタデータは、ハイフン (-)、数字、および文字をサポートします。OSS は大文字を小文字に変換します。アンダースコア (_) を含む他の文字はサポートされていません。 |
x-oss-tagging | String | いいえ | TagA=A&TagB=B | オブジェクトに 1 つ以上のキーと値のタグを指定します。例： 説明 キーと値は URL エンコードする必要があります。キーは必須ですが、値はオプションです。たとえば、オブジェクトタグを |
x-oss-object-worm-mode | String | いいえ | COMPLIANCE | オブジェクトの保持ポリシーのモードを指定します。値は |
x-oss-object-worm-retain-until-date | String | いいえ | 2026-09-30T00:00:00.000Z | 保持ポリシーの有効期限を指定します。日付は ISO 8601 形式である必要があります。このヘッダーは、ObjectWorm が有効になっているバケットに対してのみ有効です。指定された有効期限より前は、オブジェクトを削除または上書きすることはできません。このヘッダーを指定しない場合、デフォルトのルールが設定されていれば、バケットのデフォルトの保持ルールがアップロードされたオブジェクトに適用されます。 |
レスポンスパラメーター
パラメーター | タイプ | 例 | 説明 |
Content-MD5 | String | 1B2M2Y8AsgTpgAmY7PhC**** | アップロードされたオブジェクトの MD5 ハッシュ。 重要 これはアップロードされたオブジェクトの MD5 ハッシュであり、レスポンスボディの MD5 ハッシュではありません。 |
x-oss-hash-crc64ecma | String | 316181249502703**** | アップロードされたオブジェクトの CRC-64 ハッシュ。 |
x-oss-version-id | String | CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** | アップロードされたオブジェクトのバージョン ID。OSS は、バケットでバージョン管理が有効になっている場合にのみこのヘッダーを返します。 |
共通レスポンスヘッダーの詳細については、「共通レスポンスヘッダー」をご参照ください。
例
シンプルなアップロード
リクエスト
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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-zhangjiakou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 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
ストレージクラスの設定
リクエスト
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-Disposition: attachment;filename=oss_download.jpg Date: Fri, 24 Feb 2012 06:03:28 GMT Content-Type: image/jpeg Content-Length: 344606 x-oss-storage-class: Archive Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e [344606 bytes of object data]レスポンス
HTTP/1.1 200 OK Server: AliyunOSS Date: Sat, 21 Nov 2015 18:52:34 GMT Content-Type: image/jpeg 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218eレスポンス
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****"
エラーコード
エラーコード | HTTP ステータスコード | 説明 |
MissingContentLength | 411 | リクエストがチャンクエンコーディングを使用していないか、Content-Length パラメーターが設定されていません。 |
InvalidEncryptionAlgorithmError | 400 | x-oss-server-side-encryption に指定された値が無効です。 有効な値：AES256、KMS。 |
AccessDenied | 403 | オブジェクトのアップロード時に、指定されたバケットにアクセスするために必要な権限がありません。 |
NoSuchBucket | 404 | オブジェクトのアップロード時に、指定されたバケットが存在しません。 |
InvalidObjectName | 400 | オブジェクト名が無効です。オブジェクト名が指定されていない、長さ制限を超えている、または無効である可能性があります。 |
InvalidArgument | 400 | 考えられる原因：
|
RequestTimeout | 400 | Content-Length が指定されていますが、メッセージ本文が送信されていないか、送信されたメッセージ本文が指定されたサイズより小さいです。この場合、サーバーはリクエストがタイムアウトするまで待機します。 |
Bad Request | 400 | リクエストで Content-MD5 を指定した場合、OSS は送信されたデータの MD5 ハッシュを計算し、リクエストの Content-MD5 の値と比較します。2 つの値が一致しない場合、このエラーが返されます。 |
KmsServiceNotEnabled | 403 | x-oss-server-side-encryption に KMS を指定しましたが、KMS スイートを購入していません。 |
FileAlreadyExists | 409 | このエラーの考えられる理由は次のとおりです：
|
FileImmutable | 409 | 保持ポリシーで保護されているオブジェクトを変更しようとすると、OSS はこのエラーを返します。 |
統合メソッド
よくある質問
オブジェクトのメタデータの変更方法
OSS コンソール、ossbrowser、各種言語の SDK、ossutil コマンドラインツール、または REST API を使用して、オブジェクトのメタデータを変更できます。たとえば、Content-Type を application/octet-stream から image/jpeg に変更できます。詳細については、「オブジェクトのメタデータの管理」をご参照ください。
Expires ヘッダーが機能しない理由
キャッシュヘッダーの優先度
ExpiresとCache-Controlの両方を設定した場合、Cache-Controlが優先されます。Cache-Controlにmax-age=3600などのキャッシュディレクティブが含まれている場合、Expiresヘッダーは無視されることがあります。Expiresが正しく設定されていないExpiresヘッダーには、GMT 形式の未来の時間を値として指定する必要があります。次のコードは、Node.js SDK を使用してこのヘッダーを設定する方法の例です：const OSS = require('ali-oss'); // OSS クライアントインスタンスを作成します。 const client = new OSS({ // yourregion をバケットが配置されているリージョンに置き換えます。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。 region: 'yourregion', // 環境変数からアクセス認証情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。 accessKeyId: process.env.OSS_ACCESS_KEY_ID, accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET, // バケット名を指定します。 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); } } // キャッシュされたコンテンツの絶対有効期限を設定します。 const expiresDate = new Date('2024-10-12T00:00:00.000Z'); setExpires('your-object-name', expiresDate);