Импорт данных FHIR

Вы можете использовать операцию import, чтобы загружать данные FHIR® на сервер FHIR с высокой пропускной способностью.

Режимы операций импорта

Операция import поддерживает два режима: начальный и добавочный. Каждый режим имеет различные функции и варианты использования.

Начальный режим

• Предназначено для загрузки ресурсов FHIR на пустой сервер FHIR.

• Блокирует запись API на сервер FHIR.

Инкрементальный режим

• Оптимизировано для загрузки данных на сервер FHIR периодически и не блокирует запись через API.

• Позволяет загружать lastUpdated и versionId значения из метаданных ресурсов, если они присутствуют в JSON ресурса.

• Позволяет загружать ресурсы в непоследовательном порядке версий. Примечание для несистематического ввода ресурсов

  • Если в импортируемых файлах не указаны значения полей version и lastUpdated, нет гарантии, что все ресурсы будут импортированы в службу FHIR.
  • Если в импортируемых файлах имеются ресурсы с повторяющимися значениями полей version и lastUpdated, то в службу FHIR случайным образом будет добавлен только один из этих ресурсов.
  • При параллельном выполнении, если несколько ресурсов используют один и тот же идентификатор ресурса, импортируется только один из этих ресурсов случайным образом.

В следующей таблице показано различие между режимами импорта.

Вопросы, связанные с производительностью

Чтобы добиться оптимальной производительности операции import, рассмотрите следующие факторы.

• Используйте большие файлы для импорта. Оптимальный размер файла NDJSON для импорта составляет >=50 МБ (или >=20 K ресурсов, без верхнего предела). Рассмотрите возможность объединения небольших файлов вместе.

• Импорт файлов ресурсов FHIR в виде одного пакета. Для оптимальной производительности импортируйте все файлы ресурсов FHIR, которые необходимо принять на сервере FHIR в одной import операции. Импорт всех файлов в одной операции снижает затраты на создание нескольких заданий импорта и управление ими. Оптимально общий размер файлов в одном импорте должен быть большим (>=100 ГБ или >=100 млн ресурсов, без верхнего предела).

• Ограничение количества заданий параллельного импорта. Одновременно можно выполнять несколько import заданий, но это может повлиять на общую пропускную способность операции import.

Выполнение операции импорта

Предпосылки

• Чтобы использовать import операцию, на сервере FHIR требуется роль Импортера данных FHIR.

• Настройте сервер FHIR. Данные FHIR должны храниться в файлах, относящихся к ресурсам, в формате FHIR NDJSON в хранилище BLOB-объектов Azure. Дополнительные сведения см. в разделе "Настройка параметров импорта".

• Данные должны находиться в том же арендаторе, что и служба FHIR.

• Получение маркера доступа см. в разделе "Маркер доступа"

Совершить звонок

Сделайте вызов POST к <<FHIR service base URL>>/$import со следующим заголовком запроса и текстом запроса.

Заголовок запроса

Prefer:respond-async
Content-Type:application/fhir+json

Тело

В следующих таблицах описываются параметры тела и входные данные.

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "<Use "InitialLoad" for initial mode import / Use "IncrementalLoad" for incremental mode import>"
        }, 
        {
            "name": "allowNegativeVersions",
            "valueBoolean": true
        },
        {
            "name": "input",
            "part": [
                { 
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/filename.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "\"0x8D92A7342657F4F\""
                }
            ]
        }
    ]
}

Проверка состояния импорта

После запуска import операции пустой текст ответа со ссылкой callback возвращается в Content-location заголовке ответа вместе с 202 Accepted кодом состояния. Сохраните ссылку callback , чтобы проверить состояние импорта.

Регистрация операции import осуществляется в виде идемпотентного вызова. Одно и то же содержимое данных регистрации приводит к одинаковой регистрации, что влияет на способность повторной обработки файлов с тем же именем. Воздержаться от обновления файлов на месте. Вместо этого мы рекомендуем использовать другое имя файла для обновленных данных. Или, если обновление на месте с тем же именем файла неизбежно, добавьте ETags в нагрузку регистрации.

Чтобы проверить состояние импорта, выполните вызов REST с GET методом к callback ссылке, возвращенной на предыдущем шаге.

Интерпретация ответа с помощью этой таблицы.

В следующей таблице описываются важные поля в тексте ответа:

{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": <null in case type parameter in not populated in request. If provided, resource name will be added>,
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/filename.ndjson"
        }
    ],
    "error": [
        { 
        "type": "OperationOutcome",
        "count": 51,
        "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson",
        "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson"
        }
    ]
}

