Exportieren von DICOM-Dateien

Der DICOM-Dienst bietet die Möglichkeit, DICOM-Daten einfach in einem Dateiformat zu exportieren, wodurch die Verwendung der medizinischen Bildgebung in externen Workflows wie KI und maschinellem Lernen vereinfacht wird. DICOM-Studien, -Serien und -Instanzen können mithilfe der Export-API massenweise in ein Azure Blob Storage-Konto exportiert werden. DICOM-Daten, die in ein Speicherkonto exportiert werden, werden als .dcm Datei in einer Ordnerstruktur exportiert, die Instanzen nach StudyInstanceID und SeriesInstanceIDorganisiert.

Es gibt drei Schritte zum Exportieren von Daten aus dem DICOM-Dienst:

  • Aktivieren Sie eine systemseitig zugewiesene verwaltete Identität für den DICOM-Dienst.
  • Konfigurieren Sie ein neues oder vorhandenes Speicherkonto, und erteilen Sie der vom System verwalteten Identität die Berechtigung.
  • Verwenden Sie die Export-API, um einen neuen Exportauftrag zum Exportieren der Daten zu erstellen.

Aktivieren der verwalteten Identität für den DICOM-Dienst

Der erste Schritt zum Exportieren von Daten aus dem DICOM-Dienst besteht darin, eine vom System verwaltete Identität zu aktivieren. Diese verwaltete Identität wird verwendet, um den DICOM-Dienst zu authentifizieren und dem Speicherkonto die Berechtigung zu erteilen, das als Ziel für den Export verwendet wird. Weitere Informationen zu verwalteten Identitäten in Azure finden Sie unter Informationen zu verwalteten Identitäten für Azure-Ressourcen.

  1. Navigieren Sie im Azure-Portal zum DICOM-Dienst, aus dem Sie exportieren möchten, und wählen Sie Identität aus.

Screenshot: Auswahl der Identitätsansicht

  1. Legen Sie die Option Status auf Ein fest, und wählen Sie dann Speichern aus.

Screenshot: Systemseitig zugewiesener Identitätsschalter

  1. Wählen Sie im daraufhin angezeigten Bestätigungsdialogfeld Ja aus.

Screenshot des Dialogfelds zur Bestätigung der Aktivierung der Systemidentität

Die Erstellung der verwalteten Systemidentität dauert einige Minuten. Wenn die Systemidentität aktiviert wurde, wird eine Objekt-ID (Prinzipal)-ID angezeigt.

Erteilen von Speicherkontoberechtigungen für die verwaltete Systemidentität

Die vom System verwaltete Identität benötigt die Berechtigung Mitwirkender für Speicherblobdaten , um Daten in das Zielspeicherkonto zu schreiben.

  1. Wählen Sie unter Berechtigungen die Option Azure-Rollenzuweisungen aus.

Screenshot: Schaltfläche

  1. Wählen Sie Rollenzuweisung hinzufügen aus. Treffen Sie im Bereich Rollenzuweisung hinzufügen die folgenden Optionen:
    • Wählen Sie unter Bereichdie Option Speicher aus.
    • Wählen Sie unter Ressource das Zielspeicherkonto für den Exportvorgang aus.
    • Wählen Sie unter Rolle die Option Mitwirkender an Storage-Blobdaten aus.

Screenshot des Bereichs

  1. Wählen Sie Speichern aus, um die Berechtigung zur systemverwalteten Identität hinzuzufügen.

Verwenden der Export-API

Die Export-API macht einen POST Endpunkt zum Exportieren von Daten verfügbar.

POST <dicom-service-url>/<version>/export

Aufgrund einer Quelle, des zu exportierenden Datensatzes und eines Ziels, des Speicherorts, an den die Daten exportiert werden, gibt der Endpunkt einen Verweis auf einen neuen Exportvorgang mit langer Ausführungsdauer zurück. Die Dauer dieses Vorgangs hängt von der Menge der zu exportierenden Daten ab. Weitere Informationen zum Überwachen des Status von Exportvorgängen finden Sie weiter unten unter Vorgangsstatus .

Fehler, die beim Export auftreten, werden in einem Fehlerprotokoll aufgezeichnet. Weitere Informationen finden Sie weiter unten unter Fehler .

Anforderung

Der Anforderungstext besteht aus der Exportquelle und dem Exportziel.

{
    "source": {
        "type": "identifiers",
        "settings": {
            "values": [
                "..."
            ]
        }
    },
    "destination": {
        "type": "azureblob",
        "settings": {
            "setting": "<value>"
        }
    }
}

Quelleinstellungen

