Déclaration de conformité DICOM

Les magasins DICOM dans l'API Cloud Healthcare sont compatibles avec un sous-ensemble des services Web RESTful spécifiés dans la norme DICOM PS3.18 – Web Services (communément appelée DICOMweb). Plus précisément, ils sont compatibles avec les Ressources et service d'études (auparavant appelés services WADO-RS, STOW-RS et QIDO-RS).

De plus, l'API Cloud Healthcare prend en charge un service Web propriétaire pour la suppression d'instances DICOM.

L'API Cloud Healthcare ne prend pas en charge le service URI, le service de liste de travail, le service d'instance non patient ni aucune transaction de capacités.

Transaction de récupération

La transaction de récupération est un service Web RESTful permettant de récupérer des données d'imagerie DICOM.

La transaction de récupération permet de récupérer les ressources suivantes :

  • Ressources DICOM :
    • Étude
    • Série
    • Instance
    • Cadres
    • Bulkdata
  • Ressources de métadonnées
    • Étude
    • Série
    • Instance
  • Ressources du rendu
    • Instance
    • Cadres

Incompatible avec les ressources de Vignette.

Pour en savoir plus sur les quotas et les limites de ces méthodes, consultez la page Quotas et limites.

DICOM study/series/instances

Les en-têtes Accept suivants sont acceptés :

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (par défaut)
  • 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=*
.

Instances DICOM

En plus des en-têtes Accept ci-dessus, RetrieveInstance accepte les types de contenu en une seule partie pour plus de commodité :

  • 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=*

Cela ne fait pas partie du standard DICOMweb officiel.

Cadres DICOM

Les en-têtes Accept suivants sont acceptés :

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (par défaut)
  • 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"

Une syntaxe de transfert de * permet à l'utilisateur de demander qu'aucun transcodage ne soit effectué. La syntaxe de transfert du fichier importé est donc utilisée. Pour application/octet-stream, les données groupées seront renvoyées au format indiqué dans le fichier DICOM importé.

Ressources du rendu

Les en-têtes Accept suivants sont acceptés :

  • image/jpeg (par défaut)
  • image/png

Seule la récupération des ressources Instance ou Frame est acceptée.

Aucun paramètre d'URL n'est accepté.

Ressources de métadonnées

Les en-têtes Accept suivants sont acceptés :

  • application/dicom+json (par défaut)
  • multipart/related; type=application/dicom+xml

Les balises encodées en tant qu'éléments InlineBinary sont encodées à l'aide d'un ordre d'octets little-endian, car le paramètre de syntaxe de transfert n'est pas compatible avec les points de terminaison qui demandent des ressources de métadonnées.

Par défaut, RetrieveMetadata ne renvoie aucun attribut dont la représentation de valeur DICOM est OB, OW ou UN. Pour renvoyer des URI BulkData pour les tags correspondant à la définition de Bulkdata Preview, utilisez Preview version.

Les tags de séquence DICOM contenant approximativement plus de 1 Mio de données ne seront pas renvoyés dans les ressources de métadonnées. Cette limitation ne s'applique qu'aux ressources de métadonnées. Les ressources DICOM contiendront toujours ces tags.

Ressources Bulkdata (preview)

Les en-têtes Accept suivants sont acceptés :

  • multipart/related; type="application/octet-stream"; transfer-syntax=* (par défaut)
  • application/octet-stream; transfer-syntax=*

Syntaxes de transfert compatibles avec le transcodage

Les en-têtes Accept ci-dessus décrivent les types de médias et les syntaxes de transfert que vous pouvez demander à l'API, mais cela n'est pas nécessairement toujours possible en fonction de la syntaxe de transfert du fichier d'origine importé. En particulier, le transcodage n'est possible qu'à partir des syntaxes de transfert suivantes :

  • 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 (JPEG Lossless)
  • 1.2.840.10008.1.2.4.70 (JPEG Lossless Selection Value 1)
  • 1.2.840.10008.1.2.4.90 (JPEG 2000 Lossless uniquement)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE Lossless)

