Dichiarazione di conformità DICOM

Gli archivi DICOM all'interno dell'API Cloud Healthcare supportano un sottoinsieme dei servizi web RESTful specificati nello standard DICOM PS3.18 - Web Services (comunemente denominato DICOMweb). In particolare, supportano il servizio e risorse di Studi (precedentemente indicato come i servizi WADO-RS, STOW-RS e QIDO-RS).

Inoltre, l'API Cloud Healthcare supporta un servizio web proprietario per l'eliminazione delle istanze DICOM.

L'API Cloud Healthcare non supporta il servizio URI, il servizio Worklist, il servizio di istanza non paziente o qualsiasi delle transazioni funzionalità.

Recupera transazione

Recupera transazione è un servizio web RESTful per recuperare i dati di imaging DICOM.

La transazione di recupero supporta il recupero delle seguenti risorse:

  • Risorse DICOM:
    • Studio
    • Serie
    • Istanza
    • Frame
    • Dati in blocco
  • Risorse di metadati
    • Studio
    • Serie
    • Istanza
  • Risorse visualizzate
    • Istanza
    • Frame

Non supporta le risorse relative alle miniature.

Consulta Quote e limiti per maggiori dettagli su quote e limiti per questi metodi.

Studio/serie/istanze DICOM

Sono supportate le seguenti intestazioni Accept:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (valore predefinito)
  • 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=*

Istanze DICOM

In aggiunta alle intestazioni Accept sopra riportate, RetrieveInstance supporta tipi di contenuti in singole parti per comodità:

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

Questo non fa parte dello standard DICOMweb ufficiale.

Frame DICOM

Sono supportate le seguenti intestazioni Accept:

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

La sintassi di trasferimento * consente all'utente di richiedere che non venga eseguita la transcodifica, pertanto verrà utilizzata la sintassi di trasferimento del file caricato. Per application/octet-stream, i dati collettivi verranno restituiti nel formato in cui appaiono nel file DICOM caricato.

Risorse sottoposte a rendering

Sono supportate le seguenti intestazioni Accept:

  • image/jpeg (valore predefinito)
  • image/png

È supportato solo il recupero delle risorse Instance o Frame.

Non sono supportati parametri URL.

Risorse dei metadati

Sono supportate le seguenti intestazioni Accept:

  • application/dicom+json (valore predefinito)
  • multipart/related; type=application/dicom+xml

Per impostazione predefinita, RetrieveMetadata non restituisce alcun attributo con una rappresentazione del valore DICOM di OB, OD, OF, OL, OW o UN. Per restituire BulkDataURI per i tag corrispondenti alla definizione Bulkdata dell'anteprima, utilizza Preview version.

I tag della sequenza DICOM contenenti più di 1 MiB di dati circa non verranno restituiti nelle risorse dei metadati. Questo limite si applica solo alle risorse dei metadati. Le risorse DICOM continueranno a contenere questi tag.

Risorse di dati collettivi (anteprima)

Sono supportate le seguenti intestazioni Accept:

  • multipart/related; type="application/octet-stream"; transfer-syntax=* (valore predefinito)
  • application/octet-stream; transfer-syntax=*

Sintassi di trasferimento supportate per la transcodifica

Le intestazioni Accept riportate in precedenza descrivono i tipi di supporto e le sintassi di trasferimento che puoi richiedere dall'API, ma ciò non sempre è possibile e dipende dalla sintassi di trasferimento del file originale che hai caricato. In particolare, la transcodifica è possibile solo dalle seguenti sintassi di trasferimento:

  • 1.2.840.10008.1.2 (Little Endian Implicit)
  • 1.2.840.10008.1.2.1 (esplicita Little Endian)
  • 1.2.840.10008.1.2.2 (Big Endian VR esplicito)
  • 1.2.840.10008.1.2.4.50 (processo di riferimento JPEG 1)
  • 1.2.840.10008.1.2.4.57 (JPEG senza perdita di dati)
  • 1.2.840.10008.1.2.4.70 (valore selezione senza perdita di dati 1 JPEG)
  • 1.2.840.10008.1.2.4.90 (solo JPEG 2000 senza perdita di dati)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE senza perdita di dati)

Se il file originale ha una sintassi di trasferimento non compresa nell'elenco in alto e viene richiesta la transcodifica in un altro formato, verrà restituito un errore.

L'API Cloud Healthcare non può convertire in JPEG immagini non monocromatiche con profondità di bit superiore a 8.

Per disattivare la transcodifica e recuperare qualsiasi file dall'API, puoi impostare transfer-syntax=* nell'intestazione Accept.

Codici di stato

