すべてのプロダクト
Search
ドキュメントセンター

Object Storage Service:マルチパートアップロード

最終更新日:Feb 26, 2024

サイズが5 GBを超える大きなオブジェクトをobject Storage Service (OSS) にアップロードすると、ネットワークの中断やプログラムのクラッシュにより、オブジェクトのアップロードに失敗することがあります。 複数回の再試行後にオブジェクトのアップロードに失敗した場合は、マルチパートアップロードを実行してラージオブジェクトをアップロードできます。 オブジェクトを複数のパーツに分割し、パーツを並行してアップロードすると、アップロードを高速化できます。 すべてのパーツがアップロードされたら、CompleteMultipartUpload操作を呼び出して、これらのパーツを完全なオブジェクトに結合できます。

使用上の注意

  • このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用します。 OSSと同じリージョンにある他のAlibaba CloudサービスからOSSにアクセスする場合は、内部エンドポイントを使用します。 OSSリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。

  • このトピックでは、アクセス資格情報は環境変数から取得します。 アクセス資格情報の設定方法の詳細については、「アクセス資格情報の設定」をご参照ください。

  • このトピックでは、OSSエンドポイントを使用してOSSClientインスタンスを作成します。 カスタムドメイン名またはSTS (Security Token Service) を使用してOSSClientインスタンスを作成する場合は、「初期化」をご参照ください。

  • マルチパートアップロードを実行するには、oss:PutObject権限が必要です。 詳細については、「RAMユーザーへのカスタムポリシーのアタッチ」をご参照ください。

処理中

マルチパートアップロードを実装するには、次の手順を実行します。

  1. マルチパートアップロードタスクを開始します。

    OSSで一意のアップロードIDを取得するには、bucket.init_multipart_uploadメソッドを使用します。

  2. パーツをアップロード

    bucket.upload_partメソッドを使用してパーツをアップロードします。

    説明
    • マルチパートアップロードタスクでは、部品番号を使用して、オブジェクト内の部品の相対位置を識別します。 部品をアップロードし、その部品番号を使用して別の部品をアップロードすると、後者の部品が前者の部品を上書きします。

    • OSSは、レスポンスのETagヘッダーにアップロードされた各パーツのMD5ハッシュを含めます。

    • OSSはアップロードされたパーツのMD5ハッシュを計算し、そのMD5ハッシュをOSS SDK for Goによって計算されたMD5ハッシュと比較します。 2つのハッシュが異なる場合、OSSはInvalidDigestエラーコードを返します。

  3. マルチパートアップロードタスクを完了します。

    すべてのパーツをアップロードしたら、e bucket.com plete_multipart_uploadメソッドを使用して、パーツを完全なオブジェクトに結合します。

