Migrer des files d'attente d'envoi vers Cloud Tasks (Go)

Avant de passer à la dernière version du SDK des services App Engine, consultez la présentation de la migration.

Passer aux bibliothèques clientes Cloud Tasks

Si vous préférez abandonner complètement les services groupés hérités, vous pouvez migrer votre code pour utiliser directement l'API Cloud Tasks. Vous devrez alors retravailler le code de votre application.

Avec Cloud Tasks, vous accédez au même service qu'avec l'API RPC Task Queues. Cela signifie que vous n'avez pas besoin de recréer les files d'attente d'envoi existantes ni les tâches d'envoi. Cependant, vous devez migrer le code qui crée les files d'attente d'envoi ou les tâches d'envoi ou qui interagit avec elles afin d'utiliser l'API Cloud Tasks.

Vous pouvez créer des files d'attente d'envoi et des tâches d'envoi et interagir avec elles à l'aide des API REST et RPC Cloud Tasks, de la bibliothèque cliente Cloud Tasks , de Google Cloud CLI et de la Google Cloud console. Cette page fournit des exemples d'utilisation de gcloud CLI et de la bibliothèque cliente Cloud Tasks.

Fonctionnalités non disponibles dans Cloud Tasks

Pour la migration des bibliothèques clientes Cloud Tasks, les fonctionnalités suivantes ne sont pas disponibles dans Cloud Tasks :

• Mettre en file d'attente des tâches dans les transactions Datastore
• Utiliser la bibliothèque de tâches différées au lieu d'un service de nœuds de calcul
• Utiliser des tâches dans des applications mutualisées
• Simuler avec le serveur de développement local
• Ajouter des tâches de manière asynchrone

Si vous passez à la dernière version du SDK, les fonctionnalités telles que les tâches différées, les espaces de noms et la simulation locale sont compatibles via le wrapper du SDK.

Tarifs et quotas

La migration de vos files d'attente d'envoi vers Cloud Tasks peut avoir une incidence sur les tarifs et les quotas de votre application.

Tarifs

Consultez les tarifs de Cloud Tasks pour estimer votre coût mensuel avant la migration.

Comme pour Task Queues, l'envoi de requêtes à votre application App Engine avec une cible d'envoi Cloud Tasks est sans frais. Toutefois, contrairement à Task Queues, Cloud Tasks facture les opérations effectuées, telles que la création, la suppression ou la gestion des tâches. Cela peut entraîner un coût mensuel global plus élevé que celui de la file d'attente de tâches App Engine sans frais.

Quotas

Les requêtes Cloud Tasks sont également comptabilisées dans vos quotas de requêtes App Engine.

Comme Task Queues, Cloud Tasks dispose de quotas spécifiques aux services. La migration vers Cloud Tasks modifiera probablement vos quotas.

Avant de commencer

Les sections suivantes décrivent les étapes de configuration à suivre avant de migrer vos files d'attente d'envoi vers Cloud Tasks.

Migrer les files d'attente de retrait

Avant de commencer, migrez les files d'attente de retrait avant de suivre les instructions de ce guide pour migrer les files d'attente d'envoi. La migration des files d'attente de retrait après celle des files d'attente d'envoi n'est pas recommandée, car l'utilisation obligatoire du fichier queue.yaml est susceptible de provoquer un comportement inattendu avec Cloud Tasks.

Protéger la configuration des files d'attente

Une fois le processus de migration vers Cloud Tasks lancé, la modification de votre fichier queue.yaml n'est pas recommandée et peut provoquer un comportement inattendu. Protégez la configuration de vos files d'attente contre les modifications effectuées par le fichier queue.yaml en procédant comme suit :

1. Configurez la gcloud CLI pour omettre votre fichier queue.yaml dans les déploiements ultérieurs.

   Ajoutez votre fichier queue.yaml à un fichier .gcloudignore. Pour vérifier si vous disposez déjà d'un fichier .gcloudignore, vous pouvez exécuter la commande suivante dans votre terminal à partir du répertoire de premier niveau de votre application. Cette commande renvoie le nom du fichier si celui-ci existe.

   ls -a | grep .gcloudignore

   Pour en savoir plus sur les fichiers .gcloudignore, consultez la documentation de référence sur .gcloudignore.

2. Restreignez les autorisations sur votre fichier queue.yaml.

   Suivez les bonnes pratiques décrites dans notre guide sur la sécurisation de la configuration des files d'attente.

