DICOM-Konformitätserklärung

DICOM-Speicher in der Cloud Healthcare API unterstützen einen Teil der RESTful-Webdienste, die im Standard DICOM PS3.18-Web Services (allgemein als DICOMweb bezeichnet) angegeben sind. Sie unterstützen insbesondere die Studien-Dienste und -Ressourcen (früher als WADO-RS-, STOW-RS- und QIDO-RS-Dienste bezeichnet).

Weiter unterstützt die Cloud Healthcare API einen proprietären Webdienst zum Löschen von DICOM-Instanzen.

Die Cloud Healthcare API unterstützt weder den URI-Dienst noch den Arbeitslistendienst, den Nicht-Patienten-Instanzdienst oder eine der Capabilities-Transaktionen.

Transaktion abrufen

Der Vorgang Transaktion abrufen ist ein RESTful-Webdienst zum Abrufen von DICOM-Bilddaten.

Die Abruf-Transaktion unterstützt das Abrufen der folgenden Ressourcen:

  • DICOM-Ressourcen:
    • Studie
    • Reihe
    • Instanz
    • Frames
    • Bulkdata
  • Metadaten-Ressourcen
    • Studie
    • Reihe
    • Instanz
  • Gerenderte Ressourcen
    • Instanz
    • Frames

Thumbnail-Ressourcen werden nicht unterstützt.

Einzelheiten zu Kontingenten und Limits für diese Methoden finden sich unter Kontingente und Limits.

DICOM-Studie/-Serie/-Instanzen

Die folgenden Accept-Header werden unterstützt:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (Standard)
  • 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=*

DICOM-Instanzen

Zusätzlich zu den oben genannten Accept-Headern unterstützt RetrieveInstance der Einfachheit halber einteilige Inhaltstypen:

  • 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=*

Dies ist nicht Teil des offiziellen DICOMweb-Standards.

DICOM-Frames

Die folgenden Accept-Header werden unterstützt:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (Standard)
  • 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"

Mit einer Transfersyntax des Typs * kann der Nutzer anfordern, dass keine Transcodierung erfolgt. Entsprechend wird die Transfersyntax der hochgeladenen Datei verwendet. Mit application/octet-stream werden die Bulk-Daten in dem Format zurückgegeben, in dem sie in der hochgeladenen DICOM-Datei angezeigt werden.

Gerenderte Ressourcen

Die folgenden Accept-Header werden unterstützt:

  • image/jpeg (Standard)
  • image/png

Nur das Abrufen von Instanz- oder Frame-Ressourcen wird unterstützt.

URL-Parameter werden nicht unterstützt.

Metadaten-Ressourcen

Die folgenden Accept-Header werden unterstützt:

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

RetrieveMetadata gibt kein Attribut zurück, das eine DICOM-Wertdarstellung von OB, OD, OF, OL, OW oder UN hat.

In den Metadaten werden BulkDataURIs nicht zurückgegeben.

Bulkdata-Ressourcen

Die folgenden Accept-Header werden unterstützt:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1
  • 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"

Nur das Abrufen von PixelData wird unterstützt.

Unterstützte Transfersyntaxen für die Transcodierung

Die oben genannten Accept-Header beschreiben, welche Medientypen und Übertragungssyntaxen Sie von der API anfordern können. Je nach Übertragungssyntax der hochgeladenen Originaldatei ist dies jedoch nicht immer möglich. Insbesondere ist die Transcodierung nur mit folgenden Übertragungssyntaxen möglich:

  • 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 (verlustfreies JPEG)
  • 1.2.840.10008.1.2.4.70 (verlustfreies JPEG Auswahlwert 1)
  • 1.2.840.10008.1.2.4.90 (nur verlustfreies JPEG 2000)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (verlustfreies RLE)

Wenn die ursprüngliche Datei eine andere Übertragungssyntax als die in der obigen Liste aufweist und Sie die Transcodierung in ein anderes Format anfordern, wird ein Fehler zurückgegeben.

Wenn Sie die Transcodierung deaktivieren und beliebige Dateien von der API abrufen möchten, können Sie im Accept-Header transfer-syntax=* festlegen.

Statuscodes

Code Bedeutung
200 (OK) Die Antwortnutzlast enthält Darstellungen für alle Zielressourcen.
400 (Bad Request) Die Anfrage war ungültig (z. B. fehlerhafte Abfrageparameter oder Header) für die angegebene(n) Zielressource(n) (z. B. fehlende Pixeldaten).
401 (Unauthorized) Die Anfrage enthält keine Anmeldedaten für die Authentifizierung.
403 (Permission Denied) Der authentifizierte Nutzer hat keinen Zugriff auf diese Ressource oder die Ressource existiert nicht.
406 (Not Acceptable) Der Server unterstützt keinen der zulässigen Medientypen.
429 (Too Many Requests) Der Client hat sein Kontingent überschritten.
503 (Service Unavailable) Der Server ist derzeit nicht verfügbar oder die Anfrage hat das Zeitlimit überschritten.

