すべてのプロダクト
Search

このプロダクト

    Object Storage Service:AppendObject

    ドキュメントセンター

    Object Storage Service:AppendObject

    最終更新日:Jun 03, 2025

    既存のオブジェクトにオブジェクトを追加することで、オブジェクトをアップロードします。 AppendObject 操作を呼び出すことによって作成されたオブジェクトは、追加可能なオブジェクトです。 PutObject 操作を呼び出すことによってアップロードされたオブジェクトは、通常のオブジェクトです。

    バージョン管理

    バージョン管理が有効または一時停止されているバケット内の追加可能なオブジェクトに対して AppendObject 操作を呼び出す場合は、次の点に注意してください。

    • 現在のバージョンが追加可能なオブジェクトであるオブジェクトに対してのみ、AppendObject 操作を呼び出すことができます。 この操作を呼び出すと、Object Storage Service (OSS) は追加可能なオブジェクトの以前のバージョンを生成しません。

      現在のバージョンが追加可能なオブジェクトであるオブジェクトに対して PutObject または DeleteObject 操作を呼び出すと、OSS は追加可能なオブジェクトを以前のバージョンとして保存します。 ただし、追加可能なオブジェクトにコンテンツを追加することはできません。

    • 追加可能なオブジェクトに対してのみ AppendObject 操作を呼び出すことができます。 通常のオブジェクトや削除マーカーなど、他のタイプのオブジェクトに対して AppendObject 操作を呼び出すことはできません。

    制限

    • AppendObject 操作を使用して生成されるオブジェクトの最大サイズは 5 GB です。

    • 保持ポリシーによって保護されているオブジェクトに対しては、AppendObject 操作を呼び出すことはできません。 詳細については、「保持ポリシー」をご参照ください。

    • OSS サーバーに保存されている追加可能なオブジェクトは、特定のカスタマーマスターキー (CMK) ID を使用して暗号化することはできません。

    権限

    デフォルトでは、Alibaba Cloud アカウントはすべての権限を持っています。 RAM ユーザーまたは Alibaba Cloud アカウント下の RAM ロールは、デフォルトでは権限を持っていません。 Alibaba Cloud アカウントまたはアカウント管理者は、RAM ポリシーまたは バケットポリシーを通じて操作権限を付与する必要があります。

    API

    アクション

    定義

    AppendObject

    oss:PutObject

    この操作を呼び出して、既存のオブジェクトにオブジェクトを追加することでアップロードできます。

    oss:PutObjectTagging

    既存のオブジェクトにオブジェクトを追加してアップロードする際に、x-oss-tagging を介してオブジェクトタグを指定する場合、この権限が必要です。

    リクエスト構造

    POST /ObjectName?append&position=Position HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    リクエストヘッダー

    ヘッダー

    タイプ

    必須

    例

    説明

    Cache-control

    文字列

    いいえ

    no-cache

    オブジェクトのウェブページキャッシュ動作。 詳細については、RFC 2616 をご覧ください。

    デフォルトでは、このパラメーターは空のままです。

    Content-Disposition

    文字列

    いいえ

    attachment;filename=oss_download.jpg

    オブジェクトがダウンロードされるときのオブジェクトの名前。 詳細については、RFC 2616 をご覧ください。

    デフォルトでは、このパラメーターは空のままです。

    Content-MD5

    文字列

    いいえ

    ohhnqLBJFiKkPSBO1eNaUA==

    MD5 アルゴリズムを使用して計算された MD5 ハッシュ。 このヘッダーは、受信したメッセージのコンテンツが送信されたメッセージのコンテンツと同じであるかどうかを確認するために使用されます。

    Content-MD5 ヘッダーの値を取得するには、ヘッダーを除くメッセージコンテンツに基づいて 128 ビットの数を計算し、その数を Base64 エンコードします。

    デフォルトでは、このパラメーターは空のままです。

    制限: なし。

    Expires

    GMT

    いいえ

    Wed, 08 Jul 2015 16:57:01 GMT

    有効期限。 詳細については、RFC 2616 をご覧ください。

    デフォルトでは、このパラメーターは空のままです。

    x-oss-server-side-encryption

    文字列

    いいえ

    AES256

    OSS サーバーでオブジェクトを暗号化するために使用されるメソッド。

    有効な値:

    • AES256: OSS によって管理されるキーが暗号化と復号に使用されます (SSE-OSS)。

    • KMS: Key Management Service (KMS) によって管理される CMK が暗号化と復号に使用されます。

    x-oss-object-acl

    文字列

    いいえ

    private

    オブジェクトのアクセス制御リスト (ACL)。

    有効な値:

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

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

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

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

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

    x-oss-storage-class

    文字列

    いいえ

    Standard

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

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

    有効な値:

    • Standard

    • IA

    • Archive

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

    重要

    • このヘッダーは、オブジェクトに対して AppendObject 操作を初めて呼び出したときにのみ有効になります。

    • 追加可能なオブジェクトのストレージタイプをコールドアーカイブまたはディープコールドアーカイブに変換することはできません。

    x-oss-meta-*

    文字列

    いいえ

    x-oss-meta-location

    追加可能なオブジェクトを作成するときに AppendObject リクエストに追加できるパラメーター。 パラメーターには、x-oss-meta- プレフィックスが含まれている必要があります。 これらのパラメーターは、既存の追加可能なオブジェクトにオブジェクトを追加するときのリクエストには含めることができません。 x-oss-meta-* プレフィックスを含むパラメーターは、オブジェクトのメタデータと見なされます。

    オブジェクトに対して x-oss-meta- プレフィックスを含む複数のパラメーターを指定できます。 メタデータの合計サイズは 8 KB を超えることはできません。

    x-oss-meta- プレフィックスを含むパラメーターの名前には、ハイフン (-)、数字、および文字を含めることができます。 大文字は小文字に変換されます。 アンダースコア (_) などの他の文字はサポートされていません。

    x-oss-tagging

    文字列

    いいえ

    TagA=A

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

    重要

    • このヘッダーは、オブジェクトに対して AppendObject 操作を初めて呼び出したときにのみ有効になります。

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

    AppendObject リクエストに含まれる共通のリクエストヘッダーの詳細については、「共通のリクエストヘッダー」をご参照ください。

    リクエストのパラメーター

    重要

    append パラメーターと position パラメーターはどちらも 正規化リソースであり、AppendObject リクエストの署名に含める必要があります。

    パラメーター

    タイプ

    必須

    例

    説明

    append

    文字列

    はい

    該当なし

    リクエストが AppendObject リクエストであることを指定します。 オブジェクトに対して AppendObject 操作が呼び出されるたびに、オブジェクトが最後に変更された時刻が更新されます。

    position

    文字列

    はい

    0

    AppendObject 操作が開始される位置。 AppendObject 操作が成功するたびに、レスポンスに x-oss-next-append-position ヘッダーが含まれ、次の AppendObject 操作が開始される位置が指定されます。

    オブジェクトに対して呼び出される最初の AppendObject 操作の position ヘッダーの値は 0 である必要があります。 オブジェクトに対して呼び出される後続の AppendObject 操作の position ヘッダーの値は、オブジェクトの現在の長さです。 たとえば、最初の AppendObject リクエストで指定された position ヘッダーの値が 0 で、Content-Length の値が 65536 の場合、2 番目の AppendObject リクエストの position ヘッダーの値は 65536 に設定する必要があります。

    • AppendObject リクエストの position ヘッダーの値が 0 で、追加可能なオブジェクトと同じ名前のオブジェクトが存在しない場合、PutObject リクエストと同じ方法で、AppendObject リクエストに x-oss-server-side-encryption などのヘッダーを指定できます。 AppendObject リクエストで x-oss-server-side-encryption ヘッダーに有効な値を指定すると、リクエストへのレスポンスに x-oss-server-side-encryption ヘッダーが含まれます。 メタデータを変更する場合は、CopyObject 操作を呼び出すことができます。

    • position ヘッダーの値が有効な AppendObject リクエストを呼び出して、サイズが 0 KB のオブジェクトを既存の追加可能なオブジェクトに追加する場合、追加可能なオブジェクトの状態は変更されません。

    レスポンスヘッダー

    ヘッダー

    タイプ

    例

    説明

    x-oss-next-append-position

    64 ビット整数

    1717

    次の追加操作が開始される位置。これはオブジェクトの長さです。

    このヘッダーは、AppendObject リクエストが成功した場合、または position とオブジェクトの長さが一致しないために HTTP ステータスコード 409 が返された場合に返されます。

    x-oss-hash-crc64ecma

    64 ビット整数

    3231342946509354535

    オブジェクトの 64 ビット CRC 値。 この値は、ECMA-182 標準に基づいて計算されます。

    AppendObject リクエストへのレスポンスに含まれる共通のレスポンスヘッダーの詳細については、「共通のレスポンスヘッダー」をご参照ください。

    64 ビット CRC 値の計算方法

    追加可能なオブジェクトの CRC 値は、ECMA-182 標準に基づいて計算されます。 オブジェクトの 64 ビット CRC 値は、次のいずれかの方法で計算できます。

    • Boost CRC モジュールを使用する 

      typedef boost::crc_optimal<64, 0x42F0E1EBA9EA3693ULL, 0xffffffffffffffffULL, 0xffffffffffffffffULL, true, true> boost_ecma;
