Use APIs padrão DICOMweb com cURL

  • Artigo

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.

  1. Inicie sessão no portal do Azure.
  2. Pesquise recursos recentes e selecione sua instância de serviço DICOM.
  3. Copie a URL do serviço DICOM.
  4. 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 substituindo-as por 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. Essas ferramentas podem ser usadas com sucesso.

  • 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. Essas ferramentas podem ser usadas com sucesso.

  • 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

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. Estas ferramentas podem ser usadas com sucesso:

  • 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

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. Estas ferramentas podem ser usadas com sucesso:

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

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.

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 geralmente é apenas 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.

Pesquisa de estudos

Esta solicitação permite pesquisar um ou mais estudos por atributos DICOM.

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

Detalhes:

  • Percurso: .. /estudos? StudyInstanceUID={estudo}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: application/dicom+json
    • Autorização: 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}"

Pesquisa de séries

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

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

Detalhes:

  • Percurso: .. /série? SeriesInstanceUID={série}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: application/dicom+json
    • Autorização: 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}"

Pesquisa de séries dentro de um estudo

Esta solicitação permite pesquisar 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 DICOM.

Detalhes:

  • Percurso: .. /estudos/{estudo}/série? SeriesInstanceUID={série}
  • 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?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 para uma ou mais instâncias por atributos DICOM.

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

Detalhes:

  • Percurso: .. /instâncias? SOPInstanceUID={instância}
  • Método: GET
  • Cabeçalhos:
    • Aceitar: application/dicom+json
    • Autorização: 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 dentro de um estudo

Essa solicitação permite pesquisas para uma ou mais instâncias dentro de um único estudo por atributos DICOM.

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

Detalhes:

  • Percurso: .. /studies/{study}/instances? SOPInstanceUID={instância}
  • 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/instances?SOPInstanceUID=1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

Pesquisar instâncias dentro de um estudo e série

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

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

Detalhes:

  • Percurso: .. /studies/{study}/series/{series}/instances? SOPInstanceUID={instância}
  • 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?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 dentro de um estudo e série

Esta solicitação exclui uma única instância dentro de um único estudo e uma única série.

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

Detalhes:

  • Percurso: .. /studies/{study}/series/{series}/instances/{instance}
  • Método: DELETE
  • Cabeçalhos:
    • Autorização: 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 dentro de um estudo

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

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

Detalhes:

  • Percurso: .. /estudos/{estudo}/série/{série}
  • Método: DELETE
  • Cabeçalhos:
    • Autorização: 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}"

Eliminar um estudo específico

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

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

Detalhes:

  • Percurso: .. /estudos/{estudo}
  • Método: DELETE
  • Cabeçalhos:
    • Autorização: Portador {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® é a marca registrada da National Electrical Manufacturers Association para suas publicações de padrões relacionados a comunicações digitais de informações médicas.