Automatiser les processus avec ArcGIS Notebooks

ArcGIS Notebook Server vous permet d’appliquer plusieurs méthodes pour automatiser les processus, notamment en utilisant des notebooks planifiés, des webhooks ou vos propres scripts personnalisés à l’aide de l’API d’administration Execute Notebook.

Remarque :

Pour que vous puissiez automatiser un notebook à l’aide de tâches planifiées, de webhooks ou de l’API Run Notebook, le notebok doit utiliser un runtime de version 3.0 ou ultérieure.

Planifier des tâches de notebook

Depuis la version 10.8.1, les créateurs de notebooks peuvent planifier ArcGIS Notebooks pour une exécution automatisée à heure fixe dans le futur, une seule fois ou de manière récurrente. La création de tâches pour programmer des notebooks permet d’automatiser des processus classiques, exécuter aux heures creuses des traitements qui utilisent un grand volume de données et mettre à jour régulièrement des jeux de données. Vous pourriez ainsi programmer un notebook pour réaliser les opérations suivantes :

• Importer des données à partir d’une source en ligne mise à jour tous les mois, nettoyer les données automatiquement, appliquer les transformations nécessaires et transférer les données dans votre espace de travail.
• Exécuter un processus d’analyse de Big Data impliquant des traitements lourds au cours de la nuit au moment où les ressources de votre machine sont inutilisées.
• Gérer les utilisateurs ayant créé un compte dans le portail la semaine précédente et vous envoyer la liste par e-mail.

Vous pouvez créer une ou plusieurs tâches pour un notebook. Par défaut, un administrateur ou créateur de notebooks peut créer un maximum de 20 tâches. En cas de changement de propriétaire d’un notebook, les tâches qui lui sont associées sont désactivées et attribuées à son nouveau propriétaire.

Vous pouvez utiliser les tâches planifiées pour paramétrer les notebooks. Un notebook paramétré vous permet d’écrire un code générique qui peut s’adapter aux différentes entrées sans intervention de votre part. Lors de l’exécution de la tâche, les paramètres choisis sont insérés dans le notebook, où ils peuvent éventuellement être enregistrés. Par exemple, vous pouvez utiliser un notebook paramétré pour produire des rapports sur la pollution de l’air par région de façon récurrente. Ce notebook peut comporter plusieurs tâches planifiées, une pour chaque région à étudier. Par ailleurs, pour chaque tâche, une entrée paramétrée comme le nom de la ville et le type de pollution peuvent être transmis au notebook.

Remarque :

Le nombre d’exécutions simultanées de tâches de notebook est limité par la propriété système maxExecuteNotebookContainersPerNode dans Notebook Server.

Vous pouvez configurer la tâche pour enregistrer l’état du notebook dans l’élément de notebook d’origine à l’issue de l'exécution.

Une vue HTML statique est enregistrée pour chaque tâche planifiée exécutée.

À l’aide de la fenêtre Manage tasks (Gérer les tâches) de la page d’accueil d’ArcGIS Notebook Server ou de la page Tâches (Tâches) dans ArcGIS Notebook Server Manager, les administrateurs peuvent afficher des détails, modifier, interrompre et reprendre, ou supprimer chaque tâche de notebook active sur le site. Les administrateurs et créateurs de notebooks doivent posséder le privilège permettant de planifier un notebook pour pouvoir afficher de façon détaillée, modifier, interrompre, reprendre ou supprimer une tâche de notebook dans la page des détails du notebook ou dans la fenêtre des tâches de l’éditeur de notebooks.

Si l’exécution précédente d’une tâche est toujours en cours, la nouvelle exécution de la tâche planifiée est ignorée. Par exemple, si l’exécution d’une tâche est programmée toutes les 15 minutes, mais qu’une instance de cette tâche est en cours depuis 20 minutes, l’exécution planifiée suivante est ignorée. Si cela se produit souvent, le propriétaire de la tâche doit ajuster l’intervalle temporel planifié de façon à ce que les exécutions ne se chevauchent pas.

Pour plus d’informations sur les tâches de notebook planifiées, reportez-vous à la rubrique d’aide Planifier une tâche de notebook.

Limites des tâches planifiées

Il existe certaines limites au niveau de l’utilisateur, de l’organisation et du site ArcGIS Notebook Server (machine) associées aux tâches de notebook planifiées.

