Condividi tramite

Usare le API DICOMweb standard con cURL

  • Articolo

Questo articolo illustra come usare il servizio DICOMweb con cURL e file DICOM® con estensione dcm di esempio.

Usare questi file di esempio:

  • blue-circle.dcm
  • dicom-metadata.csv
  • green-square.dcm
  • red-triangle.dcm

Il nome file e i valori studyUID, seriesUID e instanceUID dei file DICOM di esempio sono:

file StudyUID SeriesUID InstanceUID
green-square.dcm 1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420 1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652 1.2.826.0.1.3680043.8.498.12714725698140337137334606354172323212
red-triangle.dcm 1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420 1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652 1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395
blue-circle.dcm 1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420 1.2.826.0.1.3680043.8.498.77033797676425927098669402985243398207 1.2.826.0.1.3680043.8.498.13273713909719068980354078852867170114

Nota

Ognuno di questi file rappresenta una singola istanza e fa parte dello stesso studio. I file green-square e red-triangle fanno inoltre parte della stessa serie, mentre il file blue-circle si trova in una serie separata.

Prerequisiti

Per usare le API DICOMweb Standard, è necessario avere un'istanza del servizio DICOM distribuita. Per altre informazioni, vedere Distribuire il servizio DICOM usando il portale di Azure.

Dopo aver distribuito un'istanza del servizio DICOM, recuperare l'URL per il servizio app.

  1. Accedere al portale di Azure.
  2. Cercare Risorse recenti e selezionare l'istanza del servizio DICOM.
  3. Copiare l'URL servizio del servizio DICOM.
  4. Se è necessario un token di accesso, vedere Ottenere il token di accesso per il servizio DICOM.

Per questo codice si accede a un servizio di Azure disponibile in anteprima pubblica. È importante non caricare informazioni sanitarie protette.

Usare il servizio DICOM

DICOMweb Standard usa un numero elevato di richieste HTTP multipart/related combinate con intestazioni di accettazione specifiche di DICOM. Gli sviluppatori che hanno familiarità con altre API basate su REST spesso riscontrano problemi con DICOMweb Standard. Quando è operativo, risulta tuttavia facile da usare. Occorre acquisire un po' di familiarità per iniziare.

Ogni comando cURL contiene almeno una e a volte due variabili che devono essere sostituite. Per semplificare l'esecuzione dei comandi, cercare e sostituire le variabili seguenti con i valori specifici.

  • {URL servizio} L'URL del servizio è l'URL per accedere al servizio DICOM di cui è stato effettuato il provisioning nel portale di Azure, ad esempio https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com. Assicurarsi di specificare la versione come parte dell'URL durante l'esecuzione di richieste. Altre informazioni sono disponibili nella documentazione sul controllo delle versioni API per il servizio DICOM.
  • {path-to-dicoms}: percorso della directory contenente il file red-triangle.dcm, ad esempio C:/dicom-server/docs/dcms
    • Assicurarsi di usare le barre come separatori e terminare la directory senza una barra finale.

Caricare istanze DICOM (STOW)

Archiviare istanze usando multipart/related

Questa richiesta intende illustrare come caricare file DICOM usando multipart/related.

Nota

Il servizio DICOM è più tollerante rispetto allo standard DICOM. Nell'esempio viene tuttavia illustrata una richiesta POST conforme allo standard.

Dettagli:

  • Percorso: ../studies
  • Metodo: POST
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {valore token}
  • Corpo:
    • Content-Type: application/dicom per ogni file caricato, separato da un valore limite

Alcuni linguaggi e strumenti di programmazione si comportano in modo diverso. Ad esempio, alcuni richiedono di definire un limite personalizzato. Per questi strumenti potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. È possibile usare gli strumenti seguenti con esito positivo.

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

Archiviare istanze per uno studio specifico

Questa richiesta illustra come caricare file DICOM usando multipart/related in uno studio designato.

Dettagli:

  • Percorso: ../studies/{studio}
  • Metodo: POST
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {valore token}
  • Corpo:
    • Content-Type: application/dicom per ogni file caricato, separato da un valore limite

Alcuni linguaggi e strumenti di programmazione si comportano in modo diverso. Ad esempio, alcuni richiedono di definire un limite personalizzato. Per questi linguaggi e strumenti potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. È possibile usare gli strumenti seguenti con esito positivo.

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
curl --request POST "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Store-single-instance

Nota

Si tratta di un'API non standard che consente il caricamento di un singolo file DICOM senza la necessità di configurare POST per multipart/related. Anche se cURL gestisce correttamente multipart/related, questa API consente a strumenti come Postman di caricare file nel servizio DICOM.

