Créer des tâches d'envoi

Cette page explique comment créer des tâches et les placer dans des files d'attente d'envoi. Lorsque vous souhaitez traiter une tâche, vous devez créer un objet de tâche et le placer dans une file d'attente. Vous pouvez spécifier explicitement le service et le gestionnaire qui traitent la tâche et éventuellement transmettre au gestionnaire des données spécifiques à la tâche. Vous pouvez également ajuster la configuration de la tâche, par exemple en planifiant une heure future d'exécution ou en limitant le nombre de nouvelles tentatives en cas d'échec de la tâche.

Créer une tâche

Pour créer une tâche et la placer en file d'attente, appelez la fonction taskqueue.Add.

import("google.golang.org/appengine/taskqueue")

Spécifier le service de nœuds de calcul

Lorsqu'une tâche est extraite de sa file d'attente, le service de file d'attente de tâches l'envoie à un service de nœuds de calcul. Chaque tâche comporte un élément target (cible) et un élément url, qui déterminent le service et le gestionnaire qui exécuteront la tâche.

target

La cible spécifie le service qui recevra la requête HTTP permettant d'exécuter la tâche. Il s'agit d'une chaîne qui spécifie un service, une version ou une instance dans une forme canonique. Voici les formes les plus courantes :

    service
    version.service
    instance.version.service

La chaîne cible est ajoutée au début du nom de domaine de votre application. Il existe trois façons de définir la cible pour une tâche :

  • Déclarez la cible au moment de créer la tâche. Vous pouvez définir la cible explicitement lors de la création de l'objet Task en définissant l'en-tête Host : 

    h := http.Header{}
h.Add("Host", "versionHostname")
task := taskqueue.Task{
	Header: h,
}

  • Incluez une instruction target lorsque vous définissez une file d'attente dans le fichier queue.yaml, comme dans la définition de queue-blue. Toutes les tâches ajoutées à une file d'attente avec une instruction target utiliseront cette cible, même si une autre cible a été attribuée à la tâche au moment de sa création.

  • Si aucune cible n'est spécifiée selon l'une des deux méthodes précédentes, la cible de la tâche correspond alors à la version du service qui la met en file d'attente. Notez que si vous placez ainsi en file d'attente une tâche issue du service et de la version par défaut, et que la version par défaut change avant que la tâche ne soit lancée, cette dernière s'exécute dans la nouvelle version par défaut.

url

L'élément url sélectionne l'un des gestionnaires du service cible, qui effectuera la tâche.

L'élément url doit correspondre à l'un des formats d'URL de gestionnaire du service cible. L'élément url peut comprendre des paramètres de requête si la méthode spécifiée dans la tâche est GET ou PULL. Si aucun élément url n'est spécifié, l'URL par défaut /_ah/queue/[QUEUE_NAME] est utilisée, où [QUEUE_NAME] correspond au nom de la file d'attente de la tâche.

Transmettre des données au gestionnaire

Vous pouvez transmettre des données au gestionnaire en tant que paramètres de requête dans l'URL de la tâche, mais seulement si la méthode spécifiée dans la tâche est GET ou PULL.

La fonction NewPOSTTask possède un argument positionnel pour le paramètre "query_data". Les données correspondent généralement à un dictionnaire de paires clé/valeur. Si la méthode de la tâche est POST ou PUT, les données sont ajoutées à la charge utile de la requête HTTP. Si la méthode est GET, les données sont ajoutées à l'URL en tant que paramètres de requête.

Nommer une tâche

Lorsque vous créez une tâche, App Engine lui attribue un nom unique par défaut. Vous pouvez toutefois attribuer le nom de votre choix à une tâche à l'aide du paramètre name. Les tâches auxquelles vous avez attribué un nom personnalisé présentent l'avantage d'être dédupliquées, ce qui signifie que vous pouvez utiliser des noms de tâches pour vous assurer que les tâches ne sont ajoutées qu'une seule fois. La déduplication se poursuit pendant neuf jours après l'achèvement ou la suppression de la tâche.

Notez que la logique de déduplication introduit une surcharge de performances importante, entraînant des latences accrues et des taux d'erreur potentiellement plus élevés associés aux tâches nommées. Ces coûts peuvent être considérablement augmentés si les tâches sont nommées de manière séquentielle, par exemple avec des horodatages. Par conséquent, si vous attribuez vos propres noms, nous vous recommandons d'utiliser un préfixe distribué de manière homogène pour les noms de tâches, tel qu'un hachage du contenu.

Si vous attribuez vos propres noms à des tâches, notez que leur longueur maximale est de 500 caractères, et qu'ils peuvent contenir des majuscules, des minuscules, des traits de soulignement et des traits d'union.

Placer des tâches en file d'attente dans des transactions Cloud Datastore

Dans le cadre d'une transaction Datastore, une tâche n'est placée en file d'attente (et garantie d'être mise en file d'attente) que si la transaction est correctement validée. Les tâches ajoutées à une transaction sont considérées comme faisant partie de celle-ci et possèdent le même niveau d'isolation et de cohérence.

Une application ne peut pas insérer plus de cinq tâches transactionnelles dans des files d'attente de tâches au cours d'une même transaction. Les tâches transactionnelles ne doivent pas porter de noms spécifiés par l'utilisateur.

L'exemple de code suivant montre comment insérer des tâches transactionnelles dans une file d'attente d'envoi dans le cadre d'une transaction Datastore :

import (
	"net/url"

	"golang.org/x/net/context"

	"google.golang.org/appengine/datastore"
	"google.golang.org/appengine/taskqueue"
)

func f(ctx context.Context) {
	err := datastore.RunInTransaction(ctx, func(ctx context.Context) error {
		t := taskqueue.NewPOSTTask("/worker", url.Values{
			// ...
		})
		// Use the transaction's context when invoking taskqueue.Add.
		_, err := taskqueue.Add(ctx, t, "")
		if err != nil {
			// Handle error
		}
		// ...
		return nil
	}, nil)
	if err != nil {
		// Handle error
	}
	// ...
}

Utiliser le package "delay" au lieu d'un service de nœuds de calcul

La configuration d'un gestionnaire pour chaque tâche distincte (telle que décrite dans les sections précédentes) peut s'avérer fastidieuse, tout comme la sérialisation et la désérialisation d'arguments complexes, notamment si vous souhaitez que la file d'attente exécute de nombreuses tâches diverses, mais de faible taille. Le SDK Go inclut un package (appengine/delay) qui expose une simple API qui vous dispense de l'ensemble des étapes du processus de configuration des gestionnaires de tâches dédiés ainsi que des processus de sérialisation/désérialisation des paramètres.

Pour utiliser le package delay, procédez comme suit :

var expensiveFunc = delay.Func("some-arbitrary-key", func(ctx context.Context, a string, b int) {
	// do something expensive!
})

// Somewhere else
expensiveFunc.Call(ctx, "Hello, world!", 42)

Le package delay sérialise l'appel de fonction et ses arguments, puis les ajoute à la file d'attente de tâches. Une fois la tâche exécutée, le package delay exécute la fonction.

Pour plus d'informations sur l'utilisation du package delay, reportez-vous à sa documentation.

Utiliser des tâches dans une application mutualisée

Par défaut, les files d'attente d'envoi utilisent l'espace de noms actuel tel qu'il est défini dans le gestionnaire d'espaces de noms au moment de la création de la tâche. Si votre application exploite une architecture mutualisée, consultez la section API Namespaces Go 1.11.

Étape suivante