Publier un notebook sous forme d’outil Web

ArcGIS Notebooks permet de publier des webhooks sous forme d’outils Web. Les administrateurs, ainsi que les auteurs de notebooks dotés du privilège Publier des outils Web, peuvent publier leurs propres notebooks sous forme d’outils Web. Lorsqu’un notebook est publié sous la forme d’un outil Web, un service de géotraitement asynchrone est créé sur ArcGIS Notebook Server et inscrit comme outil Web. Il existe une relation un vers un entre le notebook et l’outil Web, ce qui implique qu’il n’est possible de publier qu’un seul outil Web par notebook. Les outils Web sont utilisables par n’importe quelle application client compatible avec les services de géotraitement asynchrones RESTful.

La publication d’un notebook en tant qu’outil Web est prise en charge pour les notebooks dont la version de runtime est 6.0 ou ultérieure. Pour vérifier les informations de runtime d’un notebook, cliquez sur le bouton Info (Informations) sur le ruban supérieur de l’éditeur de notebooks ou dans l’onglet Settings (Paramètres) sur la page Élément de notebook. Pour en savoir plus sur les runtimes de notebooks, consultez Afficher les bibliothèques Python disponibles.

L’éditeur de notebooks permet de configurer les paramètres en entrée et en sortie d’un notebook. Les paramètres en entrée correspondent aux variables en entrée d’un notebook à externaliser pour la saisie utilisateur lorsque le notebook est exécuté comme outil Web. Les paramètres en sortie représentent les variables en sortie d’un notebook à renvoyer comme sorties d’outil Web. Lorsque vous inscrivez une ou plusieurs variables en entrée ou en sortie et que vous publiez un notebook, les paramètres sont proposés comme paramètres en entrée ou en sortie pour l’outil Web correspondant.

Remarque :

Il n’est pas indispensable de définir des paramètres en entrée ou en sortie pour publier un notebook sous la forme d’un outil Web. Par exemple, les notebooks qui exécutent des tâches avec des entrées et sorties prédéfinies, comme les couches d’entités référencées par itemId, ne requièrent pas nécessairement des paramètres en entrée ou en sortie.

Remarque :

Les types de données suivants sont pris en charge comme paramètres en entrée ou en sortie : String (Chaîne), Long, Double, Boolean (Booléen), Feature set (Jeu d’entités), Record set (Jeu d’enregistrements), Date, Linear unit (Unité linéaire), Raster data layer (Couche de données raster) et File (Fichier). Pour plus d’informations, reportez-vous à la rubrique Geoprocessing services data types (Types de données de services de géotraitement) de la documentation ArcGIS REST API.

Lorsqu’un outil Web est exécuté, ArcGIS Notebook Server lance une exécution automatisée du notebook sur la machine Notebook Server en ouvrant un nouveau conteneur et en exécutant le notebook sans intervention de l’utilisateur. Les utilisateurs qui bénéficient du privilège d’exécution d’outils Web et avec lesquels l’outil Web a été partagé peuvent accéder à l’outil Web et l’exécuter. Outre le privilège d’exécution d’outils Web requis, il convient de disposer de tous les autres privilèges nécessaires à l’exécution du notebook. Consulter la rubrique Types d’utilisateur, rôles et privilèges pour en savoir plus sur les privilèges.

Remarque :

Si, lorsque vous créez un notebook à partager comme outil Web, le notebook référence un fichier de votre répertoire d’espace de travail comme données en entrée, les autres utilisateurs avec lesquels le notebook ou l’outil Web est partagé n’ont pas accès à ce fichier. Si certains de vos fichiers doivent être référencés comme données en entrée dans le notebook, vous pouvez les référencer par le biais d’un élément partagé dans votre contenu ArcGIS ou les charger et les référencer à partir d’un répertoire de données personnalisées inscrit auprès de ArcGIS Notebook Server.

Par défaut, ArcGIS Notebook Server est configuré pour traiter un maximum de 10 exécutions de notebook non interactives simultanées par machine ArcGIS Notebook Server. Sont incluses les exécutions déclenchées par des outils Web, des tâches planifiées, l’API executeNotebook et des déclencheurs de webhook. Les administrateurs peuvent augmenter cette limite en cas de besoin.

Remarque :

Si vous ne voyez pas l’option Parameters (Paramètres) ou Publish (Publier) dans l’éditeur de notebooks, vous ne disposez pas du privilège Publier des outils Web ou vous n’êtes pas le propriétaire du notebook. Dans un notebook nouvellement créé, les options Parameters (Paramètres) et Publish (Publier) ne sont pas affichées tant qu’il n’a pas été enregistré.

