Utiliser les API DICOMweb Standard avec cURL

Article
04/18/2024

Cet article montre comment utiliser le service DICOMweb avec cURL avec des exemples de fichiers .dcm DICOM®.

Utilisez les exemples de fichiers suivants :

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

Les noms de fichier, studyUID, seriesUID et instanceUID des exemples de fichiers DICOM sont les suivants :

Fichier	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

Remarque

Chacun de ces fichiers représente une seule instance et fait partie de la même étude. De plus, green-square et red-triangle font partie de la même série, alors que blue-circle fait partie d’une série distincte.

Prérequis

Pour utiliser les API DICOMweb Standard, vous devez avoir une instance du service DICOM déployée. Pour plus d’informations, consultez Déployer le service DICOM à l’aide du portail Azure.

Une fois que vous avez déployé une instance du service DICOM, récupérez l’URL de votre service d’application.

Connectez-vous au portail Azure.
Recherchez les Ressources récentes et sélectionnez votre instance de service DICOM.
Copiez l’URL de service de votre service DICOM.
Si vous avez besoin d’un jeton d’accès, consultez Obtenir le jeton d’accès pour le service DICOM.

Pour ce code, nous accédons à un service Azure en préversion publique. Il est important que vous ne chargez aucune information de santé privée (PHI).

Utiliser le service DICOM

DICOMweb standard utilise fortement les requêtes HTTP multipart/related combinées avec des en-têtes d’acceptation spécifiques à DICOM. Les développeurs familiarisés avec d’autres API REST trouvent souvent l’utilisation de DICOMweb Standard difficile. Toutefois, après l’avoir installé et utilisé, il est facile à utiliser. Il y a juste un délai d’adaptation pour commencer.

Les commandes cURL contiennent chacune une ou deux variables qui doivent être remplacées. Pour simplifier l’exécution des commandes, recherchez et remplacez les variables suivantes par vos valeurs spécifiques :

{Service URL} L’URL du service est l’URL permettant d’accéder au service DICOM que vous avez approvisionné sur le portail Azure, par exemple https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com. Veillez à spécifier la version dans l’URL quand vous effectuez des requêtes. Pour plus d’informations, consultez la documentation relative au contrôle de version des API pour le service DICOM.
{path-to-dicoms} : chemin d’accès au répertoire qui contient le fichier red-triangle.dcm, tel que C:/dicom-server/docs/dcms
- Veillez à utiliser des barres obliques comme séparateurs, mais n’incluez pas de barre oblique à la fin du répertoire.

Charger des instances DICOM (STOW)

Store-instances-using-multipart/related

Cette requête vise à montrer comment charger des fichiers DICOM à l’aide de multipart/related.

Remarque

Le service DICOM est moins strict que le standard DICOM. Toutefois, l’exemple illustre une requête POST qui se conforme étroitement à la norme.

Détails :

Path : ../studies
Méthode : POST
Headers :
- Accept : application/dicom+json
- Content-Type : multipart/related; type="application/dicom"
- Authorization : Bearer {token value}
Corps :
- Content-Type : application/dicom pour chaque fichier chargé, séparés par une valeur de limite

Certains langages de programmation et outils se comportent différemment. Par exemple, certaines nécessitent que vous définissiez votre propre limite. Pour ces outils, vous devrez peut-être utiliser un en-tête Content-Type légèrement modifié. Ces outils peuvent être utilisés avec succès.

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"

Stocker des instances pour une étude spécifique

Cette requête montre comment charger des fichiers DICOM à l’aide de multipart/related sur une étude désignée.

Détails :

Path : ../studies/{study}
Méthode : POST
Headers :
- Accept : application/dicom+json
- Content-Type : multipart/related; type="application/dicom"
- Authorization : Bearer {token value}
Corps :
- Content-Type : application/dicom pour chaque fichier chargé, séparés par une valeur de limite

Certains langages de programmation et outils se comportent différemment. Par exemple, certaines nécessitent que vous définissiez votre propre limite. Pour ces langues et outils, vous devrez peut-être utiliser un en-tête Content-Type légèrement modifié. Ces outils peuvent être utilisés avec succès.

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

Remarque

Il s’agit d’une API non standard qui autorise le chargement d’un seul fichier DICOM sans avoir à configurer le POST pour multipart/related. Bien que cURL gère bien multipart/related, cette API permet aux outils tels que Postman de charger des fichiers dans le service DICOM.