Speichertransaktion

Die Speichertransaktion ist ein RESTful-Webdienst zum Speichern von DICOM-Bilddaten.

Die Speichertransaktion akzeptiert entweder direkt 10 DICOM-Binärdateien oder die Aufteilung einer DICOM-Datei in Metadaten (im JSON-Format) und Bulk-Daten. Diese beiden Versionen nutzen abweichende Semantiken, die in folgenden Abschnitten beschrieben werden.

Einzelheiten zu Kontingenten und Limits für diese Methode finden sich unter Kontingente und Limits.

DICOM Part 10-Binärdateien

Folgende Content-Typen werden unterstützt:

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

Der Server erzwingt oder ersetzt Attribute nicht.

Diese Version akzeptiert alle Transfer-Syntaxen und SOP-Klassen. Zum Extrahieren mancher Schlüsselmetadaten-Attribute wird nur eine minimale Validierung der DICOM-Datei durchgeführt.

Beachten Sie, dass die Store-Transaktion der Einfachheit halber auch einzelne Teil-HTTP-Anfragen mit einer einzigen DICOM-Instanz mit dem Inhaltstyp application/dicom akzeptiert. Dies ist nicht Teil des offiziellen DICOMweb-Standards.

Informationen zur zugehörigen Anleitung finden sich unter DICOM-Instanz speichern.

JSON-Metadaten- und Bulk-Datenanfragen

Wenn Instanzen unter Verwendung von JSON-Metadaten und Bulk-Daten gespeichert werden, muss der erste mehrteilige Teil aus einem JSON-Array von DICOM-Instanzen bestehen.

Der erste Teil muss den Inhaltstyp application/dicom+json; transfer-syntax=TransferSyntaxUID haben, wobei TransferSyntaxUID die Übertragungssyntax ist, die zum Codieren von Binärdaten in InlineBinary-Objekten verwendet wurde. Wenn in den Metadaten keine InlineBinary-Objekte vorhanden sind, kann der Parameter transfer-syntax weggelassen werden.

Folgende DICOM-Elemente müssen in jeder Instanz in den JSON-Metadaten vorhanden sein:

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

Das Element SpecificCharacterSet muss auf ISO_IR 192 gesetzt werden und die JSON-Metadaten müssen in Unicode-UTF-8 codiert sein. Mit der TransferSyntaxUID können Sie eine beliebige gültige Übertragungssyntax festlegen, mit Ausnahme folgender nicht unterstützter Übertragungssyntaxen:

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

Inn den JSON-Metadaten können Nutzer mehrere BulkDataURIs für DICOM-Tags mit VRs von OB, OW oder UN angeben. Diese BulkDataURIs geben an, dass die Binärdaten für das Tag, das den URI enthält, in einem folgenden Teil gesendet werden, in dem der Content-Location-Header auf die BulkDataURI festgelegt ist.

Jede Instanz in den JSON-Metadaten darf höchstens einen BulkDataURI haben. Die JSON-Metadaten dürfen keine doppelten BulkDataURIs enthalten. Komprimierte Bulk-Imagedaten dürfen nur für das PixelData-Tag gesendet werden. Beim Senden muss die im Bulk-Datenteil angegebene Transfersyntax mit dem Wert des Elements TransferSyntaxUID der Instanz übereinstimmen.

Die folgenden Inhaltstypen werden für Bulk-Datenteile unterstützt:

  • 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

Eine alternative Methode zur Angabe von Binärdaten ist die Codierung als InlineBinary-Base64-codierter String. Dies wird für alle Tags außer PixelData unterstützt, die als Bulk-Datenteil gesendet werden müssen. Wenn InlineBinary-Objekte in den JSON-Metadaten verwendet werden, muss die für die Codierung verwendete Übertragungssyntax im Content-Type des JSON-Metadatenteils angegeben werden.

Der Server leitet keine Makro-Attribute für Beschreibungen von Bildpixeln ab.

Eine entsprechende Anleitung finden Sie unter DICOM-Instanzen aus JSON-Metadaten und JPEG-Bildern erstellen.

Antwort