Прием мягко удаленных ресурсов

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

Добавьте расширение к ресурсу для информирования службы FHIR, что ресурс был мягко удалён.

{"resourceType": "Patient", "id": "example10", "meta": { "lastUpdated": "2023-10-27T04:00:00.000Z", "versionId": 4, "extension": [ { "url": "http://azurehealthcareapis.com/data-extensions/deleted-state", "valueString": "soft-deleted" } ] } }

После успешного завершения import операции выполните поиск в истории ресурса, чтобы проверить мягко удаленные ресурсы. Если вы знаете идентификатор удаленного ресурса, используйте шаблон URL-адреса в следующем примере.

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

Если вы не знаете идентификатор ресурса, выполните поиск в истории по типу ресурса.

<FHIR_URL>/<resource-type>/_history

Устранение неполадок операции импорта

Ниже приведены сообщения об ошибках, возникающие при сбое import операции, а также рекомендуемые действия для устранения проблем.

200 ОК, но в ответе возникает ошибка с URL-адресом

Операция import завершается успешно и возвращает 200 OK. Однако, error.url присутствует в тексте ответа. Файлы, присутствующих в расположении error.url , содержат фрагменты JSON, аналогичные следующему примеру.

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "details": {
                "text": "Given conditional reference '{0}' doesn't resolve to a resource."
            },
            "diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
        }
    ]
}

Причина: файлы NDJSON содержат ресурсы с условными ссылками, которые import не поддерживаются.

Решение. Замените условные ссылки на обычные ссылки в файлах NDJSON.

400 Недопустимый запрос

Операция import завершается ошибкой и возвращается 400 Bad Request. Тело ответа содержит диагностический контент

Операция импорта завершилась ошибкой по причине: такой узел не известен. (example.blob.core.windows.net:443) Решение. Убедитесь, что ссылка на хранилище Azure правильна. Проверьте параметры сети и брандмауэра, чтобы убедиться, что сервер FHIR может получить доступ к хранилищу. Если служба находится в виртуальной сети, убедитесь, что хранилище находится в той же виртуальной сети или в виртуальной сети, пиринговой с виртуальной сетью службы FHIR.

Ресурсы SearchParameter нельзя обрабатывать с помощью решения импорта: операция импорта возвращает ошибку HTTP 400 при приеме ресурса параметра поиска через процесс импорта. Это изменение предназначено для предотвращения попадания параметров поиска в неправильное состояние при выполнении операции импорта.

403 Запрещено

Операция import завершается ошибкой и возвращается 403 Forbidden. Текст ответа содержит диагностическое содержимое.

Операция импорта завершилась ошибкой по причине: сервер не прошел проверку подлинности запроса. Убедитесь, что значение заголовка Authorization правильно сформировано, включая подпись. Причина. Служба FHIR использует управляемое удостоверение для проверки подлинности исходного хранилища. Эта ошибка указывает на отсутствие или неправильное назначение роли. Решение: Назначьте серверу FHIR роль Storage Blob Data Contributor. Дополнительные сведения см. в статье Назначение ролей Azure.

500 Internal Server Error (внутренняя ошибка сервера).

Операция import завершается ошибкой и возвращается 500 Internal Server Error. Текст ответа содержит содержимое диагностики

Операция импорта завершилась ошибкой по причине: база данных "***" достигла квоты размера. Разделите или удалите данные, удалите индексы или просмотрите документацию, чтобы найти возможные решения проблемы.

Причина. Достигнуто ограничение хранилища службы FHIR.

Решение. Уменьшите размер данных или рассмотрите azure API для FHIR, что имеет более высокий предел хранилища.

423 Заблокировано

Поведение: Операция import завершается ошибкой и возвращается 423 Locked. Текст ответа содержит следующее содержимое:

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Service is locked for initial import mode."
        }
    ]
}

Причина. Служба FHIR настроена в режиме начального импорта, который блокировал другие операции.

Решение: отключите режим начального импорта службы FHIR или выберите добавочный режим.

Ограничения

• Максимально допустимое количество файлов для каждой import операции — 10 000.
• Количество файлов, загруженных на сервер FHIR с одинаковым значением поля lastUpdated, точным до миллисекунды, не может превышать 10 000.
• Операция импорта не поддерживается для типа ресурса SearchParameter.
• Операция импорта не поддерживает условные ссылки в ресурсах.

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

Преобразуйте ваши данные в FHIR

Настройка параметров экспорта и настройка учетной записи хранения

Копирование данных в Azure Synapse Analytics