Modifier le nombre maximal d’exécutions de notebook automatisées simultanées (maxExecuteNotebookContainersPerNode)

Lors de l’exécution d’un notebook par une tâche planifiée, d’un webhook ou de l’API Execute Notebook, ArcGIS Notebook Server ouvre automatiquement un nouveau conteneur et exécute le notebook sans intervention de l’utilisateur. Par défaut, ArcGIS Notebook Server est configuré pour traiter un maximum de 10 exécutions de notebook simultanées pour chaque machine Notebook Server. En tenant compte des ressources (processeur et RAM) disponibles sur chaque machine du site Notebook Server, un administrateur peut ajuster cette limite en modifiant la propriété système maxExecuteNotebookContainersPerNode dans Notebook Server. Les demandes de notebooks automatisés envoyées après le dépassement de cette limite seront ajoutées dans une file d’attente et exécutées une fois que le nombre d’exécutions de tâches automatisées sera retombé sous cette limite. Les tâches en file d’attente échouent si le temps d’attente dépasse le délai d’expiration.

Remarque :

Cela ne limite pas le nombre de notebooks qui sont exécutés interactivement à partir de l’éditeur de notebooks.

Vous pouvez modifier la limite maxExecuteNotebookContainersPerNode en procédant comme suit.

Remarque :

L’augmentation de la limite peut entraîner l’utilisation de ressources supplémentaires sur la machine Notebook Server.

1. Connectez-vous à votre portail ArcGIS Enterprise en tant qu’administrateur.
2. Ouvrez ArcGIS Notebook Server Manager.
3. Cliquez sur Settings (Paramètres) > Site
4. Modifiez la valeur de la propriété maxExecuteNotebookContainersPerNode.
5. Cliquez sur Save (Enregistrer).
6. Lisez l’avertissement concernant le redémarrage de votre Notebook Server et cliquez sur Save and Restart (Enregistrer et redémarrer) pour enregistrer les modifications.

Nombre maximal de tâches de notebook planifiées actives par utilisateur

Chaque auteur de notebook doté du privilège Planifier des notebooks peut créer jusqu’à 20 tâches de notebook actives au maximum. Une fois cette limite atteinte, l’utilisateur ne peut pas créer de nouvelles tâches planifiées. Une nouvelle tâche peut être créée dès lors qu’une tâche existante passe de l’état Active (Actif) à Complete (Terminé), Failed (Échec) ou Inactive (Inactif). Vous pouvez modifier cette limite en mettant à jour la propriété ExecuteNotebooksUserLimit à l’aide de l’opération Mettre à jour les limites système dans l’API Administrateur d’ArcGIS Enterprise.

Nombre maximal de tâches de notebook planifiées actives par organisation

Le nombre maximal de tâches de notebook planifiées actives pour une organisation est limité à 200. Cette limite représente le nombre total de tâches actives qui peuvent appartenir à tous les utilisateurs dans une organisation Portal. Une fois cette limite atteinte, les utilisateurs ne peuvent pas créer de nouvelles tâches de notebook planifiées. Vous pouvez modifier cette limite en mettant à jour la propriété ExecuteNotebooksOrgLimit à l’aide de l’opération Mettre à jour les limites système dans l’API Administrateur d’ArcGIS Enterprise.

Nombre de résultats signalés pour une tâche planifiée

Les résultats d’une tâche sont signalés et conservés pendant 30 exécutions. Les exécutions de tâche antérieures aux 30 exécutions les plus récentes d’une tâche sont supprimées définitivement. Vous pouvez modifier cette limite en mettant à jour la propriété TaskRunHistoryCount à l’aide de l’opération Mettre à jour les limites système dans l’API Administrateur d’ArcGIS Enterprise.

Échec automatique d’une tâche

Les tâches qui échouent 5 fois consécutives basculent automatiquement à l’état Failed (Échec) et ne s’exécutent plus. Avant de la réactiver, le propriétaire de la tâche doit vérifier que l’exécution du notebook peut aboutir sans intervention de la part de l’utilisateur. Pour garantir que les tâches continuent de s’exécuter, le propriétaire de la tâche doit identifier et rectifier l’échec et basculer la tâche à l’état Actif. Vous pouvez modifier cette limite en mettant à jour la propriété FailedRunsDisableTask à l’aide de l’opération Mettre à jour les limites système dans l’API Administrateur d’ArcGIS Enterprise.

