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 tags encodés en tant qu'éléments InlineBinary seront encodés à l'aide de l'ordre des octets Little Endian, comme le paramètre de syntaxe de transfert n'est pas compatible avec les points de terminaison demandant des ressources de métadonnées.
Par défaut, RetrieveMetadata ne renvoie aucun attribut ayant une valeur DICOM
Représentation des valeurs d'OB, d'OW ou de UN. Pour renvoyer BulkDataURI pour les tags correspondants
l'aperçu
Définition des données en masse,
utilisez la
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 groupées (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 avec une valeur de bits alloués (0028, 0100) de 1 ou qui sont stockées soit dans les données Float Pixel Data (7FE0,0008), soit dans les données Float Pixel Data (7FE0,0009) Les tags ne peuvent être transcodés qu'entre des 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. dans le guide d'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 consulter le guide d'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 <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID>
tuple en tant qu'instance déjà présente dans le store DICOM, une erreur Processing failed (Échec du traitement)
s'affiche avec la mention "déjà existe" FailureDetail.
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 surtrue
, 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 surall
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, qui peut être contrôlée à l'aide de les valeurs d'en-tête Acceptez 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 les exceptions suivantes.
Par défaut, searchForInstances
ne renvoie aucun attribut ayant une valeur DICOM
Représentation des valeurs d'OB, d'OW ou de UN. Pour renvoyer des BulkDataURI pour les tags correspondants
l'aperçu
Définition des données en masse,
utilisez la
Prévisualisez 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.
Définition du tag Bulkdata (preview)
Lors de la récupération de métadonnées avec des méthodes Preview, l'API Cloud Healthcare exclut
à certains tags définis comme données en masse. Au lieu de cela, ces tags seront renvoyés
ainsi que les métadonnées, avec un BulkDataURI permettant à l'utilisateur de récupérer le contenu.
de ces tags (voir
RetrieveBulkdata
).
Voici la définition utilisée par l'API Cloud Healthcare:
- N'importe quelle balise de données Pixel: (7FE0,0008), (7FE0,0009) (7FE0,0010).
- Tout tag comportant la valeur VR de OB, OW ou UN.
- Balise comportant un RV d'écran extérieur, d'arrière-plan ou d'objet OL d'une taille supérieure à 2 Kio.
- Pour d'anciennes raisons, les tags d'instances déjà ingérés L'API Cloud Healthcare peut être considérée comme des données groupées si le tag est plus grand. que 256 B (OF et OL) ou 512 B (OD).
- Balise dont l'objet VR est AT, FD, FL, UL ou US et qui possède une valeur
Multiplicité (VM) supérieure à 512.
- Pour d'anciennes raisons, les tags d'instances déjà ingérés L'API Cloud Healthcare peut être considérée comme des données en masse si la VM est supérieure à 64.
En outre, les balises suivantes sont considérées comme des données groupées, mais ne possèdent pas
BulkDataURI lorsqu'ils sont renvoyés par des méthodes de métadonnées, et le contenu ne peut pas être
récupérée à l'aide de
RetrieveBulkdata
:
- Balise dont la valeur VR de SQ est supérieure à environ 1 Mio.