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. 采用审慎的凭据链——生产环境优先使用托管标识；切勿将密钥硬编码
4. 处理 RequestFailedException，以应对 ARM API 错误
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

适用场景

当需要执行概述中所述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。