Personalizacja API: nadpisania punktów dostępu i hooki

Gdzie to znaleźć

Moduł Administracja, ekran Import/Eksport, sekcja Personalizacja API, przycisk API.

Ekran jest zastrzeżony dla kont Premium i chroniony wzmocnionym uwierzytelnianiem: Omniscol ponownie pyta o hasło administratora, zanim otworzy okno. Ponieważ każde działanie na tym ekranie dotyka technicznego kontraktu integracji, jej wdrożenie odbywa się w porozumieniu z Omniscol.

Konfiguracja ogólna

Definiuje się tu nagłówki HTTP (format klucz1:wartość1;klucz2:wartość2) stosowane do wszystkich hooków. To naturalne miejsce, aby przenieść token uwierzytelniający do własnego serwera (na przykład Authorization: Bearer …, którego ten serwer oczekuje). W przypadku nadpisania uwierzytelnianie umieszcza się natomiast w nagłówkach właściwych dla punktu dostępu (zob. poniżej).

Nadpisanie punktu dostępu

Nadpisanie przedefiniowuje punkt dostępu API Omniscol tak, aby aplikacja internetowa wywoływała w jego miejsce inny adres URL. Trzy zastosowania, od najpotężniejszego do najprostszego.

Udostępnianie danych na żywo z systemu informacyjnego placówki

To najpotężniejsze zastosowanie. Punkt dostępu do odczytu przekierowuje się na zewnętrzny adres URL — zwykle na ETL, który pośredniczy w dostępie do wewnętrznego systemu informacyjnego placówki. Aplikacja internetowa pobiera wtedy dane na żywo z tego systemu, a nie z lokalnej kopii przechowywanej przez Omniscol.

Konkretnie: gdy adres przekierowania jest bezwzględnym adresem zewnętrznym, aplikacja internetowa wywołuje go wprost, bez pośrednictwa serwerów Omniscol, i przyjmuje odpowiedź w takiej postaci, w jakiej przyszła — dokładnie tak, jakby pochodziła z Omniscol. Jedyny warunek jest taki, aby system placówki odpowiadał w formacie oczekiwanym przez Omniscol dla tego punktu dostępu (identyczna struktura JSON): nie ma żadnego pośredniego przekodowania. Dla tego punktu dostępu lokalna kopia Omniscol nie jest już odpytywana; wyświetlane dane pochodzą — na żywo — z systemu placówki.

Przykład: baza przedmiotów placówki udostępniana na bieżąco z jej systemu informacyjnego, tak aby każda aktualizacja po stronie szkoły była natychmiast widoczna w Omniscol, bez ponownego importu.

Uwierzytelnianie wobec systemu placówki umieszcza się tutaj w nagłówkach właściwych dla punktu dostępu (na przykład Authorization: Bearer …), wpisywanych w wierszu nadpisania. Metodę HTTP również można narzucić osobno dla każdego punktu dostępu.

Przełączenie punktu dostępu samej aplikacji na żywe źródło zewnętrzne to możliwość równie potężna jak wymagająca: należy się nią posługiwać razem z działem informatycznym i w porozumieniu z Omniscol.

Wstawienie własnego serwera lub serwera proxy

Wywołania można też przepuścić przez własny serwer lub serwer proxy — na przykład aby zezwolić na współdzielenie zasobów między źródłami (CORS) albo wstawić własną logikę między aplikację internetową a Omniscol.

Wyłączenie punktu dostępu

Aby wyłączyć punkt dostępu, wystarczy nie podawać żadnego adresu przekierowania (metoda null).

Należy oszacować skutek dla interfejsu. Omniscol to jednostronicowa aplikacja internetowa (SPA), której elementy interfejsu są sterowane dostępnymi punktami dostępu: przyciski, zakładki i menu pojawiają się tylko wtedy, gdy istnieje punkt dostępu, od którego zależą. Wyłączenie punktu dostępu powoduje więc dynamiczne zniknięcie — przy następnym wyświetleniu — zależnych od niego elementów interfejsu, a po wyłączeniu wszystkich punktów dostępu danego modułu z nawigacji znika cały moduł. Elementy te są usuwane, a nie tylko ukrywane, i wszystko to odbywa się bez żadnej ingerencji w kod: wystarczy zmienić konfigurację i ponownie wczytać aplikację.