すべてのパーツがアップロードされたら、次のいずれかの方法を使用して、すべてのパーツを完全なオブジェクトに結合できます。

  • 要求本文に部品情報を含めて、すべての部品を完全なオブジェクトに結合する

    # -*-コーディング: utf-8 -*-
    osのインポート
    oss2インポートSizedFileAdapterから、determine_part_size
    oss2.modelsからPartInfoをインポート
    oss2のインポート
    oss2.credentialsからEnvironmentVariableCredentialsProviderをインポート
    
    # 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。 
    # バケットの名前を指定します。 例: examplebucket. 
    bucket = oss2.Bucket(auth, 'https:// oss-cn-hangzhou.aliyuncs.com ', 'examplebucket')
    # オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 例: exampledir/exampleobject.txt。 
    key = 'exampledir/exampleobject.txt'
    # アップロードするローカルファイルのフルパスを指定します。 例: D :\\ localpath\\examplefile.txt。 
    filename = 'D :\\ localpath\\examplefile.txt'
    
    total_size = os.path.getsize (ファイル名)
    # determine_part_sizeメソッドを使用して、部品サイズを決定します。 
    part_size = determine_part_size(total_size, preferred_size=100*1024)
    
    # マルチパートアップロードタスクを開始します。 
    # マルチパートアップロードタスクを開始するときにオブジェクトのストレージクラスを指定する場合は、init_multipart_uploadメソッドを使用するときに関連するヘッダーを設定します。 
    # headers = dict()
    # オブジェクトのwebページのキャッシュ動作を指定します。 
    # headers['Cache-Control '] = 'no-cache'
    # ダウンロード時のオブジェクトの名前を指定します。 
    # headers['Content-Disposition'] = 'oss_MultipartUpload.txt'
    # オブジェクトのコンテンツエンコーディング形式を指定します。 
    # headers['Content-Encoding'] = 'utf-8'
    # 有効期間を指定します。 単位:ミリ秒。 
    # headers['Expires'] = '1000'
    # マルチパートアップロードタスクの開始時に、マルチパートアップロードを実行してアップロードされたオブジェクトが、同じ名前の既存のオブジェクトを上書きするかどうかを指定します。 この例では、このパラメーターはtrueに設定されています。これは、同じ名前のオブジェクトを上書きできないことを示します。 
    # headers['x-oss-forbid-overwrite'] = 'true'
    # 各パーツの暗号化に使用するサーバー側の暗号化方法を指定します。 
    # headers[OSS_SERVER_SIDE_ENCRYPTION] = SERVER_SIDE_ENCRYPTION_KMS
    # オブジェクトの暗号化に使用するアルゴリズムを指定します。 このパラメーターを設定しない場合、オブジェクトはAES-256を使用して暗号化されます。 
    # headers[OSS_SERVER_SIDE_DATA_ENCRYPTION] = SERVER_SIDE_ENCRYPTION_KMS
    # Key Management Service (KMS) が管理するCustomer Master Key (CMK) のIDを指定します。 
    # headers[OSS_SERVER_SIDE_ENCRYPTION_KEY_ID] = '9468da86-3509-4f8d-a61e-6eab1eac ****'
    # オブジェクトのストレージクラスを指定します。 
    # headers['x-oss-storage-classs'] = oss2.BUCKET_STORAGE_CLASS_STANDARD
    # オブジェクトのタグを指定します。 オブジェクトに複数のタグを同時に指定できます。 
    # headers[OSS_OBJECT_TAGGING] = 'k1=v1&k2=v2&k3=v3'
    # upload_id = bucket.init_multipart_upload (キー、ヘッダー=ヘッダー) 。upload_id
    upload_id = bucket.init_multipart_upload(key).upload_id
    # マルチパートアップロードタスクをキャンセルするか、アップロードIDに基づいてアップロードされたパーツをリストします。 
    # アップロードIDに基づいてマルチパートアップロードタスクをキャンセルする場合は、InitiateMultipartUpload操作を呼び出してマルチパートアップロードタスクを開始した後にアップロードIDを取得します。 
    # アップロードIDに基づいてマルチパートアップロードタスクでアップロードされたパーツを一覧表示する場合は、InitiateMultipartUpload操作を呼び出してマルチパートアップロードタスクを開始した後、CompleteMultipartUpload操作を呼び出してマルチパートアップロードタスクを完了する前に、アップロードIDを取得します。 
    # print("UploadID:", upload_id)
    parts = []
    
    # パーツをアップロードします。 
    with open(filename, 'rb') as fileobj:
        part_number = 1
        offset = 0
        while offset < total_size:
            num_to_upload = min(part_size, total_size - offset)
            # SizedFileAdapter(fileobj, size) メソッドを使用して、新しいオブジェクトを生成し、追加操作の開始位置を再計算します。 
            result = bucket.upload_part(key, upload_id, part_number,
                                        SizedFileAdapter(fileobj, num_to_upload))
            parts.append(PartInfo(part_number, result.etag))
    
            offset += num_to_upload
            part_number += 1
    
    # マルチパートアップロードタスクを完了します。 
    # マルチパートアップロードタスクの完了時にヘッダーを設定します (必要な場合) 。 
    headers = dict()
    # オブジェクトのアクセス制御リスト (ACL) を指定します。 この例では、ACLはOBJECT_ACL_PRIVATEに設定され、オブジェクトのACLがプライベートであることを示します。 
    # headers["x-oss-object-acl"] = oss2.OBJECT_ACL_PRIVATE
    bucket.com plete_multipart_upload(key, upload_id, parts, headers=headers)
    # bucket.com plete_multipart_upload(key, upload_id, parts) 
    重要

    ネットワークの状態が安定している場合は、各パーツのサイズを大きくすることを推奨します。 それ以外の場合は、各パーツのサイズを小さくします。

  • サーバー上のパーツを一覧表示して、パーツを完全なオブジェクトに結合します。

    説明

    サーバーにパーツを一覧表示してパーツを完全なオブジェクトに結合する場合は、次のサンプルコードで指定されているアップロードIDを使用して、複数のパーツがアップロードされていることを確認してください。

    # -*-コーディング: utf-8 -*-
    oss2のインポート
    oss2.credentialsからEnvironmentVariableCredentialsProviderをインポート
    # 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。 
    # バケットの名前を指定します。 例: examplebucket. 
    bucket = oss2.Bucket(auth, 'https:// oss-cn-hangzhou.aliyuncs.com ', 'examplebucket')
    # オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 例: exampledir/exampleobject.txt。 
    key = 'exampledir/exampleobject.txt'
    # アップロードするローカルファイルのフルパスを指定します。 例: D :\\ localpath\\examplefile.txt。 
    filename = 'D :\\ localpath\\examplefile.txt'
    # アップロードIDを指定します。 InitiateMultipartUpload操作を呼び出してマルチパートアップロードタスクを開始した後、CompleteMultipartUpload操作を呼び出してマルチパートアップロードタスクを完了する前に、アップロードIDを取得できます。 
    upload_id = '0004B9894A22E5B1888A1E29F823 ****'
    
    # マルチパートアップロードタスクを完了します。 
    # マルチパートアップロードタスクの完了時にオブジェクトのACLを指定する場合は、complete_multipart_upload関数で関連ヘッダーを設定します。 
    headers = dict()
    # headers["x-oss-object-acl"] = oss2.OBJECT_ACL_PRIVATE
    # リクエストでx-oss-complete-all:yesを指定した場合、現在のアップロードIDを使用してアップロードされたすべてのパーツが一覧表示され、パーツ番号でパーツが並べ替えられ、CompleteMultipartUpload操作が実行されます。 
    # リクエストにx-oss-complete-all:yesを指定した場合、リクエスト本文は指定できません。 そうしないと、エラーが発生します。 
    ヘッダー ["x-oss-complete-all"] = 'yes'
    bucket.com plete_multipart_upload(key, upload_id, None, headers=headers) 

