Uso de LAS API estándar DICOMWeb™ con cURL

En este tutorial se usa cURL para demostrar cómo trabajar con el servicio DICOM.

En este tutorial, usaremos los siguientes archivos .dcm DICOM de ejemplo.

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

El nombre de archivo, studyUID, seriesUID e instanceUID de los archivos DICOM de ejemplo es el siguiente:

Archivo 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

Nota:

Cada uno de estos archivos representa una sola instancia y forma parte del mismo estudio. Además, el triángulo verde cuadrado y rojo forman parte de la misma serie, mientras que el círculo azul está en una serie independiente.

Prerrequisitos

Para usar las API estándar DICOMWeb™, debe tener una instancia del servicio DICOM implementado. Si aún no ha implementado una instancia del servicio DICOM, consulte Implementación del servicio DICOM mediante el Azure Portal.

Una vez que haya implementado una instancia del servicio DICOM, recupere la dirección URL de App Service:

  1. Inicie sesión en el Portal de Azure.
  2. Busque Recursos recientes y seleccione la instancia del servicio DICOM.
  3. Copie la dirección URL del servicio DICOM.
  4. Si aún no ha obtenido un token, consulte Obtención del token de acceso para el servicio DICOM mediante la CLI de Azure.

Para este código, accederemos a un servicio de Azure de versión preliminar pública. Es importante que no cargue ninguna información de salud privada (PHI).

Trabajar con el servicio DICOM

El estándar DICOMweb™ hace un uso intensivo de multipart/related las solicitudes HTTP combinadas con encabezados de aceptación específicos de DICOM. Los desarrolladores familiarizados con otras API basadas en REST suelen encontrar trabajo con DICOMweb™ Standard incómodo. Sin embargo, una vez que lo tenga en funcionamiento, es fácil de usar. Solo se necesita un poco de familiaridad para empezar.

Los comandos cURL contienen al menos uno y, a veces, dos variables que se deben reemplazar. Para simplificar la ejecución de los comandos, busque y reemplace las siguientes variables reemplazandolas por sus valores específicos:

  • {Dirección URL del servicio} Esta es la dirección URL para acceder al servicio DICOM que aprovisionó en el Azure Portal, por ejemplo, https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com. Asegúrese de especificar la versión como parte de la dirección URL al realizar solicitudes. Para obtener más información, consulte Control de versiones de API para el servicio DICOM.
  • {path-to-dicoms}: ruta de acceso al directorio que contiene el archivo red-triangle.dcm, como C:/dicom-server/docs/dcms
    • Asegúrese de usar barras diagonales como separadores y finalizar el directorio sin una barra diagonal final.

Carga de instancias de DICOM (STOW)

Store-instances-using-multipart/related

Esta solicitud pretende demostrar cómo cargar archivos DICOM mediante varias partes o relacionadas.

Nota:

El servicio DICOM es más lenciente que el estándar DICOM. Sin embargo, en el ejemplo siguiente se muestra una solicitud POST que cumple estrictamente con el estándar.

Detalles:

  • Camino:.. /Estudios
  • Método: POST
  • Encabezados:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorización: portador {valor del token}
  • Cuerpo:
    • Content-Type: application/dicom para cada archivo cargado, separado por un valor de límite

Algunos lenguajes de programación y herramientas se comportan de forma diferente. Por ejemplo, algunos requieren que defina su propio límite. Para ellos, es posible que tenga que usar un encabezado Content-Type ligeramente modificado. Los siguientes se han usado correctamente.

  • 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"

Almacenar instancias de un estudio específico

Esta solicitud muestra cómo cargar archivos DICOM mediante varias partes o relacionadas con un estudio designado.

Detalles:

  • Camino:.. /studies/{study}
  • Método: POST
  • Encabezados:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorización: portador {valor del token}
  • Cuerpo:
    • Content-Type: application/dicom para cada archivo cargado, separado por un valor de límite

Algunos lenguajes de programación y herramientas se comportan de forma diferente. Por ejemplo, algunos requieren que defina su propio límite. Para ellos, es posible que tenga que usar un encabezado Content-Type ligeramente modificado. Los siguientes se han usado correctamente.

  • 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"

Store-single-instance

Nota:

Se trata de una API no estándar que permite cargar un único archivo DICOM sin necesidad de configurar POST para varias partes o relacionadas. Aunque cURL controla bien varias partes o relacionadas, esta API permite que herramientas como Postman carguen archivos en el servicio DICOM.

El método siguiente es necesario para cargar un único archivo DICOM.

Detalles:

  • Camino:.. /Estudios
  • Método: POST
  • Encabezados:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Autorización: portador {valor del token}
  • Cuerpo:
    • Contiene un único archivo DICOM como bytes binarios.
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"

Recuperación de DICOM (WADO)

Recuperar todas las instancias de un estudio

Esta solicitud recupera todas las instancias de un único estudio y las devuelve como una colección de bytes de varias partes o relacionadas.

Detalles:

  • Camino:.. /studies/{study}
  • Método: GET
  • Encabezados:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Autorización: portador {valor del token}
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"

Este comando cURL mostrará los bytes descargados en el archivo de salida (suppressWarnings.txt), pero no son archivos DICOM directos, solo una representación de texto de la descarga multipart/relacionada.

Recuperar metadatos de todas las instancias del estudio

Esta solicitud recupera los metadatos de todas las instancias de un único estudio.

Detalles:

  • Camino:.. /studies/{study}/metadata
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}

Este comando cURL mostrará los bytes descargados en el archivo de salida (suppressWarnings.txt), pero no son archivos DICOM directos, solo una representación de texto de la descarga multipart/relacionada.

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}"