3. Apprenez-en plus sur Cloud Tasks et le fichier queue.yaml (facultatif).

   Lorsque vous gérez la configuration de vos files d'attente à l'aide de l'API Cloud Tasks, le déploiement d'un fichier queue.yaml ignore la configuration définie par Cloud Tasks, ce qui peut provoquer un comportement inattendu. Pour en savoir plus, consultez la page Utiliser la gestion des files d'attente et utiliser queue.yaml (comparaison).

Authentifier votre application dans l'API Cloud Tasks

Vous devez authentifier votre application dans l'API Cloud Tasks. Cette section traite de l'authentification pour deux cas d'utilisation différents.

Pour développer ou tester votre application localement, nous vous recommandons d'utiliser un compte de service. Pour obtenir des instructions sur la configuration d'un compte de service et sur sa connexion à votre application, consultez la documentation sur la manière d'obtenir et de fournir les identifiants du compte de service manuellement.

Pour déployer votre application sur App Engine, vous n'avez pas besoin de fournir de nouvelle authentification. Les identifiants par défaut de l'application déduisent les informations d'authentification pour les applications App Engine.

Importer les bibliothèques clientes Cloud

Pour utiliser la bibliothèque cliente Cloud Tasks avec votre application App Engine :

1. Téléchargez la dépendance de la bibliothèque cliente Cloud Tasks :

   go get cloud.google.com/go/cloudtasks/apiv2

2. Importez les dépendances de la bibliothèque cliente Cloud Tasks dans les fichiers chargés de la création et de la mise en file d'attente des tâches :

   import (
     "context"
     "fmt"
   
     cloudtasks "cloud.google.com/go/cloudtasks/apiv2"
     taskspb "cloud.google.com/go/cloudtasks/apiv2/cloudtaskspb"
   )

Créer et gérer des files d'attente

Cette section explique comment créer et gérer des files d'attente à l'aide de l'API Cloud Tasks.

Avec Cloud Tasks, vous n'utilisez pas de fichier queue.yaml pour créer ou gérer des files d'attente. À la place, vous utilisez l'API Cloud Tasks. L'utilisation conjointe d'un fichier queue.yaml et de l'API Cloud Tasks n'est pas recommandée. Toutefois, selon votre application, cela peut s'avérer inévitable lors de la migration de Task Queues vers Cloud Tasks. Pour en savoir plus sur les bonnes pratiques, consultez la page Utiliser la gestion des files d'attente et utiliser queue.yaml (comparaison).

Créer des files d'attente

Lisez cette section si votre application crée des files d'attente de manière automatisée ou si vous souhaitez créer des files d'attente supplémentaires à partir de la ligne de commande.

Dans Cloud Tasks, les noms de files d'attente sont au format projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID. La partie LOCATION_ID du nom de la file d'attente correspond à une Google Cloud région. La partie QUEUE_ID du nom de la file d'attente est équivalente au champ name de la file d'attente Task Queues. Le nom de la file d'attente est généré au moment de sa création, sur la base du projet, de la région et du QUEUE_ID que vous spécifiez.

En règle générale, l'emplacement de la file d'attente (région) doit correspondre à la région de votre application. Les deux exceptions à cette règle concernent les applications utilisant la région europe-west et celles utilisant la région us-central. Dans Cloud Tasks, ces régions sont appelées respectivement europe-west1 et us-central1.

Vous pouvez spécifier une configuration facultative lors de la création d'une file d'attente, mais vous pouvez également la mettre à jour après sa création.

Vous n'avez pas besoin de recréer les files d'attente existantes. Migrez plutôt le code qui interagit avec vos files d'attente existantes en lisant les sections pertinentes de ce guide.

Remarque : Le service de file d'attente de tâches App Engine crée automatiquement une file d'attente par défaut nommée default. Cloud Tasks ne crée pas automatiquement cette file d'attente.

Réutiliser les noms de files d'attente

Vous devez attendre sept jours après la suppression d'une file d'attente pour en créer une autre avec le même ID dans le même projet et le même emplacement (région).

L'exemple suivant permet de créer deux files d'attente à l'aide de Cloud Tasks. La première file d'attente possède l'ID queue-blue et est configurée pour envoyer toutes les tâches à la version v2 du service task-module à un taux de 5/s. La deuxième file d'attente possède l'ID queue-red et distribue les tâches à un taux de 1/s. Les deux sont créées sur le projet avec l'ID du projet dans l'emplacement us-central1. Il s'agit de l'équivalent Cloud Tasks pour la création de files d'attente dans Task Queues.

