Automatiser les processus avec ArcGIS Notebooks—ArcGIS Enterprise on Kubernetes

Notebook Services vous permet d’appliquer plusieurs méthodes pour automatiser les processus, notamment en utilisant des notebooks planifiés, des webhooks ou des 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

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 organisation 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 :

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, à partir de la fenêtre Manage tasks (Gérer les tâches).

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 Notebook Services, 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 et de l’organisation associées aux tâches de notebook planifiées.

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

Lors de l’exécution d’un notebook par une tâche planifiée, d’un webhook ou de l’API Execute Notebook, Notebook Services ouvre automatiquement un nouveau déploiement et exécute le notebook sans intervention de l’utilisateur. Par défaut, Notebook Services est configuré pour traiter un maximum de 10 exécutions de notebook simultanées pour chaque déploiement de service d’automatisation de notebook. En tenant compte des ressources disponibles sur le cluster Kubernetes, un administrateur peut ajuster cette limite en modifiant la propriété de configuration maxAutomatedNotebookJobsPerManager de Notebook Services. 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 maxAutomatedNotebookJobsPerManager en procédant comme suit.

Remarque :

L’augmentation de la limite peut entraîner l’utilisation de ressources supplémentaires sur les nœuds.

Connectez-vous à votre API ArcGIS Enterprise Administrator en tant qu’administrateur.
Cliquez sur Notebooks > Configuration > Update Configuration (Mettre à jour la configuration).
Cliquez sur Settings (Paramètres) > Site
Modifiez la valeur de la propriété maxAutomatedNotebookJobsPerManager.
Cliquez sur Update Notebook Configuration (Mettre à jour la configuration du notebook).

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 dans l’API ArcGIS Enterprise Administrator.

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. 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 l’opération ExecuteNotebooksOrgLimitMettre à jour les limites dans l’API ArcGIS Enterprise Administrator.

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 dans l’API ArcGIS Enterprise Administrator.

É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 dans l’API ArcGIS Enterprise Administrator.

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 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, groupes ou utilisateurs surviennent. Notebook Services joue le rôle de récepteur de la charge utile du webhook. Lorsqu’un webhook est déclenché, une requête HTTP est adressée à Notebook Services pour exécuter un notebook choisi 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 Services.

Créer un webhook

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

Connectez-vous en tant qu’administrateur par défaut ou rôle personnalisé avec le privilège Webhooks d’organisation.
Cliquez sur Organization (Organisation) > Settings (Paramètres) > Webhooks.
Cliquez sur Create webhook (Créer un webhook).
Spécifiez un nom de webhook.
Par exemple, vous pouvez saisir Name=mynotebook_webhook.
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.
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.
Sélectionnez le type de charge utile Notebook.
Sélectionnez le notebook qui s’exécutera au déclenchement du webhook.
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).
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 depuis la page Organization settings (Paramètres de l’organisation). Procédez comme suit pour gérer les webhooks existants :

Connectez-vous en tant qu’administrateur par défaut ou en tant que rôle personnalisé avec le privilège Webhooks d’organisation.
Cliquez sur Organization (Organisation) > Settings (Paramètres) > Webhooks pour afficher 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’appliqueront à tous les webhooks de votre organisation. Pour modifier les paramètres de webhook avancés, procédez comme suit :

Connectez-vous en tant qu’administrateur par défaut ou en tant que rôle personnalisé avec le privilège Webhooks d’organisation.
Cliquez sur 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 des webhooks d’organisation

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 :

webhookPayload = {
    "properties": {
        "itemId": "<notebook_item_id>"
    },
    "events": [
        {
            "source": "<items | user | group | role>",
            "id": "<source_id>",
            "userId": "<user_id_of_member_triggered_webhook>",
            "when": 1742596800000,
            "operation": "<operation_triggered_webhook>",
            "properties": {"<operation_details>"},
            "username": "<username_of_member_triggered_webhook>"
        }
    ],
    "info": {
        "webhookId": "<webhook_id>",
        
        "webhookName": "<webhook_name>",
        "when": 1742596805000
    }
}

Automatiser un notebook à l’aide de webhooks de service

Les webhooks, y compris ceux 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 Notebook Services.

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é dans votre organisation. 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. Octroyez les privilèges des éléments Create and edit Notebooks (Créer et mettre à jour des notebooks) et Create, Update, and Delete (Créer, mettre à jour et supprimer) et éventuellement le privilège de notebook Advanced (Avancé) pour ArcPy. Des privilèges supplémentaires peuvent s’avérer nécessaires selon les processus effectués dans le notebook.

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

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

Connectez-vous en tant qu’utilisateur doté des droits d’administration.
Cliquez sur la page Item Details (Détails de l’élément) de l’élement de clé d’API.
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 :

Connectez-vous au répertoire d’administration en tant qu’administrateur.
L’URL est https://organization.domain.com/<context>/admin.
Cliquez sur Notebooks > Webhook Receivers (Récepteurs webhook) > Register Webhook Receiver (Inscrire un récepteur webhook).
L’URL est https://organization.domain.com/<context>/admin/notebooks/webhookReceivers/create.
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 :

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

Charge utile des webhooks de service

Webhooks de service d’entités

L’exemple de code suivant illustre une charge utile pour un webhook de service d’entités.

webhookPayload = {
    "serviceType": "FeatureServer",
    "changesUrl": "<change_url>",
    "name": "<webhook_name>",
    "id": "<webhook_id>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "FeaturesCreated",
            "when": 1740436800000
        },
        {
            "eventType": "FeaturesDeleted",
            "when": 1740436810000
        },
        {
            "eventType": "FeaturesUpdated",
            "when": 1740436820000
        }
    ]
}

Webhooks de service de géotraitement

L’exemple de code suivant illustre une charge utile pour un webhook de service de géotraitement.

webhookPayload = {
    "serviceType": "GPServer",
    "jobId": "<job_id>",
    "statusURL": "<status_url>",
    "name": "<webhook_name>",
    "taskName": "<task_name>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "esriJobSucceeded",
            "when": 1742337000000
        }
    ]
}

API d’exécution d’un 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 (Exécuter un notebook) dans le API ArcGIS Enterprise Administrator. Lorsqu’elle est invoquée, cette opération exécute automatiquement un notebook. Toutefois, si vous utilisez un 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.

Vous avez un commentaire à formuler concernant cette rubrique ?