Configurer les paramètres en entrée

Les paramètres en entrée représentent les variables en entrée d’un notebook qui sont externalisées lorsqu’un notebook est exécuté comme outil Web. Vous pouvez utiliser la fenêtre Parameters (Paramètres) de l’éditeur de notebooks pour configurer des paramètres en entrée comme variables et les ajouter à votre notebook.

1. Dans l’éditeur de notebooks, cliquez sur Parameters (Paramètres).
2. Cliquez sur Add (Ajouter).
3. Sélectionnez l’entrée comme paramètre Direction.
4. Remplissez le champ Variable name (Nom de variable).

   Remarque :

   Ce nom doit être identique à un nom de variable qui se trouve dans le code du notebook ou qui est déjà configuré dans le notebook.

5. Remplissez le champ Display name (Nom d’affichage) pour le paramètre de l’outil Web.
6. Dans le menu déroulant Data type (Type de données), sélectionnez un type de données pour le paramètre en entrée.
7. Pour Default Value (Valeur par défaut), indiquez la valeur du paramètre en entrée. Pour connaître la syntaxe des valeurs par défaut des types de données pris en charge, reportez-vous à la rubrique Geoprocessing services data types (en anglais uniquement).
8. Pour Description, saisissez la description du paramètre en entrée.
9. Cliquez sur Save (Enregistrer) pour enregistrer le paramètre en entrée.
10. Répétez les étapes 1 à 9 pour ajouter d’autres paramètres en entrée.
11. Après avoir ajouté tous les paramètres en entrée souhaités, sélectionnez une cellule de votre notebook dans laquelle les insérer et cliquez sur Insert as variables (Insérer comme variables).
12. Cliquez sur Save (Enregistrer) pour enregistrer le notebook.

Configurer les paramètres en sortie

Pour configurer la sortie d’un notebook publié sous la forme d’un outil Web, vous pouvez configurer des paramètres en sortie dans la fenêtre Parameters (Paramètres) de l’éditeur de notebooks.

1. Dans l’éditeur de notebooks, cliquez sur Parameters (Paramètres).
2. Cliquez sur Add (Ajouter).
3. Pour le paramètre Direction, sélectionnez la sortie.
4. Remplissez le champ Variable name (Nom de variable).

   Remarque :

   Ce nom doit être identique à un nom de variable qui se trouve dans le code du notebook ou qui est déjà configuré dans le notebook.

5. Remplissez le champ Display name (Nom d’affichage) pour le paramètre de l’outil Web.
6. Dans le menu déroulant Data type (Type de données), sélectionnez un type de données pour le paramètre en sortie.
7. Pour Default Value (Valeur par défaut), indiquez la valeur du paramètre en sortie. Pour connaître la syntaxe des valeurs par défaut des types de données pris en charge, reportez-vous à la rubrique Geoprocessing services data types (en anglais uniquement).
8. Pour Description, saisissez la description du paramètre en sortie.
9. Cliquez sur Save (Enregistrer) pour enregistrer le paramètre en sortie.
10. Sélectionnez une cellule dans votre notebook. Cliquez sur le bouton Add (Ajouter) afin d’ajouter l’extrait de code Python requis pour écrire la sortie de l’outil Web.

    Il est recommandé de sélectionner une cellule proche de la partie inférieure du notebook, en dessous des cellules où les sorties sont créées.

11. Vérifiez que les noms de variable en sortie figurant dans l’extrait de code ajouté correspondent à la sortie définie dans le notebook, et apportez d’autres modifications à l’extrait de code si nécessaire.
12. Répétez les étapes 1 à 11 pour ajouter d’autres paramètres en sortie.
13. Cliquez sur Save (Enregistrer) pour enregistrer le notebook.

Publier un outil Web

Vous pouvez utiliser la fenêtre Publish (Publier) de l’éditeur de notebooks pour publier un notebook sous la forme d’un outil Web.

1. Enregistrez le notebook pour vous assurer de publier sa dernière copie.
2. Exécutez manuellement les cellules du notebook de manière interactive pour vérifier l’absence d’erreurs.

Remarque :

