Uso de la API estándar de DICOMweb con cURL

  • Artículo

En este artículo se muestra cómo trabajar con el servicio DICOMweb mediante cURL y archivos .dcm DICOM® de ejemplo.

Use estos archivos 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 son:

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 cuadrado verde y el triángulo rojo forman parte de la misma serie, mientras que el círculo azul está en una serie independiente.

Requisitos previos

Para usar las API estándar de DICOM, debe tener una instancia del servicio DICOM implementado. Para más información, consulte Implementación del servicio DICOM mediante Azure Portal.

Después de implementar una instancia del servicio DICOM, recupere la dirección URL de App Service.

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

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

Uso del servicio DICOM

El estándar DICOMweb hace un uso intensivo de solicitudes HTTP multipart/related combinadas con encabezados de aceptación específicos de DICOM. Los desarrolladores familiarizados con otras API basadas en REST suelen encontrar muy complejo el estándar DICOMweb. Sin embargo, una vez que está en funcionamiento, es fácil de usar. Solo es necesario acostumbrarse al principio.

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

  • {Service URL} La dirección URL del servicio es la dirección URL para acceder al servicio DICOM que aprovisionó en 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 DICOM (STOW)

Almacenamiento de instancias mediante varias partes o relacionadas

Esta solicitud pretende demostrar cómo cargar archivos DICOM mediante multipart/related (varias partes o relacionadas).

Nota:

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

Detalles:

  • Ruta de acceso: ../studies
  • Método: POST
  • Encabezados:
    • Aceptar: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorización: portador {valor de 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 esas herramientas, es posible que tenga que usar un encabezado Content-Type ligeramente modificado. Estas herramientas se pueden usar 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"

Almacena instancias para un estudio específico

Esta solicitud muestra cómo cargar archivos DICOM mediante multipart/related (varias partes o relacionadas) con un estudio designado.

Detalles:

  • Ruta de acceso: ../studies/{study}
  • Método: POST
  • Encabezados:
    • Aceptar: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorización: portador {valor de 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 esos lenguajes y herramientas, es posible que tenga que usar un encabezado Content-Type ligeramente modificado. Estas herramientas se pueden usar 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"

Almacenamiento de instancia única

Nota:

Se trata de una API no estándar que permite la carga de un único archivo DICOM sin necesidad de configurar POST para multipart/related (varias partes o relacionadas). Aunque cURL controla bien multipart/related (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:

  • Ruta de acceso: ../studies
  • Método: POST
  • Encabezados:
    • Aceptar: application/dicom+json
    • Content-Type: application/dicom
    • Autorización: portador {valor de 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"

Instancias de Upsert con varias partes o relacionadas

Nota:

Se trata de una API no estándar que permite el upsert de archivos DICOM mediante varias partes o relacionadas.

Detalles:

  • Ruta de acceso: ../studies
  • Método: PUT
  • Encabezados:
    • Aceptar: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorización: portador {valor de 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 esas herramientas, es posible que tenga que usar un encabezado Content-Type ligeramente modificado. Estas herramientas se pueden usar correctamente:

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
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"

Instancias de Upsert para un estudio específico

Nota:

Se trata de una API no estándar que permite el upsert de archivos DICOM mediante varias partes o relacionadas con un estudio designado.

Detalles:

  • Ruta de acceso: ../studies/{study}
  • Método: PUT
  • Encabezados:
    • Aceptar: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorización: portador {valor de 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 esos lenguajes y herramientas, es posible que tenga que usar un encabezado Content-Type ligeramente modificado. Estas herramientas se pueden usar correctamente:

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
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"

Instancia única de Upsert

Nota:

Se trata de una API no estándar que permite el upsert de un solo archivo DICOM.

Use este método para cargar un único archivo DICOM:

Detalles:

  • Ruta de acceso: ../studies
  • Método: PUT
  • Encabezados:
    • Aceptar: application/dicom+json
    • Content-Type: application/dicom
    • Autorización: portador {valor de token}
  • Cuerpo:
    • Contiene un único archivo DICOM como bytes binarios.
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"

Recuperación de DICOM (WADO)

Recuperación de todas las instancias de un estudio

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

Detalles:

  • Ruta de acceso: ../studies/{study}
  • Método: GET
  • Encabezados:
    • Aceptar: multipart/related; type="application/dicom"; transfer-syntax=*
    • Autorización: portador {valor de 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 muestra 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/related (varias partes o relacionadas).

Recuperación de metadatos de todas las instancias del estudio

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

Detalles:

  • Ruta de acceso: ../studies/{study}/metadata
  • Método: GET
  • Encabezados:
    • Aceptar: application/dicom+json
    • Autorización: portador {valor de token}

Este comando cURL muestra 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/related (varias partes o relacionadas).

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

Recuperación de 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 multipart/related (de varias partes o relacionadas).

Detalles:

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

Este comando cURL muestra 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 multipart/related (varias partes o relacionadas).

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"

Recuperación de los metadatos de todas las instancias de una serie

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

Detalles:

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

Recuperación de 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:

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

Recuperación de 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 una única serie.

Detalles:

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

Recuperación de uno o varios marcos de una sola instancia

Esta solicitud recupera uno o varios fotogramas de una sola instancia y los devuelve como una colección de bytes multipart/related (de varias partes o relacionadas). 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 suele ser solo la imagen asociada a la propia instancia.

Detalles:

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

En los ejemplos siguientes, buscamos elementos mediante 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, consulte la Instrucción de conformidad de DICOM.

Detalles:

  • Ruta de acceso: ../studies?StudyInstanceUID={study}
  • Método: GET
  • Encabezados:
    • Aceptar: application/dicom+json
    • Autorización: portador {valor de 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 habilita las búsquedas de una o varias series por atributos DICOM.

Para obtener más información sobre los atributos DICOM admitidos, consulte la Instrucción de conformidad de DICOM.

Detalles:

  • Ruta de acceso: ../series?SeriesInstanceUID={series}
  • Método: GET
  • Encabezados:
    • Aceptar: application/dicom+json
    • Autorización: portador {valor de 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}"

Búsqueda de series en un estudio

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

Para obtener más información sobre los atributos DICOM admitidos, consulte la Instrucción de conformidad de DICOM.

Detalles:

  • Ruta de acceso: ../studies/{study}/series?SeriesInstanceUID={series}
  • Método: GET
  • Encabezados:
    • Aceptar: application/dicom+json
    • Autorización: portador {valor de 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, consulte la Instrucción de conformidad de DICOM.

Detalles:

  • Ruta de acceso: ../instances?SOPInstanceUID={instance}
  • Método: GET
  • Encabezados:
    • Aceptar: application/dicom+json
    • Autorización: portador {valor de 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}"

Búsqueda de instancias en un estudio

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

Para obtener más información sobre los atributos DICOM admitidos, consulte la Instrucción de conformidad de DICOM.

Detalles:

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

Búsqueda de instancias dentro de un estudio y 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, consulte la Instrucción de conformidad de DICOM

Detalles:

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

Eliminación de DICOM

Eliminación de una instancia específica de un estudio y una serie

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

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

Detalles:

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

Eliminación de una serie específica de un estudio

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

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

Detalles:

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

Eliminación de un estudio específico

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

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

Detalles:

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

Nota:

DICOM® es la marca registrada de la Asociación Nacional de Fabricantes Eléctricos para sus publicaciones de normas relacionadas con las comunicaciones digitales de información médica.