Verwenden von DICOMweb-Standard-APIs mit cURL

Artikel
04/16/2024

In diesem Artikel wird gezeigt, wie Sie mit dem DICOMweb-Dienst mit cURL- und Beispiel-DCM-DICOM-Dateien® arbeiten.

Verwenden Sie die folgenden Beispieldateien:

blue-circle.dcm
dicom-metadata.csv
green-square.dcm
red-triangle.dcm

Der Dateiname „studyUID“, „seriesUID“ und „instanceUID“ der DICOM-Beispieldateien sind:

Datei	StudyUID	SeriesUID	InstanceUID
green-square.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.12714725698140337137334606354172323212
red-triangle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395
blue-circle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.77033797676425927098669402985243398207	1.2.826.0.1.3680043.8.498.13273713909719068980354078852867170114

Hinweis

Jede dieser Dateien stellt eine einzelne Instanz dar und ist Teil derselben Studie. Außerdem sind green-square und red-triangle Teil derselben Datenreihe, während sich blue-circle in einer separaten Reihe befindet.

Voraussetzungen

Um die DICOM-Standard-APIs zu verwenden, müssen Sie über eine Instanz des DICOM-Diensts verfügen. Weitere Informationen finden Sie unter Bereitstellen des DICOM-Diensts mithilfe des Azure-Portals.

Rufen Sie nach der Bereitstellung einer Instanz des DICOM-Diensts die URL für Ihren App-Dienst ab.

Melden Sie sich beim Azure-Portal an.
Suchen Sie Zuletzt verwendete Ressourcen und wählen Sie Ihre DICOM-Dienstinstanz aus.
Kopieren Sie die Dienst-URL Ihres DICOM-Diensts.
Wenn Sie ein Zugriffstoken benötigen, lesen Sie Abrufen des Zugriffstokens für den DICOM-Dienst.

Für diesen Code greifen wir auf einen Azure-Dienst in der öffentlichen Vorschau zu. Es ist wichtig, dass Sie keine privaten Gesundheitsinformationen (Private Health Information, PHI) hochladen.

Arbeiten mit dem DICOM-Dienst

Der DICOMweb Standard verwendet multipart/related-HTTP-Anforderungen in Kombination mit DICOM-spezifischen Accept-Headern. Entwickler, die mit anderen REST-basierten APIs vertraut sind, finden die Arbeit mit dem DICOMweb Standard häufig unpraktisch. Nachdem Sie es jedoch in Betrieb nehmen, ist es einfach zu verwenden. Es braucht nur ein bisschen Vertrautheit, um loszulegen.

Die cURL-Befehle enthalten jeweils mindestens eine und manchmal zwei Variablen, die ersetzt werden müssen. Um die Ausführung der Befehle zu vereinfachen, suchen Sie die folgenden Variablen, und ersetzen Sie sie durch Ihre spezifischen Werte.

{Service URL} Die Dienst-URL (Service URL) ist die URL für den Zugriff auf Ihren DICOM-Dienst, den Sie im Azure-Portal bereitgestellt haben, z. B. https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com. Stellen Sie sicher, dass Sie die Version als Teil der URL angeben, wenn Sie Anforderungen stellen. Weitere Informationen finden Sie in der API-Versionsverwaltung für DICOM-Dienstdokumentation.
{path-to-dicoms} – Der Pfad zum Verzeichnis, das die Datei „red-triangle.dcm“ enthält, z. B. C:/dicom-server/docs/dcms
- Stellen Sie sicher, dass Schrägstriche als Trennzeichen verwendet werden und das Verzeichnis ohne nachfolgende Schrägstriche beendet wird.

DICOM-Instanzen hochladen (STOW)

Speichern von Instanzen mithilfe von multipart/related

Diese Anforderung soll veranschaulichen, wie DICOM-Dateien mithilfe von mehrteiligen/verwandten Dateien hochgeladen werden.

Hinweis

Der DICOM-Dienst ist nachsichtiger als der DICOM-Standard. Das Beispiel zeigt jedoch eine POST-Anforderung, die eng mit dem Standard übereinstimmt.

Details:

Path: ../studies
Methode: POST
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
Hauptteil:
- Content-Type: application/dicom für jede Datei hochgeladen, durch einen Trennwert getrennt

Einige Programmiersprachen und -tools verhalten sich anders. Für einige müssen Sie beispielsweise ihre eigene Grenze definieren. Für diese Tools müssen Sie möglicherweise einen leicht geänderten Content-Type-Header verwenden. Die folgenden Tools können erfolgreich verwendet werden:

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

Speichern von Instanzen für eine bestimmte Studie

Diese Anforderung veranschaulicht, wie DICOM-Dateien mithilfe von mehrteiligen/verwandten Studien hochgeladen werden.

Details:

Path: ../studies/{study}
Methode: POST
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
Hauptteil:
- Content-Type: application/dicom für jede Datei hochgeladen, durch einen Trennwert getrennt

Einige Programmiersprachen und -tools verhalten sich anders. Für einige müssen Sie beispielsweise ihre eigene Grenze definieren. Für diese Sprachen und Tools müssen Sie möglicherweise einen leicht geänderten Content-Type-Header verwenden. Die folgenden Tools können erfolgreich verwendet werden:

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --request POST "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Store-single-instance

Hinweis

Dies ist eine nicht standardmäßige API, die das Hochladen einer einzelnen DICOM-Datei ermöglicht, ohne dass der POST für multipart/related konfiguriert werden muss. Obwohl cURL multipart/related gut verarbeitet, ermöglicht diese API Tools wie Postman das Hochladen von Dateien in den DICOM-Dienst.

