Использование API DICOMweb Standard с cURL

Статья
04/13/2024

В этой статье показано, как работать со службой DICOMweb с помощью cURL и примеров .dcm файлов DICOM®.

Используйте следующие примеры файлов:

blue-circle.dcm
dicom-metadata.csv
green-square.dcm
red-triangle.dcm

Имя файла, studyUID, seriesUID и instanceUID примера файлов DICOM:

Файлы	StudyUID	SeriesUID	InstanceUID
green-square.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.12714725698140337137334606354172323212
red-triangle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395
blue-circle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.77033797676425927098669402985243398207	1.2.826.0.1.3680043.8.498.13273713909719068980354078852867170114

Примечание.

Каждый из этих файлов представляет один экземпляр и является частью одного исследования. Кроме того, зеленый квадрат и красный треугольник являются частью одной серии, в то время как синий круг находится в отдельной серии.

Необходимые компоненты

Чтобы использовать API-интерфейсы DICOM standard, необходимо развернуть экземпляр службы DICOM. Дополнительные сведения см. в статье "Развертывание службы DICOM с помощью портал Azure".

После развертывания экземпляра службы DICOM получите URL-адрес службы приложений.

Войдите на портал Azure.
Выполните поиск последних ресурсов и выберите экземпляр службы DICOM.
Скопируйте URL-адрес службы DICOM.
Если вам нужен маркер доступа, см . сведения о получении маркера доступа для службы DICOM.

Для этого кода мы доступ к службе Общедоступной предварительной версии Azure. Важно, чтобы вы не загружали какие-либо частные сведения о работоспособности (PHI).

Работа со службой DICOM

DiCOMweb Standard использует http-запросы в сочетании multipart/related с определенными заголовками приема DICOM. Разработчики, знакомые с другими API на основе REST, часто находят работу с DICOMweb Standard неловко. Тем не менее, после того как вы получите его и работаете, это легко использовать. Это просто занимает немного знакомства, чтобы приступить к работе.

Команды cURL содержат по крайней мере одну, а иногда две переменные, которые должны быть заменены. Чтобы упростить выполнение команд, выполните поиск и замените указанные ниже переменные.

{URL-адрес службы} URL-адрес службы — это URL-адрес для доступа к службе DICOM, подготовленной в портал Azure, напримерhttps://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com. Обязательно укажите версию в качестве части URL-адреса при выполнении запросов. Дополнительные сведения см. в документации по версиям API для службы DICOM.
{path-to-dicoms} — путь к каталогу, который содержит файл red-triangle.dcm, например C:/dicom-server/docs/dcms
- Убедитесь, что в качестве разделителей используется косая черта вперед и заканчивается каталог без косой черты.

Отправка экземпляров DICOM (STOW)

Хранение экземпляров с помощью нескольких частей или связанных

Этот запрос намерен продемонстрировать, как отправлять ФАЙЛЫ DICOM с помощью нескольких частей или связанных.

Примечание.

Служба DICOM более удобна, чем стандарт DICOM. Однако в примере демонстрируется запрос POST, который соответствует стандарту.

Сведения:

Путь:.. /учёба
Метод: POST
Заголовки:
- Принять: application/dicom+json
- Тип контента: многопартийное или связанное; type="application/dicom"
- Авторизация: носитель {значение токена}
Текст:
- Content-Type: application/dicom для каждого отправленного файла, разделенного значением границы

Некоторые языки программирования и средства ведут себя по-разному. Например, некоторым требуется определить собственную границу. Для этих средств может потребоваться использовать немного измененный заголовок Content-Type. Следующие средства можно использовать успешно.

Тип контента: многопартийное или связанное; type="application/dicom"; boundary=ABCD1234
Тип контента: многопартийное или связанное; boundary=ABCD1234
Тип контента: многопартийное или связанное

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

Хранение экземпляров для конкретного исследования

В этом запросе показано, как отправлять ФАЙЛЫ DICOM с помощью нескольких частей или связанных с указанным исследованием.

Сведения:

Путь:.. /studies/{study}
Метод: POST
Заголовки:
- Принять: application/dicom+json
- Тип контента: многопартийное или связанное; type="application/dicom"
- Авторизация: носитель {значение токена}
Текст:
- Content-Type: application/dicom для каждого отправленного файла, разделенного значением границы

Некоторые языки программирования и средства ведут себя по-разному. Например, некоторым требуется определить собственную границу. Для этих языков и инструментов может потребоваться использовать немного измененный заголовок Content-Type. Следующие средства можно использовать успешно.

Тип контента: многопартийное или связанное; type="application/dicom"; boundary=ABCD1234
Тип контента: многопартийное или связанное; boundary=ABCD1234
Тип контента: многопартийное или связанное

curl --request POST "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Хранилище с одним экземпляром

Примечание.

Это нестандартный API, который позволяет отправлять один ФАЙЛ DICOM без необходимости настраивать POST для нескольких частей или связанных. Хотя cURL хорошо обрабатывает многопартийную или связанную с ним работу, этот API позволяет таким средствам, как Postman отправлять файлы в службу DICOM.

Для отправки одного ФАЙЛА DICOM требуется следующий метод.

Сведения:

Путь:.. /учёба
Метод: POST
Заголовки:
- Принять: application/dicom+json
- Content-Type: application/dicom
- Авторизация: носитель {значение токена}
Текст:
- Содержит один файл DICOM в виде двоичных байтов.

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

