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 (chiamato comunemente DICOMweb). In particolare, supportano il servizio e le risorse per gli studi (in precedenza noti come servizi WADO-RS, STOW-RS e QIDO-RS).

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

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

Recuperare la transazione

Retrieve Transaction è un servizio web RESTful per recuperare i dati di imaging DICOM.

La transazione Recupera supporta il recupero delle seguenti risorse:

  • Risorse DICOM:
    • Studio
    • Serie
    • Istanza
    • Frame
    • Bulkdata
  • Risorse per i metadati
    • Studio
    • Serie
    • Istanza
  • Risorse visualizzate
    • Istanza
    • Frame

Non supporta le risorse miniature.

Per informazioni dettagliate su quote e limiti per questi metodi, consulta Quote e limiti.

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 riportate sopra, RetrieveInstance supporta per praticità i tipi di contenuti con una sola parte:

  • 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 la transcodifica non venga effettuata, pertanto verrà utilizzata la sintassi di trasferimento del file caricato. Nel caso di application/octet-stream, i dati collettivi verranno restituiti in qualunque formato siano presenti 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 di 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 utilizzando l'ordinamento dei byte little-endian, poiché il parametro della sintassi di trasferimento non è supportato negli endpoint che richiedono risorse di metadati.

Per impostazione predefinita, RetrieveMetadata non restituisce alcun attributo con una rappresentazione del valore DICOM corrispondente a OB, OW o UN. Per restituire BulkDataURI per i tag corrispondenti alla definizione di Bulkdata di Anteprima, utilizza Preview version.

I tag di sequenza DICOM contenenti più di circa 1 MiB di dati non verranno retitrati nelle risorse di metadati. Questa limitazione si applica solo alle risorse di metadati. Le risorse DICOM continueranno a contenere questi tag.

