Modes de flux de modification dans Azure Cosmos DB

S’APPLIQUE À : NoSQL

Azure Cosmos DB offre deux modes de flux de modification. Chaque mode offre les mêmes fonctionnalités de base. Les différences incluent les opérations capturées dans le flux, les métadonnées disponibles pour chaque modification et la période de rétention des modifications. Vous pouvez utiliser le flux de modification dans différents modes dans plusieurs applications pour le même conteneur Azure Cosmos DB afin de répondre aux exigences de chaque charge de travail. Chaque application de flux de modification individuelle ne peut être configurée pour lire le flux de modification que dans un seul mode. L’utilisation du flux de modification dans un mode ne vous empêche pas d’utiliser le flux de modification dans un autre mode dans une autre application.

Remarque

Avez-vous des commentaires sur les modes de flux de modification ? Nous attendons vos remarques ! N’hésitez pas à partager vos commentaires directement avec l’équipe d’ingénieurs Azure Cosmos DB : cosmoschangefeed@microsoft.com.

Mode de flux de modification de dernière version

Le mode dernière version est un enregistrement persistant des modifications apportées aux éléments à partir des créations et des mises à jour. Vous obtenez la dernière version de chaque élément dans le conteneur. Par exemple, si un élément est créé, puis mis à jour avant de lire le flux de modification, seule la version mise à jour apparaît dans le flux de modification. Les suppressions ne sont pas capturées en tant que modifications, et lorsqu’un élément est supprimé, il n’est plus disponible dans le flux. Le mode de flux de modification de dernière version est activé par défaut et est compatible avec tous les comptes Azure Cosmos DB, à l’exception de l’API pour Table et de l’API pour PostgreSQL. Ce mode était auparavant la méthode par défaut pour utiliser le flux de modification.

Mode de flux de modification Toutes les versions et suppressions (préversion)

Le mode Toutes les versions et suppressions (préversion) est un enregistrement persistant de toutes les modifications apportées aux éléments à partir des opérations de création, de mise à jour et de suppression. Vous obtenez un enregistrement de chaque modification apportée aux éléments dans l’ordre dans lequel elles se sont produites, y compris les modifications intermédiaires apportées à un élément entre les lectures du flux de modification. Par exemple, si un élément est créé, puis mis à jour avant de lire le flux de modification, les versions de création et de mise à jour de l’élément apparaissent toutes deux dans le flux de modification. Pour lire à partir du flux de modification en mode Toutes les versions et en suppressions, vous devez configurer des sauvegardes continues pour votre compte Azure Cosmos DB. L’activation des sauvegardes continues crée le flux de modification Toutes les versions et suppressions. Vous pouvez uniquement lire les modifications qui se sont produites pendant la période de sauvegarde continue lors de l’utilisation de ce mode de flux de modification. Ce mode est uniquement compatible avec les comptes Azure Cosmos DB for NoSQL. En savoir plus sur la façon de s’inscrire à la préversion.

Cas d’utilisation du flux de modification

Mode Dernière version

Le mode dernière version permet de traiter facilement les modifications en temps réel et historiques des éléments d’un conteneur, avec la possibilité de revenir aux modifications depuis le début du conteneur.

Voici des scénarios bien adaptés à ce mode :

• Migrations d’un conteneur entier vers un emplacement secondaire.

• Possibilité de retraiter les modifications à partir du début du conteneur.

• Traitement en temps réel des modifications apportées aux éléments d’un conteneur résultant d’opérations de création et de mise à jour.

• Charges de travail qui n’ont pas besoin de capturer les suppressions ou les modifications intermédiaires entre les lectures.

Mode Toutes les versions et suppressions (préversion)

Le mode de flux de modification Toutes les versions et suppressions permet de nouveaux scénarios pour le flux de modification et en simplifie d’autres. Vous pouvez lire chaque modification apportée aux éléments (même dans les cas où plusieurs modifications se sont produites entre les lectures de flux de modification), identifier le type d’opération des modifications en cours de traitement et obtenir les modifications qui résultent des suppressions.

Voici quelques scénarios courants rendus possibles et améliorés par ce mode :

• Transfert de données en temps réel entre deux emplacements sans implémentation d’une suppression réversible.

• Déclenchement d’une logique basée sur des modifications incrémentielles si plusieurs opérations de modification pour un élément donné sont attendues entre les vérifications du flux de modification.

• Déclenchement d’alertes lors d’opérations de suppression, comme dans les scénarios d’audit.

• Possibilité de traiter les créations, les mises à jour et les suppressions d’éléments différemment en fonction du type d’opération.

Fonctionnalités de chaque mode

En plus des fonctionnalités communes à tous les modes de flux de modification, chaque mode de flux de modification présente les caractéristiques suivantes :