マルチパートアップロードタスクのキャンセル

bucket.abort_multipart_uploadメソッドを使用して、マルチパートアップロードタスクをキャンセルできます。 マルチパートアップロードタスクがキャンセルされた場合、アップロードIDを使用してパーツをアップロードすることはできません。 さらに、アップロードされたパーツは削除されます。

次のサンプルコードは、マルチパートアップロードタスクをキャンセルする方法の例を示しています。

# -*-コーディング: utf-8 -*-
osのインポート
oss2のインポート
oss2.credentialsからEnvironmentVariableCredentialsProviderをインポート

# 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。 
# バケットの名前を指定します。 例: examplebucket. 
bucket = oss2.Bucket(auth, 'https:// oss-cn-hangzhou.aliyuncs.com ', 'examplebucket')
# オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 例: exampledir/exampleobject.txt。 
key = 'exampledir/exampleobject.txt'
# アップロードIDを指定します。 InitiateMultipartUpload操作の応答からアップロードIDを取得できます。 
upload_id = 'yourUploadId'

# 指定したアップロードIDを持つマルチパートアップロードタスクをキャンセルします。 アップロードされたパーツは削除されます。 
bucket.abort_multipart_upload(key, upload_id) 

アップロードされたパーツの一覧表示

次のサンプルコードは、アップロードされたパーツを一覧表示する方法の例です。

# -*-コーディング: utf-8 -*-
osのインポート
oss2のインポート
oss2.credentialsからEnvironmentVariableCredentialsProviderをインポート

# 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。 
bucket = oss2.Bucket(auth, 'https:// oss-cn-hangzhou.aliyuncs.com ', 'yourBucketName')
# オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 例: exampledir/exampleobject.txt。 
key = 'exampledir/exampleobject.txt'
# アップロードIDを指定します。 InitiateMultipartUpload操作の応答からアップロードIDを取得できます。 CompleteMultipartUpload操作を呼び出してマルチパートアップロードタスクを完了する前に、アップロードIDを取得する必要があります。 
upload_id = 'yourUploadId'

# 指定されたアップロードIDを使用するアップロードされたパーツを一覧表示します。 
oss2.PartIteratorのpart_info (バケット、キー、upload_id) の場合:
    プリント ('part_number:', part_info.part_number)
    print('etag:'、part_info.etag)
    プリント ('size:'、part_info.size) 

