Подписки FHIR: темы, каналы, R4-R5

Q: Содержит ли уведомление данные?

Только если content равен full-resource . Более безопасный вариант по умолчанию — id-only : уведомление сообщает вам, какой ресурс изменился, и вы получаете его с вашим собственным разрешением.

Q: Являются ли FHIR-подписки тем же, что и вебхуки?

Подписка rest-hook — это вебхук с формой, определенной FHIR: обнаруживаемые темы, стандартные пакеты уведомлений и отслеживание состояния. Обычные вебхуки, предлагаемые платформой, выполняют ту же задачу только для этой платформы.

Краткий ответ: Subscription сообщает FHIR-серверу: уведомить этот конечный пункт при изменении ресурсов, соответствующих этим условиям. В FHIR R4 условия — это строка поиска (criteria: "Observation?patient=123&code=85354-9"), и сервер отправляет соответствующий ресурс по REST hook, websocket, электронной почте или FHIR-сообщению. В R4B и R5 модель была перестроена вокруг SubscriptionTopic: сервер публикует события, о которых он может уведомлять, клиент подписывается на тему с фильтрами, а уведомления приходят как Bundle типа subscription-notification, который всегда начинается с ресурса SubscriptionStatus. Руководство по реализации Subscriptions R5 Backport позволяет серверам R4 предлагать новую модель.

R4: подписки на основе критериев

В FHIR R4 подписка основана на критериях: клиент создает ресурс Subscription, критерии которого представляют собой поисковую строку, например Observation?code=…&patient=…, а канал — rest-hook, websocket, email, sms или message. Сервер оценивает критерии для каждого созданного или обновленного ресурса и отправляет каждый соответствующий ресурс или пустое уведомление в конечную точку.

{
  "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>"]
  }
}

Сервер оценивает критерии при каждом создании и обновлении. Когда ресурс соответствует, он отправляет его по POST на конечный пункт (или отправляет пустой тело, если payload опущен, чтобы клиент сам получил ресурс). Это работало, но с тремя проблемами: серверы не могли указать, какие критерии они поддерживают, клиенты не могли отличить пропущенное уведомление от периода затишья, а "ресурс соответствует поиску" — это не то же самое, что "произошло событие" (завершение Encounter не может быть выражено как поиск).

R4B и R5: подписки на основе тем

В FHIR R4B и R5 подписки основаны на темах. Сервер публикует ресурсы SubscriptionTopic, описывающие события (ресурс, триггер, такой как создание, обновление, удаление, или условие FHIRPath, и разрешенные фильтры). Подписчик создает подписку, указывающую на тему с значениями filterBy, типом канала, конечной точкой, периодом пульса и настройкой содержимого: пустое, только идентификатор или полный ресурс.

SubscriptionTopic — это ресурс, который публикует сервер, описывающий событие: какой ресурс, какой триггер (создание, обновление, удаление или условие FHIRPath, такое как %previous.status != 'finished' and %current.status = 'finished') и какие фильтры может использовать подписчик. Затем подписчик создает Subscription, который указывает на тему:

