DICOM-Studien, -Serien und -Instanzen aktualisieren und patchen

Auf dieser Seite wird erläutert, wie DICOM-Studien, ‑Serien und ‑Instanzen in der Cloud Healthcare API aktualisiert und direkt gepatcht werden können. Informationen dazu, wie Sie Speicher in der Cloud Healthcare API mit DICOM-Daten füllen, finden Sie unter DICOMweb-Standard verwenden.

DICOM-Instanzen aktualisieren

DICOM-Instanzen können ersetzt werden, indem Sie eine neue Version der .dcm-Datei hochladen. Ähnlich wie bei storeInstances kann eine mehrteilige Datei auch verwendet werden, um mehrere Instanzen gleichzeitig zu aktualisieren (häufig zum Aktualisieren einer Studie oder Serie mit mehreren Instanzen). Nach der Aktualisierung wird die ursprüngliche Instanz vollständig ersetzt.

Im Gegensatz zu storeInstances kann eine vollständige Instanz nicht mit JSON-Metadaten aktualisiert werden. Informationen zu Teilaktualisierungen mit JSON finden Sie unter DICOM-Metadaten patchen.

Das Aktualisieren einer Instanz wird als „Upsert“ behandelt. Wenn die Instanz vorhanden ist, wird sie aktualisiert. Wenn die Instanz nicht vorhanden ist, wird sie erstellt und in den Speicher eingefügt.

Beim Einfügen einer neuen Instanz werden die Werte SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID und SERIES_INSTANCE_UID aus den bereitgestellten Metadaten erfasst. UIDs müssen die folgenden Anforderungen erfüllen:

  • Er darf nur numerische Werte enthalten, die durch Punkte getrennt sind.
  • Sie dürfen keine geschützten Gesundheitsdaten (Protected Health Information, PHI) enthalten.

Das folgende Beispiel zeigt, wie Sie eine Instanz in einem DICOM-Speicher aktualisieren. Weitere Informationen finden Sie unter projects.locations.datasets.dicomStores.updateInstances.

curl

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: die ID Ihres Google Cloud -Projekts
  • LOCATION ist der Standort des Datasets
  • DATASET_ID ist das übergeordnete Dataset des DICOM-Speichers
  • DICOM_STORE_ID: die ID des DICOM-Speichers
  • DICOM_INSTANCE_FILE: der Pfad zu einer DICOM-Instanzdatei auf Ihrem lokalen Computer, die mit dem Suffix .dcm endet.

Das folgende Beispiel zeigt eine PUT-Anfrage mit 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"

Die Ausgabe ist die folgende XML-Antwort:

Mehrere Instanzen gleichzeitig aktualisieren

Im folgenden Beispiel wird gezeigt, wie Sie eine DICOM-Studie oder ‑Serie mit mehreren Instanzen mithilfe einer mehrteiligen Nachricht aktualisieren.

curl

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: die ID Ihres Google Cloud -Projekts
  • LOCATION ist der Standort des Datasets
  • DATASET_ID ist das übergeordnete Dataset des DICOM-Speichers
  • DICOM_STORE_ID: die ID des DICOM-Speichers
  • MULTIPART_FILE: der Pfad zu einer Multipart-Datei auf Ihrem lokalen Rechner. Die Datei enthält mehrere DICOM-Instanzen, die jeweils durch eine Begrenzung getrennt sind.
  • BOUNDARY: Die Begrenzung, die zum Trennen der DICOM-Instanzen in der Multipart-Datei verwendet wird

Das folgende Beispiel zeigt eine PUT-Anfrage mit 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"

Die Ausgabe ist die folgende XML-Antwort:

DICOM-Metadaten patchen

Sie können ein DICOM-Tag auf Studien-, Serien- oder Instanzebene hinzufügen, entfernen oder bearbeiten. Das Verhalten für jede Ebene sieht folgendermaßen aus:

Bei Patches, die einen Vorgang mit langer Ausführungszeit zurückgeben, werden alle Fehler beim Anwenden des Patches auf eine Instanz in Cloud Logging protokolliert. Die Anzahl der fehlgeschlagenen Instanzen wird in den Vorgangsmetadaten zusammen mit einem Link zu den zugehörigen Logs zurückgegeben.

JSON Patch

Die Syntax für die Tag-Bearbeitung entspricht dem JSON-Patch-Standard. Es werden nur die Vorgänge add, replace und remove unterstützt. Sie können ein Tag mit seinem öffentlichen Schlüsselwort (sofern das Tag öffentlich ist) oder einer achtstelligen Hexadezimal-ID angeben. Beachten Sie, dass allen Tag-Pfaden das Präfix / vorangestellt werden muss. Wenn Sie ein Tag add oder replace, müssen Sie neben der Tag-ID eine VR und einen Wert für das Tag angeben. Wenn Sie ein Tag remove, müssen Sie nur die Tag-ID angeben.

