DICOM 적합성 명세

Cloud Healthcare API 내의 DICOM 저장소는 DICOM PS3.18-웹 서비스 표준(일반적으로 DICOMweb이라고 함)에 지정된 RESTful 웹 서비스의 하위 집합을 지원합니다. 특히 연구 서비스 및 리소스(이전의 WADO-RS, STOW-RS, QIDO-RS 서비스)를 지원합니다.

또한 Cloud Healthcare API는 DICOM 인스턴스 삭제를 위한 독점 웹 서비스를 지원합니다.

Cloud Healthcare API는 URI 서비스, Worklist 서비스, 비 환자 인스턴스 서비스 또는 모든 기능 트랜잭션을 지원하지 않습니다.

트랜잭션 검색

트랜잭션 검색은 DICOM 이미지 데이터를 검색하기 위한 RESTful 웹 서비스입니다.

트랜잭션 검색은 다음 리소스 검색을 지원합니다.

  • DICOM 리소스:
    • 연구
    • 시리즈
    • 인스턴스
    • 프레임
    • 일괄 데이터
  • 메타데이터 리소스
    • 연구
    • 시리즈
    • 인스턴스
  • 렌더링된 리소스
    • 인스턴스
    • 프레임

미리보기 이미지 리소스를 지원하지 않습니다.

이러한 메서드의 할당량 및 한도에 대한 자세한 내용은 할당량 및 한도를 참조하세요.

DICOM 연구/시리즈/인스턴스

다음과 같은 Accept 헤더가 지원됩니다.

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1(기본)
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*

DICOM 인스턴스

위의 Accept 헤더 허용 외에도 RetrieveInstance는 편의를 위해 단일 부분 콘텐츠 유형을 지원합니다.

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

공식 DICOMweb 표준에 포함되지 않습니다.

DICOM 프레임

다음과 같은 Accept 헤더가 지원됩니다.

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1(기본)
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

*의 전송 구문을 사용하면 사용자가 트랜스코딩을 수행하지 않도록 요청할 수 있으므로 업로드된 파일의 전송 구문이 사용됩니다. application/octet-stream의 경우 대량 데이터는 업로드된 DICOM 파일에 표시되는 형식으로 반환됩니다.

렌더링된 리소스

다음과 같은 Accept 헤더가 지원됩니다.

  • image/jpeg(기본)
  • image/png

인스턴스 또는 프레임 리소스 검색만 지원됩니다.

URL 매개변수는 지원되지 않습니다.

메타데이터 리소스

다음과 같은 Accept 헤더가 지원됩니다.

  • application/dicom+json(기본)
  • multipart/related; type=application/dicom+xml

InlineBinary 요소로 인코딩된 태그는 Little Endian 바이트 순서를 사용하여 인코딩됩니다. 전송 구문 매개변수는 메타데이터 리소스를 요청하는 엔드포인트에서 지원되지 않습니다.

기본적으로 RetrieveMetadata는 DICOM 값 표현이 OB, OW 또는 UN인 속성을 반환하지 않습니다. 미리보기 일괄 데이터 정의와 일치하는 태그에 대해 BulkDataURI를 반환하려면 Preview version을 사용합니다.

약 1MiB를 초과하는 데이터가 포함된 DICOM 시퀀스 태그는 메타데이터 리소스에 반환되지 않습니다. 이 제한사항은 메타데이터 리소스에만 적용됩니다. DICOM 리소스에는 이러한 태그가 계속 포함됩니다.

일괄 데이터 리소스(미리보기)

다음과 같은 Accept 헤더가 지원됩니다.

  • multipart/related; type="application/octet-stream"; transfer-syntax=*(기본)
  • application/octet-stream; transfer-syntax=*

트랜스코딩에 지원되는 전송 구문

위의 Accept 헤더는 API에서 요청할 수 있는 미디어 유형 및 전송 구문을 설명하지만 업로드된 원본 파일의 전송 구문에 따라 항상 가능한 것은 아닙니다. 특히 트랜스코딩은 다음 전송 구문에서만 가능합니다.

  • 1.2.840.10008.1.2(Little Endian Implicit)
  • 1.2.840.10008.1.2.1(Little Endian Explicit)
  • 1.2.840.10008.1.2.2(Explicit VR Big Endian)
  • 1.2.840.10008.1.2.4.50(JPEG Baseline Process 1)
  • 1.2.840.10008.1.2.4.57(JPEG Lossless)
  • 1.2.840.10008.1.2.4.70(JPEG Lossless Selection Value 1)
  • 1.2.840.10008.1.2.4.90(JPEG 2000 Lossless Only)
  • 1.2.840.10008.1.2.4.91(JPEG 2000)
  • 1.2.840.10008.1.2.5(RLE Lossless)

