.NET Aspire Azure Blob Storage 統合
Azure Blob Storage は、大量の非構造化データを格納するためのサービスです。 .NET Aspire Azure Blob Storage 統合により、既存の Azure Blob Storage インスタンスに接続したり、.NET アプリケーションから新しいインスタンスを作成したりできます。
ホスティング統合
.NET .NET Aspire Azure Storage ホスティング統合は、さまざまなストレージ リソースを次の種類としてモデル化します。
- AzureStorageResource: Azure Storage リソースを表します。
- AzureStorageEmulatorResource: Azure ストレージ エミュレーター リソース (Azurite) を表します。
- AzureBlobStorageResource: Azure BLOB ストレージ リソースを表します。
- AzureQueueStorageResource: Azure キュー ストレージ リソースを表します。
- AzureTableStorageResource: Azure Table Storage リソースを表します。
これらの型と API にアクセスして表現するには、📦Aspireホスティング.Azure NuGet パッケージをアプリ ホスト プロジェクトに追加します。
dotnet add package Aspire.Hosting.Azure.Storage
詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。
ストレージ リソース Azure 追加する
アプリ ホスト プロジェクトで、AddAzureStorage を呼び出して、Azure Storage リソース ビルダーを追加して返します。
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage");
// An Azure Storage resource is required to add any of the following:
//
// - Azure Blob storage resource.
// - Azure Queue storage resource.
// - Azure Table storage resource.
// After adding all resources, run the app...
アプリ ホストに AzureStorageResource
を追加すると、Blob、Queue、Table ストレージ リソース Azure を追加するのに役立つ他の便利な API が公開されます。 つまり、他のストレージ リソースを追加する前に、AzureStorageResource
を追加する必要があります。
大事な
AddAzureStorageを呼び出すと、暗黙的に AddAzureProvisioningが呼び出されます。これによって、アプリの起動時に Azure リソースを動的に生成するためのサポートが追加されます。 アプリは、適切なサブスクリプションと場所を構成する必要があります。 詳細については、「ローカル プロビジョニング: 構成」を参照してください。
生成されたプロビジョニング Bicep
の Bicepを初めて経験する場合、それは Azure リソースを定義するためのドメイン固有の言語です。 .NET .NET Aspireでは、Bicep を手動で記述する必要はありません。代わりに、プロビジョニング API によって Bicep が生成されます。 アプリを発行すると、生成された Bicep がマニフェスト ファイルと共に出力されます。 Azure Storage リソースを追加すると、次の Bicep が生成されます。
ストレージ Bicep Azure 切り替えます。
@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location
param principalId string
param principalType string
resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
name: take('storage${uniqueString(resourceGroup().id)}', 24)
kind: 'StorageV2'
location: location
sku: {
name: 'Standard_GRS'
}
properties: {
accessTier: 'Hot'
allowSharedKeyAccess: false
minimumTlsVersion: 'TLS1_2'
networkAcls: {
defaultAction: 'Allow'
}
}
tags: {
'aspire-resource-name': 'storage'
}
}
resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
name: 'default'
parent: storage
}
resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
properties: {
principalId: principalId
roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
principalType: principalType
}
scope: storage
}
resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
properties: {
principalId: principalId
roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
principalType: principalType
}
scope: storage
}
resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
properties: {
principalId: principalId
roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
principalType: principalType
}
scope: storage
}
output blobEndpoint string = storage.properties.primaryEndpoints.blob
output queueEndpoint string = storage.properties.primaryEndpoints.queue
output tableEndpoint string = storage.properties.primaryEndpoints.table
上記の Bicep は、Azure ストレージ アカウントを次の既定値でプロビジョニングするモジュールです。
-
kind
: ストレージ アカウントの種類。 既定値はStorageV2
です。 -
sku
: ストレージ アカウントの SKU。 既定値はStandard_GRS
です。 -
properties
: ストレージ アカウントのプロパティ:-
accessTier
: ストレージ アカウントのアクセス層。 既定値はHot
です。 -
allowSharedKeyAccess
: ストレージ アカウントがアカウント アクセス キーによる要求の承認を許可するかどうかを示すブール値。 既定値はfalse
です。 -
minimumTlsVersion
: ストレージ アカウントでサポートされている TLS の最小バージョン。 既定値はTLS1_2
です。 -
networkAcls
: ストレージ アカウントのネットワーク ACL。 既定値は{ defaultAction: 'Allow' }
です。
-
ストレージ アカウントに加えて、BLOB コンテナーもプロビジョニングします。
次のロールの割り当てがストレージ アカウントに追加され、アプリケーションへのアクセスが許可されます。 詳細については、組み込みの Azure ロールベースのアクセス制御 (Azure RBAC) ロール を参照してください。
役割/ID | 説明 |
---|---|
ストレージ BLOB データ共同作成者ba92f5b4-2d11-453d-a403-e96b0029c9fe |
ストレージ コンテナーと BLOB Azure 読み取り、書き込み、および削除します。 |
ストレージ テーブル データ共同作成者0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3 |
Storage のテーブルとエンティティ Azure 読み取り、書き込み、削除します。 |
ストレージ キュー データ共同作成者974c5e8b-45b9-4653-ba55-5f855dd0fb88 |
ストレージ キューAzureおよびキュー メッセージを読み取り、書き込み、削除します。 |
生成された Bicep は開始点であり、特定の要件を満たすようにカスタマイズできます。
プロビジョニング インフラストラクチャをカスタマイズする
すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。 この型では、Azure API を使用して、ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) リソースを構成する fluent API を提供することで、生成された Bicep をカスタマイズできます。 たとえば、kind
、sku
、properties
などを構成できます。 次の例では、Azure Storage リソースをカスタマイズする方法を示します。
builder.AddAzureStorage("storage")
.ConfigureInfrastructure(infra =>
{
var storageAccount = infra.GetProvisionableResources()
.OfType<StorageAccount>()
.Single();
storageAccount.AccessTier = StorageAccountAccessTier.Cool;
storageAccount.Sku = new StorageSku { Name = StorageSkuName.PremiumZrs };
storageAccount.Tags.Add("ExampleKey", "Example value");
});
上記のコード:
-
ConfigureInfrastructure API への呼び出しを連鎖させます。
-
infra
パラメーターは、AzureResourceInfrastructure 型のインスタンスです。 - プロビジョニング可能なリソースは、GetProvisionableResources() メソッドを呼び出すことによって取得されます。
- 1つのStorageAccountが取得されました。
- StorageAccount.AccessTier は、StorageAccountAccessTier.Coolに割り当てられます。
-
StorageAccount.Sku は、StorageSkuの
Name
を持つ新しい PremiumZrs に割り当てられます。 -
ExampleKey
のキーと値がExample value
のタグがストレージ アカウントに追加されます。
-
Azure Storage リソースをカスタマイズするために使用できる構成オプションは他にも多数あります。 詳細については、Azure.Provisioning.Storageを参照してください。
既存の Azure ストレージ アカウントに接続する
接続する既存の Azure ストレージ アカウントがある場合があります。 新しい Azure Storage リソースを表す代わりに、接続文字列をアプリ ホストに追加できます。 既存の Azure Storage アカウントに接続を追加するには、AddConnectionString メソッドを呼び出します。
var builder = DistributedApplication.CreateBuilder(args);
var blobs = builder.AddConnectionString("blobs");
builder.AddProject<Projects.WebApplication>("web")
.WithReference(blobs);
// After adding all resources, run the app...
手記
接続文字列は、データベース接続、メッセージ ブローカー、エンドポイント URI、その他のサービスなど、さまざまな接続情報を表すために使用されます。 .NET .NET Aspire 命名法では、"接続文字列" という用語は、あらゆる種類の接続情報を表すために使用されます。
接続文字列は、アプリ ホストの構成 (通常は セクションの ConnectionStrings
) で構成されます。 アプリ ホストは、この接続文字列を環境変数としてすべての依存リソースに挿入します。次に例を示します。
{
"ConnectionStrings": {
"blobs": "https://{account_name}.blob.core.windows.net/"
}
}
依存リソースは、GetConnectionString メソッドを呼び出し、接続名をパラメーターとして渡すことによって、挿入された接続文字列にアクセスできます(この場合 "blobs"
。
GetConnectionString
API は、IConfiguration.GetSection("ConnectionStrings")[name]
の短縮形です。
ストレージ エミュレーター リソース Azure 追加する
Azure ストレージ エミュレーター リソースを追加するには、IResourceBuilder<AzureStorageResource>
の呼び出しを RunAsEmulator API にチェーンします。
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage")
.RunAsEmulator();
// After adding all resources, run the app...
RunAsEmulator
を呼び出すと、エミュレーターを使用してローカルで実行するようにストレージ リソースが構成されます。 この場合のエミュレーターは Azuritemcr.microsoft.com/azure-storage/azurite
イメージでコンテナーをアプリ ホストに追加すると、アプリ ホストが起動したときにコンテナーが作成されて起動されます。 詳細については、「コンテナー リソースのライフサイクルの」を参照してください。
Azurite コンテナーを構成する
コンテナー リソースで使用できるさまざまな構成があります。たとえば、コンテナーのポート、環境変数、有効期間などを構成できます。
Azurite コンテナー ポートの構成
既定では、.NET.NET Aspireによって構成された Azurite コンテナーは、次のエンドポイントを公開します。
エンドポイント | コンテナー ポート | ホスト ポート |
---|---|---|
blob |
10000 | 動的 |
queue |
10001 | 動的 |
table |
10002 | 動的 |
待ち受けているポートは、デフォルトで動的です。 コンテナーが起動すると、ポートはホスト コンピューター上のランダムなポートにマップされます。 エンドポイント ポートを構成するには、次の例に示すように、RunAsEmulator
メソッドによって提供されるコンテナー リソース ビルダーの呼び出しをチェーンします。
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage").RunAsEmulator(
azurite =>
{
azurite.WithBlobPort("blob", 27000)
.WithQueuePort("queue", 27001)
.WithTablePort("table", 27002);
});
// After adding all resources, run the app...
上記のコードは、Azurite コンテナーの既存の blob
、queue
、および table
エンドポイントを構成して、ポート 27000
、27001
、および 27002
をそれぞれリッスンします。 Azurite コンテナーのポートは、次の表に示すようにホスト ポートにマップされます。
エンドポイント名 | ポート マッピング (container:host ) |
---|---|
blob |
10000:27000 |
queue |
10001:27001 |
table |
10002:27002 |
永続的な有効期間で Azurite コンテナーを構成する
永続的な有効期間で Azurite コンテナーを構成するには、Azurite コンテナー リソースで WithLifetime メソッドを呼び出し、ContainerLifetime.Persistent渡します。
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage").RunAsEmulator(
azurite =>
{
azurite.WithLifetime(ContainerLifetime.Persistent);
});
// After adding all resources, run the app...
詳細については、「コンテナー リソースの有効期間 」を参照してください。
データ ボリュームを使用して Azurite コンテナーを構成する
Azure ストレージ エミュレーター リソースにデータ ボリュームを追加するには、WithDataVolume ストレージ エミュレーター リソースで Azure メソッドを呼び出します。
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage").RunAsEmulator(
azurite =>
{
azurite.WithDataVolume();
});
// After adding all resources, run the app...
データ ボリュームは、Azurite データをコンテナーのライフサイクル外に保持するために使用されます。 データ ボリュームは Azurite コンテナーの /data
パスにマウントされ、name
パラメーターが指定されていない場合、名前は .azurite/{resource name}
形式になります。 データボリュームと、バインド マウントよりも優先される理由の詳細については、Docker ドキュメント「ボリューム」を参照してください。
データ バインド マウントを使用して Azurite コンテナーを構成する
Azure ストレージ エミュレーター リソースにデータ バインド マウントを追加するには、WithDataBindMount メソッドを呼び出します。
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage").RunAsEmulator(
azurite =>
{
azurite.WithDataBindMount("../Azurite/Data");
});
// After adding all resources, run the app...
大事な
データ バインド マウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適した ボリュームと比較して機能が制限されています。 ただし、バインド マウントを使用すると、ホスト システム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。
データ バインド マウントは、コンテナーの再起動の間に Azurite データを保持するために、ホスト マシンのファイルシステムに依存します。 データ バインド マウントは、Azurite コンテナー内のアプリ ホスト ディレクトリ (../Azurite/Data
) を基準にして、ホスト コンピューター上の IDistributedApplicationBuilder.AppHostDirectory パスにマウントされます。 データ バインド マウントの詳細については、「Docker ドキュメント: バインド マウント」を参照してください。
ストレージ リソースに接続する
.NET .NET Aspire アプリ ホストを実行すると、Azure Storage Explorerなどの外部ツールからストレージ リソースにアクセスできます。 Azurite を使用してストレージ リソースがローカルで実行されている場合は、Azure Storage Explorer によって自動的に取得されます。
手記
Azure Storage Explorer は、既定のポートが使用されていると仮定して Azurite ストレージ リソースを検出します。 異なるポートを使用するように Azurite コンテナーを構成
ストレージ エクスプローラーからストレージ リソース Azure 接続するには、次の手順に従います。
.NET .NET Aspire アプリ ホストを実行します。
Azure Storage Explorer を開きます。
エクスプローラーの ペインを表示します。
[ リストを更新する] リンクを選択して、ストレージ アカウントの一覧を更新します。
Emulator & Attached ノードを展開します。
ストレージ アカウント ノードを展開します。
リソースの名前がプレフィックスとして含まれたストレージ アカウントが表示されます。
Azure Storage Explorer を使用して、ストレージ アカウントとその内容を自由に探索できます。 Azure Storage Explorer の使用方法の詳細については、「Storage Explorerの開始方法」を参照してください。
Azure Blob Storage のリソースを追加する
アプリ ホスト プロジェクトで、Azure Blob Storageによって返された AddBlobs インスタンスで IResourceBuilder<IAzureStorageResource>
への呼び出しを連結して、AddAzureStorage 統合を登録します。 次の例では、Azure Blob Storage という名前の storage
リソースと blobs
という名前の BLOB コンテナーを追加する方法を示します。
var builder = DistributedApplication.CreateBuilder(args);
var blobs = builder.AddAzureStorage("storage")
.RunAsEmulator();
.AddBlobs("blobs");
builder.AddProject<Projects.ExampleProject>()
.WithReference(blobs)
.WaitFor(blobs);
// After adding all resources, run the app...
上記のコード:
-
Azureという名前の
storage
Storage リソースを追加します。 - エミュレーターを使用してローカルで実行するようにストレージ リソースを構成するために、RunAsEmulator への呼び出しをチェーンします。 この場合のエミュレーターは Azurite
です。 -
blobs
という名前の BLOB コンテナーをストレージ リソースに追加します。 -
blobs
リソースをExampleProject
に追加し、準備が整うのを待ってからプロジェクトを開始します。
ホスティング統合の正常性チェック
Azure Storage ホスティング統合により、ストレージ リソースの正常性チェックが自動的に追加されます。 エミュレーターとして実行されている場合にのみ追加され、Azurite コンテナーが実行されていることと、そのコンテナーへの接続を確立できることを確認します。 ホスティング統合は、AspNetCore.HealthChecks 📦 NuGet パッケージに依存します。また、Azure.Storage.Blobs NuGet パッケージも必要です。
Client 統合
.NET Aspire Azure Blob Storage client 統合を開始するには、まず 📦Aspireパッケージをインストールしてください。このパッケージは、Azure.Storage.Blobs 用の NuGet パッケージであり、client-consuming プロジェクト、つまり Azure Blob Storageclientを利用するアプリケーションのプロジェクトに含まれます。 Azure Blob Storage client 統合により、BlobServiceClientとの対話に使用できる Azure Blob Storage インスタンスが登録されます。
dotnet add package Aspire.Azure.Storage.Blobs
Azure Blob Storage client の追加
Program.cs-consuming プロジェクトの client ファイルで、任意の AddAzureBlobClient で IHostApplicationBuilder 拡張メソッドを呼び出して、依存関係挿入コンテナーを介して使用する BlobServiceClient
を登録します。 このメソッドは、接続名パラメーターを受け取ります。
builder.AddAzureBlobClient("blobs");
その後、依存関係の挿入を使用して BlobServiceClient
インスタンスを取得できます。 たとえば、サービスから client を取得するには、次のようにします。
public class ExampleService(BlobServiceClient client)
{
// Use client...
}
構成
.NET Aspire
Azure Blob Storage 統合には、プロジェクトの要件と規則に基づいて BlobServiceClient
を構成するための複数のオプションが用意されています。
接続文字列を使用する
ConnectionStrings
構成セクションの接続文字列を使用する場合は、AddAzureBlobClientを呼び出すときに接続文字列の名前を指定できます。
builder.AddAzureBlobClient("blobs");
その後、接続文字列は ConnectionStrings
構成セクションから取得され、次の 2 つの接続形式がサポートされます。
サービス URI
ServiceUri
プロパティと連携して接続を確立する AzureStorageBlobsSettings.Credentialを使用することをお勧めします。 資格情報が構成されていない場合は、Azure.Identity.DefaultAzureCredential が使用されます。
{
"ConnectionStrings": {
"blobs": "https://{account_name}.blob.core.windows.net/"
}
}
接続文字列
または、Azure Storage 接続文字列 を使用することもできます。
{
"ConnectionStrings": {
"blobs": "AccountName=myaccount;AccountKey=myaccountkey"
}
}
詳細については、「Azure 構成する」を参照してください。
構成プロバイダーを使用する
.NET Aspire
Azure Blob Storage 統合では、Microsoft.Extensions.Configurationがサポートされます。
AzureStorageBlobsSettings キーを使用して、構成から BlobClientOptions と Aspire:Azure:Storage:Blobs
を読み込みます。 次のスニペットは、いくつかのオプションを構成する appsettings.json ファイルの例です。
{
"Aspire": {
"Azure": {
"Storage": {
"Blobs": {
"DisableHealthChecks": true,
"DisableTracing": false,
"ClientOptions": {
"Diagnostics": {
"ApplicationId": "myapp"
}
}
}
}
}
}
}
完全な Azure Blob Storageclient 統合 JSON スキーマについては、Aspireを参照してください。Azure.Storage.Blobs/ConfigurationSchema。json.
インライン デリゲートを使用する
また、Action<AzureStorageBlobsSettings> configureSettings
デリゲートを渡して、一部またはすべてのオプションをインラインで設定することもできます。たとえば、正常性チェックを構成します。
builder.AddAzureBlobClient(
"blobs",
settings => settings.DisableHealthChecks = true);
BlobClientOptions メソッドの 2 番目のパラメーターである Action<IAzureClientBuilder<BlobServiceClient, BlobClientOptions>> configureClientBuilder
デリゲートを使用して、AddAzureBlobClient
を設定することもできます。 たとえば、次の clientによって、すべての要求の問題に対してユーザー エージェント ヘッダーの最初の部分を設定するには、次のようにします。
builder.AddAzureBlobClient(
"blobs",
configureClientBuilder: clientBuilder =>
clientBuilder.ConfigureOptions(
options => options.Diagnostics.ApplicationId = "myapp"));
Client 統合の健康チェック
既定では、.NET.NET Aspire 統合により、すべてのサービス 正常性チェック が有効になります。 詳細については、.NET.NET Aspire 統合の概要を参照してください。
.NET Aspire Azure Blob Storage 統合:
-
AzureStorageBlobsSettings.DisableHealthChecks が
false
されたときに正常性チェックを追加し、Azure Blob Storageへの接続を試みます。 -
/health
HTTP エンドポイントと統合されます。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります。
可観測性とテレメトリ
伐採
.NET Aspire Azure Blob Storage 統合では、次のログ カテゴリが使用されます。
Azure.Core
Azure.Identity
追跡
.NET Aspire Azure Blob Storage 統合では、OpenTelemetryを使用して次のトレース アクティビティが出力されます。
Azure.Storage.Blobs.BlobContainerClient
メトリック
.NET Aspire Azure Blob Storage 統合は現在、Azure SDK の制限により、既定ではメトリックをサポートしていません。
関連項目
.NET Aspire