Per caricare un singolo file DICOM, è necessario il metodo seguente.

Dettagli:

  • Percorso: ../studies
  • Metodo: POST
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Authorization: Bearer {valore token}
  • Corpo:
    • Contiene un singolo file DICOM come byte binari.
curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

Eseguire l'upsert di istanze usando multipart/related

Nota

Si tratta di un'API non standard che consente l'upsert dei file DICOM usando multipart/related.

Dettagli:

  • Percorso: ../studies
  • Metodo: PUT
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {valore token}
  • Corpo:
    • Content-Type: application/dicom per ogni file caricato, separato da un valore limite

Alcuni linguaggi e strumenti di programmazione si comportano in modo diverso. Ad esempio, alcuni richiedono di definire un limite personalizzato. Per questi strumenti potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. È possibile usare gli strumenti seguenti con esito positivo.

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

Eseguire l'upsert di istanze per uno studio specifico

Nota

Si tratta di un'API non standard che consente l'upsert dei file DICOM usando multipart/related in uno studio designato.

Dettagli:

  • Percorso: ../studies/{studio}
  • Metodo: PUT
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {valore token}
  • Corpo:
    • Content-Type: application/dicom per ogni file caricato, separato da un valore limite

Alcuni linguaggi e strumenti di programmazione si comportano in modo diverso. Ad esempio, alcuni richiedono di definire un limite personalizzato. Per questi linguaggi e strumenti potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. È possibile usare gli strumenti seguenti con esito positivo.

  • Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
  • Content-Type: multipart/related; boundary=ABCD1234
  • Content-Type: multipart/related
curl --request PUT "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Eseguire l'upsert di un'istanza singola

Nota

Si tratta di un'API non standard che consente l'upsert di un singolo file DICOM.

Usare questo metodo per caricare un singolo file DICOM.

Dettagli:

  • Percorso: ../studies
  • Metodo: PUT
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Authorization: Bearer {valore token}
  • Corpo:
    • Contiene un singolo file DICOM come byte binari.
curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

Recuperare DICOM (WADO)

Recuperare tutte le istanze all'interno di uno studio

Questa richiesta recupera tutte le istanze all'interno di un singolo studio e le restituisce come raccolta di byte multipart/related.

Dettagli:

  • Percorso: ../studies/{studio}
  • Metodo: GET
  • Intestazioni:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Questo comando cURL mostra i byte scaricati nel file di output (suppressWarnings.txt). Non si tratta tuttavia di file DICOM diretti, ma solo di una rappresentazione testuale del download multipart/related.

Recuperare i metadati di tutte le istanze in uno studio

Questa richiesta recupera i metadati per tutte le istanze all'interno di un singolo studio.

Dettagli:

  • Percorso: ../studies/{studio}/metadata
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}

Questo comando cURL mostra i byte scaricati nel file di output (suppressWarnings.txt). Non si tratta tuttavia di file DICOM diretti, ma solo di una rappresentazione testuale del download multipart/related.

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Recuperare tutte le istanze all'interno di una serie

Questa richiesta recupera tutte le istanze all'interno di una singola serie e le restituisce come raccolta di byte multipart/related.

Dettagli:

  • Percorso: ../studies/{studio}/series/{serie}
  • Metodo: GET
  • Intestazioni:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Authorization: Bearer {valore token}

Questo comando cURL mostra i byte scaricati nel file di output (suppressWarnings.txt). Non si tratta tuttavia del file DICOM, ma solo di una rappresentazione testuale del download multipart/related.

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Recuperare i metadati di tutte le istanze all'interno di una serie

Questa richiesta recupera i metadati per tutte le istanze all'interno di un singolo studio.

Dettagli:

  • Percorso: ../studies/{studio}/series/{serie}/metadata
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Recuperare una singola istanza all'interno di una serie di uno studio

Questa richiesta recupera una singola istanza e la restituisce come flusso DICOM formattato di byte.

Dettagli:

  • Percorso: ../studies/{studio}/series{serie}/instances/{istanza}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom; transfer-syntax=*
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Recuperare i metadati di una singola istanza all'interno di una serie di uno studio

Questa richiesta recupera i metadati per una singola istanza all'interno di un singolo studio e serie.

Dettagli:

  • Percorso: ../studies/{studio}/series/{serie}/instances/{istanza}/metadata
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Recuperare uno o più frame da una singola istanza

