확장 쿼리 태그

아티클
03/15/2024

기본값으로 DICOM® 서비스는 적합성 선언문에 지정된 DICOM 태그에 대한 쿼리를 지원합니다. 확장 쿼리 태그를 사용하도록 설정하면 애플리케이션의 요구에 따라 태그 목록을 쉽게 확장할 수 있습니다.

사용자는 아래에 나열된 API를 사용하여 표준 DICOM 태그와 프라이빗 DICOM 태그 모두에 사용자의 DICOM 연구, 시리즈 및 인스턴스를 인덱싱하여 QIDO-RS 쿼리에 지정할 수 있습니다.

API

버전: v1

지정된 DICOM 서비스 인스턴스에서 지원되는 태그를 쉽게 관리하기 위해 다음 API 엔드포인트가 추가되었습니다.

API	설명
POST .../extendedquerytags	확장 쿼리 태그 추가
GET .../extendedquerytags	확장 쿼리 태그 나열
GET .../extendedquerytags/{tagPath}	확장 쿼리 태그 가져오기
DELETE .../extendedquerytags/{tagPath}	확장 쿼리 태그 삭제
PATCH .../extendedquerytags/{tagPath}	확장 쿼리 태그 업데이트
GET .../extendedquerytags/{tagPath}/errors	확장 쿼리 태그 오류 나열
GET .../operations/{operationId}	가져오기 작업

확장 쿼리 태그 추가

하나 이상의 확장 쿼리 태그를 추가하고, 지정된 태그를 사용하여 현재의 DICOM 인스턴스를 다시 인덱싱하는 장기 실행 작업을 시작합니다.

POST .../extendedquerytags

요청 헤더

이름	필수	Type	설명
Content-Type	True	string	`application/json`가 지원됨

요청 본문

이름	필수	Type	설명
본문		추가를 위한 확장 쿼리 태그`[]`

제한 사항

지원되는 VR 유형은 다음과 같습니다.

VR	설명	단일 값 일치	범위 일치	유사 일치
AE	애플리케이션 엔터티	X
AS	나이 문자열	X
CS	코드 문자열	X
DA	날짜	X	X
DS	10진 문자열	X
DT	날짜 및 시간	X	X
FD	부동 소수점 더블	X
FL	부동 소수점 싱글	X
IS	정수 문자열	X
LO	긴 문자열	X
PN	사용자 이름	X		X
SH	짧은 문자열	X
SL	부호 있는 긴	X
SS	부호 있는 짧은	X
TM	Time	X	X
UI	고유 식별자	X
UL	부호 없는 긴	X
US	부호 없는 짧은	X

참고 항목

SQ(Sequence of Items) 형식의 태그에 속하는 연속 태그는 현재 지원되지 않습니다. 확장 쿼리 태그를 최대 128개까지 추가할 수 있습니다. 값이 null이거나 비어 있는 경우 확장 쿼리 태그를 인덱싱하지 않습니다.

응답

이름	형식	설명
202(수락됨)	작업 참조	확장 쿼리 태그가 추가되었으며 기존 DICOM 인스턴스를 다시 인덱싱하기 위해 장기 실행 작업이 시작되었습니다
400(잘못된 요청)		요청 본문에 잘못된 데이터가 있습니다
409(충돌)		요청된 쿼리 태그가 이미 하나 이상 지원되고 있습니다

확장 쿼리 태그 나열

모든 확장 쿼리 태그의 목록입니다.

GET .../extendedquerytags

응답

이름	형식	설명
200(OK)	확장 쿼리 태그`[]`	확장 쿼리 태그를 반환합니다

확장 쿼리 태그 가져오기

확장 쿼리 태그를 가져옵니다.

GET .../extendedquerytags/{tagPath}

URI 매개 변수

이름	그런 다음	필수	Type	설명
tagPath	path	True	string	tagPath는 태그의 경로로, 태그 또는 키워드가 될 수 있습니다. 예를 들어 환자 ID는 `00100020` 또는 `PatientId`로 표현됩니다

응답

이름	형식	설명
200(OK)	확장 쿼리 태그	`tagPath`가 지정된 확장 쿼리 태그
400(잘못된 요청)		요청된 태그 경로가 잘못되었습니다
404(찾을 수 없음)		요청된 tagPath가 있는 확장 쿼리 태그를 찾을 수 없습니다

확장 쿼리 태그 삭제

확장 쿼리 태그를 삭제합니다.

DELETE .../extendedquerytags/{tagPath}

URI 매개 변수

이름	그런 다음	필수	Type	설명
tagPath	path	True	string	tagPath는 태그의 경로로, 태그 또는 키워드가 될 수 있습니다. 예를 들어 환자 ID는 `00100020` 또는 `PatientId`로 표현됩니다

응답

