匯出 DICOM 檔案

發行項
01/26/2023

DICOM 服務可讓您輕鬆地以檔案格式匯出 DICOM 資料，簡化在外部工作流程中使用醫療影像的程式，例如 AI 和機器學習。 DICOM 研究、系列和實例可以使用匯出 API 大量匯出至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`	是		一或多個 DICOM 研究、系列和/或 SOP 實例識別碼的清單，格式為 `"<StudyInstanceUID>[/<SeriesInstanceUID>[/<SOPInstanceUID>]]"` 。

目的地設定

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

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

範例

下列範例會將下列 DICOM 資源匯出至名為的儲存體帳戶中名為 exportdicomexport 的 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
{
    "sources": {
        "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 本文) 相同。

在目的地容器內，可以使用下列路徑格式找到 DCM 檔案： <operation id>/results/<study>/<series>/<sop instance>.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 服務概觀