すべてのプロダクト
Search

このプロダクト

    Object Storage Service:オブジェクトのアップロード

    ドキュメントセンター

    Object Storage Service:オブジェクトのアップロード

    最終更新日:Apr 23, 2025

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

    注意事項

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

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

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

    バージョン管理

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

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

    権限

    デフォルトでは、Alibaba Cloud アカウントはアカウント内のリソースに対するフルアクセス権限を持っています。対照的に、RAM ユーザーと Alibaba Cloud アカウントに関連付けられた RAM ロールは、最初は権限を持っていません。RAM ユーザーまたはロールを使用してリソースを管理するには、RAM ポリシーまたは バケットポリシーを介して必要な権限を付与する必要があります。

    API

    アクション

    説明

    PutObject

    oss:PutObject

    オブジェクトをアップロードする権限を付与します。

    oss:PutObjectTagging

    オブジェクトをアップロードするときに、x-oss-tagging ヘッダーを使用してオブジェクトのタグを指定します。

    kms:GenerateDataKey

    オブジェクトをアップロードするときに、オブジェクトのメタデータに X-Oss-Server-Side-Encryption: KMS が含まれている場合、両方の操作の権限が必要です。

    kms:Decrypt

    リクエスト構文

    PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    リクエストヘッダー

    OSS は、Cache-Control、Expires、Content-Encoding、Content-Disposition、Content-Type などの HTTP リクエストヘッダーをサポートしています。オブジェクトをアップロードするときにこれらのヘッダーを指定すると、オブジェクトをダウンロードするときにヘッダーが自動的に指定された値に設定されます。

    ヘッダー

    タイプ

    必須

    例

    説明

    Authorization

    String

    いいえ

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

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

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

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

    Cache-Control

    String

    いいえ

    no-cache

    オブジェクトのダウンロード時の Web ページのキャッシュ動作。有効な値：

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

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

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

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

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

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

    Content-Disposition

    String

    いいえ

    attachment

    オブジェクトを表示するために使用されるメソッド。有効な値：

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

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

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

      yourFileName は、ダウンロードされたオブジェクトのカスタム名を指定します（例：example.jpg）。

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

    説明

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

    • オブジェクト名に日本語文字が含まれるオブジェクトのダウンロードで、ファイル名に文字化けしたローカルファイルが作成されるのを防ぐには、オブジェクト名に含まれる日本語文字を URL エンコードする必要があります。たとえば、OSS 内の Test.txt オブジェクトが元のオブジェクト名 Test.txt のローカルファイルとしてダウンロードされるようにするには、Content-Disposition ヘッダーを attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename*=UTF-8''%E6%B5%8B%E8%AF%95.txt に設定する必要があります。これは、"attachment;filename="+URLEncoder.encode("Test","UTF-8")+".txt;filename*=UTF-8''"+URLEncoder.encode("Test","UTF-8")+".txt" から派生しています。

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

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

    Content-Encoding

    String

    いいえ

    identity

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

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

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

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

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

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

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

    Content-MD5

    String

    いいえ

    eB5eJF1ptWaXm4bijSPyxw==

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

    データ整合性を確保するために、OSS はアップロードするオブジェクトの MD5 ハッシュをチェックするための複数のメソッドを提供しています。[Content-MD5] ヘッダーに基づいてアップロードするオブジェクトの MD5 ハッシュを確認するには、リクエストに [Content-MD5] ヘッダーを追加します。

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

    Content-Length

    String

    いいえ

    344606

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

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

    Expires

    String

    いいえ

    Wed, 08 Jul 2015 16:57:01 GMT

    有効期限。詳細については、RFC2616 をご参照ください。

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

    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 のクエリ/秒 (QPS) パフォーマンスが低下します。x-oss-forbid-overwrite ヘッダーを多数のリクエスト (QPS > 1,000) で構成する場合は、チケットを送信してください。

    デフォルト値: 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)。

    有効な値：

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

    • private: オブジェクトの ACL は非公開です。オブジェクトの所有者と承認されたユーザーのみが、オブジェクトに対する読み取りおよび書き込み権限を持っています。

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

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

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

    x-oss-storage-class

    String

    いいえ

    Standard

    オブジェクトのストレージタイプ。

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

    有効な値：

    • Standard

      説明

      クラウドボックスの OSS を使用する場合、Standard ストレージタイプのみがサポートされます。

    • IA

    • Archive

    • ColdArchive

    • DeepColdArchive

      重要

      多数のオブジェクトをアップロードし、オブジェクトのストレージタイプを Deep Cold Archive に設定する場合、高額な PUT リクエスト料金 が発生します。オブジェクトをアップロードするときにオブジェクトのストレージタイプを Standard に設定し、ライフサイクルルール を設定して Standard オブジェクトのストレージタイプを Deep Cold Archive に変換することをお勧めします。これにより、PUT リクエスト料金が削減されます。

    ストレージタイプの詳細については、「ストレージタイプ」をご参照ください。

    x-oss-meta-*

    String

    いいえ

    x-oss-meta-location

    オブジェクトのメタデータを指定します。x-oss-meta- パラメータを含むパラメータを設定すると、そのパラメータはメタデータを指定します。例: x-oss-meta-location。1 つのオブジェクトに複数のメタデータヘッダーを指定できます。ただし、オブジェクトのメタデータは 8 KB を超えることはできません。

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

    x-oss-tagging

    String

    いいえ

    TagA=A&TagB=B

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

    説明

    タグキーとタグ値は URL エンコードする必要があります。オブジェクトにタグを指定する場合、タグキーのみが必須で、タグ値はオプションです。例: TagA&TagB=B。

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

    レスポンスヘッダー

    ヘッダー

    タイプ

    例

    説明

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

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

    重要

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

    x-oss-hash-crc64ecma

    String

    316181249502703****

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

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

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

    Date や x-oss-request-id などの、PutObject リクエストへのレスポンスにおける一般的なレスポンスヘッダーの詳細については、「一般的な 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: 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

    • オブジェクトをアップロードし、オブジェクトのストレージタイプを 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-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=host,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,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****"

    OSS SDK

    PutObject 操作を呼び出すには、次のプログラミング言語の OSS SDK を使用できます。

    ossutil

    PutObject 操作に対応する ossutil コマンドについては、「put-object」をご参照ください。

    エラーコード

    エラーコード

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

    • Expires ヘッダーの無効な値

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

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

// OSS クライアントインスタンスを作成します。
const client = new OSS({
  // バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 ヘッダーが正常に設定されました。'); // 日本語コメント
  } catch (error) {
    console.error('Expires ヘッダーの設定エラー:', error); // 日本語コメント
  }
}

// キャッシュの絶対有効期限を指定します。
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);