cURL과 함께 DICOMweb 표준 API 사용

  • 아티클

이 문서에서는 cURL 및 샘플 .dcm DICOM® 파일을 사용하여 DICOMweb 서비스를 사용하는 방법을 보여줍니다.

다음 샘플 파일을 사용합니다.

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

샘플 DICOM 파일의 파일 이름, studyUID, seriesUID 및 instanceUID는 다음과 같습니다.

파일 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

참고 항목

각 파일은 하나의 인스턴스를 나타내며 동일한 연구의 일부입니다. 또한 녹색 사각형과 빨간색 삼각형은 동일한 계열이며, 파란색 원은 별도의 계열입니다.

필수 조건

DICOM 표준 API를 사용하려면 DICOM 서비스의 인스턴스가 배포되어 있어야 합니다. 자세한 내용은 Azure Portal을 사용하여 DICOM 서비스 배포를 참조하세요.

DICOM 서비스의 인스턴스를 배포한 후 App Service의 URL을 검색합니다.

  1. Azure Portal에 로그인합니다.
  2. 최신 리소스를 검색하고 DICOM 서비스 인스턴스를 선택합니다.
  3. DICOM 서비스의 서비스 URL을 복사합니다.
  4. 액세스 토큰이 필요한 경우 DICOM 서비스에 대한 액세스 토큰 가져오기를 참조하세요.

이 코드의 경우 공개 미리 보기 Azure Service에 액세스합니다. 개인 의료 정보(PHI)를 업로드하지 않는 것이 중요합니다.

DICOM 서비스 작업

DICOMweb 표준은 DICOM 특정 수락 헤더와 결합된 multipart/related HTTP 요청을 많이 사용합니다. 다른 REST 기반 API에 익숙한 개발자는 DICOMweb 표준을 사용하는 것이 불편할 수 있습니다. 그러나 실행한 후에는 사용하기 쉽습니다. 시작하기 위해서는 약간의 적응이 필요합니다.

cURL 명령에는 각각 교체해야 하는 변수가 적어도 1개, 때때로 2개가 포함되어 있습니다. 명령 실행을 간소화하려면 다음 변수를 검색하여 특정 값으로 바꿉니다.

  • {Service URL} 서비스 URL은 Azure Portal에서 프로비전한 DICOM 서비스에 액세스하기 위한 URL로 예를 들면 https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com입니다. 요청할 때는 버전을 URL의 일부로 지정해야 합니다. 자세한 내용은 DICOM 서비스용 API 버전 관리 설명서에서 찾을 수 있습니다.
  • {path-to-dicoms} - red-triangle.dcm 파일이 포함된 디렉터리의 경로(예: C:/dicom-server/docs/dcms)
    • 슬래시를 구분 기호로 사용하고 후행 슬래시 없이디렉터리를 종료해야 합니다.

DICOM 인스턴스 업로드(STOW)

multipart/related를 사용하여 인스턴스 저장

이 요청은 multipart/related를 사용하여 DICOM 파일을 업로드하는 방법을 보여 줍니다.

참고 항목

DICOM 서비스는 DICOM 표준보다 더 관대합니다. 그러나 이 예제에서는 표준을 엄격하게 준수하는 POST 요청을 보여 줍니다.

세부 정보:

  • 경로: ../studies
  • 메서드: POST
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {token value}
  • 본문:
    • Content-Type: 업로드된 각 파일에 대해 application/dicom, 경계 값으로 구분

일부 프로그래밍 언어 및 도구는 다르게 동작합니다. 예를 들어 일부는 고유한 경계를 정의해야 합니다. 이러한 도구의 경우 약간 수정된 Content-Type 헤더를 사용해야 할 수 있습니다. 이러한 도구를 성공적으로 사용할 수 있습니다.

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

특정 연구에 대한 인스턴스 저장

이 요청은 지정된 연구에 대해 multipart/related를 사용하여 DICOM 파일을 업로드하는 방법을 보여 줍니다.

세부 정보:

  • 경로: ../studies/{study}
  • 메서드: POST
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {token value}
  • 본문:
    • Content-Type: 업로드된 각 파일에 대해 application/dicom, 경계 값으로 구분

일부 프로그래밍 언어 및 도구는 다르게 동작합니다. 예를 들어 일부는 고유한 경계를 정의해야 합니다. 이러한 언어 및 도구의 경우 약간 수정된 Content-Type 헤더를 사용해야 할 수 있습니다. 이러한 도구를 성공적으로 사용할 수 있습니다.

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

저장소 단일 인스턴스

참고 항목

multipart/related에 대해 POST를 구성할 필요 없이 단일 DICOM 파일을 업로드할 수 있는 비표준 API입니다. cURL은 multipart/related를 잘 처리하지만 이 API를 사용하면 Postman과 같은 도구에서 DICOM 서비스에 파일을 업로드할 수 있습니다.

