Declaración de conformidad de DICOM

Los almacenes DICOM de la API Cloud Healthcare son compatibles con un subconjunto de servicios web RESTful especificados en el estándar DICOM PS3.18 - Web Services (DICOM PS3.18 - Servicios web) (comúnmente conocido como DICOMweb). En concreto, admiten los servicios y recursos de estudios (anteriormente denominados servicios WADO-RS, STOW-RS y QIDO-RS).

Además, la API Cloud Healthcare es compatible con un servicio web propio para eliminar instancias DICOM.

La API Cloud Healthcare no admite el servicio URI, el servicio de lista de trabajo, el servicio de instancias no de pacientes ni ninguna de las transacciones de funciones.

Recuperar transacción

La transacción Retrieve es un servicio web RESTful para recuperar datos de imágenes DICOM.

La transacción Retrieve admite la recuperación de los siguientes recursos:

  • Recursos de DICOM:
    • Estudio
    • Serie
    • Instancia
    • Marcos
    • Bulkdata
  • Recursos de metadatos
    • Estudio
    • Serie
    • Instancia
  • Recursos renderizados
    • Instancia
    • Marcos

No admite recursos Thumbnail.

Consulta Cuotas y límites para obtener más información sobre las cuotas y los límites de estos métodos.

Estudios, series e instancias DICOM

Se admiten los siguientes encabezados de aceptación:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (predeterminado)
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*

Instancias DICOM

Además de los encabezados de aceptación anteriores, RetrieveInstance admite tipos de contenido de una sola parte para mayor comodidad:

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

No forma parte del estándar oficial de DICOMweb.

Marcos DICOM

Se admiten los siguientes encabezados de aceptación:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (predeterminado)
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

Una sintaxis de transferencia de * permite al usuario solicitar que no se realice la transcodificación, por lo que se utilizará la sintaxis de transferencia del archivo cargado. Para application/octet-stream, los datos en bloque se devolverán en el formato que aparezca en el archivo DICOM cargado.

Recursos renderizados

Se admiten los siguientes encabezados de aceptación:

  • image/jpeg (predeterminado)
  • image/png

Solo es compatible la recuperación de recursos de instancia o marco.

No se admite ningún parámetro de URL que no sea Ventana gráfica.

Recursos de metadatos

Se admiten los siguientes encabezados de aceptación:

  • application/dicom+json (predeterminado)
  • multipart/related; type=application/dicom+xml

Las etiquetas codificadas como elementos InlineBinary se codificarán mediante el orden de bytes little-endian, ya que el parámetro de sintaxis de transferencia no se admite en los endpoints que solicitan recursos de metadatos.

RetrieveMetadata incluirá BulkDataURIs para las etiquetas que coincidan con la definición de Bulkdata.

Las etiquetas de secuencia DICOM que contengan más de 1 MiB de datos aproximadamente no se devolverán en los recursos de metadatos. Esta limitación solo se aplica a los recursos de metadatos. Los recursos DICOM seguirán conteniendo estas etiquetas.

Recursos de datos en bloque

Se admiten los siguientes encabezados de aceptación:

  • multipart/related; type="application/octet-stream"; transfer-syntax=* (predeterminado)
  • application/octet-stream; transfer-syntax=*

Sintaxis de transferencia admitidas para la transcodificación

Los encabezados de aceptación anteriores describen los tipos de recursos multimedia y las sintaxis de transferencia que puedes solicitar a la API. No obstante, dependiendo de la sintaxis de transferencia del archivo original que se ha cargado, no siempre es posible hacerlo. En concreto, la transcodificación solo es posible a partir de las siguientes sintaxis de transferencia:

  • 1.2.840.10008.1.2 (Little Endian Implicit)
  • 1.2.840.10008.1.2.1 (Little Endian Explicit)
  • 1.2.840.10008.1.2.2 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.4.50 (JPEG Baseline Process 1)
  • 1.2.840.10008.1.2.4.57 (JPEG Lossless)
  • 1.2.840.10008.1.2.4.70 (JPEG Lossless Selection Value 1)
  • 1.2.840.10008.1.2.4.90 (JPEG 2000 Lossless Only)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE Lossless)

Si el archivo original tiene una sintaxis de transferencia diferente a la de la lista anterior y solicitas la transcodificación a otro formato, se devolverá un error.

La API Cloud Healthcare no puede transcodificar a JPEG imágenes no monocromáticas con una profundidad de bits superior a 8. Además, las imágenes con un valor de Bits Allocated (0028, 0100) de 1 o que se almacenan en las etiquetas Float Pixel Data (7FE0,0008) o Double Float Pixel Data (7FE0,0009) solo se pueden transcodificar entre formatos nativos.

Para deshabilitar la transcodificación y recuperar cualquier archivo de la API, puedes establecer transfer-syntax=* en el encabezado de aceptación.

