Cette page décrit comment Metronome prend en charge l’idempotence afin que vous puissiez réessayer les requêtes en toute sécurité sans créer de doublons. L’idempotence garantit que des opérations comme la création de clients ou l’ingestion d’événements d’utilisation aboutissent exactement une fois, même lorsque les requêtes sont retentées en raison de problèmes réseau, de délais d’expiration ou de la logique du client.
Metronome fournit des mécanismes d’idempotence intégrés pour que vous puissiez réessayer les requêtes en toute sécurité sans introduire de données superflues.
Metronome utilise différents mécanismes d’idempotence selon le type de données :
| Méthode | Lieu d’utilisation | Portée | Comportement en cas de conflit | Rétention |
|---|
| Transaction ID | Ingestion d’événements (/ingest, Segment) | Événements d’utilisation | Ignore les événements ultérieurs avec le même ID | 34 jours |
| Ingest alias | Écritures sur les clients (création ou mise à jour) | Clients | Renvoie 409 Conflict si l’ingest alias est déjà utilisé | Jusqu’à libération |
uniqueness_key | Création de ressources | Ressources sélectionnées (voir ci-dessous) | Renvoie 409 Conflict | Jusqu’à libération (disponible uniquement pour les Alerts) |
En-tête Idempotency-Key | Requêtes API POST | Cache de requêtes | Renvoie 409 Conflict si les paramètres diffèrent | ≥ 24 heures |
Ingestion d’événements
Les événements d’utilisation sont diffusés vers Metronome à grande échelle. Pour éviter les doublons, Metronome utilise le champ transaction_id comme clé d’idempotence.
Une fois qu’un événement d’utilisation a été accepté avec un identifiant de transaction donné, Metronome ignore les événements ultérieurs portant le même identifiant de transaction au cours des 34 jours suivants. Cela vous permet de réessayer l’envoi d’événements en toute sécurité sans risque de duplication.
Ingest aliases
Les ingest aliases mappent vos identifiants client internes à un ID client Metronome. Lorsque vous envoyez de l’utilisation indexée sur un ingest alias, Metronome l’associe automatiquement au bon client.
Les ingest aliases sont également idempotents par nature, ce qui empêche la création d’entités client en double ou d’enregistrements conflictuels.
DÉPLACEMENT DES INGEST ALIASESEn raison de la nature idempotente des ingest aliases, vous ne pouvez déplacer un ingest alias entre clients que si vous le retirez d’abord du client d’origine. Cette règle s’applique aux clients archivés comme actifs.
Requêtes API
Metronome prend en charge deux méthodes pour garantir l’idempotence via l’API REST :
- Utilisation de uniqueness keys (sur certains endpoints)
- Utilisation de l’en-tête Idempotency-Key
Uniqueness keys
Metronome prend en charge l’idempotence pour les ressources couramment créées dans Metronome en acceptant un champ uniqueness_key dans la charge utile de la requête. Cette uniqueness key est stockée dans la ressource au sein de Metronome, et Metronome garantit qu’aucune ressource ne peut partager la même uniqueness key. Si vous tentez de créer une ressource avec une uniqueness key déjà utilisée, vous recevez une erreur HTTP 409 Conflict avec le message « This uniqueness key has already been used. »
Exemples de ressources avec uniqueness keys :
- Contract
- Alert
- Commits et credits au niveau du client
- Modifications de contrat [bientôt disponible]
En-tête Idempotency-Key
Metronome recommande d’utiliser un en-tête Idempotency-Key pour les endpoints qui n’incluent pas de uniqueness key dédiée. Metronome prend en charge l’envoi d’un en-tête Idempotency-Key pour tous les endpoints POST. Si l’en-tête Idempotency-Key est fourni et que la requête commence à s’exécuter (elle passe la validation et n’entre pas en conflit avec une autre requête concurrente), les résultats de l’appel d’API sont persistés et les mêmes résultats sont renvoyés.
Comportement :
- Les clés doivent être uniques par requête
- Une nouvelle tentative avec la même clé et des paramètres identiques renvoie le résultat d’origine.
- Une nouvelle tentative avec la même clé mais des paramètres différents renvoie HTTP
409 Conflict.
- Metronome conserve les clés d’idempotence pendant au moins 24 heures.
- L’idempotence s’applique même si une requête renvoie une erreur HTTP 500, ce qui signifie que Metronome met en cache et renvoie l’erreur
Comprendre l’idempotence avec les erreurs :
Lorsqu’une requête avec l’en-tête Idempotency-Key renvoie une erreur, Metronome met l’erreur en cache et la renvoie pour les nouvelles tentatives ultérieures utilisant la même clé d’idempotence. Ce comportement suit les meilleures pratiques du secteur — lorsqu’une opération échoue en cours d’exécution, les nouvelles tentatives sans examen manuel peuvent aggraver la situation. Dans ces cas, Metronome met en cache et renvoie l’erreur pour s’assurer que vous voyez l’échec de manière cohérente, étudiez l’état du système et décidez s’il faut réessayer ou résoudre manuellement.
Bonnes pratiques
- Générez des clés déterministes pour l’idempotence basée sur les ressources : dérivez les clés de la logique métier (par exemple, hash de l’ID externe et du type d’opération) afin que les nouvelles tentatives réutilisent toujours la même clé.
- Utilisez des clés aléatoires lorsque c’est approprié : générez des UUID si vous n’avez pas besoin de clés déterministes (par exemple, en-tête
Idempotency-Key).
- Adaptez les nouvelles tentatives à la durée de vie de la clé :
- Événements d’utilisation : réessayez dans les 34 jours.
- Écritures API REST : réessayez dans les 24 heures.
- Préférez les uniqueness keys lorsqu’elles sont disponibles : utilisez
uniqueness_key pour la création de ressources comme les contrats plutôt que l’en-tête Idempotency-Key.
- Mettez en œuvre des nouvelles tentatives sûres : réessayez toujours avec un backoff exponentiel et réutilisez la même clé.