Recuperar todas las instancias de una serie

Esta solicitud recupera todas las instancias de una sola serie y las devuelve como una colección de bytes de varias partes o relacionados.

Detalles:

  • Camino:.. /studies/{study}/series/{series}
  • Método: GET
  • Encabezados:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Autorización: portador {valor del token}

Este comando cURL mostrará los bytes descargados en el archivo de salida (suppressWarnings.txt), pero no es el archivo DICOM, solo una representación de texto de la descarga relacionada con varias partes.

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"

Recuperar metadatos de todas las instancias de una serie

Esta solicitud recupera los metadatos de todas las instancias de un único estudio.

Detalles:

  • Camino:.. /studies/{study}/series/{series}/metadata
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Recuperar una sola instancia dentro de una serie de un estudio

Esta solicitud recupera una sola instancia y la devuelve como una secuencia con formato DICOM de bytes.

Detalles:

  • Camino:.. /studies/{study}/series{series}/instances/{instance}
  • Método: GET
  • Encabezados:
    • Accept: application/dicom; transfer-syntax=*
    • Autorización: portador {valor del token}
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"

Recuperar metadatos de una sola instancia dentro de una serie de un estudio

Esta solicitud recupera los metadatos de una sola instancia dentro de un único estudio y serie.

Detalles:

  • Camino:.. /studies/{study}/series/{series}/instances/{instance}/metadata
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Recuperar uno o varios fotogramas de una sola instancia

Esta solicitud recupera uno o varios fotogramas de una sola instancia y los devuelve como una colección de bytes de varias partes o relacionados. Se pueden recuperar varios fotogramas pasando una lista separada por comas de números de fotogramas. Todas las instancias de DICOM con imágenes tienen como mínimo un fotograma, que a menudo es simplemente la imagen asociada a la propia instancia.

Detalles:

  • Camino:.. /studies/{study}/series{series}/instances/{instance}/frames/1,2,3
  • Método: GET
  • Encabezados:
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (valor predeterminado) o
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* o
    • Accept: multipart/related; type="application/octet-stream";
    • Autorización: portador {valor del token}
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"

Consulta DICOM (QIDO)

En los ejemplos siguientes, buscaremos elementos con sus identificadores únicos. También puede buscar otros atributos, como PatientName.

Búsqueda de estudios

Esta solicitud permite buscar uno o varios estudios por atributos DICOM.

Para obtener más información sobre los atributos DICOM admitidos, vea la instrucción de conformidad diCOM.

Detalles:

  • Camino:.. /¿Estudios? StudyInstanceUID={study}
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Búsqueda de series

Esta solicitud permite buscar una o varias series por atributos DICOM.

Para obtener más información sobre los atributos DICOM admitidos, vea la instrucción de conformidad diCOM.

Detalles:

  • Camino:.. /¿Serie? SeriesInstanceUID={series}
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Buscar series dentro de un estudio

Esta solicitud permite buscar una o varias series dentro de un único estudio por atributos DICOM.

Para obtener más información sobre los atributos DICOM admitidos, vea la instrucción de conformidad diCOM.

Detalles:

  • Camino:.. /studies/{study}/series? SeriesInstanceUID={series}
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Búsqueda de instancias

Esta solicitud permite buscar una o varias instancias por atributos DICOM.

Para obtener más información sobre los atributos DICOM admitidos, vea la instrucción de conformidad diCOM.

Detalles:

  • Camino:.. /¿Instancias? SOPInstanceUID={instance}
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Buscar instancias dentro de un estudio

Esta solicitud permite buscar una o varias instancias dentro de un único estudio por atributos DICOM.

Para obtener más información sobre los atributos DICOM admitidos, vea la instrucción de conformidad diCOM.

Detalles:

  • Camino:.. /studies/{study}/instances? SOPInstanceUID={instance}
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Buscar instancias dentro de un estudio y una serie

Esta solicitud permite buscar una o varias instancias dentro de un único estudio y una sola serie por atributos DICOM.

Para obtener más información sobre los atributos dicom admitidos, vea la instrucción de conformidad de DICOM.

Detalles:

  • Camino:.. /studies/{study}/series/{series}/instances? SOPInstanceUID={instance}
  • Método: GET
  • Encabezados:
    • Accept: application/dicom+json
    • Autorización: portador {valor del token}
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}"

Eliminar DICOM

Eliminar una instancia específica dentro de un estudio y una serie

Esta solicitud elimina una única instancia dentro de un único estudio y una sola serie.

La eliminación no forma parte del estándar DICOM, pero se ha agregado para mayor comodidad.

Detalles:

  • Camino:.. /studies/{study}/series/{series}/instances/{instance}
  • Método: DELETE
  • Encabezados:
    • Autorización: portador {valor del token}
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}"

Eliminar una serie específica dentro de un estudio

Esta solicitud elimina una sola serie (y todas las instancias secundarias) dentro de un único estudio.

La eliminación no forma parte del estándar DICOM, pero se ha agregado para mayor comodidad.

Detalles:

  • Camino:.. /studies/{study}/series/{series}
  • Método: DELETE
  • Encabezados:
    • Autorización: portador {valor del token}
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}"

Eliminar un estudio específico

Esta solicitud elimina un único estudio (y todas las series y instancias secundarias).

La eliminación no forma parte del estándar DICOM, pero se ha agregado para mayor comodidad.

Detalles:

  • Camino:.. /studies/{study}
  • Método: DELETE
  • Encabezados:
    • Autorización: portador {valor del token}
curl--request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498
--header "Authorization: Bearer {token value}"

Pasos siguientes

Para obtener información sobre el servicio DICOM, consulte