Krótka odpowiedź: Subscription informuje serwer FHIR, aby powiadomił ten punkt końcowy o zmianach w zasobach pasujących do tych warunków. W FHIR R4 warunki te to ciąg wyszukiwania (criteria: "Observation?patient=123&code=85354-9"), a serwer wysyła pasujący zasób do punktu końcowego REST, websocketa, e-maila lub wiadomości FHIR. W R4B i R5 model został przebudowany wokół SubscriptionTopic: serwer publikuje zdarzenia, o których może powiadomić, klient subskrybuje temat z filtrami, a powiadomienia docierają jako Bundle typu subscription-notification, który zawsze zaczyna się od zasobu SubscriptionStatus. Przewodnik implementacyjny Subscriptions R5 Backport pozwala serwerom R4 oferować nowy model.
R4: subskrypcje oparte na kryteriach
W FHIR R4, subskrypcja jest oparta na kryteriach: klient tworzy zasób Subscription, którego kryterium jest ciąg wyszukiwania, taki jak Observation?code=…&patient=…, a kanał to rest-hook, websocket, email, sms lub message. Serwer ocenia kryteria dla każdego utworzenia i aktualizacji oraz wysyła (POST) każdy pasujący zasób lub puste powiadomienie do punktu końcowego.
{
"resourceType": "Subscription",
"status": "requested",
"reason": "Blood pressure alerts for the hypertension clinic",
"criteria": "Observation?code=http://loinc.org|85354-9&patient=Patient/123",
"channel": {
"type": "rest-hook",
"endpoint": "https://clinic.example.org/hooks/bp",
"payload": "application/fhir+json",
"header": ["Authorization: Bearer <token>"]
}
}
Serwer ocenia kryteria dla każdego utworzenia i aktualizacji. Gdy zasób pasuje, POSTuje go do punktu końcowego (lub POSTuje pusty korpus, jeśli payload jest pominięty, aby klient sam pobrał zasób). Działało to, ale z trzema problemami: serwery nie mogły powiedzieć, jakie kryteria obsługują, klienci nie mogli odróżnić pominiętego powiadomienia od okresu ciszy, a „zasób pasował do wyszukiwania” to nie to samo co „zdarzenie miało miejsce” (zakończenie wizyty nie jest wyrażalne jako wyszukiwanie).
R4B i R5: subskrypcje oparte na tematach
W FHIR R4B i R5 subskrypcje są oparte na tematach. Serwer publikuje zasoby SubscriptionTopic opisujące zdarzenia (zasób, wyzwalacz, taki jak utworzenie, aktualizacja, usunięcie lub warunek FHIRPath, oraz dozwolone filtry). Subskrybent tworzy Subscription wskazujący na temat z wartościami filterBy, typem kanału, punktem końcowym, okresem heartbeat i ustawieniem zawartości empty, id-only lub full-resource.
SubscriptionTopic to zasób publikowany przez serwer, opisujący zdarzenie: który zasób, który wyzwalacz (utworzenie, aktualizacja, usunięcie lub warunek FHIRPath, taki jak %previous.status != 'finished' and %current.status = 'finished') i jakie filtry subskrybent może użyć. Subskrybent następnie tworzy Subskrypcję wskazującą na temat:
{
"resourceType": "Subscription",
"status": "requested",
"topic": "http://example.org/fhir/SubscriptionTopic/encounter-end",
"filterBy": [{"resourceType": "Encounter", "filterParameter": "patient", "value": "Patient/123"}],
"channelType": {"system": "http://terminology.hl7.org/CodeSystem/subscription-channel-type", "code": "rest-hook"},
"endpoint": "https://clinic.example.org/hooks/encounters",
"heartbeatPeriod": 60,
"timeout": 30,
"contentType": "application/fhir+json",
"content": "id-only"
}
content wybiera, ile danych jest przesyłanych: empty (tylko zdarzenie), id-only (referencje, pobierz resztę z własnym autoryzacją) lub full-resource. heartbeatPeriod sprawia, że serwer wysyła sygnał „heartbeat”, dzięki czemu cisza jest wykrywalna.
Jak wygląda powiadomienie
Powiadomienie o subskrypcji FHIR to Bundle typu subscription-notification, którego pierwszym wpisem jest zasób SubscriptionStatus podający subskrypcję, temat, typ powiadomienia (handshake, heartbeat, event-notification, query-status lub query-event) oraz licznik eventsSinceSubscriptionStart do wykrywania pominiętych zdarzeń. Dalsze wpisy zawierają zmienione zasoby lub ich odniesienia, w zależności od ustawienia zawartości.
Każde powiadomienie to Bundle typu subscription-notification. Jego pierwszy wpis to SubscriptionStatus z referencją subskrypcji, tematem, typem powiadomienia (handshake, heartbeat, event-notification, query-status, query-event) i licznikiem eventsSinceSubscriptionStart; luka w liczniku oznacza pominięte zdarzenie, a klient może wywołać $events, aby je odzyskać. Dalsze wpisy zawierają zasoby lub ich referencje, w zależności od content.
Kanały: rest-hook (serwer POSTuje do Twojego punktu końcowego HTTPS), websocket (klient łączy się i odbiera powiadomienia na gnieździe, przydatne dla aplikacji przeglądarkowych), email (tylko powiadomienie, bez danych), message (wiadomość FHIR w formie Bundle). Kanał R4 sms został usunięty.
Uruchamianie w produkcji
Uruchomienie subskrypcji FHIR w środowisku produkcyjnym wymaga obsługi idempotentnej kluczowanej na podstawie numeru zdarzenia i wersji zasobu, zabezpieczenia punktu końcowego, które weryfikuje nadawcę i nigdy nie traktuje ładunku jako autoryzacji, tolerancji dla pakietów zbiorczych z wieloma zdarzeniami, odpowiedzi 2xx na początkowe powiadomienie o uzgadnianiu (handshake) oraz świadomości, że wiele serwerów nadal ogranicza subskrypcje do usług backendowych, a nie aplikacji pacjentów.
- Idempotentność. Powiadomienia mogą być duplikowane po ponownej próbie; kluczuj po numerze zdarzenia i wersji zasobu.
- Bezpieczeństwo. Punkt końcowy musi zweryfikować nadawcę (nagłówek z tajnym kluczem współdzielonym, wzajemne TLS lub podpisy) i nigdy nie może ufać ładunkowi jako autoryzacji; pobieraj wrażliwe dane z powrotem z serwera za pomocą własnego tokena, gdy
contenttoid-only. - Backpressure. Serwery grupują zdarzenia i szanują
maxCount; klienci muszą akceptować pakiety z wieloma zdarzeniami. - Handshake. Po aktywacji serwer wysyła powiadomienie
handshakei oczekuje odpowiedzi 2xx; w przeciwnym razie subskrypcja przechodzi w stanerror. - Zakresy (Scopes). SMART on FHIR powoli dodawał zakresy subskrypcji; wiele serwerów nadal ogranicza subskrypcje do usług backendowych (poświadczenia klienta), a nie aplikacji pacjenta.
Webhooki, które nie są subskrypcjami FHIR
Webhooki, które nie są subskrypcjami FHIR, to proste mechanizmy platformy: rejestrujesz adres URL HTTPS i otrzymujesz podpisane zdarzenia JSON, takie jak zapis zasobu lub zmiana zgody, bez żadnego SubscriptionTopic. Anpheros oferuje takie webhooki. Są one prostsze dla jednej platformy, ale nie są wykrywalne przez ogólny klient FHIR, więc integracje, które muszą działać z dowolnym serwerem FHIR, używają subskrypcji.
Wiele platform, w tym Anpheros, oferuje zwykłe webhooki: rejestrujesz adres URL HTTPS i otrzymujesz podpisane zdarzenia JSON, takie jak zasób zapisany, zgoda zmieniona, dokument sfinalizowany. Rozwiązują ten sam problem z mniejszą liczbą formalności i bez SubscriptionTopic, i nie są zasobami FHIR, więc ogólny klient FHIR nie może ich odkryć. Jeśli Twoja integracja musi działać z dowolnym serwerem FHIR, użyj Subskrypcji; jeśli jest skierowana na jedną platformę, jej webhooki są zazwyczaj prostsze. Anpheros dokumentuje swoje webhooki na stronie dla deweloperów (link poniżej).
Powiązane strony
- FHIR R4 vs R5
- Wyszukiwanie FHIR wyjaśnione
- FHIR Bundle wyjaśnione
- CDS Hooks wyjaśnione
- Zdalne monitorowanie pacjentów z FHIR
- Webhooki Anpheros (dla deweloperów)
Źródła
- HL7 FHIR R5: Subscription
- HL7 FHIR R5: SubscriptionTopic
- HL7 FHIR R5: SubscriptionStatus i powiadomienia
- HL7 FHIR R4: Subscription
- Przewodnik implementacyjny Subscriptions R5 Backport
Najczęstsze pytania
Czy mogę używać subskrypcji w stylu R5 na serwerze R4?
Tak, jeśli serwer implementuje przewodnik implementacyjny Subscriptions R5 Backport, który koduje temat, filtry i ustawienia kanału jako rozszerzenia zasobu R4 Subscription i używa pakietów R4 do powiadomień.
Jaka jest różnica między subskrypcją a ankietowaniem z _lastUpdated?
Ankietowanie wielokrotnie pyta serwer i niczego nie pomija, ale jest powolne i marnotrawne; Subskrypcje wysyłają zdarzenia w miarę ich występowania. Solidne klienty łączą oba: subskrybuj dla szybkości, ankietuj lub wywołaj $events, aby odzyskać dane po awarii.
Czy powiadomienie zawiera dane?
Tylko jeśli content to full-resource. Bezpieczniejszym domyślnym ustawieniem jest id-only: powiadomienie informuje, który zasób się zmienił, a Ty pobierasz go z własną autoryzacją.
Czy subskrypcje FHIR są tym samym co webhooki?
Subskrypcja typu rest-hook to webhook o zdefiniowanym przez FHIR kształcie: możliwe do odkrycia tematy, standardowe pakiety powiadomień i śledzenie stanu. Zwykłe webhooki oferowane przez platformę wykonują tę samą pracę tylko dla tej platformy.
Wypróbuj za darmo w sandboksie
Pierwsze wywołanie FHIR w 5 minut. API HL7 FHIR R4 z wbudowaną zgodą pacjenta: wypróbuj w piaskownicy, a następnie połącz własną aplikację lub system kliniczny.
Za darmo · 30 syntetycznych pacjentów · bez karty
Anpheros tworzy dokumentację medyczną, nad którą pacjent ma kontrolę i którą może udostępniać dowolnej klinice, na platformie HL7 FHIR R4, z siedzibą w UE. Te przewodniki pomogą Ci zrozumieć i uporządkować informacje o Twoim zdrowiu; nie zastępują one wizyty u lekarza.
O Anpheros →