Die einzige Einstellung ist die Liste der zu exportierenden Bezeichner.

Eigenschaft Erforderlich Standard BESCHREIBUNG
Values Ja Eine Liste mit mindestens einem DICOM-Studien-, Serien- und/oder SOP-Instanzbezeichner im Format ."<StudyInstanceUID>[/<SeriesInstanceUID>[/<SOPInstanceUID>]]"

Zieleinstellungen

Die Verbindung mit dem Azure Blob Storage-Konto wird mit angegeben BlobContainerUri.

Eigenschaft Erforderlich Standard BESCHREIBUNG
BlobContainerUri Nein "" Der vollständige URI für den Blobcontainer.
UseManagedIdentity Ja false Ein erforderliches Flag, das angibt, ob die verwaltete Identität zur Authentifizierung beim Blobcontainer verwendet werden soll.

Beispiel

Im folgenden Beispiel wird der Export der folgenden DICOM-Ressourcen in den Blobcontainer im export Speicherkonto mit dem Namen dicomexportangefordert:

  • Alle Instanzen innerhalb der Studie, deren StudyInstanceUID ist 1.2.3.
  • Alle Instanzen innerhalb der Reihe, deren StudyInstanceUID ist 12.3 und SeriesInstanceUID ist 4.5.678.
  • Die -Instanz, 123.456deren StudyInstanceUID ist , SeriesInstanceUID7.8und SOPInstanceUID ist 9.1011.12.
POST /export HTTP/1.1
Accept: */*
Content-Type: application/json
{
    "sources": {
        "type": "identifiers",
        "settings": {
            "values": [
                "1.2.3",
                "12.3/4.5.678",
                "123.456/7.8/9.1011.12"
            ]
        }
    },
    "destination": {
        "type": "azureblob",
        "settings": {
            "blobContainerUri": "https://dicomexport.blob.core.windows.net/export",
            "UseManagedIdentity": true
        }
    }
}

Antwort

Die Export-API gibt einen 202 Statuscode zurück, wenn ein Exportvorgang erfolgreich gestartet wurde. Der Text der Antwort enthält einen Verweis auf den Vorgang, während der Wert des Location Headers die URL für den Status des Exportvorgangs ist (derselbe wie href im Textkörper).

Im Zielcontainer befinden sich die DCM-Dateien im folgenden Pfadformat: <operation id>/results/<study>/<series>/<sop instance>.dcm

HTTP/1.1 202 Accepted
Content-Type: application/json
{
    "id": "df1ff476b83a4a3eaf11b1eac2e5ac56",
    "href": "https://example-dicom.dicom.azurehealthcareapis.com/v1/operations/df1ff476b83a4a3eaf11b1eac2e5ac56"
}

Vorgangsstatus

Die obige href URL kann bis zum Abschluss nach dem aktuellen Status des Exportvorgangs abgefragt werden. Sobald der Auftrag einen Terminalstatus erreicht hat, gibt die API den Statuscode 200 anstelle von 202 zurück, und der Wert der Statuseigenschaft wird entsprechend aktualisiert.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "operationId": "df1ff476b83a4a3eaf11b1eac2e5ac56",
    "type": "export",
    "createdTime": "2022-09-08T16:40:36.2627618Z",
    "lastUpdatedTime": "2022-09-08T16:41:01.2776644Z",
    "status": "completed",
    "results": {
        "errorHref": "https://dicomexport.blob.core.windows.net/export/4853cda8c05c44e497d2bc071f8e92c4/errors.log",
        "exported": 1000,
        "skipped": 3
    }
}

Errors

Wenn beim Exportieren einer DICOM-Datei Benutzerfehler auftreten, wird die Datei übersprungen und der entsprechende Fehler protokolliert. Dieses Fehlerprotokoll wird auch zusammen mit den DICOM-Dateien exportiert und kann vom Aufrufer überprüft werden. Das Fehlerprotokoll finden Sie unter <export blob container uri>/<operation ID>/errors.log.

Format

Jede Zeile des Fehlerprotokolls ist ein JSON-Objekt mit den folgenden Eigenschaften. Ein bestimmter Fehlerbezeichner kann mehrmals im Protokoll angezeigt werden, da jede Aktualisierung des Protokolls mindestens einmal verarbeitet wird.

Eigenschaft BESCHREIBUNG
Timestamp Datum und Uhrzeit des Auftretens des Fehlers.
Identifier Der Bezeichner für die DICOM-Studie, -Serie oder -SOP-Instanz im Format "<study instance UID>[/<series instance UID>[/<SOP instance UID>]]".
Error Die ausführliche Fehlermeldung.

Nächste Schritte