Si le fichier d'origine présente une syntaxe de transfert autre que celle de la liste ci-dessus et que vous demandez le transcodage vers un autre format, une erreur est renvoyée.

L'API Cloud Healthcare ne peut pas transcoder des images non monochromes avec une profondeur de bits supérieure à 8 au format JPEG. De plus, les images dont la valeur Bits Allocated (0028, 0100) est égale à 1 ou qui sont stockées dans les tags Float Pixel Data (7FE0,0008) ou Double Float Pixel Data (7FE0,0009) ne peuvent être transcodées que entre les formats natifs.

Afin de désactiver le transcodage et de récupérer tout fichier de l'API, vous pouvez définir transfer-syntax=* dans votre en-tête Accept.

Codes d'état

Code Signification
200 (OK) La charge utile de réponse contient des représentations pour toutes les ressources Target.
400 (Requête incorrecte) La requête était incorrecte (par exemple, paramètres ou en-têtes de requête incorrects) pour la ou les ressources Target spécifiées (par exemple, données de pixels manquantes).
401 (Opération non autorisée) Les identifiants d'authentification de la requête sont manquants.
403 (Autorisation refusée) L'utilisateur authentifié n'a pas accès à cette ressource (ou la ressource n'existe pas).
406 (Non accepté) Le serveur ne prend en charge aucun des types de contenu autorisés.
429 (Trop de requêtes) Le client dépasse son quota.
503 (Service indisponible) Le serveur est actuellement indisponible ou la requête a dépassé sa date limite.

Transaction en magasin

La Transaction en magasin est un service Web RESTful permettant de stocker des données d'imagerie DICOM.

La transaction en magasin accepte directement les fichiers binaires DICOM Partie 10 ou accepte la division d'un fichier DICOM en métadonnées (représentées au format JSON) et en donnés groupées. Ces deux versions ont une sémantique différente décrite dans les sections suivantes.

Consultez la section Quotas et limites pour en savoir plus sur les quotas et les limites de cette méthode.

Fichiers binaires DICOM Part 10

Les types de contenu suivants sont acceptés :

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

Aucune contrainte ni aucun remplacement d'attributs n'est effectué par le serveur.

Cette version accepte toutes les syntaxes de transfert et toutes les classes SOP. Seule la validation minimale du fichier DICOM est effectuée pour extraire certains attributs de métadonnées clés.

Notez que, pour plus de commodité, la Transaction en magasin accepte également une requête HTTP en une seule partie avec une seule instance DICOM dont le contenu est de type application/dicom. Cela ne fait pas partie du standard DICOMweb officiel.

Consultez la section Stocker une instance DICOM pour obtenir le guide d'utilisation#39;utilisation associé.

Métadonnées JSON et requêtes de données groupées

Lorsque vous stockez des instances utilisant des métadonnées JSON et des données groupées, la première partie en plusieurs parties doit être constituée d'un tableau JSON d'instances DICOM.

La première partie doit avoir le type de contenu application/dicom+json; transfer-syntax=TransferSyntaxUID, où TransferSyntaxUID est la syntaxe de transfert utilisée pour encoder des données binaires dans des objets InlineBinary. Si aucun objet InlineBinary n'est présent dans les métadonnées, le paramètre transfer-syntax peut être omis.

Les éléments DICOM suivants doivent être présents dans chaque instance dans les métadonnées JSON :

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

L'élément SpecificCharacterSet doit être défini sur ISO_IR 192 et les métadonnées JSON doivent être encodées au format UTF-8 Unicode. La valeur TransferSyntaxUID peut être définie sur n'importe quelle syntaxe de transfert valide, à l'exception des syntaxes de transfert non compatibles suivantes :

  • 1.2.840.10008.1.2.2 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

Dans les métadonnées JSON, l'utilisateur peut spécifier plusieurs URI BulkDataURI pour les tags DICOM avec des valeurs RV d'OB, OW ou UN. Ces URI BulkDataURI indiquent que les données binaires du tag contenant l'URI seront envoyées dans une partie suivante dont l'en-tête Content-Location est défini sur l'URI BulkDataURI.

Chaque instance des métadonnées JSON peut avoir au maximum un URI BulkDataURI. Les métadonnées JSON ne doivent pas contenir aucun URI BulkDataURI dupliqué. Les données groupées des images compressées ne doivent être envoyées que pour le tag PixelData et lorsqu'elles sont envoyées, la syntaxe de transfert spécifiée dans la partie des données groupées doit correspondre à la valeur de l'élément TransferSyntaxUID de l'instance.

Les éléments Content-Types suivants sont compatibles avec les parties de données groupées :

  • 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

Une autre méthode pour spécifier des données binaires consiste à les encoder en tant que chaîne encodée en base64 InlineBinary. Cette option est compatible avec tous les tags, à l'exception de PixelData, qui doit être envoyée en tant que partie de données groupées. Lorsque des objets InlineBinary sont utilisés dans les métadonnées JSON, la syntaxe de transfert utilisée pour le codage doit être spécifiée dans le type de contenu de la partie de métadonnée JSON.

Le serveur ne dérive pas d'attributs de macro de description de pixel d'image.

Consultez la section Créer des instances DICOM à partir de métadonnées JSON et de fichiers JPEG pour obtenir le guide d'utilisation#39;utilisation associé.

Réponse

En cas d'erreur, un tag FailureDetail (0009, 0097) supplémentaire (pour les réponses XML) ou FailureDetailJSON (0009,1097) (pour les réponses JSON) est retourné. Le tag FailureDetail fournit une description lisible de l'erreur.

Si une instance DICOM possède le même tuple <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> qu'une autre instance déjà présente dans le magasin DICOM, une erreur Échec du traitement est renvoyée avec un tag FailureDetail "existe déjà".

La réponse peut être au format JSON ou XML, ce qui peut être contrôlé via les valeurs d'en-tête Accept suivantes :

  • application/dicom+xml (par défaut)
  • application/dicom+json

Codes d'état

Code Signification
200 (OK) La ressource a bien été stockée.
400 (Requête incorrecte) La requête n'est pas valide (par exemple, un type de contenu ou une syntaxe de transfert non compatible).
401 (Opération non autorisée) Les identifiants d'authentification de la requête sont manquants.
403 (Autorisation refusée) L'utilisateur authentifié n'a pas accès à cette ressource (ou la ressource n'existe pas).
406 (Non accepté) Le serveur ne prend en charge aucun des types de contenu autorisés.
409 (Conflit) Au moins une ressource n'a pas été stockée (par exemple, un fichier DICOM non valide). Pour plus d'informations, vérifiez le tag FailureDetail dans le corps de la réponse.
429 (Trop de requêtes) Le client dépasse son quota.
503 (Service indisponible) Le serveur est actuellement indisponible ou la requête a dépassé sa date limite.

Transaction de recherche

La Transaction de recherche est un service Web RESTful permettant d'interroger les métadonnées d'imagerie DICOM.

L'API Cloud Healthcare permet de rechercher des études, des séries et des instances.

Paramètres de recherche

La recherche à l'aide des tags suivants est possible :

  • Studies :
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Series : tous les termes de recherche au niveau de l'étude et
    • SeriesInstanceUID
    • Type
  • Instances : tous les termes de recherche au niveau de l'étude/la série et
    • SOPInstanceUID

Seule une valeur unique, une correspondance exacte, est acceptée, sauf pour StudyDate, qui prend en charge les requêtes de plage et PatientName, qui prend en charge la correspondance floue.

Les paramètres d'URL supplémentaires suivants sont acceptés :

  • fuzzymatching : si ce champ est défini sur true, la correspondance partielle est appliquée au tag PatientName. La correspondance partielle effectuera une tokenisation et une normalisation de la valeur de PatientName dans la requête et de la valeur stockée. La correspondance se fera si un jeton de recherche est un préfixe d'un jeton stocké. Par exemple, si PatientName est "John^Doe", alors "jo", "Do" et "John Doe" correspondront tous. Toutefois, "ohn" ne correspondra pas.
  • includefield : peut être défini sur une liste d'ID d'attributs séparés par des virgules, tels que des ID de tags DICOM ou des mots clés, ou défini sur all pour renvoyer tous les tags disponibles. Pour obtenir la liste des tags disponibles, consultez la section Résultats renvoyés.

La pagination est acceptée à l'aide des paramètres de requête limit et offset. Il n'y a pas d'en-tête de réponse Avertissement si aucun autre résultat n'est disponible. Vous devez exécuter une requête supplémentaire pour déterminer s'il y a plus de résultats.

  • limit : nombre maximal de résultats à renvoyer, jusqu'à 5 000 pour les études/séries et 50 000 pour les instances. Le nombre de résultats par défaut est 100 pour les études/séries et 1 000 pour les instances.

  • offset : nombre de résultats à ignorer au début (jusqu'à 1 000 000).

Le décalage horaire par rapport à l'heure UTC n'est pas accepté.

Résultats renvoyés

La réponse peut être au format JSON ou XML, ce qui peut être contrôlé à l'aide des valeurs d'en-tête Accept suivantes:

  • application/dicom+json (par défaut)
  • multipart/related; type=application/dicom+xml

Par défaut, les attributs suivants sont renvoyés :

  • Studies :
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Series :
    • SpecificCharacterSet
    • Type
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Instances :
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • Lignes
    • Colonnes
    • BitsAllocated
    • NumberOfFrames

Pour includefield=all, les attributs par défaut sont renvoyés avec les attributs suivants :

  • Studies :
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • Series :
    • SeriesNumber
    • Laterality
    • SeriesDate
    • SeriesTime
  • Instances: tous les attributs présents dans l'instance DICOM, à l'exception des exceptions suivantes.

Par défaut, searchForInstances ne renvoie aucun attribut dont la représentation de valeur DICOM est OB, OW ou UN. Pour renvoyer des BulkDataURIs pour les balises correspondant à la définition de Bulkdata Preview, utilisez Preview searchForInstances.

Les tags de séquence DICOM contenant approximativement plus de 1 Mio de données ne seront pas renvoyés dans la réponse de métadonnées.

Métadonnées incohérentes/non valides

Dans le cas de SearchForStudies/SearchForSeries, il est possible que les métadonnées au niveau des études/séries soient incohérentes entre plusieurs instances. Par exemple, deux instances peuvent être importées avec le même StudyInstanceUID, mais avec des StudyDates différents. Dans ce cas, le comportement de recherche n'est pas bien défini. La recherche par cette valeur peut fonctionner dans certains cas, mais pas dans d'autres, et la valeur renvoyée peut varier selon les appels.

Codes d'état

Code Signification
200 (OK) La charge utile de réponse contient des représentations pour toutes les ressources Target.
400 (Requête incorrecte) La requête n'est pas valide (par exemple, paramètres de requête non valides).
401 (Opération non autorisée) Les identifiants d'authentification de la requête sont manquants.
403 (Autorisation refusée) L'utilisateur authentifié n'a pas accès à cette ressource (ou la ressource n'existe pas).
406 (Non accepté) Le serveur ne prend en charge aucun des types de contenu autorisés.
429 (Trop de requêtes) Le client dépasse son quota.
503 (Service indisponible) Le serveur est actuellement indisponible ou la requête a dépassé sa date limite.

Suppression

L'API Cloud Healthcare accepte les types d'actions propriétaires suivants :

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Ils utilisent les mêmes chemins de requête que leurs homologues WADO-RS (RetrieveStudy, RetrieveSeries et RetrieveInstance, respectivement). Au lieu d'une requête HTTP GET, une requête DELETE est utilisée. Par conséquent, l'étude, la série ou l'instance spécifiée est supprimée avec toutes les ressources DICOM qu'elle contient.

Les méthodes DeleteStudy et DeleteSeries renvoient une opération de longue durée qui supprime toutes les instances de l'étude ou de la série. Veuillez noter que les instances ne peuvent pas être insérées dans une étude ou une série en cours de suppression par une opération tant que l'opération n'est pas terminée.

Pour plus d'informations sur les opérations, consultez la section Gérer les opérations de longue durée.

Une requête DeleteInstance réussie renvoie une réponse vide.

Codes d'état

Code Signification
200 (OK) La ressource de requête a été supprimée.
400 (Requête incorrecte) La requête n'est pas valide
401 (Opération non autorisée) Les identifiants d'authentification de la requête sont manquants.
403 (Autorisation refusée) L'utilisateur authentifié n'a pas accès à cette ressource (ou la ressource n'existe pas).
429 (Trop de requêtes) Le client dépasse son quota.
503 (Service indisponible) Le serveur est actuellement indisponible ou la requête a dépassé sa date limite.

En-têtes Accept

Certaines des méthodes ci-dessus permettent de contrôler le format de réponse à l'aide d'en-têtes Accept HTTP. La mise en correspondance des caractères génériques est possible à la fois au premier niveau (par exemple, */*) et au niveau du sous-type (par exemple, image/*). La spécification d'une valeur q est également acceptée pour indiquer une préférence relative. Si aucune valeur q n'est spécifiée pour un en-tête Accept, la valeur par défaut est 1.0.

Si plusieurs en-têtes Accept sont spécifiés et qu'il existe un lien entre les en-têtes Accept de préférence les plus élevés, le serveur choisit l'en-tête Accept. Dans ce scénario, les clients ne doivent pas dépendre du choix de l'en-tête Accept par le serveur.

Classes SOP compatibles

L'API Cloud Healthcare peut ingérer et récupérer de manière élémentaire toutes les classes DICOM SOP. Pour toute récupération nécessitant un transcodage entre les formats d'image, consultez la section Syntaxes de transfert compatibles avec le transcodage pour obtenir la liste des syntaxes de transfert acceptées.

Version du dictionnaire DICOM

L'API Cloud Healthcare utilise le dictionnaire DICOM 2022d pour analyser les balises des instances ingérées.

Pour l'exportation vers BigQuery, l'API Cloud Healthcare utilise le dictionnaire DICOM 2024c pour générer des noms de colonnes.

Définition de la balise Bulkdata (preview)

Lors de la récupération des métadonnées à l'aide des méthodes Preview, l'API Cloud Healthcare exclut certaines balises définies comme bulkdata. À la place, ces balises seront renvoyées avec des métadonnées avec un BulkDataURI qui permet à l'utilisateur de récupérer le contenu de ces balises (voir RetrieveBulkdata). Voici la définition utilisée par l'API Cloud Healthcare:

  • N'importe quelle balise de données de pixel: (7FE0,0008), (7FE0,0009) ou (7FE0,0010).
  • Tout tag avec une VR OB, OW ou UN.
  • Une balise dont la VR est OD, OF ou OL et qui est supérieure à 2 ko.
    • Pour des raisons historiques, les balises d'instances déjà ingérées dans l'API Cloud Healthcare peuvent être considérées comme des données groupées si la balise est supérieure à 256 octets (OF et OL) ou 512 octets (OD).
  • Une balise dont la VR est AT, FD, FL, UL ou US et dont la multiplicité de valeurs (VM) est supérieure à 512.
    • Pour des raisons historiques, les tags d'instances déjà ingérés dans l'API Cloud Healthcare peuvent être considérés comme des données groupées si la VM est supérieure à 64.

De plus, les balises suivantes sont considérées comme des données groupées, mais ne comportent pas d'URI BulkDataURI lorsqu'elles sont renvoyées à partir de méthodes de métadonnées, et les contenus ne peuvent pas être récupérés à l'aide de RetrieveBulkdata:

  • Tag avec une VR de SQ et une taille supérieure à environ 1 Mo.