변경 피드 개요

  • 아티클

변경 피드는 DICOM® 서비스에서 발생하는 모든 변경 사항에 대한 로그를 제공합니다. 변경 피드는 이러한 변경 내용에 대해 순서가 지정되고, 보장되며, 내구성이 있고, 변경할 수 없는, 읽기 전용 로그를 제공합니다. 변경 피드는 DICOM 서비스의 기록을 살펴보고 서비스에서 생성, 업데이트 및 삭제 시 작동할 수 있는 기능을 제공합니다.

클라이언트 응용 프로그램은 언제든지 이러한 로그를 모든 크기의 일괄 처리 작업으로 읽을 수 있습니다. 변경 피드를 사용하면 DICOM 서비스에서 발생하는 변경 이벤트를 처리하는 효율적이고 확장 가능한 솔루션을 빌드할 수 있습니다.

이러한 변경 이벤트를 비동기, 증분 또는 전체 방식으로 처리할 수 있습니다. 많은 클라이언트 애플리케이션에서 자체의 고유한 속도로 변경 피드를 독립적으로 병렬로 읽을 수 있습니다.

API의 v2를 기준으로 특정 기간 동안 변경 피드를 쿼리할 수 있습니다.

요청할 때는 버전을 URL의 일부로 지정해야 합니다. 자세한 내용은 DICOM 서비스용 API 버전 관리 설명서에서 확인할 수 있습니다.

API 디자인

API는 변경 피드와 상호 작용하기 위해 두 개의 GET 엔드포인트를 노출합니다. 변경 피드를 사용하는 일반적인 흐름은 사용량 섹션에서 설명합니다.

동사 경로 반환 설명
GET /changefeed JSON 배열 변경 피드 읽기
GET /changefeed/latest JSON 개체 변경 피드의 최신 항목 읽기

개체 모델

필드 형식 설명
Sequence long 변경 이벤트당 고유 ID
StudyInstanceUid string 연구 인스턴스 UID
SeriesInstanceUid string 시리즈 인스턴스 UID
SopInstanceUid string sop 인스턴스 UID
작업 string 수행된 작업 - create, update, 또는 delete
Timestamp 날짜/시간 작업이 수행된 날짜 및 시간(UTC)
State(상태) string 메타데이터의 현재 상태
메타데이터 개체 필요에 따라 인스턴스가 있는 경우 현재 DICOM 메타데이터

상태

시스템 상태 설명
현재 이 인스턴스는 최신 버전입니다.
대체됨 이 인스턴스는 새 버전으로 대체되었습니다.
deleted 이 인스턴스는 삭제되었으며 더 이상 서비스에서 사용할 수 없습니다.

변경 피드

변경 피드 리소스는 DICOM 서버 내에서 발생한 이벤트 컬렉션입니다.

버전 2

Request

GET /changefeed?startTime={datetime}&endtime={datetime}&offset={int}&limit={int}&includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json

Response