단일 DICOM 파일을 업로드하려면 다음 메서드가 필요합니다.

세부 정보:

  • 경로: ../studies
  • 메서드: POST
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Authorization: Bearer {token value}
  • 본문:
    • 단일 DICOM 파일을 이진 바이트로 포함합니다.
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"

multipart/related를 사용하는 Upsert 인스턴스

참고 항목

다중 파트/관련 파일을 사용하여 DICOM 파일의 upsert를 허용하는 비표준 API입니다.

세부 정보:

  • 경로: ../studies
  • 메서드: PUT
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {token value}
  • 본문:
    • Content-Type: 업로드된 각 파일에 대해 application/dicom, 경계 값으로 구분

일부 프로그래밍 언어 및 도구는 다르게 동작합니다. 예를 들어 일부는 고유한 경계를 정의해야 합니다. 이러한 도구의 경우 약간 수정된 Content-Type 헤더를 사용해야 할 수 있습니다. 이러한 도구를 성공적으로 사용할 수 있습니다.

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

특정 연구를 위한 Upsert 인스턴스

참고 항목

지정된 연구와 관련된 다중 파트를 사용하여 DICOM 파일의 upsert를 허용하는 비표준 API입니다.

세부 정보:

  • 경로: ../studies/{study}
  • 메서드: PUT
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: multipart/related; type="application/dicom"
    • Authorization: Bearer {token value}
  • 본문:
    • Content-Type: 업로드된 각 파일에 대해 application/dicom, 경계 값으로 구분

일부 프로그래밍 언어 및 도구는 다르게 동작합니다. 예를 들어 일부는 고유한 경계를 정의해야 합니다. 이러한 언어 및 도구의 경우 약간 수정된 Content-Type 헤더를 사용해야 할 수 있습니다. 이러한 도구를 성공적으로 사용할 수 있습니다.

  • 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 단일 인스턴스

참고 항목

단일 DICOM 파일의 upsert를 허용하는 비표준 API입니다.

이 메서드를 사용하여 단일 DICOM 파일을 업로드합니다.

세부 정보:

  • 경로: ../studies
  • 메서드: PUT
  • Headers:
    • Accept: application/dicom+json
    • Content-Type: application/dicom
    • Authorization: Bearer {token value}
  • 본문:
    • 단일 DICOM 파일을 이진 바이트로 포함합니다.
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"

DICOM 검색(WADO)

연구 내 모든 인스턴스 검색

이 요청은 단일 연구 내 모든 인스턴스를 검색하고 다중 파트/관련 바이트의 컬렉션으로 반환합니다.

세부 정보:

  • 경로: ../studies/{study}
  • 메서드: GET
  • Headers:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Authorization: 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"

이 cURL 명령은 출력 파일(suppressWarnings.txt)에서 다운로드한 바이트를 표시하지만 DICOM 다이렉트 파일이 아니라 다중 파트/관련 다운로드의 텍스트 표현만 표시합니다.

연구에서 모든 인스턴스의 메타데이터 검색

이 요청은 단일 연구 내 모든 인스턴스에 대한 메타데이터를 검색합니다.

세부 정보:

  • 경로: ../studies/{study}/metadata
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: Bearer {token value}

이 cURL 명령은 출력 파일(suppressWarnings.txt)에서 다운로드한 바이트를 표시하지만 DICOM 다이렉트 파일이 아니라 다중 파트/관련 다운로드의 텍스트 표현만 표시합니다.

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

계열 내 모든 인스턴스 검색

이 요청은 단일 계열 내 모든 인스턴스를 검색하고 다중 파트/관련 바이트의 컬렉션으로 반환합니다.

세부 정보:

  • 경로: ../studies/{study}/series/{series}
  • 메서드: GET
  • Headers:
    • Accept: multipart/related; type="application/dicom"; transfer-syntax=*
    • Authorization: Bearer {token value}

이 cURL 명령은 출력 파일(suppressWarnings.txt)에서 다운로드한 바이트를 표시하지만 DICOM 파일이 아니라 다중 파트/관련 다운로드의 텍스트 표현만 표시합니다.

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"

계열 내에서 모든 인스턴스의 메타데이터 검색

이 요청은 단일 연구 내 모든 인스턴스에 대한 메타데이터를 검색합니다.

세부 정보:

  • 경로: ../studies/{study}/series/{series}/metadata
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

단일 연구의 단일 계열 내에서 단일 인스턴스 검색

이 요청은 단일 인스턴스를 검색하고 DICOM 형식의 바이트 스트림으로 반환합니다.

세부 정보:

  • 경로: ../studies/{study}/series{series}/instances/{instance}
  • 메서드: GET
  • Headers:
    • Accept: application/dicom; transfer-syntax=*
    • Authorization: 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"

단일 연구의 단일 계열 내에서 단일 인스턴스의 메타데이터 검색

