Los almacenes de DICOM dentro de la API de Cloud Healthcare admiten un subconjunto de los servicios web RESTful especificados en el estándar PS3.18 de servicios web (comúnmente conocido como DICOMweb). Específicamente, admiten los servicios y recursos de estudios (antes denominados servicios de WADO-RS, STOW-RS y QIDO-RS).
Además, la API de Cloud Healthcare admite un servicio web de propietario para la eliminación de instancias de DICOM.
La API de Cloud Healthcare no es compatible con el servicio de URI, el servicio de listas de trabajo, el servicio de instancias de que no son de pacientes ni ninguna de las transacciones de capacidades.
Recupera transacción
La transacción de recuperación es un servicio web RESTful para recuperar datos de imágenes de DICOM.
La transacción de recuperación admite la recuperación de los siguientes recursos:
- Recursos de DICOM:
- Estudio
- Serie
- Instance
- Marcos
- Datos masivos
- Recursos de metadatos
- Estudio
- Serie
- Instance
- Recursos procesados
- Instance
- Marcos
No admite recursos de miniaturas.
Consulta Cuotas y límites para obtener detalles sobre las cuotas y los límites de estos métodos.
Estudio/serie/instancias de DICOM
Se admiten los siguientes encabezados de aceptación:
multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1
(predeterminada)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 de DICOM
Además de los encabezados de aceptación anteriores, RetrieveInstance admite los siguientes tipos de contenido de una sola parte para mayor conveniencia:
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=*
Esto no forma parte del estándar oficial de DICOMweb.
Marcos de DICOM
Se admiten los siguientes encabezados de aceptación:
multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1
(predeterminada)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 que el usuario solicite que no se realicen transcodificaciones, por lo que se usará la sintaxis de transferencia del archivo subido. Para application/octet-stream
, los datos masivos se mostrarán en cualquier formato que aparezca en el archivo de DICOM subido.
Recursos procesados
Se admiten los siguientes encabezados de aceptación:
image/jpeg
(predeterminada)image/png
Solo se admite la recuperación de recursos de instancias o marcos.
No se admiten parámetros de URL.
Recursos de metadatos
Se admiten los siguientes encabezados de aceptación:
application/dicom+json
(predeterminada)multipart/related; type=application/dicom+xml
Las etiquetas que se codifican como elementos InlineBinary se codificarán con el orden de bytes de formato little-endian, ya que el parámetro de sintaxis de transferencia no es compatible con los extremos que solicitan recursos de metadatos.
De forma predeterminada, RetrieveMetadata no muestra ningún atributo que tenga una representación de valor de DICOM de OB, OW o UN. Para mostrar BulkDataURIs de etiquetas que coincidan con la definición de Bulkdata de la versión preliminar, usa Preview version
.
Las etiquetas de secuencia de DICOM que contienen más de 1 MiB de datos no se mostrarán en los recursos de metadatos. Esta limitación se aplica solo a los recursos de metadatos. Los recursos de DICOM sí contendrán estas etiquetas.
Recursos de datos masivos (versión preliminar)
Se admiten los siguientes encabezados de aceptación:
multipart/related; type="application/octet-stream"; transfer-syntax=*
(predeterminada)application/octet-stream; transfer-syntax=*
Sintaxis de transferencia admitidas para la transcodificación
En los encabezados de aceptación anteriores, se describe qué tipos de medios y sintaxis de transferencia puedes solicitar desde la API, pero esto no siempre será posible en función de la sintaxis de transferencia del archivo original que se subió. En particular, 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
(Proceso 1 del modelo de referencia JPEG)1.2.840.10008.1.2.4.57
(JPEG Lossless)1.2.840.10008.1.2.4.70
(valor 1 de selección JPEG sin pérdida)1.2.840.10008.1.2.4.90
(solo JPEG 2000 sin pérdida)1.2.840.10008.1.2.4.91
(JPEG 2000)1.2.840.10008.1.2.5
(RLE sin pérdida)
Si el archivo original tiene una sintaxis de transferencia distinta de la de la lista anterior y solicitas la transcodificación a otro formato, se mostrará un error.
La API de Cloud Healthcare no puede transcodificar a JPEG imágenes no monocromáticas con una profundidad de bits mayor que 8. Además, las imágenes con un valor de Bits asignados (0028, 0100) de 1 o que se almacenan en las etiquetas de datos de píxeles de punto flotante (7FE0,0008) o de punto flotante doble (7FE0,0009) solo se pueden transcodificar entre formatos nativos.
Para inhabilitar la transcodificación y recuperar cualquier archivo de la API, puedes configurar transfer-syntax=*
en tu encabezado de aceptación.
Códigos de estado
Code | Significado |
---|---|
200 (OK) | La carga útil de respuesta contiene representaciones de todos los recursos de destino. |
400 (solicitud incorrecta) | La solicitud no era válida (p. ej., los encabezados o los parámetros de consulta eran incorrectos) para los recursos de destino especificados (p. ej., Faltaban datos de píxeles). |
401 (no está autorizado) | A la solicitud le faltan credenciales de autenticación. |
403 (permiso denegado) | El usuario autenticado no tiene acceso a este recurso (o el recurso no existe). |
406 (No es aceptable) | El servidor no admite ninguno de los tipos de medios aceptables. |
429 (demasiadas solicitudes) | El cliente supera su cuota. |
503 (servicio no disponible) | El servidor no está disponible en este momento o la solicitud excedió su fecha límite. |
Transacciones en tienda
La transacción en tienda es un servicio web RESTful para almacenar datos de imágenes de DICOM.
La transacción de tienda acepta archivos binarios de DICOM de la parte 10 directamente o acepta la división de un archivo de DICOM en metadatos (representados en JSON) y datos masivos. Estas 2 versiones tienen una semántica diferente que se describe en las siguientes secciones.
Consulta Cuotas y límites para obtener detalles 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 fuerza ni reemplaza los atributos.
Esta versión acepta todas las clases de sintaxis de transferencia. Solo se realiza una validación mínima del archivo de DICOM para extraer algunos atributos de metadatos clave.
Ten en cuenta que, para mayor conveniencia, la transacción en tienda también acepta una solicitud HTTP de una sola parte con una sola instancia de DICOM que tenga el tipo de contenido application/dicom
. Esto no forma parte del estándar oficial de DICOMweb.
Consulta Almacena una instancia de DICOM para ver la guía práctica asociada.
Solicitudes de datos masivos y de metadatos JSON
Cuando se almacenan instancias mediante metadatos JSON y datos masivos, la primera parte múltiple debe constar de un arreglo JSON de instancias de DICOM.
La primera parte debe tener un tipo de contenido de application/dicom+json; transfer-syntax=TransferSyntaxUID
, en el que TransferSyntaxUID
es la sintaxis de transferencia que se usó para codificar los datos binarios en los objetos InlineBinary.
Si no hay objetos InlineBinary presentes en los metadatos, se puede omitir el parámetro transfer-syntax
.
Los siguientes elementos de DICOM deben estar presentes en todas las instancias de los metadatos JSON:
- SpecificCharacterSet
- TransferSyntaxUID
- SOPClassUID
- StudyInstanceUID
- SeriesInstanceUID
- SOPInstanceUID
El elemento SpecificCharacterSet se debe establecer en ISO_IR 192
y los metadatos JSON se deben codificar en UTF-8 de Unicode. TransferSyntaxUID se puede establecer en cualquier sintaxis de transferencia válida, excepto en las siguientes sintaxis de transferencia que no son compatibles:
1.2.840.10008.1.2.2
(Explicit VR Big Endian)1.2.840.10008.1.2.1.99
(VR Little Endian explícito deflactado)
En los metadatos de JSON, el usuario puede especificar varios BulkDataURI para etiquetas de DICOM con RV de OB, OW o UN. Estos BulkDataURI indican que los datos binarios de la etiqueta que contiene el URI se enviarán en una parte siguiente que tiene el encabezado de ubicación de contenido establecido en BulkDataURI.
Cada instancia de los metadatos JSON puede tener como máximo un BulkDataURI. No debe haber ningún BulkDataURI duplicado en los metadatos de JSON. Los datos masivos comprimidas de imágenes solo se deben enviar para la etiqueta PixelData y, cuando se envían, la sintaxis de transferencia especificada en la parte de los datos masivos debe coincidir con el valor del elemento TransferSyntaxUID de la instancia.
Los siguientes tipos de contenido son compatibles con las partes de los datos masivos:
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 codificarlos como una string codificada en Base64. Esto es compatible con todas las etiquetas, excepto PixelData, que debe enviarse como parte de los datos masivos. Cuando se usan objetos InlineBinary en los metadatos JSON, la sintaxis de transferencia que se usó para la codificación debe especificarse en el tipo de contenido de la parte de los metadatos JSON.
El servidor no obtiene atributos de macro de descripción de píxeles de imágenes.
Consulta Crea instancias de DICOM a partir de metadatos JSON y archivos JPEG para ver la guía práctica asociada.
Respuesta
En caso de error, se mostrará una etiqueta adicional FailureDetail (0009, 0097) (para las respuestas XML) o FailureDetailJSON (0009, 1097) (para las respuestas JSON). En la etiqueta FailureDetail, se proporciona una descripción legible del error.
Si una instancia de DICOM tiene la misma tupla <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID>
que otra instancia que ya está en el almacén de DICOM, se muestra un error de procesamiento con una etiqueta FailureDetail que indica que “ya existe”.
La respuesta puede estar en formato JSON o XML, que se puede controlar mediante los siguientes valores de encabezado de aceptación:
application/dicom+xml
(predeterminada)application/dicom+json
Códigos de estado
Code | Significado |
---|---|
200 (OK) | El recurso se almacenó correctamente. |
400 (solicitud incorrecta) | La solicitud no era válida (p. ej., no se admite la sintaxis de transferencia o el tipo de medio). |
401 (no está autorizado) | A la solicitud le faltan credenciales de autenticación. |
403 (permiso denegado) | El usuario autenticado no tiene acceso a este recurso (o el recurso no existe). |
406 (No es aceptable) | El servidor no admite ninguno de los tipos de medios aceptables. |
409 (Conflicto) | No se almacenó correctamente ni un solo recurso (p. ej., el archivo de DICOM no es válido). Revisa la etiqueta FailureDetail en el cuerpo de la respuesta para obtener más información. |
429 (demasiadas solicitudes) | El cliente supera su cuota. |
503 (servicio no disponible) | El servidor no está disponible en este momento o la solicitud excedió su fecha límite. |
Transacción de búsqueda
La transacción de búsqueda es un servicio web RESTful para consultar metadatos de imágenes de DICOM.
La API de Cloud Healthcare admite la búsqueda de estudios, de series y de instancias.
Parámetros de búsqueda
Se admite la búsqueda mediante las siguientes etiquetas:
- Estudios:
- StudyInstanceUID
- PatientName
- PatientID
- AccessionNumber
- ReferringPhysicianName
- StudyDate
- Serie: todos los términos de búsqueda a nivel de estudio y los siguientes elementos:
- SeriesInstanceUID
- Modalidad
- Instancias: todos los términos de búsqueda a nivel de estudio y de series, y los siguientes elementos:
- SOPInstanceUID
Solo se admite la coincidencia exacta con un único valor, a excepción de StudyDate, que admite consultas de rangos, y PatientName, que admite coincidencias parciales.
Se admiten los siguientes parámetros de URL adicionales:
fuzzymatching
: Si se establece entrue
, se aplicará la coincidencia parcial a la etiqueta PatientName. La coincidencia parcial realizará la asignación de token y la normalización del valor de PatientName en la consulta y el valor almacenado. Si algún token de búsqueda es un prefijo de un token almacenado, coincidirá. Por ejemplo, si PatientName es "John^Doe", entonces "jo", "Do" y "John Doe" coincidirán. Sin embargo, "ohn" no coincidirá.includefield
: Se puede establecer en una lista de IDs de atributos separados por comas, como palabras clave o IDs de las etiquetas de DICOM, o puedes establecerlo en el valorall
para mostrar todas las etiquetas disponibles. Para obtener una lista de las etiquetas disponibles, consulta Resultados mostrados.
La paginación es compatible mediante los parámetros de consulta limit
y offset
. No habrá encabezado de respuesta de advertencia si no hay más resultados disponibles. Debes ejecutar una consulta adicional para determinar si hay más resultados.
limit
: Cantidad máxima de resultados que se deben mostrar, hasta un máximo de 5,000 para estudios o series y de 50,000 para instancias. La cantidad predeterminada de resultados es de 100 para estudios o series y de 1,000 para instancias.offset
: cantidad de resultados que se deben omitir al principio hasta un máximo de 1,000,000.
La compensación de zona horaria de UTC no es compatible.
Resultados mostrados
La respuesta puede estar en formato JSON o XML, que se puede controlar mediante los siguientes valores de encabezado de aceptación:
application/dicom+json
(predeterminada)multipart/related; type=application/dicom+xml
De forma predeterminada, se mostrarán los siguientes atributos:
- Estudios:
- SpecificCharacterSet
- StudyDate
- StudyTime
- AccessionNumber
- InstanceAvailability
- ReferringPhysicianName
- TimezoneOffsetFromUTC
- PatientName
- PatientID
- PatientBirthDate
- PatientSex
- StudyInstanceUID
- StudyID
- Serie:
- SpecificCharacterSet
- Modality
- TimezoneOffsetFromUTC
- SeriesDescription
- SeriesInstanceUID
- PerformedProcedureStepStartDate
- PerformedProcedureStepStartTime
- RequestAttributesSequence
- Instancias:
- SpecificCharacterSet
- SOPClassUID
- SOPInstanceUID
- InstanceAvailability
- TimezoneOffsetFromUTC
- InstanceNumber
- Filas
- Columnas
- BitsAllocated
- NumberOfFrames
Para includefield=all
, se mostrarán los atributos predeterminados junto con los siguientes:
- 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
- Laterality
- SeriesDate
- SeriesTime
- Instancias: todos los atributos presentes en la instancia de DICOM, excepto las siguientes excepciones.
De forma predeterminada, searchForInstances
no muestra ningún atributo que tenga una representación de valor de DICOM de OB, OW o UN. Para mostrar BulkDataURIs para etiquetas que coincidan con la definición de Bulkdata de la versión preliminar, usa searchForInstances
de la versión preliminar.
Las etiquetas de secuencia de DICOM que contienen más de 1 MiB de datos no se mostrarán en la respuesta de metadatos.
Metadatos incoherentes o no válidos
En el caso de SearchForStudies y SearchForSeries, existe la posibilidad de que haya metadatos incoherentes a nivel de estudio o serie en varias instancias. Por ejemplo, se podrían subir dos instancias con el mismo StudyInstanceUID, pero con StudyDates diferentes. En este caso, el comportamiento de búsqueda no está bien definido. La búsqueda mediante ese valor puede funcionar en algunos casos, pero no en otros, y el valor que se muestra puede variar en las diferentes llamadas.
Códigos de estado
Code | Significado |
---|---|
200 (OK) | La carga útil de respuesta contiene representaciones de todos los recursos de destino. |
400 (solicitud incorrecta) | La solicitud no era válida (p. ej., los parámetros de búsqueda no eran válidos). |
401 (no está autorizado) | A la solicitud le faltan credenciales de autenticación. |
403 (permiso denegado) | El usuario autenticado no tiene acceso a este recurso (o el recurso no existe). |
406 (No es aceptable) | El servidor no admite ninguno de los tipos de medios aceptables. |
429 (demasiadas solicitudes) | El cliente supera su cuota. |
503 (servicio no disponible) | El servidor no está disponible en este momento o la solicitud excedió su fecha límite. |
Eliminación
La API de Cloud Healthcare admite los siguientes tipos de acciones de propietario:
- DeleteStudy
- DeleteSeries
- DeleteInstance
Estas usan las mismas rutas de solicitud que sus contrapartes de WADO-RS (RetrieveStudy, RetrieveSeries y RetrieveInstance, respectivamente). En lugar de una solicitud GET
HTTP, se usa una solicitud DELETE
. El efecto de esto es que el estudio, la serie o la instancia especificados se borran junto con todos los recursos de DICOM que contiene.
Los métodos DeleteStudy
y DeleteSeries
muestran una operación de larga duración que borra todas las instancias del estudio o la serie. Ten en cuenta que las instancias no se pueden insertar en un estudio o serie que estén siendo borrados por una operación hasta que se complete la operación.
Consulta Administra operaciones de larga duración para obtener una guía práctica sobre las operaciones.
Una solicitud DeleteInstance
exitosa muestra una respuesta vacía.
Códigos de estado
Code | Significado |
---|---|
200 (OK) | Se borró el recurso de la solicitud. |
400 (solicitud incorrecta) | La solicitud no era válida. |
401 (no está autorizado) | A la solicitud le faltan credenciales de autenticación. |
403 (permiso denegado) | El usuario autenticado no tiene acceso a este recurso (o el recurso no existe). |
429 (demasiadas solicitudes) | El cliente supera su cuota. |
503 (servicio no disponible) | El servidor no está disponible en este momento o la solicitud excedió su fecha límite. |
Acepta encabezados
Algunos de los métodos anteriores proporcionan la capacidad de controlar el formato de respuesta mediante encabezados de aceptación HTTP. La coincidencia con comodines se admite tanto en el nivel superior (p. ej., */*
) como en el de subtipo (p. ej., image/*
). También se admite la especificación de un valor q
para indicar una preferencia relativa. Si no se especifica un valor q
para un encabezado de aceptación, este se establecerá en el valor predeterminado de 1.0.
En el caso de que se especifiquen varios encabezados de aceptación y haya un vínculo entre los encabezados de aceptación de mayor preferencia, el servidor elegirá el encabezado de aceptación. En este caso, los clientes no deben depender de la elección del servidor para el encabezado de aceptación.
Clases de SOP compatibles
La API de Cloud Healthcare puede transferir y realizar recuperaciones básicas de todas las clases de SOP de DICOM. Para cualquier recuperación que requiera transcodificación entre formatos de imagen, consulta Sintaxis de transferencia admitidas para la transcodificación a fin de obtener una lista de las sintaxis de transferencia compatibles.
Versión del diccionario de DICOM
La API de Cloud Healthcare usa el diccionario DICOM 2022d para analizar las etiquetas de las instancias transferidas.
Para exportar a BigQuery, la API de Cloud Healthcare usa el diccionario DICOM 2024c para generar nombres de columnas.
Definición de etiquetas de datos masivos (versión preliminar)
Cuando recuperes metadatos con métodos de vista previa, la API de Cloud Healthcare excluirá ciertas etiquetas que se definen como bulkdata. En su lugar, estas etiquetas se mostrarán junto con metadatos con un BulkDataURI que le permite al usuario recuperar el contenido de estas etiquetas (consulta RetrieveBulkdata
). La siguiente es la definición que usa la API de Cloud Healthcare:
- Cualquier etiqueta de datos de píxeles: (7FE0,0008), (7FE0,0009) (7FE0,0010).
- Cualquier etiqueta con una RV de OB, OW o UN.
- Una etiqueta con una RV de OD, OF o OL que sea mayor que 2 KiB
- Por motivos heredados, las etiquetas de instancias que ya se transfirieron a la API de Cloud Healthcare se pueden considerar datos masivos si la etiqueta es mayor que 256 B (OF y OL) o 512 B (OD).
- Una etiqueta con un VR de AT, FD, FL, UL o US y una Multiplicidad de valores (VM) superior a 512.
- Por motivos heredados, las etiquetas de instancias que ya se transfirieron a la API de 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 muestran desde métodos de metadatos, y el contenido no se puede recuperar con RetrieveBulkdata
:
- Una etiqueta con un VR de SQ y un tamaño superior a aproximadamente 1 MiB.