Condividi tramite

Usare le API DICOMweb Standard con cURL

  • Articolo

Questo articolo illustra come usare il servizio DICOMweb usando cURL ed esempi .dcm file DICOM®.

Usare questi file di esempio:

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

Il nome file, 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. Inoltre, il quadrato verde e il triangolo rosso fanno parte della stessa serie, mentre il cerchio blu si trova in una serie separata.

Prerequisiti

Per usare le API DICOM Standard, è necessario che sia distribuita un'istanza del servizio DICOM. 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 le risorse recenti e selezionare l'istanza del servizio DICOM.
  3. Copiare l'URL 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 in anteprima pubblica. È importante non caricare informazioni sanitarie private .

Usare il servizio DICOM

DICOMweb Standard usa intensamente multipart/related le richieste HTTP combinate con intestazioni di accettazione specifiche di DICOM. Gli sviluppatori che hanno familiarità con altre API basate su REST spesso trovano a lavorare con DICOMweb Standard imbarazzante. Tuttavia, dopo averlo installato e in esecuzione, è facile da usare. Ci vuole un po' di familiarità per iniziare.

I comandi cURL contengono almeno uno e a volte due variabili che devono essere sostituite. Per semplificare l'esecuzione dei comandi, cercare e sostituire le variabili seguenti sostituendole 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, https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.comad esempio . Assicurarsi di specificare la versione come parte dell'URL durante l'esecuzione di richieste. Altre informazioni sono disponibili nella documentazione relativa al controllo delle versioni delle 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 con più parti/correlate

Questa richiesta intende illustrare come caricare file DICOM usando più parti/correlate.

Nota

Il servizio DICOM è più favorevole rispetto allo standard DICOM. Tuttavia, nell'esempio viene illustrata una richiesta POST conforme allo standard.

Dettagli:

  • Percorso:.. /Studi
  • Metodo: POST
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorizzazione: Bearer {token value}
  • 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 il proprio limite. Per questi strumenti, potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. Questi strumenti possono essere usati correttamente.

  • 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 più parti/correlati a uno studio designato.

Dettagli:

  • Percorso:.. /studies/{study}
  • Metodo: POST
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorizzazione: Bearer {token value}
  • 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 il proprio limite. Per questi linguaggi e strumenti, potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. Questi strumenti possono essere usati correttamente.

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

Archivio a istanza singola

Nota

Si tratta di un'API non standard che consente il caricamento di un singolo file DICOM senza la necessità di configurare POST per più parti/correlate. Anche se cURL gestisce correttamente più parti/correlate, 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:.. /Studi
  • Metodo: POST
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Autorizzazione: Bearer {token value}
  • 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"

Istanze upsert che usano istanze multipart/correlate

Nota

Si tratta di un'API non standard che consente l'upsert dei file DICOM usando più parti/correlate.

Dettagli:

  • Percorso:.. /Studi
  • Metodo: PUT
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorizzazione: Bearer {token value}
  • 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 il proprio limite. Per questi strumenti, potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. Questi strumenti possono essere usati correttamente:

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

Istanze di Upsert per uno studio specifico

Nota

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

Dettagli:

  • Percorso:.. /studies/{study}
  • Metodo: PUT
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Autorizzazione: Bearer {token value}
  • 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 il proprio limite. Per questi linguaggi e strumenti, potrebbe essere necessario usare un'intestazione Content-Type leggermente modificata. Questi strumenti possono essere usati correttamente:

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

Upsert a 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:.. /Studi
  • Metodo: PUT
  • Intestazioni:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Autorizzazione: Bearer {token value}
  • 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/correlati.

Dettagli:

  • Percorso:.. /studies/{study}
  • Metodo: GET
  • Intestazioni:
    • Accetta: multipart/correlato; type="application/dicom"; transfer-syntax=*
    • Autorizzazione: Bearer {token value}
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), ma non sono file DICOM diretti, ma solo una rappresentazione testuale del download multipart/correlato.