이름	형식	설명
204(내용 없음)		요청된 tagPath가 있는 확장 쿼리 태그가 성공적으로 삭제되었습니다.
400(잘못된 요청)		요청된 태그 경로가 잘못되었습니다.
404(찾을 수 없음)		요청된 tagPath가 있는 확장 쿼리 태그를 찾을 수 없습니다

확장 쿼리 태그 업데이트

확장 쿼리 태그를 업데이트합니다.

PATCH .../extendedquerytags/{tagPath}

URI 매개 변수

이름	그런 다음	필수	Type	설명
tagPath	path	True	string	tagPath는 태그의 경로로, 태그 또는 키워드가 될 수 있습니다. 예를 들어 환자 ID는 `00100020` 또는 `PatientId`로 표현됩니다

요청 헤더

이름	필수	Type	설명
Content-Type	True	string	`application/json`이 지원됩니다.

요청 본문

이름	필수	Type	설명
본문		업데이트를 위한 확장 쿼리 태그

응답

이름	형식	설명
20(정상)	확장 쿼리 태그	업데이트된 확장 쿼리 태그
400(잘못된 요청)		요청된 태그 경로 또는 본문이 잘못되었습니다
404(찾을 수 없음)		요청된 tagPath가 있는 확장 쿼리 태그를 찾을 수 없습니다

확장 쿼리 태그 오류 나열

확장 쿼리 태그의 오류를 나열합니다.

GET .../extendedquerytags/{tagPath}/errors

URI 매개 변수

이름	그런 다음	필수	Type	설명
tagPath	path	True	string	tagPath는 태그의 경로로, 태그 또는 키워드가 될 수 있습니다. 예를 들어 환자 ID는 `00100020` 또는 `PatientId`로 표현됩니다

응답

이름	형식	설명
200(OK)	확장 쿼리 태그 오류`[]`	태그와 연결된 확장 쿼리 태그 오류의 목록입니다
400(잘못된 요청)		요청된 태그 경로가 잘못되었습니다
404(찾을 수 없음)		요청된 tagPath가 있는 확장 쿼리 태그를 찾을 수 없습니다

가져오기 작업

장기 실행 작업을 가져옵니다.

GET .../operations/{operationId}

URI 매개 변수

이름	그런 다음	필수	Type	설명
operationId	path	True	string	작업 ID

응답

이름	형식	설명
200(OK)	연산	지정 ID에 대해 완료된 작업
202(수락됨)	연산	지정 ID에 대해 실행 중인 작업
404(찾을 수 없음)		작업을 찾을 수 없습니다

확장 쿼리 태그가 있는 QIDO

태그 상태

확장 쿼리 태그의 상태는 현재의 상태를 나타냅니다. 확장 쿼리 태그를 처음 추가하면 그 상태가 Adding으로 설정되고, 기존 DICOM 인스턴스를 다시 인덱싱하기 위해 장기 실행 작업이 시작됩니다. 이 작업이 완료되면 태그 상태가 Ready로 업데이트됩니다. 이제 QIDO에서 확장 쿼리 태그를 사용할 수 있습니다.

예를 들어 제조업체 모델명(0008, 1090)을 추가하고 이것이 Ready 상태가 되면, 그 다음부터는 다음 쿼리를 사용하여 제조업체 모델명별로 저장된 인스턴스들을 필터링할 수 있습니다.

../instances?ManufacturerModelName=Microsoft

기존 태그와 함께 사용할 수도 있습니다. 예시:

../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true

태그 쿼리 상태

QueryStatus는 태그에 QIDO가 허용되는지 여부를 나타냅니다. 재인덱싱 작업이 특정 태그에 하나 이상의 DICOM 인스턴스를 처리하지 못할 경우, 그 태그의 QueryStatus가 자동으로 Disabled로 설정됩니다. 인덱싱 오류를 무시하고 확장 쿼리 태그 업데이트 API를 통해 QueryStatus을 Enabled로 설정하여 쿼리가 이 태그를 사용하도록 허용할 수 있습니다. 직접 사용 설정을 한 태그를 하나 이상 참조하는 QIDO 요청에는 응답 헤더 erroneous-dicom-attributes에 인덱싱 오류가 있는 태그 집합이 포함될 것입니다.

예를 들어 재인덱싱 시 확장 쿼리 태그 PatientAge에 오류가 있는데, 이것이 수동으로 사용 설정되었다고 가정해 보겠습니다. 다음 쿼리에서 erroneous-dicom-attributes 헤더에 PatientAge이 보일 것입니다.

../instances?PatientAge=035Y

정의

확장 쿼리 태그

QIDO-RS에 지원되는 DICOM 태그입니다.

