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 wyzwalacza	Przykład identyfikatora URI	Właściwości
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	sharedToGroups — sposób udostępnienia elementu (identyfikator grupy, instytucja lub wszyscy) Przykłady sformatowane pod kątem czytelności //groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }
Konkretny element przestanie być udostępniany	/items/<itemID>/unshare	unsharedFromGroups — sposób anulowania udostępnienia elementu (identyfikator grupy, instytucja lub wszyscy) Przykłady sformatowane pod kątem czytelności //Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }
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	Właściwości
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	invitedUserNames — nazwy użytkowników zaproszonych do grupy Przykład sformatowany pod kątem czytelności "properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }
Do konkretnej grupy zostanie dodany użytkownik	/groups/<groupID>/addUsers	addedUserNames — nazwy użytkowników, którzy zostali dodani do grupy. Przykład sformatowany pod kątem czytelności "properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }
Z konkretnej grupy zostanie usunięty użytkownik	/groups/<groupID>/removeUsers	removeUserNames — nazwy użytkowników usuniętych z grupy. Przykład sformatowany pod kątem czytelności "properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }
W konkretnej grupie zostanie zaktualizowana rola użytkownika	/groups/<groupID>/updateUsers	updateUserNames — nazwy użytkowników, których role grupy zostały zaktualizowane Przykład sformatowany pod kątem czytelności "properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }
Nastąpi ponowne przypisanie prawa własności konkretnej grupy	/groups/<groupID>/reassign
Element zostanie udostępniony grupie	/groups/<groupID>/itemShare	sharedItems — itemID i typ elementu zostaną udostępnione grupie. Przykład sformatowany pod kątem czytelności "properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }
Element przestanie być udostępniany konkretnej grupie	/groups/<groupID>/itemUnshare	unsharedItems — itemID i typ elementu przestaną być udostępniane grupie. Przykład sformatowany pod kątem czytelności "properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }

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	Właściwości
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	userRoleUpdatedTo — nowa rola, do której przypisano użytkownika. Przykład sformatowany pod kątem czytelności "properties": { "userRoleUpdatedTo": ["New role"] }
Do konkretnego użytkownika przypisano nowy typ użytkownika	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo — nowy typ użytkownika, do którego przypisano użytkownika. Przykład sformatowany pod kątem czytelności "properties": { "userLicenseTypeUpdatedTo": ["Editor"] }

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	Właściwości
Wszystkie zdarzenia wyzwalacza dla wszystkich ról w portalu	/roles
Zostanie utworzona nowa rola	/roles/add	name — nazwa roli, która została utworzona, zaktualizowana lub usunięta. Przykład sformatowany pod kątem czytelności "properties": { "name": ["New role"] }
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: 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.