マルチパートアップロードタスクの一覧表示

  • 特定のオブジェクトのマルチパートアップロードタスクの一覧表示

    次のサンプルコードは、特定のオブジェクトのマルチパートアップロードタスクを一覧表示する方法の例を示しています。

    # -*-コーディング: utf-8 -*-
    osのインポート
    oss2のインポート
    oss2.credentialsからEnvironmentVariableCredentialsProviderをインポート
    
    # 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。 
    # バケットの名前を指定します。 例: examplebucket. 
    bucket = oss2.Bucket(auth, 'https:// oss-cn-hangzhou.aliyuncs.com ', 'examplebucket')
    # オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 例: exampledir/exampleobject.txt。 
    key = 'exampledir/exampleobject.txt'
    
    # オブジェクトのすべてのマルチパートアップロードタスクを一覧表示します。 init_multipart_uploadメソッドが同じオブジェクトに使用されるたびに、異なるアップロードIDが返されます。 
    # アップロードIDは、マルチパートアップロードタスクを一意に識別します。 
    oss2.ObjectUploadIterator (バケット、キー) のupload_infoの場合:
        print('key:', upload_info.key)
        print('upload_id:', upload_info.upload_id) 
  • バケット内のすべてのマルチパートアップロードタスクを一覧表示する

    次のサンプルコードは、バケット内のすべてのマルチパートアップロードタスクを一覧表示する方法の例を示しています。

    # -*-コーディング: utf-8 -*-
    osのインポート
    oss2のインポート
    oss2.credentialsからEnvironmentVariableCredentialsProviderをインポート
    
    # Alibaba CloudアカウントのAccessKeyペアには、すべてのAPI操作に対する権限があります。 これらの資格情報を使用してOSSで操作を実行することは、リスクの高い操作です。 RAMユーザーを使用してAPI操作を呼び出したり、ルーチンのO&Mを実行することを推奨します。RAMユーザーを作成するには、RAMコンソールにログインします。 
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。 
    # バケットの名前を指定します。 例: examplebucket. 
    bucket = oss2.Bucket(auth, 'https:// oss-cn-hangzhou.aliyuncs.com ', 'examplebucket')
    
    # バケット内のすべてのマルチパートアップロードタスクを一覧表示します。 
    oss2.MultipartUploadIterator (バケット) のupload_infoの場合:
        print('key:', upload_info.key)
        print('upload_id:', upload_info.upload_id) 
  • バケット内の名前に特定のプレフィックスが含まれるオブジェクトのマルチパートアップロードタスクを一覧表示する

    次のサンプルコードは、名前に特定のプレフィックスが含まれているオブジェクトのマルチパートアップロードタスクをバケットに一覧表示する方法の例を示しています。

    # -*-コーディング: utf-8 -*-
    osのインポート
    oss2のインポート
    oss2.credentialsからEnvironmentVariableCredentialsProviderをインポート
    # Alibaba CloudアカウントのAccessKeyペアには、すべてのAPI操作に対する権限があります。 これらの資格情報を使用してOSSで操作を実行することは、リスクの高い操作です。 RAMユーザーを使用してAPI操作を呼び出したり、ルーチンのO&Mを実行することを推奨します。RAMユーザーを作成するには、RAMコンソールにログインします。 
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # この例では、中国 (杭州) リージョンのエンドポイントが使用されます。 実際のエンドポイントを指定します。 
    # バケットの名前を指定します。 例: examplebucket. 
    bucket = oss2.Bucket(auth, 'https:// oss-cn-hangzhou.aliyuncs.com ', 'examplebucket')
    
    # 名前にテストプレフィックスが含まれているオブジェクトのマルチパートアップロードタスクをバケットに一覧表示します。 
    oss2.MultipartUploadIterator (バケット、プレフィックス='test') のupload_infoの場合:
        print('key:', upload_info.key)
        print('upload_id:', upload_info.upload_id) 

よくある質問

パーツを削除するには?

    参考資料

    • マルチパートアップロードには3つのAPI操作が含まれます。 操作の詳細については、以下のトピックを参照してください。

    • マルチパートアップロードタスクをキャンセルするために呼び出すことができるAPI操作の詳細については、「AbortMultipartUpload」をご参照ください。

    • アップロードされたパーツを一覧表示するために呼び出すことができるAPI操作の詳細については、「ListParts」をご参照ください。

    • 実行中のすべてのマルチパートアップロードタスク (開始されたが完了していない、またはキャンセルされたタスク) を一覧表示するために呼び出すことができるAPI操作の詳細については、「ListMultipartUploads」をご参照ください。