Exporter des fichiers DICOM

Le service DICOM offre la possibilité d’exporter facilement des données DICOM dans un format de fichier, ce qui simplifie le processus d’utilisation de l’imagerie médicale dans des workflows externes, tels que l’IA et le Machine Learning. Les études, séries et instances DICOM peuvent être exportées en bloc vers un compte Stockage Blob Azure à l’aide de l’API d’exportation. Les données DICOM exportées vers un compte de stockage sont exportées en tant que .dcm fichier dans une structure de dossiers qui organise les instances par StudyInstanceID et SeriesInstanceID.

L’exportation de données à partir du service DICOM comporte trois étapes :

  • Activez une identité managée affectée par le système pour le service DICOM.
  • Configurez un compte de stockage nouveau ou existant et accordez l’autorisation à l’identité managée système.
  • Utilisez l’API d’exportation pour créer un travail d’exportation afin d’exporter les données.

Activer l’identité managée pour le service DICOM

La première étape pour exporter des données à partir du service DICOM consiste à activer une identité managée par le système. Cette identité managée est utilisée pour authentifier le service DICOM et accorder l’autorisation au compte de stockage utilisé comme destination pour l’exportation. Pour plus d’informations sur les identités managées dans Azure, consultez À propos des identités managées pour les ressources Azure.

  1. Dans le Portail Azure, accédez au service DICOM à partir duquel vous souhaitez exporter, puis sélectionnez Identité.

Capture d’écran montrant la sélection de la vue Identité.

  1. Définissez l’option Étatsur Activé, puis sélectionnez Enregistrer.

Capture d’écran du bouton bascule identité affectée par le système.

  1. Sélectionnez Oui dans la boîte de dialogue de confirmation qui s’affiche.

Capture d’écran de la boîte de dialogue confirmant l’activation de l’identité système.

La création de l’identité managée système prend quelques minutes. Une fois l’identité système activée, un ID d’objet (principal) s’affiche.

Accorder des autorisations de compte de stockage à l’identité managée système

L’identité managée système a besoin de l’autorisation Contributeur aux données Blob de stockage pour écrire des données dans le compte de stockage de destination.

  1. Sous Autorisations , sélectionnez Attributions de rôles Azure.

Capture d’écran du bouton Attributions de rôles Azure dans la vue Identité.

  1. Sélectionnez Ajouter une attribution de rôle. Dans le panneau Ajouter une attribution de rôle , effectuez les sélections suivantes :
    • Sous Étendue, sélectionnez Stockage.
    • Sous Ressource, sélectionnez le compte de stockage de destination pour l’opération d’exportation.
    • Sous Rôle, sélectionnez Contributeur de données du blob de stockage.

Capture d’écran du panneau Ajouter une attribution de rôle.

  1. Sélectionnez Enregistrer pour ajouter l’autorisation à l’identité managée système.

Utiliser l’API d’exportation

L’API d’exportation expose un point POST de terminaison pour l’exportation de données.

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

Compte tenu d’une source, du jeu de données à exporter et d’une destination, de l’emplacement vers lequel les données seront exportées, le point de terminaison retourne une référence à une nouvelle opération d’exportation de longue durée. La durée de cette opération dépend du volume de données à exporter. Pour plus d’informations sur la surveillance de la progression des opérations d’exportation, consultez État de l’opération ci-dessous.

Toutes les erreurs rencontrées lors de la tentative d’exportation sont enregistrées dans un journal des erreurs. Pour plus d’informations , consultez Erreurs ci-dessous.

Requête

Le corps de la demande se compose de la source et de la destination de l’exportation.

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

Paramètres de la source

Le seul paramètre est la liste des identificateurs à exporter.

Propriété Obligatoire Default Description
Values Oui Liste d’une ou de plusieurs études, séries et/ou identificateurs d’instances SOP au format ."<StudyInstanceUID>[/<SeriesInstanceUID>[/<SOPInstanceUID>]]"

Paramètres de destination

La connexion au compte de stockage Blob Azure est spécifiée avec un BlobContainerUri.

Propriété Obligatoire Default Description
BlobContainerUri Non "" URI complet du conteneur d’objets blob.
UseManagedIdentity Oui false Indicateur obligatoire indiquant si l’identité managée doit être utilisée pour s’authentifier auprès du conteneur d’objets blob.

Exemple

L’exemple ci-dessous demande l’exportation des ressources DICOM suivantes vers le conteneur d’objets blob nommé export dans le compte de stockage nommé dicomexport:

  • Toutes les instances de l’étude dont StudyInstanceUID est 1.2.3.
  • Toutes les instances de la série dont StudyInstanceUID est 12.3 et SeriesInstanceUID est 4.5.678.
  • L’instance dont StudyInstanceUID est 123.456, SeriesInstanceUID est 7.8et SOPInstanceUID a la valeur 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
        }
    }
}

response

L’API d’exportation retourne un 202 code d’état lorsqu’une opération d’exportation est démarrée avec succès. Le corps de la réponse contient une référence à l’opération, tandis que la valeur de l’en-tête Location est l’URL de l’état de l’opération d’exportation (identique à href dans le corps).

À l’intérieur du conteneur de destination, les fichiers DCM sont au format de chemin suivant : <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"
}

État de l’opération

L’URL ci-dessus href peut être interrogée pour connaître l’état actuel de l’opération d’exportation jusqu’à l’achèvement. Une fois que le travail a atteint un état terminal, l’API retourne un code d’état 200 au lieu de 202, et la valeur de sa propriété status est mise à jour en conséquence.

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
    }
}

Erreurs

S’il existe des erreurs utilisateur lors de l’exportation d’un fichier DICOM, le fichier est ignoré et son erreur correspondante est journalisée. Ce journal des erreurs est également exporté en même temps que les fichiers DICOM et peut être examiné par l’appelant. Le journal des erreurs se trouve à l’adresse <export blob container uri>/<operation ID>/errors.log.

Format

Chaque ligne du journal des erreurs est un objet JSON avec les propriétés suivantes. Un identificateur d’erreur donné peut apparaître plusieurs fois dans le journal, car chaque mise à jour du journal est traitée au moins une fois.

Propriété Description
Timestamp Date et heure auxquelles l’erreur s’est produite.
Identifier Identificateur de l’étude, de la série ou de l’instance SOP DICOM au format ."<study instance UID>[/<series instance UID>[/<SOP instance UID>]]"
Error Message d’erreur détaillé.

Étapes suivantes