Codice Significato
200 (OK) Il payload di risposta contiene rappresentazioni per tutte le risorse di destinazione.
400 (Richiesta errata) La richiesta non era valida (ad es. intestazioni o parametri di ricerca errati) per le risorse di destinazione specificate (ad es. dati dei pixel mancanti).
401 (Non autorizzato) Nella richiesta mancano le credenziali di autenticazione.
403 (Autorizzazione negata) L'utente autenticato non ha accesso a questa risorsa (oppure la risorsa non esiste).
406 (Non accettabile) Il server non supporta nessuno dei tipi di media accettabili.
429 (Troppe richieste) Il client sta superando la sua quota.
503 (Servizio non disponibile) Il server non è al momento disponibile o la richiesta ha superato la scadenza.

Transazione in negozio

Store Transaction è un servizio web RESTful per l'archiviazione dei dati di imaging DICOM.

La transazione dell'archivio accetta direttamente file binari DICOM Parte 10 o accetta la suddivisione di un file DICOM in metadati (rappresentati in JSON) e dati in blocco. Queste due versioni hanno una semantica diversa, descritta nelle sezioni seguenti.

Consulta Quote e limiti per maggiori dettagli su quote e limiti per questo metodo.

File binari DICOM parte 10

Sono supportati i seguenti tipi di contenuti:

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

Il server non aggiunge forzatamente né sostituisce alcun attributo.

Questa versione accetta tutte le sintassi di trasferimento e le classi SOP. Viene eseguita solo una convalida minima del file DICOM per estrarre alcuni attributi di metadati chiave.

Tieni presente che, per praticità, la transazione in negozio accetta anche una singola richiesta HTTP su una singola parte con una singola istanza DICOM con tipo di contenuto application/dicom. Questo non fa parte dello standard DICOMweb ufficiale.

Consulta Archiviare un'istanza DICOM per la guida illustrativa associata.

Metadati JSON e richieste di dati collettive

Al momento di archiviare le istanze mediante metadati JSON e dati collettivi, la prima parte multipart deve essere composta da un array JSON di istanze DICOM.

La prima parte deve avere un Content-Type application/dicom+json; transfer-syntax=TransferSyntaxUID dove TransferSyntaxUID è la sintassi di trasferimento utilizzata per codificare i dati binari negli oggetti InlineBinary. Se nei metadati non sono presenti oggetti InlineBinary, il parametro transfer-syntax può essere omesso.

I seguenti elementi DICOM devono essere obbligatoriamente presenti in ogni istanza nei metadati JSON:

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

L'elemento SpecificCharacterSet deve essere impostato su ISO_IR 192 e i metadati JSON devono essere codificati in formato Unicode UTF-8. Il TransferSyntaxUID può essere impostato su qualsiasi sintassi di trasferimento valida, ad eccezione delle seguenti sintassi di trasferimento non supportate:

  • 1.2.840.10008.1.2.2 (Big Endian VR esplicito)
  • 1.2.840.10008.1.2.1.99 (Little Endian in VR esplicita smontata)

All'interno dei metadati JSON, l'utente può specificare più BulkDataURI per i tag DICOM con VR di OB, OW o UN. Questi BulkDataURI indicano che i dati binari del tag che contiene l'URI verranno inviati in una parte successiva con l'intestazione Content-Location impostata su BulkDataURI.

Ogni istanza nei metadati JSON può avere al massimo un BulkDataURI. Non devono essere presenti BulkDataURI duplicati nei metadati JSON. I dati collettivi delle immagini compresse devono essere inviati solo per il tag PixelData. Una volta inviati, la sintassi di trasferimento specificata nella parte dei dati collettivi deve corrispondere al valore dell'elemento TransferSyntaxUID dell'istanza.

Sono supportati i seguenti tipi di contenuti per le parti dei dati collettivi:

  • 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

Un metodo alternativo per specificare dati binari è codificarli come stringa InlineBinary con codifica base64. Ciò vale per tutti i tag tranne PixelData, che deve essere inviato come parte dei dati collettivi. Se nei metadati JSON vengono utilizzati oggetti InlineBinary, la sintassi di trasferimento utilizzata per la codifica deve essere specificato nel Content-Type della parte dei metadati JSON.

Il server non ricava gli attributi delle macro di descrizione dei pixel dell'immagine.

Consulta la sezione Creare istanze DICOM da metadati JSON e file JPEG per la guida illustrativa associata.

Risposta

In caso di errore, verrà restituito un ulteriore tag FailureDetail (0009, 0097) per le risposte XML o un tag FailureDetailJSON (0009, 1097) per le risposte JSON. Il tag FailureDetail fornisce una descrizione leggibile dell'errore.

Se un'istanza DICOM ha la stessa tupla <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> di un'altra istanza già presente nell'archivio DICOM, viene restituito un errore di errore di elaborazione con un tag FailureDetails "già esistente".