gcloud

Gcloud CLI déduit le projet et l'emplacement à partir de sa configuration.

gcloud tasks queues create queue-blue \
    --max-dispatches-per-second=5 \
    --routing-override=service:task-module,version:v2

gcloud tasks queues create queue-red \
    --max-dispatches-per-second=1

Pour en savoir plus, consultez la section Créer une file d'attente Cloud Tasks dans la documentation de référence Cloud Tasks.

Définir le taux de traitement de la file d'attente

Le tableau ci-dessous répertorie les champs qui diffèrent entre Task Queues et Cloud Tasks.

Champ Task Queues	Champ Cloud Tasks	Description
rate	max_dispatches_per_second	Taux maximal auquel les tâches sont distribuées depuis la file d'attente.
max_concurrent_requests	max_concurrent_dispatches	Nombre maximal de tâches simultanées pouvant être distribuées depuis la file d'attente.
bucket_size	max_burst_size	Cloud Tasks calcule une propriété get-only max_burst_size qui limite la vitesse de traitement des tâches de la file d'attente en fonction de la valeur de max_dispatches_per_second. Ce champ permet à la file d'attente d'atteindre un taux élevé de sorte que le traitement démarre peu de temps après la mise en file d'attente d'une tâche, tout en limitant l'utilisation des ressources lorsqu'un grand nombre de tâches est placé en file d'attente pour une courte période. Pour les files d'attente App Engine créées ou mises à jour à l'aide d'un fichier, max_burst_size est initialement égal à bucket_size. Toutefois, si la file d'attente est ensuite transmise à une update commande à l'aide d'une interface Cloud Tasks, max_burst_size sera réinitialisé en fonction de la valeur de max_dispatches_per_second, que cette dernière soit mise à jour ou non.max_dispatches_per_second
total_storage_limit	Obsolète dans Cloud Tasks	Cloud Tasks n'est pas compatible avec la définition d'une limite de stockage personnalisée.

Vous pouvez définir le taux de traitement de la file d'attente lors de sa création ou la mettre à jour par la suite. L'exemple ci-dessous utilise Cloud Tasks pour définir le taux de traitement d'une file d'attente nommée queue-blue qui a déjà été créée. Si queue-blue a été créé ou configuré à l'aide d'un fichier queue.yaml, l'exemple suivant réinitialise max_burst_size en fonction de la valeur max_dispatches_per_second de 20. Il s'agit de l'équivalent Cloud Tasks pour la définition du taux de traitement de la file d'attente dans Task Queues.

gcloud

gcloud tasks queues update queue-blue \
    --max-dispatches-per-second=20 \
    --max-concurrent-dispatches=10

Pour en savoir plus, consultez la section Définir des limites de débit.

Désactiver et reprendre les files d'attente

Cloud Tasks utilise le terme suspendre de la même manière que Task Queues utilise le terme désactiver. La suspension d'une file d'attente arrête l'exécution des tâches jusqu'à sa reprise. Cependant, vous pouvez continuer à ajouter des tâches à une file d'attente suspendue. Cloud Tasks utilise le terme réactiver de la même manière que Task Queues.

L'exemple suivant suspend une file d'attente avec l'ID queue1. Il s'agit de l'équivalent Cloud Tasks pour la désactivation des files d'attente dans Task Queues.

gcloud

gcloud tasks queues pause queue1

Pour en savoir plus, consultez la section Suspendre des files d'attentedans la documentation de référence Cloud Tasks.

Supprimer des files d'attente

Une fois que vous supprimez une file d'attente, vous devez attendre sept jours avant de pouvoir en créer une autre portant le même nom. Envisagez de supprimer définitivement toutes les tâches d'une file d'attente et de reconfigurer la file d'attente si vous ne pouvez pas attendre sept jours.

L'exemple suivant supprime la file d'attente ayant l'ID queue1. Il s'agit de l'équivalent Cloud Tasks pour la suppression des files d'attente dans Task Queues.

gcloud

gcloud tasks queues delete queue1

Pour en savoir plus, consultez la section Supprimer des files d'attentedans la documentation de référence Cloud Tasks.

Créer et gérer des tâches

Cette section explique comment créer et gérer des tâches à l'aide de l'API Cloud Tasks.

Créer des tâches

Le tableau ci-dessous répertorie les champs qui diffèrent entre Task Queues et Cloud Tasks.