이름	형식	설명
Path	string	일반적으로 그룹 ID와 요소 ID로 구성된 태그 경로입니다. 예를 들어 `PatientId`(0010,0020)의 경로는 00100020입니다
VR	string	이 태그의 값 표현
PrivateCreator	string	이 프라이빗 태그의 구현 개발자의 식별 코드
수준	확장 쿼리 태그 수준	확장 쿼리 태그의 수준
상태	확장 쿼리 태그 상태	확장 쿼리 태그의 상태
QueryStatus	확장 쿼리 태그 쿼리 상태	확장 쿼리 태그의 쿼리 상태
Errors	확장 쿼리 태그 오류 참조	확장 쿼리 태그 오류에 대한 참조
연산	작업 참조	장기 실행 작업에 대한 참조

코드 예제 1은 상태가 Ready인 표준 태그(0008,0070)입니다.

{
    "status": "Ready",
    "level": "Instance",
    "queryStatus": "Enabled",
    "path": "00080070",
    "vr": "LO"
}

코드 예제 2는 상태가 Adding인 표준 태그(0010,1010)입니다. 여기서 ID가 1a5d0306d9624f699929ee1a59ed57a0인 작업이 실행되고 있으며 지금까지 21개의 오류가 발생했습니다.

{
    "status": "Adding",
    "level": "Study",
    "errors": {
        "count": 21,
        "href": "https://localhost:63838/extendedquerytags/00101010/errors"
    },
    "operation": {
        "id": "1a5d0306d9624f699929ee1a59ed57a0",
        "href": "https://localhost:63838/operations/1a5d0306d9624f699929ee1a59ed57a0"
    },
    "queryStatus": "Disabled",
    "path": "00101010",
    "vr": "AS"
}

작업 참조

장기 실행 작업에 대한 참조입니다.

이름	형식	설명
ID	string	작업 ID
Href	string	작업에 대한 URI

연산

장기 실행 작업을 나타냅니다.

이름	형식	설명
OperationId	string	작업 ID
OperationType	작업 유형	장기 실행 작업의 유형
CreatedTime	string	작업이 생성된 시간
LastUpdatedTime	string	작업이 마지막으로 업데이트된 시간
상태	작업 상태	작업의 런타임 상태를 나타냅니다
PercentComplete	정수	작업이 완료한 작업 백분율
리소스	string`[]`	작업이 생성하거나 조작하는 리소스 위치들의 컬렉션

다음 코드 예제는 실행 중인 재인덱싱 작업입니다.

{
    "resources": [
        "https://localhost:63838/extendedquerytags/00101010"
    ],
    "operationId": "a99a8b51-78d4-4fd9-b004-b6c0bcaccf1d",
    "type": "Reindex",
    "createdTime": "2021-10-06T16:40:02.5247083Z",
    "lastUpdatedTime": "2021-10-06T16:40:04.5152934Z",
    "status": "Running",
    "percentComplete": 10
}

작업 상태

장기 실행 작업의 런타임 상태를 나타냅니다.

이름	형식	설명
NotStarted	string	작업이 시작되지 않았습니다
실행 중	string	작업이 실행 중이며 아직 완료되지 않았습니다
Completed	string	작업이 성공적으로 완료되었습니다
실패함	string	하나 이상의 오류가 발생한 후 작업이 조기에 중지되었습니다

확장 쿼리 태그 오류

확장 쿼리 태그 인덱싱 작업 중에 발생한 오류입니다.

이름	형식	설명
StudyInstanceUid	string	인덱싱 오류가 발생한 연구 인스턴스 UID
SeriesInstanceUid	string	인덱싱 오류가 발생한 시리즈 인스턴스 UID
SopInstanceUid	string	인덱싱 오류가 발생한 Sop 인스턴스 UID
CreatedTime	string	오류가 발생한 시간(UTC)
ErrorMessage	string	오류 메시지

다음 코드 예제에는 DICOM 인스턴스에 예상치 못한 값 길이 오류가 포함되어 있습니다. 이 오류는 2021-10-06T16:41:44.4783136에 발생했습니다.

{
    "studyInstanceUid": "2.25.253658084841524753870559471415339023884",
    "seriesInstanceUid": "2.25.309809095970466602239093351963447277833",
    "sopInstanceUid": "2.25.225286918605419873651833906117051809629",
    "createdTime": "2021-10-06T16:41:44.4783136",
    "errorMessage": "Value length is not expected."
}

확장 쿼리 태그 오류 참조

확장 쿼리 태그 오류에 대한 참조입니다.

이름	형식	설명
개수	정수	확장 쿼리 태그에 있는 오류의 총 개수
Href	string	확장 쿼리 태그 오류에 대한 URI

작업 유형

장기 실행 작업의 형식입니다.

이름	형식	설명
다시 인덱싱	string	새 태그를 기반으로 이전에 추가된 데이터에 대한 인덱스를 업데이트하는 다시 인덱스 작업

