Azure 资源管理器 Cosmos DB .NET SDK
Azure.ResourceManager.CosmosDB (.NET)
用于通过 Azure Resource Manager 部署和管理 Azure Cosmos DB 资源的管理平面 SDK。
> ⚠️ 管理平面 vs 数据平面
> - 本 SDK (Azure.ResourceManager.CosmosDB):创建账户、数据库、容器,配置吞吐量,管理 RBAC
> - 数据平面 SDK (Microsoft.Azure.Cosmos):对文档进行 CRUD 操作、执行查询和存储过程
安装
dotnet add package Azure.ResourceManager.CosmosDB
dotnet add package Azure.Identity当前版本:稳定版 v1.4.0,预览版 v1.4.0-beta.13
环境变量
AZURE_SUBSCRIPTION_ID=<your-subscription-id>
用于服务主体身份验证(可选)
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;
// 始终使用 DefaultAzureCredential
var credential = new DefaultAzureCredential();
var armClient = new ArmClient(credential);
// 获取订阅
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核心工作流
1. 创建 Cosmos DB 账户
using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;
// 获取资源组
var resourceGroup = await subscription
.GetResourceGroupAsync("my-resource-group");
// 定义账户
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
};
// 创建账户(长时间运行的操作)
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 小时
});
var containerCollection = database.GetCosmosDBSqlContainers();
var containerOperation = await containerCollection.CreateOrUpdateAsync(
WaitUntil.Completed,
"my-container",
containerData);
CosmosDBSqlContainerResource container = containerOperation.Value;
4. 配置吞吐量 (Throughput)
// 手动吞吐量
var throughputData = new ThroughputSettingsUpdateData(
new ThroughputSettingsResourceInfo
{
Throughput = 400
});
// 自动缩放吞吐量
var autoscaleData = new ThroughputSettingsUpdateData(
new ThroughputSettingsResourceInfo
{
AutoscaleSettings = new AutoscaleSettingsResourceInfo
{
MaxThroughput = 4000
}
});
// 应用到数据库
await database.CreateOrUpdateCosmosDBSqlDatabaseThroughputAsync(
WaitUntil.Completed,
throughputData);
5. 获取连接信息
// 获取密钥
var keys = await account.GetKeysAsync();
Console.WriteLine($"Primary Key: {keys.Value.PrimaryMasterKey}");
// 获取连接字符串
var connectionStrings = await account.GetConnectionStringsAsync();
foreach (var cs in connectionStrings.Value.ConnectionStrings)
{
Console.WriteLine($"{cs.Description}: {cs.ConnectionString}");
}
关键类型参考
| 类型 | 用途 |
|------|---------|
| ArmClient | 所有 ARM 操作的入口点 |
| CosmosDBAccountResource | 表示一个 Cosmos DB 账户 |
| CosmosDBAccountCollection | 账户 CRUD 的集合 |
| CosmosDBSqlDatabaseResource | SQL API 数据库 |
| CosmosDBSqlContainerResource | SQL API 容器 |
| CosmosDBAccountCreateOrUpdateContent | 账户创建的负载数据 |
| CosmosDBSqlDatabaseCreateOrUpdateContent | 数据库创建的负载数据 |
| CosmosDBSqlContainerCreateOrUpdateContent | 容器创建的负载数据 |
| ThroughputSettingsUpdateData | 吞吐量配置 |
最佳实践
1. 对于必须在继续之前完成的操作,请使用 WaitUntil.Completed。
2. 当需要手动轮询或并行运行操作时,请使用 WaitUntil.Started。
3. 始终使用 DefaultAzureCredential —— 切勿硬编码密钥。
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("账户已存在");
}
catch (RequestFailedException ex)
{
Console.WriteLine($"ARM 错误: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}
参考文件
| 文件 | 阅读时机 |
|------|--------------|
| 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 |
使用场景
本技能适用于执行概览中所描述的工作流或操作。局限性
- 仅在任务明确符合上述范围时使用本技能。
- 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
- 如果缺失必要的输入、权限、安全边界或成功标准,请停止操作并请求澄清。