Champ Task Queues	Champ Cloud Tasks	Description
N/A	app_engine_http_request	Crée une requête qui cible un service App Engine. Ces tâches sont appelées "tâches App Engine".
method	http_method	Spécifie la méthode de requête, par exemple POST.
url	relative_uri	Indique le gestionnaire de tâches. Notez la différence dans la lettre finale : i pour URI (Uniform Resource Identifier) plutôt que l pour URL (Uniform Resource Locator).
target	app_engine_routing	Facultatif. Spécifie les champs service, version et instance App Engine pour une tâche App Engine. S'ils ne sont pas définis, le service, la version et l'instance par défaut sont utilisés.

L'exemple suivant crée une tâche qui est acheminée vers le gestionnaire /update_counter sur le service App Engine par défaut. Il s'agit de l'équivalent Cloud Tasks pour la création de tâches dans Task Queues.

gcloud

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=POST \
    --relative-uri=/update_counter \
    --routing=service:worker \
    --body-content=10

Pour en savoir plus, consultez la page Créer des tâches App Engine dans la documentation de référence Cloud Tasks .

Spécifier le service cible et le routage

La spécification du service cible, de la version et de l'instance App Engine pour les tâches App Engine est facultative. Par défaut, les tâches App Engine sont acheminées vers le service, la version et l'instance définis par défaut au moment de la tentative d'exécution de ces tâches.

Définissez la propriété app_engine_routing de la tâche lors de sa création afin de spécifier une instance, une version ou un service App Engine différents pour votre tâche.

Pour acheminer toutes les tâches d'une file d'attente donnée vers les mêmes service, version et instance App Engine, vous pouvez définir la propriété app_engine_routing_override sur la file d'attente.

Pour en savoir plus, consultez la section Configurer le routage dans la documentation de référence Cloud Tasks.

Transmettre des données au gestionnaire

Comme pour Task Queues, vous pouvez transmettre des données au gestionnaire de deux manières à l'aide de Cloud Tasks. Vous pouvez soit transmettre des données en tant que paramètres de requête dans l'URI relatif, soit transmettre des données dans le corps de la requête à l'aide des méthodes HTTP POST ou PUT.

Cloud Tasks utilise le terme corps de la même manière que Task Queues utilise le terme charge utile. Pour le corps, Cloud Tasks utilise par défaut le type de contenu octet-stream plutôt que le texte brut. Vous pouvez définir le type de contenu du corps en le spécifiant dans l'en-tête.

L'exemple suivant montre comment transmettre une clé au gestionnaire /update_counter de deux manières différentes. Il s'agit de l'équivalent Cloud Tasks pour la transmission des données au gestionnaire dans Task Queues.

gcloud

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=GET  \
    --relative-uri=/update_counter?key=blue \
    --routing=service:worker

gcloud tasks create-app-engine-task \
    --queue=default \
    --method=POST \
    --relative-uri=/update_counter \
    --routing=service:worker \
    --body-content="{'key': 'blue'}"

Spécifier le nom de la tâche

La spécification du nom de la tâche est facultative. Si vous n'indiquez aucun nom de tâche, Cloud Tasks en crée un automatiquement en générant un ID de tâche, et en déduisant le projet et l'emplacement (région) en fonction de la file d'attente que vous avez spécifiée lors de la création de la tâche.

Les noms de tâches sont au format projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID. La partie TASK_ID du nom de la tâche est équivalente au champ name de la tâche Task Queues.

Réutiliser des noms de tâches

Vous devez attendre avant de réutiliser le nom d'une tâche. Ce temps d'attente diffère selon que la file d'attente distribuant la tâche a été créée dans Cloud Tasks ou dans Task Queues.