Automatiser un notebook à l’aide de webhooks d’organisation

Un webhook est un mécanisme qui permet à une application de fournir à d’autres applications des informations liées aux événements. En tant qu’administrateur ArcGIS Enterprise Portal ou qu’utilisateur doté du privilège Webhooks d’organisation, vous pouvez créer, gérer et configurer des webhooks. Vous pouvez configurer des webhooks pour exécuter automatiquement un notebook dont vous êtes propriétaire lorsque des événements associés à vos éléments de portail, groupes ou utilisateurs surviennent. Notebook Server joue le rôle de récepteur de la charge utile d’un webhook. Lorsqu’un webhook est déclenché, une requête HTTP est adressée à Notebook Server pour exécuter un notebook sélectionné sans intervention de la part de l’utilisateur.

Remarque :

Le nombre d’exécutions simultanées de notebooks à partir de webhooks est limité par la propriété système maxExecuteNotebookContainersPerNode dans Notebook Server.

Créer un webhook

Les webhooks peuvent être administrés sur la page Organization settings (Paramètres d’organisation) de votre portail. Procédez comme suit pour créer un webhook :

1. Connectez-vous en tant qu’administrateur par défaut ou rôle personnalisé avec le privilège Webhooks d’organisation.
2. Accédez à Organization (Organisation) > Settings (Paramètres) > Webhooks.
3. Cliquez sur Create webhook (Créer un webhook).
4. Spécifiez un nom de webhook.

   Par exemple, vous pouvez saisir Name=mynotebook_webhook.

5. Sélectionnez le type d’événement qui déclenchera le webhook.

   Par défaut, tous les types d’événements (Éléments, Utilisateurs, Groupes et Rôles) sont pris en compte.

6. Utilisez Trigger (Déclencheur) pour accepter la valeur par défaut (/) ou spécifier une ou plusieurs valeurs comme événements déclencheurs.

   Par exemple : Events (Événements)=/items, /items/<ID d’élément>,/users.

   Reportez-vous à la rubrique Événements déclencheurs pris en charge pour plus d’informations.

   Pour des exemples supplémentaires, reportez-vous à la rubrique Événements déclencheurs.

7. Sélectionnez le type de charge utile Notebook.

   Remarque :

   Si l’option Notebook n’est pas disponible, cela signifie que Notebook Server n’a pas été configuré avec votre portail. Si l’option Notebook est disponible, mais impossible à sélectionner, cela signifie qu’aucun notebook disponible pour la configuration des webhooks ne vous appartient. L’élément de notebook qui servira pour le webhook doit vous appartenir.

8. Sélectionnez le notebook qui s’exécutera au déclenchement du webhook.
9. Vous pouvez aussi saisir une valeur Secret Key (Clé secrète) qui sera incluse dans la charge utile des webhooks.

   Vous pouvez en outre utiliser des valeurs aléatoires et prégénérées pour la valeur Secret key (Clé secrète).

10. Cliquez sur Create webhook (Créer un webhook) pour enregistrer les paramètres de webhook et créer un webhook.

Gérer les webhooks

Les webhooks peuvent être administrés sur la page Organization settings (Paramètres d’organisation) de votre portail. Procédez comme suit pour gérer les webhooks existants :

1. Connectez-vous en tant qu’administrateur par défaut ou en tant que rôle personnalisé avec le privilège Webhooks d’organisation.
2. Accédez à Organization (Organisation) > Settings (Paramètres) > Webhooks pour voir une liste de webhooks créés par vous et d’autres administrateurs de webhooks.

Vous pouvez gérer vos webhooks existants avec les opérations suivantes.

• Désactiver un webhook : lorsqu’un webhook est actif, cliquez sur Active (Actif). Vous êtes invité à confirmer le changement de statut. Cliquez sur Confirm (Confirmer) pour désactiver le webhook. La désactivation du webhook empêche la livraison des charges utiles lorsque le webhook est déclenché.
• Activer un webhook : lorsqu’un webhook est inactif, cliquez sur Inactive (Inactif). Vous êtes invité à confirmer le changement de statut. Cliquez sur Confirm (Confirmer) pour activer le webhook. Une fois le webhook activé, la livraison des charges utiles reprend.
• Mettre à jour un webhook : cliquez sur le bouton des options dans le webhook et sur Edit (Mise à jour) pour modifier les événements déclencheurs du webhook ou le notebook spécifié pour le webhook.
• Supprimer un webhook : cliquez sur le bouton des options dans le webhook et sur Delete (Supprimer). Cliquez sur Confirm (Confirmer) pour supprimer le webhook.

