匯出 DICOM 檔案

DICOM 服務可讓您輕鬆地以檔案格式匯出 DICOM 資料,簡化在外部工作流程中使用醫療影像的程式,例如 AI 和機器學習。 DICOM 研究、系列和實例可以使用匯出 API 大量匯出至Azure Blob 儲存體帳戶。 匯出至儲存體帳戶的 DICOM 資料將會匯出為 .dcm 資料夾結構中的檔案,該檔案會依 StudyInstanceIDSeriesInstanceID 組織實例。

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

  • 為 DICOM 服務啟用系統指派的受控識別。
  • 設定新的或現有的儲存體帳戶,並授與系統受控識別的許可權。
  • 使用匯出 API 來建立新的匯出作業來匯出資料。

啟用 DICOM 服務的受控識別

從 DICOM 服務匯出資料的第一個步驟是啟用系統受控識別。 此受控識別可用來驗證 DICOM 服務,並將許可權授與作為匯出目的地的儲存體帳戶。 如需 Azure 中受控識別的詳細資訊,請參閱 關於 Azure 資源的受控識別

  1. 在Azure 入口網站中,流覽至您要從中匯出的 DICOM 服務,然後選取 [身分識別]。

顯示 [身分識別] 檢視選取專案的螢幕擷取畫面。

  1. [狀態] 選項設定為 [ 開啟],然後選取 [ 儲存]。

系統指派身分識別切換的螢幕擷取畫面。

  1. 在出現的確認對話方塊中,選取 [ ]。

確認啟用系統身分識別之對話方塊的螢幕擷取畫面。

建立系統受控識別需要幾分鐘的時間。 啟用系統身分識別後,將會顯示 物件 (主體) 識別碼

將儲存體帳戶許可權授與系統受控識別

系統受控識別需要 儲存體 Blob 資料參與者 許可權,才能將資料寫入目的地儲存體帳戶。

  1. [許可權 ] 底下,選取 [Azure 角色指派]。

身分識別檢視上 Azure 角色指派按鈕的螢幕擷取畫面。

  1. 選取 [新增角色指派]。 在 [ 新增角色指派 ] 面板上,選取下列專案:
    • [範圍]底下,選取 [儲存體]。
    • [資源] 下,選取匯出作業的目的地儲存體帳戶。
    • [角色]底下,選取 [儲存體 Blob 資料參與者]。

[新增角色指派] 面板的螢幕擷取畫面。

  1. 選取 [儲存 ] 以將許可權新增至系統受控識別。

使用匯出 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 容器:

  • 研究內的所有實例,其 StudyInstanceUID1.2.3
  • 數列內的所有實例,其 StudyInstanceUID12.3SeriesInstanceUID4.5.678
  • 實例,其 StudyInstanceUID123.456SeriesInstanceUID7.8 ,且 SOPInstanceUID9.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 詳細的錯誤訊息。

下一步