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

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

最終更新日:Dec 19, 2023

Object Storage Service (OSS) は、マルチパートアップロード機能を提供します。 マルチパートアップロードを使用すると、大きなオブジェクトを複数のパートに分割してアップロードできます。 これらのパーツがアップロードされたら、CompleteMultipartUpload操作を呼び出して、パーツを完全なオブジェクトに結合できます。

使用上の注意

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

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

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

手順

マルチパートアップロードを使用してオブジェクトをアップロードするには、次の手順を実行します。

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

    InitiateMultipartUploadRequestメソッドを呼び出して、OSSで一意のアップロードIDを取得します。

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

    UploadPartRequestメソッドを呼び出して、パーツをアップロードします。

    説明
    • 特定のアップロードIDを持つマルチパートアップロードタスクによってパーツがアップロードされる場合、オブジェクト内のパーツの相対位置を識別するためにパーツ番号が使用されます。 既存の部品と同じ部品番号を持つ部品をアップロードすると、既存の部品はアップロードされた部品によって上書きされます。

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

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

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

    すべてのパーツがアップロードされたら、CompleteMultipartUploadRequestメソッドを呼び出して、パーツを完全なオブジェクトに結合します。

マルチパートアップロードのサンプルコード

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

Aliyun.OSSを使用した


// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。 
var endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// バケットの名前を指定します。 
var bucketName = "examplebucket";
// オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 
var objectName = "exampleobject.txt";
// アップロードするローカルファイルのフルパスを指定します。 デフォルトでは、ローカルファイルのフルパスを指定しない場合、サンプルプログラムが属するプロジェクトのパスからローカルファイルがアップロードされます。 
var localFilename = "D :\\ localpath\\examplefile.txt";
// OSSClientインスタンスを作成します。 
var client = new OssClient (エンドポイント、accessKeyId、accessKeySecret);

// マルチパートアップロードタスクを開始し、レスポンスでアップロードIDを取得します。 
var uploadId = "";
トライ
{
    // アップロードされたオブジェクトの名前とオブジェクトのバケットを指定します。 InitiateMultipartUploadRequestでオブジェクトメタデータを設定できます。 ただし、ContentLengthを指定する必要はありません。 
    var request = new InitiateMultipartUploadRequest(bucketName, objectName);
    var result = client.InitiateMultipartUpload(request);
    uploadId = result.UploadId;
    // アップロードIDを表示します。 
    Console.WriteLine("Init multi part upload succeeded");
    // マルチパートアップロードタスクをキャンセルするか、アップロードIDに基づいてアップロードされたパーツをリストします。 
    // アップロードIDに基づいてマルチパートアップロードタスクをキャンセルする場合は、InitiateMultipartUpload操作を呼び出してマルチパートアップロードタスクを開始した後にアップロードIDを取得します。  
    // アップロードIDに基づいてマルチパートアップロードタスクでアップロードされたパーツを一覧表示する場合は、InitiateMultipartUpload操作を呼び出してマルチパートアップロードタスクを開始した後、CompleteMultipartUpload操作を呼び出してマルチパートアップロードタスクを完了する前に、アップロードIDを取得します。 
    Console.WriteLine("Upload Id:{0}", result.UploadId);
}
キャッチ (例外ex)
{
    Console.WriteLine("Initマルチパートアップロードに失敗しました, {0}", 例: メッセージ);
}
// 部品の総数を計算します。 
var partSize = 100*1024;
var fi = new FileInfo(localFilename);
var fileSize = fi.Length;
var partCount = fileSize / partSize;
if (fileSize % partSize != 0)
{
    partCount ++;
}
// マルチパートアップロードタスクを開始します。 partETagsはPartETagsのリストです。 OSSがpartETagsを受信すると、OSSはすべてのパーツを1つずつ検証します。 すべての部品が検証された後、OSSはこれらの部品を完全なオブジェクトに結合します。 
var partETags = newリスト <PartETag>();
トライ
{
    using (var fs = File.Open(localFilename, FileMode.Open))
    {
        for (var i = 0; i < partCount; i++)
        {
            var skipBytes = (long)partSize * i;
            // 現在のアップロードタスクの開始位置を見つけます。 
            fs.Seek(skipBytes, 0);
            // このアップロードでパーツサイズを計算します。 最後のパーツのサイズは、オブジェクトが計算されたパーツサイズで分割された後の残りのサイズです。 
            var size = (partSize < fileSize - skipBytes) ? partSize : (fileSize - skipBytes);
            var request = new UploadPartRequest(bucketName, objectName, uploadId)
            {
                InputStream = fs,
                PartSize = size,
                PartNumber = i + 1
            };
            // UploadPartを呼び出してパーツをアップロードします。 返される結果には、部品のETag値が含まれます。 
            var result = client.UploadPart(request);
            partETags.Add(result.PartETag);
            Console.WriteLine("finish {0}/{1}", partETags.Count, partCount);
        }
        Console.WriteLine("Put multi part upload succeeded");
    }
}
キャッチ (例外ex)
{
    Console.WriteLine("Put multi part upload failed, {0}", ex.Message);
}
// マルチパートアップロードタスクを完了します。 
トライ
{
    var completeMultipartUploadRequest = new CompleteMultipartUploadRequest(bucketName, objectName, uploadId);
    foreach (var partETag in partETags)
    {
        completeMultipartUploadRequest.PartETags.Add(partETag);
    }
    var result = client.CompleteMultipartUpload(completeMultipartUploadRequest);
    Console.WriteLine("完全なマルチパート成功");
}
キャッチ (例外ex)
{
    Console.WriteLine("complete multi part failed, {0}", ex.Message);
} 

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

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

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