Questa richiesta recupera uno o più frame da una singola istanza e li restituisce come raccolta di byte multipart/related. È possibile recuperare più fotogrammi passando un elenco di numeri di frame delimitato da virgole. Tutte le istanze di DICOM con immagini hanno almeno un frame, che spesso è semplicemente l'immagine associata all'istanza stessa.

Dettagli:

  • Percorso: ../studies/{studio}/series{serie}/instances/{istanza}/frames/1,2,3
  • Metodo: GET
  • Intestazioni:
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (Default) o
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* o
    • Accept: multipart/related; type="application/octet-stream";
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/frames/1"
--header "Accept: multipart/related; type=\"application/octet-stream\"; transfer-syntax=1.2.840.10008.1.2.1"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

Query DICOM (QIDO)

Negli esempi seguenti viene eseguita la ricerca di elementi usando i rispettivi identificatori univoci. È anche possibile cercare altri attributi, ad esempio PatientName.

Ricerca di studi

Questa richiesta consente ricerche di uno o più studi in base agli attributi DICOM.

Per altre informazioni sugli attributi di DICOM supportati, vedere la Dichiarazione di conformità DICOM.

Dettagli:

  • Percorso: ../studies?StudyInstanceUID={studio}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies?StudyInstanceUID=1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Cercare serie

Questa richiesta consente ricerche di una o più serie in base agli attributi DICOM.

Per altre informazioni sugli attributi di DICOM supportati, vedere la Dichiarazione di conformità DICOM.

Dettagli:

  • Percorso: ../series?SeriesInstanceUID={serie}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/series?SeriesInstanceUID=1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Cercare serie all'interno di uno studio

Questa richiesta consente ricerche di una o più serie all'interno di un singolo studio in base agli attributi DICOM.

Per altre informazioni sugli attributi di DICOM supportati, vedere la Dichiarazione di conformità DICOM.

Dettagli:

  • Percorso: ../studies/{studio}/series?SeriesInstanceUID={serie}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series?SeriesInstanceUID=1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Cercare istanze

Questa richiesta consente ricerche di una o più istanze in base agli attributi DICOM.

Per altre informazioni sugli attributi di DICOM supportati, vedere la Dichiarazione di conformità DICOM.

Dettagli:

  • Percorso: ../instances?SOPInstanceUID={istanza}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Cercare istanze all'interno di uno studio

Questa richiesta consente ricerche di una o più istanze all'interno di un singolo studio in base agli attributi DICOM.

Per altre informazioni sugli attributi di DICOM supportati, vedere la Dichiarazione di conformità DICOM.

Dettagli:

  • Percorso: ../studies/{studio}/instances?SOPInstanceUID={istanza}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Cercare istanze all'interno di uno studio e una serie

Questa richiesta consente ricerche di una o più istanze all'interno di un singolo studio e una singola serie in base agli attributi DICOM.

Per altre informazioni sugli attributi di DICOM supportati, vedere la Dichiarazione di conformità DICOM

Dettagli:

  • Percorso: ../studies/{studio}/series/{serie}/instances?SOPInstanceUID={istanza}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Authorization: Bearer {valore token}
curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Eliminare DICOM

Eliminare un'istanza specifica all'interno di uno studio e di una serie

Questa richiesta elimina una singola istanza all'interno di un singolo studio e di una singola serie.

L'eliminazione non fa parte dello standard DICOM, ma viene aggiunta per praticità.

Dettagli:

  • Percorso: ../studies/{studio}/series/{serie}/instances/{istanza}
  • Metodo: DELETE
  • Intestazioni:
    • Authorization: Bearer {valore token}
curl --request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Authorization: Bearer {token value}"

Eliminare una serie specifica all'interno di uno studio

Questa richiesta elimina una singola serie (e tutte le istanze figlio) all'interno di un singolo studio.

L'eliminazione non fa parte dello standard DICOM, ma viene aggiunta per praticità.

Dettagli:

  • Percorso: ../studies/{studio}/series/{serie}
  • Metodo: DELETE
  • Intestazioni:
    • Authorization: Bearer {valore token}
curl --request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Authorization: Bearer {token value}"

Eliminare uno studio specifico

Questa richiesta elimina un singolo studio (e tutte le serie e le istanze figlio).

L'eliminazione non fa parte dello standard DICOM, ma viene aggiunta per praticità.

Dettagli:

  • Percorso: ../studies/{studio}
  • Metodo: DELETE
  • Intestazioni:
    • Authorization: Bearer {valore token}
curl--request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498
--header "Authorization: Bearer {token value}"

Nota

DICOM® è il marchio registrato della National Electrical Manufacturers Association per le sue pubblicazioni Standard relative alle comunicazioni digitali delle informazioni mediche.