Dichiarazione di conformità DICOM

Gli archivi DICOM all'interno dell'API Cloud Healthcare supportano un sottoinsieme del servizio web RESTful specificati in DICOM PS3.18 - Web Services (comunemente indicato come 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 per istanze non pazienti o una qualsiasi delle transazioni di funzionalità.

Recuperare la transazione

Il recupero della transazione è un servizio web RESTful per il recupero dei 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 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. Per application/octet-stream i dati in blocco verranno restituiti in qualsiasi formato appaia nel file .

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 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 un indirizzo Rappresentazione del valore di OB, OW o ON. 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 riportati 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 implicito)
  • 1.2.840.10008.1.2.1 (esplicito Little Endian)
  • 1.2.840.10008.1.2.2 (Big Endian VR esplicito)
  • 1.2.840.10008.1.2.4.50 (JPEG Baseline Process 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ò transcodificare immagini non monocromatiche con profondità di bit maggiore di 8 in JPEG. Inoltre, immagini con un valore di bit allocati (0028, 0100) pari a 1 o sono archiviati in Data Float Pixel Data (7FE0,0008) Float Pixel Data (7FE0,0009) possono essere transcodificati 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 è valida (ad es. parametri di query 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 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

La transazione in negozio è un servizio web RESTful per l'archiviazione dei dati di imaging DICOM.

La transazione dello store accetta i file binari DICOM della Parte 10 direttamente oppure accetta la suddivisione di un file DICOM in metadati (rappresentati in JSON) e dati in blocco. Queste due versioni hanno una semantica diversa, descritta nel seguente sezioni.

Consulta Quote e limiti per i dettagli su quote e limiti per questo .

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. Solo convalida minima del file DICOM viene fatto per estrarre alcuni attributi chiave dei metadati.

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

Vedi Archiviare un'istanza DICOM per consultare la guida illustrativa 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 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 il codice JSON i metadati devono essere codificati in formato Unicode UTF-8. Il TransferSyntaxUID può essere impostato su qualsiasi sintassi di trasferimento valida, fatta eccezione per i seguenti trasferimenti non supportati sintassi:

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

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.

Vedi Creare istanze DICOM da metadati JSON e file JPEG per consultare 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 lo stesso <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> tupla come un'altra istanza già presente nell'archivio DICOM, viene visualizzato un errore Elaborazione errore viene restituito con un errore "già esistente" Tag FailureDetails.

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 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

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 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 alla Tag PatientName. La corrispondenza parziale eseguirà la tokenizzazione e la normalizzazione sia del valore 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", poi "jo", "Do" e "John Doe" corrisponderanno tutte. Tuttavia, "ohn" non corrisponderà.
  • includefield: può essere impostato su un elenco di ID attributi separati da virgole, come ID tag o parole chiave DICOM oppure imposta il valore all per restituire tutti i tag. Per un elenco dei tag disponibili, consulta Risultati restituiti.

Il paging è supportato 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 ci sono più 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 è 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, 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 al i 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, escluso il 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 l'anteprima Definizione di Bulkdata utilizza la Visualizza l'anteprima searchForInstances.

I tag di sequenza DICOM che contengono più di circa 1 MiB di dati non 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 query 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 (o 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.

La DeleteStudy e DeleteSeries restituiscono un'operazione a lunga esecuzione 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 fino al completamento dell'operazione.

Per una guida dettagliata sulle operazioni, consulta Gestione di operazioni a lunga esecuzione.

Un DeleteInstance riuscito 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 (oppure la risorsa non esiste).
429 (Troppe richieste) Il client sta superando la 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 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, è impostato sul valore predefinito di 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 la generazione dei nomi delle colonne.

Definizione dei tag dei dati collettivi (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 VR di OB, OW o UN.
  • Un tag con un VR di OD, OF o OL maggiore di 2 KiB.
    • 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) maggiore di 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 dati collettivi, ma non presentano BulkDataURIs quando vengono restituiti da metodi di metadati e i contenuti non possono essere recuperato con RetrieveBulkdata:

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