Recuperare i metadati di tutte le istanze in studio

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

Dettagli:

  • Percorso:.. /studies/{study}/metadata
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}

Questo comando cURL mostra i byte scaricati nel file di output (suppressWarnings.txt), ma non sono file DICOM diretti, ma solo una rappresentazione testuale del download multipart/correlato.

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/correlati.

Dettagli:

  • Percorso:.. /studies/{study}/series/{series}
  • Metodo: GET
  • Intestazioni:
    • Accetta: multipart/correlato; type="application/dicom"; transfer-syntax=*
    • Autorizzazione: Bearer {token value}

Questo comando cURL mostra i byte scaricati nel file di output (suppressWarnings.txt), ma non è il file DICOM, ma solo una rappresentazione testuale del download multipart/correlato.

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/{study}/series/{series}/metadata
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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/{study}/series{series}/instances/{instance}
  • Metodo: GET
  • Intestazioni:
    • Accetta: application/dicom; transfer-syntax=*
    • Autorizzazione: Bearer {token value}
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 studi

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

Dettagli:

  • Percorso:.. /studies/{study}/series/{series}/instances/{instance}/metadata
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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ù fotogrammi da una singola istanza

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

Dettagli:

  • Percorso:.. /studies/{study}/series{series}/instances/{instance}/frames/1,2,3
  • Metodo: GET
  • Intestazioni:
    • Accetta: multipart/correlato; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (impostazione predefinita) o
    • Accetta: multipart/correlato; type="application/octet-stream"; transfer-syntax=* o
    • Accetta: multipart/correlato; type="application/octet-stream";
    • Autorizzazione: Bearer {token value}
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 gli identificatori univoci. È anche possibile cercare altri attributi, ad esempio PatientName.

Ricerca di studi

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

Per altre informazioni sugli attributi DICOM supportati, vedere l'istruzione di conformità DICOM.

Dettagli:

  • Percorso:.. /Studi? StudyInstanceUID={study}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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 di cercare una o più serie in base agli attributi DICOM.

Per altre informazioni sugli attributi DICOM supportati, vedere l'istruzione di conformità DICOM.

Dettagli:

  • Percorso:.. /Serie? SeriesInstanceUID={series}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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 di cercare una o più serie all'interno di un singolo studio in base agli attributi DICOM.

Per altre informazioni sugli attributi DICOM supportati, vedere l'istruzione di conformità DICOM.

Dettagli:

  • Percorso:.. /studies/{study}/series? SeriesInstanceUID={series}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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 le istanze

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

Per altre informazioni sugli attributi DICOM supportati, vedere l'istruzione di conformità DICOM.

Dettagli:

  • Percorso:.. /Istanze? SOPInstanceUID={instance}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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 di cercare una o più istanze all'interno di un singolo studio in base agli attributi DICOM.

Per altre informazioni sugli attributi DICOM supportati, vedere l'istruzione di conformità DICOM.

Dettagli:

  • Percorso:.. /studies/{study}/instances? SOPInstanceUID={instance}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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 di una serie

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

Per altre informazioni sugli attributi DICOM supportati, vedere l'istruzione di conformità DICOM

Dettagli:

  • Percorso:.. /studies/{study}/series/{series}/instances? SOPInstanceUID={instance}
  • Metodo: GET
  • Intestazioni:
    • Accept: application/dicom+json
    • Autorizzazione: Bearer {token value}
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}"

Elimina 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/{study}/series/{series}/instances/{instance}
  • Metodo: DELETE
  • Intestazioni:
    • Autorizzazione: Bearer {token value}
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/{study}/series/{series}
  • Metodo: DELETE
  • Intestazioni:
    • Autorizzazione: Bearer {token value}
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 tutte le istanze figlio).

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

Dettagli:

  • Percorso:.. /studies/{study}
  • Metodo: DELETE
  • Intestazioni:
    • Autorizzazione: Bearer {token value}
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.