La méthode suivante est nécessaire pour charger un seul fichier DICOM.

Détails :

Path : ../studies
Méthode : POST
Headers :
- Accept : application/dicom+json
- Content-Type : application/dicom
- Authorization : Bearer {token value}
Corps :
- Contient un seul fichier DICOM sous forme d’octets binaires.

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 d’instances utilisant multipart/related

Remarque

Il s’agit d’une API non standard qui permet l’upsert des fichiers DICOM à l’aide de plusieurs parties/associées.

Détails :

Path : ../studies
Méthode : PUT
Headers :
- Accept : application/dicom+json
- Content-Type : multipart/related; type="application/dicom"
- Authorization : Bearer {token value}
Corps :
- Content-Type : application/dicom pour chaque fichier chargé, séparés par une valeur de limite

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 d’instances pour une étude spécifique

Remarque

Il s’agit d’une API non standard qui permet l’insertion de fichiers DICOM utilisant le format multipart/relatif à une étude désignée.

Détails :

Path : ../studies/{study}
Méthode : PUT
Headers :
- Accept : application/dicom+json
- Content-Type : multipart/related; type="application/dicom"
- Authorization : Bearer {token value}
Corps :
- Content-Type : application/dicom pour chaque fichier chargé, séparés par une valeur de limite

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"

Remontée d’une instance unique

Remarque

Il s’agit d’une API non standard qui permet l’insertion d’un seul fichier DICOM.

Utilisez cette méthode pour télécharger un seul fichier DICOM :

Détails :

Path : ../studies
Méthode : PUT
Headers :
- Accept : application/dicom+json
- Content-Type : application/dicom
- Authorization : Bearer {token value}
Corps :
- Contient un seul fichier DICOM sous forme d’octets binaires.

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"

Récupérer DICOM (WADO)

Récupérer toutes les instances dans une étude

Cette requête récupère toutes les instances d’une seule étude et les retourne sous la forme d’une collection d’octets multipart/related.

Détails :

Path : ../studies/{study}
Méthode : 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"

Cette commande cURL affiche les octets téléchargés dans le fichier de sortie (suppressWarnings.txt), mais ils ne sont pas des fichiers DICOM directs, seulement une représentation textuelle du téléchargement multipart/related.

Récupérer les métadonnées de toutes les instances dans une étude

Cette requête récupère les métadonnées de toutes les instances au sein d’une seule étude.

Détails :

Path : ../studies/{study}/metadata
Méthode : 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}"

Récupérer toutes les instances dans une série

Cette requête récupère toutes les instances d’une seule série et les retourne sous la forme d’une collection d’octets multipart/related.

Détails :

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

Cette commande cURL affiche les octets téléchargés dans le fichier de sortie (suppressWarnings.txt), mais ce n’est pas le fichier DICOM, seulement une représentation textuelle du téléchargement multipart/related.

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"

Récupérer les métadonnées de toutes les instances dans une série

Cette requête récupère les métadonnées de toutes les instances au sein d’une seule étude.

Détails :

Path : ../studies/{study}/series/{series}/metadata
Méthode : 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}"

Récupérer une seule instance au sein d’une série d’une étude

Cette requête récupère une instance unique et la retourne sous forme de flux d’octets au format DICOM.

Détails :

Path : ../studies/{study}/series{series}/instances/{instance}
Méthode : 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"

Récupérer les métadonnées d’une seule instance au sein d’une série d’une étude

Cette requête récupère les métadonnées d’une seule instance au sein d’une seule étude et d’une seule série.

Détails :

Path : ../studies/{study}/series/{series}/instances/{instance}/metadata
Méthode : 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}"

Récupérer une ou plusieurs images à partir d’une seule instance

Cette requête récupère une ou plusieurs images à partir d’une instance unique et les retourne sous forme de collection d’octets multipart/related. Plusieurs images peuvent être récupérées en passant une liste de numéros d’images séparés par des virgules. Toutes les instances DICOM avec des images ont au minimum une image, ce qui est souvent simplement l’image associée à l’instance elle-même.

Détails :

Path : ../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
Méthode : GET
Headers :
- Accept : multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (Default) or
- Accept : multipart/related; type="application/octet-stream"; transfer-syntax=* or
- 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"

Interroger DICOM (QIDO)

Dans les exemples suivants, nous recherchons des éléments à l’aide de leurs identificateurs uniques. Vous pouvez également rechercher d’autres attributs, tels que PatientName.