Développez avec le SDK Durable Task for Go

En utilisant le SDK Durable Task for Go, vous pouvez définir les orchestrations, activités et entités durables comme des fonctions Go. Hébergez l’application sur votre propre plateforme informatique. Le Durable Task Scheduler stocke l’historique d’exécution et transmet le travail à vos workers Go.

Important

Le SDK Go est en bêta. Cet article et le démarrage rapide de Go utilisent la version 1.0.0-beta3. La bêta n’est pas un remplacement direct de la v0.6.0 : elle ne prend pas en charge les backends SQLite et PostgreSQL embarqués ni l’hôte autonome gRPC. Go n'est pas un langage pris en charge par Durable Functions.

Conditions requises et installation

Installez la version bêta publiée depuis un module Go existant :

go get github.com/microsoft/durabletask-go@v1.0.0-beta3

Après avoir ajouté des importations SDK à votre code, exécutez go mod tidy pour enregistrer les dépendances transitives et les sommes de contrôle.

Pour une application complète qui lance un travailleur, planifie des activités parallèles, lit leurs résultats et s'arrête proprement, voir Créer une application avec SDK Durable Task - Go.

Modèle de programmation

Le SDK est livré comme un seul module Go. Ses principaux paquets sont :

Package Purpose
task Orchestration, activité et contextes d’entités ; inscription des tâches ; primitives de workflow durables.
durabletaskscheduler Options de connexion et connexions distinctes pour le client et le worker à Durable Task Scheduler.
client Configuration des travailleurs, y compris le traitement simultané, le versionnement et les filtres des éléments de travail.
api IDs d’instance et d’entité, métadonnées d’orchestration et options de requête de gestion.

Un orchestrateur a la signature func(*task.OrchestrationContext) (any, error). Une activité a la signature func(task.ActivityContext) (any, error). Une entité basée sur une fonction a pour signature func(*task.EntityContext) (any, error). Lire l’entrée typée avec GetInput, et retourner un résultat sérialisable ou une erreur. Le JSON est le format de données par défaut.

Inscrire et exécuter des tâches

Créez un registre avec task.NewTaskRegistry. Enregistrez les noms stables avec AddOrchestratorN, AddActivityN et AddEntityN, et vérifiez les erreurs d’enregistrement. Les noms utilisés lors des appels d'activité et de la planification des clients doivent correspondre aux inscriptions.

Analyse de la chaîne de connexion avec durabletaskscheduler.NewOptionsFromConnectionString. Passez les options à :

  • durabletaskscheduler.NewClient pour démarrer et gérer les instances d’orchestration.
  • durabletaskscheduler.NewWorker pour exécuter des tâches enregistrées.

Appelez Start sur le worker pour commencer à traiter les éléments de travail. Utilisez client.WithAutoWorkItemFilters() pour générer des filtres de routage des workers à partir du registre. Ne laissez pas un worker consommer des tâches enregistrées uniquement par une autre application.

Le client et le worker possèdent des connexions séparées. Fermez le client lorsque vous avez terminé. Videz le processus de travail avec Shutdown, en utilisant un nouveau contexte borné si le contexte d'exécution de l'application a expiré. Le démarrage rapide vérifie s'il y a des erreurs dans les deux opérations.

Écrire des orchestrateurs déterministes

Utilisez le contexte d'orchestration pour les opérations durables :

Operation Go API Learn more
Activités de la séquence ctx.CallActivity(...).Await(&result) Chaînage de fonctions
Déploiement et regroupement Planifiez toutes les tâches, puis ctx.WhenAll(tasks...) et lisez les résultats avec Await Fan-out/fan-in
Retarder ctx.CreateTimer(duration).Await(nil) Timers durables
Attendre un événement ctx.WaitForSingleEvent(name, timeout).Await(&result) Événements externes
Appeler un workflow enfant ctx.CallSubOrchestrator(...).Await(&result) Sous-orchestrations
Réessayer une activité task.WithActivityRetryPolicy Gestion des erreurs et réessais
Commencez un nouvel historique ctx.ContinueAsNew Orchestrations éternelles
Saisie de l’avancement ctx.SetCustomStatusValue Statut personnalisé
Appeler ou envoyer un signal à une entité ctx.CallEntity et ctx.SignalEntity Entités durables

