Возможности REST API FHIR для службы azure Health Data Services FHIR

  • Статья

В этой статье мы рассмотрим некоторые нюансы взаимодействия RESTful службы FHIR служб медицинских данных Azure (в настоящее время называется службой FHIR).

Условное создание и обновление

Служба FHIR поддерживает создание, условное создание, обновление и условное обновление в соответствии со спецификацией FHIR. Одним из полезных заголовков в этих сценариях является заголовок If-Match . Используется If-Match заголовок, который проверяет обновляемую версию перед обновлением. ETag Если объект не соответствует ожидаемому ETag, будет получено сообщение об ошибке 412 Предусловие не выполнено.

Удаление и условное удаление

Служба FHIR предлагает два типа удаления. Существует удаление, которое также известно как жесткое + обратимое удаление, и условное удаление.

Удаление (жесткое + обратимое удаление)

Удаление, определенное спецификацией FHIR, требует, чтобы после удаления ресурса последующие операции чтения ресурса, не относящиеся к версии, возвращали код состояния HTTP 410. Таким образом, ресурс больше не будет найден с помощью поиска. Кроме того, служба FHIR позволяет полностью удалить ресурс (включая весь журнал). Чтобы полностью удалить ресурс, можно передать параметры hardDelete параметра в значение true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Если вы не передадите этот параметр или не зададите значение hardDelete false, исторические версии ресурса по-прежнему будут доступны.

Примечание

Если требуется только удалить журнал, служба FHIR поддерживает пользовательскую операцию с именем $purge-history. Эта операция позволяет удалить журнал из ресурса.

Условное удаление

Условное удаление позволяет передавать условия поиска для удаления ресурса. По умолчанию условное удаление позволяет удалять по одному элементу за раз. Можно также указать параметр для одновременного _count удаления до 100 элементов. Ниже приведены некоторые примеры использования условного удаления.

Чтобы удалить один элемент с помощью условного удаления, необходимо указать условия поиска, возвращающие один элемент.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704

Вы можете выполнить тот же поиск, но включить hardDelete=true , чтобы также удалить весь журнал.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true

Чтобы удалить несколько ресурсов, включите _count=100 параметр . Этот параметр удалит до 100 ресурсов, соответствующих условиям поиска.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100

Восстановление удаленных файлов

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

Если идентификатор удаленного ресурса известен, используйте следующий шаблон URL-адреса:

<FHIR_URL>/<resource-type>/<resource-id>/_history

Пример: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history

Если идентификатор ресурса неизвестный, выполните поиск в журнале по всему типу ресурса:

<FHIR_URL>/<resource-type>/_history

Пример: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history

После того как вы найдете запись, которую нужно восстановить, используйте PUT операцию , чтобы повторно создать ресурс с тем же идентификатором, или используйте POST операцию , чтобы создать новый ресурс с теми же сведениями.

Примечание

Срок действия журнала или обратимого удаления данных не зависит от времени. Единственный способ удалить журнал или обратимо удаленные данные — с помощью операции жесткого удаления или операции очистки журнала.

Пакетные пакеты и пакеты транзакций

В FHIR пакеты можно рассматривать как контейнер, содержащий несколько ресурсов. Пакетные пакеты и пакеты транзакций позволяют пользователям отправлять набор действий, выполняемых на сервере в одном HTTP-запросе или ответе. Действия могут выполняться независимо как "пакет" или как одна атомарная "транзакция", в которой весь набор изменений выполняется успешно или завершается сбоем в виде одной сущности. Можно отправлять действия для нескольких ресурсов одного и того же или разного типа, например создание, обновление или удаление. Дополнительные сведения см. в разделе Пакеты FHIR.

Пакетное взаимодействие или пакет транзакций со службой FHIR выполняется с помощью команды HTTP POST по базовому URL-адресу.

POST {{fhir_url}} 
{ 
  "resourceType": "Bundle", 
  "type": "batch", 
  "entry": [ 
    { 
      "resource": { 
        "resourceType": "Patient", 
        "id": "patient-1", 
        "name": [ 
          { 
            "given": ["Alice"], 
            "family": "Smith" 
          } 
        ], 
        "gender": "female", 
        "birthDate": "1990-05-15" 
      }, 
      "request": { 
        "method": "POST", 
        "url": "Patient" 
      } 
    }, 
    { 
      "resource": { 
        "resourceType": "Patient", 
        "id": "patient-2", 
        "name": [ 
          { 
            "given": ["Bob"], 
            "family": "Johnson" 
          } 
        ], 
        "gender": "male", 
        "birthDate": "1985-08-23" 
      }, 
      "request": { 
        "method": "POST", 
        "url": "Patient" 
      } 
    } 
   } 
  ] 
}

В случае пакета каждая запись рассматривается как отдельное взаимодействие или операция. В случае пакета транзакций все взаимодействия или операции либо успешно, либо завершаются сбоем. Для пакета или пакета успешных транзакций ответ содержит по одной записи для каждой записи в запросе. Для пакета неудачных транзакций служба FHIR возвращает один элемент OperationOutcome.

Примечание

Для пакетных пакетов не должно быть взаимозависимостей между разными записями в пакете FHIR. Успех или сбой одной записи не должен влиять на успех или неудачу другой записи.

Параллельная обработка пакета пакетной службы в общедоступной предварительной версии

