Cette page explique comment créer un gestionnaire de tâches, c'est-à-dire le code qui gère une tâche d'envoi. Vous devez fournir un gestionnaire de requêtes pour traiter la tâche. Le mappage de l'URL de requête au gestionnaire approprié est déclaré dans le fichier app.yaml de votre service, comme tout autre gestionnaire de requêtes. Comme vous contrôlez la manière de mapper les requêtes de tâches à un gestionnaire, vous êtes libre d'organiser vos gestionnaires de tâches comme vous le souhaitez. Si votre application traite de nombreux types de tâches, vous pouvez ajouter tous les gestionnaires à un seul service ou les répartir entre plusieurs services.
Écrire un gestionnaire de requêtes de tâches d'envoi
Dans la file d'attente, le service Task Queue crée un en-tête HTTP et l'envoie à une instance du service de nœud de calcul spécifié par la cible de la tâche. Les requêtes Task Queue sont envoyées à partir de l'adresse IP 0.1.0.2.
Il n'est pas nécessaire que votre gestionnaire soit rédigé dans le même langage que celui qui a créé et mis en file d'attente la tâche si le gestionnaire se trouve dans un service distinct.
Suivez ces instructions lorsque vous écrivez le code de votre gestionnaire :
Le code doit renvoyer un code d'état HTTP compris entre 200 et 299 pour indiquer la réussite de la tâche. Tout autre code indique que la tâche a échoué.
Les tâches d'envoi ont un délai d'exécution fixe qui dépend du type de scaling du service qui les exécute. Les services de scaling automatique doivent s'achever au plus tard 10 minutes plus tard. Scaling manuel et de base : les requêtes peuvent durer jusqu'à 24 heures. Si le gestionnaire ne respecte pas le délai, le service Task Queue suppose que la tâche a échoué et tente une nouvelle exécution.
Le gestionnaire doit être idempotent. L'API Task Queue d'App Engine est conçue pour assurer une distribution de type "au moins une fois". En d'autres termes, si une tâche est ajoutée avec succès, App Engine la transmet à un gestionnaire au moins une fois. Notez que dans certaines circonstances rares, l'exécution de plusieurs tâches est possible. Le code doit donc garantir qu'une exécution répétée n'entraîne pas d'effets secondaires néfastes.
Le service Task Queue utilise le code HTTP de la réponse du gestionnaire pour déterminer si la tâche a abouti. La réponse du gestionnaire n'est visible que par le service Task Queue et ne sert qu'à déterminer si la tâche a abouti. La file d'attente ignore tous les autres champs de la réponse. Ensuite, le service supprime la réponse. L'application d'origine ne reçoit jamais de données. Si une tâche échoue, le service Task Queue la retente en envoyant une autre requête.
Les données fournies par l'utilisateur peuvent être distribuées au gestionnaire dans la requête sous forme de chaîne de requête ou de charge utile dans le corps de la requête. L'insertion de données utilisateur est décrite dans la section Créer des tâches. Si la requête inclut des données, le gestionnaire doit savoir comment elles y ont été insérées. Le code exact utilisé pour extraire les données de la requête dépend du framework Web que vous utilisez.
Pour tester un gestionnaire de tâches, connectez-vous en tant qu'administrateur et accédez à son URL depuis votre navigateur.
Lire les en-têtes de requêtes
Une requête HTTP de tâche d'envoi comporte des en-têtes spéciaux définis par App Engine qui contiennent des informations spécifiques à la tâche que votre gestionnaire peut utiliser.
Si ces en-têtes sont présents dans une requête d'utilisateur externe à votre application, ils sont supprimés et remplacés. La seule exception concerne les requêtes des administrateurs connectés à l'application, qui sont autorisés à définir des en-têtes à des fins de test. En revanche, les en-têtes ne sont pas supprimés lorsque votre application est en cours d'exécution sur le serveur de développement.
Les requêtes de Task Queue contiennent toujours les en-têtes suivants :
| En-tête | Description |
|---|---|
X-Appengine-QueueName |
Nom de la file d'attente (éventuellement "default" pour la file d'attente d'envoi par défaut). |
X-Appengine-TaskName |
Nom de la tâche ou identifiant unique généré par le système si aucun nom n'a été spécifié. |
X-Appengine-TaskRetryCount |
Nombre de fois où une tâche a fait l'objet de nouvelles tentatives d'exécution. Pour la première tentative, cette valeur est définie sur 0. Ce chiffre inclut les tentatives lorsque la tâche a échoué en raison d'un manque d'instances disponibles et n'a jamais atteint la phase d'exécution. |
X-Appengine-TaskExecutionCount |
Nombre de fois où cette tâche a précédemment échoué pendant la phase d'exécution. Ce chiffre n'inclut pas les échecs dus à un manque d'instances disponibles. |
X-Appengine-TaskETA |
Heure d'exécution cible de la tâche, spécifiée en secondes depuis le 1er janvier 1970. |
Si le gestionnaire de requêtes trouve l'un des en-têtes répertoriés ci-dessus, il peut valider qu'il s'agit d'une requête Task Queue.
De plus, les requêtes Task Queue peuvent contenir les en-têtes suivants :
| En-tête | Description |
|---|---|
X-Appengine-TaskPreviousResponse |
Code de réponse HTTP de la tentative précédente. |
X-Appengine-TaskRetryReason |
Raison de la nouvelle tentative d'exécution de la tâche. |
X-Appengine-FailFast |
Indique qu'une tâche en cours échoue immédiatement si une instance existante n'est pas disponible. |
Sécuriser les URL du gestionnaire de tâches
Si une tâche effectue des opérations sensibles (telles que la modification de données), vous souhaiterez peut-être sécuriser l'URL du gestionnaire pour éviter qu'un utilisateur externe malveillant ne l'appelle directement. Vous pouvez empêcher les utilisateurs d'accéder aux URL de tâches en limitant l'accès aux administrateurs App Engine. Les requêtes de tâches elles-mêmes sont émises par App Engine et peuvent toujours cibler une URL restreinte.
Vous pouvez restreindre l'accès à une URL en ajoutant l'élément login: admin à la configuration du gestionnaire dans le fichier app.yaml.
Exemple :
runtime: php55
api_version: 1
threadsafe: true
handlers:
- url: /tasks/process
script: process.php
login: admin
Étape suivante
- Découvrez comment supprimer des tâches.