원본 파일의 전송 구문이 위의 목록에 없는 경우 다른 형식으로 트랜스코딩을 요청하면 오류가 반환됩니다.

Cloud Healthcare API는 비트 깊이가 8 이상인 단색 외 이미지를 JPEG로 트랜스코딩할 수 없습니다. 또한 할당된 비트 값(0028, 0100)이 1이거나 Float Pixel 데이터(7FE0,0008), Double Float Pixel 데이터(7FE0,0009) 태그에 저장된 이미지는 기본 형식 간에만 트랜스코딩될 수 있습니다.

트랜스코딩을 사용 중지하고 API에서 파일을 가져오려면 Accept 헤더에 transfer-syntax=*를 설정하면 됩니다.

상태 코드

코드 의미
200 (OK) 응답 페이로드에는 모든 대상 리소스에 대한 표현이 포함됩니다.
400 (Bad Request) 지정된 대상 리소스(예: 픽셀 데이터 누락)에 대한 요청이 잘못되었습니다(예: 잘못된 쿼리 매개변수 또는 헤더).
401 (Unauthorized) 요청에 인증 사용자 인증 정보가 누락되었습니다.
403 (Permission Denied) 인증된 사용자가 이 리소스에 액세스할 수 없거나 리소스가 존재하지 않습니다.
406 (Not Acceptable) 서버가 사용 가능한 미디어 유형을 지원하지 않습니다.
429 (Too Many Requests) 클라이언트가 해당 할당량을 초과합니다.
503 (Service Unavailable) 서버를 현재 사용할 수 없거나 요청이 기한을 초과했습니다.

Store 트랜잭션

Store 트랜잭션은 DICOM 이미지 데이터를 저장하기 위한 RESTful 웹 서비스입니다.

Store 트랜잭션은 Part 10 DICOM 바이너리 파일을 직접 허용하거나 DICOM 파일을 메타데이터(JSON으로 표시) 및 대량 데이터로 분할하는 것을 허용합니다. 이 두 버전에는 다음 섹션에서 설명하는 시맨틱스가 다릅니다.

이 메서드의 할당량 및 한도에 대한 자세한 내용은 할당량 및 한도를 참조하세요.

DICOM part 10 바이너리 파일

지원되는 콘텐츠 유형은 다음과 같습니다.

  • multipart/related; type=application/dicom
  • application/dicom

속성의 유도 또는 대체가 서버에서 수행되지 않습니다.

이 버전에서는 모든 전송 구문 및 SOP 클래스가 허용됩니다. 일부 키 메타데이터 속성을 추출하기 위해 DICOM 파일의 최소 검사만 수행됩니다.

편의 상 Store 트랜잭션은 콘텐츠 유형이 application/dicom인 단일 DICOM 인스턴스가 있는 단일 부분 HTTP 요청도 허용합니다. 공식 DICOMweb 표준에 포함되지 않습니다.

관련 안내 가이드는 DICOM 인스턴스 저장을 참조하세요.

JSON 메타데이터 및 대량 데이터 요청

JSON 메타데이터 및 대량 데이터를 사용하여 인스턴스를 저장할 때 첫 번째 멀티파트 부분은 DICOM 인스턴스의 JSON 배열로 구성되어야 합니다.

첫 번째 부분의 콘텐츠 유형은 application/dicom+json; transfer-syntax=TransferSyntaxUID여야 합니다. 여기서 TransferSyntaxUID는 InlineBinary 객체의 바이너리 데이터를 인코딩하는 데 사용된 전송 구문입니다. 메타데이터에 InlineBinary 객체가 없으면 transfer-syntax 매개변수를 생략할 수 있습니다.

다음 DICOM 요소는 JSON 메타데이터의 모든 인스턴스에 있어야 합니다.

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

