Utilização de APIs Standard DICOMWeb™ com cURL

Este tutorial utiliza o cURL para demonstrar o trabalho com o serviço DICOM.

Neste tutorial, usaremos os seguintes ficheiros .dcm DICOM.

  • blue-circle.dcm
  • dicom-metadata.csv
  • verde-quadrado.dcm
  • red-triângulo.dcm

O nome do ficheiro, studyUID, seriesUID e instanceUID dos ficheiros DICOM da amostra é o seguinte:

Ficheiro StudyUID SeriesUID InstanceUID
verde-quadrado.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-triângulo.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 destes ficheiros representa um único caso e faz parte do mesmo estudo. Além disso, o triângulo verde-quadrado e vermelho fazem parte da mesma série, enquanto o círculo azul está numa série separada.

Pré-requisitos

Para utilizar as APIs Standard DICOMWeb™, tem de ter uma instância do serviço DICOM implantada. Se ainda não implementou uma instância do serviço DICOM, consulte o serviço Deploy DICOM utilizando o portal do Azure.

Uma vez implantado um caso do serviço DICOM, recupere o URL para o seu serviço de Aplicações:

  1. Inicie sessão no portal do Azure.
  2. Pesse os recursos recentes e selecione a sua instância de serviço DICOM.
  3. Copie o URL de serviço do seu serviço DICOM.
  4. Se ainda não obteve um token, consulte obter o token de acesso para o serviço DICOM utilizando o Azure CLI.

Para este código, vamos aceder a um serviço de Azure de Pré-Visualização Pública. É importante que não faça o upload de nenhuma informação privada de saúde (PHI).

Trabalhar com o serviço DICOM

A Norma DICOMweb™ utiliza fortemente os pedidos HTTP multipart/related combinados com cabeçalhos de aceitação específicos da DICOM. Os desenvolvedores familiarizados com outras APIs baseadas em REST muitas vezes acham que trabalhar com o DICOMweb™ Standard é estranho. No entanto, uma vez que está a funcionar, é fácil de usar. Só é preciso um pouco de familiaridade para começar.

Os comandos cURL contêm, cada um, pelo menos uma, e às vezes duas, variáveis que devem ser substituídas. Para simplificar a execução dos comandos, procure e substitua as seguintes variáveis substituindo-as pelos seus valores específicos:

  • {URL de serviço} Este é o URL para aceder ao seu serviço DICOM que ademediou no portal do Azure, por exemplo. https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com Certifique-se de especificar a versão como parte do url ao fazer pedidos. Mais informações podem ser encontradas na versão API para documentação do serviço DICOM.
  • {caminho-a-dicoms} - O caminho para o diretório que contém o ficheiro red-triangle.dcm, como C:/dicom-server/docs/dcms
    • Certifique-se de que utiliza cortes para a frente como separadores e que termine o diretório sem um corte para a frente.

Upload de DiCOM Instances (STOW)

Casos de loja-utilização multiparte/relacionado

Este pedido pretende demonstrar como carregar ficheiros DICOM utilizando multiparte/relacionados.

Nota

O serviço DICOM é mais brando do que a norma DICOM. No entanto, o exemplo abaixo demonstra um pedido DEM que cumpre rigorosamente a norma.

Detalhes:

  • Caminho: .. /estudos
  • Método: POST
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Tipo de conteúdo: multiparte/relacionado; tipo="aplicação/dicom"
    • Autorização: Portador {valor simbólico}
  • Corpo:
    • Tipo de conteúdo: aplicação/dicom para cada ficheiro carregado, separado por um valor limite

Algumas linguagens e ferramentas de programação comportam-se de forma diferente. Por exemplo, alguns exigem que defina o seu próprio limite. Para estes, poderá ser necessário utilizar um cabeçalho do tipo de conteúdo ligeiramente modificado. Os seguintes foram utilizados com sucesso.

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

Casos de loja para um estudo específico

Este pedido demonstra como fazer o upload de ficheiros DICOM utilizando multiparte/relacionado com um estudo designado.

