Usar as APIs Standard DICOMweb com cURL

  • Artigo

Esse artigo mostra como trabalhar com o serviço DICOMweb usando o cURL e arquivos .dcm do DICOM® de exemplo.

Use esses 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:

Arquivo 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

Observação

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 Standard DICOM, você deve ter uma instância do serviço DICOM implantada. Para obter mais informações, confira Implantar o serviço DICOM usando o portal do Azure.

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

  1. Entre no portal do Azure.
  2. Pesquise Recursos recentes e selecione sua instância de serviço DICOM.
  3. Copie a URL de Serviço do serviço DICOM.
  4. Se você não tiver um token, confira Obter token de acesso para o serviço DICOM.

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

Trabalhar com o serviço DICOM

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

Os comandos 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 substituindo-as por seus valores específicos:

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

Carregar instâncias DICOM (STOW)

Armazenar instâncias usando multipart/related

Essa solicitação pretende demonstrar como carregar arquivos DICOM usando várias partes/relacionadas.

Observação

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

Detalhes:

  • Path: ../studies
  • Método: POST
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Portador {token value}
  • Corpo:
    • Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

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

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

Armazenar instâncias para um estudo específico

Essa solicitação demonstra como carregar arquivos DICOM usando várias partes/relacionadas a um estudo designado.

Detalhes:

  • Path: ../studies/{study}
  • Método: POST
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Portador {token value}
  • Corpo:
    • Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

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

  • 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

Observação

Essa é 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 manipule bem várias partes/relacionadas, essa API permite que ferramentas como o Postman carreguem arquivos no serviço DICOM.

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

Detalhes:

  • Path: ../studies
  • Método: POST
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Authorization: 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"

Executar upsert de instâncias usando multipart/related

Observação

Essa é uma API não padrão que permite executar upsert de arquivos DICOM usando multipart/related.

Detalhes:

  • Path: ../studies
  • Método: PUT
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Portador {token value}
  • Corpo:
    • Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

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

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

Executar upsert de instâncias para um estudo específico

Observação

Essa é uma API não padrão que permite executar upsert de arquivos DICOM usando multipart/related para um estudo designado.

Detalhes:

  • Path: ../studies/{study}
  • Método: PUT
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Portador {token value}
  • Corpo:
    • Content-Type: application/dicom para cada arquivo carregado, separado por um valor de limite

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

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

Executar upsert de instância única

Observação

Essa é uma API não padrão que permite o upsert de apenas um arquivo DICOM.

Use este método para carregar apenas um arquivo DICOM:

Detalhes:

  • Path: ../studies
  • Método: PUT
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Authorization: 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 em um estudo

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

Detalhes:

  • Path: ../studies/{study}
  • Método: GET
  • Cabeçalhos:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Authorization: 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 de várias partes/relacionado.

Recuperar metadados de todas as instâncias no estudo

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

Detalhes:

  • Path: ../studies/{study}/metadata
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: Portador {token value}

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 de várias partes/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 em uma série

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

Detalhes:

  • Path: ../studies/{study}/series/{series}
  • Método: GET
  • Cabeçalhos:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Authorization: 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 de texto do download de 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:

  • Path: ../studies/{study}/series/{series}/metadata
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: 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 em uma série de um estudo

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

Detalhes:

  • Path: ../studies/{study}/series{series}/instances/{instance}
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom; transfer-syntax=*
    • Authorization: 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 em 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:

  • Path: ../studies/{study}/series/{series}/instances/{instance}/metadata
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: 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 de 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, no mínimo, um quadro, que geralmente é apenas a imagem associada à própria instância.

Detalhes:

  • Path: ../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
  • Método: GET
  • Cabeçalhos:
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (Padrão) ou
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* ou
    • Accept: multipart/related; type="application/octet-stream";
    • Authorization: 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.

Pesquisar estudos

Essa solicitação permite pesquisas para um ou mais estudos por atributos DICOM.

Para obter mais informações sobre os atributos DICOM com suporte, confira a Instrução de conformidade DICOM.

Detalhes:

  • Path: ../studies?StudyInstanceUID={study}
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: Portador {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}"

Pesquisar séries

Essa solicitação permite pesquisas de uma ou mais séries por atributos DICOM.

Para obter mais informações sobre os atributos DICOM com suporte, confira a Instrução de conformidade DICOM.

Detalhes:

  • Path: ../series?SeriesInstanceUID={series}
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: Portador {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}"

Pesquisar séries em um estudo

Essa solicitação permite pesquisas de uma ou mais séries em um único estudo por atributos DICOM.

Para obter mais informações sobre os atributos DICOM com suporte, confira a Instrução de conformidade DICOM.

Detalhes:

  • Path: ../studies/{study}/series?SeriesInstanceUID={series}
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: Portador {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}"

Pesquisar instâncias

Essa solicitação permite pesquisas por uma ou mais instâncias por atributos DICOM.

Para obter mais informações sobre os atributos DICOM com suporte, confira a Instrução de conformidade DICOM.

Detalhes:

  • Path: ../instances?SOPInstanceUID={instance}
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: Portador {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}"

Pesquisar instâncias em um estudo

Essa solicitação permite pesquisar uma ou mais instâncias em um único estudo por atributos DICOM.

Para obter mais informações sobre os atributos DICOM com suporte, confira a Instrução de conformidade DICOM.

Detalhes:

  • Path: ../studies/{study}/instances?SOPInstanceUID={instance}
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: Portador {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}"

Pesquisar instâncias em um estudo e série

Essa solicitação permite pesquisas de uma ou mais instâncias em um único estudo e série única por atributos DICOM.

Para obter mais informações sobre os atributos DICOM com suporte, confira a Instrução de conformidade DICOM

Detalhes:

  • Path: ../studies/{study}/series/{series}/instances?SOPInstanceUID={instance}
  • Método: GET
  • Cabeçalhos:
    • Accept: application/dicom+json
    • Authorization: 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?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Excluir DICOM

Excluir uma instância específica em um estudo e uma série

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

A exclusão não faz parte do DICOM padrão, mas é adicionada para conveniência.

Detalhes:

  • Path: ../studies/{study}/series/{series}/instances/{instance}
  • Método: DELETE
  • Cabeçalhos:
    • Authorization: Portador {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}"

Excluir uma série específica em um estudo

Essa solicitação exclui uma única série (e todas as instâncias filho) em um único estudo.

A exclusão não faz parte do DICOM padrão, mas é adicionada para conveniência.

Detalhes:

  • Path: ../studies/{study}/series/{series}
  • Método: DELETE
  • Cabeçalhos:
    • Authorization: Portador {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}"

Excluir um estudo específico

Essa solicitação exclui um único estudo (e todas as séries e instâncias filho).

A exclusão não faz parte do DICOM padrão, mas é adicionada para conveniência.

Detalhes:

  • Path: ../studies/{study}
  • Método: DELETE
  • Cabeçalhos:
    • Authorization: Portador {token value}
curl--request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498
--header "Authorization: Bearer {token value}"

Observação

DICOM® é a marca registrada da National Electrical Manufacturers Association para suas publicações de padrões relacionados às comunicações digitais de informações médicas.