확장 쿼리 태그 상태

확장 쿼리 태그의 상태입니다.

이름	형식	설명
추가	string	확장 쿼리 태그가 추가되었으며 장기 실행 작업이 기존의 DICOM 인스턴스를 다시 인덱싱합니다
준비	string	확장 쿼리 태그가 QIDO-RS를 위해 준비 상태입니다
삭제 중	string	확장 쿼리 태그가 삭제되고 있습니다

확장 쿼리 태그 수준

이 태그가 적용되는 DICOM 정보 계층 구조의 수준입니다.

이름	형식	설명
인스턴스	string	확장 쿼리 태그가 인스턴스 수준에서 연관성이 있습니다
계열	string	확장 쿼리 태그가 시리즈 수준에서 연관성이 있습니다
연구	string	확장 쿼리 태그가 연구 수준에서 연관성이 있습니다

확장 쿼리 태그 쿼리 상태

확장 쿼리 태그의 쿼리 상태입니다.

이름	형식	설명
사용 안 함	string	확장 쿼리 태그를 쿼리할 수 없습니다
Enabled	string	확장 쿼리 태그를 쿼리할 수 있습니다

참고 항목

다시 인덱싱 작업 중 오류가 발생하면 확장 쿼리 태그에서 QIDO가 비활성화됩니다. 확장 쿼리 태그 업데이트 API를 호출하여 이것을 사용하도록 활성화할 수 있습니다.

업데이트를 위한 확장 쿼리 태그

업데이트를 위한 확장 쿼리 태그를 나타냅니다.

이름	형식	설명
QueryStatus	확장 쿼리 태그 쿼리 상태	확장 쿼리 태그의 쿼리 상태

추가를 위한 확장 쿼리 태그

추가를 위한 확장 쿼리 태그를 나타냅니다.

이름	필수	Type	설명
Path	True	string	일반적으로 그룹 ID와 요소 ID로 구성된 태그의 경로로, 여기서 `PatientId`(0010,0020)의 경로는 00100020입니다
VR		string	이 태그의 값 표현입니다. 표준 태그의 경우 선택 사항이고, 프라이빗 태그의 경우 필수 사항입니다
PrivateCreator		string	이 프라이빗 태그의 구현 개발자의 식별 코드입니다. 태그가 프라이빗 태그인 경우에만 설정
수준	True	확장 쿼리 태그 수준	이 태그가 관련된 계층 구조를 나타냅니다. 연구, 시리즈, 또는 인스턴스 중 하나여야 합니다

코드 예제 1MicrosoftPC은 인스턴스 수준에서 값 표현 SS로 프라이빗 태그(0401,1001)를 정의하고 있습니다.

{
    "Path": "04011001",
    "VR": "SS",
    "PrivateCreator": "MicrosoftPC",
    "Level": "Instance"
}

코드 예제 2는 시리즈 수준에서 정의된 값 표현 LO와 함께 키워드 ManufacturerModelName이 있는 표준 태그를 사용합니다.

{
    "Path": "ManufacturerModelName",
    "VR": "LO",
    "Level": "Series"
}

코드 예제 3은 표준 태그(0010,0040)를 사용하며 연구에서 정의됩니다. 이 값 표현은 DICOM 표준에 의해 이미 정의되어 있습니다.

{
    "Path": "00100040",
    "Level": "Study"
}

요약

이 개념 아티클에서는 DICOM 서비스 내에서의 확장 쿼리 태그 기능에 대한 개요를 제시하였습니다.

다음 단계

Azure에 DICOM 서비스 배포

DICOM 서비스를 통해 DICOMweb API 사용

참고 항목

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

다음을 통해 공유

확장 쿼리 태그

API

버전: v1

확장 쿼리 태그 추가

요청 헤더

요청 본문

제한 사항

응답

확장 쿼리 태그 나열

응답

확장 쿼리 태그 가져오기

URI 매개 변수

응답

확장 쿼리 태그 삭제

URI 매개 변수

응답

확장 쿼리 태그 업데이트

URI 매개 변수

요청 헤더

요청 본문

응답

확장 쿼리 태그 오류 나열

URI 매개 변수

응답

가져오기 작업

URI 매개 변수

응답

확장 쿼리 태그가 있는 QIDO

태그 상태

태그 쿼리 상태

정의

확장 쿼리 태그

작업 참조

연산

작업 상태

확장 쿼리 태그 오류

확장 쿼리 태그 오류 참조

작업 유형

확장 쿼리 태그 상태

확장 쿼리 태그 수준

확장 쿼리 태그 쿼리 상태

업데이트를 위한 확장 쿼리 태그

추가를 위한 확장 쿼리 태그

요약

다음 단계

피드백

추가 리소스