Detalhes:

  • Caminho: .. /estudos/{estudo}
  • Método: POST
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Tipo de conteúdo: multiparte/relacionado; tipo="aplicação/dicom"
    • Autorização: Portador {valor simbólico}
  • Corpo:
    • Tipo de conteúdo: aplicação/dicom para cada ficheiro carregado, separado por um valor limite

Algumas linguagens e ferramentas de programação comportam-se de forma diferente. Por exemplo, alguns exigem que defina o seu próprio limite. Para estes, poderá ser necessário utilizar um cabeçalho do tipo de conteúdo ligeiramente modificado. Os seguintes foram utilizados com sucesso.

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

Loja de caso único

Nota

Trata-se de uma API não padrão que permite o upload de um único ficheiro DICOM sem a necessidade de configurar o POST para multiparte/relacionado. Embora o cURL lide bem multipart/relacionado, esta API permite que ferramentas como o Carteiro carreguem ficheiros para o serviço DICOM.

É necessário carregar um único ficheiro DICOM.

Detalhes:

  • Caminho: .. /estudos
  • Método: POST
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Tipo de conteúdo: aplicação/dicom
    • Autorização: Portador {valor simbólico}
  • Corpo:
    • Contém um único ficheiro 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"

Recuperação do DICOM (WADO)

Recuperar todos os casos dentro de um estudo

Este pedido recupera todas as instâncias num único estudo e devolve-as como uma coleção de bytes multipartais/relacionados.

Detalhes:

  • Caminho: .. /estudos/{estudo}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: multiparte/relacionado; tipo="aplicação/dicom"; transferência-sintaxe=*
    • Autorização: Portador {valor simbólico}
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 mostrará os bytes descarregados no ficheiro de saída (suppressWarnings.txt), mas estes não são ficheiros DICOM diretos, apenas uma representação de texto do download multiparte/relacionado.

Recuperar metadados de todas as instâncias em estudo

Este pedido recupera os metadados para todos os casos num único estudo.

Detalhes:

  • Caminho: .. /estudos/{estudo}/metadados
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}

Este comando cURL mostrará os bytes descarregados no ficheiro de saída (suppressWarnings.txt), mas estes não são ficheiros DICOM diretos, apenas uma representação de texto do download multiparte/relacionado.

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

Este pedido recupera todas as instâncias dentro de uma única série e devolve-as como uma coleção de bytes multipartais/relacionados.

Detalhes:

  • Caminho: .. /estudos/{study}/series/{series}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: multiparte/relacionado; tipo="aplicação/dicom"; transferência-sintaxe=*
    • Autorização: Portador {valor simbólico}

Este comando cURL mostrará os bytes descarregados no ficheiro de saída (suppressWarnings.txt), mas não é o ficheiro DICOM, apenas uma representação de texto do download multipartes/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 dentro de uma série

Este pedido recupera os metadados para todos os casos num único estudo.

Detalhes:

  • Caminho: .. /estudos/{study}/series/{series}/metadados
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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}"

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

Este pedido recupera uma única instância e devolve-o como um fluxo de bytes formatados pela DICOM.

Detalhes:

  • Caminho: .. /estudos/{study}/series{series}/instances/{instance}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom; transferência-sintaxe=*
    • Autorização: Portador {valor simbólico}
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 estudo

Este pedido recupera os metadados para uma única instância dentro de um único estudo e série.

Detalhes:

  • Caminho: .. /estudos/{study}/series/{series}/instances/{instance}/metadados
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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 um único caso

Este pedido recupera um ou mais quadros de uma única instância, e devolve-os como uma coleção de bytes multipartais/relacionados. Vários quadros podem ser recuperados através de uma lista separada de vírgulas de números de quadros. Todos os casos de DICOM com imagens têm no mínimo um quadro, que é muitas vezes apenas a imagem associada ao próprio caso.

