Теги расширенных запросов

Общие сведения

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

С помощью перечисленных ниже API пользователи могут индексировать свои исследования DICOM, ряды и экземпляры как в стандартных, так и в частных тегах DICOM, чтобы их можно было указать в запросах QIDO-RS.

Программные интерфейсы

Версия: v1

Для управления поддерживаемыми тегами в данном экземпляре службы DICOM добавлены следующие конечные точки API.

API	Описание
POST .../extendedquerytags	Добавление тегов расширенных запросов
GET .../extendedquerytags	Вывод списка тегов расширенных запросов
GET .../extendedquerytags/{tagPath}	Получение тега расширенного запроса
DELETE .../extendedquerytags/{tagPath}	Удаление тега расширенного запроса
PATCH .../extendedquerytags/{tagPath}	Обновление тега расширенного запроса
GET .../extendedquerytags/{tagPath}/errors	Перечисление ошибок тега расширенного запроса
GET .../operations/{operationId}	Операция GET

Добавление тегов расширенных запросов

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

POST .../extendedquerytags

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

Имя	Обязательно	Тип	Описание
Content-Type	True	строка	application/json поддерживается.

Текст запроса

Имя	Обязательно	Тип	Описание
текст		Расширенный тег запроса для добавления[]

Ограничения

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

VR	Описание	Сопоставление одного значения	Сопоставление диапазонов	Нечеткое соответствие
AE	Сущность приложения	X
AS	Строка возраста	X
CS	Строка кода	X
DA	Дата	X	X
DS	Десятичная строка	X
DT	Дата и время	X	X
FD	Двойная точка с плавающей запятой	X
FL	Одиночная точка с плавающей запятой	X
IS	Целочисленная строка	X
ЛО	Длинная строка	X
PN	Имя пользователя	X		X
SH	Короткая строка	X
SL	Подписанный длинный	X
SS	Подписанный короткий	X
TM	Time	X	X
Пользовательский интерфейс	Уникальный идентификатор	X
UL	Длинное целое без знака	X
США	Короткое целое без знака	X

Примечание

Последовательные теги, которые являются тегами под тегом типа Sequence of Items (SQ), в настоящее время не поддерживаются. Можно добавить до 128 тегов расширенных запросов.

Ответы

Имя	Тип	Описание
202 Accepted (принято).	Справочник по операции	Добавлены расширенные теги запросов и запущена длительная операция для повторной индексации существующих экземпляров DICOM.
400 (недопустимый запрос)		Текст запроса содержит недопустимые данные
409 (конфликт)		Один или несколько запрошенных тегов запроса уже поддерживаются

Вывод списка тегов расширенных запросов

Списки всех расширенных тегов запросов.

GET .../extendedquerytags

Ответы

Имя	Тип	Описание
200 OK;	Тег расширенного запроса[]	Возвращает расширенные теги запроса

Получение тега расширенного запроса

Получение тега расширенного запроса.

GET .../extendedquerytags/{tagPath}

Параметры универсального кода ресурса (URI)

Имя	В	Обязательно	Тип	Описание
tagPath	path	True	строка	tagPath — это путь к тегу, который может быть либо тегом, либо ключевое слово. Например, идентификатор пациента представлен 00100020 или PatientId

Ответы

Имя	Тип	Описание
200 OK;	Тег расширенного запроса	Тег расширенного запроса с указанным tagPath
400 (недопустимый запрос)		Запрошенный путь тега недопустим
404 (не найдено)		Не найден тег расширенного запроса с запрошенным tagPath

Удаление тега расширенного запроса

Удаление тега расширенного запроса.

DELETE .../extendedquerytags/{tagPath}

Параметры универсального кода ресурса (URI)

Имя	В	Обязательно	Тип	Описание
tagPath	path	True	строка	tagPath — это путь к тегу, который может быть либо тегом, либо ключевое слово. Например, идентификатор пациента представлен 00100020 или PatientId

Ответы