SpecificCharacterSet 요소는 ISO_IR 192로 설정해야 하며 JSON 메타데이터는 유니코드 UTF-8로 인코딩해야 합니다. TransferSyntaxUID는 지원되지 않는 다음 전송 구문을 제외하고 유효한 전송 구문으로 설정할 수 있습니다.

  • 1.2.840.10008.1.2.2(Explicit VR Big Endian)
  • 1.2.840.10008.1.2.1.99(Deflated Explicit VR Little Endian)

사용자는 JSON 메타데이터 내에서 OB, OW 또는 UN의 VR을 사용하여 DICOM 태그에 여러 BulkDataURI를 지정할 수 있습니다. 이러한 BulkDataURI는 URI가 포함된 태그의 바이너리 데이터가 Content-Location 헤더가 BulkDataURI로 설정된 다음 부분으로 전송됨을 나타냅니다.

JSON 메타데이터의 각 인스턴스에는 BulkDataURI가 최대 한 개 포함될 수 있습니다. JSON 메타데이터에 중복되는 BulkDataURI가 없어야 합니다. 압축된 이미지 대량 데이터는 PixelData 태그에 대해서만 전송되어야 하며 대량 데이터 부분에 지정된 전송 구문은 인스턴스의 TransferSyntaxUID 요소 값과 일치해야 합니다.

다음은 대량 데이터 부분에 대해 지원되는 Content-Type입니다.

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

바이너리 데이터를 지정하는 다른 방법은 InlineBinary base64 인코딩 문자열로 인코딩하는 것입니다. 이는 대량 데이터 부분으로 전송해야 하는 PixelData를 제외한 모든 태그에서 지원됩니다. JSON 메타데이터에 InlineBinary 객체가 사용되는 경우 인코딩에 사용된 전송 구문은 JSON 메타데이터 부분의 Content-Type에 지정되어야 합니다.

서버가 이미지 픽셀 설명 매크로 속성을 파생하지 않습니다.

관련 안내 가이드는 JSON 메타데이터 및 JPEG 파일에서 DICOM 인스턴스 만들기를 참조하세요.

응답

오류가 발생하면 추가 FailureDetail(0009, 0097) 태그(XML 응답용) 또는 FailedDetailJSON(0009,1097) 태그(JSON 응답용)가 반환됩니다. FailedDetail 태그는 인간이 읽을 수 있는 오류 설명을 제공합니다.

DICOM 인스턴스의 <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> 튜플이 DICOM 저장소에 이미 있는 다른 인스턴스의 튜플과 동일한 경우 '이미 존재함' FailureDetail 태그와 함께 처리 실패 오류가 반환됩니다.

응답은 JSON 또는 XML 형식일 수 있으며, 다음의 Accept 헤더 값을 통해 제어할 수 있습니다.

  • application/dicom+xml(기본)
  • application/dicom+json

상태 코드

코드 의미
200 (OK) 리소스가 성공적으로 저장되었습니다.
400 (Bad Request) 요청이 잘못되었습니다(예: 지원되지 않는 미디어 유형 또는 전송 구문).
401 (Unauthorized) 요청에 인증 사용자 인증 정보가 누락되었습니다.
403 (Permission Denied) 인증된 사용자가 이 리소스에 액세스할 수 없거나 리소스가 존재하지 않습니다.
406 (Not Acceptable) 서버가 사용 가능한 미디어 유형을 지원하지 않습니다.
409 (Conflict) 리소스가 하나 이상 성공적으로 저장되지 않았습니다(예: 부적합한 DICOM 파일). 자세한 내용은 응답 본문에서 FailureDetail 태그를 확인하세요.
429 (Too Many Requests) 클라이언트가 해당 할당량을 초과합니다.
503 (Service Unavailable) 서버를 현재 사용할 수 없거나 요청이 기한을 초과했습니다.

Search 트랜잭션

Search 트랜잭션은 DICOM 이미지 메타데이터를 쿼리하기 위한 RESTful 웹 서비스입니다.

Cloud Healthcare API는 연구, 시리즈, 인스턴스 검색을 지원합니다.

검색 매개변수

다음 태그를 사용한 검색이 지원됩니다.

  • 연구:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • 시리즈: 모든 연구 수준 검색어 및
    • SeriesInstanceUID
    • 형식
  • 인스턴스: 모든 연구 및 시리즈 수준 검색어 및
    • SOPInstanceUID

