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

使用上の注意

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

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

• oss:PutObject 権限は、マルチパートアップロードを実行するために必要です。 詳細については、「RAM ポリシーの一般的な例」をご参照ください。

手順

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

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

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

2. パーツをアップロードします。

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

   説明

   • マルチパートアップロードタスクでは、フラグメント番号を使用して、オブジェクト内のパーツの相対位置を識別します。 既存のパーツと同じフラグメント番号を持つパーツをアップロードすると、既存のパーツはアップロードされたパーツによって上書きされます。

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

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

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

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

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

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

using Aliyun.OSS;
using Aliyun.OSS.Common;

// バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを 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";
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
const string region = "cn-hangzhou";

// ClientConfiguration インスタンスを作成し、要件に基づいてデフォルトパラメータを変更します。
var conf = new ClientConfiguration();

// 署名アルゴリズム V4 を使用します。
conf.SignatureVersion = SignatureVersion.V4;

// OSSClient インスタンスを作成します。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);

// マルチパートアップロードタスクを開始し、応答でアップロード ID を取得します。
var uploadId = "";
try
{
    // アップロードされたオブジェクトの名前とオブジェクトのバケットを指定します。 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);
}
catch (Exception ex)
{
    Console.WriteLine("Init multi part upload failed, {0}", ex.Message);
    Environment.Exit(1);
}
// パーツの総数を計算します。
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 を受信した後、すべてのパーツを 1 つずつ検証します。すべてのパーツが検証されると、OSS はこれらのパーツを完全なオブジェクトに結合します。
var partETags = new List<PartETag>();
try
{
    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");
    }
}
catch (Exception ex)
{
    Console.WriteLine("Put multi part upload failed, {0}", ex.Message);
    Environment.Exit(1);
}
// パーツがアップロードされた後、パーツを結合します。
try
{
    var completeMultipartUploadRequest = new CompleteMultipartUploadRequest(bucketName, objectName, uploadId);
    foreach (var partETag in partETags)
    {
        completeMultipartUploadRequest.PartETags.Add(partETag);
    }
    var result = client.CompleteMultipartUpload(completeMultipartUploadRequest);
    Console.WriteLine("complete multi part succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("complete multi part failed, {0}", ex.Message);
    Environment.Exit(1);
}

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

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

アップロードされたパーツを一覧表示するコード例を以下に示します。

using Aliyun.OSS;
using Aliyun.OSS.Common;

// バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを 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 を指定します。アップロード ID は、InitiateMultipartUpload 操作への応答から取得できます。
var uploadId = "yourUploadId";
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
const string region = "cn-hangzhou";

// ClientConfiguration インスタンスを作成し、要件に基づいてデフォルトパラメータを変更します。
var conf = new ClientConfiguration();

// 署名アルゴリズム V4 を使用します。
conf.SignatureVersion = SignatureVersion.V4;

// OSSClient インスタンスを作成します。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
// マルチパートアップロードタスクを開始します。
try
{
    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);
}
catch (Exception ex)
{
    Console.WriteLine("Init multi part upload failed, {0}", ex.Message);
}
// マルチパートアップロードタスクをキャンセルします。
try
{
    var request = new AbortMultipartUploadRequest(bucketName, objectName, uploadId);
    client.AbortMultipartUpload(request);
    Console.WriteLine("Abort multi part succeeded, {0}", uploadId);
}
catch (Exception ex)
{
    Console.WriteLine("Abort multi part failed, {0}", ex.Message);
}

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

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

using Aliyun.OSS;
using Aliyun.OSS.Common;

// バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを 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 を指定します。アップロード ID は、InitiateMultipartUpload 操作への応答から取得できます。 CompleteMultipartUpload 操作を呼び出してマルチパートアップロードタスクを完了する前に、アップロード ID を取得する必要があります。
var uploadId = "yourUploadId";
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
const string region = "cn-hangzhou";

// ClientConfiguration インスタンスを作成し、要件に基づいてデフォルトパラメータを変更します。
var conf = new ClientConfiguration();

// 署名アルゴリズム V4 を使用します。
conf.SignatureVersion = SignatureVersion.V4;

// OSSClient インスタンスを作成します。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    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);
}
catch (Exception ex)
{
    Console.WriteLine("List parts failed, {0}", ex.Message);
}

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

ossClient.listMultipartUploads メソッドを呼び出して、進行中のすべてのマルチパートアップロードタスク (開始済みであるが、完了またはキャンセルされていないタスク) を一覧表示できます。次の表は、進行中のすべてのマルチパートアップロードタスクを一覧表示するときに構成できるパラメータについて説明しています。

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

using Aliyun.OSS;
using Aliyun.OSS.Common;

// バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを 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";

// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
const string region = "cn-hangzhou";

// ClientConfiguration インスタンスを作成し、要件に基づいてデフォルトパラメータを変更します。
var conf = new ClientConfiguration();

// 署名アルゴリズム V4 を使用します。
conf.SignatureVersion = SignatureVersion.V4;

// OSSClient インスタンスを作成します。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    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);
}
catch (Exception ex)
{
    Console.WriteLine("List multi part uploads failed, {0}", ex.Message);
}

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

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

using Aliyun.OSS;
using Aliyun.OSS.Common;

// バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを 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;
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
const string region = "cn-hangzhou";

// ClientConfiguration インスタンスを作成し、要件に基づいてデフォルトパラメータを変更します。
var conf = new ClientConfiguration();

// 署名アルゴリズム V4 を使用します。
conf.SignatureVersion = SignatureVersion.V4;

// OSSClient インスタンスを作成します。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    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);
}
catch (Exception ex)
{
    Console.WriteLine("List multi part uploads failed, {0}", ex.Message);
}

関連情報

• マルチパートアップロードを実行するために使用される完全なサンプルコードについては、GitHub にアクセスしてください。

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

  • InitiateMultipartUpload

  • UploadPart

  • CompleteMultipartUpload

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

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

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