Выполнение массовых обновлений для данных FHIR

Эта $bulk-update операция позволяет массово обновлять несколько ресурсов FHIR с помощью асинхронной обработки. Он поддерживает:

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

Операция использует поддерживаемые типы патчей, $bulk-update перечисленные в следующем разделе, для выполнения обновлений.

• replace: Заменить существующее значение. Он использует семантику патча replace FHIR, что гарантирует идемпотентность обновлений.
• upsert: Добавляет значение, если его нет, или заменяет его, если оно уже существует.

Предварительные требования для операции массового обновления

Обязательные роли

Для выполнения массового обновления назначите приложению или пользователю одну из следующих ролей:

• Оператор массовой обработки данных FHIR: предоставляет доступ к массовым операциям в службе FHIR.
• FHIR Data Contributor: предоставляет административный доступ к сервису FHIR.

Обязательные заголовки

Просьба

Используйте параметры поиска FHIR в запросе. Операция массового обновления поддерживает стандартные фильтры поиска, такие как address:contains=Meadow или Patient.birthdate=1987-02-20. Также можно использовать _include, _revinclude, и _not-referenced для расширения критериев поиска. Используйте _meta-history для настройки поведения версии для обновлений, основанных только на метаданных.

Примеры запросов

1. Массовое обновление на системном уровне: При запуске операции на системном уровне вы можете обновлять ресурсы FHIR для всех типов ресурсов на сервере FHIR.

   PATCH https://{FHIR-SERVICE-HOST}/$bulk-update
   

2. Обновления с ограничением по типу ресурса: При запуске операции для отдельных типов ресурсов можно обновить FHIR-ресурсы, которые соответствуют типу ресурса в URL.

   PATCH https://{FHIR-SERVICE-HOST}/[ResourceType]/$bulk-update
   

3. Запрос ресурсов для обновления на основе параметров поиска. В этом примере используйте _include и _revinclude. Обновите все ресурсы для пациентов, последний раз обновлённые до 18.12.2021, и любые ресурсы, ссылающиеся на них:

   PATCH {FHIR-SERVICE-HOST}/Patient/$bulk-update?_lastUpdated=lt2021-12-18&_revinclude=*
   

   PATCH {FHIR-SERVICE-HOST}/DiagnosticReport/$bulk-update?_lastUpdated=lt2021-12-12&_include=DiagnosticReport:based-on:ServiceRequest&_include:iterate=ServiceRequest:encounter
   

4. Обновления только метаданных с параметром запроса _meta-history: Когда политика версионирования сервера FHIR задана как versioned или version-update, параметр _meta-history определяет, создают ли изменения только метаданных ресурса новую историческую версию ресурса. По умолчанию любое изменение ресурса, включая изменения только метаданных, создает новую версию и сохраняет предыдущую версию в виде исторической записи. Когда параметр установлен _meta-history в false, изменения только в метаданных не создают новую версию, и предыдущая версия не сохраняется как историческую запись. Используйте эту опцию, когда метаданные часто меняются и хотите избежать многих версий истории, которые отличаются только по метаданным. Дополнительные сведения и примеры см. в разделе " Политика управления версиями FHIR" и "Управление журналами".

   PATCH https://{FHIR-SERVICE-HOST}/$bulk-update?_meta-history=false
   

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

Пример тела запроса:

{ 
  "resourceType": "Parameters", 
  "parameter": [ 
    { 
      "name": "operation", 
      "part": [ 
        { 
          "name": "type", 
          "valueCode": "upsert" 
        }, 

        { 
          "name": "path", 
          "valueString": "Resource.meta" 
        }, 

        { 
          "name": "name", 
          "valueString": "security" 
        }, 

        { 
          "name": "value", 
          "valueCoding": { 
            "system": "http://example.org/security-system", 
            "code": "SECURITY_TAG_CODE", 
            "display": "Updated Security Tag Display" 
          } 
        } 
      ] 
    } 
  ] 
}

Ключевые моменты

• Каждый путь исправления должен начинаться с корня ResourceType (например, с Patient.meta.tag), чтобы четко различать метауровневые обновления и обновления элементов. Вы можете патчить общие свойства, используя корень ресурса. Вы можете выполнять массовое обновление на уровне системы, для одного типа ресурса или для нескольких типов ресурсов. Если вам нужно обновить разные поля для разных типов ресурсов, укажите соответствия между полями и значениями в отдельных операциях.
• Если ваш поиск возвращает несколько типов ресурсов, патч применяется только к ресурсам, тип которых совпадает с ResourceType префиксом в пути патча. Операция игнорирует другие типы.
• SearchParameter и StructureDefinition считаются вне области применения для массовых обновлений. Запуск задачи массового обновления по типу ресурса на SearchParameter или StructureDefinition также приводит к ошибке 400 Bad Request. Если массовый запрос обновления на уровне системы или типа ресурса возвращает ресурсы типа SearchParameter или StructureDefinition, операция игнорирует эти ресурсы. Обновляются только другие типы ресурсов.

