Object Storage Service:Multipart upload (C# SDK V1)

注意事項

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

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

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

マルチパートアップロードのフロー

マルチパートアップロードは、次の 3 つのステップで構成されます：

1. マルチパートアップロードの開始

   InitiateMultipartUploadRequest メソッドを呼び出します。OSS は、グローバルに一意なアップロード ID を返します。

2. パートのアップロード

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

   説明

   • 特定の uploadId について、パート番号は完全なオブジェクト内でのパートの位置を識別します。既存のパートと同じパート番号で新しいパートをアップロードすると、既存のパートは上書きされます。

   • OSS は、受信したパートデータの MD5 ハッシュを応答の ETag ヘッダーに含めます。

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

3. マルチパートアップロードの完了

   すべてのパートをアップロードした後、CompleteMultipartUploadRequest メソッドを呼び出して、それらを完全なファイルに結合します。

マルチパートアップロードの完全な例

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

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

// yourEndpoint を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを 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 で ObjectMeta を設定できますが、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);
}
// パートの総数を計算します。
// パートの最小サイズは 100 KB、最大サイズは 5 GB です。最後のパートは 100 KB より小さくてもかまいません。
var partSize = 100 * 1024;
var fi = new FileInfo(localFilename);
var fileSize = fi.Length;
var partCount = fileSize / partSize;
if (fileSize % partSize != 0)
{
    partCount++;
}
//  マルチパートアップロードが初期化されたら、パートのアップロードを開始します。PartETags は、PartETag 情報を格納するリストです。OSS は、送信されたパートのリストを受信した後、各パートの有効性を検証します。すべてのデータパートが検証された後、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;

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

// yourEndpoint を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを 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 を呼び出してマルチパートアップロードを完了する前に返されます。
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;

// yourEndpoint を、バケットが配置されているリージョンのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを 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);
        }
        // 結果が切り捨てられている場合、nextKeyMarker は次のリクエストの開始点を示します。
        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;

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