Ignorez les cellules qui contiennent les extraits de code pour les paramètres en sortie, car elles ne sont pas exécutées en mode interactif.
3. Cliquez sur Publish (Publier) dans le ruban de l’éditeur de notebooks.
4. Saisissez un titre et une description pour l’outil Web dans les champs Title (Titre) et Description de la fenêtre Publish (Publier).
5. Vérifiez les paramètres en entrée et en sortie.
6. Cliquez sur Publish (Publier) pour publier le notebook sous la forme d’un outil Web.
7. Après la publication de l’outil Web, cliquez sur View detail (Afficher les détails) pour consulter la page des détails des éléments correspondant à l’outil Web.
8. Cliquez sur Share (Partager) pour ouvrir la fenêtre Share (Partager).
   1. Sélectionnez Organization (Organisation) pour partager l’outil Web avec tous les utilisateurs de votre organisation.
   2. Cliquez sur Edit group sharing (Mettre à jour le partage de groupe) pour partager l’outil Web avec des groupes spécifiques.
   3. Sélectionnez les groupes avec lesquels effectuer le partage.
   4. Cliquez sur OK.
   5. Cliquez sur Save (Enregistrer).

Partager un outil web

Pour partager ou mettre à jour les paramètres de partage d’un outil Web de notebook existant avec votre organisation ou des groupes spécifiques, procédez comme suit.

Remarque :

Les utilisateurs avec lesquels l’outil Web est partagé doivent disposer du privilège d’exécution des outils Web et des privilèges supplémentaires nécessaires pour exécuter le notebook, afin d’être en mesure d’exécuter l’outil Web partagé.

Remarque :

Depuis la version 11.2, vous pouvez maintenant partager un outil Web de notebook sur un niveau différent de celui sur lequel le notebook a été publié. Par exemple, un outil Web de notebook peut être partagé avec l’organisation même si le notebook même n’est pas partagé avec l’organisation. Pour vous assurer qu’un outil Web publié dans une version précédente est capable d’exploiter ce changement, remplacez l’outil Web.

1. Vérifiez que vous êtes connecté à Portal for ArcGIS et que vous disposez des privilèges suffisants pour partager du contenu avec votre organisation.
2. Cliquez sur Content (Contenu).
3. Cochez la case située en regard du titre de l’outil Web que vous souhaitez partager.
4. Cliquez sur Share (Partager).
   1. Sélectionnez Organization (Organisation) pour partager l’outil Web avec tous les utilisateurs de votre organisation.
   2. Cliquez sur Edit group sharing (Mettre à jour le partage de groupe) pour partager l’outil Web avec des groupes spécifiques.
   3. Sélectionnez les groupes avec lesquels effectuer le partage.
   4. Cliquez sur OK.
   5. Cliquez sur Save (Enregistrer).

Remplacer l’outil Web

Le remplacement d’un outil Web met à jour un outil Web pour utiliser le dernier instantané de ce notebook. Vous pouvez remplacer un outil Web de notebook dans la fenêtre Publish (Publier) de l’éditeur de notebooks.

1. Si un paramètre en entrée ou en sortie doit être mis à jour, suivez la procédure présentée dans la section Modifier un paramètre en entrée ou en sortie de cette rubrique.
2. Si vous ajoutez de nouveaux paramètres en entrée ou en sortie, suivez la procédure présentée dans la section Configurer les paramètres en entrée ou Configurer les paramètres en sortie de cette rubrique.
3. Cliquez sur Save (Enregistrer) pour vous assurer de publier la dernière copie du notebook.
4. Exécutez manuellement chaque cellule du notebook pour vous assurer qu’il n’y a plus d’erreur.

   Remarque :

   N’exécutez pas les cellules qui contiennent les extraits de code pour les paramètres en sortie, car elles ne seront pas exécutées en mode interactif.

5. Cliquez sur Publish (Publier).
6. Cliquez sur Overwrite (Remplacer) pour remplacer l’outil Web.

Supprimer un outil Web

Vous pouvez supprimer un outil Web publié à partir d’un notebook en supprimant l’élément d’outil Web.

1. Dans le ruban supérieur de l’éditeur de notebooks, cliquez sur Publish (Publier).
2. Cliquez sur View detail (Afficher les détails) pour consulter la page des détails des éléments correspondant à l’outil Web.
3. Cliquez sur Settings (Paramètres).
4. Cliquez sur Delete item (Supprimer l’élément), puis confirmez votre souhait de supprimer l’élément d’outil Web et le service de géotraitement publié sur ArcGIS Notebook Server.

Remarque :

Si l’élément de notebook à partir duquel l’outil Web est publié est supprimé, l’élément d’outil Web est également supprimé.

Modifier un paramètre en entrée ou en sortie