Имя	Тип	Описание
204 No Content (нет содержимого).		Расширенный тег запроса с запрошенным tagPath успешно удален.
400 (недопустимый запрос)		Запрошенный путь к тегу недопустим.
404 (не найдено)		Не найден тег расширенного запроса с запрошенным tagPath

Обновление тега расширенного запроса

Обновление тега расширенного запроса.

PATCH .../extendedquerytags/{tagPath}

Параметры универсального кода ресурса (URI)

Имя	В	Обязательно	Тип	Описание
tagPath	path	True	строка	tagPath — это путь к тегу, который может быть либо тегом, либо ключевое слово. Например, идентификатор пациента представлен 00100020 или PatientId

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

Имя	Обязательно	Тип	Описание
Content-Type	True	строка	application/json поддерживается.

Текст запроса

Имя	Обязательно	Тип	Описание
текст		Тег расширенного запроса для обновления

Ответы

Имя	Тип	Описание
20 (ОК)	Тег расширенного запроса	Обновленный тег расширенного запроса
400 (недопустимый запрос)		Недопустимый путь или текст запрошенного тега
404 (не найдено)		Тег расширенного запроса с запрошенным tagPath не найден

Вывод списка ошибок тега расширенного запроса

Выводит список ошибок в расширенном теге запроса.

GET .../extendedquerytags/{tagPath}/errors

Параметры универсального кода ресурса (URI)

Имя	В	Обязательно	Тип	Описание
tagPath	path	True	строка	tagPath — это путь к тегу, который может быть либо тегом, либо ключевое слово. Например, идентификатор пациента представлен 00100020 или PatientId

Ответы

Имя	Тип	Описание
200 OK;	Ошибка тега расширенного запроса[]	Список ошибок тега расширенного запроса, связанных с тегом
400 (недопустимый запрос)		Запрошенный путь к тегу недопустим
404 (не найдено)		Тег расширенного запроса с запрошенным tagPath не найден

Операция получения

Получение длительной операции.

GET .../operations/{operationId}

Параметры универсального кода ресурса (URI)

Имя	В	Обязательно	Тип	Описание
operationId	path	True	строка	Идентификатор операции

Ответы

Имя	Тип	Описание
200 OK;	Операция	Завершенная операция для указанного идентификатора
202 Accepted (принято).	Операция	Выполняющаяся операция для указанного идентификатора
404 (не найдено)		Операция не найдена

QIDO с расширенными тегами запросов

Состояние тега

Тег "Состояние расширенного запроса" указывает текущее состояние. При первом добавлении тега расширенного запроса для его состояния устанавливается значение Adding, и запускается длительная операция для повторной индексации существующих экземпляров DICOM. После завершения операции состояние тега обновляется на Ready. Теперь в QIDO можно использовать тег расширенного запроса.

Например, если добавляется тег Manufacturer Model Name (0008,1090) и находится в Ready состоянии , в дальнейшем следующие запросы можно использовать для фильтрации хранимых экземпляров по имени модели производителя.

../instances?ManufacturerModelName=Microsoft

Их также можно использовать с существующими тегами. Пример:

../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true

Состояние запроса тега

QueryStatus указывает, разрешено ли QIDO для тега. Если операции повторной индексации не удается обработать один или несколько экземпляров DICOM для тега, параметру QueryStatus этого тега присваивается Disabled значение автоматически. Вы можете игнорировать ошибки индексирования и разрешить запросам использовать этот тег, задав для значение QueryStatus с Enabled помощью API обновления расширенного тега запроса . Все запросы QIDO, ссылающиеся по крайней мере на один тег, включенный вручную, будут содержать набор тегов с ошибками индексирования в заголовке erroneous-dicom-attributesответа .

Например, предположим, что в теге PatientAge расширенного запроса произошли ошибки во время повторного индексирования, но он был включен вручную. Для следующего запроса вы увидите PatientAge в заголовке erroneous-dicom-attributes .

../instances?PatientAge=035Y