В настоящее время пакетные пакеты и пакеты транзакций выполняются последовательно в службе FHIR. Чтобы повысить производительность и пропускную способность, мы включаем параллельную обработку пакетных пакетов в общедоступной предварительной версии.
Использование возможности параллельной пакетной обработки пакета

  • Задайте для заголовка x-bundle-processing-logic значение parallel.
  • Убедитесь, что для операций DELETE, POST, PUT или PATCH в одном пакете нет перекрывающегося идентификатора ресурса.

Важно!

Параллельная обработка пакета в настоящее время находится в общедоступной предварительной версии. Предварительные версии API и пакеты SDK предоставляются без соглашения об уровне обслуживания. Не рекомендуется использовать их для рабочих нагрузок. Некоторые функции могут не поддерживаться или иметь ограниченные возможности. Дополнительные сведения см. в статье Дополнительные условия использования предварительных версий Microsoft Azure.

Исправление и условное исправление

Исправление — это ценная операция RESTful, когда необходимо обновить только часть ресурса FHIR. С помощью исправления можно указать элементы, которые требуется обновить в ресурсе, не обновляя всю запись. FHIR определяет три способа исправления ресурсов: исправление JSON, исправление XML и исправление FHIRPath. Служба FHIR поддерживает как исправление JSON, так и исправление FHIRPath, а также условное исправление JSON и условное исправление FHIRPath (которое позволяет исправлять ресурс на основе условий поиска, а не идентификатора ресурса). Чтобы ознакомиться с некоторыми примерами, ознакомьтесь с примером REST-файла исправления FHIRPath и REST-файлом JSON Patch REST для каждого подхода. Дополнительные сведения см. в документации по HL7 по операциям исправления с помощью FHIR.

Примечание

При использовании PATCH для STU3 и при запросе пакета журнала исправленный ресурс Bundle.entry.request.method сопоставляется с PUT. Это связано с тем, что STU3 не содержит определения для PATCH команды в наборе значений HTTPVerb.

Исправление с помощью исправления FHIRPath

Этот метод исправления является наиболее эффективным, так как он использует FHIRPath для выбора целевого элемента. Одним из распространенных сценариев является использование FHIRPath Patch для обновления элемента в списке без знания порядка списка. Например, если вы хотите удалить данные о домашних телекоммуникациях пациента, не зная индекса, можно использовать приведенный ниже пример.

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Тип содержимого: application/fhir+json

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "operation",
            "part": [
                {
                    "name": "type",
                    "valueCode": "delete"
                },
                {
                    "name": "path",
                    "valueString": "Patient.telecom.where(use = 'home')"
                }
            ]
        }
    ]
}

Для всех операций исправления FHIRPath должен быть application/fhir+json задан заголовок Content-Type. Исправление FHIRPatch поддерживает операции добавления, вставки, удаления, удаления и перемещения. Операции исправления FHIRPatch также можно легко интегрировать в пакеты. Дополнительные примеры см. в примере REST-файла исправления FHIRPath.

Исправление с помощью исправления JSON

Исправление JSON в службе FHIR соответствует хорошо используемой спецификации, определенной целевой группой по проектированию интернета. Формат полезных данных не использует ресурсы FHIR и вместо этого использует документ JSON, использующий JSON-Pointers для выбора элементов. Исправление JSON является более компактным и имеет тестовую операцию, которая позволяет проверить, выполняется ли условие, прежде чем выполнять исправление. Например, если вы хотите установить пациента как умершего только в том случае, если он еще не помечен как умерший, можно использовать приведенный ниже пример.

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Тип содержимого: application/json-patch+json

[
	{
		"op": "test",
		"path": "/deceasedBoolean",
		"value": false
	},
	{
		"op": "replace",
		"path": "/deceasedBoolean",
		"value": true
	}
]

Для всех операций исправления JSON должен быть application/json-patch+json задан заголовок Content-Type. Исправление JSON поддерживает операции добавления, удаления, замены, копирования, перемещения и тестирования. Дополнительные примеры см. в примере REST-файла исправления JSON.

Исправление JSON в пакетах

По умолчанию исправление JSON не поддерживается в ресурсах пакета. Это связано с тем, что пакет поддерживает только ресурсы FHIR, а полезные данные исправления JSON не являются ресурсом FHIR. Чтобы обойти эту проблему, мы будем использовать двоичные ресурсы с типом содержимого "application/json-patch+json" и кодировкой base64 полезных данных JSON внутри пакета. Сведения об этом обходном пути см. в этой статье в чате FHIR Zulip.

В приведенном ниже примере мы хотим изменить пол у пациента на женщину. Мы взяли исправление [{"op":"replace","path":"/gender","value":"female"}] JSON и закодировали его в base64.

POST https://{FHIR-SERVICE-HOST-NAME}/
Content-Type: application/json

{
	"resourceType": "Bundle",
	"id": "bundle-batch",
	"type": "batch",
	"entry": [
		{
			"fullUrl": "Patient/{PatientID}",
			"resource": {
				"resourceType": "Binary",
				"contentType": "application/json-patch+json",
				"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
			},
			"request": { 
				"method": "PATCH",
				"url": "Patient/{PatientID}"
			}
		}
	]
}

Дальнейшие действия

Из этой статьи вы узнали о некоторых возможностях REST службы FHIR. Далее вы можете узнать больше о ключевых аспектах поиска ресурсов в службе FHIR.

Общие сведения о средстве поиска FHIR

(FHIR®) — это зарегистрированная торговая марка организации HL7, которая используется с разрешения HL7.