Die folgende Methode ist erforderlich, um eine einzelne DICOM-Datei hochzuladen.

Details:

Path: ../studies
Methode: POST
Headers:
- Accept: application/dicom+json
- Content-Type: application/dicom
- Authorization: Bearer {token value}
Hauptteil:
- Enthält eine einzelne DICOM-Datei als Binärbytes.

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

Upsert von Instanzen mithilfe von multipart/related

Hinweis

Dies ist eine nicht standardmäßige API, die den Upsert von DICOM-Dateien mithilfe von mehrteiligen/verwandten Dateien zulässt.

Details:

Path: ../studies
Methode: PUT
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
Hauptteil:
- Content-Type: application/dicom für jede Datei hochgeladen, durch einen Trennwert getrennt

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

Upsert von Instanzen für eine bestimmte Studie

Hinweis

Dies ist eine nicht standardmäßige API, die den Upsert von DICOM-Dateien mithilfe von multipart/related-Dateien an eine verwandte Studie zulässt.

Details:

Path: ../studies/{study}
Methode: PUT
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {token value}
Hauptteil:
- Content-Type: application/dicom für jede Datei hochgeladen, durch einen Trennwert getrennt

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --request PUT "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Upsert einzelner Instanz

Hinweis

Dies ist eine nicht standardmäßige API, die den Upsert einer einzelnen DICOM-Datei zulässt.

Verwenden Sie diese Methode, um eine einzelne DICOM-Datei hochzuladen.

Details:

Path: ../studies
Methode: PUT
Headers:
- Accept: application/dicom+json
- Content-Type: application/dicom
- Authorization: Bearer {token value}
Hauptteil:
- Enthält eine einzelne DICOM-Datei als Binärbytes.

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

Abrufen von DICOM (WADO)

Abrufen aller Instanzen innerhalb einer Studie

Diese Anforderung ruft alle Instanzen innerhalb einer einzelnen Studie ab und gibt sie als Sammlung von mehrteiligen/verwandten Bytes zurück.

Details:

Path: ../studies/{study}
Methode: GET
Headers:
- Accept: multipart/related; type="application/dicom"; transfer-syntax=*
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Dieser cURL-Befehl zeigt die heruntergeladenen Bytes in der Ausgabedatei an (suppressWarnings.txt), aber sie sind keine direkten DICOM-Dateien, sondern nur eine Textdarstellung des mehrteiligen/verwandten Downloads.

Abrufen von Metadaten aller Instanzen in der Studie

Diese Anforderung ruft die Metadaten für alle Instanzen innerhalb einer einzigen Studie ab.

Details:

Path: ../studies/{study}/metadata
Methode: GET
Headers:
- Accept: application/dicom+json
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Abrufen aller Instanzen innerhalb einer Datenreihe

Diese Anforderung ruft alle Instanzen innerhalb einer einzelnen Datenreihe ab und gibt sie als Sammlung von mehrteiligen/verwandten Bytes zurück.

Details:

Path: ../studies/{study}/series/{series}
Methode: GET
Headers:
- Accept: multipart/related; type="application/dicom"; transfer-syntax=*
- Authorization: Bearer {token value}

Dieser cURL-Befehl zeigt die heruntergeladenen Bytes in der Ausgabedatei an (suppressWarnings.txt), aber nicht die DICOM-Datei, sondern nur eine Textdarstellung des mehrteiligen/verwandten Downloads.

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Abrufen von Metadaten aller Instanzen innerhalb einer Datenreihe

Diese Anforderung ruft die Metadaten für alle Instanzen innerhalb einer einzigen Studie ab.

Details:

Path: ../studies/{study}/series/{series}/metadata
Methode: GET
Headers:
- Accept: application/dicom+json
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Abrufen einer einzelnen Instanz innerhalb einer Reihe einer Studie

Diese Anforderung ruft eine einzelne Instanz ab und gibt sie als DICOM-formatierten Bytestrom zurück.

Details:

Path: ../studies/{study}/series{series}/instances/{instance}
Methode: GET
Headers:
- Accept: application/dicom; transfer-syntax=*
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Abrufen von Metadaten einer einzelnen Instanz innerhalb einer Reihe einer Studie

Diese Anforderung ruft die Metadaten für eine einzelne Instanz innerhalb einer einzigen Studie und Datenreihe ab.

Details:

Path: ../studies/{study}/series/{series}/instances/{instance}/metadata
Methode: GET
Headers:
- Accept: application/dicom+json
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Abrufen eines oder mehrerer Frames aus einer einzelnen Instanz

Diese Anforderung ruft einen oder mehrere Frames aus einer einzelnen Instanz ab und gibt sie als Sammlung von mehrteiligen/verwandten Bytes zurück. Mehrere Frames können abgerufen werden, indem eine durch Kommas getrennte Liste von Framenummern übergeben wird. Alle DICOM-Instanzen mit Bildern weisen mindestens einen Frame auf, der häufig nur das Bild ist, das der Instanz selbst zugeordnet ist.

Details:

Path: ../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
Methode: GET
Headers:
- Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (Default) oder
- Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* oder
- Accept: multipart/related; type="application/octet-stream";
- Authorization: Bearer {token value}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/frames/1"
--header "Accept: multipart/related; type=\"application/octet-stream\"; transfer-syntax=1.2.840.10008.1.2.1"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Abfrage von DICOM (QIDO)

In den folgenden Beispielen suchen wir anhand ihrer eindeutigen Bezeichner nach Elementen. Sie können auch nach anderen Attributen suchen, z. B. PatientName.

Suchen nach Studien

Diese Anforderung ermöglicht die Suche nach einer oder mehreren Studien anhand von DICOM-Attributen.