uint64_t do_boost_crc(const char* buffer, int length)
{
    boost_ecma crc;
    crc.process_bytes(buffer, length);
    return crc.checksum();
}

    • Python の crcmod 関数を使用する 

      do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693L, initCrc=0L, xorOut=0xffffffffffffffffL, rev=True)
print do_crc64("123456789")

    他の操作との関係

    操作

    関係

    PutObject

    既存の追加可能なオブジェクトに対して PutObject 操作を呼び出すと、追加可能なオブジェクトは通常のオブジェクトに変換されます。

    HeadObject

    既存の追加可能なオブジェクトに対して HeadObject 操作を呼び出すと、x-oss-next-append-position、x-oss-hash-crc64ecma、および x-oss-object-type ヘッダーが返されます。 追加可能なオブジェクトの x-oss-object-type 値は Appendable です。

    GetBucket(ListObjects)

    GetBucket リクエストへのレスポンスでは、追加可能なオブジェクトの x-oss-object-type 値は Appendable です。

    例

    • リクエスト例 

      POST /oss.jpg?append&position=0 HTTP/1.1 
Host: oss-example.oss.aliyuncs.com 
Cache-control: no-cache 
Expires: Wed, 08 Jul 2015 16:57:01 GMT 
x-oss-storage-class: Archive
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Wed, 08 Jul 2015 06:57:01 GMT 
Content-Type: image/jpg 
Content-Length: 1717 
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e  
[1717 バイトのオブジェクトデータ]

      成功レスポンスの例 

      HTTP/1.1 200 OK
