azure-resource-manager-cosmosdb-dotnet

バンドルされているアップストリームのサポート

サポートファイルはスキル相対パスに含まれています。ピン留めされたソース、ライセンス、ハッシュ、インポート時の変更については、UPSTREAM-NOTICE.md を参照してください。

Azure.ResourceManager.CosmosDB (.NET)

Azure Resource Manager を介して Azure Cosmos DB リソースをプロビジョニングおよび管理するための管理プレーン SDK です。

⚠️ 管理プレーンとデータプレーン

• この SDK（Azure.ResourceManager.CosmosDB）：アカウント、データベース、コンテナーの作成、スループットの構成、RBAC の管理
• データプレーン SDK（Microsoft.Azure.Cosmos）：ドキュメントに対する CRUD 操作、クエリ、ストアドプロシージャの実行

インストール

dotnet add package Azure.ResourceManager.CosmosDB
dotnet add package Azure.Identity

バージョンの範囲：インポートされた例は過去のものであり、現行バージョンを示すものではありません。対象とする SDK のバージョンを固定してコンパイルしてください。一般的に必要なインポートには、Azure、Azure.Core、Azure.ResourceManager.Resources が含まれます。

環境変数

AZURE_SUBSCRIPTION_ID=<your-subscription-id>
# For service principal auth (optional)
AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

認証

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.CosmosDB;

// Choose the intended tenant/identity explicitly; DefaultAzureCredential is convenient for local development.
var credential = new DefaultAzureCredential();
var armClient = new ArmClient(credential);

// Get subscription
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var subscription = armClient.GetSubscriptionResource(
    new ResourceIdentifier($"/subscriptions/{subscriptionId}"));

リソース階層

ArmClient
└── SubscriptionResource
    └── ResourceGroupResource
        └── CosmosDBAccountResource
            ├── CosmosDBSqlDatabaseResource
            │   └── CosmosDBSqlContainerResource
            │       ├── CosmosDBSqlStoredProcedureResource
            │       ├── CosmosDBSqlTriggerResource
            │       └── CosmosDBSqlUserDefinedFunctionResource
            ├── CassandraKeyspaceResource
            ├── GremlinDatabaseResource
            ├── MongoDBDatabaseResource
            └── CosmosDBTableResource

プロビジョニング前に、サブスクリプション、テナント、リージョン、対象となる正確なリソース、予算、ネットワーク／保持ポリシーを確認してください。削除、フェールオーバー、ローテーションには明示的な承認が必要です。ARM RBAC とデータプレーン RBAC は別々です。

主なワークフロー

1. Cosmos DB アカウントを作成する

using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;

// Get resource group
var resourceGroup = await subscription
    .GetResourceGroupAsync("my-resource-group");

// Define account
var accountData = new CosmosDBAccountCreateOrUpdateContent(
    location: AzureLocation.EastUS,
    locations: new[]
    {
        new CosmosDBAccountLocation
        {
            LocationName = AzureLocation.EastUS,
            FailoverPriority = 0,
            IsZoneRedundant = false
        }
    })
{
    Kind = CosmosDBAccountKind.GlobalDocumentDB,
    ConsistencyPolicy = new ConsistencyPolicy(DefaultConsistencyLevel.Session),
    EnableAutomaticFailover = true
};

// Create account (long-running operation)
var accountCollection = resourceGroup.Value.GetCosmosDBAccounts();
var operation = await accountCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-cosmos-account",
    accountData);

CosmosDBAccountResource account = operation.Value;

2. SQL データベースを作成する

var databaseData = new CosmosDBSqlDatabaseCreateOrUpdateContent(
    new CosmosDBSqlDatabaseResourceInfo("my-database"));

var databaseCollection = account.GetCosmosDBSqlDatabases();
var dbOperation = await databaseCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-database",
    databaseData);

CosmosDBSqlDatabaseResource database = dbOperation.Value;

3. SQL コンテナーを作成する

