Azure.ResourceManager.CosmosDB (.NET)

SDK du plan de gestion pour l'approvisionnement et la gestion des ressources Azure Cosmos DB via Azure Resource Manager.

⚠️ Plan de gestion vs Plan de données

• Ce SDK (Azure.ResourceManager.CosmosDB) : Créer des comptes, bases de données, conteneurs, configurer le débit, gérer RBAC
• SDK du plan de données (Microsoft.Azure.Cosmos) : Opérations CRUD sur les documents, requêtes, exécution de procédures stockées

Installation

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

Versions actuelles : Stable v1.4.0, Preview v1.4.0-beta.13

Variables d'environnement

AZURE_SUBSCRIPTION_ID=<your-subscription-id>
# Pour l'authentification par principal de service (optionnel)
AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

Authentification

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

// Toujours utiliser DefaultAzureCredential
var credential = new DefaultAzureCredential();
var armClient = new ArmClient(credential);

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

Hiérarchie des ressources

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

Flux de travail principal

1. Créer un compte Cosmos DB

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

// Obtenir le groupe de ressources
var resourceGroup = await subscription
    .GetResourceGroupAsync("my-resource-group");

// Définir le compte
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
};

// Créer le compte (opération longue durée)
var accountCollection = resourceGroup.Value.GetCosmosDBAccounts();
var operation = await accountCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-cosmos-account",
    accountData);

CosmosDBAccountResource account = operation.Value;

2. Créer une base de données 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. Créer un conteneur 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 heures
    });

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

CosmosDBSqlContainerResource container = containerOperation.Value;

4. Configurer le débit

// Débit manuel
var throughputData = new ThroughputSettingsUpdateData(
    new ThroughputSettingsResourceInfo
    {
        Throughput = 400
    });

// Débit autoscale
var autoscaleData = new ThroughputSettingsUpdateData(
    new ThroughputSettingsResourceInfo
    {
        AutoscaleSettings = new AutoscaleSettingsResourceInfo
        {
            MaxThroughput = 4000
        }
    });

// Appliquer à la base de données
await database.CreateOrUpdateCosmosDBSqlDatabaseThroughputAsync(
    WaitUntil.Completed,
    throughputData);

5. Obtenir les informations de connexion

// Obtenir les clés
var keys = await account.GetKeysAsync();
Console.WriteLine($"Primary Key: {keys.Value.PrimaryMasterKey}");

// Obtenir les chaînes de connexion
var connectionStrings = await account.GetConnectionStringsAsync();
foreach (var cs in connectionStrings.Value.ConnectionStrings)
{
    Console.WriteLine($"{cs.Description}: {cs.ConnectionString}");
}

Référence des types clés

Bonnes pratiques

1. Utiliser WaitUntil.Completed pour les opérations qui doivent se terminer avant de continuer
2. Utiliser WaitUntil.Started quand vous voulez interroger manuellement ou exécuter des opérations en parallèle
3. Toujours utiliser DefaultAzureCredential — ne jamais coder les clés en dur
4. Gérer RequestFailedException pour les erreurs API ARM
5. Utiliser CreateOrUpdateAsync pour les opérations idempotentes
6. Naviguer la hiérarchie via les méthodes Get* (ex. account.GetCosmosDBSqlDatabases())

Gestion des erreurs

using Azure;

try
{
    var operation = await accountCollection.CreateOrUpdateAsync(
        WaitUntil.Completed, accountName, accountData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    Console.WriteLine("Account already exists");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}

Fichiers de référence

SDKs connexes