Определения

Тег расширенного запроса

Тег DICOM, который будет поддерживаться для QIDO-RS.

Имя	Тип	Описание
Путь	строка	Путь к тегу, обычно состоящий из идентификатора группы и идентификатора элемента. Например, PatientId (0010 0020) имеет путь 00100020
VR	строка	Представление значения этого тега
PrivateCreator	строка	Идентификационный код реализующего этого закрытого тега
Level	Расширенный уровень тега запроса	Уровень расширенного тега запроса
Состояние	Состояние тега расширенного запроса	Состояние тега расширенного запроса
QueryStatus	Состояние запроса расширенного тега запроса	Состояние запроса расширенного тега запроса
ошибки	Справочник по ошибкам расширенного тега запроса	Ссылка на ошибки расширенного тега запроса
Операция	Справочник по операции	Ссылка на долго выполняющуюся операцию

Пример кода 1 — это стандартный тег (0008 0070) в Ready состоянии.

{
    "status": "Ready",
    "level": "Instance",
    "queryStatus": "Enabled",
    "path": "00080070",
    "vr": "LO"
}

Пример кода 2 — это стандартный тег (0010 1010) в Adding состоянии. На нем выполняется операция с идентификатором 1a5d0306d9624f699929ee1a59ed57a0 , и на данный момент произошла 21 ошибка.

{
    "status": "Adding",
    "level": "Study",
    "errors": {
        "count": 21,
        "href": "https://localhost:63838/extendedquerytags/00101010/errors"
    },
    "operation": {
        "id": "1a5d0306d9624f699929ee1a59ed57a0",
        "href": "https://localhost:63838/operations/1a5d0306d9624f699929ee1a59ed57a0"
    },
    "queryStatus": "Disabled",
    "path": "00101010",
    "vr": "AS"
}

Справочник по операции

Ссылка на долго выполняющуюся операцию.

Имя	Тип	Описание
ID	строка	идентификатор операции
Href	строка	Универсальный код ресурса (URI) операции

Операция

Представляет длительную операцию.

Имя	Тип	Описание
OperationId	строка	Идентификатор операции
OperationType	Тип операции	Тип длительной операции
CreatedTime	строка	Время создания операции
LastUpdatedTime	строка	Время последнего обновления операции
Состояние	Состояние операции	Представляет состояние операции во время выполнения.
PercentComplete	Целое число	Процент работы, выполненной операцией
Ресурсы	string[]	Коллекция расположений ресурсов, которые создаются или обрабатываются операцией

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

{
    "resources": [
        "https://localhost:63838/extendedquerytags/00101010"
    ],
    "operationId": "a99a8b51-78d4-4fd9-b004-b6c0bcaccf1d",
    "type": "Reindex",
    "createdTime": "2021-10-06T16:40:02.5247083Z",
    "lastUpdatedTime": "2021-10-06T16:40:04.5152934Z",
    "status": "Running",
    "percentComplete": 10
}

Состояние операции

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

Имя	Тип	Описание
NotStarted	строка	Операция не запущена
Запущен	строка	Операция выполняется и еще не завершена
Завершено	строка	Операция успешно завершена
Сбой	строка	Операция была преждевременно остановлена после возникновения одной или нескольких ошибок

Ошибка тега расширенного запроса

Ошибка, которая произошла во время расширенной операции индексирования тегов запроса.

Имя	Тип	Описание
StudyInstanceUid	строка	Изучение uiD экземпляра, где произошли ошибки индексирования
SeriesInstanceUid	строка	UiD экземпляра ряда, где произошли ошибки индексирования
SopInstanceUid	строка	Идентификатор пользовательского интерфейса экземпляра Sop, где произошли ошибки индексирования
CreatedTime	строка	Время возникновения ошибки (UTC)
ErrorMessage	строка	Сообщение об ошибке

В следующем примере кода содержится непредвиденная ошибка длины значения в экземпляре DICOM. Это произошло в 2021-10-06T16:41:44.4783136.