Vous pouvez modifier un paramètre en entrée ou en sortie dans la fenêtre Parameters (Paramètres) de l’éditeur de notebooks.

Remarque :

Si un notebook a déjà été publié sous la forme d’un outil Web, vous devez activer le bouton Enable editing (Activer la mise à jour) dans la fenêtre Parameters (Paramètres) avant de pouvoir modifier des paramètres. La prudence s’impose pour toutes modifications de paramètres après la publication du notebook sous la forme d’un outil Web. En effet, certains changements peuvent interrompre l’exécution des applications Web qui utilisent l’outil Web.

1. Dans le ruban supérieur de l’éditeur de notebooks, cliquez sur Parameters (Paramètres).
2. Cliquez sur le bouton d’options en regard du paramètre, puis sur Edit (Mettre à jour).
3. Mettez à jour le paramètre, puis cliquez sur Save (Enregistrer).
   1. Si un paramètre en entrée a été mis à jour, effacez manuellement le contenu de la cellule existante ou supprimez-la avec les variables en entrée, puis répétez l’étape qui permet d’insérer les paramètres en entrée comme variables dans le notebook.
   2. Si un paramètre en sortie a été mis à jour, effacez manuellement l’extrait de code correspondant à la variable en sortie, puis répétez les étapes qui permettent d’ajouter au notebook l’extrait de code pour le paramètre en sortie.
4. Cliquez sur Save (Enregistrer) pour enregistrer le notebook.

Supprimer un paramètre en entrée ou en sortie

Vous pouvez supprimer des paramètres en entrée ou en sortie dans la fenêtre Parameters (Paramètres).

1. Dans le ruban supérieur de l’éditeur de notebooks, cliquez sur Parameters (Paramètres).
2. Cliquez sur le bouton d’options en regard du paramètre, puis sur Delete (Supprimer).
3. Cliquez sur Delete (Supprimer) pour supprimer définitivement le paramètre.
4. Effacez manuellement la variable en entrée ou l’extrait de code en sortie, ou supprimez-les, dans le notebook.
5. Cliquez sur Save (Enregistrer) pour enregistrer le notebook.

Utiliser l’étendue de la carte

Lorsque vous exécutez un outil Web dans Map Viewer, si l’étendue de géotraitement et le système de coordonnées en sortie sont supprimés, ils sont transmis au notebook en tant que variable Python nommée context, avec les autres paramètres en entrée (voir ci-dessous).

context = {
    "extent": {
        "ymin": 1759249.9654418486,
        "xmin": 6481923.176042713,
        "ymax": 1795442.256243616,
        "xmax": 6531137.243576055,
        "spatialReference": {"latestWkid": 2229, "wkid": 102645},
    },
    "outSR": {"latestWkid": 4269},
}

Vous pouvez utiliser la valeur de la variable context pour définir l’étendue et le système de coordonnées en sortie des processus d’analyse spatiale dans le notebook. Pour tester les processus d’analyse spatiale avant de publier le notebook en tant qu’outil Web, déclarez la variable context avec une valeur par défaut.

Lorsque vous êtes prêt à effectuer la publication, insérez les paramètres en entrée sous forme de variables après la cellule dans laquelle vous déclarez la variable context.

Résoudre les problèmes d’exécution d’un outil Web

Après la publication d’un notebook en tant qu’outil Web, vous pouvez vérifier le bon fonctionnement de l’outil Web en exécutant la tâche à partir du répertoire des services ArcGIS Notebook Server.

1. Dans un navigateur Web, ouvrez le répertoire de services ArcGIS Notebook Server https://notebookserver.domain.com/webadaptorcontext/rest/services.
2. Connectez-vous en tant que propriétaire de l’outil Web.
3. Recherchez le service, puis accédez à la page des tâches.
4. Cliquez sur Submit job (Soumettre la tâche).
5. Indiquez des paramètres en entrée, puis cliquez sur Submit job (Soumettre la tâche).
6. Vous pouvez également cliquer sur le lien Check Job Details Again (Revérifier les détails de la tâche) pour vérifier le statut de la tâche.

   Si l’exécution de l’outil Web aboutit, des liens d’accès aux sorties sont disponibles. Un aperçu HTML de l’exécution du notebook est généré en sortie par défaut, que l’exécution soit concluante ou non.

7. Téléchargez l’aperçu HTML du notebook, puis affichez-le pour vérifier si des problèmes sont survenus au cours de l’exécution de l’outil Web.
8. Si l’exécution de l’outil Web échoue, vérifiez que le notebook s’exécute correctement dans l’éditeur de notebooks.