Azure 资源管理器 Cosmos DB .NET SDK

azure-resource-manager-cosmosdb-dotnet
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.20/5
使用7.7K

Azure.ResourceManager.CosmosDB (.NET)

用于通过 Azure Resource Manager 部署和管理 Azure Cosmos DB 资源的管理平面 SDK。

> ⚠️ 管理平面 vs 数据平面
> - 本 SDK (Azure.ResourceManager.CosmosDB):创建账户、数据库、容器,配置吞吐量,管理 RBAC
> - 数据平面 SDK (Microsoft.Azure.Cosmos):对文档进行 CRUD 操作、执行查询和存储过程

安装

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

当前版本:稳定版 v1.4.0,预览版 v1.4.0-beta.13

环境变量

bash
AZURE_SUBSCRIPTION_ID=<your-subscription-id>

用于服务主体身份验证(可选)

AZURE_TENANT_ID=<tenant-id> AZURE_CLIENT_ID=<client-id> AZURE_CLIENT_SECRET=<client-secret>

身份验证

csharp
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}"));

资源层级

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

核心工作流

1. 创建 Cosmos DB 账户

csharp
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 数据库

csharp
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 容器

csharp
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)

csharp
// 手动吞吐量
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. 获取连接信息

csharp
// 获取密钥
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()导航层级结构

错误处理

csharp
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 |

使用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

  • 仅在任务明确符合上述范围时使用本技能。
  • 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺失必要的输入、权限、安全边界或成功标准,请停止操作并请求澄清。