Paramètres de webhook avancés

Utilisez les paramètres de webhook avancés pour modifier des propriétés telles que le nombre de tentatives de livraison pouvant être effectuées, les notifications du temps écoulé et les propriétés d’expiration des notifications pour les webhooks. Ces paramètres avancés s’appliquent à tous les webhooks du portail. Pour modifier les paramètres de webhook avancés, procédez comme suit :

1. Connectez-vous en tant qu’administrateur par défaut ou en tant que rôle personnalisé avec le privilège Webhooks d’organisation.
2. Accédez à Organization (Organisation) > Settings (Paramètres) > Webhooks > Advanced webhook settings (Paramètres de webhook avancés) pour modifier les valeurs par défaut des propriétés de webhook avancées.

Charge utile d'un webhook

Lorsqu’un notebook est exécuté à partir d’un webhook, les informations sur la charge utile de ce dernier sont automatiquement injectées dans le notebook dans une cellule initiale. Une fois injectées, les informations fournies sur la charge utile du webhook peuvent être utilisées dans le notebook pour d'autres processus d'automatisation.

Informations sur la charge utile d'un webhook incluses dans un notebook :

{
  "properties": {
    "itemId": "<itemId of the current notebook>"
  },
  "events": [
    {
      "source": "items",
      "id": "<itemId of the item that resulted in webhook trigger>",
      "userId": "<webhook user>",
      "when": \<epoch time in ms when webhook was triggered\>,
      "operation": "<type of operation that resulted in webhook trigger>",
      "properties": {},
      "username": "<webhook username>"
    }
  ],
  "info": {
    "webhookId": "<webhookId>",
    "portalURL": "<public portal url>",
    "webhookName": "<webhook name>",
    "when": \<epoch time in ms when webhook was triggered\>,
  }
}

Automatiser un notebook à l’aide de webhooks de service

Introduits comme fonctionnalité bêta dans ArcGIS Notebook Server 11.4, les webhooks, y compris les webhooks pour les services de géotraitement asynchrones et les services d’entités, ainsi que d’autres webhooks génériques, peuvent déclencher une exécution de notebook en réponse à des événements spécifiques. Les aministrateurs peuvent inscrire l’URL du récepteur webhook en tant qu’URL de webhook ou de charge utile pour ces webhooks. Lorsqu’un événement spécifique associé à un webhook est déclenché, il appelle automatiquement l’URL du récepteur webhook de notebook, lançant ainsi l’exécution du notebook correspondant.

Les sections suivantes expliquent comment configurer un récepteur webhook de notebook dans ArcGIS Notebook Server.

Créer une application de clé d’API

Une clé d’API est un jeton persistant qui autorise un webhook de service à exécuter un élément de notebook associé et à accéder de manière sécurisée aux fonctionnalités d’ArcGIS Enterprise requises pour l’exécution du notebook.

Les clés d’API sont générées à l’aide des informations d’identification de clé d’API, un type d’élément hébergé sur le portail. Les informations d’identification de clé d’API comportent des paramètres qui vous permettent de générer des clés d’API et de gérer leurs propriétés, comme les privilèges et la date d’expiration. Le processus de création des informations d’identification de clé d’API et d’utilisation des clés d’API dans l’application est désigné sous le nom d’authentification par clé d’API.

Pour connaître la procédure de génération d’une clé d’API, reportez-vous au didacticiel Créer une clé d’API.

Remarque :

Avant d’effectuer l’étape finale de copie du cache, suivez la procédure décrite dans les sections ci-dessous pour appliquer les éventuels privilèges supplémentaires requis pour l’exécution du notebook.

Appliquer des privilèges à l’application de clés d’API

Pour appliquer des privilèges supplémentaires à une application de clés d’API, procédez comme suit :

1. Connectez-vous au répertoire Portal à l’aide des informations d’identification administrateur utilisées pour créer la clé d’API.

   L’URL du répertoire Portal est https://portal.domain.com/webadaptorname/sharing/rest.

   Une fois connecté, vous êtes dirigé vers la page User resource (Ressource utilisateur) de l’utilisateur connecté.

   L’URL de la page User resource (Ressource utilisateur) est https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>.