Экземпляры Upsert с помощью нескольких частей и связанных

Примечание.

Это не стандартный API, который позволяет выполнять upsert файлов DICOM с помощью нескольких частей или связанных.

Сведения:

Путь:.. /учёба
Метод: PUT
Заголовки:
- Принять: application/dicom+json
- Тип контента: многопартийное или связанное; type="application/dicom"
- Авторизация: носитель {значение токена}
Текст:
- Content-Type: application/dicom для каждого отправленного файла, разделенного значением границы

Тип контента: многопартийное или связанное; type="application/dicom"; boundary=ABCD1234
Тип контента: многопартийное или связанное; boundary=ABCD1234
Тип контента: многопартийное или связанное

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

Экземпляры Upsert для конкретного исследования

Примечание.

Это нестандартный API, который позволяет upsert файлов DICOM использовать многопартийное или связанное с назначенным исследованием.

Сведения:

Путь:.. /studies/{study}
Метод: PUT
Заголовки:
- Принять: application/dicom+json
- Тип контента: многопартийное или связанное; type="application/dicom"
- Авторизация: носитель {значение токена}
Текст:
- Content-Type: application/dicom для каждого отправленного файла, разделенного значением границы

Тип контента: многопартийное или связанное; type="application/dicom"; boundary=ABCD1234
Тип контента: многопартийное или связанное; boundary=ABCD1234
Тип контента: многопартийное или связанное

curl --request PUT "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Один экземпляр Upsert

Примечание.

Это не стандартный API, который позволяет выполнять upsert одного DICOM-файла.

Используйте этот метод для отправки одного ФАЙЛА DICOM.

Сведения:

Путь:.. /учёба
Метод: PUT
Заголовки:
- Принять: application/dicom+json
- Content-Type: application/dicom
- Авторизация: носитель {значение токена}
Текст:
- Содержит один файл DICOM в виде двоичных байтов.

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

Получение DICOM (WADO)

Получение всех экземпляров в исследовании

Этот запрос извлекает все экземпляры в одном исследовании и возвращает их в виде коллекции многопартийных или связанных байтов.

Сведения:

Путь:.. /studies/{study}
Метод: GET
Заголовки:
- Принять: многопартийное или связанное; type="application/dicom"; transfer-syntax=*
- Авторизация: носитель {значение токена}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Эта команда cURL показывает скачанные байты в выходном файле (suppressWarnings.txt), но они не являются прямыми файлами DICOM, а только текстовым представлением многопартийного или связанного скачивания.

Получение метаданных всех экземпляров в исследовании

Этот запрос извлекает метаданные для всех экземпляров в одном исследовании.

Сведения:

Путь:.. /studies/{study}/метаданные
Метод: GET
Заголовки:
- Принять: application/dicom+json
- Авторизация: носитель {значение токена}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Получение всех экземпляров в серии

Этот запрос извлекает все экземпляры в одной серии и возвращает их в виде коллекции многопартийных и связанных байтов.

Сведения:

Путь:.. /studies/{study}/series/{series}
Метод: GET
Заголовки:
- Принять: многопартийное или связанное; type="application/dicom"; transfer-syntax=*
- Авторизация: носитель {значение токена}

Эта команда cURL показывает скачанные байты в выходном файле (suppressWarnings.txt), но это не DICOM-файл, а только текстовое представление многопартийного или связанного скачивания.

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Получение метаданных всех экземпляров в серии

Этот запрос извлекает метаданные для всех экземпляров в одном исследовании.

Сведения:

Путь:.. /studies/{study}/series/{series}/metadata
Метод: GET
Заголовки:
- Принять: application/dicom+json
- Авторизация: носитель {значение токена}

curl --request GET "{Service URL}/v{version}/studies1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Получение одного экземпляра в серии исследования

Этот запрос извлекает один экземпляр и возвращает его в виде отформатированного потока байтов в формате DICOM.

Сведения:

Путь:.. /studies/{study}/series{series}/instances/{instance}
Метод: GET
Заголовки:
- Принять: application/dicom; transfer-syntax=*
- Авторизация: носитель {значение токена}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Получение метаданных одного экземпляра в серии исследований

Этот запрос извлекает метаданные для одного экземпляра в рамках одного исследования и ряда.

Сведения:

Путь:.. /studies/{study}/series/{series}/instances/{instance}/metadata
Метод: GET
Заголовки:
- Принять: application/dicom+json
- Авторизация: носитель {значение токена}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Получение одного или нескольких кадров из одного экземпляра

Этот запрос извлекает один или несколько кадров из одного экземпляра и возвращает их в виде коллекции многопартийных или связанных байтов. Можно получить несколько кадров, передав список чисел кадра с разделиемыми запятыми. Все экземпляры DICOM с изображениями имеют как минимум один кадр, который часто является просто изображением, связанным с самим экземпляром.

Сведения:

Путь:.. /studies/{study}/series{series}/instances/{instance}/frames/1,2,3
Метод: GET
Заголовки:
- Принять: многопартийное или связанное; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (по умолчанию)
- Принять: многопартийное или связанное; type="application/octet-stream"; transfer-syntax=* или
- Принять: многопартийное или связанное; type="application/octet-stream";
- Авторизация: носитель {значение токена}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/frames/1"
--header "Accept: multipart/related; type=\"application/octet-stream\"; transfer-syntax=1.2.840.10008.1.2.1"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Query DICOM (QIDO)

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