Pour les tâches dans les files d'attente qui ont été créées à l'aide de Task Queues (y compris la file d'attente par défaut), vous devez attendre environ neuf jours après la suppression ou l'exécution de la tâche d'origine. Pour les tâches se trouvant dans des files d'attente qui ont été créées à l'aide de Cloud Tasks, vous devez attendre environ une heure après la suppression ou l'exécution de la tâche d'origine.

L'exemple suivant crée une tâche avec le paramètre TASK_ID défini sur first-try et l'ajoute à la file d'attente par défaut. Il s'agit de l'équivalent Cloud Tasks pour la dénomination des tâches dans Task Queues.

gcloud

Gcloud CLI crée le nom de la tâche en déduisant le projet et l'emplacement à partir de votre configuration.

gcloud tasks create-app-engine-task first-try \
    --queue=default \
    --method=GET \
    --relative-uri=/url/path

Réessayer d'effectuer les tâches en échec

Vous pouvez définir la configuration des nouvelles tentatives de tâches sur des files d'attente lors de leur création ou de leur mise à jour. Le tableau ci-dessous répertorie le champ Task Queues et le champ Cloud Tasks correspondant.

Champ Task Queues	Champ Cloud Tasks
task_retry_limit	max_attempts
task_age_limit	max_retry_duration
min_backoff_seconds	min_backoff
max_backoff_seconds	max_backoff
max_doublings	max_doublings

Utiliser des paramètres de nouvelle tentative spécifiques à une tâche

Les paramètres de nouvelle tentative spécifiques à une tâche qui ont été configurés dans Task Queues fonctionnent dans Cloud Tasks, mais vous ne pouvez pas les modifier ni les définir sur de nouvelles tâches. Pour modifier les paramètres de nouvelle tentative d'une tâche comportant des paramètres qui lui sont spécifiques, vous devez recréer la tâche avec une file d'attente Cloud Tasks contenant les paramètres de nouvelle tentative souhaités.

L'exemple suivant illustre divers scénarios de nouvelles tentatives d'exécution :

• Dans fooqueue, les tâches sont relancées jusqu'à sept fois et jusqu'à deux jours après la première tentative d'exécution. Une fois ces deux limites atteintes, la tâche échoue définitivement.
• Dans la file d'attente barqueue, App Engine tente de relancer les tâches en augmentant l'intervalle de manière linéaire entre chaque tentative jusqu'à atteindre l'intervalle maximum, puis en relançant indéfiniment des tentatives à l'intervalle maximum (les intervalles entre les requêtes sont donc de 10, 20, 30, ..., 190, 200 secondes, puis toujours 200 secondes).
• Dans la file d'attente bazqueue, l'intervalle entre les tentatives commence à 10 secondes puis est doublé trois fois avant d'augmenter de manière linéaire, après quoi les tâches sont relancées indéfiniment à l'intervalle maximum (les intervalles entre les requêtes sont donc de 10, 20, 40, 80, 160, 240, 300 secondes, puis toujours 300 secondes).

Il s'agit de l'équivalent Cloud Tasks pour la relance des tâches dans Task Queues.

gcloud

Lorsque vous définissez des options qui spécifient un nombre de secondes, vous devez inclure s après le nombre entier (par exemple, 200s et non 200).

gcloud tasks queues create fooqueue \
    --max-attempts=7 \
    --max-retry-duration=172800s  #2*60*60*24 seconds in 2 days

gcloud tasks queues create barqueue \
    --min-backoff=10s \
    --max-backoff=200s \
    --max-doublings=0

gcloud tasks queues create bazqueue \
    --min-backoff=10s \
    --max-backoff=300s \
    --max-doublings=3

Pour en savoir plus, consultez la section Définir les paramètres de nouvelle tentative dans la documentation de référence Cloud Tasks.

Supprimer des tâches d'une file d'attente

Lorsque vous supprimez une tâche, vous devez attendre neuf jours avant de pouvoir créer une tâche portant le même nom si elle se trouve dans une file d'attente créée à l'aide d'un fichier queue.yaml ou une heure si elle se trouve dans une file d'attente créée à l'aide de Cloud Tasks.

L'exemple suivant supprime la tâche ayant l'ID foo de la file d'attente ayant l'ID queue1. Il s'agit de l'équivalent Cloud Tasks pour la suppression de tâches dans Task Queues.

gcloud

Le projet et l'emplacement de la tâche sont obtenus à partir du projet par défaut de gcloud CLI.

gcloud tasks delete foo --queue=queue1

Pour en savoir plus, consultez la section Supprimer une tâche d'une file d'attente dans la documentation de référence Cloud Tasks.

Supprimer définitivement des tâches

L'exemple suivant montre comment supprimer définitivement toutes les tâches de la file d'attente ayant l'ID queue1. Il s'agit de l'équivalent Cloud Tasks pour la suppression définitive de tâches dans Task Queues.

gcloud

Le projet et l'emplacement de la file d'attente sont obtenus à partir du projet par défaut de gcloud CLI.

gcloud tasks queues purge queue1

Pour en savoir plus, consultez la section Supprimer définitivement toutes les tâches d'une file d'attente dans la documentation de référence Cloud Tasks.

Étapes suivantes

• Documentation Cloud Tasks
• Bibliothèque cliente Cloud Tasks
• Documentation de référence sur l'API REST Cloud Tasks
• Documentation de référence sur l'API RPC Cloud Tasks