{
  "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 выбирает, сколько данных передается: empty (только событие), id-only (ссылки, остальное получить с вашим собственным разрешением) или full-resource. heartbeatPeriod заставляет сервер отправлять пульс, чтобы можно было обнаружить тишину.

Как выглядит уведомление

Уведомление FHIR-подписки представляет собой Bundle типа subscription-notification, первая запись которого — это ресурс SubscriptionStatus, содержащий информацию о подписке, теме, типе уведомления (handshake, heartbeat, event-notification, query-status или query-event) и счетчик eventsSinceSubscriptionStart для обнаружения пропущенных событий. Дальнейшие записи содержат измененные ресурсы или их ссылки, в зависимости от настройки содержимого.

Каждое уведомление — это Bundle типа subscription-notification. Его первая запись — это SubscriptionStatus со ссылкой на подписку, темой, типом уведомления (handshake, heartbeat, event-notification, query-status, query-event) и счетчиком eventsSinceSubscriptionStart; пробел в счетчике означает пропущенное событие, и клиент может вызвать $events для его восстановления. Дальнейшие записи содержат ресурсы или их ссылки, в зависимости от content.

Каналы: rest-hook (сервер отправляет POST на ваш HTTPS-конечный пункт), websocket (клиент подключается и получает уведомления по сокету, полезно для браузерных приложений), email (только уведомление, без данных), message (FHIR-сообщение Bundle). Канал R4 sms был удален.

Запуск в продакшене

Запуск FHIR-подписок в производственной среде требует идемпотентной обработки с привязкой к номеру события и версии ресурса, безопасности конечной точки, которая проверяет отправителя и никогда не рассматривает полезную нагрузку как авторизацию, терпимости к пакетам с множеством событий, ответа 2xx на начальное уведомление рукопожатия и понимания того, что многие серверы по-прежнему ограничивают подписки серверными службами, а не клиентскими приложениями пациентов.

Идемпотентность. Уведомления могут дублироваться после повторной попытки; используйте номер события и версию ресурса в качестве ключа.
Безопасность. Конечный пункт должен проверять отправителя (общий секретный заголовок, взаимный TLS или подписи) и никогда не должен доверять полезной нагрузке как разрешению; получайте конфиденциальные данные обратно с сервера с вашим собственным токеном, когда content равен id-only.
Обратное давление. Серверы группируют события и уважают maxCount; клиенты должны принимать пакеты с большим количеством событий.
Рукопожатие. При активации сервер отправляет уведомление handshake и ожидает 2xx; в противном случае подписка переходит в состояние error.
Области действия. SMART on FHIR медленно добавлял области действия подписки; многие серверы по-прежнему ограничивают подписки серверными службами (учетные данные клиента), а не приложениями пациентов.

Вебхуки, которые не являются FHIR-подписками

Вебхуки, не являющиеся FHIR-подписками, представляют собой простые механизмы платформы: вы регистрируете URL-адрес HTTPS и получаете подписанные JSON-события, такие как запись ресурса или изменение согласия, без каких-либо SubscriptionTopic. Anpheros предлагает такие вебхуки. Они проще для одной платформы, но не обнаруживаются универсальным FHIR-клиентом, поэтому интеграции, которые должны работать с любым FHIR-сервером, используют подписки.

Многие платформы, включая Anpheros, предлагают обычные вебхуки: вы регистрируете HTTPS-URL и получаете подписанные JSON-события, такие как ресурс записан, согласие изменено, документ финализирован. Они решают ту же потребность с меньшим количеством церемоний и без SubscriptionTopic, и они не являются FHIR-ресурсами, поэтому универсальный FHIR-клиент не может их обнаружить. Если ваша интеграция должна работать с любым FHIR-сервером, используйте Subscriptions; если она нацелена на одну платформу, ее вебхуки обычно проще. Anpheros документирует свои вебхуки на сайте для разработчиков (ссылка ниже).

Связанные страницы

Источники

Частые вопросы

Могу ли я использовать подписки в стиле R5 на сервере R4?

Да, если сервер реализует руководство по реализации Subscriptions R5 Backport, которое кодирует тему, фильтры и настройки канала как расширения ресурса R4 Subscription и использует пакеты R4 для уведомлений.

В чем разница между подпиской и опросом с _lastUpdated?

Опрос многократно запрашивает сервер и ничего не пропускает, но он медленный и расточительный; подписки отправляют события по мере их возникновения. Надежные клиенты сочетают оба подхода: подписываются для скорости, опрашивают или вызывают $events для восстановления после простоя.

Содержит ли уведомление данные?

Только если content равен full-resource. Более безопасный вариант по умолчанию — id-only: уведомление сообщает вам, какой ресурс изменился, и вы получаете его с вашим собственным разрешением.

Являются ли FHIR-подписки тем же, что и вебхуки?

Подписка rest-hook — это вебхук с формой, определенной FHIR: обнаруживаемые темы, стандартные пакеты уведомлений и отслеживание состояния. Обычные вебхуки, предлагаемые платформой, выполняют ту же задачу только для этой платформы.

Anpheros Platform

Попробуйте бесплатно в песочнице

Первый запрос FHIR за 5 минут. API HL7 FHIR R4 с встроенным согласием пациента: попробуйте в песочнице, затем подключите свое приложение или систему клиники.

Создать бесплатную песочницу Читать руководства для разработчиков →

Бесплатно · 30 синтетических пациентов · без карты

Это руководство носит информационный характер и не заменяет консультацию врача. Решения о своём здоровье принимайте вместе с врачом. В экстренной ситуации звоните по местному номеру экстренной помощи (112 в Европе).

Автор

Команда Anpheros

Anpheros создает медицинскую карту, которую пациент контролирует и может делиться с любой клиникой, на платформе HL7 FHIR R4, базирующейся в ЕС. Эти руководства помогут вам понять и организовать свое здоровье; они не заменяют вашего врача.

О Anpheros →