2. Cliquez sur Contenu utilisateur.
3. Cliquez sur le lien de l’élément correspondant à la clé d’API que vous venez de créer.

   La page de l’API des détails de l’élément de la clé d’API s’ouvre : https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>/items/<itemId>

4. Cliquez sur Update App (Mettre à jour l’application).
5. Ajoutez les privilèges suivants à la fin de la section Privileges (Privilèges).
   1. Accordez l’autorisation d’exécution d’un notebook : "premium:publisher:createNotebooks"
   2. Si vous le souhaitez, vous pouvez autoriser l’importation et l’utilisation d’ArcPy dans le notebook associé : "premium:publisher:createAdvancedNotebooks"
   3. Indiquez tout autre privilège nécessaire à l’exécution du code du notebook.

   L’exemple suivant de clé d’API dispose du privilège qui permet d’accéder à l’élément de notebook référencé par son ID d’élément, des privilèges pour les notebooks standards et avancés, ainsi que des privilèges pour la publication des couches d’entités.

   [
     "portal:app:access:item:bfebec55911a4cd2a85ff9eae51dcf68",
     "premium:publisher:createAdvancedNotebooks",
     "premium:publisher:createNotebooks",
     "portal:user:createItem",
     "portal:publisher:publishFeatures"
   ]

6. Cliquez sur Update App (Mettre à jour l’application) pour enregistrer les modifications.
7. Déconnectez-vous du répertoire Portal.

Générer et copier une clé d’API

Pour générer et copier une clé d’API, procédez comme suit :

1. Connectez-vous au portail en tant qu’utilisateur doté des droits d’administration.
2. Cliquez sur la page Item Details (Détails de l’élément) de l’élement de clé d’API.
3. Suivez la procédure décrite dans la section Copier la clé d’API du didacticiel Créer une clé d’API.

Inscrire un récepteur webhook de notebook

Pour inscrire un récepteur webhook de notebook, procédez comme suit :

1. Connectez-vous au répertoire d’administration d’ArcGIS Notebook Server à l’aide des informations d’identification de l’administrateur du portail.

   L’URL est https://notebookserverwebadaptor.domain.com/webadaptor/admin.

2. Cliquez sur Notebooks > Webhook Receivers (Récepteurs webhook) > Register Webhook Receiver (Inscrire un récepteur webhook).

   L’URL est https://notebookserverwebadaptor.domain.com/webadaptor/admin/notebooks/webhookReceivers/create.

3. Inscrivez le récepteur webhook en suivant les informations indiquées dans la rubrique Créer des récepteurs webhook de l’API d’administration.

   Une fois le récepteur webhook de notebook créé, une URL du récepteur webhook est renvoyée dans la réponse. Cette URL peut être utilisée comme URL de webhook lors de l’inscription de webhooks de service de géotraitement asynchrone, de webhooks de service d’entités et d’autres webhooks génériques.

Créer un webhook de service de géotraitement asynchrone ou un webhook de service d’entités

Pour créer un webhook de service de géotraitement asynchrone ou un webhook de service d’entités, procédez comme suit :

1. Utilisez l’URL du récepteur webhook, des en-têtes secrets et des en-têtes de signature pour créer un webhook de service asynchrone.
2. Vérifiez que le notebook associé au récepteur webhook de notebook est exécuté à chaque déclenchement d’un événement spécifique du webhook de service.

API Execute Notebook

Les administrateurs et créateurs de notebooks peuvent également automatiser l’exécution d’un notebook sans intervention de la part de l’utilisateur à l’aide de l'opération Execute Notebook dans le répertoire administrateur d’ArcGIS Notebook Server. Lorsqu’elle est invoquée, cette opération exécute automatiquement le notebook. Toutefois, si vous utilisez votre propre script personnalisé, vous pouvez planifier son exécution automatique à une heure précise ou la répéter à intervalles réguliers. Vous pouvez également utiliser une tâche cron ou un planificateur Windows pour programmer l’exécution de l’opération Execute Notebook à une heure précise ou la répéter à intervalles réguliers.

Pour en savoir plus, reportez-vous à la rubrique Execute Notebook (Exécuter un notebook) du guide de référence du répertoire administrateur.