變更摘要概觀

發行項
05/11/2024

變更摘要會提供 DICOM® 服務中所發生所有變更的記錄。變更摘要提供這些變更的已排序、保證、不可變和唯讀記錄。變更摘要可讓您瀏覽 DICOM 服務的歷程記錄，並在服務中建立、更新和刪除時採取動作。

用戶端應用程式可以任何大小的批次模式隨時讀取這些記錄。變更摘要可讓您建立有效率且可調整的解決方案，以處理您 DICOM 服務中發生的變更事件。

您可以用累加方式或完整方式來非同步處理這些變更事件。任何數目的用戶端應用程式都可以依自己的步調，以平行方式獨立讀取變更摘要。

從 API v2 開始，可以查詢特定時間範圍的變更摘要。

發出要求時，請務必將版本指定為 URL 的一部分。如需詳細資訊，請參閱適用於 DICOM 服務的 API 版本設定文件。

API 設計

API 會公開兩個 GET 端點，以便與變更摘要互動。使用方式一節會提供取用變更摘要的一般流程。

動詞命令	路由	傳回	描述
GET	/changefeed	JSON 陣列	讀取變更摘要
GET	/changefeed/latest	JSON 物件	讀取變更摘要中的最新項目

物件模型

欄位	類型	描述
序列	long	每個變更事件的唯一識別碼
StudyInstanceUid	string	研究執行個體 UID
SeriesInstanceUid	string	系列執行個體 UID
SopInstanceUid	string	SOP 執行個體 UID
動作	string	已執行的動作 - `create`、`update` 或 `delete`
時間戳記	Datetime	執行動作的日期和時間 (UTC)
州 (縣/市)	字串	中繼資料的目前狀態
中繼資料	object	選擇性地，如果執行個體存在，則為目前的 DICOM 中繼資料

狀態

State	描述
目前的	這個執行個體是目前的版本。
取代後	這個執行個體會取代為新版本。
已刪除	此執行個體已刪除，且服務中已不再提供。

變更摘要

變更摘要資源是 DICOM 伺服器內發生的事件集合。

第 2 版

要求

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

參數

姓名	類型	描述	預設	最小值	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 版

要求

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

參數

姓名	類型	描述	預設	最小值	Max
offset	long	事件的起始序號 (不含)	`0`	`0`
limit	int	相對於位移的序號最大值。例如，如果位移為 10 且限制為 5，則傳回的最大序號為 15。	`10`	`1`	`100`
includeMetadata	bool	指出是否要包含 DICOM 中繼資料	`true`

姓名	類型	描述	預設
includeMetadata	bool	指出是否要包含中繼資料	`true`

使用方式

使用者應用程式

第 2 版

應用程式會定期查詢某個時間間隔的變更摘要
- 例如，如果每小時查詢一次，變更摘要的查詢看起來可能會像 /changefeed?startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
- 如果從開頭開始，變更摘要查詢可能會省略 startTime 以讀取所有 endTime 以前 (但不包括) 的變更
  - 例如：/changefeed?endTime=2023-05-10T17:00:00Z
根據 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 版

應用程式會決定其要開始讀取變更事件的序號：
- 若要從第一個事件開始，應用程式應該使用 offset=0
- 若要從最新事件開始，應用程式應該使用 /changefeed/latest 資源，從最新變更事件以 Sequence 的值指定 offset 參數
在一些定期輪詢間隔中，應用程式會執行下列動作：
- 從 /changefeed/latest 端點擷取最新的序號
- 使用目前的位移查詢變更摘要，以擷取下一組要處理的變更
  - 例如，如果應用程式最多處理到序號 15，且只要一次處理最多五個事件，則應該使用 URL /changefeed?offset=15&limit=5
- 處理 /changefeed 資源傳回的任何項目
- 將其目前的序號更新為下列其中一項：
  1. /changefeed 資源傳回的最大序號
  2. 如果未從 /changefeed 資源傳回任何變更事件，但 /changefeed/latest 傳回的最新序號大於 offset 目前所使用的序號，則為 offset + limit

其他潛在的使用模式

變更摘要支援非常適合用來根據已變更物件處理資料的案例。例如，其可以用來：

建立已連線的應用程式管線 (例如 ML)，以根據已建立或已刪除的執行個體來回應變更事件或排程執行。
根據對物件發生的變更，擷取商務分析深入解析和計量。
輪詢變更摘要，以建立推播通知的事件來源。

下一步

從變更摘要提取變更

注意

DICOM® 是國家電氣製造商協會對於其與醫療資訊數位通訊相關的標準出版物的註冊商標。

共用方式為

變更摘要概觀

API 設計

物件模型

狀態

變更摘要

第 2 版

要求

回應

參數

第 1 版

要求

回應

參數

最新的變更摘要

要求

回應

參數

使用方式

使用者應用程式

第 2 版

第 1 版

其他潛在的使用模式

下一步

意見反應

其他資源