Microsoft Azure BLOB API
警告： DSAzure API は非推奨になり、Data.Cloud.AzureAPI に置き換えられました。クラウド コンピューティング アプリケーションの開発時には、新しい API を使用することをお勧めします。詳細は、「DataSnap でのクラウド コンピューティング」を参照してください。
Microsoft Azure BLOB API は、Data.Cloud.AzureAPI ユニットの Data.Cloud.AzureAPI.TAzureBlobService クラスにあります。
提供されている主要機能には、以下のものがあります。
- コンテナ リストの取得
- コンテナの作成とコンテナの削除
- ブロック BLOB の作成
- ページ BLOB の作成
- BLOB コンテンツの変更
- BLOB のコピー
- BLOB の削除
- スナップショットの作成
- BLOB のリースの取得、更新、更新停止、解除
- BLOB またはコンテナのプロパティおよびメタデータの取得
以下の説明では、TAzureBlobService のインスタンスを既に作成してあると仮定します。どのコード例でも、このインスタンスは FBlobService という名前で参照されます。さらに、XML パーサーが手元にあり、使用できるように既に適切に構成されているものとします。API は、場合によっては XML を返しますが、その場合、その XML の解析方法がわかっている必要があります。
コンテナの操作
コンテナは、プロパティとメタデータを持ち、BLOB を所有することができます。以下に、コンテナに関して実行できる操作をまとめます。
ルート コンテナの作成
ルート コンテナがあると、短いコンテナ アドレスを使用できるようになります（コンテナ名が含まれないため）。ルート コンテナは、次のコードで作成することができます。
Success := FBlobService.CreateRootContainer(Access);
ここで、Access は 'x-ms-blob-public-access' ヘッダーで使用する値です。情報をどう公開してアクセスさせるかに応じて、空の文字列、container、blob のいずれかを指定できます。Access を省略すると、デフォルト値の blob が使われます。あるいは、次のようにしてルート コンテナを作成することもできます。
Success := FBlobService.CreateContainer('$root', MetaData, Access);
ここで、MetaData は、ルート コンテナのメタデータ（省略可能）の TStringList です。MetaData パラメータを含まないオーバーロード関数があるため、このパラメータは完全に省略することができます。
ルート コンテナを作成したら、その後は他のコンテナと同じように扱うことができます。
コンテナの作成
通常のコンテナを作成するには、ルート コンテナの場合と同じコードを使用しますが（上記の CreateContainer を呼び出して名前を渡す例）、$root 以外の名前を指定します。
このコンテナ名は、次の命名規則に沿ったものでなければなりません。
- 長さは 3 ～ 65 文字である
- 英数字とハイフンのみで構成されている
- 先頭がハイフンであってはならない
- 小文字のみの表記である
コンテナの削除
ルート コンテナを削除するには、次のコードを呼び出します。
Success := FBlobService.DeleteRootContainer;
それ以外のコンテナを削除するには、次のコードを呼び出します。
Success := FBlobService.DeleteContainer('container-name');
引数にはコンテナの実際の名前を渡します。どちらの関数も、削除が成功すれば True を、成功しなければ False を返します。
全コンテナのリストの取得
利用可能なすべてのコンテナのリストを取得するには、次のコードを使用します。
xmlStr := ListContainers(['include'], ['metadata']);
パラメータには 2 つの配列を渡します。
- クラウドへ要求と一緒に渡すパラメータの配列
- 最初の配列に対応する値の配列
最初の配列の項目は 2 番目の配列の同じインデックスにある項目に直接対応しているため、この 2 つの配列は同じ長さでなければなりません。上記のコードでは、include というパラメータと "metadata" という値が渡されています。これは、返される XML に各コンテナのメタデータを含めるという意味です。この関数はパラメータなしで呼び出すこともでき、その場合にはメタデータは返されません。配列には maxresults というパラメータも指定できます。これは、この問い合わせから返されるコンテナの数を制限するためのものです。
返される XML は次のようになります。
<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ...>
...
<Containers>
<Container>
<Name>container-name</Name>
<URL>container-address</URL>
<Properties>
<Last-Modified>date/time-value</Last-Modified>
<Etag>etag</Etag>
</Properties>
<Metadata>
<metadata-name>value</metadata-name>
</Metadata>
</Container>
</Containers>
...
</EnumerationResults>
返される XML 全体の例については、「関連項目」セクションの MSDN ドキュメントを参照してください。
上記の XML には Containers 要素が 1 つあり、そこにすべての Container 項目が含まれます。各コンテナには、名前、URL、プロパティ、メタデータ（メタデータを返すよう指定した場合）が含まれます。
コンテナのプロパティの取得
先ほどの XML を見ると、各コンテナにプロパティが関連付けられていることがわかります。これらのプロパティは、全コンテナのリストを取得したときにも含められますが、次のコードを使用して個別に取得し直すこともできます。
Success := FBlobService.GetContainerProperties('container-name');
Props := TStringList.Create;
if Success then
FBlobService.PopulateContainerProperties(Props);
このコードでは、最初の要求が成功していれば、TStringList にプロパティのキーと値のペアが取り出されます。
コンテナのメタデータの取得
先ほどの XML を見ると、コンテナのリストを（'include' プロパティを 'metadata' に設定して）取得すると、メタデータのキーと値のペアのコレクションが返されることがわかります。ノード名（上の例では metadata-name）は実際のメタデータ キーになります。値はもちろん、メタデータ キーに対応する値です。
特定のコンテナのメタデータだけを取得することもできます。それには、次のコードを使用します。
Success := FBlobService.GetContainerMetadata('container-name');
Meta := TStringList.Create;
if Success then
FBlobService.PopulateContainer('x-ms-meta-', Meta);
最初の GetContainerMetadata の呼び出しでは、呼び出しが成功すると True が返されます。PopulateContainer では、前の呼び出しで集められたデータを使用して、指定した TStringList にメタデータのキーと値のペアを取り出します。メタデータはサーバーからの応答のヘッダーに含められて返され、各メタデータ キーの先頭には x-ms-meta- が付けられています。キー名の残りの部分は、実際のメタデータ キー名です。PopulateContainer 手続きは、任意の接頭辞を受け取り、その指定された文字列の接頭辞を基にヘッダーのどのキーと値のペアをリストに含めるかを判断し、TStringList に追加します。
コンテナのメタデータの変更
コンテナに格納されたメタデータを変更するには、まず上記のコードを使って TStringList に最新のメタデータを取り出し、その TStringList に対して、新しいメタデータのキーと値のペアを追加したり、既存のペアを変更または削除するなどの変更を行います。その後、次のコードを使って、変更をクラウドにコミットします。
Success := FBlobService.SetContainerMetadata('container-name', Meta);
ここで、Meta はコミット対象のキーと値のペアを含んだ TStringList です。更新が成功すれば True が返され、成功しなければ False が返されます。ルート コンテナの場合には、名前に '$root' を指定してください。
メモ： コンテナ内に格納するページ BLOB やブロック BLOB を作成することもできます。これらについては、「ページ BLOB の操作」や「ブロック BLOB の操作」で説明します。
メモ： コンテナのプロパティを変更することはできません。
一般の BLOB 操作
以下の操作は、ページ BLOB とブロック BLOB の両方で利用できます。ブロック BLOB はストリーミング用に、ページ BLOB はランダムな読み取り/書き込み操作用に、それぞれ最適化されています。
BLOB の削除
BLOB は、次のコードで削除することができます。
Success := FBlobService.DeleteBlob('container-name', 'blob-name');
DeleteBlob には、この他に、Snapshot、LeaseId、DeleteSnapshots という 3 つの任意指定のパラメータがあります。DeleteSnapshots は、空のままにする（BLOB に関連付けられたスナップショットがない場合のみ）か、include または only に設定することができます。include に設定すると BLOB とすべてのスナップショットが削除され、only に設定すると BLOB のスナップショットだけが削除されて BLOB 自体は残されます。
BLOB の具体的な 1 つのスナップショットを削除したい場合には、Snapshot に値を指定することができます。リースが取得されていて、まだその有効期限が切れていない場合には、LeaseId を指定しなければ BLOB の削除が成功しません。
BLOB のコピー
コピー元の BLOB と同じストレージ アカウント内のものであれば、どのコンテナにでも BLOB をコピーすることができます。コピー元と同じコンテナにコピーする場合には、もちろん、コピー先 BLOB に別の名前を指定する必要があります。
BLOB をコピーするには、次のコードを使用します。
Success := FBlobService.CopyBlob('destination-container', 'destination-blob-name', 'source-container', 'source-blob-name');
その他に、コピーする BLOB の具体的なスナップショット、コピー元 BLOB の最終変更日を確認するための日付/時刻値（指定した日付以降に変更されている場合にのみコピーを行います）、'変更されていない日付'（コピー元 BLOB がその日付以降に変更されていない場合にのみコピーを行います）など、任意指定のパラメータを指定することができます。すべての任意指定のパラメータを確認するには、TAzureBlobService のドキュメントか、DSAzure ユニットのコードを参照してください。また、任意指定のパラメータには LeaseId もあります。これはコピー先 BLOB のもので、コピー先 BLOB が既に存在し、そのリースを取得している場合に使用します。
スナップショットの作成
BLOB のスナップショットは、次のコードで作成することができます。
snapshot := FBlobService.SnapshotBlob('container-name', 'blob-name');
SnapshotBlob は、この他に、IfModifiedSince、IfUnmodifiedSince、IfMatch、IfNoneMatch、LeaseId、MetaHeaders という任意指定のパラメータを（この順序で）受け取ることができます。
スナップショット情報も含む完全な BLOB を XML 形式で取得したい場合には、ListBlobs を次のように少し変更して呼び出します。
xml := FBlobService.ListBlobs('container-name', ['prefix', 'include', 'include'], ['blob-name', 'metadata', 'snapshots']);
ここで、'container-name' および 'blob-name' は実際の値に置き換えてください。
リースの使い方
すべての BLOB について、リースの取得、リースの更新、リースの解除、リースの更新停止を行うことができます。BLOB のリースの取得が成功すると、その BLOB およびプロパティ/メタデータに対して 1 分間、排他的書き込みアクセスを行うことができます。その 1 分が過ぎる前に、必要がなくなればリースを解除したり、追加で 60 秒が必要であればリースを更新することができます。このリースは、誰かが BLOB のリースの更新を停止するまで、継続して更新できます。リースの更新停止が要求された場合、現在の 1 分間が終わるまではリースを維持できますが、そのリース ID でさらにリースを更新することはできません。
リースの取得
BLOB のリースを取得するには、次のコードを使用します。
LeaseId := FBlobService.LeaseBlob('container-name', 'blob-name');
リース ID が返されると、リースの変更、更新、解除ができるようになります。これらの操作には LeaseID という '任意指定' のパラメータがあり、誰かに BLOB がリースされている場合には必須パラメータになるためです。
リースの更新
リースを更新するには、次のコードを使用します。
FBlobService.LeaseBlob('container-name', 'blob-name', 'renew', LeaseId);
この呼び出しは最初にリースを作成したときに使用した呼び出しと似ていますが、2 つのパラメータが追加されています。最初のパラメータでは操作の種類が renew（更新）であることを示し、2 番目のパラメータにはリースを取得したときに返された LeaseId を指定します。処理が成功すると、BLOB およびそのデータに対して、さらに 60 秒間の保護された書き込みアクセスが得られます。
リースの更新停止
誰か（または何らかの理由でそのままリースを解除したくない場合には自分自身）が取得したリースの更新を停止するには、次のコードを使用します。
FBlobService.LeaseBlob('container-name', 'blob-name', 'break');
duration := StrToInt(FBlobService.ResponseHeader['x-ms-lease-time']);
これによりリースの更新が停止され、duration の秒数が過ぎると、BLOB はロックされていない状態になります。
リースの解除
取得した BLOB のリースは、有効期限が切れる前に解除することができます。それには、次のコードを使用します。
FBlobService.LeaseBlob('container-name', 'blob-name', 'release', LeaseId);
これで、LeaseId が正しければ、指定した BLOB のリースが解除されます。
BLOB コンテンツのダウンロード
次のコードで BLOB コンテンツをダウンロードすることができます。
stream := TFileStream.Create(location, fmCreate);
Success := FBlobService.GetBlob('container-name', 'blob-name', stream);
また、任意指定の 4 番目のパラメータで、ダウンロードする BLOB スナップショットを指定することもできます。GetBlob の呼び出しで False が返された場合には、サーバーにより返されたメッセージを FBlobService.ResponseText から取得することができます。
BLOB プロパティの取得
BLOB のプロパティを取得する方法は、コンテナのプロパティを取得する操作と似ています。コードは次のようになります。
Success := FBlobService.GetBlobProperties('container-name', 'blob-name');
Props := TStringList.Create;
if Success then
FBlobService.PopulateContainerProperties(Props);
GetBlobProperties の呼び出しには任意指定の 3 番目のパラメータがあり、プロパティを取得する対象として BLOB 自体ではなくスナップショットを指定することができます。GetBlobProperties の呼び出しが成功すると True が返され、PopulateContainerProperties を呼び出して実際のプロパティを取り出すことができます。
BLOB メタデータの取得
BLOB のメタデータを取り出す方法も、コンテナの場合の操作と似ています。次のコードで行うことができます。
Success := FBlobService.GetBlobMetadata('container-name', 'blob-name');
Meta := TStringList.Create;
if Success then
FBlobService.PopulateContainer('x-ms-meta-', Meta);
GetBlobMetadata にも任意指定の 3 番目のオプション Snapshot があり、BLOB 自体ではなくそのスナップショットのメタデータを取得することができます。
BLOB プロパティの設定
次のコードで BLOB のシステム プロパティを設定することができます。
Success := FBlobService.SetBlobProperties('container-name', 'blob-name', cache, contentType, encoding, language, md5, LeaseId);
最初の 2 つのプロパティ以外はどれも任意指定で、すべて文字列です（BLOB のリースが取得されている場合には LeaseId を指定する必要があり、BLOB に有効なリースがない場合には指定してはなりません）。
BLOB メタデータの変更
BLOB に格納されたメタデータを変更する方法は、コンテナに格納されたメタデータを変更する操作と非常によく似ています。次にそのコード例を示します。
Success := FBlobService.SetBlobMetadata('container-name', 'blob-name', Meta);
Meta パラメータは、メタデータのキーと値のペア（複数可）です。この他に LeaseId という 4 番目の任意指定のパラメータがあります。有効な BLOB のリースが取得されている場合には、これを指定しなければなりません。
ブロック BLOB の操作
以下に示すのは、ブロック BLOB に固有の操作です。
- ブロック BLOB の作成
ブロック BLOB を新規作成するには、次のコードを使用します。
Success := FBlobService.PutBlockBlob('container-name', 'blob-name', ContentBytes);
ContentBytes は、BLOB のコンテンツとして使われる TBytes インスタンスです。PutBlockBlob の任意指定のパラメータには、順に LeaseId、UserHeaders、ContentType、ContentEncoding、ContentLanguage、ContentMD5 があります。これら任意指定のパラメータに関する情報は、下記の MSDN ドキュメントに記載されています。コンテンツ タイプを指定しなかった場合には、application/octet-stream が使われます。
- ブロック BLOB コンテンツの更新
ブロック BLOB を作成した後、その値のどれでも変更することができます。それには、BLOB を作成したときとまったく同じコードを使用します。この場合には、LeaseId のパラメータが有効になります（まだ BLOB を作成していない場合には LeaseId が必要なことはあり得なかったためです）。
ページ BLOB の操作
以下に示すのは、ページ BLOB に固有の操作です。
- ページ BLOB の作成
ページ BLOB を新規作成するには、Data.Cloud.AzureAPI.TAzureBlobService.PutPageBlob を次のコードのように使用します。
Success := FBlobService.PutPageBlob('container-name', 'blob-name', BlobSize);
任意指定のパラメータには、順に ContainerName、BlobName、MaximumSize、LeaseID、OptionalHeaders、MetaData、ResponseInfo があります。これら任意指定のパラメータについて詳しく知るには、下記の MSDN ドキュメントを参照してください。コンテンツ タイプを指定しなかった場合には、application/octet-stream が使われます。