단일 값만 일치검색이 지원됩니다. 단, 범위 쿼리를 지원하는 StudyDate 및 퍼지 일치를 지원하는 PatientName은 예외입니다.

다음과 같은 추가 URL 매개변수가 지원됩니다.

  • fuzzymatching: true로 설정하면 퍼지 일치가 PatientName 태그에 적용됩니다. 퍼지 일치는 쿼리의 PatientName 값과 저장된 값을 토큰화하고 정규화합니다. 검색 토큰이 저장된 토큰의 프리픽스인 경우 일치합니다. 예를 들어 PatientName이 'John^Doe'인 경우 'jo', 'Do', 'John Doe'가 모두 일치합니다. 하지만 'ohn'은 일치하지 않습니다.
  • includefield: 쉼표로 구분된 attributeID 목록(예: DICOM 태그 ID 또는 키워드)으로 설정하거나 all 값으로 설정하여 사용 가능한 모든 태그를 반환할 수 있습니다. 사용 가능한 태그 목록은 반환된 결과를 참조하세요.

페이징은 limit 및 offset 쿼리 매개변수를 사용하여 지원됩니다. 사용할 수 있는 결과가 없으면 경고 응답 헤더가 없습니다. 결과가 더 있는지 확인하려면 추가 쿼리를 실행해야 합니다.

  • limit: 반환해야 하는 결과의 최대 개수입니다. 연구/시리즈의 경우 최대 5,000개, 인스턴스의 경우 최대 50,000개입니다. 기본 결과 수는 연구/시리즈 100개, 인스턴스 1,000개입니다.

  • offset: 초기에 최대 1,000,000까지 건너 뛸 결과 수입니다.

UTC의 시간대 오프셋은 지원되지 않습니다.

반환된 결과

응답은 JSON 또는 XML 형식일 수 있으며, 다음의 Accept 헤더 값을 사용해서 제어할 수 있습니다.

  • application/dicom+json(기본)
  • multipart/related; type=application/dicom+xml

기본적으로 다음 속성이 반환됩니다.

  • 연구:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • 시리즈:
    • SpecificCharacterSet
    • 형식
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • 인스턴스:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • 행
    • 열
    • BitsAllocated
    • NumberOfFrames

includefield=all의 경우, 기본 속성이 다음 속성과 함께 반환됩니다.

  • 연구:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • 시리즈:
    • SeriesNumber
    • Laterality
    • SeriesDate
    • SeriesTime
  • 인스턴스: 다음 예외를 제외하고 DICOM 인스턴스에 있는 모든 속성입니다.

기본적으로 searchForInstances는 DICOM 값 표현이 OB, OW 또는 UN인 속성을 반환하지 않습니다. 미리보기 일괄 데이터 정의와 일치하는 태그에 대해 BulkDataURI를 반환하려면 미리보기 searchForInstances를 사용합니다.

약 1MiB를 초과하는 데이터가 포함된 DICOM 시퀀스 태그는 메타데이터 응답에서 반환되지 않습니다.

일치하지 않거나 잘못된 메타데이터

SearchForStudies/SearchForSeries의 경우 여러 인스턴스 간에 연구/시리즈 수준 메타데이터가 일치하지 않을 수 있습니다. 예를 들어 동일한 StudyInstanceUID로 두 인스턴스를 업로드할 수 있지만 StudyDates가 달라야 합니다. 이 경우 검색 동작은 잘 정의되지 않습니다. 이 값을 사용한 검색이 일부 경우에는 작동할 수 있지만 다른 경우에는 실패할 수 있으며, 반환되는 값이 각 호출마다 달라질 수 있습니다.

상태 코드

코드 의미
200 (OK) 응답 페이로드에는 모든 대상 리소스에 대한 표현이 포함됩니다.
400 (Bad Request) 요청이 잘못되었습니다(예: 잘못된 쿼리 매개변수).
401 (Unauthorized) 요청에 인증 사용자 인증 정보가 누락되었습니다.
403 (Permission Denied) 인증된 사용자가 이 리소스에 액세스할 수 없거나 리소스가 존재하지 않습니다.
406 (Not Acceptable) 서버가 사용 가능한 미디어 유형을 지원하지 않습니다.
429 (Too Many Requests) 클라이언트가 해당 할당량을 초과합니다.
503 (Service Unavailable) 서버를 현재 사용할 수 없거나 요청이 기한을 초과했습니다.

