Actualiza y aplica parches a instancias, estudios y series de DICOM

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

Actualiza instancias de DICOM

Las instancias de DICOM se pueden reemplazar subiendo una nueva versión del archivo .dcm. Al igual que storeInstances, también 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). Después de la actualización, la instancia original se reemplazará por completo.

A diferencia de storeInstances, la actualización de una instancia completa no se puede realizar con metadatos JSON. Para obtener información sobre las actualizaciones parciales con JSON, consulta Aplica parches a los metadatos de DICOM.

La actualización de una instancia se tratará como una "inserción-actualización". Si la instancia existe, se actualizará. Si la instancia no existe, se creará y se insertará en el almacén.

Cuando se inserta una instancia nueva, los valores de SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID y SERIES_INSTANCE_UID se recopilan de los metadatos proporcionados. Los UIDs deben cumplir con los siguientes requisitos:

  • Solo deben contener valores numéricos separados por puntos.
  • No contener información de salud protegida (PHI)

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

curl

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

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

En el siguiente ejemplo, se muestra una solicitud PUT mediante 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 en XML:

Cómo actualizar varias instancias a la vez

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

curl

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

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

En el siguiente ejemplo, se muestra una solicitud PUT mediante 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 en XML:

Aplica parches a los metadatos de DICOM

Puedes agregar, quitar o editar una etiqueta de DICOM a nivel del estudio, la serie o la instancia. El comportamiento para cada uno de los niveles es el siguiente:

En el caso de los parches que devuelven una operación de larga duración, cualquier error al aplicar el parche a una instancia se registrará en Cloud Logging. La cantidad de instancias con errores se muestra en los metadatos de la operación, junto con un vínculo a los registros asociados.

Parche de JSON

La sintaxis para editar etiquetas sigue el estándar de parche JSON. Solo se admiten las operaciones add, replace y remove. Puedes especificar una etiqueta con 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 acceso a las etiquetas deben tener el prefijo /. Cuando add o replace una etiqueta, debes especificar una RV y un valor para la etiqueta junto con el identificador de etiqueta. Cuando remove una etiqueta, solo necesitas especificar el identificador de la etiqueta.

Se admite la edición de etiquetas dentro de una secuencia, así como el reemplazo de secuencias. Consulta las limitaciones de la aplicación de parches para saber qué no se admite con la aplicación de parches. Para especificar una etiqueta dentro de una secuencia, separa la secuencia y la etiqueta secundaria con el índice del elemento y barras inversas. Este es un ejemplo en el que se add la etiqueta InstanceCreationDate al 2º elemento de ReferencedInstanceSequence (ten en cuenta que los elementos de secuencia se indexan a partir de 0):

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

Para agregar una secuencia completa (o reemplazar una secuencia completa), el campo value de la entrada de JSON Patch debe ser la representación JSON de DICOM de una secuencia. A continuación, se muestra un ejemplo de cómo agregar la secuencia OtherPatientIDs con 2 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" ]
          }
        }
      ]
    }
  }
]

Aplica parches a una sola instancia

curl

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

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

En el siguiente ejemplo, se muestra una solicitud PATCH mediante 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 tiene éxito, se mostrará la respuesta en formato JSON en el servidor:

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

Aplica parches a un estudio o una serie

curl

A fin de editar las etiquetas de DICOM para todas las instancias en un estudio determinado, realiza una solicitud PATCH y especifica la siguiente información:

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

En el siguiente ejemplo, se muestra una solicitud PATCH mediante 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 tiene éxito, se mostrará la respuesta en formato JSON en el servidor:

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

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

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 es exitosa, el servidor mostrará 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

Las siguientes limitaciones y comportamientos adicionales se aplican cuando se editan etiquetas de 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 que se considere bulkdata (consulta la definición de bulkdata)
    • Además de la definición anterior, no se puede agregar ninguna etiqueta con un VR de OD, OF, OL, OV, SV o UV con patch (ya sea con operaciones de add o replace), independientemente de la longitud.
  • No se puede editar una secuencia que contiene una etiqueta considerada como bulkdata.
    • Esto significa que las operaciones replace o remove en una etiqueta de secuencia fallarán si alguna de las etiquetas incluidas en la secuencia original se considera bulkdata.
    • Además, fallará cualquier operación replace o add en una etiqueta de secuencia si alguna de las etiquetas incluidas en la secuencia nueva se considera bulkdata.
  • Si intentas replace o remove una etiqueta que no existe, la API de Cloud Healthcare muestra un error y falla la edición.
  • Si intentas add una etiqueta que ya existe, la operación de edición se comporta igual que si hubieras llamado a una operación de reemplazo. La operación de reemplazo sustituye el valor existente de la etiqueta por el valor nuevo especificado en la operación.
  • Si bien se pueden agregar, reemplazar o quitar secuencias (y también se pueden editar las etiquetas dentro de los elementos de una secuencia), no se pueden agregar, reemplazar ni quitar elementos individuales de una secuencia.
    • En la práctica, esto significa que se rechazará cualquier edición con una ruta de acceso de etiqueta que termine en un índice (por ejemplo, /ReferencedSeriesSequence/0).
    • Si es necesario realizar cambios en un elemento individual de una secuencia, reemplaza toda la secuencia principal por una copia en la que se hayan aplicado los cambios.