Change feed overview
The change feed provides logs of all the changes that occur in the DICOM® service. The change feed provides ordered, guaranteed, immutable, and read-only logs of these changes. The change feed offers the ability to go through the history of DICOM service and acts upon the creates, updates, 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 DICOM service.
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.
Make sure to specify the version as part of the URL when making requests. More information can be found in the API Versioning for DICOM service Documentation.
The API exposes two GET
endpoints for interacting with the change feed. A typical flow for consuming the change feed is provided in the Usage section.
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 |
Field | Type | Description |
---|---|---|
Sequence | long | The unique ID per change event |
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 , update , 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 |
State | Description |
---|---|
current | This instance is the current version. |
replaced | This instance is replaced with a new version. |
deleted | This instance is deleted and is no longer available in the service. |
The change feed resource is a collection of events that occurred within the DICOM server.
GET /changefeed?startTime={datetime}&endtime={datetime}&offset={int}&limit={int}&includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json
[
{
"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
}
},
//...
]
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 |
GET /changefeed?offset={int}&limit={int}&includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json
[
{
"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
}
},
// ...
]
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 is 15. | 10 |
1 |
100 |
includeMetadata | bool | Indicates whether or not to include the DICOM metadata | true |
The latest change feed resource represents the latest event that occurred within the DICOM server.
GET /changefeed/latest?includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"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
}
}
Name | Type | Description | Default |
---|---|---|---|
includeMetadata | bool | Indicates whether or not to include the metadata | true |
- An application regularly queries the change feed on some time interval
- For example, if querying every hour, a query for the change feed might look like
/changefeed?startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
- If starting from the beginning, the change feed query might omit the
startTime
to read all of the changes up to, but excluding, theendTime
- For example:
/changefeed?endTime=2023-05-10T17:00:00Z
- For example:
- For example, if querying every hour, a query for the change feed might look like
- Based on the
limit
(if provided), an application continues to query for more pages of change events if the number of returned events is equal to thelimit
(or default) by updating the offset on each subsequent query- For example, if the
limit
is100
, and 100 events are returned, then the subsequent query would includeoffset=100
to fetch the next "page" of results. The 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
- For example, if the
- 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 ofSequence
from the latest change event using the/changefeed/latest
resource
- To start from the first event, the application should use
- 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 processed up to sequence number 15 and it only wants to process at most five events at once, then it should use the URL
/changefeed?offset=15&limit=5
- For example, if the application processed up to sequence number 15 and it only wants to process at most five events at once, then it should use the URL
- Processes any entries return by the
/changefeed
resource - Updates its current sequence number to either:
- The maximum sequence number returned by the
/changefeed
resource - 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 foroffset
- The maximum sequence number returned by the
- Fetches the latest sequence number from the
Change feed support is well-suited for scenarios that process data based on objects that are 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.
Pull changes from the change feed
Nota
DICOM® is the registered trademark of the National Electrical Manufacturers Association for its Standards publications relating to digital communications of medical information.