Cosmos DB : premiers pas avec az CLI, PowerShell, l'émulateur et les sauvegardes
Créer compte, base et conteneur, insérer et interroger des items, bases de l'indexation, émulateur local et sauvegardes périodique ou continue.
Après la théorie, mes premiers pas pratiques : créer un compte, une base et un conteneur en ligne de commande, insérer et interroger des items, regarder la politique d'indexation, lancer l'émulateur en local et comprendre les sauvegardes. Je n'ai gardé que des commandes et paramètres que j'ai retrouvés dans la documentation Microsoft. Noms génériques : rg-cosmos-dev, cosmos-contoso-dev, AppDb, orders.
Créer le compte, la base et le conteneur avec az CLI
az group create --name rg-cosmos-dev --location westeurope
az cosmosdb create --name cosmos-contoso-dev --resource-group rg-cosmos-dev `
--default-consistency-level Session `
--locations regionName=westeurope failoverPriority=0 isZoneRedundant=False
az cosmosdb sql database create --account-name cosmos-contoso-dev `
--resource-group rg-cosmos-dev --name AppDb
az cosmosdb sql container create --account-name cosmos-contoso-dev `
--resource-group rg-cosmos-dev --database-name AppDb --name orders `
--partition-key-path "/customerId" --throughput 400
Le nom du compte doit être en minuscules et faire moins de 44 caractères. Pour de l'autoscale, remplacer --throughput par --max-throughput (la doc CLI indique une valeur minimale de 4000). Pour du serverless, on crée le compte avec --capabilities EnableServerless et on ne passe aucun débit au conteneur.
La même chose avec PowerShell (Az.CosmosDB)
$loc = New-AzCosmosDBLocationObject -LocationName "West Europe" -FailoverPriority 0 -IsZoneRedundant 0
$account = New-AzCosmosDBAccount -ResourceGroupName "rg-cosmos-dev" `
-LocationObject $loc -Name "cosmos-contoso-dev" -ApiKind "Sql" `
-DefaultConsistencyLevel "Session" -EnableAutomaticFailover:$true
$db = New-AzCosmosDBSqlDatabase -ParentObject $account -Name "AppDb"
New-AzCosmosDBSqlContainer -ParentObject $db -Name "orders" `
-PartitionKeyKind Hash -PartitionKeyPath "/customerId" -Throughput 400
New-AzCosmosDBSqlContainer accepte aussi -AutoscaleMaxThroughput à la place de -Throughput.
Insérer et interroger des items
L'az CLI gère les ressources (plan de contrôle), pas les items. Pour les données : l'explorateur de données du portail, un SDK, ou Cosmos DB Shell. Un exemple avec le SDK Python :
from azure.cosmos import CosmosClient
client = CosmosClient(endpoint, credential) # endpoint + clé, ou identité Entra
container = client.get_database_client("AppDb").get_container_client("orders")
container.create_item({"id": "o-1001", "customerId": "C42", "status": "paid", "total": 129.9})
# Lecture par point : id + clé de partition, la moins chère (environ 1 RU pour 1 Ko)
item = container.read_item(item="o-1001", partition_key="C42")
# Requête : syntaxe SQL du NoSQL, "c" est l'alias du conteneur
rows = list(container.query_items(
query="SELECT c.id, c.total FROM c WHERE c.customerId = @cid AND c.status = @st",
parameters=[{"name": "@cid", "value": "C42"}, {"name": "@st", "value": "paid"}]))
Ce que je retiens :
SELECT ... FROM c WHERE ...ressemble à du SQL, mais travaille sur des documents JSON ;SELECT VALUE COUNT(1) FROM ccompte les items.- Une requête qui filtre sur
id+ clé de partition n'est pas une lecture par point : seule l'opération de lecture du SDK/REST l'est. - Mettre la clé de partition dans le
WHEREévite le fan-out inter-partitions. - Dans le portail, « Query Stats » donne le coût en RU.
Politique d'indexation : les bases
Par défaut, un conteneur est en mode consistent et indexe toutes les propriétés (/*), ce qui est pratique en développement mais coûte des RU à chaque écriture. On peut exclure des chemins ou ajouter des index composites :
{
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [ { "path": "/*" } ],
"excludedPaths": [ { "path": "/notes/?" }, { "path": "/\"_etag\"/?" } ],
"compositeIndexes": [
[ { "path": "/customerId", "order": "ascending" },
{ "path": "/total", "order": "descending" } ]
]
}
On l'applique à la création avec --idx @policy.json (ou via az cosmosdb sql container update --idx). Réflexe de production : n'indexer que les propriétés réellement filtrées ou triées.
L'émulateur local
Pour développer sans abonnement, il existe un émulateur. La version Linux « vNext » tourne dans Docker :
docker run --detach --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
- Le point d'accès est
http://localhost:8081, l'explorateur de données surhttp://localhost:1234, la sonde de santé sur le port 8080. - Les SDK .NET et Java ne supportent pas le mode HTTP : démarrer avec
--protocol https. - Limites : API NoSQL uniquement, pas d'authentification appliquée, les RU ne sont pas implémentées, et seuls les index vectoriels DiskANN sont pris en compte (les autres politiques d'indexation sont acceptées mais n'optimisent rien). Il ne remplace donc pas un test sur un vrai compte pour le coût et l'indexation.
- Il existe aussi un émulateur Windows (provisionné uniquement, pas de serverless).
Sauvegardes : périodique ou continue
| Périodique (défaut) | Continue | |
|---|---|---|
| Principe | Sauvegarde complète toutes les 4 h, 2 copies conservées par défaut | Restauration à tout instant (point-in-time) |
| Réglages | Intervalle (minimum 1 h) et rétention (jusqu'à un mois) | Paliers Continuous7Days, Continuous30Days, Continuous35Days |
| Restauration | Demande au support, dans un nouveau compte | Libre-service (portail, PowerShell, CLI) |
La sauvegarde continue se choisit à la création et ne peut pas revenir à périodique ; on peut migrer de périodique vers continu. Elle exige un compte à une seule région d'écriture, en API NoSQL/MongoDB (ou Table/Gremlin).
az cosmosdb create --name cosmos-contoso-dev --resource-group rg-cosmos-dev \
--backup-policy-type Continuous --continuous-tier "Continuous7Days" \
--default-consistency-level Session --locations regionName="West Europe"
New-AzCosmosDBAccount -ResourceGroupName "rg-cosmos-dev" -Location "West Europe" `
-BackupPolicyType Continuous -ContinuousTier Continuous7Days `
-Name "cosmos-contoso-dev" -ApiKind "Sql"
Pour auditer le mode de sauvegarde de tous les comptes, une requête Azure Resource Graph sur microsoft.documentdb/databaseaccounts et properties.backupPolicy.type suffit.
Retour d'expérience
- Créer le compte avec le bon mode de sauvegarde dès le départ.
- Choisir la clé de partition avant le premier conteneur : elle ne se change pas.
- Les clés de compte sont des secrets : préférer l'authentification Microsoft Entra, et ne jamais les mettre dans un script versionné.
- Supprimer le groupe de ressources de test pour éviter les frais.