Bei einem Fehler wird entweder das zusätzliche Tag FailureDetail (0009, 0097; für XML-Antworten) oder das FailureDetailJSON-Tag (0009, 1097; für JSON-Antworten) zurückgegeben. Das FailureDetail-Tag enthält eine von Menschen lesbare Beschreibung des Fehlers.

Wenn im DICOM-Speicher bereits eine identische DICOM-Instanz vorhanden ist, wird ein WarningReason-Tag (0008, 1196) mit dem Statuscode 45070 zurückgegeben. Darauf folgt entweder ein WarningReason-Tag (0009, 0096) (für XML-Antworten) oder ein WarningReasonJSON-Tag (0009, 1096) (für JSON-Antworten). WarningReason enthält eine für Menschen lesbare Beschreibung der Warnung. Wenn eine DICOM-Instanz nicht mit einer vorhandenen Instanz identisch ist, aber dasselbe Tupel <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> wie eine im DICOM-Speicher hat, wird ein Verarbeitungsfehler mit einem "bereits vorhandenen"-FailureDetail-Tag zurückgegeben.

Die Antwort kann im JSON- oder XML-Format vorliegen, das über die folgenden Werte im Accept-Header gesteuert werden kann:

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

Statuscodes

Code Bedeutung
200 (OK) Die Ressource wurde erfolgreich gespeichert.
400 (Bad Request) Die Anfrage war ungültig (z. B. nicht unterstützter Medientyp oder Übertragungssyntax).
401 (Unauthorized) Die Anfrage enthält keine Anmeldedaten für die Authentifizierung.
403 (Permission Denied) Der authentifizierte Nutzer hat keinen Zugriff auf diese Ressource oder die Ressource existiert nicht.
406 (Not Acceptable) Der Server unterstützt keinen der zulässigen Medientypen.
409 (Conflict) Mindestens eine Ressource wurde nicht erfolgreich gespeichert (Beispiel: ungültige DICOM-Datei). Weitere Informationen finden sich im FailureDetail-Tag im Antworttext.
429 (Too Many Requests) Der Client hat sein Kontingent überschritten.
503 (Service Unavailable) Der Server ist derzeit nicht verfügbar oder die Anfrage hat das Zeitlimit überschritten.

Suchtransaktion

Die Suchtransaktion ist ein RESTful-Webdienst zum Abfragen von DICOM-Imaging-Metadaten.

Mit der Cloud Healthcare API können Sie Studien, Serien und Instanzen suchen.

Suchparameter

Die Suche mit folgenden Tags wird unterstützt:

  • Studien:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Serie: Alle Suchbegriffe auf Studienebene und
    • SeriesInstanceUID
    • Modalität
  • Instanzen: alle Suchbegriffe auf Studien-/Serienebene und
    • SOPInstanceUID

Es wird nur die exakte Übereinstimmung eines einzelnen Werts unterstützt, mit Ausnahme von StudyDate, das Bereichsabfragen unterstützt, und PatientName, das ungenaue Übereinstimmungen unterstützt.

Folgende zusätzliche URL-Parameter werden unterstützt:

  • fuzzymatching: Mit der Einstellung true wird das Fuzzy-Matching für das Tag PatienName angewendet. Das Fuzzy-Matching führt eine Tokenisierung und Normalisierung des Werts PatientenName in der Abfrage und im gespeicherten Wert durch. Eine Übereinstimmung wird festgestellt, wenn ein Such-Token das Präfix eines gespeicherten Tokens ist. Beispiel: Ist PatientName "John^Doe", so führen "jo", "Do" und "John Doe" zu Übereinstimmungen. "ohn" bedingt dagegen keine Übereinstimmung.
  • includefield: Kann auf eine durch Kommas getrennte Liste von Attribut-IDs, darunter DICOM-Tag-IDs oder Keywords, oder auf den Wert all eingestellt werden. Letztere Einstellung gibt alle verfügbaren Tags zurück. Eine Liste der verfügbaren Tags findt sich unter Zurückgegebene Ergebnisse.

Paging wird mit den Abfrageparametern limit und offset unterstützt. Es ist kein Warnungsheader vorhanden, wenn keine weiteren Ergebnisse verfügbar sind. Sie müssen eine zusätzliche Abfrage ausführen, um festzustellen, ob weitere Ergebnisse vorliegen.

  • limit: Maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen, maximal 5.000 für Studien/Serien und 50.000 für Instanzen. Die Standardanzahl an Ergebnissen beträgt 100 für Studien/Serien und 1.000 für Instanzen.

  • offset: Anzahl der anfangs zu überspringenden Ergebnisse, maximal 1.000.000.

Zeitzonenunterschiede von UTC werden nicht unterstützt.

