DICOM 파일 내보내기

아티클
02/23/2024

DICOM® 서비스를 사용하면 DICOM 데이터를 파일 형식으로 내보낼 수 있습니다. 이 서비스는 AI 및 기계 학습과 같은 외부 워크플로에서 의료 이미지를 사용하는 프로세스를 간소화합니다. 내보내기 API를 사용하여 DICOM 연구, 계열 및 인스턴스를 대량으로 Azure Blob Storage 계정에 내보낼 수 있습니다. 스토리지 계정으로 추출된 DICOM 데이터는 StudyInstanceID 및 SeriesInstanceID로 인스턴스를 구성하는 폴더 구조에서 .dcm 파일로 내보내집니다.

DICOM 서비스에서 데이터를 내보내기 위한 세 가지 단계가 있습니다.

DICOM 서비스에 대해 시스템이 할당한 관리 ID를 사용 설정합니다.
신규 또는 기존 스토리지 계정을 구성하고 시스템이 할당한 관리 ID에 대한 권한을 부여합니다.
내보내기 API를 사용하여 데이터를 내보내기 위한 새 내보내기 작업을 만듭니다.

DICOM 서비스에 관리 ID 사용

DICOM 서비스에서 데이터를 내보내는 첫 번째 단계는 시스템이 할당 관리 ID를 사용하도록 설정하는 것입니다. 이 관리 ID는 DICOM 서비스를 인증하고 내보내기 대상으로 사용되는 스토리지 계정에 권한을 부여하는 데 사용됩니다. Azure에서 관리 ID에 대한 자세한 내용은 Azure 리소스의 관리 ID 정보를 참조하세요.

Azure Portal에서 내보낼 DICOM 서비스를 찾아보고 ID를 선택합니다.
상태 옵션을 켜기로 전환한 다음 저장을 설정합니다.
표시되는 확인 대화 상자에서 예를 선택합니다.

시스템이 할당한 관리 ID를 만드는 데 몇 분 정도 걸립니다. 시스템 ID를 사용 설정하면 개체(보안 주체) ID가 나타납니다.

스토리지 계정 권한 할당

시스템이 할당한 관리 ID는 대상 스토리지 계정에 데이터를 쓰려면 Storage Blob 데이터 기여자 권한이 필요합니다.

권한에서 Azure 역할 할당을 선택합니다.
역할 할당 추가를 선택합니다. 역할 할당 추가 창에서 다음을 선택합니다.
- 범위에서 스토리지를 선택합니다.
- 리소스 에서 내보내기 작업의 대상 스토리지 계정을 선택합니다.
- 역할에서 Storage Blob 데이터 기여자를 선택합니다.
저장을 선택하여 시스템이 할당 관리 ID에 권한을 추가합니다.

내보내기 API 사용

내보내기 API는 데이터를 내보내기 위한 하나의 POST 엔드포인트를 노출합니다.

POST <dicom-service-url>/<version>/export

원본, 내보낼 데이터 집합 및 대상, 데이터를 내보낼 위치가 지정된 경우 엔드포인트는 장기 실행 중인 새 내보내기 작업에 대한 참조를 반환합니다. 작업 시간은 내보낼 데이터의 양에 따라 달라집니다. 내보내기 작업의 진행률을 모니터링하는 방법에 대한 자세한 내용은 작업 상태 섹션을 참조하세요.

내보내는 동안 발생한 모든 오류는 오류 로그에 기록됩니다. 자세한 내용은 오류 섹션을 참조하세요.

요청

요청 본문은 내보내기 원본 및 대상으로 구성됩니다.

{
    "source": {
        "type": "identifiers",
        "settings": {
            "values": [
                "..."
            ]
        }
    },
    "destination": {
        "type": "azureblob",
        "settings": {
            "setting": "<value>"
        }
    }
}

원본 설정

유일한 설정은 내보낼 식별자 목록입니다.

속성	Required	기본값	설명
`Values`	예		하나 이상의 DICOM 연구, 계열 및/또는 SOP 인스턴스 식별자 목록(`"<StudyInstanceUID>[/<SeriesInstanceUID>[/<SOPInstanceUID>]]"` 형식)