Das Bearbeiten von Tags in einer Sequenz wird unterstützt, ebenso wie das Ersetzen von Sequenzen. Informationen dazu, was mit dem Patch nicht unterstützt wird, finden Sie unter Patch-Einschränkungen. Wenn Sie ein Tag innerhalb einer Sequenz angeben möchten, trennen Sie die Sequenz und das untergeordnete Tag durch den Elementindex und Backslashes. Hier ist ein Beispiel, in dem das Tag InstanceCreationDate dem zweiten Element von ReferencedInstanceSequence zugewiesen wird (Sequenzelemente sind 0-indexiert):add

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

Wenn Sie eine vollständige Sequenz hinzufügen oder ersetzen möchten, muss das Feld value des JSON-Patch-Eintrags die DICOM-JSON-Darstellung einer Sequenz sein. Hier ist ein Beispiel für das Hinzufügen der OtherPatientIDs-Sequenz mit zwei Elementen zu einer Instanz:

[
  {
    "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" ]
          }
        }
      ]
    }
  }
]

Einzelne Instanz patchen

curl

Wenn Sie die DICOM-Tags für eine einzelne Instanz bearbeiten möchten, senden Sie eine PATCH-Anfrage und geben Sie die folgenden Informationen an:

  • PROJECT_ID: die ID Ihres Google Cloud -Projekts
  • LOCATION ist der Standort des Datasets
  • DATASET_ID ist das übergeordnete Dataset des DICOM-Speichers
  • DICOM_STORE_ID: die ID des DICOM-Speichers
  • STUDY_UID: die Studien-UID der DICOM-Instanz
  • SERIES_UID: die Serien-UID der DICOM-Instanz
  • INSTANCE_UID: die Instanz-UID der DICOM-Instanz

Das folgende Beispiel zeigt eine PATCH-Anfrage mit 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"

Wenn die Anfrage erfolgreich ist, gibt der Server die Antwort im JSON-Format zurück:

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

Studie oder Serie patchen

curl

Um die DICOM-Tags für alle Instanzen in einer bestimmten Studie zu bearbeiten, senden Sie eine PATCH-Anfrage und geben Sie die folgenden Informationen an:

  • PROJECT_ID: die ID Ihres Google Cloud -Projekts
  • LOCATION ist der Standort des Datasets
  • DATASET_ID ist das übergeordnete Dataset des DICOM-Speichers
  • DICOM_STORE_ID: die ID des DICOM-Speichers
  • STUDY_UID: die Studien-UID der DICOM-Studie

Das folgende Beispiel zeigt eine PATCH-Anfrage mit 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"

Wenn die Anfrage erfolgreich ist, gibt der Server die Antwort im JSON-Format zurück:

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

Die Antwort enthält eine Vorgangs-ID. Mit der Methode Operation get können Sie den Status des Vorgangs verfolgen und weitere Details anzeigen:

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"

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort mit dem Status des Vorgangs im JSON-Format zurück:

{
  "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": "..."
  }
}

Beschränkungen

Beim Bearbeiten von DICOM-Tags gelten die folgenden Einschränkungen und zusätzlichen Verhaltensweisen:

  • Folgende Tags können nicht bearbeitet werden:
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • Alle Tags mit einer Gruppennummer unter „0008“
    • Alle Tags, die als „bulkdata“ gelten (siehe Definition von „bulkdata“)
    • Zusätzlich zur obigen Definition kann kein Tag mit einem VR von OD, OF, OL, OV, SV oder UV mit patch (entweder add- oder replace-Vorgänge) hinzugefügt werden, unabhängig von der Länge.
  • Eine Sequenz, die ein Tag enthält, das als Bulk-Daten betrachtet wird, kann nicht bearbeitet werden.
    • Das bedeutet, dass replace- oder remove-Vorgänge für ein Sequenz-Tag fehlschlagen, wenn eines der im ursprünglichen Sequenz-Tag enthaltenen Tags als „bulkdata“ eingestuft wird.
    • Außerdem schlagen alle replace- oder add-Vorgänge für ein Sequenz-Tag fehl, wenn eines der Tags in der neuen Sequenz als Bulk-Daten betrachtet wird.
  • Wenn Sie versuchen, ein nicht vorhandenes Tag zu replace oder remove, gibt die Cloud Healthcare API einen Fehler zurück und die Bearbeitung schlägt fehl.
  • Wenn Sie versuchen, ein Tag zu add, das bereits vorhanden ist, verhält sich der Bearbeitungsvorgang genauso, als hätten Sie einen Ersetzungsvorgang aufgerufen. Der Ersetzungsvorgang ersetzt den vorhandenen Wert des Tags durch den neuen, im Vorgang angegebenen Wert.
  • Sequenzen können hinzugefügt, ersetzt oder entfernt werden. Tags in Elementen einer Sequenz können ebenfalls bearbeitet werden. Einzelne Elemente in einer Sequenz können jedoch nicht hinzugefügt, ersetzt oder entfernt werden.
    • In der Praxis bedeutet das, dass alle Änderungen mit einem Tag-Pfad, der mit einem Index endet, abgelehnt werden (z. B. /ReferencedSeriesSequence/0).
    • Wenn Änderungen an einem einzelnen Element in einer Sequenz erforderlich sind, ersetzen Sie die gesamte übergeordnete Sequenz durch eine Kopie, in der die Änderungen vorgenommen wurden.