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 noto come DICOMweb). In particolare, supportano il servizio e le risorse di studi (precedentemente noti come 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 istanze non pazienti o nessuna delle transazioni di 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 collettivi
  • Risorse dei metadati
    • Studio
    • Serie
    • Istanza
  • Risorse visualizzate
    • Istanza
    • Frame

Non supporta le risorse relative alle miniature.

Consulta Quote e limiti per i 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

Oltre alle intestazioni Accept sopra riportate, RetrieveInstance supporta tipi di contenuti di una singola parte 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=*

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 la transcodifica non venga eseguita, pertanto verrà utilizzata la sintassi di trasferimento del file caricato. Per application/octet-stream, i dati in blocco verranno restituiti nel formato visualizzato 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

I tag codificati come elementi InlineBinary verranno codificati con un ordinamento byte little-endian, poiché il parametro di sintassi del trasferimento non è supportato sugli endpoint che richiedono risorse di metadati.

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

I tag di sequenza DICOM contenenti più di circa 1 MiB di dati non verranno restituiti nelle risorse di metadati. Questo limite si applica solo alle risorse di 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 implicito)
  • 1.2.840.10008.1.2.1 (esplicito Little Endian)
  • 1.2.840.10008.1.2.2 (Big Endian per VR esplicito)
  • 1.2.840.10008.1.2.4.50 (processo di base JPEG 1)
  • 1.2.840.10008.1.2.4.57 (JPEG senza perdita di dati)
  • 1.2.840.10008.1.2.4.70 (valore di selezione senza perdita di dati JPEG 1)
  • 1.2.840.10008.1.2.4.90 (solo JPEG 2000 Lossless)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE Lossless)

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 disabilitare la transcodifica e recuperare qualsiasi file dall'API, puoi impostare transfer-syntax=* nell'intestazione Accept.

Codici di stato

Codice Significato
200 (OK) Il payload della risposta contiene rappresentazioni per tutte le risorse di destinazione.
400 (Richiesta errata) La richiesta non è valida (ad es. intestazioni o parametri di ricerca non validi) per le risorse target specificate (ad es., dati pixel mancanti).
401 (Autorizzazione non autorizzata) 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 è attualmente 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 dello store accetta direttamente i file binari DICOM parte 10 o la suddivisione di un file DICOM in metadati (rappresentati in JSON) e dati collettivi. Queste due versioni hanno una semantica diversa, descritta nelle sezioni seguenti.

Consulta Quote e limiti per i 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 dei metadati chiave.

Tieni presente che, per praticità, la transazione di archiviazione accetta anche una richiesta HTTP in 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 collettivi

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 pari a application/dicom+json; transfer-syntax=TransferSyntaxUID dove TransferSyntaxUID è la sintassi di trasferimento utilizzata per codificare i dati binari negli oggetti InlineBinary. Se non sono presenti oggetti InlineBinary nei metadati, 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 parametro TransferSyntaxUID può essere impostato su qualsiasi sintassi di trasferimento valida, fatta eccezione per le seguenti sintassi di trasferimento non supportate:

  • 1.2.840.10008.1.2.2 (Big Endian per VR esplicito)
  • 1.2.840.10008.1.2.1.99 (Little Endian VR esplicito deflate)

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 per la descrizione dei pixel immagine.

Consulta 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 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) La risorsa è stata archiviata.
400 (Richiesta errata) La richiesta non è valida (ad es. tipo di media non supportato o sintassi di trasferimento).
401 (Autorizzazione non autorizzata) 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. file DICOM non valido). Controlla il tag FailureDettagli nel corpo della risposta per ulteriori informazioni.
429 (Troppe richieste) Il client sta superando la sua quota.
503 (Servizio non disponibile) Il server non è attualmente 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

La ricerca mediante i seguenti tag è supportata:

  • Studi:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Serie: 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 la corrispondenza esatta con un solo valore, ad eccezione di StudyDate, che supporta query sugli intervalli e di PatientName, che supporta la corrispondenza parziale.

Sono supportati i seguenti parametri URL aggiuntivi:

  • fuzzymatching: se impostato su true, la corrispondenza parziale verrà applicata al tag PatientName. La corrispondenza parziale eseguirà la tokenizzazione e la normalizzazione del valore di PatientName nella query e del valore archiviato. Corrisponde se un token di ricerca è un prefisso di un 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 attributi, come parole chiave o ID tag DICOM, oppure 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. Se non sono disponibili altri risultati, non viene visualizzata alcuna intestazione della risposta all'avviso. Devi eseguire un'ulteriore query per determinare se ci sono più risultati.

  • limit: numero massimo di risultati che devono essere restituiti, fino a un massimo di 5000 per studi/serie e 50.000 per le istanze. Il numero predefinito di risultati è 100 per 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 di 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 seguenti eccezioni.

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

I tag di sequenza DICOM contenenti più di circa 1 MiB di dati 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 della risposta contiene rappresentazioni per tutte le risorse di destinazione.
400 (Richiesta errata) La richiesta non è valida (ad es. parametri di ricerca non validi).
401 (Autorizzazione non autorizzata) 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 è attualmente 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 istanze in uno studio o in una serie che è in fase di eliminazione da un'operazione fino al completamento dell'operazione.

Per una guida illustrativa sulle operazioni, consulta Gestione delle operazioni a lunga esecuzione.

Una richiesta DeleteInstance andata a buon fine restituisce una risposta vuota.

Codici di stato

Codice Significato
200 (OK) La risorsa richiesta è stata eliminata.
400 (Richiesta errata) La richiesta non è valida.
401 (Autorizzazione non autorizzata) 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 è attualmente 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 a livello superiore (ad es. */*) che a sottotipo (ad es. image/*). La specifica di un valore q è supportata anche per indicare la preferenza relativa. Se non viene specificato un valore q per l'intestazione Accept, il valore predefinito è 1,0.

Nel caso in cui vengano specificate più intestazioni Accept e sia presente un legame tra le intestazioni Accept con le preferenze più elevate, il server sceglierà l'intestazione Accept. In questo scenario, i client non devono dipendere dalla scelta del server per l'intestazione Accept.

Classi SOP supportate

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

Restrizioni per i valori tag

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

Definizione dei tag dei dati collettivi (anteprima)

Quando si recuperano metadati con metodi di anteprima, l'API Cloud Healthcare esclude alcuni 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 (vedi RetrieveBulkdata). Di seguito è riportata la definizione utilizzata dall'API Cloud Healthcare:

  • Qualsiasi tag con VR di OB, OW o UN.
  • Un tag con un VR di OD, OF o OL maggiore di 2 KiB.
    • Per motivi legacy, i tag delle istanze già importate nell'API Cloud Healthcare potrebbero essere considerati dati collettivi se il tag è superiore a 256 B (OF e OL) o 512 B (OD).
  • Un tag con VR di AT, FD, FL, UL o US e ha una moltiplicazione del valore (VM) maggiore di 512.
    • Per motivi legacy, i tag delle istanze già importate nell'API Cloud Healthcare possono essere considerati dati collettivi se la VM è maggiore di 64.

Inoltre, i seguenti tag sono considerati dati collettivi, ma non dispongono di BulkDataURI quando vengono restituiti da metodi di metadati e i contenuti non possono essere recuperati utilizzando RetrieveBulkdata:

  • Tag PixelData.
  • Un tag con una VR pari a SQ e una dimensione superiore a 1 MiB circa.