대상 설정

Blob Storage 계정에 대한 연결은 BlobContainerUri를 사용하여 지정됩니다.

속성	Required	기본값	설명
`BlobContainerUri`	아니요	`""`	Blob 컨테이너에 대한 전체 URI
`UseManagedIdentity`	예	`false`	관리 ID를 사용하여 Blob 컨테이너에 인증해야 하는지 여부를 나타내는 필수 플래그입니다.

예시

다음 예제에서는 다음 DICOM 리소스를 스토리지 계정(dicomexport)에서 Blob 컨테이너(export)로 내보내도록 요청합니다.

StudyInstanceUID가 1.2.3인 연구 내 모든 인스턴스
StudyInstanceUID가 12.3이고 SeriesInstanceUID가 4.5.678인 계열 내 모든 인스턴스
StudyInstanceUID가 123.456이고, SeriesInstanceUID가 7.8이고, SOPInstanceUID가 9.1011.12인 인스턴스

POST /export HTTP/1.1
Accept: */*
Content-Type: application/json
{
    "source": {
        "type": "identifiers",
        "settings": {
            "values": [
                "1.2.3",
                "12.3/4.5.678",
                "123.456/7.8/9.1011.12"
            ]
        }
    },
    "destination": {
        "type": "azureblob",
        "settings": {
            "blobContainerUri": "https://dicomexport.blob.core.windows.net/export",
            "UseManagedIdentity": true
        }
    }
}

응답

내보내기 작업이 시작되면 내보내기 API는 202 상태 코드를 반환합니다. 응답 본문에는 작업에 대한 참조가 포함되어 있지만 Location 헤더 값은 내보내기 작업의 상태에 대한 URL입니다(본문의 href와 동일).

대상 컨테이너 내에서 경로 형식 <operation id>/results/<study>/<series>/<sop instance>.dcm을 사용하여 DCM 파일을 찾습니다.

HTTP/1.1 202 Accepted
Content-Type: application/json
{
    "id": "df1ff476b83a4a3eaf11b1eac2e5ac56",
    "href": "https://example-dicom.dicom.azurehealthcareapis.com/v1/operations/df1ff476b83a4a3eaf11b1eac2e5ac56"
}

작업 상태

완료될 때까지 내보내기 작업의 현재 상태에 대한 이전 href URL을 폴링합니다. 작업이 터미널 상태에 도달하면 API는 202 대신 200 상태 코드를 반환합니다. 그에 따라 상태 속성의 값이 업데이트됩니다.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "operationId": "df1ff476b83a4a3eaf11b1eac2e5ac56",
    "type": "export",
    "createdTime": "2022-09-08T16:40:36.2627618Z",
    "lastUpdatedTime": "2022-09-08T16:41:01.2776644Z",
    "status": "completed",
    "results": {
        "errorHref": "https://dicomexport.blob.core.windows.net/export/4853cda8c05c44e497d2bc071f8e92c4/errors.log",
        "exported": 1000,
        "skipped": 3
    }
}

Errors

DICOM 파일을 내보낼 때 사용자 오류가 있는 경우 파일을 건너뛰고 해당 오류가 기록됩니다. 이 오류 로그는 DICOM 파일과 함께 내보내지고 호출자는 이를 검토할 수 있습니다. <export blob container uri>/<operation ID>/errors.log에서 오류 로그를 찾을 수 있습니다.

형식

오류 로그의 각 행은 다음 속성을 갖는 JSON 개체입니다. 로그에 대한 각 업데이트가 한 번 이상 처리되므로 지정된 오류 식별자가 로그에 여러 번 나타날 수 있습니다.

속성	설명
`Timestamp`	오류가 발생한 날짜와 시간
`Identifier`	DICOM 연구, 계열 또는 SOP 인스턴스의 식별자(`"<study instance UID>[/<series instance UID>[/<SOP instance UID>]]"` 형식).
`Error`	자세한 오류 메시지입니다

참고 항목

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