Mode Dernière version

• Le flux de modification inclut les opérations d’insertion et de mise à jour qui sont apportées aux éléments du conteneur.

• Ce mode de flux de modification ne consigne pas les suppressions. Vous pouvez capturer les suppressions en définissant un indicateur de « suppression réversible » dans vos éléments au lieu de les supprimer directement. Par exemple, vous pouvez ajouter un attribut dans l’élément appelé deleted avec la valeur true, et ensuite définir une durée de vie (TTL) sur l’élément. Le flux de modification le capture sous forme de mise à jour et l’élément est automatiquement supprimé lorsque la durée de vie expire. Vous pouvez également définir un délai d’expiration fixe pour vos éléments en utilisant la fonctionnalité TTL. Avec cette solution, vous devez traiter les modifications dans un intervalle de temps inférieur à la période d’expiration de durée de vie.

• Seule la dernière modification d’un élément spécifique est incluse dans le flux de modification. Les modifications intermédiaires peuvent ne pas être disponibles.

• Lorsqu’un élément est supprimé, il n’est plus disponible dans le flux de modification.

• Les modifications peuvent être synchronisées à partir de n’importe quel point dans le temps, et il n’existe aucune période fixe de conservation des données pendant laquelle les modifications sont disponibles.

• Vous ne pouvez pas filtrer le flux de modification pour un type d’opération spécifique. Une alternative possible consiste à ajouter un « marqueur réversible » sur l’élément pour les mises à jour et à filtrer les résultats en fonction de ce marqueur lorsque vous traitez les éléments dans le flux de modification.

• Le point de départ pour lire le flux de modification peut se situer au début du conteneur, à un instant donné, « maintenant » ou à un point de contrôle spécifique. La précision de l’heure de début est d’environ cinq secondes.

Mode Toutes les versions et suppressions (préversion)

• Le flux de modification inclut les opérations d’insertion, de mise à jour et de suppression apportées aux éléments du conteneur. Les suppressions suite aux expirations de durée de vie sont également capturées.

• Des métadonnées sont fournies pour déterminer le type de modification, notamment si une suppression résulte de l’expiration de la durée de vie.

• Les éléments du flux de modification figurent dans l’ordre où ils ont été modifiés. Il n’est pas garanti que les suppressions suite aux expirations de durée de vie apparaissent dans le flux immédiatement après l’expiration de l’élément. Elles apparaissent lorsque l’élément est vidé du conteneur.

• Tous les changements qui se sont produits au cours de la fenêtre de conservation définie pour les sauvegardes continues sur le compte peuvent être lus. Toute tentative de lecture des modifications qui se sont produites en dehors de la fenêtre de rétention génère une erreur. Par exemple, si votre conteneur a été créé il y a huit jours et que la période de rétention de la période de sauvegarde continue est de sept jours, vous pouvez uniquement lire les modifications des sept derniers jours.

• Le point de départ du flux de modification peut être « maintenant » ou à partir d’un point de contrôle spécifique au cours de votre période de rétention. Vous ne pouvez pas lire les modifications depuis le début du conteneur ou depuis un instant précis en utilisant ce mode.

Utilisez le flux de modification

Chaque mode est compatible avec différentes méthodes pour lire le flux de modification pour chaque langage.

Mode Dernière version

Vous pouvez utiliser les méthodes suivantes pour consommer les modifications du flux de modification en mode dernière version :

Méthode pour lire le flux de modification	.NET	Java	Python	Node.JS
Modèle de tirage (pull) du flux de modification	Oui	Oui	Oui	Oui
Processeur de flux de modification	Oui	Oui	No	Non
Déclencheur Azure Functions	Oui	Oui	Oui	Oui

Analysez l’objet de réponse

En mode dernière version, l’objet de réponse par défaut est un tableau des éléments qui ont changé. Chaque élément contient les métadonnées standard pour tout élément Azure Cosmos DB, y compris _etag et _ts avec l’ajout d’une nouvelle propriété, _lsn.

Le format _etag est un format interne. Vous ne devez pas vous y fier, car il peut être modifié à tout moment. _ts correspond à un horodatage de modification ou de création. Vous pouvez utiliser les données _ts à des fins de comparaison chronologique. Le format _lsn est un ID de lot qui est ajouté uniquement pour le flux de modification. Il représente l’ID de transaction. De nombreux éléments peuvent avoir un même _lsn.

ETag de FeedResponse est différent du _etag que vous voyez sur l’élément. _etag est un identificateur interne, utilisé pour le contrôle d’accès concurrentiel. La propriété _etag représente la version de l’élément, tandis que la propriété ETag est utilisée pour séquencer le flux.

Mode Toutes les versions et suppressions (préversion)

