Identity Governance & Administration
sara.next
  1. sara.next
  2. Technologia
  3. Obsługa błędów i wyjątków

Technologia · Dla deweloperów

Obsługa błędów i wyjątków

Najważniejszy test integracji IGA zaczyna się wtedy, gdy zatwierdzona zmiana nie może zostać wykonana — albo nie wiadomo, czy została wykonana.

  • Implemented / Not implemented
  • timeout
  • idempotencja

Kontekst

Różnica między błędem technicznym a błędem procesu

Nie wszystkie niepowodzenia są takie same. Zgłoszenie może zostać odrzucone na etapie autoryzacji, skrypt może nie skompilować się, REST API może odmówić dostępu, a system docelowy może wykonać zmianę, lecz nie potwierdzić jej przed timeoutem. Każdy z tych przypadków wymaga innej reakcji, ponieważ inne jest ryzyko pozostawienia nieprawidłowych uprawnień.

Mechanizm autoimplementacji sara.next posługuje się stanami „Implemented” i „Not implemented”, z komunikatem o błędzie. Dokumentacja omawia m.in. niepowodzenie kompilacji skryptu Groovy, wyjątki przy nieobecnych zmiennych oldUser lub request.oldAtar, błędne wartości identyfikatorów, różnice w schemacie SQL, błędy uwierzytelnienia REST oraz opóźnienie po stronie API.

Macierz obsługi

Praktyczne scenariusze

Praktyczne scenariusze
ProblemPotencjalna przyczynaZalecane działanie
Błąd kompilacji GroovySkładnia, brak zmiennej, błędny typ danychPoprawka w środowisku testowym, testy jednostkowe skryptu, ponowny odbiór
NullPointerExceptionUżycie oldUser w niewłaściwej operacji lub brak oldAtarSprawdzenie kontraktu zmiennych i null-safe navigation
HTTP 401/403Niepoprawny lub niewystarczający sekret albo zakres kontaKontrola konfiguracji połączenia i uprawnień, bez logowania sekretów
HTTP 429/503Limit API albo przejściowa niedostępnośćKontrolowana obsługa rate limit, ustalenie sposobu retry
Timeout po wysłaniuNiepewność, czy żądanie wykonało sięNajpierw odczyt stanu docelowego, dopiero potem decyzja o ponowieniu
SQL zwrócił błądUprawnienia, constraint, niepoprawne dane, blokadaAnaliza transakcji i danych, poprawka bez nadawania nadmiarowych przywilejów
Weryfikacja nie przeszłaNiespójny stan, błąd zapytania lub opóźnienie propagacjiPorównanie stanu faktycznego z oczekiwanym, identyfikacja punktu niezgodności
Część zmian w zewnętrznych systemach się powiodłaBrak transakcji rozproszonejProcedura kompensacyjna, ręczna interwencja, raport incydentu lub wyjątku

Diagnostyka

Typowe błędy skryptów i ich przyczyny

Komunikaty, które najczęściej pojawiają się przy pierwszej konfiguracji autoimplementacji.

Typowe błędy skryptów i ich przyczyny
ObjawPrzyczynaCo zrobić
Groovy script compilation failed: ...Błąd składni skryptu: niezamknięty napis, brakujący nawias albo niepoprawna składnia Groovy.Komunikat błędu zawiera numer wiersza — od niego zacznij.
NullPointerException przy oldUseroldUser jest dostępny tylko dla wniosków Delete i Replace. Odwołanie do niego w skrypcie Create kończy się wyjątkiem.Jeżeli skrypt jest współdzielony, używaj bezpiecznej nawigacji: oldUser?.samAccountName.
NullPointerException przy request.oldAtarrequest.oldAtar jest ustawiane tylko dla wniosków Modify i Delete (przechowuje poprzedni rekord dostępu).Zawsze używaj bezpiecznej nawigacji: request.oldAtar?.dimensionValues.
Weryfikacja SQL nieoczekiwanie zwraca falseZapytanie SELECT nie zwróciło wierszy: login nie odpowiada zapisanej wartości (wielkość liter, prefiks domeny), tabela lub widok są inne niż zakładano albo skrypt implementacyjny nie wykonał zmiany.Sprawdź komentarz przy pozycji w kolejce — zawiera szczegóły.
Weryfikacja REST nieoczekiwanie zwraca falseŻądanie GET zwróciło status inny niż 2xx: błędna ścieżka lub zasób nie powstał, nieudane uwierzytelnienie albo opóźnienie po stronie API.Sprawdź poświadczenia połączenia REST i rozważ, czy weryfikacja musi następować natychmiast.

