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.
Pobierz aplikację
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 |
Dodanie elementu do portalu | /items/add |
Wszystkie zdarzenia wyzwalacza dla konkretnego elementu | /items/<itemID> |
Usunięcie konkretnego elementu | /items/<itemID>/delete |
Aktualizacja właściwości konkretnego elementu | /items/<itemID>/update |
Przeniesienie elementu lub zmiana właściciela elementu | /items/<itemID>/move |
Opublikowanie konkretnego elementu | /items/<itemID>/publish |
Udostępnienie konkretnego elementu | /items/<itemID>/share |
Anulowanie udostępnienia konkretnego elementu | /items/<itemID>/unshare |
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 |
Dodawanie grupy | /groups/add |
Wszystkie zdarzenia wyzwalacza dla konkretnej grupy | /groups/<groupID> |
Aktualizacja konkretnej grupy | /groups/<groupID>/update |
Usunięcie konkretnej grupy | /groups/<groupID>/delete |
Włączenie opcji Ochrona przed usunięciem dla konkretnej grupy | /groups/<groupID>/protect |
Wyłączenie opcji Ochrona przed usunięciem dla konkretnej grupy | /groups/<groupID>/unprotect |
Zaproszenie użytkownika do przyłączenia się do konkretnej grupy | /groups/<groupID>/invite |
Dodanie użytkownika do konkretnej grupy | /groups/<groupID>/addUsers |
Usunięcie użytkownika z konkretnej grupy | /groups/<groupID>/removeUsers |
Aktualizacja roli użytkownika w konkretnej grupie | /groups/<groupID>/updateUsers |
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 |
Dodanie użytkownika do instytucji | /users/add |
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 |
Usunięcie konkretnego użytkownika | /users/<username>/delete |
Aktualizacja profilu konkretnego użytkownika | /users/<username>/update |
Wyłączenie konta konkretnego użytkownika | /users/<username>/disable |
Włączenie konta konkretnego użytkownika | /users/<username>/enable |
Ł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 | Folder nie zawiera prawidłowego projektu aplikacji | Opis |
---|---|---|
webhookName | ciąg znakowy | Nazwa elementu webhook, który dostarczył ładunek. |
webhookId | ciąg znakowy | Identyfikator elementu webhook, który dostarczył ładunek. |
portalURL | ciąg znakowy | Adres URL portalu, w którym jest rejestrowany element webhook. |
when | timestamp | Czas dostarczenia ładunku. |
username | ciąg znakowy | Użytkownik, który wyzwolił zdarzenie. |
userId | ciąg znakowy | Identyfikator użytkownika, który wyzwolił zdarzenie. |
when | timestamp | Czas wystąpienia zdarzenia. |
operation | ciąg znakowy | Operacja wykonana przez użytkownika. Może to być:
|
source | ciąg znakowy | Typ elementu, na którym wykonano operację. Może to być item, group lub user. |
id | ciąg znakowy | Identyfikator elementu źródłowego, na którym wykonano operację. |
properties | obiekt | Właściwości dodatkowe powiązane ze zdarzeniem. Może to być:
|
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://machineURL/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. Następujące punkty opisują sposób tworzenia elementu webhook:
- Przejdź do aplikacji ArcGIS Portal Directory.https://webadaptorhost.domain.com/webadaptorname/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- Przewiń do dołu strony do elementu Webhooks w sekcji Zasoby podrzędne.https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/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
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 przez portal 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 zostanie wyzwolony po każdej aktualizacji ich właściwości. Jeśli na przykład zostałaby subskrybowana aktualizacja konkretnego elementu w portalu, element webhook zostałby wyzwolony po wprowadzeniu aktualizacji w tytule, znaczniku lub miniaturze elementu. Łatwą metodą określenia, czy działanie stanowi aktualizację w portalu, jest sprawdzenie ruchu sieciowego. Za każdym razem, gdy wynikiem działania jest wywołanie operacji Aktualizuj, to samo działanie będzie również w stanie wyzwolić element webhook nasłuchujący aktualizacji.
Korzystam z Zintegrowanego uwierzytelniania systemu Windows w portalu ArcGIS Enterprise. Czy nadal subskrybuję operacje logowania i wylogowania użytkownika do i z portalu (user/<username>/signIn)?
Te zdarzenia są wyzwalane wówczas, gdy użytkownik loguje się lub wylogowuje z użyciem uwierzytelniania OAuth. Z tego powodu Zintegrowane uwierzytelnianie systemu Windows i SAML nie są obsługiwane. Jednak wbudowane zabezpieczenia portalu i infrastruktura PKI obsługują zdarzenia logowania i wylogowania.
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ż zakończą się niepowodzeniem, zostaną one potraktowane jako pojedyncze niepowodzenie dla zasady deactivationPolicy skonfigurowanej podczas tworzenia elementu webhook. Element webhook zostanie dezaktywowany 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.