[
    {
        "Sequence": 1,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-04T01:03:08.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    {
        "Sequence": 2,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-05T07:13:16.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    //...
]

매개 변수

이름 형식 설명 기본값 Min Max
offset long 결과 집합의 시작 부분에서 건너뛸 이벤트 수 0 0
limit int 반환할 최대 이벤트 수입니다 100 1 200
startTime DateTime 변경 이벤트의 포괄 시작 시간 "0001-01-01T00:00:00Z" "0001-01-01T00:00:00Z" "9999-12-31T23:59:59.9999998Z"
endTime DateTime 변경 이벤트의 전용 종료 시간 "9999-12-31T23:59:59.9999999Z" "0001-01-01T00:00:00.0000001" "9999-12-31T23:59:59.9999999Z"
includeMetadata bool DICOM 메타데이터를 포함할지 여부를 나타냅니다 true

버전 1

Request

GET /changefeed?offset={int}&limit={int}&includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json

Response

[
    {
        "Sequence": 1,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-04T01:03:08.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    {
        "Sequence": 2,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-05T07:13:16.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    // ...
]

매개 변수

이름 형식 설명 기본값 Min Max
offset long 이벤트에 대한 전용 시작 시퀀스 번호입니다 0 0
limit int 오프셋을 기준으로 하는 시퀀스 번호의 최대값입니다. 예를 들어 오프셋이 10이고 제한이 5면 반환되는 최대 시퀀스 번호는 15입니다. 10 1 100
includeMetadata bool DICOM 메타데이터를 포함할지 여부를 나타냅니다 true

최신 변경 피드

최신 변경 피드 리소스는 DICOM 서버 내에서 발생한 최신 이벤트를 나타냅니다.

Request

GET /changefeed/latest?includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json

Response

{
    "Sequence": 2,
    "StudyInstanceUid": "{uid}",
    "SeriesInstanceUid": "{uid}",
    "SopInstanceUid": "{uid}",
    "Action": "create|update|delete",
    "Timestamp": "2020-03-05T07:13:16.4834Z",
    "State": "current|replaced|deleted",
    "Metadata": {
        //DICOM JSON
    }
}

매개 변수

이름 형식 설명 기본값
includeMetadata bool 메타데이터를 포함할지 여부를 나타냅니다 true

사용

사용자 애플리케이션

버전 2

  1. 애플리케이션은 일정한 시간 간격으로 변경 피드를 규칙적으로 쿼리합니다
    • 예를 들어 매시간 쿼리하는 경우 변경 피드에 대한 쿼리는 다음과 같을 수 있습니다 /changefeed?startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
    • 처음부터 시작하는 경우 변경 피드 쿼리는 startTime을 생략하여 endTime을 제외한 모든 변경 사항을 읽을 수 있습니다
      • 예: /changefeed?endTime=2023-05-10T17:00:00Z
  2. limit(제공된 경우)을 기준으로 각각의 후속 쿼리에서 오프셋을 업데이트하여 반환된 이벤트 수가 limit(또는 기본값)와 같은 경우 애플리케이션은 변경 이벤트의 더 많은 페이지를 계속 쿼리합니다
    • 예를 들어 limit이 100이고 100개의 이벤트가 반환되는 경우 후속 쿼리는 결과의 다음 "페이지"의 결과를 가져오기 위해 offset=100을 포함합니다. 쿼리는 다음과 같은 패턴을 보여줍니다.
      • /changefeed?offset=0&limit=100&startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
      • /changefeed?offset=100&limit=100&startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
      • /changefeed?offset=200&limit=100&startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
    • 이벤트가 limit보다 적게 반환되는 경우 애플리케이션은 시간 범위 내에 더 이상 결과가 없다고 가정할 수 있습니다

버전 1

  1. 애플리케이션이 변경 이벤트 읽기를 시작할 시퀀스 번호를 결정합니다.
    • 첫 번째 이벤트에서 시작하려면 애플리케이션이 offset=0을 사용해야 합니다
    • 최신 이벤트에서 시작하려면 애플리케이션이 /changefeed/latest 리소스를 사용하여 최신 변경 이벤트의 Sequence 값을 통해 offset 매개 변수를 지정해야 합니다
  2. 어느 정도 규칙적인 폴링 간격으로 애플리케이션은 다음 작업을 수행합니다.
    • /changefeed/latest 엔드포인트에서 최신 시퀀스 번호를 가져옵니다
    • 현재 오프셋을 통해 변경 피드를 쿼리하여 처리할 다음 변경 집합을 가져옵니다
      • 예를 들어 애플리케이션이 시퀀스 번호 15까지 처리했고 최대 5개의 이벤트만 한 번에 처리하려는 경우 URL /changefeed?offset=15&limit=5을 사용해야 합니다
    • /changefeed 리소스에서 반환하는 항목을 처리합니다
    • 현재 시퀀스 번호를 다음 중 하나로 업데이트합니다.
      1. /changefeed 리소스에서 반환하는 최대 시퀀스 번호
      2. /changefeed 리소스에서 변경 이벤트가 반환되지 않았지만 /changefeed/latest에서 반환한 최신 시퀀스 번호가 offset에 사용되는 현재 시퀀스 번호보다 더 클 경우 offset + limit

기타 잠재적 사용량 패턴

변경 피드 지원은 변경된 개체를 기반으로 하여 데이터를 처리하는 시나리오에 적합합니다. 예를 들어 다음과 같은 목적으로 사용할 수 있습니다.

  • 변경 이벤트에 대응하거나, 생성되었거나 삭제된 인스턴스를 기반으로 실행을 예약하는 연결된 애플리케이션 파이프라인(예: ML)을 빌드합니다.
  • 개체에 발생하는 변경 내용에 따라 비즈니스 분석 인사이트 및 메트릭을 추출합니다.
  • 변경 피드를 폴링하여 푸시 알림에 대한 이벤트 원본을 만듭니다.

다음 단계

변경 피드에서 변경 내용 끌어오기

참고 항목

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