Mise à jour partielle de document dans Azure Cosmos DB

S’APPLIQUE À : NoSQL

La fonctionnalité Mise à jour partielle de document Azure Cosmos DB (également appelée API Patch) offre un moyen pratique de modifier un document dans un conteneur. Actuellement, pour mettre à jour un document dont le client a besoin pour le lire, il faut exécuter des vérifications de contrôle d’accès concurrentiel optimiste (si nécessaire), mettre à jour le document localement, puis l’envoyer en tant qu’appel d’API de remplacement de document entier.

La fonctionnalité de mise à jour partielle de document améliore cette expérience de manière significative. Le client peut juste envoyer les propriétés/champs modifiés dans un document sans effectuer une opération de remplacement de document entier. Les principaux avantages de cette fonctionnalité sont les suivants :

• Amélioration de la productivité des développeurs : fournit une API pratique pour faciliter l’utilisation et pouvoir mettre à jour le document de manière conditionnelle.
• Améliorations des performances : évite des cycles de processeur supplémentaires côté client et réduit la latence et la bande passante réseau de bout en bout.
• Écritures multirégions : prend en charge la résolution automatique et transparente des conflits avec des mises à jour partielles sur des chemins discrets dans le même document.

Exemple de document JSON cible :

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

Document de correctif JSON :

[
  { "op": "add", "path": "/color", "value": "silver" },
  { "op": "remove", "path": "/used" },
  { "op": "set", "path": "/price", "value": 355.45 }
  { "op": "incr", "path": "/inventory/quantity", "value": 10 },
  { "op": "add", "path": "/tags/-", "value": "featured-bikes" },
  { "op": "move", "from": "/color", "path": "/inventory/color" }
]

Document JSON obtenu :

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Opérations prises en charge

Ce tableau récapitule les opérations prises en charge par cette fonctionnalité.

Modes pris en charge

La fonctionnalité de mise à jour partielle de document prend en charge les modes de fonctionnement suivants. Consultez le document Bien démarrer pour obtenir des exemples de code.

• Patch monodocument : Vous pouvez appliquer un patch à un seul document en fonction de son identifiant et de la clé de partition. Il est possible d’exécuter plusieurs opérations de patch sur un seul document. La limite maximale est de 10 opérations.

• Patch multi-document : Vous pouvez appliquer un patch à plusieurs documents dans la même clé de partition dans le cadre d’une transaction. Cette transaction multi-documents est validée seulement si toutes les opérations réussissent dans l’ordre dans lequel elles sont décrites. Si une opération échoue, la totalité de la transaction est restaurée.

• Mise à jour conditionnelle : pour les modes susmentionnés, il est également possible d’ajouter un prédicat de filtre de type SQL (par exemple, from c where c.taskNum = 3) de sorte que l’opération échoue si la précondition spécifiée dans le prédicat n’est pas remplie.

• Vous pouvez également utiliser les API en bloc des kits SDK pris en charge pour exécuter une ou plusieurs opérations de patch sur plusieurs documents.

Similitudes et différences

Comparons les similitudes et les différences entre les modes pris en charge.

Add vs. Set

L’opération Set est similaire à l’opération Add pour tous les types de données, sauf Array. Une opération Add à un index (valide) entraîne l’ajout d’un élément à l’index spécifié et tous les éléments existants dans le tableau sont décalés après l’élément existant. Ce comportement diffère de l’opération Set qui met à jour l’élément existant à l’index spécifié.

Add ou Replace

L’opération Add ajoute une propriété si celle-ci n’existe pas déjà (y compris le type de données Array). L’opération Replace échoue si la propriété n’existe pas (s’applique également au type de données Array).

Set vs. Replace

L’opération Set ajoute une propriété si celle-ci n’existe pas déjà (sauf s’il y avait un Array). L’opération Replace échoue si la propriété n’existe pas (s’applique également au type de données Array).

Référence de l’API REST pour la mise à jour partielle d’un document

L’API REST d’Azure Cosmos DB fournit un accès programmatique aux ressources d’Azure Cosmos DB pour créer, interroger et supprimer des bases de données, des collections de documents et des documents. Outre l’exécution d’opérations d’insertion, de remplacement, de suppression, de lecture, d’énumération et d’interrogation sur les documents JSON d’une collection, vous pouvez utiliser la méthode HTTP PATCH pour l’opération de mise à jour partielle d’un document. Pour plus d’informations, consultez les informations de référence relatives à l’API REST d’Azure Cosmos DB.

Par exemple, voici à quoi ressemble la requête pour une opération set à l’aide de la mise à jour partielle d’un document.

PATCH https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1 HTTP/1.1
x-ms-documentdb-partitionkey: ["Andersen"]
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT
Authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Content-Type:application/json_patch+json
Cache-Control: no-cache
User-Agent: Microsoft.Azure.DocumentDB/2.16.12
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=602; x-ms-session-token=602
Content-Length: calculated when request is sent
Connection: keep-alive

{
  "operations": [
    {
      "op": "set",
      "path": "/Parents/0/FamilyName",
      "value": "Bob"
    }
  ]
}

Résolution des conflits au niveau du document vs. au niveau du chemin

Si votre compte Azure Cosmos DB est configuré avec plusieurs régions d’écriture, des conflits et des stratégies de résolution des conflits sont applicables au niveau du document, LWW (Last Write Wins) étant la stratégie de résolution des conflits par défaut. Pour les mises à jour partielles de document, les opérations de patch sur plusieurs régions détectent et résolvent les conflits à un niveau de chemin plus précis.

Un exemple permet de mieux comprendre la résolution de conflits.

Supposons que vous ayez le document suivant dans Azure Cosmos DB :

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345", "67890"],
  "level": "gold"
}

Différents clients émettent des opérations de correctif simultanément dans différentes régions :

• Set attribue /level sur platinum
• Remove 67890 de /phone

Étant donné que les requêtes de patch ont été faites sur des chemins non conflictuels dans le document, les conflits de ces requêtes sont résolus de manière automatique et transparente, contrairement à la stratégie Last Writer Wins (LWW) au niveau du document.

Le client verra le document suivant après la résolution des conflits :

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345"],
  "level": "platinum"
}

Modifier le flux

Le flux de modification dans Azure Cosmos DB écoute un conteneur pour toutes les modifications, puis génère les documents qui ont été modifiés. À l’aide du flux de modification, vous voyez toutes les mises à jour des documents, y compris les mises à jour partielles et complètes des documents. Lorsque vous traitez des éléments à partir du flux de modification, le document complet est retourné même si la mise à jour résulte d’une opération de correctif.

Pour plus d’informations sur le flux de modification dans Azure Cosmos DB, consultez Flux de modification dans Azure Cosmos DB.

Étapes suivantes

• Découvrir comment démarrer avec la Mise à jour partielle de document en utilisant .NET, Java et Node
• Questions fréquentes sur la Mise à jour partielle de document