La risposta può essere in formato XML o JSON, il che può essere controllato tramite i seguenti valori di intestazione Accept:

  • application/dicom+xml (valore predefinito)
  • application/dicom+json

Codici di stato

Codice Significato
200 (OK) Risorsa archiviata.
400 (Richiesta errata) La richiesta non era valida (ad esempio si tratta di un tipo di media non supportato o di una sintassi di trasferimento).
401 (Non autorizzato) Nella richiesta mancano le credenziali di autenticazione.
403 (Autorizzazione negata) L'utente autenticato non ha accesso a questa risorsa (oppure la risorsa non esiste).
406 (Non accettabile) Il server non supporta nessuno dei tipi di media accettabili.
409 (Conflitto) Almeno una risorsa non è stata archiviata correttamente (ad es. un file DICOM non valido). Per ulteriori informazioni, controlla il tag FailureDetails nel corpo della risposta.
429 (Troppe richieste) Il client sta superando la sua quota.
503 (Servizio non disponibile) Il server non è al momento disponibile o la richiesta ha superato la scadenza.

Cerca transazione

La transazione di ricerca è un servizio web RESTful per eseguire query sui metadati di imaging DICOM.

L'API Cloud Healthcare supporta la ricerca di studi, serie e istanze.

Parametri di ricerca

È supportata la ricerca in base ai seguenti tag:

  • Studi:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Series: tutti i termini di ricerca a livello di studio e
    • SeriesInstanceUID
    • Modalità
  • Istanze: tutti i termini di ricerca a livello di studio/serie e
    • SOPInstanceUID

È supportata solo la corrispondenza esatta per singolo valore, ad eccezione di StudyDate, che supporta query di intervalli e PatientName, che supporta la corrispondenza parziale.

Sono supportati i seguenti parametri URL aggiuntivi:

  • fuzzymatching: se il criterio viene impostato su true, la corrispondenza parziale verrà applicata al tag PatientName. La corrispondenza parziale esegue la tokenizzazione e la normalizzazione del valore di PatientName nella query e del valore archiviato. Trova un eventuale token di ricerca che è un prefisso di qualsiasi token archiviato. Ad esempio, se PatientName è "John^Doe", allora "jo", "Do" e "John Doe" corrisponderanno tutti. Tuttavia, "ohn" non corrisponderà.
  • includefield: può essere impostato su un elenco separato da virgole di ID attributo, ad esempio parole chiave o ID tag DICOM, oppure impostato sul valore all per restituire tutti i tag disponibili. Per un elenco dei tag disponibili, consulta Risultati restituiti.

Il paging è supportato utilizzando i parametri di ricerca limit e offset. Non viene visualizzata alcuna intestazione di risposta di avviso se non sono disponibili altri risultati. Devi eseguire una query aggiuntiva per determinare se ci sono altri risultati.

  • limit: numero massimo di risultati che devono essere restituiti, fino a un massimo di 5000 per studi/serie e 50.000 per istanze. Il numero predefinito di risultati è 100 per gli studi/serie e 1000 per le istanze.

  • offset: numero di risultati da saltare all'inizio fino a un massimo di 1.000.000.

Non è supportata la differenza di fuso orario rispetto a UTC.

Risultati restituiti

La risposta può essere in formato JSON o XML, che può essere controllato utilizzando i seguenti valori dell'intestazione Accept:

  • application/dicom+json (valore predefinito)
  • multipart/related; type=application/dicom+xml

Per impostazione predefinita, verranno restituiti i seguenti attributi:

  • Studi:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Serie:
    • SpecificCharacterSet
    • Modalità
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Istanze:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • Righe
    • Colonne
    • BitsAllocated
    • NumberOfFrames

Per includefield=all, verranno restituiti gli attributi predefiniti insieme ai seguenti attributi:

  • Studi:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • Serie:
    • SeriesNumber
    • Lateralità
    • SeriesDate
    • SeriesTime
  • Istanze: tutti gli attributi presenti nell'istanza DICOM, escluse le eccezioni seguenti.

Per impostazione predefinita, searchForInstances non restituisce alcun attributo con una rappresentazione del valore DICOM di OB, OD, OF, OL, OW o UN. Per restituire BulkDataURI per i tag corrispondenti alla definizione Bulkdata dell'anteprima, utilizza l'anteprima searchForInstances.

I tag della sequenza DICOM contenenti più di 1 MiB di dati circa non verranno restituiti nella risposta dei metadati.

Metadati incoerenti/non validi

