オブジェクト
オブジェクトはユーザー操作の基本的な OSS データユニットです。1 つのオブジェクトの最大サイズは、データアップロードモードによって異なる場合があります。オブジェクトのサイズは、Put Object モードでは 5 GB 以下、マルチパートアップロードモードでは 48.8 TB 以下の制限があります。オブジェクトには、key、meta、および data が含まれます。key はオブジェクト名です。meta は、オブジェクトの説明で、名前と値の一連のペアで構成されます。data はオブジェクトデータです。
命名規則
オブジェクト命名規則:
- UTF-8 エンコーディングを使用します。
- 長さは 1 ~ 1023 バイトでなければなりません。
- “/“ または “\” で開始することはできません。
- “\r” または “\n” の改行を含めることはできません。
オブジェクトのアップロード
簡単なアップロード
指定された文字列のアップロード
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
string str = "a line of simple text";
byte[] binaryData = Encoding.ASCII.GetBytes(str);
MemoryStream requestContent = new MemoryStream(binaryData);
client.PutObject(bucketName, key, requestContent);
指定されたローカルファイルのアップロード
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
String fileToUpload = "your local file";
client.PutObject(bucketName, key, fileToUpload);
このメソッドを使用してアップロードする最大ファイルは 5 GB を超えることはできません。サイズ制限を超える場合は、代わりに multipartupload を使用してアップロードできます。
シミュレーションフォルダーの作成
OSS サービスでは、フォルダーを使用しません。すべての要素はオブジェクトとして格納されます。ただし、次のコードを使用してシミュレーションフォルダーを作成できます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
// Note: key treats as a folder and must end with a slash.
const string key = "yourfolder/";
// put object with zero bytes stream.
using (MemoryStream ms = new MemoryStream())
{
client.PutObject(bucketName, key, ms);
}
実際、シミュレーションフォルダーを作成することは、サイズが 0 のオブジェクトを作成することです。このオブジェクトはアップロードおよびダウンロードできます。コンソールには、”/“ で終わるオブジェクトがフォルダーとして表示されるため、 この方法でシミュレーションフォルダーを作成できます。フォルダーにアクセスする場合は、「フォルダーシミュレーション機能」を参照してください。
オブジェクトの Http ヘッダーの設定
OSS サービスを使用すると、オブジェクトの Http ヘッダーをカスタマイズできます。次のコードでは、オブジェクトの有効期限を設定しています。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
using (var fs = File.Open(fileToUpload, FileMode.Open))
{
var metadata = new ObjectMetadata();
metadata.ContentLength = fs.Length;
metadata.ExpirationTime = DateTime.Parse("2015-10-12T00:00:00.000Z")
client.PutObject(bucketName, key, fs, metadata);
}
.NET SDK は、Cache-Control、Content-Disposition、Content-Encoding、および Expires の 4 種類の Http ヘッダーをサポートしています。ヘッダーの詳細については、『RFC2616』を参照してください。
ユーザー定義メタデータ
OSS では、ユーザーがオブジェクトを表すメタデータを定義できます。例:
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
using (var fs = File.Open(fileToUpload, FileMode.Open))
{
var metadata = new ObjectMetadata();
metadata.UserMetadata.Add("name", "my-data");
metadata.ContentLength = fs.Length;
client.PutObject(bucketName, key, fs, metadata);
}
上記のコードでは、名前が “name” で値が “my-data” のメタデータを定義しています。このオブジェクトをダウンロードする場合、ユーザーはメタデータも取得します。1 つのオブジェクトに複数の同様のパラメーターを含むことができますが、すべてのユーザーメタの合計サイズは 2 KB 以内である必要があります。
注意: ユーザーメタの名前では大文字小文字は区別されません。たとえば、ユーザーがオブジェクトをアップロードし、メタデータの名前を “Name” と定義すると、ヘッダーに格納されているパラメーターが “x-oss-meta-name” になります。したがって、オブジェクトにアクセスするときは、”name” という名前のパラメーターを使用します。ただし、格納されているパラメーターが “name” であり、そのパラメーターの情報が見つからない場合、システムは “Null” を返します。
マルチパートアップロード
OSS では、サーバーにアップロードする 1 つのオブジェクトを複数のリクエストに分割できます。マルチパートアップロードコンテンツについては、「MultipartUpload」の「Object Multipart Upload」を参照してください。
バケットオブジェクトの一覧表示
オブジェクトのリスト
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
public void ListObject(String bucketName)
{
var listObjectsRequest = new ListObjectsRequest(bucketName);
var result = ossClient.ListObjects(listObjectsRequest);
foreach (var summary in result.ObjectSummaries)
{
Console.WriteLine(summary.Key);
}
}
注意: デフォルトでは、バケットに 100 を超えるオブジェクトが含まれている場合、最初の 100 個のみが返され、返される結果の IsTruncated パラメーターは true になります。返される NextMarker を、次のデータアクセスの開始位置として使用できます。MaxKeys パラメーターを変更するか、それぞれのアクセスに Marker パラメーターを使用して、返されるオブジェクトエントリの数を増やすことができます。
拡張パラメーター
一般に、ListObjectsRequest パラメーターはさらに強力な機能を提供します。例:
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
var listObjectsRequest = new ListObjectsRequest(bucketName)
{
Delimiter = "/",
Marker = "abc"
};
result = ossClient.ListObjects(listObjectsRequest);
foreach (var summary in result.ObjectSummaries)
{
Console.WriteLine(summary.Key);
}
設定可能なパラメーター名とその機能:
名前 | 機能 |
---|---|
Delimiter | オブジェクト名の文字をグループ化するために使用されます。すべての名前には指定されたプレフィックスが含まれ、最初の Delimiter 文字間のオブジェクトは、グループ要素 CommonPrefixes として機能します。 |
Marker | アルファベット順で marker 後の最初のエントリから結果を返すように設定します。 |
MaxKeys | 1 件のリクエストに対して返されるオブジェクトの最大数を制限します。指定されていない場合のデフォルト値は 100 です。MaxKeys の値は 1000 以下にする必要があります。 |
Prefix | 返されるオブジェクトキーにプレフィックスが付いていることを要求します。プレフィックスを使用するクエリから返されるキーにはそのプレフィックスも含まれることに注意してください。 |
全体で 1,000 を超える一連のオブジェクトをトラバースするためには複数のイテレーションを実行する必要があります。各イテレーション中に、最後のイテレーションの最終的なオブジェクトキーを現在のイテレーションの Marker として使用できます。
フォルダー機能のシミュレーション
Delimiter と Prefix を組み合わせてフォルダー関数をシミュレートできます。Delimiter と Prefix を組み合わせる目的は次のとおりです。フォルダーの名前としてプレフィックスを設定すると、このプレフィックスで始まるファイルが列挙され、このフォルダー内のすべてのファイルとサブフォルダーが再帰的に返されます。Delimiter が “/“ として設定されている場合、返される値にはフォルダー内のファイルが列挙され、サブフォルダーは CommonPrefixes セクションで返されます。サブフォルダー内のファイルとフォルダーは再帰的に表示されません。バケットに oss.jpg、fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi の 4 つのファイルが含まれる場合、 フォルダーの区切り記号として “/“ 記号を使用します。
すべてのバケットファイルのリスト
バケット内のすべてのファイルを取得するには、次のように記述します。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
ObjectListing result = null;
string nextMarker = string.Empty;
do
{
var listObjectsRequest = new ListObjectsRequest(bucketName)
{
Marker = nextMarker,
MaxKeys = 100
};
result = client.ListObjects(listObjectsRequest);
foreach (var summary in result.ObjectSummaries)
{
Console.WriteLine(summary.Key);
}
nextMarker = result.NextMarker;
} while (result.IsTruncated);
出力:
Objects:
fun/movie/001.avi
fun/movie/007.avi
fun/test.jpg
oss.jpg
CommonPrefixs:
ディレクトリ内のすべてのファイルの再帰的なリスト
Prefix パラメーターを次のように設定して、ディレクトリ内のすべてのファイルを取得できます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
var listObjectsRequest = new ListObjectsRequest(bucketName)
{
Prefix = "fun/"
};
result = client.ListObjects(listObjectsRequest);
foreach (var summary in result.ObjectSummaries)
{
Console.WriteLine(summary.Key);
}
出力:
Objects:
fun/movie/001.avi
fun/movie/007.avi
fun/test.jpg
CommonPrefixs:
ディレクトリ内のファイルとサブディレクトリのリスト
Prefix と Delimiter を組み合わせて使用して、ディレクトリ内のファイルとサブディレクトリをリストできます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
var listObjectsRequest = new ListObjectsRequest(bucketName)
{
Prefix = "fun/",
Delimiter = "/"
};
result = client.ListObjects(listObjectsRequest);
Console.WriteLine("Objects:");
foreach (var summary in result.ObjectSummaries)
{
Console.WriteLine(summary.Key);
}
Console.WriteLine("CommonPrefixes:");
foreach (var prefix in result.CommonPrefixes)
{
Console.WriteLine(prefix);
}
出力:
Objects:
fun/test.jpg
CommonPrefixs:
fun/movie/
返される結果で、ObjectSummaries リストに fun ディレクトリ内のファイルが含まれます。CommonPrefixs リストには fun ディレクトリのすべてのサブフォルダーが示されます。fun/movie/001.avi および fun/movie/007.avi ファイルは fun フォルダーの movie ディレクトリにあるため、リストされていません。
オブジェクトの取得
オブジェクトの単純な取得
次のコードを使用してオブジェクトを取得し、ストリームに入力することができます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
public void GetObject(String bucketName, string key)
{
var o = client.GetObject(bucketName, key);
using (var requestStream = o.Content)
{
byte[] buf = new byte[1024];
var fs = File.Open(fileToDownload, FileMode.OpenOrCreate);
var len = 0;
while ((len = requestStream.Read(buf, 0, 1024)) != 0)
{
fs.Write(buf, 0, len);
}
fs.Close();
}
}
OSSObject には、オブジェクトのバケット、オブジェクト名、メタデータ、入力ストリームなどさまざまなオブジェクト情報が含まれます。入力ストリームを使用してオブジェクトのコンテンツを取得し、オブジェクトまたはメモリに格納できます。ObjectMetadata には、ETag、Http ヘッダー、およびオブジェクトのアップロード時に定義されたカスタムメタデータが含まれます。
GetObjectRequest を使用したオブジェクトの取得
他の関数については、GetObjectRequest を使用してオブジェクトを取得できます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
public void GetObject(String bucketName, string key)
{
var getObjectRequest = new GetObjectRequest(bucketName, key);
getObjectRequest.SetRange(20, 100);
var o = client.GetObject(getObjectRequest);
using (var requestStream = o.Content)
{
byte[] buf = new byte[1024];
var fs = File.Open(fileToDownload, FileMode.OpenOrCreate);
var len = 0;
while ((len = requestStream.Read(buf, 0, 1024)) != 0)
{
fs.Write(buf, 0, len);
}
fs.Close();
}
}
getObjectRequest で setRange メソッドを使用してオブジェクトの範囲を返すことができます。ファイルのマルチパートダウンロードと再開可能なデータ転送にこの関数を使用できます。GetObjectRequest は次のパラメーターを設定できます。
パラメーター | 説明 |
---|---|
Range | ファイル転送の範囲を指定します。 |
ModifiedSinceConstraint | 指定された時間が実際の変更時間よりも早い場合、ファイルは通常どおり送信されます。それ以外の場合、304 Not Modified 例外がスローされます。 |
UnmodifiedSinceConstraint | 指定された時間が実際の変更時間と同じか、実際の変更時間よりも遅い場合、ファイルは通常どおり送信されます。それ以外の場合、412 Precondition Failed 例外がスローされます。 |
MatchingETagConstraints | ETag グループを入力します。入力した予測 ETag がオブジェクトの ETag と一致する場合、ファイルは通常どおり送信されます。それ以外の場合、412 Precondition Failed 例外がスローされます。 |
NonmatchingEtagConstraints | ETag グループを入力します。入力した予測 ETag がオブジェクトの ETag と一致しない場合、ファイルは通常どおり送信されます。それ以外の場合、304 Not Modified 例外がスローされます。 |
ResponseHeaderOverrides | OSS から返されるリクエストの一部のヘッダーをカスタマイズします。 |
ObjectMetadata のみの取得
getObjectMetadata メソッドは、オブジェクトエンティティの代わりに ObjectMetadata のみを取得するために使用できます。コードは次のとおりです。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
public void GetObjectMetadata(String bucketName, string key)
{
var metadata = client.GetObjectMetadata(bucketName, key);
…
}
オブジェクトの削除
次のコードでオブジェクトは削除されます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
public void DeleteObject(String bucketName, string key)
{
client.DeleteObject(bucketName, key);
…
}
次のコードでオブジェクトはバッチ削除されます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
var keys = new List<string>();
var listResult = client.ListObjects(bucketName);
foreach (var summary in listResult.ObjectSummaries)
{
keys.Add(summary.Key);
}
var request = new DeleteObjectsRequest(bucketName, keys, false);
client.DeleteObjects(request);
オブジェクトのコピー
同じリージョン内で、操作権限がある 1 つのオブジェクトをコピーできます。1 GB を超える大きいオブジェクトをコピーするときは、Upload Part Copy メソッドを使用することをお勧めします。
1 つのオブジェクトのコピー
copyObject メソッドを使用すると、1 つのオブジェクトをコピーできます。コードは次のとおりです。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
var metadata = new ObjectMetadata();
metadata.AddHeader("mk1", "mv1");
var req = new CopyObjectRequest(sourceBucket, sourceKey, targetBucket, targetKey)
{
NewObjectMetadata = metadata
};
var ret = client.CopyObject(req);
このメソッドを使用してコピーされるオブジェクトは 1 GB 未満であることが必要です。1 GB を超えるとエラーが返されます。オブジェクトが 1 GB を超える場合は、次の Upload Part Copy メソッドを使用します。
オブジェクトメタの変更
データをコピーすると、既存のオブジェクトのメタ情報が変更される可能性があります。コピーされたソースオブジェクトのアドレスがコピー先オブジェクトのアドレスと同じである場合は、ソースオブジェクトのメタ情報が置き換えられます。
// Initialize OSSClient
var client = new OssClient(endpoint, accessId, accessKey);
var metadata = new ObjectMetadata();
metadata.ContentType = "text/html";
var req = new CopyObjectRequest(sourceBucket, sourceKey, sourceBucket, sourceKey)
{
NewObjectMetadata = metadata
};
var ret = client.CopyObject(req);