匯出 DICOM 檔案

發行項
05/11/2024

DICOM® 服務可讓您以檔案格式匯出 DICOM 資料。此服務可簡化在外部工作流程中使用醫學影像的程序，例如 AI 和機器學習。您可使用匯出 API，將 DICOM 研究、序列和執行個體大量匯出至 Azure Blob 儲存體帳戶。匯出至儲存體帳戶的 DICOM 資料會在資料夾結構中匯出為 .dcm 檔案 (依 StudyInstanceID 和 SeriesInstanceID 組織執行個體)。

從 DICOM 服務匯出資料有三個步驟：

為 DICOM 服務啟用系統指派的受控識別。
設定新的或現有儲存體帳戶，並提供權限給系統指派的受控識別。
使用匯出 API 建立新的匯出作業來匯出資料。

啟用 DICOM 服務的受控識別

從 DICOM 服務匯出資料的第一個步驟是啟用系統指派的受控識別。此受控識別可用來驗證 DICOM 服務，並提供全縣給做為匯出目的地的儲存體帳戶。如需 Azure 中受控識別的詳細資訊，請參閱關於 Azure 資源受控識別。

在 Azure 入口網站中，瀏覽至您要從中匯出的 DICOM 服務，然後選取 [身分識別]。
將 [狀態] 選項設定為 [開啟]，然後選取 [儲存]。
在出現的確認對話方塊中，選取 [是]。

建立系統指派的受控識別需要幾分鐘的時間。啟用系統身分識別之後，[物件 (主體) 識別碼] 隨即出現。

指派儲存體帳戶權限

系統指派的受控識別需要 [儲存體 Blob 資料參與者] 權限，才能將資料寫入至目的地儲存體帳戶。

在 [權限] 下，選取 [Azure 角色指派]。
選取 [新增角色指派]。在 [新增角色指派] 窗格上，進行下列選取：
- 在 [範圍] 之下，選取 [儲存體]。
- 在 [資源] 之下，選取匯出作業的目的地儲存體帳戶。
- 在 [角色] 之下，選取 [儲存體 Blob 資料參與者]。
選取 [儲存]，將權限新增至系統指派的受控識別。

使用匯出 API

匯出 API 會公開一個 POST 端點來匯出資料。

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

假設有來源、要匯出的資料集，以及目的地、要匯出資料的位置，端點會傳回對新的長時間執行匯出作業的參考。此作業的持續時間取決於要匯出的資料量。如需監視匯出作業進度的詳細資訊，請參閱作業狀態一節。

當您嘗試匯出時遇到的任何錯誤，都會記錄在錯誤記錄檔中。如需詳細資訊，請參閱錯誤一節。

要求

要求本文包含匯出來源和目的地。

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

來源設定

唯一的設定是要匯出的識別碼清單。

屬性	必要	預設	描述
`Values`	Yes		一或多個 DICOM 研究、序列和/或 SOP 執行個體識別碼的清單，其格式為 `"<StudyInstanceUID>[/<SeriesInstanceUID>[/<SOPInstanceUID>]]"`

目的地設定

使用 BlobContainerUri 指定與 Blob 儲存體帳戶的連線。

屬性	必要	預設	描述
`BlobContainerUri`	No	`""`	Blob 容器的完整 URI
`UseManagedIdentity`	Yes	`false`	必要旗標，指出是否應該使用受控識別向 Blob 容器進行驗證

範例

下列範例會要求將下列 DICOM 資源匯出至名為 dicomexport 的儲存體帳戶中名為 export 的 Blob 容器：

研究內的所有執行個體，其 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 會傳回 200 狀態碼，而不是 202。其狀態屬性的值會據以更新。

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
    }
}

錯誤

如果您匯出 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® 是美國電氣製造商協會對於其與醫療資訊數位通訊相關的標準出版物的註冊商標。

共用方式為