LLI Wiki — My Digital Knowledge Base

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 :

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

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

Pour aller plus loin

Mastodon LLIMastodon SocialFosstodon