Aliyun.OSSを使用した


// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。 
var endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// バケットの名前を指定します。 
var bucketName = "examplebucket";
// オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 
var objectName = "exampleobject.txt";
// アップロードIDを指定します。 InitiateMultipartUpload操作の応答からアップロードIDを取得できます。 
var uploadId = "yourUploadId";

// OSSClientインスタンスを作成します。 
var client = new OssClient (エンドポイント、accessKeyId、accessKeySecret);
// マルチパートアップロードタスクを開始します。 
トライ
{
    var request = new InitiateMultipartUploadRequest(bucketName, objectName);
    var result = client.InitiateMultipartUpload(request);
    uploadId = result.UploadId;
    // アップロードIDを表示します。 
    Console.WriteLine("Init multi part upload succeeded");
    Console.WriteLine("Upload Id:{0}", result.UploadId);
}
キャッチ (例外ex)
{
    Console.WriteLine("Initマルチパートアップロードに失敗しました, {0}", 例: メッセージ);
}
// マルチパートアップロードタスクをキャンセルします。 
トライ
{
    var request = new AbortMultipartUploadRequest(bucketName, objectName, uploadId);
    client.AbortMultipartUpload(request);
    Console.WriteLine("Abort multi part successed, {0}", uploadId);
}
キャッチ (例外ex)
{
    Console.WriteLine (「マルチパートの中止に失敗しました。{0} 」、メッセージなど);
} 

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

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

Aliyun.OSSを使用した

// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。 
var endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// バケットの名前を指定します。 
var bucketName = "examplebucket";
// オブジェクトのフルパスを指定します。 バケット名をフルパスに含めないでください。 
var objectName = "exampleobject.txt";
// アップロードIDを指定します。 InitiateMultipartUpload操作の応答からアップロードIDを取得できます。 CompleteMultipartUpload操作を呼び出してマルチパートアップロードタスクを完了する前に、アップロードIDを取得する必要があります。 
var uploadId = "yourUploadId";

// OSSClientインスタンスを作成します。 
var client = new OssClient (エンドポイント、accessKeyId、accessKeySecret);
トライ
{
    PartListing listPartsResult = null;
    var nextMarker = 0;
    do 
    {
        var listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId) 
        {
            PartNumberMarker = nextMarker,
        };
        // アップロードしたパーツを一覧表示します。 
        listPartsResult = client.ListParts(listPartsRequest);
        Console.WriteLine("List parts succeeded");
        // アップロードされたすべてのパーツをトラバースします。 
        var parts = listPartsResult.Parts;
        foreach (var part in parts)
        {
            Console.WriteLine("partNumber: {0}, ETag: {1}, Size: {2}", part.PartNumber, part.ETag, part.Size);
        }
        nextMarker = listPartsResult.NextPartNumberMarker;
    } while (listPartsResult.IsTruncated);
}
キャッチ (例外ex)
{
    Console.WriteLine("List parts failed, {0}", ex.Message);
} 

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

ossClient.listMultipartUploadsメソッドを呼び出して、実行中のすべてのマルチパートアップロードタスクを一覧表示できます。 次の表に、進行中のすべてのマルチパートアップロードタスクを一覧表示するときに設定できるパラメーターを示します。

パラメーター

説明

メソッド

プレフィックス

返されるオブジェクトの名前に含める必要があるプレフィックス。 クエリにプレフィックスを使用する場合、返されるオブジェクト名にはプレフィックスが含まれます。

ListMultipartUploadsRequest.setPrefix(String prefix)

区切り文字

オブジェクト名のグループ化に使用される文字。 指定されたプレフィックスから区切り文字の最初の出現までの部分文字列を名前に含むオブジェクトは、単一の要素として返されます。

ListMultipartUploadsRequest.setDelimiter(String delimiter)

maxUploads

今回返すマルチパートアップロードタスクの最大数。 デフォルト値は 1000 です。 最大値は 1000 です。

ListMultipartUploadsRequest.setMaxUploads(Integer maxUploads)

keyMarker