Odzyskiwanie

Cztery zasady odzyskiwania

  1. Nie ponawiaj „w ciemno”

    Po timeoutach sprawdź stan, by nie tworzyć podwójnych kont albo konfliktujących przypisań.

  2. Oddziel retry od decyzji biznesowej

    Ponowne wykonanie zatwierdzonej operacji może być technicznie uzasadnione, lecz zmiana zakresu uprawnienia wymaga nowej decyzji.

  3. Używaj idempotencji tam, gdzie to możliwe

    grant powinien wykrywać istniejące przypisanie, a revoke brak przypisania; ostateczne zachowanie zależy od docelowego API lub SQL.

  4. Dokumentuj rozbieżności

    Przechowuj identyfikator zgłoszenia, aplikację, typ operacji, informację o błędzie, wynik kontroli stanu oraz decyzję o sposobie przywrócenia spójności.

Transakcje

Zależność od modelu transakcyjnego

W SQL dokumentacja wskazuje wykonanie listy instrukcji w jednej transakcji. Nie należy przenosić tego wniosku na kilka wywołań HTTP lub kilka systemów docelowych. W REST operacja POST zakończona timeoutem nie daje podstaw do uznania, że nie zadziałała. Prawidłowy projekt wykorzystuje zapytanie kontrolne do odczytania rzeczywistego przypisania.

sara.nextSkrypt / adapterSystem docelowy01 Zatwierdzona operacja02 POST: żądanie zmiany03 Timeout: wynik nieznany04 Zapytanie kontrolne05 Rzeczywiste przypisanie06 Decyzja: ponowić czy nie07 Status z informacją o błędzie
Schemat poglądowy wzorca rekomendowanego — nie opis automatycznego zachowania platformy.

Logi

Obsługa błędów bez ujawniania danych wrażliwych

Logi powinny zawierać identyfikator korelacyjny, typ operacji, status i kod błędu.

UwagaLogi nie powinny zawierać haseł, tokenów Bearer, API key, pełnych danych osobowych ani treści zapytań z sekretami.

W środowiskach regulowanych należy zdefiniować politykę retencji i uprawnienia dostępu do logów. Implementacja tych kontroli powinna zostać zweryfikowana w konkretnej konfiguracji.

Opinia eksperta wdrożeniowego

Najbardziej ryzykowny status: „nie wiem”

W procesie nadawania uprawnień najbardziej ryzykowny status brzmi: „nie wiem, czy zmiana się wykonała”. Właśnie dla takich przypadków projektowałbym integrację.

Monitoring błędów ma sens dopiero wtedy, gdy wiadomo, kto odpowiada za decyzję, jak sprawdzić faktyczny stan i jak zamknąć wyjątek bez utraty śladu audytowego.

Zakres

Co potwierdza dokumentacja, a co wymaga projektu

Potwierdzone

  • podstawowe statusy rezultatu autoimplementacji,
  • możliwość weryfikacji,
  • przykłady błędów Groovy, SQL i REST.

Wzorce rekomendowane, nie gwarancje platformy

  • polityka retry i backoff,
  • dead-letter queue,
  • circuit breaker,
  • centralne alertowanie,
  • rozproszona kompensacja,
  • automatyczna rekonsyliacja.

Zweryfikuj z nami scenariusze awaryjne integracji

Najlepiej jeszcze przed uruchomieniem produkcyjnym.