Créer et gérer des webhooks—Portal for ArcGIS | Documentation d’ArcGIS Enterprise

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é `//groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }`
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é `//Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }`
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é `"properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }`
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é `"properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }`
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é `"properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }`
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é `"properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }`
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é `"properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }`
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é `"properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }`

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é `"properties": { "userRoleUpdatedTo": ["New role"] }`
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é `"properties": { "userLicenseTypeUpdatedTo": ["Editor"] }`

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é `"properties": { "name": ["New role"] }`
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 : add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
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 : sharedToGroups : mode de partage d’un élément (ID de groupe, Organisation ou Tout le monde) unsharedFromGroups : mode d’annulation du partage d’un élément (ID de groupe, Organisation ou Tout le monde) removeUserNames : noms d’utilisateur correspondant aux utilisateurs supprimés d’un groupe updateUserNames : noms d’utilisateur correspondant aux utilisateurs dont les rôles de groupe ont été mis à jour invitedUserNames : noms d’utilisateur correspondant aux utilisateurs invités dans un groupe addedUserNames : noms d’utilisateur correspondant aux utilisateurs qui ont été ajoutés dans un groupe userRoleUpdatedTo : nouveau rôle attribué à l’utilisateur reassignedTo : nouvel utilisateur auquel un élément ou un groupe a été réattribué userLicenseTypeUpdatedTo : nouveau type d’utilisateur attribué à un utilisateur name : nom du rôle qui a été créé, mis à jour ou supprimé

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://machine.domain.com/webadaptor/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://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
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
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://machine.domain.com/webadaptor/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://machine.domain.com/webadaptor/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://machine.domain.com/webadaptor/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 ?