{
    "studyInstanceUid": "2.25.253658084841524753870559471415339023884",
    "seriesInstanceUid": "2.25.309809095970466602239093351963447277833",
    "sopInstanceUid": "2.25.225286918605419873651833906117051809629",
    "createdTime": "2021-10-06T16:41:44.4783136",
    "errorMessage": "Value length is not expected."
}

Справочник по ошибкам расширенного тега запроса

Ссылка на ошибки расширенного тега запроса.

Имя	Тип	Описание
Count	Целое число	Общее количество ошибок в теге расширенного запроса
Href	строка	URI для ошибок тега расширенного запроса

Operation type (Тип операции)

Тип длительной операции.

Имя	Тип	Описание
Повторная индексация	строка	Операция повторной индексации, которая обновляет индексы для ранее добавленных данных на основе новых тегов.

Состояние тега расширенного запроса

Состояние тега расширенного запроса.

Имя	Тип	Описание
Добавление	строка	Добавлен расширенный тег запроса, а в ходе длительной операции выполняется переиндексирование существующих экземпляров DICOM.
Ready	строка	Тег расширенного запроса готов к использованию QIDO-RS
Удаление	строка	Тег расширенного запроса удаляется

Расширенный уровень тега запроса

Уровень иерархии сведений DICOM, на котором применяется этот тег.

Имя	Тип	Описание
Экземпляр	строка	Тег расширенного запроса имеет отношение на уровне экземпляра.
Series	строка	Тег расширенного запроса имеет отношение на уровне рядов.
Исследование	строка	Расширенный тег запроса имеет отношение на уровне исследования

Состояние запроса расширенного тега запроса

Состояние запроса расширенного тега запроса.

Имя	Тип	Описание:
Выключено	строка	Запрос к расширенному тегу запроса запрещен
Активировано	строка	Разрешено запрашивать тег расширенного запроса

Примечание

Ошибки во время операции повторной индексации отключают QIDO для тега расширенного запроса. Чтобы включить его, можно вызвать API обновления расширенного тега запроса .

Расширенный тег запроса для обновления

Представляет расширенный тег запроса для обновления.

Имя	Тип	Описание
QueryStatus	Состояние запроса расширенного тега запроса	Состояние запроса расширенного тега запроса

Расширенный тег запроса для добавления

Представляет расширенный тег запроса для добавления.

Имя	Обязательно	Тип	Описание
Путь	True	строка	Путь к тегу, обычно состоящий из идентификатора группы и идентификатора PatientId элемента ( 0010 0020), имеет путь 00100020
VR		строка	Представление значения этого тега. Это необязательно для стандартного тега и требуется для частного тега.
PrivateCreator		строка	Идентификационный код реализации этого закрытого тега. Задается только в том случае, если тег является частным тегом
Level	True	Расширенный уровень тега запроса	Представляет иерархию, в которой относится этот тег. Должен быть одним из объектов Study, Series или Instance

В примере кода 1MicrosoftPC определяется закрытый тег (0401,1001) с представлением SS значения на уровне экземпляра.

{
    "Path": "04011001",
    "VR": "SS",
    "PrivateCreator": "MicrosoftPC",
    "Level": "Instance"
}

В примере кода 2 используется стандартный тег с ключевое слово ManufacturerModelName с представлением LO значения, определенного на уровне рядов.

{
    "Path": "ManufacturerModelName",
    "VR": "LO",
    "Level": "Series"
}

В примере кода 3 используется стандартный тег (0010 0040) и он определяется в исследованиях. Представление значения уже определено стандартом DICOM.

{
    "Path": "00100040",
    "Level": "Study"
}

Итоги

В этой концептуальной статье представлен обзор функции расширенного тега запроса в службе DICOM.

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

Дополнительные сведения о развертывании службы DICOM см. в статье.

Развертывание службы DICOM в Azure

Использование СТАНДАРТНЫХ API DICOMweb™со службой DICOM