Pendant la préversion, les méthodes suivantes pour lire le flux de modification sont disponibles pour chaque SDK client :

Méthode pour lire le flux de modification	.NET	Java	Python	Node.JS
Modèle de tirage (pull) du flux de modification	>= 3.32.0-preview	>= 4.42.0	Non	>= 4.1.0
Processeur de flux de modification	>= 3.40.0-preview.0	>= 4.42.0	Non	Non
Déclencheur Azure Functions	Non	Non	Non	N°

Notes

Quel que soit le mode de connexion configuré dans votre application, toutes les requêtes effectuées avec le flux de modification Toutes les versions et suppressions utilisent le mode passerelle.

Prise en main

Pour commencer à utiliser le mode de flux de modification Toutes les versions et suppressions, inscrivez-vous à la préversion via la page Fonctionnalités en préversion de la page Vue d’ensemble de votre abonnement Azure. Recherchez la fonctionnalité AllVersionsAndDeletesChangeFeed, puis sélectionnez S’inscrire.

Avant d’envoyer votre demande, vérifiez que vous avez au moins un compte Azure Cosmos DB dans l’abonnement. Ce compte peut être un compte existant ou un nouveau compte que vous avez créé pour tester la fonctionnalité d’évaluation. Si vous n’avez pas de compte dans l’abonnement au moment où votre demande est reçue, celle-ci est refusée parce qu’il n’y a aucun compte auquel appliquer la fonctionnalité.

L’équipe d’Azure Cosmos DB examine votre requête et vous contacte par e-mail pour confirmer les comptes Azure Cosmos DB de l’abonnement que vous souhaitez inscrire à la préversion. Pour utiliser la préversion, vous devez avoir configuré les sauvegardes continues pour votre compte Azure Cosmos DB. Les sauvegardes continues peuvent être activées avant ou après avoir été admises dans la préversion, mais les sauvegardes continues doivent être activées avant que vous n’essayiez de lire le flux de modifications du mode Toutes les versions et toutes les suppressions.

Analysez l’objet de réponse

L’objet réponse est un tableau d’éléments qui représentent chaque modification. Différentes propriétés sont remplies en fonction du type de changement. Il n’y a actuellement aucun moyen d’obtenir la version précédente des éléments pour les opérations de remplacement ou de suppression.

• Opérations de création

  {
    "current": {
      <The current version of the item that changed. All the properties of your item will appear here.>
    },
    "metadata": {
      "operationType": "create",
      "lsn": <A number that represents the batch ID. Many items can have the same lsn.>,
      "crts": <A number that represents the Conflict Resolved Timestamp. It has the same format as _ts.>
    }
  }
  

• Opérations de remplacement

  {
    "current": {
      <The current version of the item that changed. All the properties of your item will appear here.>
    },
    "metadata": {
      "operationType": "replace",
      "lsn": <A number that represents the batch ID. Many items can have the same lsn.>,
      "crts": <A number that represents the Conflict Resolved Timestamp. It has the same format as _ts.>,
      "previousImageLSN" : <A number that represents the batch ID of the change prior to this one.>,
    }
  }
  

• Opérations de suppression

  {
    "metadata": {
      "operationType": "delete",
      "lsn": <A number that represents the batch ID. Many items can have the same lsn.>,
      "crts": <A number that represents the Conflict Resolved Timestamp. It has the same format as _ts.>,
      "previousImageLSN" : <A number that represents the batch ID of the change prior to this one.>,
      "id": "<Id of the deleted item.>",
      "partitionKey": {
        "<Partition key property name>": "<Partition key property value>"
      }
    }
  }
  

Limites

• Pris en charge pour les comptes Azure Cosmos DB pour NoSQL. Les autres types de comptes Azure Cosmos DB ne sont pas pris en charge.

• Des sauvegardes continues sont requises pour utiliser ce mode de flux de modification. Vous trouverez les limitations de l’utilisation de la sauvegarde continue dans la documentation.

• La lecture des modifications sur un conteneur qui existait avant l’activation des sauvegardes continues sur le compte n’est pas prise en charge.

• La possibilité de commencer à lire le flux de modification à partir du début ou de sélectionner une heure de début en fonction d’un horodatage passé n’est pas prise en charge actuellement. Vous pouvez commencer à partir de « maintenant » ou à partir d’un bail ou d’un jeton de continuation précédent.

• La réception de la version précédente des éléments qui ont été supprimés ou mis à jour n’est actuellement pas disponible.

• Les comptes qui ont activé la fusion de partitions ne sont pas pris en charge.

Étapes suivantes

Apprenez-en davantage sur le flux de modification dans les articles suivants :

• Vue d’ensemble du flux de modification
• Modèles de conception des flux de modification
• Options de lecture du flux de modification