Skip To Content

Tworzenie elementów webhook i zarządzanie nimi

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 wyzwalaczaPrzykł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 wyzwalaczaPrzykł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 wyzwalaczaPrzykł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 wyzwalaczaPrzykł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.

KluczTypOpis
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:

  • add
  • addUsers
  • delete
  • disable
  • enable
  • invite
  • move
  • protect
  • publish
  • removeUsers
  • share
  • unprotect
  • unshare
  • update
  • updateUsers
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:

  • sharedToGroups — sposób udostępnienia elementu (identyfikator grupy, instytucja lub wszyscy)
  • unsharedFromGroups — sposób anulowania udostępnienia elementu (identyfikator grupy, instytucja lub wszyscy)
  • removeUserNames — nazwy użytkowników usuniętych z grupy
  • updateUserNames — nazwy użytkowników, których role grupy zostały zaktualizowane
  • invitedUserNames — nazwy użytkowników zaproszonych do grupy
  • addedUserNames — nazwy użytkowników, którzy zostali dodani do grupy
  • userRoleUpdatedTo — nowa rola, do której przypisano użytkownika
  • reassignedTo — nowy użytkownik, do którego ponownie przypisano element lub grupę
  • userLicenseTypeUpdatedTo — nowy typ użytkownika, do którego przypisano użytkownika
  • name – nazwa roli, która została utworzona, zaktualizowana lub usunięta

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:

  1. Przejdź do aplikacji ArcGIS Portal Directory.
    https://machine.domain.com/webadaptor/sharing/rest
  2. Zaloguj się jako administrator.

    Tylko administrator może tworzyć elementy webhook i zarządzać nimi.

    Zostanie wyświetlona strona użytkownika administratora.

  3. 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>
  4. Przewiń do dołu strony do elementu Webhooks w sekcji Zasoby podrzędne.
    https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
  5. W polu Obsługiwana operacja wybierz Create Webhook.
  6. 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.