삭제

Cloud Healthcare API는 다음 고유 작업 유형을 지원합니다.

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

이것들은 WADO-RS 항목과 동일한 요청 경로를 사용합니다(각각 RetrieveStudy, RetrieveSeries, RetrieveInstance). HTTP GET 요청 대신 DELETE 요청이 사용됩니다. 그 결과 모든 DICOM 리소스가 포함된 상태로 지정된 연구, 시리즈, 인스턴스가 삭제됩니다.

DeleteStudy 및 DeleteSeries 메서드는 연구 또는 시리즈의 모든 인스턴스를 삭제하는 장기 실행 작업을 반환합니다. 인스턴스는 작업이 완료될 때까지 작업에 의해 삭제되는 연구 또는 시리즈에 삽입할 수 없습니다.

작업에 대한 안내 가이드는 장기 실행 작업 관리를 참조하세요.

DeleteInstance 요청이 성공하면 빈 응답이 반환됩니다.

상태 코드

코드 의미
200 (OK) 요청 리소스가 삭제되었습니다.
400 (Bad Request) 요청이 잘못되었습니다.
401 (Unauthorized) 요청에 인증 사용자 인증 정보가 누락되었습니다.
403 (Permission Denied) 인증된 사용자가 이 리소스에 액세스할 수 없거나 리소스가 존재하지 않습니다.
429 (Too Many Requests) 클라이언트가 해당 할당량을 초과합니다.
503 (Service Unavailable) 서버를 현재 사용할 수 없거나 요청이 기한을 초과했습니다.

Accept 헤더

위 메서드 중 일부는 HTTP Accept 헤더를 사용하여 응답 형식을 제어하는 기능을 제공합니다. 와일드 카드 일치는 최상위 수준(예: */*)과 하위유형(예: image/*) 모두에서 지원됩니다. q 값 지정도 상대적 환경설정을 나타내기 위해 지원됩니다. q 값이 Accept 헤더에 지정되지 않으면 기본값 1.0으로 설정됩니다.

여러 Accept 헤더가 지정되고 가장 선호되는 Accept 헤더 사이에 동점이 있는 경우 서버는 Accept 헤더를 선택합니다. 이 시나리오에서 클라이언트는 서버의 Accept 헤더 선택에 의존해서는 안 됩니다.

지원되는 SOP 클래스

Cloud Healthcare API는 모든 DICOM SOP 클래스의 수집 및 기본 검색을 수행할 수 있습니다. 이미지 형식 간 트랜스코딩이 필요한 검색의 경우 지원되는 전송 구문 목록은 트랜스코딩에 지원되는 전송 구문을 참조하세요.

일괄 데이터 태그 정의(미리보기)

미리보기 메서드로 메타데이터를 검색할 때 Cloud Healthcare API는 일괄 데이터로 정의된 특정 태그를 제외합니다. 대신 이러한 태그는 사용자가 이러한 태그의 콘텐츠를 검색할 수 있게 허용하는 BulkDataURI 포함 메타데이터와 함께 반환됩니다(RetrieveBulkdata 참조). 다음은 Cloud Healthcare API에서 사용되는 정의입니다.

  • 모든 픽셀 데이터 태그: (7FE0,0008), (7FE0,0009) (7FE0,0010)
  • VR이 OB, OW, UN인 모든 태그
  • VR이 OD, OF 또는 OL이고 2KiB보다 큰 태그
    • 기존 이유로, Cloud Healthcare API에 이미 수집된 인스턴스의 태그는 태그가 256B(OF 및 OL) 또는 512B(OD)보다 큰 경우 일괄 데이터로 간주될 수 있습니다.
  • VR이 AT, FD, FL, UL, US이고 값 다양성(VM)이 512보다 큰 태그
    • 기존 이유로, Cloud Healthcare API에 이미 수집된 인스턴스의 태그는 VM이 64보다 크면 일괄 데이터로 간주될 수 있습니다.

또한 다음 태그는 일괄 데이터로 고려되지만 메타데이터 메서드에서 반환되었을 때 BulkDataURI가 없으며 RetrieveBulkdata를 사용해서 콘텐츠를 검색할 수 없습니다.

  • VR이 SQ이고 크기가 약 1MiB보다 큰 태그