Automatiser les processus de notebook avec des événement de webhook

Un webhook est un mécanisme qui permet à une application de fournir à d’autres applications des informations liées aux événements. Les webhooks peuvent être configurés aux niveaux de l’organisation et du service pour exécuter automatiquement un notebook lorsque des événements associés à votre organisation ou vos services se produisent.

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

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. ArcGIS Notebook Server 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 à ArcGIS 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 à partir de webhooks est limité par la propriété système maxExecuteNotebookContainersPerNode dans ArcGIS Notebook Server.

Créer un webhook d’organisation

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 :

1. Connectez-vous en tant qu’administrateur par défaut ou rôle personnalisé avec le privilège Webhooks d’organisation.
2. Cliquez sur Organization (Organisation) > Settings (Paramètres) > Webhooks.
3. Dans la section Organization webhooks (Webhooks d’organisation), cliquez sur Create webhook (Créer un webhook).
4. Spécifiez un nom de 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.

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

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

7. Sélectionnez le notebook qui s’exécutera au déclenchement du webhook.
8. 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).

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

Gérer les webhooks d’organisation

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 :

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. Cliquez sur Organization (Organisation) > Settings (Paramètres) > Webhooks pour afficher une liste des webhooks d’organisation créés par d’autres administrateurs de webhooks et vous-même.

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). 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). 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 (Mettre à jour) pour mettre à jour votre 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.

Modifier les paramètres de webhook d’organisation 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 :

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. Cliquez sur Organization (Organisation) > Settings (Paramètres) > Webhooks.
3. Dans la section Organization webhooks (Webhooks d’organisation), cliquez sur Advanced settings (Paramètres 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>",
        "portalURL": "<portal_url>",
        "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 ArcGIS Notebook Server.

Créer et copier une 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 créer 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. Pour connaître la procédure de création et de copie d’une clé d’API, suivez la procédure du 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.

Inscrire un récepteur webhook de notebook

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

1. Connectez-vous à votre portail en tant qu’administrateur.
2. Cliquez sur Organization (Organisation) > Settings (Paramètres) > webhooks > Create webhook receiver (Créer un récepteur webhook).
3. Saisissez un nom pour votre récepteur webhook.
4. Sélectionnez le notebook à exécuter par le récepteur webhook.
5. Saisissez une clé secrète de 32 caractères qui permettra de certifier l’origine du webhook.
6. Saisissez une liste d’en-têtes de signature séparés par des virgules dans lesquels une charge utile chiffrée sera recherchée.
7. Saisissez le jeton d’API avec des privilèges d’accès à l’élément de notebook, des privilèges de création de notebook/création de notebook avancé et toute autre fonctionnalité SIG du notebook.
8. Saisissez éventuellement des paramètres au format JSON.
9. Cliquez sur Create receiver (Créer un récepteur).

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

Charge utile des webhooks de service

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.

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
        }
    ]
}