Tabela wymienia dla każdego punktu dostępu: jego klucz (wewnętrzny kod operacji), pierwotny adres URL, metodę HTTP, nowy adres URL przekierowania oraz nagłówki właściwe dla niego. Pole wyszukiwania pozwala odnaleźć punkt dostępu, który ma być nadpisany.

Hooki (wywołania wychodzące)

Hook zleca Omniscolowi wysłanie żądania HTTP na wskazany adres URL po tym, jak operacja się powiedzie. To mechanizm pozwalający informować system zewnętrzny w czasie rzeczywistym — ekran informacyjny, platformę edukacyjną, system kadrowy, własną synchronizację…

Hook można podłączyć na dwa sposoby:

• do konkretnego punktu dostępu (klucz operacji);
• do zdarzenia zbiorczego, które obejmuje od razu całą rodzinę operacji. Istnieją trzy zdarzenia zbiorcze:
  • zmiana planu lekcji — zmiana dotykająca obowiązującego planu lekcji, wraz ze skutkami ubocznymi: zapisanie planu lekcji, utworzenie, przeniesienie lub usunięcie lekcji, publikacja planu lekcji, nieobecności nauczyciela lub klasy, gdy tylko obejmują jakąkolwiek datę, oraz usunięcia strukturalne (sali, przedmiotu…) w planie lekcji opublikowanym — usunięcie przedmiotu usuwa lekcje, które z niego korzystały, co samo w sobie jest zmianą. Edycje zamknięte w nieopublikowanej wersji roboczej go nie wyzwalają;
  • zmiana nauczyciela (dodanie, aktualizacja lub usunięcie);
  • zmiana przedmiotu (przedmioty niestandardowe).

Dla każdego hooka podaje się adres URL wywołania zwrotnego, metodę HTTP, pole wyboru „z danymi” (czy dołączyć treść pierwotnego żądania?) oraz własne nagłówki.

Co otrzymuje serwer placówki

Wywołanie jest wysyłane jako application/json i zawiera, obok podanych nagłówków:

• treść pierwotnego żądania, jeśli opcja „z danymi” jest włączona;
• blok metadanych Omniscol: wywołany adres URL, kod punktu dostępu, metodę, parametry, token uwierzytelniający użytkownika, identyfikator placówki oraz konfigurację samego hooka;
• nagłówki umożliwiające śledzenie: X-OS-original-query, X-OS-original-endpoint, X-OS-auth i X-School.

Przy zdarzeniu zmiana planu lekcji, gdy opcja „z danymi” jest włączona, wywołanie zawiera dodatkowo zestawienie różnic w lekcjach (lekcje dodane, zmienione, usunięte) — przydatne, aby propagować tylko to, co się zmieniło.

Zachowanie

Hooki wychodzą w tle, po tym, jak działanie użytkownika doszło do skutku: nie spowalniają interfejsu i nie blokują go, gdy serwer placówki zawiedzie. Nieudane wywołanie wychodzące jest zapisywane w dzienniku, bez przerywania pracy w Omniscol. Każde wywołanie ma krótki limit czasu (kilka sekund): serwer placówki musi szybko potwierdzić odbiór, a resztę przetworzyć po swojej stronie.

Warto wiedzieć

• API Omniscol udostępnia podzbiór operacji; nadpisanie lub hook działa wyłącznie na punktach dostępu faktycznie udostępnionych. Lista i uwierzytelnianie: zob. API Omniscol.
• W przypadku integracji z gotowym oprogramowaniem (ERP, system kadrowy, platforma edukacyjna) dedykowana synchronizacja jest zwykle lepiej dopasowana — zob. Synchronizacja z systemami zewnętrznymi. Wewnętrznie korzysta ona z tego samego mechanizmu hooków.
• Aby agent AI mógł odpytywać dane konta bez prac programistycznych, zob. MCP — podłączenie zewnętrznego agenta AI.