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 du portail ArcGIS Enterprise, vous pouvez créer, gérer et configurer des webhooks. Vous pouvez configurer vos webhooks pour qu’ils vous avertissent automatiquement lorsque des événements associés à vos éléments de portail, groupes et utilisateurs surviennent. Lorsqu’un webhook est déclenché, une requête HTTP est adressée à une payload URL définie par l’utilisateur unique pour qu’elle fournisse des informations concernant l’événement.
Termes clés
Voici les termes clés associés aux webhooks :
- Événement déclencheur : l’opération définit le déclencheur de votre webhook. Vous pouvez par exemple configurer le déclenchement de votre webhook lorsqu’un groupe donné est mis à jour dans votre organisation ou lorsqu’un élément est partagé. Un webhook peut comporter plusieurs événements déclencheurs.
- Payload : les données de l’événement déclencheur livrées par votre webhook une fois que l’événement spécifié a eu lieu. Ces informations sont au format JSON. Consultez la section Payloads ci-dessous pour plus d’informations.
- Payload URL : l’emplacement où sera envoyé la payload. La payload URL peut être créée à l’aide d’un service, tel que Microsoft Power Automate, Zapier ou IFTTT. Vous pouvez également créer votre propre extrémité du service web personnalisé à l’aide d’une plate-forme de votre choix.
Exemple de cas d’utilisation
Les webhooks permettent d’intégrer des processus dans les systèmes. Vous pouvez tirer parti des webhooks de plusieurs manières dans votre organisation.
Surveiller l’activité dans ArcGIS Enterprise
Un webhook peut servir à surveiller l’activité dans ArcGIS Enterprise. Vous pouvez par exemple vous abonner à tous les événements associés à un élément en particulier. Le webhook est déclenché lorsque les propriétés de l’élément sont mises à jour et une requête HTTPS livre une payload qui contient les données décrivant l’événement. Vous choisissez le lieu de livraison de cette payload et pouvez agir comme il convient lorsque vous recevez les informations.
Événements déclencheurs pris en charge
Lorsque vous créez votre webhook, vous vous abonnez aux événements déclencheurs. Comme ces événements sont des opérations du portail, l’URI de l’opération doit être spécifiée dans la configuration du webhook. Les sous-sections ci-dessous décrivent les événements déclencheurs disponibles et l’URI associée.
Eléments
Les propriétés d’élément pouvant être mises à jour varient selon les types d’élément et des actions uniques déclenchent l’opération /update. Par exemple, si l’élément est une carte web, la mise à jour de la balise, la configuration d’une fenêtre contextuelle ou le changement de fond de carte sont tous des événements de mise à jour qui déclencheront le webhook.
La table suivante répertorie les événements déclencheurs pour les éléments de portail pris en charge, dont notamment les cartes web, les applications web, les couches, les paquetages, les documents PDF :
| Événement déclencheur | Exemple d’URI | Propriétés |
|---|---|---|
Tous les événements déclencheurs pour tous les éléments | /items | |
Un élément est ajouté au portail | /items/add | |
N’importe quel élément est supprimé | /items/delete | |
N’importe quel élément est mis à jour | /items/update | |
N’importe quel élément est déplacé ou son appartenance modifiée | /items/move | |
N’importe quel élément est publié | /items/publish | |
N’importe quel élément est partagé | /items/share | |
Le partage de n’importe quel élément est annulé | /items/unshare | |
La propriété d’un élément est réaffectée | /items/reassign | |
Tous les événements déclencheurs pour un élément en particulier | /items/<itemID> | |
Un élément en particulier est supprimé | /items/<itemID>/delete | |
Les propriétés d’un élément en particulier sont mises à jour | /items/<itemID>/update | |
La propriété d’un élément en particulier est modifié ou l’élément est déplacé | /items/<itemID>/move | |
Un élément en particulier est publié | /items/<itemID>/publish | |
Un élément en particulier est partagé | /items/<itemID>/share | sharedToGroups : mode de partage d’un élément (ID de groupe, Organisation ou Tout le monde) Exemples, mis en page pour plus de lisibilité |
Le partage d’un élément en particulier est annulé | /items/<itemID>/unshare | unsharedFromGroups : mode d’annulation du partage d’un élément (ID de groupe, Organisation ou Tout le monde) Exemples, mis en page pour plus de lisibilité |
La propriété d’un élément en particulier est réaffectée | /items/<itemID>/reassign |
Groupes
Toute modification générale apportée aux paramètres de groupe constitue une mise à jour. Par exemple, le changement d’accès d’un groupe déclenche un événement de mise à jour.
La table suivante répertorie les événements déclencheurs avec des groupes :
| Événement déclencheur | Exemple d’URI | Propriétés |
|---|---|---|
Tous les événements déclencheurs pour tous les groupes | /groups | |
Un groupe est ajouté | /groups/add | |
N’importe quel groupe est mis à jour | /groups/update | |
N’importe quel groupe est supprimé | /groups/delete | |
Le paramètre Delete Protection (Protection contre la suppression) est activé pour un groupe | /groups/protect | |
Le paramètre Delete Protection (Protection contre la suppression) est désactivé pour un groupe | /groups/unprotect | |
Un utilisateur est invité dans un groupe | /groups/invite | |
Un utilisateur est ajouté à un groupe | /groups/addUsers | |
Un utilisateur est supprimé d’un groupe | /groups/removeUsers | |
Le rôle d’un utilisateur est mis à jour dans un groupe | /groups/updateUsers | |
La propriété d’un groupe est réaffectée | /groups/reassign | |
Tous les événements déclencheurs pour un groupe en particulier | /groups/<groupID> | |
Un groupe en particulier est mis à jour | /groups/<groupID>/update | |
Un groupe en particulier est supprimé | /groups/<groupID>/delete | |
Le paramètre Delete Protection (Protection contre la suppression) est activé pour un groupe en particulier | /groups/<groupID>/protect | |
Le paramètre Delete Protection (Protection contre la suppression) est désactivé pour un groupe en particulier | /groups/<groupID>/unprotect | |
Un utilisateur est invité dans un groupe en particulier | /groups/<groupID>/invite | invitedUserNames : noms d’utilisateur correspondant aux utilisateurs invités dans un groupe Exemple, mis en page pour plus de lisibilité |
Un utilisateur est ajouté à un groupe en particulier | /groups/<groupID>/addUsers | addedUserNames : noms d’utilisateur correspondant aux utilisateurs qui ont été ajoutés dans un groupe. Exemple, mis en page pour plus de lisibilité |
Un utilisateur est supprimé d’un groupe en particulier | /groups/<groupID>/removeUsers | removeUserNames : noms d’utilisateur correspondant aux utilisateurs supprimés d’un groupe. Exemple, mis en page pour plus de lisibilité |
Le rôle d’un utilisateur est mis à jour dans un groupe en particulier | /groups/<groupID>/updateUsers | updateUserNames : noms d’utilisateur correspondant aux utilisateurs dont les rôles de groupe ont été mis à jour Exemple, mis en page pour plus de lisibilité |
La propriété d’un groupe en particulier est réaffectée | /groups/<groupID>/reassign | |
Un élément est partagé avec un groupe | /groups/<groupID>/itemShare | sharedItems : itemID et le type de l’élément partagé avec un groupe. Exemple, mis en page pour plus de lisibilité |
Le partage d’un élément avec un groupe donné est annulé | /groups/<groupID>/itemUnshare | unsharedItems : itemID et le type de l’élément n’est plus partagé avec un groupe Exemple, mis en page pour plus de lisibilité |
Utilisateurs
Un événement de mise à jour est déclenché dès qu’une modification est apportée au profil de l’utilisateur. Toutefois, les modifications apportées au rôle d’un utilisateur, à un type d’utilisateur ou à une licence ne sont pas considérées comme une mise à jour du profil de l’utilisateur.
La table suivante répertorie les événements déclencheurs avec des utilisateurs :
| Événement déclencheur | Exemple d’URI | Propriétés |
|---|---|---|
Tous les événements déclencheurs pour tous les utilisateurs du portail | /users | |
Un utilisateur est ajouté à l’organisation | /users/add | |
N’importe quel utilisateur s’est connecté au portail | /users/signin | |
N’importe quel utilisateur s’est déconnecté du portail | /users/signout | |
N’importe quel utilisateur est supprimé | /users/delete | |
Le profil de n’importe quel utilisateur est mis à jour | /users/update | |
Le compte de n’importe quel utilisateur est désactivé | /users/disable | |
Le compte de n’importe quel utilisateur est activé | /users/enable | |
Un nouveau rôle a été affecté à n’importe quel utilisateur | /users/updateUserRole | |
Un type d’utilisateur a été affecté à n’importe quel utilisateur | /users/updateUserLicenseType | |
Tous les événements déclencheurs associés à un utilisateur en particulier | /users/<username> | |
Un utilisateur donné s’est connecté au portail | /users/<username>/signIn | |
Un utilisateur donné s’est déconnecté du portail | /users/<username>/signOut | |
Un utilisateur en particulier est supprimé | /users/<username>/delete | |
Le profil d’un utilisateur en particulier est mis à jour | /users/<username>/update | |
Le compte d’un utilisateur en particulier est désactivé | /users/<username>/disable | |
Le compte d’un utilisateur en particulier est activé | /users/<username>/enable | |
Un nouveau rôle a été affecté à un utilisateur en particulier | /users/<username>/updateUserRole | userRoleUpdatedTo : nouveau rôle attribué à l’utilisateur. Exemple, mis en page pour plus de lisibilité |
Un type d’utilisateur a été affecté à un utilisateur en particulier | /users/<username>/updateUserLicenseType | userLicenseTypeUpdatedTo : nouveau type d’utilisateur attribué à un utilisateur Exemple, mis en page pour plus de lisibilité |
Rôles
Un événement de mise à jour est déclenché dès qu’une modification est apportée aux rôles de votre organisation.
La table suivante répertorie les événements déclencheurs avec des rôles d’utilisateur :
| Événement déclencheur | Exemple d’URI | Propriétés |
|---|---|---|
Tous les événements déclencheurs pour tous rôles du portail | /roles | |
Un nouveau rôle est créé | /roles/add | name : nom du rôle qui a été créé, mis à jour ou supprimé. Exemple, mis en page pour plus de lisibilité |
Un rôle existant est mis à jour | /roles/updated | |
Un rôle existant est supprimé | /roles/delete |
Payloads
Une fois qu’un webhook est déclenché, une payload est livrée à la payload URL spécifique au format JSON. Chaque événement suit une structure JSON similaire avec des informations associées à l’événement.
| Clé | Type | Description |
|---|---|---|
| webhookName | chaîne | Nom du webhook qui a livré la payload. |
| webhookId | chaîne | ID du webhook qui a livré la payload. |
| portalURL | chaîne | URL du portail auprès duquel le webhook est inscrit. |
| when | timestamp | Heure de livraison de la payload. |
| username | chaîne | Utilisateur qui a déclenché l’événement. |
| userId | chaîne | ID de l’utilisateur qui a déclenché l’événement. |
| when | timestamp | Heure de l’événement. |
| operation | chaîne | Opération réalisée par l’utilisateur. Ce peut être, par exemple :
|
| source | chaîne | Type d’élément sur lequel l’opération a été réalisée. Il peut s’agir de item, de group ou de user. |
| id | chaîne | ID de l’élément source sur lequel l’opération a été réalisée. |
| properties | objet | Propriétés supplémentaires associées à l’événement. Ce peut être, par exemple :
|
URL de charge utile
L’utilisateur doit fournir une payload URL lorsqu’il crée un webhook. Cela permet de définir le lieu de livraison de la payload. Comme la payload est livrée via une requête HTTPS POST, le récepteur du webhook doit être configuré de façon à communiquer via HTTPS et à être accessible par le portail. Vous pouvez utiliser plusieurs services Web, tels que Microsoft Power Automate, Zapier et IFFT, pour configurer des processus personnalisés avec votre payload. Vous pouvez par exemple créer un processus de sorte que lorsque Microsoft Power Automate reçoit une payload, il analyse et met en forme la payload et l’envoie à un alias de messagerie. Vous pouvez également créer et personnaliser votre service web de façon à recevoir des payloads. Pour les organisations qui limitent l’accès à Internet, la création d’un service web personnalisé pour recevoir les payloads est recommandée. Consultez nos exemples SDK d’entreprise pour un servlet Java prêt à l’emploi.
Payload d’exemple
Voici un exemple de payload illustrant la mise à jour d’un groupe spécifique :
{
"info": {
"webhookName": "Group monitoring",
"webhookId": "72fed926aeb74c9ca8a22aacddc6725a",
"portalURL": "https://orgURL/portal/",
"when": 1543192196521
},
"events": [
{
"username": "administrator",
"userId": "173dd04b69134bdf99c5000aad0b6298",
"when": 1543192196521,
"operation": "update",
"source": "group",
"id": "173dd04b69134bdf99c5000aad0b6298",
"properties": {}
}
]
}
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 :
- Accédez au répertoire Portal for ArcGIS.https://organization.domain.com/context/sharing/rest
- 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.
- 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://organization.domain.com/context/sharing/rest/portals/<orgID>
- Faites défiler la page vers le bas, jusqu’à Webhooks, sous Child Resources (Ressources enfant).https://organization.domain/com/context/sharing/rest/portals/<orgID>/webhooks
- Sous Supported Operation (Opérations prises en charge), sélectionnez Create Webhook.
- Spécifiez les paramètres de votre webhook.
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://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks
Gérer les webhooks
Vous pouvez gérer vos webhooks via le répertoire du portail ArcGIS en émettant une demande au format suivant :
https://organization.domain.com/context/sharing/rest/<orgID>/webhooks/<webhookID>.
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.
Configurer les paramètres avancés
Plusieurs paramètres avancés permettent de personnaliser davantage vos webhooks. Ils sont appliqués à tous les webhooks configurés dans votre portail et sont accessible depuis https://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks/settings.
L’opération Update vous permet de mettre à jour les paramètres suivants :
- Nombre de tentatives de livraison : indiquez le nombre de tentatives qui seront effectuées pour livrer une payload. Le nombre par défaut est de trois tentatives, mais vous pouvez l’augmenter à cinq au maximum.
- Délai d’expiration de la notification : indiquez combien de temps une connexion va attendre la réception d’une réponse. Si aucune réponse n’est reçue pendant cet intervalle, la connexion expire et la tentative de notification est considérée comme ayant échoué.
- Temps écoulé entre les tentatives de livraison : indiquez le temps entre chaque tentative de livraison de la payload. La valeur par défaut est de 30 secondes, mais vous pouvez l’augmenter à 100 secondes au maximum ou la réduire à 1 seconde au minimum.
Consultez la documentation sur l’API des webhooks pour plus d’informations sur la configuration des paramètres avancés.
Vous avez un commentaire à formuler concernant cette rubrique ?