リスト操作の開始位置。 keyMarkerの値の後に名前がアルファベット順に表示されているオブジェクトに対して開始されたすべての進行中のマルチパートアップロードタスク。 このパラメーターをuploadIdMarkerパラメーターと共に使用して、リスト操作の開始位置を指定できます。

ListMultipartUploadsRequest.setKeyMarker(String keyMarker)

uploadIdMarker

リスト操作の開始位置。 このパラメーターは、keyMarkerパラメーターと一緒に使用されます。 keyMarkerパラメーターを設定しない場合、uploadIdMarkerパラメーターは無効です。 keyMarkerパラメーターを設定すると、クエリ結果には次の項目が含まれます。

  • 名前がkeyMarkerの値よりアルファベット順に大きいすべてのオブジェクト

  • keyMarkerの値と同じオブジェクト名を持つすべてのマルチパートアップロードタスクと、uploadIdMarkerの値より大きいアップロードID。

ListMultipartUploadsRequest.setUploadIdMarker(String uploadIdMarker)

次のサンプルコードでは、単純なリストを使用してマルチパートアップロードタスクを一覧表示する方法の例を示します。

Aliyun.OSSを使用した

// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。 
var endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// バケットの名前を指定します。 
var bucketName = "examplebucket";

// OSSClientインスタンスを作成します。 
var client = new OssClient (エンドポイント、accessKeyId、accessKeySecret);
トライ
{
    MultipartUploadListing multipartUploadListing = null;
    var nextMarker = string.Empty;
    do
    {
        // マルチパートアップロードタスクを一覧表示します。 
        var request = new ListMultipartUploadsRequest(bucketName)
        {
            KeyMarker = nextMarker,
        };
        multipartUploadListing = client.ListMultipartUploads(request);
        Console.WriteLine("List multi part succeeded");
        // 各マルチパートアップロードタスクに関する情報を一覧表示します。 
        foreach (var mu in multipartUploadListing.MultipartUploads)
        {
            Console.WriteLine("Key: {0},  UploadId: {1}", mu.Key, mu.UploadId);
        }
        // 返された結果のisTruncatedフィールドの値がfalseの場合、nextKeyMarkerとnextUploadIdMarkerの値が返され、次の読み取りの開始点として使用されます。 
        nextMarker = multipartUploadListing.NextKeyMarker;
    } while (multipartUploadListing.IsTruncated);
}
キャッチ (例外ex)
{
    Console.WriteLine("List multi part uploads failed, {0}", ex.Message);
} 

プレフィックスと返すレコードの最大数を指定してマルチパートアップロードタスクを一覧表示する

次のコードでは、プレフィックスと返すレコードの最大数を指定して、マルチパートアップロードタスクを一覧表示する方法の例を示します。

Aliyun.OSSを使用した

// バケットが配置されているリージョンのエンドポイントを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントをhttps://oss-cn-hangzhou.aliyuncs.comに設定します。 
var endpoint = "yourEndpoint";
// 環境変数からアクセス資格情報を取得します。 サンプルコードを実行する前に、OSS_ACCESS_KEY_IDおよびOSS_ACCESS_KEY_SECRET環境変数が設定されていることを確認してください。 
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// バケットの名前を指定します。 
var bucketName = "examplebucket";

// プレフィックスを指定します。 
var prefix = "yourObjectPrefix";
// 返されるレコードの最大数を100として指定します。 
var maxUploads = 100;
// OSSClientインスタンスを作成します。 
var client = new OssClient (エンドポイント、accessKeyId、accessKeySecret);
トライ
{
    MultipartUploadListing multipartUploadListing = null;
    var nextMarker = string.Empty;
    do
    {
        // マルチパートアップロードタスクを一覧表示します。 デフォルトでは、1,000のマルチパートアップロードタスクが一覧表示されます。 
        var request = new ListMultipartUploadsRequest(bucketName)
        {
            KeyMarker = nextMarker,
            // 一覧表示するオブジェクトの名前に含まれるプレフィックスを指定します。 
            Prefix = prefix,
            // 返されるレコードの最大数を指定します。 
            MaxUploads = maxUploads,
        };
        multipartUploadListing = client.ListMultipartUploads(request);
        Console.WriteLine("List multi part succeeded");
        // 各マルチパートアップロードタスクに関する情報を一覧表示します。 
        foreach (var mu in multipartUploadListing.MultipartUploads)
        {
            Console.WriteLine("Key: {0},  UploadId: {1}", mu.Key, mu.UploadId);
        }
        nextMarker = multipartUploadListing.NextKeyMarker;
    } while (multipartUploadListing.IsTruncated);
}
キャッチ (例外ex)
{
    Console.WriteLine("List multi part uploads failed, {0}", ex.Message);
} 

参考資料

  • マルチパートアップロードの実行に使用する完全なサンプルコードについては、『GitHub』をご参照ください。

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

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

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

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