Detalhes:

  • Caminho: .. /studies/{study}/series{series}/instances/{instance}/frames/1,2,3
  • Método: GET
  • Cabeçalhos:
    • Aceitar: multiparte/relacionado; tipo="aplicação/fluxo de octeto"; transposição-sintaxe=1.2.840.10008.1.2.1 (Predefinição) ou
    • Aceitar: multiparte/relacionado; tipo="aplicação/fluxo de octeto"; transferência-sintaxe=* ou
    • Aceitar: multiparte/relacionado; tipo="aplicação/fluxo de octeto";
    • Autorização: Portador {valor simbólico}
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 seguintes exemplos, procuraremos itens usando os seus identificadores únicos. Também pode pesquisar outros atributos, tais como PatientName.

Pesquisa de estudos

Este pedido permite pesquisas de um ou mais estudos por atributos DICOM.

Para obter mais informações sobre os atributos DICOM suportados, consulte a Declaração de Conformidade do DICOM.

Detalhes:

  • Caminho: .. /estudos? StudyInstanceUID={study}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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}"

Pesquisa de séries

Este pedido permite pesquisas de uma ou mais séries por atributos DICOM.

Para obter mais informações sobre os atributos DICOM suportados, consulte a Declaração de Conformidade do DICOM.

Detalhes:

  • Caminho: .. /série? SérieInstanceUID={series}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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}"

Pesquisa de séries dentro de um estudo

Este pedido permite pesquisas de uma ou mais séries dentro de um único estudo por atributos DICOM.

Para obter mais informações sobre os atributos DICOM suportados, consulte a Declaração de Conformidade do DICOM.

Detalhes:

  • Caminho: .. /estudos/{estudo}/série? SérieInstanceUID={series}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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}"

Pesquisar por exemplos

Este pedido permite pesquisas de um ou mais casos por atributos DICOM.

Para obter mais informações sobre os atributos DICOM suportados, consulte a Declaração de Conformidade do DICOM.

Detalhes:

  • Caminho: .. /instâncias? SOPInstanceUID={instância}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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}"

Pesquisa de casos dentro de um estudo

Este pedido permite pesquisas de um ou mais casos dentro de um único estudo por atributos DICOM.

Para obter mais informações sobre os atributos DICOM suportados, consulte a Declaração de Conformidade do DICOM.

Detalhes:

  • Caminho: .. /estudos/{estudo}/instâncias? SOPInstanceUID={instância}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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}"

Pesquisa de casos dentro de um estudo e série

Este pedido permite pesquisas de um ou mais casos dentro de um único estudo e série única por atributos DICOM.

Para obter mais informações sobre os atributos DICOM suportados, consulte a Declaração de Conformidade do DICOM

Detalhes:

  • Caminho: .. /estudos/{study}/series/{series}/instances? SOPInstanceUID={instância}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: aplicação/dicom+json
    • Autorização: Portador {valor simbólico}
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}"

Excluir DICOM

Eliminar um caso específico dentro de um estudo e série

Este pedido elimina uma única instância num único estudo e numa série única.

Eliminar não faz parte do padrão da DICOM, mas foi adicionado por conveniência.

Detalhes:

  • Caminho: .. /estudos/{study}/series/{series}/instances/{instance}
  • Método: EXCLUIR
  • Cabeçalhos:
    • Autorização: Portador {valor simbólico}
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}"

Excluir uma série específica dentro de um estudo

Este pedido elimina uma única série (e todas as instâncias infantis) num único estudo.

Eliminar não faz parte do padrão da DICOM, mas foi adicionado por conveniência.

Detalhes:

  • Caminho: .. /estudos/{study}/series/{series}
  • Método: EXCLUIR
  • Cabeçalhos:
    • Autorização: Portador {valor simbólico}
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}"

Excluir um estudo específico

Este pedido elimina um único estudo (e todas as séries e instâncias infantis).

Eliminar não faz parte do padrão DICOM, mas foi adicionado por conveniência.

Detalhes:

  • Caminho: .. /estudos/{estudo}
  • Método: EXCLUIR
  • Cabeçalhos:
    • Autorização: Portador {valor simbólico}
curl--request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498
--header "Authorization: Bearer {token value}"

Passos Seguintes

Para obter informações sobre o serviço DICOM, consulte