Actualizar y aplicar parches a estudios, series e instancias DICOM

En esta página se explica cómo se pueden actualizar y parchear in situ los estudios, las series y las instancias DICOM en la API Cloud Healthcare. Para obtener información sobre cómo rellenar almacenes de la API Cloud Healthcare con datos DICOM, consulta Usar el estándar DICOMweb.

Actualizar instancias DICOM

Las instancias DICOM se pueden sustituir subiendo una nueva versión del archivo .dcm. Al igual que con storeInstances, se puede usar un archivo de varias partes para actualizar varias instancias a la vez (a menudo para actualizar un estudio o una serie con varias instancias). Una vez que se haya actualizado, la instancia original se sustituirá por completo.

A diferencia de storeInstances, no se pueden actualizar instancias completas con metadatos JSON. Para obtener información sobre las actualizaciones parciales con JSON, consulta Aplicar parches a metadatos DICOM.

Actualizar una instancia se considerará una operación "upsert". Si la instancia existe, se actualizará. Si la instancia no existe, se creará y se insertará en el almacén.

Al insertar una instancia nueva, los valores de SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID y SERIES_INSTANCE_UID se obtienen de los metadatos proporcionados. Los UIDs deben cumplir estos requisitos:

  • Contener solo valores numéricos separados por puntos.
  • No deben contener información médica protegida (PHI).

En el siguiente ejemplo se muestra cómo actualizar una instancia en un almacén DICOM. Para obtener más información, consulta projects.locations.datasets.dicomStores.updateInstances.

curl

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: el ID de tu Google Cloud proyecto
  • LOCATION: la ubicación del conjunto de datos
  • DATASET_ID: el conjunto de datos superior del almacén DICOM
  • DICOM_STORE_ID: el ID del almacén DICOM
  • DICOM_INSTANCE_FILE: la ruta a un archivo de instancia DICOM en tu máquina local que termina con el sufijo .dcm

En el siguiente ejemplo se muestra una solicitud PUT que utiliza curl.

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/dicom" \
    --data-binary @DICOM_INSTANCE_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

El resultado es la siguiente respuesta XML:

Actualizar varias instancias a la vez

En el siguiente ejemplo se muestra cómo actualizar un estudio o una serie DICOM, que consta de varias instancias, mediante un mensaje de varias partes.

curl

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: el ID de tu Google Cloud proyecto
  • LOCATION: la ubicación del conjunto de datos
  • DATASET_ID: el conjunto de datos superior del almacén DICOM
  • DICOM_STORE_ID: el ID del almacén DICOM
  • MULTIPART_FILE: la ruta a un archivo de varias partes en tu máquina local. El archivo contiene varias instancias DICOM, cada una separada por un límite.
  • BOUNDARY: el límite que se usa para separar las instancias DICOM en el archivo de varias partes

En el siguiente ejemplo se muestra una solicitud PUT que utiliza curl.

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: multipart/related; type=application/dicom; boundary=BOUNDARY" \
    --data-binary @MULTIPART_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

El resultado es la siguiente respuesta XML:

Aplicar parches a metadatos DICOM

Puedes añadir, quitar o editar una etiqueta DICOM en el nivel de estudio, serie o instancia. El comportamiento de cada nivel es el siguiente:

En el caso de los parches que devuelven una operación de larga duración, los errores al aplicar el parche a una instancia se registrarán en Cloud Logging. El número de instancias fallidas se devuelve en los metadatos de la operación, junto con un enlace a los registros asociados.

JSON Patch

La sintaxis para editar etiquetas sigue el estándar JSON Patch. Solo se admiten las operaciones add, replace y remove. Puede especificar una etiqueta mediante su palabra clave pública (si la etiqueta es pública) o mediante un identificador hexadecimal de 8 dígitos. Ten en cuenta que todas las rutas de etiquetas deben empezar por /. Cuando add o replace una etiqueta, debes especificar un VR y un valor para la etiqueta, así como el identificador de la etiqueta. Cuando remove una etiqueta, solo tienes que especificar el identificador de la etiqueta.

Se pueden editar las etiquetas de una secuencia, así como sustituir secuencias. Consulta las limitaciones de los parches para saber qué no se admite con los parches. Para especificar una etiqueta dentro de una secuencia, separa la secuencia y la etiqueta secundaria con el índice del elemento y barras invertidas. A continuación, se muestra un ejemplo en el que se add la etiqueta InstanceCreationDate al segundo elemento de ReferencedInstanceSequence (tenga en cuenta que los elementos de secuencia tienen un índice que empieza por 0):

[
  {
    "op": "add",
    "path": "/ReferencedInstanceSequence/1/InstanceCreationDate",
    "value": {
      "vr": "DA",
      "Value": [ "20240501" ]
    }
  }
]