Ne réalisez pas d’appels réseau, d’entrées/sorties de fichiers, de lectures de variables d’environnement ou d’autres travaux non déterministes dans un orchestrateur. Ajoutez ce travail aux activités. Utilisez les primitives de concurrence durable du SDK au lieu des goroutines natives, des canaux, sync.WaitGroup ou time.Sleep dans le code d’orchestrateur. Utilisez ctx.Logger() pour une journalisation compatible avec la relecture. Pour plus de détails, voir contraintes de code Orchestrator.

Les activités peuvent effectuer des entrées/sorties Go ordinaires, mais elles peuvent être exécutées plus d’une fois. Rendre les effets secondaires externes idépotents.

Lire les résultats de l'exécution

WaitForOrchestrationCompletion Un retour sans erreur signifie que l’instance a atteint un état terminal, pas nécessairement que le flux de travail a réussi. Utilisez des charges utiles de requête avec api.WithFetchPayloads(true), vérifiez que RuntimeStatus est api.RUNTIME_STATUS_COMPLETED, puis décodez la sortie avec ReadOutput.

Pour les cas échoués, inspectez FailureDetails. Ne signalez pas une orchestration ratée ou interrompue comme un résultat réussi. Voir Gestion des instances.

Connectez-vous à l’émulateur ou à Azure

Le guide de démarrage rapide utilise la chaîne de connexion Endpoint=http://localhost:8080;TaskHub=default;Authentication=None. Utilisez Authentication=None pour le développement avec un émulateur local, pas pour l’accès Azure authentifié.

Pour Azure, utilisez le point de terminaison HTTPS et le nom du hub des tâches de votre planificateur. Sélectionnez Authentication=DefaultAzure pour la chaîne d’identifiants Azure Identity, ou Authentication=AzureCLI pour un identité de développement connecté via Azure CLI. Le Go SDK prend également en charge l’identité gérée et l’identité de charge de travail. Pour les détails de configuration et les modes d’authentification pris en charge, consultez le guide de connexion Go SDK.

Le guide de démarrage rapide lit la chaîne de connexion depuis la variable d’environnement DTS_CONNECTION_STRING et la transmet à NewOptionsFromConnectionString. Le SDK ne lit pas cette variable automatiquement.

Samples

Le dépôt du SDK Go comprend des exemples exécutables pour ses domaines fonctionnels, notamment les séquences d'activité, le fan-out/fan-in, les événements externes, les nouvelles tentatives, les entités durables, les planifications, les charges utiles volumineuses, l'exportation d'historique et le traçage distribué. Pour la liste complète, les prérequis et les instructions d’exécution, voir les exemples du SDK Go.

Orchestrations de tests

Le SDK n’inclut pas de backend de stockage, donc les orchestrations s’exécutent uniquement sur Durable Task Scheduler ou son émulateur. Testez les activités et autres logiques métier avec des tests unitaires Go ordinaires. Pour vérifier le comportement de l'orchestration, y compris la relecture, effectuez des tests d'intégration sur l'émulateur ou un hub de tâches dédié.

Considérations de compatibilité bêta

  • Planifications : les planifications Go ne partagent pas leur format d'état persistant avec d'autres SDK. Utilisez un hub de tâches réservé à Go pour les tâches planifiées.
  • Verrous d’entités : Go et Python utilisent un ordre de verrou multi-entités différent de .NET. N'acquérez pas simultanément des ensembles de verrous qui se chevauchent entre les orchestrations Go/Python et .NET.
  • Rembobiner : Le worker Go rejette prudemment les historiques contenant des événements supplémentaires hors cycle de vie après l'échec d'une activité ou d'une opération fille. Une requête de rembobinage acceptée ne prouve pas la récupération ; vérifiez qu’un nouvel ID d’exécution a été généré et qu’un résultat concluant a été obtenu.
  • API de gestion des émulateurs : La liste des instances et la purge filtrée ont des limitations documentées de l’émulateur. Privilégiez le nettoyage par instance pour les exemples, et ne videz pas un hub partagé.
  • Exportation d'historique (aperçu) : utilisez un hub de tâches isolé, uniquement Go, et une destination d'exportation afin que les emplois d'exportation ne puissent pas exporter ou supprimer des données d'application non liées.

Consultez la matrice de fonctionnalités et le guide de transport du SDK Go pour des détails sur la compatibilité et le comportement du cycle de vie.

Contenu connexe

  • Dernière mise à jour :