Nel caso di SearchForStudies/SearchForSeries, è possibile che i metadati a livello di studio o serie siano incoerenti in più istanze. Ad esempio, potrebbero venire caricate due istanze con valori identici per StudyInstanceUID, ma diversi per StudyDate. In questo caso, il comportamento di ricerca non è ben definito. La ricerca in base a tale valore potrebbe funzionare in alcuni casi, ma non in altri e il valore restituito potrebbe variare tra le diverse chiamate.

Codici di stato

Codice Significato
200 (OK) Il payload di risposta contiene rappresentazioni per tutte le risorse di destinazione.
400 (Richiesta errata) La richiesta non era valida (ad es. parametri di ricerca non validi).
401 (Non autorizzato) Nella richiesta mancano le credenziali di autenticazione.
403 (Autorizzazione negata) L'utente autenticato non ha accesso a questa risorsa (oppure la risorsa non esiste).
406 (Non accettabile) Il server non supporta nessuno dei tipi di media accettabili.
429 (Troppe richieste) Il client sta superando la sua quota.
503 (Servizio non disponibile) Il server non è al momento disponibile o la richiesta ha superato la scadenza.

Eliminazione

L'API Cloud Healthcare supporta i seguenti tipi di azioni proprietarie:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Questi tipi utilizzano gli stessi percorsi di richiesta delle rispettive controparti WADO-RS (RetrieveStudy, RetrieveSeries e RetrieveInstance, rispettivamente). Invece di una richiesta HTTP GET, viene utilizzata una richiesta DELETE. Il risultato è che lo studio, la serie o l'istanza specificata viene eliminata insieme a tutte le risorse DICOM che contiene.

I metodi DeleteStudy e DeleteSeries restituiscono un'operazione a lunga esecuzione che elimina tutte le istanze nello studio o nella serie. Tieni presente che non è possibile inserire le istanze in uno studio o in una serie eliminata da un'operazione fino al completamento dell'operazione.

Consulta Gestione delle operazioni a lunga esecuzione per una guida illustrativa sulle operazioni.

Una richiesta DeleteInstance riuscita restituisce una risposta vuota.

Codici di stato

Codice Significato
200 (OK) La risorsa della richiesta è stata eliminata.
400 (Richiesta errata) La richiesta non è valida.
401 (Non autorizzato) Nella richiesta mancano le credenziali di autenticazione.
403 (Autorizzazione negata) L'utente autenticato non ha accesso a questa risorsa (oppure la risorsa non esiste).
429 (Troppe richieste) Il client sta superando la sua quota.
503 (Servizio non disponibile) Il server non è al momento disponibile o la richiesta ha superato la scadenza.

Accetta intestazioni

Alcuni dei metodi riportati in precedenza consentono di controllare il formato di risposta utilizzando le intestazioni HTTP Accept. La corrispondenza con caratteri jolly è supportata sia al livello superiore (ad es. */*) che al sottotipo (ad es. image/*). È anche possibile specificare un valore q per indicare la preferenza relativa. Se non viene specificato un valore q per un'intestazione Accept, viene impostato il valore predefinito di 1,0.

Nel caso in cui vengano specificate più intestazioni Accept e esista un legame tra le intestazioni Accept più elevate, il server sceglierà l'intestazione Accept. In questo scenario, i client non dovrebbero dipendere dalla scelta dell'intestazione Accept scelta dal server.

Classi SOP supportate

L'API Cloud Healthcare può importare ed eseguire il recupero di base di tutte le classi SOP DICOM. Per qualsiasi recupero che richiede la transcodifica tra formati di immagine, consulta la sezione sulle sintassi di trasferimento supportate per la transcodifica per un elenco delle sintassi di trasferimento supportate.

Restrizioni per i valori dei tag

Il valore del tag BitsAllocated deve essere un multiplo di 8 per il recupero dei frame.

Definizione dei tag di dati collettivi (anteprima)

Quando recuperi i metadati con metodi di anteprima, l'API Cloud Healthcare esclude determinati tag definiti come dati collettivi. Questi tag verranno invece restituiti insieme ai metadati con un BulkDataURI che consente all'utente di recuperare i contenuti di questi tag (consulta RetrieveBulkdata). Di seguito è riportata la definizione utilizzata dall'API Cloud Healthcare:

  • Qualsiasi tag con VR di OB, OW o UN.
  • Un tag con una VR di AT, FD, FL, OD, OF, OL, UL o US e ha un valore Multiplicity (VM) maggiore di 64.

Inoltre, i seguenti tag sono considerati bulksheet, ma non hanno BulkDataURI quando vengono restituiti dai metodi dei metadati e non è possibile recuperare i contenuti utilizzando RetrieveBulkdata:

  • Tag PixelData.
  • Qualsiasi tag con VR di OD, OF o OL.
  • Un tag con VR di SQ e dimensioni superiori a circa 1 MiB.