Códigos de estado

Código Significado
200 (OK) La carga útil de la respuesta contiene representaciones de todos los recursos de destino.
400 (Solicitud incorrecta) La solicitud no era válida (por ejemplo, los parámetros de consulta o los encabezados no eran correctos) para los recursos de destino especificados (por ejemplo, faltaban datos de píxel).
401 (No autorizado) Faltan las credenciales de autenticación en la solicitud.
403 (Permiso denegado) El usuario autenticado no tiene acceso a este recurso (o el recurso no existe).
406 (Not Acceptable) El servidor no admite ninguno de los tipos de contenido multimedia aceptables.
429 (Demasiadas solicitudes) El cliente está superando su cuota.
503 (Servicio no disponible) El servidor no está disponible en este momento o la solicitud ha superado el plazo.

Transacción en la tienda

La transacción de almacenamiento es un servicio web RESTful para almacenar datos de imágenes DICOM.

La transacción de almacenamiento acepta directamente archivos binarios DICOM de la parte 10 o acepta la división de un archivo DICOM en metadatos (representados en JSON) y datos masivos. Estas dos versiones tienen semánticas diferentes que se describen en las siguientes secciones.

Consulta Cuotas y límites para obtener información sobre las cuotas y los límites de este método.

Archivos binarios de la parte 10 de DICOM

Se admiten los siguientes tipos de contenido:

  • multipart/related; type=application/dicom
  • application/dicom

El servidor no realiza ninguna conversión ni sustitución de atributos.

Esta versión acepta todas las sintaxis de transferencia y clases SOP. Solo se realiza una validación mínima del archivo DICOM para extraer algunos atributos de metadatos clave.

Ten en cuenta que, por comodidad, la transacción de almacenamiento también acepta una solicitud HTTP de una sola parte con una sola instancia DICOM con el tipo de contenido application/dicom. No forma parte del estándar oficial de DICOMweb.

Consulta la guía práctica para almacenar una instancia DICOM.

Solicitudes de datos en bloque y metadatos JSON

Cuando se almacenan instancias con datos en bloque y metadatos JSON, la primera parte de varias partes debe constar de una matriz JSON de instancias DICOM.

La primera parte debe tener un tipo de contenido application/dicom+json; transfer-syntax=TransferSyntaxUID donde TransferSyntaxUID es la sintaxis de transferencia que se ha utilizado para codificar datos binarios en objetos InlineBinary. Si los metadatos no contienen objetos InlineBinary, el parámetro transfer-syntax se puede omitir.

Los siguientes elementos DICOM deben estar presentes en cada instancia de los metadatos JSON:

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

El elemento SpecificCharacterSet debe establecerse en ISO_IR 192 y los metadatos JSON deben codificarse en unicode UTF-8. El elemento TransferSyntaxUID se puede definir en cualquier sintaxis de transferencia válida, excepto en las siguientes sintaxis de transferencia no compatibles:

  • 1.2.840.10008.1.2.2 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

Dentro de los metadatos JSON, el usuario puede especificar varios elementos BulkDataURI para etiquetas DICOM con representaciones de valor de OB, OW o UN. Estos elementos BulkDataURI indican que los datos binarios de la etiqueta que contiene el URI se enviarán en una parte posterior cuyo encabezado de ubicación de contenido está establecido en BulkDataURI.

Cada instancia de los metadatos JSON puede tener como máximo un elemento BulkDataURI. No debe haber ningún elemento BulkDataURI duplicado en los metadatos JSON. Los datos en bloque de imágenes comprimidas solo se deben enviar para la etiqueta PixelData y, cuando se envían, la sintaxis de transferencia especificada en la parte de los datos en bloque debe coincidir con el valor del elemento TransferSyntaxUID de la instancia.

Los siguientes tipos de contenido son compatibles con las partes de datos en bloque:

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

Un método alternativo para especificar datos binarios es codificarlo como una cadena InlineBinary codificada en base64. Esto es compatible con todas las etiquetas, excepto PixelData, que debe enviarse como una parte de datos en bloque. Cuando se utilizan objetos InlineBinary en los metadatos JSON, la sintaxis de transferencia que se ha utilizado para la codificación debe especificarse en la parte de tipo de contenido de los metadatos JSON.

El servidor no extrae atributos de macro de descripción de píxel de imagen.

Consulta la guía práctica para crear instancias DICOM a partir de metadatos JSON y archivos JPEG.

Respuesta

En caso de error, se devolverá una etiqueta FailureDetail (0009, 0097) (para respuestas XML) o una etiqueta FailureDetailJSON (0009,1097) (para respuestas JSON) adicionales. La etiqueta FailureDetail proporciona una descripción del error con formato legible para humanos.

Si una instancia DICOM tiene la misma tupla <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> que otra instancia que ya está en el almacén DICOM, se devuelve un error Processing failure con una etiqueta FailureDetail que ya exista.

