Use APIs padrão DICOMweb com cURL

Artigo
04/13/2024

Este artigo mostra como trabalhar com o serviço DICOMweb usando cURL e exemplos .dcm arquivos DICOM®.

Use estes arquivos de exemplo:

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

O nome do arquivo, studyUID, seriesUID e instanceUID dos arquivos DICOM de exemplo são:

Ficheiro	EstudoUID	SérieUID	InstânciaUID
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

Cada um desses arquivos representa uma única instância e faz parte do mesmo estudo. Além disso, o quadrado verde e o triângulo vermelho fazem parte da mesma série, enquanto o círculo azul está em uma série separada.

Pré-requisitos

Para usar as APIs padrão DICOM, você deve ter uma instância do serviço DICOM implantada. Para obter mais informações, consulte Implantar o serviço DICOM usando o portal do Azure.

Depois de implantar uma instância do serviço DICOM, recupere a URL do seu serviço de aplicativo.

Inicie sessão no portal do Azure.
Pesquise recursos recentes e selecione sua instância de serviço DICOM.
Copie a URL do serviço DICOM.
Se você precisar de um token de acesso, consulte Obter token de acesso para o serviço DICOM.

Para esse código, acessamos um serviço do Azure de Visualização Pública. É importante que não carregue nenhuma informação de saúde privada (PHI).

Trabalhar com o serviço DICOM

O DICOMweb Standard faz uso intensivo de solicitações HTTP combinadas com cabeçalhos de aceitação específicos do multipart/related DICOM. Os desenvolvedores familiarizados com outras APIs baseadas em REST geralmente acham estranho trabalhar com o DICOMweb Standard. No entanto, depois de colocá-lo em funcionamento, é fácil de usar. Basta um pouco de familiaridade para começar.

Cada comando cURL contém pelo menos uma, e às vezes duas, variáveis que devem ser substituídas. Para simplificar a execução dos comandos, pesquise e substitua as seguintes variáveis pelos seus valores específicos.

{URL do serviço} A URL do serviço é a URL para acessar seu serviço DICOM que você provisionou no portal do Azure, por exemplo, https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com. Certifique-se de especificar a versão como parte da url ao fazer solicitações. Mais informações podem ser encontradas na documentação do serviço API Versioning for DICOM.
{path-to-dicoms} - O caminho para o diretório que contém o arquivo red-triangle.dcm, como C:/dicom-server/docs/dcms
- Certifique-se de usar barras para frente como separadores e termine o diretório sem uma barra à direita.

Carregar instâncias DICOM (STOW)

Armazenar instâncias usando várias partes/relacionadas

Este pedido pretende demonstrar como fazer upload de arquivos DICOM usando multipart/related.

Nota

O serviço DICOM é mais brando do que o padrão DICOM. No entanto, o exemplo demonstra uma solicitação POST que está em estrita conformidade com o padrão.

Detalhes:

Percurso: .. /estudos
Método: POST
Cabeçalhos:
- Aceitar: application/dicom+json
- Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"
- Autorização: Portador {token value}
Corpo:
- Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

Algumas linguagens e ferramentas de programação comportam-se de forma diferente. Por exemplo, alguns exigem que você defina seu próprio limite. Para essas ferramentas, talvez seja necessário usar um cabeçalho Content-Type ligeiramente modificado. As seguintes ferramentas podem ser usadas com êxito.

Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"; limite=ABCD1234
Tipo de conteúdo: multiparte/relacionado; limite=ABCD1234
Tipo de conteúdo: 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"

Armazenar instâncias para um estudo específico

Esta solicitação demonstra como fazer upload de arquivos DICOM usando multipart/related to a um estudo designado.

Detalhes:

Percurso: .. /estudos/{estudo}
Método: POST
Cabeçalhos:
- Aceitar: application/dicom+json
- Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"
- Autorização: Portador {token value}
Corpo:
- Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

Algumas linguagens e ferramentas de programação comportam-se de forma diferente. Por exemplo, alguns exigem que você defina seu próprio limite. Para esses idiomas e ferramentas, talvez seja necessário usar um cabeçalho Content-Type ligeiramente modificado. As seguintes ferramentas podem ser usadas com êxito.

Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"; limite=ABCD1234
Tipo de conteúdo: multiparte/relacionado; limite=ABCD1234
Tipo de conteúdo: 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"

Instância única de armazenamento

Nota

Esta é uma API não padrão que permite o upload de um único arquivo DICOM sem a necessidade de configurar o POST para várias partes/relacionadas. Embora o cURL lide bem com várias partes/relacionadas, esta API permite que ferramentas como o Postman carreguem arquivos para o serviço DICOM.

O método a seguir é necessário para carregar um único arquivo DICOM.

Detalhes:

Percurso: .. /estudos
Método: POST
Cabeçalhos:
- Aceitar: application/dicom+json
- Tipo de conteúdo: application/dicom
- Autorização: Portador {token value}
Corpo:
- Contém um único arquivo DICOM como bytes binários.

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"

Instâncias Upsert usando várias partes/relacionadas

Nota

Esta é uma API não-padrão que permite o upsert de arquivos DICOM usando multipart / relacionado.

Detalhes:

Percurso: .. /estudos
Método: PUT
Cabeçalhos:
- Aceitar: application/dicom+json
- Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"
- Autorização: Portador {token value}
Corpo:
- Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"; limite=ABCD1234
Tipo de conteúdo: multiparte/relacionado; limite=ABCD1234
Tipo de conteúdo: 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"

Instâncias de Upsert para um estudo específico

Nota

Esta é uma API não-padrão que permite o upsert de arquivos DICOM usando várias partes / relacionadas a um estudo designado.

Detalhes:

Percurso: .. /estudos/{estudo}
Método: PUT
Cabeçalhos:
- Aceitar: application/dicom+json
- Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"
- Autorização: Portador {token value}
Corpo:
- Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

Tipo de conteúdo: multiparte/relacionado; type="aplicação/dicom"; limite=ABCD1234
Tipo de conteúdo: multiparte/relacionado; limite=ABCD1234
Tipo de conteúdo: 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"

Instância única do Upsert

Nota

Esta é uma API não padrão que permite o upsert de um único arquivo DICOM.

Use este método para carregar um único arquivo DICOM.

Detalhes:

Percurso: .. /estudos
Método: PUT
Cabeçalhos:
- Aceitar: application/dicom+json
- Tipo de conteúdo: application/dicom
- Autorização: Portador {token value}
Corpo:
- Contém um único arquivo DICOM como bytes binários.

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"

Recuperar DICOM (WADO)

Recuperar todas as instâncias dentro de um estudo

Essa solicitação recupera todas as instâncias em um único estudo e as retorna como uma coleção de bytes com várias partes/relacionados.

Detalhes:

Percurso: .. /estudos/{estudo}
Método: GET
Cabeçalhos:
- Aceitar: multiparte/relacionado; type="aplicação/dicom"; transferência-sintaxe=*
- Autorização: Portador {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"

Este comando cURL mostra os bytes baixados no arquivo de saída (suppressWarnings.txt), mas eles não são arquivos DICOM diretos, apenas uma representação de texto do download com várias partes/relacionado.

Recuperar metadados de todas as instâncias em estudo

Essa solicitação recupera os metadados de todas as instâncias em um único estudo.

Detalhes:

Percurso: .. /studies/{study}/metadados
Método: GET
Cabeçalhos:
- Aceitar: application/dicom+json
- Autorização: Portador {token value}

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

Recuperar todas as instâncias dentro de uma série

Essa solicitação recupera todas as instâncias de uma única série e as retorna como uma coleção de bytes com várias partes/relacionados.

Detalhes:

Percurso: .. /estudos/{estudo}/série/{série}
Método: GET
Cabeçalhos:
- Aceitar: multiparte/relacionado; type="aplicação/dicom"; transferência-sintaxe=*
- Autorização: Portador {token value}

Este comando cURL mostra os bytes baixados no arquivo de saída (suppressWarnings.txt), mas não é o arquivo DICOM, apenas uma representação em texto do download com várias partes/relacionado.

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"

Recuperar metadados de todas as instâncias em uma série

Essa solicitação recupera os metadados de todas as instâncias em um único estudo.

Detalhes:

Percurso: .. /studies/{study}/series/{series}/metadata
Método: GET
Cabeçalhos:
- Aceitar: application/dicom+json
- Autorização: Portador {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}"

Recuperar uma única instância dentro de uma série de um estudo

Essa solicitação recupera uma única instância e a retorna como um fluxo de bytes formatado em DICOM.

Detalhes:

Percurso: .. /studies/{study}/series{series}/instances/{instance}
Método: GET
Cabeçalhos:
- Aceitar: aplicação/dicom; transferência-sintaxe=*
- Autorização: Portador {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"

Recuperar metadados de uma única instância dentro de uma série de um estudo

Essa solicitação recupera os metadados de uma única instância em um único estudo e série.

Detalhes:

Percurso: .. /studies/{study}/series/{series}/instances/{instance}/metadados
Método: GET
Cabeçalhos:
- Aceitar: application/dicom+json
- Autorização: Portador {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}"

Recuperar um ou mais quadros de uma única instância

Essa solicitação recupera um ou mais quadros de uma única instância e os retorna como uma coleção de bytes com várias partes/relacionados. Vários quadros podem ser recuperados passando uma lista separada por vírgulas de números de quadros. Todas as instâncias DICOM com imagens têm pelo menos um quadro, que muitas vezes é simplesmente a imagem associada à própria instância.

Detalhes:

Percurso: .. /studies/{study}/series{series}/instances/{instance}/frames/1,2,3
Método: GET
Cabeçalhos:
- Aceitar: multiparte/relacionado; type="aplicação/octeto-fluxo"; transfer-syntax=1.2.840.10008.1.2.1 (padrão) ou
- Aceitar: multiparte/relacionado; type="aplicação/octeto-fluxo"; transferência-sintaxe=* ou
- Aceitar: multiparte/relacionado; type="aplicação/octeto-fluxo";
- Autorização: Portador {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"

Consulta DICOM (QIDO)

Nos exemplos a seguir, pesquisamos itens usando seus identificadores exclusivos. Você também pode pesquisar outros atributos, como PatientName.