Para añadir una secuencia completa (o sustituir una secuencia completa), el campo value de la entrada JSON Patch debe ser la representación JSON DICOM de una secuencia. Aquí se muestra un ejemplo de cómo añadir la secuencia OtherPatientIDs con dos elementos a una instancia:

[
  {
    "op": "add",
    "path": "/OtherPatientIDs",
    "value": {
      "vr": "SQ",
      "Value": [
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "54321" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital B" ]
          }
        },
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "24680" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital C" ]
          }
        }
      ]
    }
  }
]

Aplicar un parche a una sola instancia

curl

Para editar las etiquetas DICOM de una sola instancia, haz una solicitud PATCH y especifica la siguiente información:

  • PROJECT_ID: el ID de tu Google Cloud proyecto
  • LOCATION: la ubicación del conjunto de datos
  • DATASET_ID: el conjunto de datos superior del almacén DICOM
  • DICOM_STORE_ID: el ID del almacén DICOM
  • STUDY_UID: el UID del estudio de la instancia DICOM
  • SERIES_UID: el UID de la serie de la instancia DICOM
  • INSTANCE_UID: el UID de la instancia DICOM

En el siguiente ejemplo se muestra una solicitud PATCH que utiliza curl.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID/metadata"

Si la solicitud se realiza de forma correcta, el servidor devuelve la respuesta en formato JSON:

{
  "studyUID": "STUDY_UID",
  "seriesUID": "SERIES_UID",
  "instanceUID": "INSTANCE_UID",
  "createTimestamp": "CREATE_TIMESTAMP",
  "metadata": {
    // Full DICOM JSON metadata for the instance after edits applied
  }
}

Aplicar un parche a un estudio o una serie

curl

Para editar las etiquetas DICOM de todas las instancias de un estudio determinado, haz una solicitud PATCH y especifica la siguiente información:

  • PROJECT_ID: el ID de tu Google Cloud proyecto
  • LOCATION: la ubicación del conjunto de datos
  • DATASET_ID: el conjunto de datos superior del almacén DICOM
  • DICOM_STORE_ID: el ID del almacén DICOM
  • STUDY_UID: el UID del estudio DICOM

En el siguiente ejemplo se muestra una solicitud PATCH que utiliza curl.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/metadata"

Si la solicitud se realiza de forma correcta, el servidor devuelve la respuesta en formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

La respuesta contiene un ID de operación. Para hacer un seguimiento del estado de la operación y ver más detalles, usa el método Operation get:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

Si la solicitud se realiza de forma correcta, el servidor devuelve una respuesta con el estado de la operación en formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.dicom.DicomWebService.UpdateStudyMetadata",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "CLOUD_LOGGING_URL",
    "counter": {
      "success": "1" // Number of instances updated in the study
    }
  },
  "done": true,
  "response": {
    "@type": "..."
  }
}

Limitaciones

Se aplican las siguientes limitaciones y comportamientos adicionales al editar etiquetas DICOM:

  • No puedes editar las siguientes etiquetas:
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • Cualquier etiqueta con un número de grupo inferior a "0008"
    • Cualquier etiqueta considerada bulkdata (consulta la definición de bulkdata)
    • Además de la definición anterior, no se puede añadir ninguna etiqueta con un VR de OD, OF, OL, OV, SV o UV mediante patch (ya sea con las operaciones add o replace), independientemente de la longitud.
  • No se puede editar una secuencia que contenga una etiqueta considerada bulkdata.
    • Esto significa que las operaciones replace o remove en una etiqueta de secuencia fallarán si alguna de las etiquetas contenidas en la secuencia original se considera datos masivos.
    • Además, las operaciones replace o add en una etiqueta de secuencia fallarán si alguna de las etiquetas contenidas en la nueva secuencia se considera datos masivos.
  • Si intentas replace o remove una etiqueta que no existe, la API Cloud Healthcare devuelve un error y la edición falla.
  • Si intentas add una etiqueta que ya existe, la operación de edición se comporta del mismo modo que si hubieras llamado a una operación de sustitución. La operación de sustitución sustituye el valor actual de la etiqueta por el nuevo valor especificado en la operación
  • Aunque se pueden añadir, sustituir o quitar secuencias (y también se pueden editar las etiquetas de los elementos de una secuencia), no se pueden añadir, sustituir ni quitar elementos concretos de una secuencia.
    • En la práctica, esto significa que se rechazará cualquier edición con una ruta de etiqueta que termine en un índice (por ejemplo, /ReferencedSeriesSequence/0).
    • Si es necesario cambiar un elemento concreto de una secuencia, sustituya toda la secuencia principal por una copia en la que se hayan aplicado los cambios.