Skip to content

Latest commit

 

History

History
220 lines (180 loc) · 9.99 KB

change-feed.md

File metadata and controls

220 lines (180 loc) · 9.99 KB
Raw

Change Feed Overview

The Change Feed provides logs of all the changes that occur in your Medical Imaging Server for DICOM. The Change Feed provides ordered, guaranteed, immutable, read-only log of these changes. The Change Feed offers the ability to go through the history of the Medical Imaging Server for DICOM and act upon the creates and deletes in the service.

Client applications can read these logs at any time in batches of any size. The Change Feed enables you to build efficient and scalable solutions that process change events that occur in your Medical Imaging Server for DICOM.

You can process these change events asynchronously, incrementally, or in-full. Any number of client applications can independently read the Change Feed, in parallel, and at their own pace.

As of v2 of the API, the Change Feed can be queried for a particular time window.

API Design

The API exposes two GET endpoints for interacting with the Change Feed. A typical flow for consuming the Change Feed is provided below.

Verb Route Returns Description
GET /changefeed Json Array Read the Change Feed
GET /changefeed/latest Json Object Read the latest entry in the Change Feed

Object model

Field Type Description
Sequence long The unique ID per change events
StudyInstanceUid string The study instance UID
SeriesInstanceUid string The series instance UID
SopInstanceUid string The sop instance UID
Action string The action that was performed - either create or delete
Timestamp datetime The date and time the action was performed in UTC
State string The current state of the metadata
Metadata object Optionally, the current DICOM metadata if the instance exists

States

State Description
current This instance is the current version.
replaced This instance has been replaced by a new version.
deleted This instance has been deleted and is no longer available in the service.

Change Feed

The Change Feed resource is a collection of events that have occurred within the DICOM server.

Version 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
        }
    },
    // ...
]

Parameters

Name Type Description Default Min Max
offset long The number of events to skip from the beginning of the result set 0 0
limit int The maximum number of events to return 100 1 200
startTime DateTime The inclusive start time for change events "0001-01-01T00:00:00Z" "0001-01-01T00:00:00Z" "9999-12-31T23:59:59.9999998Z"
endTime DateTime The exclusive end time for change events "9999-12-31T23:59:59.9999999Z" "0001-01-01T00:00:00.0000001" "9999-12-31T23:59:59.9999999Z"
includeMetadata bool Indicates whether or not to include the DICOM metadata true

Version 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|update",
        "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|update",
        "Timestamp": "2020-03-05T07:13:16.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    // ...
]

Parameters

Name Type Description Default Min Max
offset long The exclusive starting sequence number for events 0 0
limit int The maximum value of the sequence number relative to the offset. For example, if the offset is 10 and the limit is 5, then the maximum sequence number returned will be 15. 10 1 100
includeMetadata bool Indicates whether or not to include the DICOM metadata true

Latest Change Feed

The latest Change Feed resource represents the latest event that has occurred within the DICOM Server.

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|delete|update",
    "Timestamp": "2020-03-05T07:13:16.4834Z",
    "State": "current|replaced|deleted",
    "Metadata": {
        // DICOM JSON
    }
}

Parameters

Name Type Description Default
includeMetadata bool Indicates whether or not to include the metadata true

Usage

DICOMcast

DICOMcast is a stateful processor that pulls DICOM changes from Change Feed, transforms and publishes them to a configured Azure API for FHIR service as an ImagingStudy resource. DICOM Cast can start processing the DICOM change events at any point and continue to pull and process new changes incrementally.

User Application

Below is the flow for an example application that wants to do additional processing on the instances within the DICOM service.

Version 2

  1. An application regularly queries the Change Feed on some time interval
    • For example, if querying every hour, a query for the Change Feed may look like /changefeed?startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
    • If starting from the beginning, the Change Feed query may omit the startTime to read all of the changes up to, but excluding, the endTime
      • E.g. /changefeed?endTime=2023-05-10T17:00:00Z
  2. Based on the limit (if provided), an application continues to query for additional pages of change events if the number of returned events is equal to the limit (or default) by updating the offset on each subsequent query
    • For example, if the limit is 100, and 100 events are returned, then the subsequent query would include offset=100 to fetch the next "page" of results. The below queries demonstrate the pattern:
      • /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
    • If fewer events than the limit are returned, then the application can assume that there are no more results within the time range

Version 1

  1. An application determines from which sequence number it wishes to start reading change events:
    • To start from the first event, the application should use offset=0
    • To start from the latest event, the application should specify the offset parameter with the value of Sequence from the latest change event using the /changefeed/latest resource
  2. On some regular polling interval, the application performs the following actions:
    • Fetches the latest sequence number from the /changefeed/latest endpoint
    • Fetches the next set of changes for processing by querying the change feed with the current offset
      • For example, if the application has currently processed up to sequence number 15 and it only wants to process at most 5 events at once, then it should use the URL /changefeed?offset=15&limit=5
    • Processes any entries return by the /changefeed resource
    • Updates its current sequence number to either:
      1. The maximum sequence number returned by the /changefeed resource
      2. The offset + limit if no change events were returned from the /changefeed resource, but the latest sequence number returned by /changefeed/latest is greater than the current sequence number used for offset

Other potential usage patterns

Change Feed support is well-suited for scenarios that process data based on objects that have changed. For example, it can be used to:

  • Build connected application pipelines like ML that react to change events or schedule executions based on created or deleted instance.
  • Extract business analytics insights and metrics, based on changes that occur to your objects.
  • Poll the Change Feed to create an event source for push notifications.

Summary

In this Concept, we reviewed the REST API design of Change Feed and potential usage scenarios. For a how-to guide on Change Feed, see Pull changes from Change Feed.