var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/partitionKey" },
            Kind = CosmosDBPartitionKind.Hash
        },
        IndexingPolicy = new CosmosDBIndexingPolicy
        {
            Automatic = true,
            IndexingMode = CosmosDBIndexingMode.Consistent
        },
        DefaultTtl = 86400 // 24 hours
    });

var containerCollection = database.GetCosmosDBSqlContainers();
var containerOperation = await containerCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-container",
    containerData);

CosmosDBSqlContainerResource container = containerOperation.Value;

4. スループットを構成する

// Manual throughput
var throughputData = new ThroughputSettingsUpdateData(
    new ThroughputSettingsResourceInfo
    {
        Throughput = 400
    });

// Autoscale throughput
var autoscaleData = new ThroughputSettingsUpdateData(
    new ThroughputSettingsResourceInfo
    {
        AutoscaleSettings = new AutoscaleSettingsResourceInfo
        {
            MaxThroughput = 4000
        }
    });

// Apply to database
await database.CreateOrUpdateCosmosDBSqlDatabaseThroughputAsync(
    WaitUntil.Completed,
    throughputData);

5. 接続情報を取得する

// Get keys
var keys = await account.GetKeysAsync();
// Pass the key directly to an approved secret store; never print it.

// Get connection strings
var connectionStrings = await account.GetConnectionStringsAsync();
foreach (var cs in connectionStrings.Value.ConnectionStrings)
{
    Console.WriteLine($"Connection available: {cs.Description} (value redacted)");
}

主な型のリファレンス

型	用途
ArmClient	すべての ARM 操作のエントリポイント
CosmosDBAccountResource	Cosmos DB アカウントを表します
CosmosDBAccountCollection	アカウントの CRUD 用コレクション
CosmosDBSqlDatabaseResource	SQL API データベース
CosmosDBSqlContainerResource	SQL API コンテナー
CosmosDBAccountCreateOrUpdateContent	アカウント作成ペイロード
CosmosDBSqlDatabaseCreateOrUpdateContent	データベース作成ペイロード
CosmosDBSqlContainerCreateOrUpdateContent	コンテナー作成ペイロード
ThroughputSettingsUpdateData	スループット構成

ベストプラクティス

1. 処理を続行する前に完了させる必要がある操作には WaitUntil.Completed を使用します
2. 手動でポーリングする場合や操作を並列実行する場合は WaitUntil.Started を使用します
3. 意図的に認証情報チェーンを選択します — 本番環境ではマネージド ID を優先し、キーをハードコードしないでください
4. ARM API エラーには RequestFailedException を処理します
5. CreateOrUpdateAsync の前に、望ましい状態全体を確認します — リクエストを繰り返すと状態が収束する場合がありますが、更新によってネットワーク、保持、コストが変わることがあります
6. Get* メソッドを使用して階層をたどります（例：account.GetCosmosDBSqlDatabases()）

エラー処理

using Azure;

try
{
    var operation = await accountCollection.CreateOrUpdateAsync(
        WaitUntil.Completed, accountName, accountData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    Console.WriteLine("Conflict: inspect the error code and current resource; 409 does not prove the requested account already exists");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}");
}

リファレンスファイル

ファイル	読むタイミング
references/account-management.md	アカウントの CRUD、フェールオーバー、キー、接続文字列、ネットワーク
references/sql-resources.md	SQL データベース、コンテナー、ストアドプロシージャ、トリガー、UDF
references/throughput.md	手動／自動スケールのスループット、モード間の移行

関連 SDK

SDK	用途	インストール
Microsoft.Azure.Cosmos	データプレーン（ドキュメントの CRUD、クエリ）	dotnet add package Microsoft.Azure.Cosmos
Azure.ResourceManager.CosmosDB	管理プレーン（この SDK）	dotnet add package Azure.ResourceManager.CosmosDB

使用するタイミング

このスキルは、概要に記載されたワークフローやアクションを実行する場合に適用されます。

制限事項

• このスキルは、タスクが上記の範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全上の境界、成功基準が不足している場合は、作業を中断して確認してください。