Ответ

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

Content-Location: https://{hostname}/_operations/bulk-update/{job-id}

Результаты опроса конечной точки

Запросы к конечной точке опроса приводят к одному из четырёх результатов, в зависимости от статуса задачи массового обновления. Ответ FHIR содержит результат в элементе OperationOutcome.

Ответ на операцию массового обновления включает четыре основных компонента:

1. ResourceUpdatedCount: показывает количество ресурсов, успешно обновленных, сгруппированных по типу ресурса.
2. ResourceIgnoredCount: указывает количество ресурсов, игнорируемых во время массового обновления по типу ресурса. Операция игнорирует ресурсы, если для их типа нет соответствующего запроса на патч или если они относятся к исключённым типам, таким как SearchParameter или StructureDefinition.
3. ResourcepatchFailedCount: отображает количество ресурсов, в которых операция патча не завершилась, по типу ресурса. Например, если вы пытаетесь заменить значение, которого не существует, операция исправления завершается с ошибкой и учитывается здесь. Задание считается "мягким сбоем", если некоторые ресурсы завершаются ошибкой, но другие успешно. Раздел Issues содержит общее сообщение, в котором рекомендуется использовать операцию FHIR PATCH для отдельных ресурсов, чтобы получить подробную информацию об ошибках.
4. Проблемы. Предоставляет сведения о любых сбоях задания или причинах неудачных обновлений.

Пример текста ответа:

{ 

  "resourceType": "Parameters", 

  "parameter": [ 
    { 
      "name": "ResourceUpdatedCount", 
      "part": [ 
        { "name": "Practitioner", "valueInteger64": 10 }, 
        { "name": "Specimen", "valueInteger64": 7 }, 
        { "name": "Device", "valueInteger64": 3 } 
      ] 
    }, 

    { 
      "name": "ResourceIgnoredCount", 
      "part": [ 
        { "name": "StructureDefinition", "valueInteger64": 9 }, 
        { "name": "SearchParameter", "valueInteger64": 8 } 
      ] 
    } 
  ] 
}

Обработка ошибок ответа

Отмена задания массового обновления

Отправьте запрос DELETE в конечную точку опроса задания следующим образом.

DELETE https://{FHIR-SERVICE-HOST}/_operations/bulk-update/{job-id}

Журналы аудита

Когда журналирование аудита включено, вы можете запрашивать журналы аудита из MicrosoftHealthcareApisAuditLogs:

• Фильтрация по ResourceId.
• Найдите в записях: задание запущено, задание выполнено успешно и сбои при установке патча.

Для получения дополнительной информации смотрите журналы диагностики услуг FHIR.

Часто задаваемые вопросы

Почему обновлённые счётчики ресурсов не соответствуют ожиданиям?

• Недостаточно ресурсов: другая задача изменила ресурсы до запуска этой задачи.
• Больше ресурсов: После запуска массового обновления появилось новое задание импорта.

Какие действия предпринять, если кажется, что моя задача массового обновления зависла? Чтобы проверить, застряла ли задача массового обновления, запустите поиск FHIR с теми же параметрами, что и задание массового обновления. Добавьте соответствующее условие операции в запрос и установите _summary=count. Если количество ресурсов уменьшается, задание функционирует. Вы также можете отменить задание массового обновления и повторить попытку.

Что влияет на вызовы REST API при одновременном выполнении задания операции массового обновления? При выполнении операции массового обновления может возникнуть повышенная задержка при одновременных вызовах службы. Чтобы избежать увеличения задержки, отмените задачу массового обновления и затем запустите его в период с меньшим трафиком.

Можно ли вернуть изменения? Используйте возможность оптового обновления аккуратно. Например, если включено управление версиями, извлеките предыдущие версии и используйте PUT, чтобы восстановить их, либо восстановите данные из резервной копии. Данные сохраняются от 7 до 30 дней в зависимости от конфигурации.

Что такое «ResourcepatchFailedCount»? Этот показатель отслеживает количество ресурсов, обработка которых завершилась сбоем во время операции PATCH. Причины могут включать:

• Замена несуществующего элемента
• Попытка обновить неизменяемое поле

Проверьте журнал аудита или отправьте отдельный PATCH запрос, чтобы узнать подробности ошибки.

Следующий шаг