La respuesta puede estar en formato JSON o XML. Esto se puede controlar mediante los siguientes valores de encabezado de aceptación:

  • application/dicom+xml (predeterminado)
  • application/dicom+json

Códigos de estado

Código Significado
200 (OK) El recurso se ha almacenado correctamente.
400 (Solicitud incorrecta) La solicitud no era válida (por ejemplo, el tipo de contenido o la sintaxis de transferencia no se admitían).
401 (No autorizado) Faltan las credenciales de autenticación en la solicitud.
403 (Permiso denegado) El usuario autenticado no tiene acceso a este recurso (o el recurso no existe).
406 (Not Acceptable) El servidor no admite ninguno de los tipos de contenido multimedia aceptables.
409 (Conflicto) No se ha podido almacenar al menos un recurso (por ejemplo, un archivo DICOM no válido). Consulta la etiqueta FailureDetail en el cuerpo de la respuesta para obtener más información.
429 (Demasiadas solicitudes) El cliente está superando su cuota.
503 (Servicio no disponible) El servidor no está disponible en este momento o la solicitud ha superado el plazo.

Buscar transacción

La transacción de búsqueda es un servicio web RESTful para consultar metadatos de imágenes DICOM.

La API Cloud Healthcare permite buscar estudios, series e instancias.

Parámetros de búsqueda

Es posible buscar elementos mediante las siguientes etiquetas:

  • Estudios:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Serie: todos los términos de búsqueda de nivel de estudio y
    • SeriesInstanceUID
    • Modalidad
  • Instancias: todos los términos de búsqueda a nivel de estudio o serie y
    • SOPInstanceUID

Solo se admite la coincidencia exacta de un solo valor, excepto para StudyDate, que permite las consultas de rango, y PatientName, que admite la coincidencia aproximada.

Se admiten los siguientes parámetros de URL adicionales:

  • fuzzymatching: Si se le asigna el valor true, se aplicará la coincidencia parcial a la etiqueta PatientName. La coincidencia aproximada realizará la tokenización y la normalización tanto del valor de PatientName en la consulta como del valor almacenado. Se producirá una coincidencia si algún token de búsqueda es un prefijo de algún token almacenado. Por ejemplo, si PatientName es "John^Doe", se encontrará una coincidencia con "jo", "Do" y "John Doe". Sin embargo, no coincidirá con "ohn".
  • includefield: se puede asignar a una lista de attributeIDs separados por comas, como IDs de etiquetas DICOM o palabras clave, o bien se puede asignar el valor all para devolver todas las etiquetas disponibles. Para ver una lista de las etiquetas disponibles, consulta Resultados devueltos.

La paginación se admite mediante los parámetros de consulta limit y offset. No hay ningún encabezado de respuesta Warning si no hay más resultados disponibles. Debes ejecutar una consulta adicional para determinar si hay más resultados.

  • limit: número máximo de resultados que se deben devolver, hasta un máximo de 5000 para los estudios o series y de 50.000 para las instancias. El número predeterminado de resultados es 100 para estudios o series y 1000 para instancias.

  • offset: número de resultados que se omitirán al principio, hasta un máximo de 1.000.000.

El desfase de zona horaria desde UTC no es compatible.

Resultados devueltos

La respuesta puede estar en formato JSON o XML. Esto se puede controlar mediante los siguientes valores de encabezado de aceptación:

  • application/dicom+json (predeterminado)
  • multipart/related; type=application/dicom+xml

De forma predeterminada, se devolverán los siguientes atributos:

  • Estudios:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Serie:
    • SpecificCharacterSet
    • Modalidad
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Instancias:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • Filas
    • Columnas
    • BitsAllocated
    • NumberOfFrames

Para includefield=all, se devolverán los atributos predeterminados junto con los siguientes atributos:

  • Estudios:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • Serie:
    • SeriesNumber
    • Lateralidad
    • SeriesDate
    • SeriesTime
  • Instances: todos los atributos presentes en la instancia DICOM, excepto los siguientes.

Las etiquetas de secuencia DICOM que contengan más de 1 MiB de datos aproximadamente no se devolverán en la respuesta de metadatos.

Metadatos incoherentes o no válidos

En el caso de SearchForStudies/SearchForSeries, existe la posibilidad de que los metadatos a nivel de estudio/serie sean incoherentes entre varias instancias. Por ejemplo, dos instancias pueden cargarse con el mismo valor de StudyInstanceUID pero tener diferentes valores de StudyDates. En este caso, el comportamiento de búsqueda no está bien definido. La búsqueda por dicho valor puede funcionar en algunos casos, pero no en otros, y el valor devuelto puede variar según las diferentes llamadas.

Códigos de estado