Date: Wed, 08 Jul 2015 06:57:01 GMT
ETag: "0F7230CAA4BE94CCBDC99C550000****"
Connection: keep-alive
Content-Length: 0  
Server: AliyunOSS
x-oss-hash-crc64ecma: 14741617095266562575
x-oss-next-append-position: 1717
x-oss-request-id: 559CC9BDC755F95A6448****

    • バージョン管理されたバケットのリクエスト例

      バージョン管理が有効になっているバケット内のオブジェクトに対して AppendObject 操作を呼び出すと、レスポンスに x-oss-version-id ヘッダーが含まれ、その値はオブジェクトの現在のバージョン ID になります。 

      POST /example?append&position=0 HTTP/1.1 
Host: versioning-append.oss.aliyuncs.com 
Date: Tue, 09 Apr 2019 03:59:33 GMT
Content-Length: 3
Content-Type: application/octet-stream
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      成功レスポンスの例 

      HTTP/1.1 200 OK
Date: Tue, 09 Apr 2019 03:59:33 GMT
ETag: "2776271A4A09D82CA518AC5C0000****"
Connection: keep-alive
Content-Length: 0  
Server: AliyunOSS
x-oss-version-id: CAEQGhiBgIC_k6aV5RgiIGI3YTY2ZmMzYWJlMzQ3YjM4YTljOTk5YjUyZGF****
x-oss-hash-crc64ecma: 3231342946509354535
x-oss-next-append-position: 47
x-oss-request-id: 5CAC18A5B7AEADE01700****

    SDK

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

    ossutil

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

    エラーコード

    エラーコード

    HTTP ステータスコード

    説明

    ObjectNotAppendable

    409

    追加可能ではないオブジェクトに対して AppendObject 操作を呼び出しました。

    PositionNotEqualToLength

    409

    • position ヘッダーの値が現在のオブジェクトの長さと一致しません。

      現在のリクエストへのレスポンスの x-oss-next-append-position ヘッダーの値に基づいて、次の AppendObject 操作が開始される位置を取得できます。 複数のリクエストが同時に送信される場合があります。 そのため、x-oss-next-append-position ヘッダーの値をリクエストの position ヘッダーの値に設定しても、値はすぐに更新されないため、リクエストは失敗する可能性があります。

    • position ヘッダーの値が 0 で、同じ名前の追加可能なオブジェクトの長さが 0 であるか、同じ名前の追加可能なオブジェクトが存在しない場合、リクエストは成功します。 それ以外の場合、このエラーコードは、position とオブジェクトの長さが一致しないために返されます。

    InvalidArgument

    400

    x-oss-storage-class や x-oss-object-acl などのパラメーターの値が無効です。

    FileImmutable

    409

    削除または変更しようとしているデータは、保持ポリシーによって保護されています。

    KmsServiceNotEnabled

    403

    サーバー側の暗号化方法として KMS が指定されていますが、コンソールで KMS がアクティブ化されていません。