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).

Darüber hinaus 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 Abruftransaktion unterstützt das Abrufen der folgenden Ressourcen:

  • DICOM-Ressourcen:
    • Studie
    • Reihe
    • Instanz
    • Frames
    • Bulk-Daten
  • Metadaten-Ressourcen
    • Studie
    • Reihe
    • Instanz
  • Gerenderte Ressourcen
    • Instanz
    • Frames

Es werden keine Miniaturansichtressourcen unterstützt.

Weitere Informationen zu Kontingenten und Limits für diese Methoden finden Sie 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"

Eine Transfersyntax von * ermöglicht dem Benutzer, keine Transcodierung anzufordern. Daher wird die Transfersyntax der hochgeladenen Datei verwendet. Für application/octet-stream werden die Bulk-Daten in dem Format zurückgegeben, das in der hochgeladenen DICOM-Datei enthalten ist.

Gerenderte Ressourcen

Die folgenden Accept-Header werden unterstützt:

  • image/jpeg (Standard)
  • image/png

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

Es werden keine URL-Parameter 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 keine BulkDataURIs zurückgegeben.

Bulk-Daten-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 Übertragungssyntaxen

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 keine der zulässigen Medientypen.
429 (Too Many Requests) Der Client überschreitet das Kontingent.
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 Teil 10-DICOM-Binärdateien oder die Aufteilung einer DICOM-Datei in Metadaten (in JSON-Format) und Bulk-Daten. Diese beiden Versionen haben eine andere Semantik, die in den folgenden Abschnitten beschrieben wird.

Weitere Informationen zu Kontingenten und Limits für diese Methode finden Sie unter Kontingente und Limits.

DICOM Part 10-Binärdateien

Die folgenden Inhaltstypen werden unterstützt:

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

Der Server führt kein Erzwingen oder Ersetzen von Attributen durch.

Diese Version akzeptiert alle Transfersyntaxen und SOP-Klassen. Die DICOM-Datei wird nur minimal validiert, um einige Schlüsselmetadatenattribute zu extrahieren.

Beachten Sie, dass die Transaktion "Store Transaction" auch eine einzelne HTTP-Anfrage mit einer einzelnen DICOM-Instanz mit dem Inhaltstyp application/dicom akzeptiert. Dies ist nicht Teil des offiziellen DICOMweb-Standards.

Die zugehörige Anleitung finden Sie 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.

Die folgenden 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 und die JSON-Metadaten müssen im Unicode-UTF-8-Format codiert sein. Für die TransferSyntaxUID kann eine beliebige gültige Übertragungssyntax festgelegt werden, mit Ausnahme der folgenden nicht unterstützten Ü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)

Innerhalb der JSON-Metadaten kann der 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 nachfolgenden Teil gesendet werden, in dem der Content-Location-Header auf den BulkDataURI gesetzt ist.

Jede Instanz in den JSON-Metadaten kann höchstens eine BulkDataURI haben. Die JSON-Metadaten dürfen keine doppelten BulkDataURIs enthalten. Komprimierte Bild-Bulk-Daten dürfen nur für das PixelData-Tag gesendet werden. Die im Bulk-Datenabschnitt angegebene Übertragungssyntax muss mit dem Wert des TransferSyntaxUID-Elements 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 ein zusätzliches FailureDetail-Tag (0009, 0097) (für XML-Antworten) oder ein 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 keine der zulässigen Medientypen.
409 (Conflict) Mindestens eine Ressource wurde nicht gespeichert (z.B. ungültige DICOM-Datei). Weitere Informationen finden Sie im FailureDetail-Tag im Antworttext.
429 (Too Many Requests) Der Client überschreitet sein Kontingent.
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-Metadaten.

Die Cloud Healthcare API unterstützt die Suche nach Studien, Serien und Instanzen.

Suchparameter

Die Suche mit den 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.

Die folgenden zusätzlichen URL-Parameter werden unterstützt:

  • fuzzymatching: Wenn dieser Wert auf true festgelegt ist, wird ein Fuzzy-Abgleich auf das PatientName-Tag angewendet. Beim Fuzzy-Abgleich wird sowohl der Wert von PatientenName in der Abfrage als auch der gespeicherte Wert tokenisiert und normalisiert. Er stimmt überein, wenn ein Such-Token ein Präfix eines gespeicherten Tokens ist. Wenn beispielsweise PatientName "John^Doe" ist, werden "jo", "Do" und "John Doe" als Übereinstimmung zurückgegeben. "ohn" stimmt aber nicht überein.

Paging wird mit den Abfrageparametern limit und offset unterstützt. Wenn keine Ergebnisse mehr verfügbar sind, gibt es keinen Warnungs-Antwort-Header. 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 die folgenden 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 den 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, die eine DICOM-Wertrepräsentation von OB, OD, OF, OL, OW oder UN haben.

In den Metadaten werden keine BulkDataURIs zurückgegeben.

Inkonsistente/ungültige Metadaten

Im Fall von SearchForStudies/SearchForSeries besteht das Potenzial für inkonsistente Metadaten auf Studien-/Serienebene über mehrere Instanzen. Beispielsweise können zwei Instanzen mit derselben StudyInstanceUID hochgeladen werden, aber unterschiedliche StudyDates haben. In diesem Fall ist das Suchverhalten nicht gut definiert. Die Suche nach diesem Wert kann in einigen Fällen funktionieren, in anderen jedoch nicht. Der zurückgegebene Wert kann je nach Aufruf 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 keine der zulässigen Medientypen.
429 (Too Many Requests) Der Client überschreitet sein Kontingent.
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 die folgenden proprietären Aktionstypen:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Diese verwenden die gleichen Anfragepfade wie ihre WADO-RS-Pendants (RetrieveStudy, RetrieveSeries und RetrieveInstance). Anstelle einer HTTP-GET-Anfrage wird eine DELETE-Anfrage verwendet. Das Ergebnis ist, dass die angegebene Studie, Serie oder Instanz zusammen mit allen darin 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 überschreitet das Kontingent.
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 durchführen. Informationen zu allen Abrufen, die eine Transcodierung zwischen Bildformaten erfordern, finden Sie unter Unterstützte Übertragungssyntaxen.