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 automatiser un notebook à l’aide de tâches planifiées, de webhooks ou de l’API Execute 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 votre 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. Par défaut, seuls les résultats des 30 dernières exécutions sont enregistrés.

À l’aide de la page Tasks (Tâches) dans ArcGIS Notebook Server Manager, les administrateurs peuvent afficher de façon détaillée, modifier, interrompre, reprendre ou supprimer chaque tâche d’un notebook actif 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 Task (Tâche) de l’éditeur de notebooks.

Pour éviter les problèmes d’exécution récurrents sur un notebook, une tâche planifiée est désactivée après cinq échecs successifs. 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.

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.

Automatiser un notebook à l’aide de webhooks

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, 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. Lorsqu’un webhook est déclenché, une requête HTTP est adressée à Notebook Server pour exécuter un notebook choisi sans intervention de la part de l’utilisateur.

Remarque :

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

Créer un webhook

Les webhooks peuvent uniquement être administrés via le répertoire du portail ArcGIS (API de partage). Procédez comme suit pour créer un webhook :

1. Accédez au répertoire Portal for ArcGIS.
   https://machine.domain.com/webadaptor/sharing/rest
2. Connectez-vous en tant qu’administrateur.

   Les webhooks peuvent uniquement être créés et gérés par un administrateur.

   La page de l’administrateur apparaît.

3. Cliquez sur l’hyperlien Org ID (ID d’org) ou émettez une requête au format ci-dessous, pour accéder à la page des ressources Portal Self.
   https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
4. Faites défiler la page vers le bas, jusqu’à Webhooks, sous Child Resources (Ressources enfant).
   https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
5. Sous Supported Operation (Opérations prises en charge), sélectionnez Create Webhook (Créer un webhook).
6. Spécifiez les paramètres de votre webhook. Pour créer un webhook permettant d’automatiser un notebook, indiquez les informations suivantes :

   Paramètre	Détails
   name (Requis)	Spécifie le nom du webhook. Exemple : name=mynotebook_webhook
   url (Facultatif)	La payload URL n’est pas exigée lors de la configuration d’un webhook pour notebooks car elle est automatiquement dérivée par le système. Vous n’avez pas besoin de fournir cette information.
   config (Requis)	Définit les propriétés de configuration de votre webhook. Remarque : Vous devez être administrateur et propriétaire de l’élément de notebook à exécuter via le webhook. Exemple : { "deactivationPolicy": { "numberOfFailures": 5, "daysInPast": 5 }, "properties": { "federatedServer": { "itemId": "<Notebook item id to be executed>", "tokenTypeToSend": "owner", "tokenExpirationTimeMinutes": 10 } } }
   events (Facultatif)	Représentation de l’URI d’un événement qui déclenche le webhook. Ce paramètre est obligatoire si changes est défini sur manual. Pour plus d’informations, reportez-vous à la section Événements déclencheurs pris en charge. Reportez-vous à la section Événements déclencheurs de la documentation Create webhooks in the REST API (Créer des webhooks dan l’API REST) pour consulter d’autres exemples d’événements déclencheurs. Exemple : events=/items,/users

   Consultez la documentation REST API du webhook pour en savoir plus sur ces paramètres.

   Votre webhook est maintenant répertorié sous les webhooks : https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks.

Pour plus d’informations sur l’automatisation par le biais de webhooks, reportez-vous à la rubrique d’aide Webhooks dans ArcGIS Enterprise.

Gérer les webhooks

Vous pouvez gérer vos webhooks via le répertoire du portail ArcGIS en émettant une demande au format suivant :

Les opérations prises en charge pour gérer vos webhooks sont les suivantes :

• Update Webhook : mettez à jour les paramètres de votre webhook. Vous pouvez modifier le nom, la payload URL, la configuration ou les événements déclencheurs pour le webhook spécifié.
• Delete Webhook : supprimez le webhook de votre portail.
• Deactivate Webhook et Activate Webhook : désactivez votre webhook, ce qui empêche les payloads d’être livrées lorsque le webhook est déclenché. Lorsque le webhook est désactivé, l’opération Activate Webhook (Activer le webhook) est disponible pour reprendre la livraison des payloads.

La page Notification Status affiche des informations sur les événements déclencheurs associés au webhook donné. Vous pouvez utiliser cette table pour surveiller votre webhook ainsi que les détails des payloads livrées, tels que l’heure à laquelle le webhook a été déclenché et les réponses reçues de la payload URL et de la payload livrée. Les enregistrements indiquant le succès de la livraison d’une payload sont supprimés au bout d’une journée. Les enregistrements indiquant l’échec d’une tentative de livraison sont stockés pendant sept jours.

Consultez Webhooks API pour des exemples sur ces opérations.

Pour plus d’informations sur l’automatisation par le biais de webhooks, reportez-vous à la rubrique d’aide Webhooks dans ArcGIS Enterprise.

Charge utile d'un webhook

Lorsqu'un notebook est exécuté via 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\>,
  }
}

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 appelée, cette opération exécute automatiquement un 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 Exécuter un notebook du guide de référence du répertoire administrateur.

Nombre maximal d’exécutions automatiques simultanées de notebooks

Lors de l’exécution d’un notebook à l’aide d’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 automatiquement sans aucune intervention de l’utilisateur. Par défaut, ArcGIS Notebook Server est configuré pour traiter un maximum de 10 exécutions de notebooks simultanées par 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.