PutObject API を使用して、ファイルを 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 を超えるファイルをアップロードするには、マルチパートアップロード機能を使用します。
既存のファイルと同じ名前のファイルをアップロードすると、デフォルトで既存のファイルが上書きされ、200 OK ステータスコードが返されます。重要なファイルが誤って上書きされるのを防ぐために、上書きを禁止するパラメーターを設定できます。
OSS はフラットなストレージ構造を使用しており、従来のファイルシステムのようなディレクトリはありません。スラッシュ (/) で終わる空のオブジェクトを作成することで、フォルダ構造をシミュレートできます。
権限
バージョン管理
リクエストパラメーター
OSS は、Cache-Control、Expires、Content-Encoding、Content-Disposition、Content-Type などの標準 HTTP リクエストヘッダーをサポートしています。これらのリクエストヘッダーを設定すると、ファイルのダウンロード時にその値が自動的に適用されます。
パラメーター | タイプ | 必須 | 例 | 説明 |
Authorization | String | いいえ | OSS qn6q**************:77Dv**************** | リクエストが認証および承認されたことを示します。Authorization 値の計算方法の詳細については、「ヘッダーに署名を含める」をご参照ください。 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 を使用して 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 パフォーマンスに影響します。多くの操作 (QPS>1000) で x-oss-forbid-overwrite リクエストヘッダーが必要な場合は、ビジネス運用への影響を防ぐためにテクニカルサポートにご連絡ください。 デフォルト値：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 | OSS で作成されるときのオブジェクトのアクセス権限を指定します。 有効な値：
アクセス権限の詳細については、「オブジェクト ACL」をご参照ください。 |
x-oss-storage-class | String | いいえ | Standard | オブジェクトのストレージクラスを指定します。 どのストレージクラスのバケットでも、オブジェクトをアップロードするときにこのパラメーターを指定すると、オブジェクトは指定されたクラスに格納されます。たとえば、低頻度アクセス (IA) バケットにオブジェクトをアップロードするときに x-oss-storage-class を Standard に設定すると、オブジェクトは標準オブジェクトとして格納されます。 有効な値：
詳細については、「ストレージクラス」をご参照ください。 |
x-oss-meta-* | String | いいえ | x-oss-meta-location | PutObject API を使用する場合、x-oss-meta- で始まるパラメーターは、 メタデータは、ハイフン (-)、数字、および小文字 (a-z) をサポートします。大文字は小文字に変換されます。アンダースコア (_) を含む他の文字はサポートされていません。 |
x-oss-tagging | String | いいえ | TagA=A&TagB=B | オブジェクトのタグをキーと値のペア形式で指定します。複数のタグを同時に設定できます。例： 説明 キーと値は URL エンコードする必要があります。キーは必須ですが、値はオプションです。たとえば、オブジェクトタグを |
詳細については、「共通のレスポンスヘッダー」をご参照ください。
レスポンスパラメーター
パラメーター | タイプ | 例 | 説明 |
Content-MD5 | String | 1B2M2Y8AsgTpgAmY7PhC**** | アップロードされたファイルの MD5 ハッシュ。 重要 MD5 ハッシュは、クライアントがアップロードを完了した後に取得されたファイルのハッシュであり、レスポンス本文の MD5 ハッシュではありません。 |
x-oss-hash-crc64ecma | String | 316181249502703**** | アップロードされたファイルの CRC-64 値。 |
x-oss-version-id | String | CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** | ファイルのバージョン ID。このレスポンスヘッダーは、バージョン管理が有効になっているバケットにファイルがアップロードされた場合にのみ返されます。 |
詳細については、「共通のレスポンスヘッダー」をご参照ください。
例
単純アップロード
リクエスト例
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-hangzhou/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/jpg 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/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: 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 コンソール、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);