Использование СТАНДАРТНЫХ API DICOMWeb™ с cURL

В этом руководстве используется cURL для демонстрации работы со службой DICOM.

В этом руководстве мы будем использовать следующие примеры 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 DICOMWeb™, необходимо развернуть экземпляр службы DICOM. Если вы еще не развернули экземпляр службы DICOM, см. статью Развертывание службы DICOM с помощью портал Azure.

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

  1. Войдите на портал Azure.
  2. Найдите последние ресурсы и выберите экземпляр службы DICOM.
  3. Скопируйте URL-адрес службы DICOM.
  4. Если вы еще не получили маркер, см. статью Получение маркера доступа для службы DICOM с помощью Azure CLI.

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

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

Стандарт DICOMweb™ интенсивно использует HTTP-запросы в сочетании multipart/related с заголовками приема, характерными для DICOM. Разработчики, знакомые с другими API на основе REST, часто считают работу со стандартом DICOMweb™ неловко. Тем не менее, после того как он будет запущен, он будет прост в использовании. Чтобы приступить к работе, требуется немного знакомства.

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

  • {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)

Store-instances-using-multipart/related

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

Примечание

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

Подробности:

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

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

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
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
  • Headers:
    • Принять: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Авторизация: носитель {значение токена}
  • Текст:
    • Content-Type: application/dicom для каждого отправленного файла, разделенного значением границы.

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

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
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
  • Headers:
    • Принять: 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"

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

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

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

Подробности:

  • Путь:.. /studies/{study}
  • Метод: GET
  • Headers:
    • Принять: многокомпонентный/связанный; 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
  • Headers:
    • Принять: application/dicom+json
    • Авторизация: Носитель {значение токена}

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

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
  • Headers:
    • Принять: многокомпонентный/связанный; 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
  • Headers:
    • Принять: 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
  • Headers:
    • Принять: 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
  • Headers:
    • Принять: 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
  • Headers:
    • Принять: многокомпонентный/связанный; 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"

Запрос DICOM (QIDO)

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

Поиск исследований

Этот запрос позволяет выполнять поиск одного или нескольких исследований по атрибутам DICOM.

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

Подробности:

  • Путь:.. /Исследования? StudyInstanceUID={study}
  • Метод: GET
  • Headers:
    • Принять: application/dicom+json
    • Авторизация: Носитель {значение токена}
curl --request GET "{Service URL}/v{version}/studies?StudyInstanceUID=1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Поиск рядов

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

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

Подробности:

  • Путь:.. /Серии? SeriesInstanceUID={series}
  • Метод: GET
  • Headers:
    • Принять: application/dicom+json
    • Авторизация: Носитель {значение токена}
curl --request GET "{Service URL}/v{version}/series?SeriesInstanceUID=1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

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

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

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

Подробности:

  • Путь:.. /studies/{study}/series? SeriesInstanceUID={series}
  • Метод: GET
  • Headers:
    • Принять: application/dicom+json
    • Авторизация: Носитель {значение токена}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series?SeriesInstanceUID=1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Поиск экземпляров

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

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

Подробности:

  • Путь:.. /Экземпляров? SOPInstanceUID={instance}
  • Метод: GET
  • Headers:
    • Принять: application/dicom+json
    • Авторизация: носитель {значение токена}
curl --request GET "{Service URL}/v{version}/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

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

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

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

Подробности:

  • Путь:.. /studies/{study}/instances? SOPInstanceUID={instance}
  • Метод: GET
  • Headers:
    • Принять: application/dicom+json
    • Авторизация: носитель {значение токена}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

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

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

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

Подробности:

  • Путь:.. /studies/{study}/series/{series}/instances? SOPInstanceUID={instance}
  • Метод: GET
  • Headers:
    • Принять: 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?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Удаление DICOM

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

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

Удаление не является частью стандарта DICOM, но оно добавлено для удобства.

Подробности:

  • Путь:.. /studies/{study}/series/{series}/instances/{instance}
  • Метод: DELETE
  • Headers:
    • Авторизация: носитель {значение токена}
curl --request DELETE "{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 "Authorization: Bearer {token value}"

Удаление определенной серии в исследовании

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

Удаление не является частью стандарта DICOM, но оно добавлено для удобства.

Подробности:

  • Путь:.. /studies/{study}/series/{series}
  • Метод: DELETE
  • Headers:
    • Авторизация: носитель {значение токена}
curl --request DELETE "{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 "Authorization: Bearer {token value}"

Удаление определенного исследования

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

Удаление не является частью стандарта DICOM, но оно было добавлено для удобства.

Подробности:

  • Путь:.. /studies/{study}
  • Метод: DELETE
  • Headers:
    • Авторизация: носитель {значение токена}
curl--request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498
--header "Authorization: Bearer {token value}"

Next Steps

Сведения о службе DICOM см. в разделе