Risorse Bulkdata (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 (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 (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ò transcodificare in JPEG le immagini non monocromatiche con una profondità di bit superiore a 8. Inoltre, le immagini con un valore Bits Allocated (0028, 0100) pari a 1 o che sono memorizzate nei tag Float Pixel Data (7FE0,0008) o Double Float Pixel Data (7FE0,0009) possono essere transcodificate solo tra formati nativi.

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 le rappresentazioni di tutte le risorse di destinazione.
400 (Richiesta non valida) La richiesta non era valida (ad es. parametri di ricerca o intestazioni 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 (o la risorsa non esiste).
406 (Non accettabile) Il server non supporta nessuno dei tipi di contenuti multimediali accettabili.
429 (Troppe richieste) Il client sta superando la 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 archiviare i dati di imaging DICOM.

La transazione di archiviazione accetta direttamente i file di dati DICOM della Parte 10 o accetta la suddivisione di un file DICOM in metadati (rappresentati in JSON) e dati collettivi. Queste due versioni hanno una semantica diversa, descritta nelle seguenti sezioni.

Per informazioni dettagliate su quote e limiti per questo metodo, consulta Quote e limiti.

File binari della parte 10 DICOM

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 chiave dei metadati.

Tieni presente che, per praticità, la transazione di archiviazione accetta anche una richiesta HTTP di una sola parte con una singola istanza DICOM con tipo di contenuto application/dicom. Non fa parte dello standard DICOMweb ufficiale.

Consulta la sezione Archiviare un'istanza DICOM per la guida dettagliata associata.

Richieste di metadati JSON e 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 di 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. L'identificatore 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 (Explicit VR Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

L'utente può specificare all'interno dei metadati JSON più BulkDataURI per i tag DICOM con VRs of OB, OW o UN. Questi BulkDataURI indicano che i dati binari per il tag contenente l'URI verranno inviati in una parte successiva in cui l'intestazione Content-Location è impostata sul BulkDataURI.

Ogni istanza nei metadati JSON può avere al massimo un BulkDataURI. Non devono esistere 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 descrittive dei pixel delle immagini.

Consulta Creare istanze DICOM da metadati JSON e file JPEG per la guida dettagliata 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 FailureDetail indicante che l'istanza è 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 memorizzata correttamente.
400 (Richiesta non valida) La richiesta non è valida (ad es. tipo di media o sintassi di trasferimento non supportati).
401 (non autorizzato) Nella richiesta mancano le credenziali di autenticazione.
403 (Autorizzazione negata) L'utente autenticato non ha accesso a questa risorsa (o la risorsa non esiste).
406 (Non accettabile) Il server non supporta nessuno dei tipi di contenuti multimediali accettabili.
409 (conflitto) Almeno una risorsa non è stata archiviata correttamente (ad es. file DICOM non valido). Per ulteriori informazioni, controlla il tag FailureDetail nel corpo della risposta.
429 (Troppe richieste) Il client sta superando la quota.
503 (Servizio non disponibile) Il server non è al momento disponibile o la richiesta ha superato la scadenza.

Cerca transazione

Search Transaction è 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 mediante i seguenti tag:

  • 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 solo la corrispondenza esatta per singolo valore, tranne che per StudyDate che supporta le query su intervalli e PatientName che supporta la corrispondenza approssimativa.

Sono supportati i seguenti parametri URL aggiuntivi:

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

La paginazione è supportata utilizzando i parametri di ricerca limit e offset. Non è presente alcuna intestazione di risposta Avviso se non sono disponibili altri risultati. Devi eseguire un'altra query per determinare se sono presenti altri risultati.

  • limit: numero massimo di risultati da restituire, fino a un massimo di 5000 per studi/serie e 50.000 per istanze. Il numero predefinito di risultati è 100 per gli studi/le 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, il 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
  • Instances: 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 corrispondente a OB, OW o UN. Per restituire BulkDataURI per i tag corrispondenti alla definizione di Bulkdata di Anteprima, utilizza Anteprima searchForInstances.

I tag di sequenza DICOM contenenti più di circa 1 MiB di dati non verranno riportati 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 le rappresentazioni di tutte le risorse di destinazione.
400 (Richiesta non valida) La richiesta non è 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 (o la risorsa non esiste).
406 (Non accettabile) Il server non supporta nessuno dei tipi di contenuti multimediali accettabili.
429 (Troppe richieste) Il client sta superando la 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 di esecuzione prolungata che elimina tutte le istanze nello studio o nella serie. Tieni presente che le istanze non possono essere inserite in uno studio o in una serie che viene eliminata da un'operazione finché l'operazione non viene completata.

Per una guida dettagliata sulle operazioni, consulta Gestione di 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 non valida) 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 (o la risorsa non esiste).
429 (Troppe richieste) Il client sta superando la quota.
503 (Servizio non disponibile) Il server non è al momento disponibile o la richiesta ha superato la scadenza.

Intestazioni Accept

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 esempio */*) che di sottotipo (ad esempio image/*). È anche possibile specificare un valore q per indicare la relativa preferenza. Se non viene specificato un valore q per un'intestazione Accept, viene impostato il valore predefinito 1.0.

Se vengono specificate più intestazioni Accept e c'è parità tra le intestazioni Accept con la preferenza più alta, il server sceglie l'intestazione Accept. In questo scenario, i client non devono dipendere dalla scelta dell'intestazione Accept del 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 immagini, consulta le sintassi di trasferimento supportate per la transcodifica per un elenco delle sintassi di trasferimento supportate.

Versione del dizionario DICOM

L'API Cloud Healthcare utilizza il dizionario DICOM 2022d per analizzare i tag delle istanze importate.

Per l'esportazione in BigQuery, l'API Cloud Healthcare utilizza il dizionario DICOM 2024c per generare i nomi delle colonne.

Definizione del tag Bulkdata (anteprima)

Quando recupera i metadati con i metodi di anteprima, l'API Cloud Healthcare esclude alcuni tag definiti come bulkdata. 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 Pixel Data: (7FE0,0008), (7FE0,0009) (7FE0,0010).
  • Qualsiasi tag con un valore VR di OB, OW o UN.
  • Un tag con un valore VR di OD, OF o OL superiore a 2 KB.
    • Per motivi di compatibilità con le versioni precedenti, i tag delle istanze già importate nell'API Cloud Healthcare potrebbero essere considerati bulkdata se il tag è più grande di 256 B (OF e OL) o 512 B (OD).
  • Un tag con un valore VR di AT, FD, FL, UL o US e una molteplicità di valori (VM) superiore a 512.
    • Per motivi di compatibilità con le versioni precedenti, i tag delle istanze già importate nell'API Cloud Healthcare possono essere considerati bulkdata se la VM è maggiore di 64.

Inoltre, i seguenti tag sono considerati bulkdata, ma non hanno URI bulkdata quando vengono restituiti dai metodi dei metadati e i contenuti non possono essere recuperati utilizzando RetrieveBulkdata:

  • Un tag con un valore VR di SQ e una dimensione superiore a circa 1 MiB.