Código Significado
200 (OK) La carga útil de la respuesta contiene representaciones de todos los recursos de destino.
400 (Solicitud incorrecta) La solicitud no era válida (por ejemplo, los parámetros de consulta no eran válidos).
401 (No autorizado) Faltan las credenciales de autenticación en la solicitud.
403 (Permiso denegado) El usuario autenticado no tiene acceso a este recurso (o el recurso no existe).
406 (Not Acceptable) El servidor no admite ninguno de los tipos de contenido multimedia aceptables.
429 (Demasiadas solicitudes) El cliente está superando su cuota.
503 (Servicio no disponible) El servidor no está disponible en este momento o la solicitud ha superado el plazo.

Eliminación

La API Cloud Healthcare admite los siguientes tipos de acciones de propietario:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Estos tipos utilizan las mismas rutas de solicitud que sus homólogos de WADO-RS (RetrieveStudy, RetrieveSeries y RetrieveInstance, respectivamente). En lugar de una solicitud GET HTTP, se usa una solicitud DELETE. En consecuencia, se eliminan el estudio, la serie o la instancia especificados junto con todos los recursos DICOM que contienen.

Los métodos DeleteStudy y DeleteSeries devuelven una operación de larga duración que elimina todas las instancias del estudio o de la serie. Ten en cuenta que las instancias no se pueden insertar en un estudio o una serie que se esté eliminando mediante una operación hasta que esta se complete.

Consulta la guía práctica sobre operaciones Gestionar operaciones de larga duración.

Una solicitud DeleteInstance correcta devuelve una respuesta vacía.

Códigos de estado

Código Significado
200 (OK) Se ha eliminado el recurso de solicitud.
400 (Solicitud incorrecta) La solicitud no era válida.
401 (No autorizado) Faltan las credenciales de autenticación en la solicitud.
403 (Permiso denegado) El usuario autenticado no tiene acceso a este recurso (o el recurso no existe).
429 (Demasiadas solicitudes) El cliente está superando su cuota.
503 (Servicio no disponible) El servidor no está disponible en este momento o la solicitud ha superado el plazo.

Encabezados de aceptación

Algunos de los métodos anteriores permiten controlar el formato de la respuesta mediante encabezados de aceptación HTTP. La coincidencia de comodines se admite tanto en el nivel superior (por ejemplo, */*) como en el subtipo (por ejemplo, image/*). También se admite la especificación de un valor q para indicar la preferencia relativa. Si no se especifica ningún valor de q en un encabezado Accept, se le asigna el valor predeterminado 1.0.

En caso de que se especifiquen varios encabezados Accept y haya un empate entre los encabezados Accept de mayor preferencia, el servidor elegirá el encabezado Accept. Los clientes no deben depender de la elección del servidor del encabezado Accept en este caso.

Clases SOP admitidas

La API Cloud Healthcare puede ingerir y realizar recuperaciones básicas de todas las clases SOP de DICOM. Para cualquier recuperación que requiera transcodificación entre formatos de imagen, consulta las sintaxis de transferencia admitidas para la transcodificación para ver una lista de las sintaxis de transferencia admitidas.

Versión del diccionario DICOM

La API Cloud Healthcare usa el diccionario DICOM 2025b para analizar las etiquetas de las instancias insertadas y para generar nombres de columna al exportar a BigQuery.

Bulkdata Definition

Al recuperar metadatos, la API Cloud Healthcare excluirá determinadas etiquetas que se definan como bulkdata. En su lugar, estas etiquetas se devolverán junto con los metadatos con un elemento BulkDataURI que permite al usuario recuperar el contenido de estas etiquetas (consulta RetrieveBulkdata). A continuación, se muestra la definición que usa la API Cloud Healthcare:

  • Cualquier etiqueta Pixel Data: (7FE0,0008), (7FE0,0009) y (7FE0,0010).
  • Cualquier etiqueta con un valor de verificación de lectura de OB, OW o UN.
  • Una etiqueta con un valor de retorno de OD, OF, OL u OV que sea superior a 2 KiB.
    • Por motivos de compatibilidad, las etiquetas de las instancias que ya se han insertado en la API Cloud Healthcare se pueden considerar datos masivos si la etiqueta es mayor de 256 B (OF y OL) o 512 B (OD).
  • Una etiqueta con un VR de AT, FD, FL, UL, US, SV o UV y un valor de multiplicidad (VM) superior a 512.
    • Por motivos de versiones anteriores, las etiquetas de las instancias que ya se han ingerido en la API Cloud Healthcare se pueden considerar datos masivos si la VM es superior a 64.

Además, las siguientes etiquetas se consideran datos masivos, pero no tienen BulkDataURIs cuando se devuelven desde métodos de metadatos y el contenido no se puede recuperar mediante RetrieveBulkdata:

  • Una etiqueta con un VR de SQ y un tamaño superior a 1 MiB aproximadamente.