Zurückgegebene Ergebnisse

Die Antwort kann im JSON- oder XML-Format vorliegen, das über die folgenden Werte im Accept-Header gesteuert werden kann:

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

Standardmäßig werden folgende Attribute zurückgegeben:

  • Studien:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Serie:
    • SpecificCharacterSet
    • Modalität
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Instanze:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • Zeilen
    • Spalten
    • BitsAllocated
    • NumberOfFrames

Bei includefield=all werden die Standardattribute zusammen mit folgenden Attributen zurückgegeben:

  • Studien:
    • 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
  • Instanzen: Alle in der DICOM-Instanz vorhandenen Attribute mit Ausnahme von Attributen mit einer DICOM-Wertrepräsentation von OB, OD, OF, OL, OW oder UN.

In den Metadaten werden BulkDataURIs nicht zurückgegeben.

Inkonsistente/ungültige Metadaten

Im Fall von SearchForStudies/SearchForSeries besteht die Möglichkeit inkonsistenter Metadaten auf Studien-/Serienebene über mehrere Instanzen. Beispiel: Es können zwei Instanzen mit derselben StudyInstanceUID hochgeladen werden, die jedoch unterschiedliche StudyDates haben. In diesem Fall ist das Suchverhalten nicht genau definiert. Die Suche nach diesem Wert kann in einigen Fällen funktionieren, in anderen jedoch nicht, und der zurückgegebene Wert kann bei verschiedenen Aufrufen variieren.

Statuscodes

Code Bedeutung
200 (OK) Die Antwortnutzlast enthält Darstellungen für alle Zielressourcen.
400 (Bad Request) Die Anfrage war ungültig (z. B. ungültige Suchparameter).
401 (Unauthorized) Die Anfrage enthält keine Anmeldedaten für die Authentifizierung.
403 (Permission Denied) Der authentifizierte Nutzer hat keinen Zugriff auf diese Ressource oder die Ressource existiert nicht.
406 (Not Acceptable) Der Server unterstützt keinen der zulässigen Medientypen.
429 (Too Many Requests) Der Client hat sein Kontingent überschritten.
503 (Service Unavailable) Der Server ist derzeit nicht verfügbar oder die Anfrage hat das Zeitlimit überschritten.

Löschen

Die Cloud Healthcare API unterstützt folgende proprietäre Aktionstypen:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Diese Elemente verwenden die gleichen Anfragepfade wie ihre WADO-RS-Pendants (RetrieveStudy, RetrieveSeries und RetrieveInstance). Anstelle einer HTTP-GET-Anfrage wird eine DELETE-Anfrage genutzt. Das hat zur Folge, dass die angegebene Studie, Serie oder Instanz mit allen enthaltenen DICOM-Ressourcen gelöscht wird.

Statuscodes

Code Bedeutung
200 (OK) Die Anfrageressource wurde gelöscht.
400 (Bad Request) Die Anfrage war ungültig.
401 (Unauthorized) Die Anfrage enthält keine Anmeldedaten für die Authentifizierung.
403 (Permission Denied) Der authentifizierte Nutzer hat keinen Zugriff auf diese Ressource oder die Ressource existiert nicht.
429 (Too Many Requests) Der Client hat sein Kontingent überschritten.
503 (Service Unavailable) Der Server ist derzeit nicht verfügbar oder die Anfrage hat das Zeitlimit überschritten.

Accept-Header

Einige der oben genannten Methoden bieten die Möglichkeit, das Antwortformat mithilfe von HTTP-Accept-Headern zu steuern. Der Abgleich von Platzhaltern wird sowohl auf oberster Ebene (z. B. */*) als auch auf Unterebene (z. B. image/*) unterstützt. Die Angabe eines q-Werts wird ebenfalls unterstützt, um die relative Präferenz anzugeben. Wenn für einen Accept-Header kein q-Wert angegeben ist, wird er auf den Standardwert 1.0 gesetzt.

Für den Fall, dass mehrere Accept-Header angegeben sind und zwischen den Accept-Headern mit der höchsten Präferenz ein Gleichstand besteht, wählt der Server den Accept-Header aus. Clients sollten in diesem Szenario nicht von der Auswahl des Accept-Headers auf dem Server abhängig sein.

Unterstützte SOP-Klassen

Die Cloud Healthcare API kann alle DICOM-SOP-Klassen aufnehmen und grundlegende Abrufe erledigen. Für Abrufe, die eine Transcodierung zwischen Bildformaten erfordern, findet sich unter Unterstützte Übertragungssyntaxen eine Liste der unterstützten Übertragungssyntaxe.