Element webhook to mechanizm umożliwiający aplikacji przesyłanie do innych aplikacji informacji sterowanych zdarzeniami. Administrator portalu ArcGIS Enterprise może tworzyć i konfigurować elementy webhook oraz zarządzać nimi. Elementy webhook możesz skonfigurować do automatycznego powiadamiania o wystąpieniu zdarzeń powiązanych z elementami portalu, grupami i użytkownikami. Po wyzwoleniu elementu webhook wysyłane jest żądanie HTTP do unikalnego, zdefiniowanego przez użytkownika adresu URL ładunku w celu podania informacji dotyczących zdarzenia.
Kluczowe terminy
Poniżej znajdują się kluczowe terminy związane z elementem webhook:
- Zdarzenie wyzwalacza — operacja skonfigurowana do wyzwolenia elementu webhook. Element webhook można na przykład skonfigurować tak, aby został wyzwolony, gdy w instytucji zostanie zaktualizowana konkretna grupa lub zostanie udostępniony element. Element webhook może mieć więcej niż jedno zdarzenie wyzwalacza.
- Ładunek — dane zdarzenia wyzwalacza dostarczane przez element webhook po wystąpieniu podanego zdarzenia. Informacje te mają format JSON. Zapoznaj się z poniższą sekcją Ładunki, aby uzyskać więcej informacji.
- Adres URL ładunku — lokalizacja, do której zostanie wysłany ładunek. Adres URL ładunku można utworzyć za pomocą usługi, na przykład Microsoft Power Automate, Zapier lub IFTTT. Możesz również utworzyć własny niestandardowy punkt końcowy usługi internetowej na wybranej przez siebie platformie.
Przykładowy przypadek zastosowania
Elementy webhook pozwalają na integrację procedur wykonywania zadań w systemach i istnieje wiele sposobów wykorzystania elementów webhook w instytucji.
Monitorowanie aktywności w oprogramowaniu ArcGIS Enterprise
Za pomocą elementu webhook można monitorować aktywność w oprogramowaniu ArcGIS Enterprise. Istnieje na przykład możliwość subskrypcji wszystkich zdarzeń powiązanych z konkretnym elementem. Element webhook jest wyzwalany, gdy właściwości elementu zostają zaktualizowane i żądanie HTTPS dostarczy ładunek zawierający dane opisujące to zdarzenie. Możesz zdecydować, gdzie ten ładunek jest dostarczany i odpowiednio zadziałać po otrzymaniu informacji.
Obsługiwane zdarzenia wyzwalacza
W momencie tworzenia elementu webhook następuje subskrypcja zdarzeń wyzwalacza. Ponieważ te zdarzenia są operacjami portalu, identyfikator URI tej operacji musi zostać podany w konfiguracji elementu webhook. Poniższe sekcje opisują dostępne zdarzenia wyzwalacza i powiązany identyfikator URI.
Atrybuty
Właściwości elementu, które mogą zostać zaktualizowane, zależą od typów elementu. Istnieją unikalne działania, które wyzwalają operację /update (aktualizacja). Jeśli na przykład element jest mapą internetową, aktualizacja znacznika, skonfigurowanie okna podręcznego lub zmiana mapy bazowej będą zdarzeniami aktualizacji, które wyzwolą element webhook.
Poniższa tabela zawiera listę zdarzeń wyzwalacza dla obsługiwanych elementów portalu, w tym map internetowych, aplikacji internetowych, warstw, pakietów, dokumentów PDF itd.:
| Zdarzenie wyzwalacza | Przykład identyfikatora URI |
|---|---|
Wszystkie zdarzenia wyzwalacza dla wszystkich elementów | /items |
Dowolny element zostanie dodany do portalu | /items/add |
Dowolny element zostanie usunięty | /items/delete |
Dowolny element zostanie zaktualizowany | /items/update |
Dowolny element zostanie przeniesiony lub nastąpi zmiana jego właściciela | /items/move |
Dowolny element zostanie opublikowany | /items/publish |
Dowolny element zostanie udostępniony | /items/share |
Dowolny element przestanie być udostępniany | /items/unshare |
Nastąpi ponowne przypisanie prawa własności do dowolnego elementu | /items/reassign |
Wszystkie zdarzenia wyzwalacza dla konkretnego elementu | /items/<itemID> |
Konkretny element zostanie usunięty | /items/<itemID>/delete |
Zostaną zaktualizowane właściwości konkretnego elementu | /items/<itemID>/update |
Zostanie zmieniony właściciel konkretnego elementu lub ten element zostanie przeniesiony | /items/<itemID>/move |
Konkretny element zostanie opublikowany | /items/<itemID>/publish |
Konkretny element zostanie udostępniony | /items/<itemID>/share |
Konkretny element przestanie być udostępniany | /items/<itemID>/unshare |
Nastąpi ponowne przypisanie prawa własności do konkretnego elementu | /items/<itemID>/reassign |
Grupy
Wszystkie zmiany ogólne wprowadzone w ustawieniach grupy stanowią aktualizację. Na przykład zmiana dostępu grupy wyzwoli zdarzenie aktualizacji.
Poniższa tabela zawiera listę zdarzeń wyzwalacza powiązanych z grupami:
| Zdarzenie wyzwalacza | Przykład identyfikatora URI |
|---|---|
Wszystkie zdarzenia wyzwalacza dla wszystkich grup | /groups |
Grupa zostanie dodana | /groups/add |
Dowolna grupa zostanie zaktualizowana | /groups/update |
Dowolna grupa zostanie usunięta | /groups/delete |
Dla dowolnej grupy zostanie włączona opcja Ochrona przed usunięciem | /groups/protect |
Dla dowolnej grupy zostanie wyłączona opcja Ochrona przed usunięciem | /groups/unprotect |
Do dowolnej grupy zostanie zaproszony użytkownik | /groups/invite |
Do dowolnej grupy zostanie dodany użytkownik | /groups/addUsers |
Z dowolnej grupy zostanie usunięty użytkownik | /groups/removeUsers |
W dowolnej grupie zostanie zaktualizowana rola użytkownika | /groups/updateUsers |
Nastąpi ponowne przypisanie prawa własności dowolnej grupy | /groups/reassign |
Wszystkie zdarzenia wyzwalacza dla konkretnej grupy | /groups/<groupID> |
Konkretna grupa zostanie zaktualizowana | /groups/<groupID>/update |
Konkretna grupa zostanie usunięta | /groups/<groupID>/delete |
Dla konkretnej grupy zostanie włączona opcja Ochrona przed usunięciem | /groups/<groupID>/protect |
Dla konkretnej grupy zostanie wyłączona opcja Ochrona przed usunięciem | /groups/<groupID>/unprotect |
Do konkretnej grupy zostanie zaproszony użytkownik | /groups/<groupID>/invite |
Do konkretnej grupy zostanie dodany użytkownik | /groups/<groupID>/addUsers |
Z konkretnej grupy zostanie usunięty użytkownik | /groups/<groupID>/removeUsers |
W konkretnej grupie zostanie zaktualizowana rola użytkownika | /groups/<groupID>/updateUsers |
Nastąpi ponowne przypisanie prawa własności konkretnej grupy | /groups/<groupID>/reassign |
Użytkownicy
Zdarzenie aktualizacji jest wyzwalane za każdym razem, gdy jest wprowadzana zmiana w profilu użytkownika. Jednak zmiany obejmujące rolę użytkownika, typ użytkownika lub licencję nie są uwzględniane jako aktualizacja profilu użytkownika.
Poniższa tabela zawiera listę zdarzeń wyzwalacza powiązanych z użytkownikami:
| Zdarzenie wyzwalacza | Przykład identyfikatora URI |
|---|---|
Wszystkie zdarzenia wyzwalacza dla wszystkich użytkowników w portalu | /users |
Użytkownik zostanie dodany do instytucji | /users/add |
Dowolny użytkownik zalogował się do portalu | /users/signin |
Dowolny użytkownik wylogował się z portalu | /users/signout |
Dowolny użytkownik zostanie usunięty | /users/delete |
Profil dowolnego użytkownika zostanie zaktualizowany | /users/update |
Konto dowolnego użytkownika zostanie wyłączone | /users/disable |
Konto dowolnego użytkownika zostanie włączone | /users/enable |
Do dowolnego użytkownika przypisano nową rolę | /users/updateUserRole |
Do dowolnego użytkownika przypisano nowy typ użytkownika | /users/updateUserLicenseType |
Wszystkie zdarzenia wyzwalacza powiązane z konkretnym użytkownikiem | /users/<username> |
Podany użytkownik zalogował się do portalu | /users/<username>/signIn |
Podany użytkownik wylogował się z portalu | /users/<username>/signOut |
Konkretny użytkownik zostanie usunięty | /users/<username>/delete |
Profil konkretnego użytkownika zostanie zaktualizowany | /users/<username>/update |
Konto konkretnego użytkownika zostanie wyłączone | /users/<username>/disable |
Konto konkretnego użytkownika zostanie włączone | /users/<username>/enable |
Do konkretnego użytkownika przypisano nową rolę | /users/<username>/updateUserRole |
Do konkretnego użytkownika przypisano nowy typ użytkownika | /users/<username>/updateUserLicenseType |
Role
Zdarzenie aktualizacji jest wyzwalane za każdym razem, gdy jest wprowadzana zmiana w rolach w instytucji.
Poniższa tabela zawiera listę zdarzeń wyzwalacza powiązanych z rolami użytkowników:
| Zdarzenie wyzwalacza | Przykład identyfikatora URI |
|---|---|
Wszystkie zdarzenia wyzwalacza dla wszystkich ról w portalu | /roles |
Zostanie utworzona nowa rola | /roles/add |
Zostanie zaktualizowana istniejąca rola | /roles/updated |
Zostanie usunięta istniejąca rola | /roles/delete |
Ładunki
Po wyzwoleniu elementu webhook do konkretnego adresu URL ładunku zostaje dostarczony ładunek w formacie JSON. Każde zdarzenie korzysta z podobnego schematu JSON z użyciem informacji odpowiednich dla danego zdarzenia.
| Klucz | Typ | Opis |
|---|---|---|
| webhookName | ciąg | Nazwa elementu webhook, który dostarczył ładunek. |
| webhookId | ciąg | Identyfikator elementu webhook, który dostarczył ładunek. |
| portalURL | ciąg | Adres URL portalu, w którym jest rejestrowany element webhook. |
| when | timestamp | Czas dostarczenia ładunku. |
| username | ciąg | Użytkownik, który wyzwolił zdarzenie. |
| userId | ciąg | Identyfikator użytkownika, który wyzwolił zdarzenie. |
| when | timestamp | Czas wystąpienia zdarzenia. |
| operation | ciąg | Operacja wykonana przez użytkownika. Dostępne możliwości:
|
| source | ciąg | Typ elementu, na którym wykonano operację. Może to być item, group lub user. |
| id | ciąg | Identyfikator elementu źródłowego, na którym wykonano operację. |
| properties | obiekt | Właściwości dodatkowe powiązane ze zdarzeniem. Dostępne możliwości:
|
Adres URL ładunku
Adres URL ładunku musi zostać podany przez użytkownika w momencie tworzenia elementu webhook; definiuje on, gdzie zostanie dostarczony ładunek. Ponieważ ładunek jest dostarczany z użyciem żądania HTTPS POST, odbiornik elementu webhook powinien zostać skonfigurowany do komunikacji z użyciem protokołu HTTPS i być osiągalny przez portal. Do skonfigurowania niestandardowych procedur wykonywania zadań z danym ładunkiem można użyć wielu usług internetowych, na przykład Microsoft Power Automate, Zapier oraz IFFT. Można na przykład utworzyć procedurę wykonywania zadań, która po otrzymaniu ładunku przez usługę Microsoft Power Automate analizuje i formatuje ładunek i wysyła go na alias e-mail. Inną możliwością jest zbudowanie i dostosowanie własnej usługi internetowej do odbierania ładunków. W przypadku instytucji, która ogranicza dostęp do Internetu, zalecane jest zbudowanie niestandardowej usługi internetowej do odbierania ładunków. Gotowe do użycia serwlety Java zawierają przykłady w bibliotece Enterprise SDK.
Przykład ładunku
Poniższy przykładowy ładunek przestawia informację o zaktualizowaniu konkretnej grupy:
{
"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": {}
}]
}
Tworzenie elementu webhook
Elementami webhook można administrować tylko za pomocą aplikacji ArcGIS Portal Directory (interfejs API udostępniania). Następujące punkty opisują sposób tworzenia elementu webhook:
- Przejdź do aplikacji ArcGIS Portal Directory.https://machine.domain.com/webadaptor/sharing/rest
- Zaloguj się jako administrator.
Tylko administrator może tworzyć elementy webhook i zarządzać nimi.
Zostanie wyświetlona strona użytkownika administratora.
- Kliknij hiperłącze ID instytucji lub utwórz żądanie w poniższej postaci, aby przejść do strony zasobów Portale > Własny.https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
- Przewiń do dołu strony do elementu Webhooks w sekcji Zasoby podrzędne.https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
- W polu Obsługiwana operacja wybierz Create Webhook.
- Podaj parametry elementu webhook.
Szczegółowe informacje o tych parametrach zawiera dokumentacja interfejsu REST API elementu webhook.
Twój element webhook zostanie wyświetlony wraz z innymi elementami webhook: https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks.
Zarządzanie elementami webhook
Do zarządzania elementami webhook można użyć aplikacji ArcGIS Portal Directory, tworząc żądanie w następującej postaci:
https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.
Obsługiwane są następujące operacje zarządzania elementami webhook:
- Update Webhook — aktualizacja parametrów elementu webhook. Dla podanego elementu webhook można zaktualizować nazwę, adres URL ładunku, konfigurację lub zdarzenia wyzwalacza.
- Delete Webhook — usunięcie elementu webhook z portalu.
- Deactivate Webhook oraz Activate Webhook — dezaktywacja elementu webhook, która spowoduje zatrzymanie dostarczania ładunków w momencie wyzwolenia tego elementu webhook. Gdy element webhook zostaje dezaktywowany, dostępna staje się operacja Aktywuj element webhook pozwalająca wznowić dostarczanie ładunków.
Na stronie Notification Status są wyświetlone informacje dotyczące zdarzeń wyzwalaczy powiązanych z konkretnym elementem webhook. Za pomocą tej tabeli można monitorować element webhook, a także szczegóły dostarczonych ładunków, takie jak czas wyzwolenia elementu webhook, odpowiedzi odebrane z adresu URL ładunku i dostarczony ładunek. Rekordy wskazujące pomyślne dostarczenie ładunku są usuwane po jednym dniu. Rekordy wskazujące zakończone niepowodzeniem próby dostarczenia są przechowywane przez siedem dni.
Przykłady tych operacji zawiera temat Interfejs API elementów webhook.
Konfigurowanie parametrów zaawansowanych
Istnieje kilka parametrów zaawansowanych, których można użyć do dalszego dostosowania elementów webhook. Parametry te zostaną zastosowane względem wszystkich skonfigurowanych elementów webhook w portalu i są dostępne pod adresem https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings.
Operacja Update pozwala zaktualizować następujące parametry:
- Liczba prób dostarczenia — podaj liczbę prób, które zostaną wykonane w celu dostarczenia ładunku. Domyślnie są to trzy próby i można ich liczbę zwiększyć do pięciu.
- Limit czasu powiadomienia — podaj, przez jaki czas połączenie będzie oczekiwać na odebranie odpowiedzi. Jeśli w tym czasie nie zostanie odebrana odpowiedź, połączenie przekroczy limit czasu, a powiadomienie zostanie uznane za zakończone niepowodzeniem.
- Upływ czasu między próbami dostarczenia — podaj czas między poszczególnymi próbami dostarczenia ładunku. Domyślnie wynosi on 30 sekund i może zostać zwiększony do maksymalnie 100 sekund lub zmniejszony do minimalnie 1 sekundy.
Więcej informacji o sposobie konfigurowania parametrów zaawansowanych zawiera dokumentacja interfejsu API elementów webhook.
Często zadawane pytania dotyczące elementów webhook
Poniżej znajduje się lista typowych pytań, które pojawiają się podczas korzystania z elementów webhook.
Moja instancja portalu ArcGIS Enterprise jest wdrożona w odłączonym środowisku za zaporą mojej instytucji. Czy nadal mogę skonfigurować elementy webhook?
Tak. Aby skonfigurować elementy webhook, trzeba będzie użyć adresu URL ładunku, który jest osiągalny dla portalu ArcGIS Enterprise. W tym celu możesz zbudować aplikację niestandardową i wdrożyć ją na serwerze wewnętrznym.
Co stanowi aktualizację dla elementu, użytkownika lub grupy?
Jeśli dokonano subskrypcji elementów, użytkowników i grup portalu, element webhook zostaje wyzwolony po każdej aktualizacji ich właściwości. Jeśli na przykład subskrybowane są aktualizacje konkretnego elementu w portalu, element webhook zostaje wyzwolony po wprowadzeniu aktualizacji w tytule, znaczniku lub miniaturze elementu. Metodą określenia, czy działanie stanowi aktualizację w portalu, jest zbadanie ruchu sieciowego. Za każdym razem, gdy wynikiem działania jest wywołanie operacji Aktualizuj, to samo działanie może również wyzwolić element webhook nasłuchujący aktualizacji.
Korzystam z Zintegrowanego uwierzytelniania systemu Windows w portalu ArcGIS Enterprise. Czy nadal mogę subskrybować operacje logowania i wylogowania użytkownika do i z portalu (user/<username>/signIn)?
Począwszy od wersji 10.9, można używać zdarzenia wyzwalacza /signin do rejestrowania zdarzeń logowania w celu uwierzytelnienia w portalu, uwierzytelnienia w warstwie internetowej oraz logowania korporacyjnego.
Co się stanie, jeśli mój adres URL ładunku zostanie wyłączony lub stanie się niedostępny? Czy istnieje jakiś sposób na odzyskanie ładunku, który nie został dostarczony?
Jeśli portal próbuje dostarczyć ładunek na adres URL ładunku lub do odbiornika webhook, który jest nieosiągalny lub nie odpowiada, skonfigurowane parametry zaawansowane określą sposób i czas podjęcia przez portal kolejnej próby dostarczenia. Jeśli te dodatkowe próby dostarczenia ładunku również kończą się niepowodzeniem, zostają one potraktowane jako pojedyncze niepowodzenie dla zasady deactivationPolicy skonfigurowanej podczas tworzenia elementu webhook. Element webhook zostaje zdezaktywowany po spełnieniu zasady.
Po przejściu do statusu powiadomienia elementu webhook można wyświetlić wszystkie rozpoczęte dostawy ładunku i określić, czy zostały one dostarczone pomyślnie.