idempotencyKey est une chaîne facultative que vous définissez sur une soumission. Renvoyez la même clé et vous obtenez la tâche créée par la première soumission ; aucun nouveau travail n’est mis en file et aucun nouveau blocage de crédits n’est posé.
Comment chaque endpoint traite une clé répétée
L’endpoint unitaire conserve une sémantique de création explicite : vous avez demandé de créer une tâche qui existe déjà, vous obtenez donc un conflit. L’erreur porte l’id de la tâche existante dans
error.details.taskId, donc une soumission sans réponse peut être récupérée en interrogeant cet id.
Grilles de localisation
L’idempotencyKey de la grille devient son id (un UUID est généré si vous l’omettez). La clé de tâche de chaque point est <grid id>:r<row>c<col>. Renvoyer la même grille sous cet id renvoie les points existants et n’admet que les points manquants. Envoyer une grille avec un autre centre, une autre taille ou un autre rayon sous le même id fait échouer les points dont les coordonnées diffèrent avec RESOURCE_ALREADY_EXISTS ; utilisez une nouvelle clé pour une nouvelle grille.
Portée et longueur
Les clés sont propres à votre compte : un autre compte peut utiliser la même chaîne sans collision avec la vôtre.
Le format UUID n’est pas obligatoire.
Rapprocher les résultats des soumissions
Si vous n’avez pas envoyé de clé,
idempotencyKey est omis de l’objet tâche, et non renvoyé à null.
Durée de vie de la clé
Une clé reste réservée pendant au moins 30 jours après la requête, y compris après la fin ou l’échec de la tâche et après la fermeture de la fenêtre de polling de 24 heures. Un404 au polling ne libère pas la clé. Utilisez la même clé pour les nouvelles tentatives réseau d’une même soumission, et une nouvelle clé (par exemple avec un suffixe :r1) pour une exécution distincte du même travail.
Étapes suivantes
Lots et grilles
Les trois endpoints de soumission en masse côte à côte.
Erreurs
Tous les codes d’erreur de requête.