Créer des gestionnaires de tâches

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 web.xml 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.

Cette API est compatible avec les environnements d'exécution de première génération et peut être utilisée lors de la mise à niveau vers des environnements d'exécution de deuxième génération correspondants. Si vous effectuez une mise à jour vers l'environnement d'exécution Java 11/17 d'App Engine, consultez le guide de migration pour en savoir plus sur les options de migration des anciens services groupés.

É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é.

  Remarque : App Engine lui-même renvoie un code d'état 503 lorsque les instances sont surchargées ou indisponibles. Le service Tasks Queue répond à cela en ralentissant la diffusion des files d'attente aux gestionnaires, pour éviter d'aggraver le problème. Si vous souhaitez déclencher une nouvelle tentative intentionnellement, utilisez un code d'état autre que 2xx ou 503.

• 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.

  Lorsque l'exécution d'une tâche approche de la date limite, App Engine génère une exception DeadlineExceededException avant cette date, afin que vous puissiez enregistrer votre travail ou consigner toute progression réalisée.

• 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.

Pour en savoir plus sur la restriction des URL, consultez la section Sécurité et authentification. Voici un exemple de code pouvant être utilisé dans web.xml pour accorder l'accès à tout élément commençant par /tasks/ uniquement aux administrateurs :

<security-constraint>
    <web-resource-collection>
        <web-resource-name>tasks</web-resource-name>
        <url-pattern>/tasks/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>

Pour en savoir plus sur le format de web.xml, consultez la documentation sur le descripteur de déploiement.

Remarque : Bien que les tâches puissent être envoyées aux chemins d'URL restreints avec <role-name>admin</role-name>, elles ne peuvent pas utiliser de chemins d'accès restreints avec <role-name>*</role-name>, car les tâches ne sont pas exécutées en tant qu'utilisateur. La restriction admin est satisfaite par l'inclusion de l'en-tête X-Appengine-QueueName décrit dans la section Lire les en-têtes de requêtes.

Étape suivante

• Découvrez comment supprimer des tâches.