이 요청은 단일 연구 및 계열 내 단일 인스턴스에 대한 메타데이터를 검색합니다.

세부 정보:

  • 경로: ../studies/{study}/series/{series}/instances/{instance}/metadata
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

단일 인스턴스에서 하나 이상의 프레임 검색

이 요청은 단일 인스턴스에서 하나 이상의 프레임을 검색하고 다중 파트/관련 바이트의 컬렉션으로 반환합니다. 쉼표로 구분된 프레임 번호 목록을 전달하여 여러 프레임을 검색할 수 있습니다. 이미지가 있는 모든 DICOM 인스턴스에는 하나 이상의 프레임이 있으며, 이는 종종 인스턴스 자체와 연결된 이미지일 뿐입니다.

세부 정보:

  • 경로: ../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
  • 메서드: GET
  • Headers:
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (Default) or
    • Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* or
    • Accept: multipart/related; type="application/octet-stream";
    • Authorization: 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"

DICOM 쿼리(QIDO)

다음 예제에서는 고유 식별자를 사용하여 항목을 검색합니다. PatientName과 같은 다른 특성을 검색할 수도 있습니다.

연구 검색

이 요청을 사용하면 DICOM 특성별로 하나 이상의 연구를 검색할 수 있습니다.

지원되는 DICOM 특성에 대한 자세한 내용은 DICOM 규칙 문을 참조하세요.

세부 정보:

  • 경로: ../studies?StudyInstanceUID={study}
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

계열 검색

이 요청을 사용하면 DICOM 특성별로 하나 이상의 계열을 검색할 수 있습니다.

지원되는 DICOM 특성에 대한 자세한 내용은 DICOM 규칙 문을 참조하세요.

세부 정보:

  • 경로: ../series?SeriesInstanceUID={series}
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

연구 내 계열 검색

이 요청을 사용하면 DICOM 특성별 단일 연구 내에서 하나 이상의 계열을 검색할 수 있습니다.

지원되는 DICOM 특성에 대한 자세한 내용은 DICOM 규칙 문을 참조하세요.

세부 정보:

  • 경로: ../studies/{study}/series?SeriesInstanceUID={series}
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

인스턴스 검색

이 요청을 사용하면 DICOM 특성별로 하나 이상의 인스턴스를 검색할 수 있습니다.

지원되는 DICOM 특성에 대한 자세한 내용은 DICOM 규칙 문을 참조하세요.

세부 정보:

  • 경로: ../instances?SOPInstanceUID={instance}
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

연구 내 인스턴스 검색

이 요청을 사용하면 DICOM 특성별로 단일 연구 내에서 하나 이상의 인스턴스를 검색할 수 있습니다.

지원되는 DICOM 특성에 대한 자세한 내용은 DICOM 규칙 문을 참조하세요.

세부 정보:

  • 경로: ../studies/{study}/instances?SOPInstanceUID={instance}
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

연구 및 계열 내 인스턴스 검색

이 요청을 사용하면 DICOM 특성별로 단일 연구 및 단일 계열 내에서 하나 이상의 인스턴스를 검색할 수 있습니다.

지원되는 DICOM 특성에 대한 자세한 내용은 DICOM 규칙 문을 참조하세요.

세부 정보:

  • 경로: ../studies/{study}/series/{series}/instances?SOPInstanceUID={instance}
  • 메서드: GET
  • Headers:
    • Accept: application/dicom+json
    • Authorization: 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}"

DICOM 삭제

연구 및 계열 내 특정 인스턴스 삭제

이 요청은 단일 연구 및 단일 계열 내에서 단일 인스턴스를 삭제합니다.

삭제는 DICOM 표준의 일부는 아니지만 편의를 위해 추가됩니다.

세부 정보:

  • 경로: ../studies/{study}/series/{series}/instances/{instance}
  • 메서드: DELETE
  • Headers:
    • Authorization: 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}"

연구 내 특정 계열 삭제

이 요청은 단일 연구 내에서 단일 계열(및 모든 자식 인스턴스)을 삭제합니다.

삭제는 DICOM 표준의 일부는 아니지만 편의를 위해 추가됩니다.

세부 정보:

  • 경로: ../studies/{study}/series/{series}
  • 메서드: DELETE
  • Headers:
    • Authorization: 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}"

특정 연구 삭제

이 요청은 단일 연구(및 모든 자식 계열 및 인스턴스)를 삭제합니다.

삭제는 DICOM 표준의 일부는 아니지만 편의를 위해 추가됩니다.

세부 정보:

  • 경로: ../studies/{study}
  • 메서드: DELETE
  • Headers:
    • Authorization: Bearer {token value}
curl--request DELETE "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498
--header "Authorization: Bearer {token value}"

참고 항목

DICOM®은 의료 정보의 디지털 통신과 관련된 표준 간행물에 대한 미국 전기공업회의 등록 상표입니다.