cURL で DICOMweb 標準 API を使用する

[アーティクル]
2024/04/16

この記事では、cURL とサンプルの .dcm DICOM® ファイルを使って DICOMweb サービスを操作する方法について説明します。

次のサンプルファイルを使います。

blue-circle.dcm
dicom-metadata.csv
green-square.dcm
red-triangle.dcm

サンプル DICOM ファイルのファイル名、studyUID、seriesUID、および instanceUID は次のとおりです。

ファイル	StudyUID	SeriesUID	InstanceUID
green-square.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.12714725698140337137334606354172323212
red-triangle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652	1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395
blue-circle.dcm	1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420	1.2.826.0.1.3680043.8.498.77033797676425927098669402985243398207	1.2.826.0.1.3680043.8.498.13273713909719068980354078852867170114

注意

これらの各ファイルは 1 つのインスタンスを表し、同じ検査の一部です。また、green-square と red-triangle は同じシリーズの一部であり、blue-circle は別のシリーズに含まれます。

前提条件

DICOM 標準 API を使用するには、DICOM サービスのインスタンスをデプロイする必要があります。詳しくは、Azure portal を使用した DICOM サービスのデプロイに関する記事を参照してください。

DICOM サービスのインスタンスをデプロイした後、アプリサービスの URL を取得します。

Azure portal にサインインします。
[最近のリソース] を検索し、DICOM サービスインスタンスを選択します。
DICOM サービスのサービス URL をコピーします。
アクセストークンが必要な場合は、DICOM サービスのアクセストークンの取得に関する記事を参照してください。

このコードでは、パブリックプレビュー Azure サービスにアクセスします。個人医療情報 (PHI) をアップロードしないようにすることが重要です。

DICOM サービスを操作する

DICOMweb 標準は、multipart/related HTTP 要求を DICOM 固有の Accept ヘッダーと組み合わせて頻繁に使用します。他の REST ベースの API に慣れている開発者は、DICOMweb 標準を使いにくいと感じることがよくあります。しかし、一度動かすことができれば、後は簡単に使用できます。使用を開始するために、少し慣れる必要があるだけです。

それぞれの cURL コマンドには、置き換える必要がある少なくとも 1 つ (ときには 2 つ) の変数が含まれています。コマンドの実行を簡単にするには、次の変数を検索して実際の特定の値に置き換えます。

{Service URL} サービス URL は、Azure portal でプロビジョニングした DICOM サービスにアクセスするための URL です (例: https://<workspacename-dicomservicename>.dicom.azurehealthcareapis.com)。要求を行う際は、URL の一部としてバージョンを必ず指定してください。詳細については、DICOM サービスの API バージョン管理に関するドキュメントを参照してください。
{path-to-dicoms} - red-triangle.dcm ファイルを含むディレクトリへのパスです (例: C:/dicom-server/docs/dcms)
- 区切り記号としてスラッシュを使い、ディレクトリの末尾にはスラッシュを "付けないで" でください。

DICOM インスタンスをアップロードする (STOW)

multipart/related を使用してインスタンスを保存する

この要求の目的は、multipart/related を使って DICOM ファイルをアップロードする方法を示すことです。

注意

DICOM サービスは、DICOM 標準ほど厳格ではありません。ただし、この例では、標準に厳密に準拠する POST 要求を示しています。

詳細:

パス: ../studies
メソッド: POST
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {トークンの値}
本文:
- Content-Type: アップロードする各ファイルの application/dicom (境界値で区切る)

一部のプログラミング言語とツールでは動作が異なります。たとえば、独自の境界を定義する必要がある場合があります。そのようなツールでは、Content-Type ヘッダーを少し変更して使う必要があるかもしれません。次のツールも正常に使用できます。

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

特定の検査のインスタンスを格納する

この要求では、指定した検査に関する multipart/related を使って DICOM ファイルをアップロードする方法を示します。

詳細:

パス: ../studies/{study}
メソッド: POST
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {トークンの値}
本文:
- Content-Type: アップロードする各ファイルの application/dicom (境界値で区切る)

一部のプログラミング言語とツールでは動作が異なります。たとえば、独自の境界を定義する必要がある場合があります。そのような言語やツールでは、Content-Type ヘッダーを少し変更して使う必要があるかもしれません。次のツールも正常に使用できます。

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --request POST "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

Store-single-instance

注意

これは、multipart/related の POST を構成する必要なく 1 つの DICOM ファイルをアップロードできる、非標準 API です。 cURL では multipart/related が適切に処理されますが、この API を使うと、Postman などのツールで DICOM サービスにファイルをアップロードできます。

1 つの DICOM ファイルをアップロードするには、次のメソッドが必要になります。

詳細:

パス: ../studies
メソッド: POST
Headers:
- Accept: application/dicom+json
- Content-Type: application/dicom
- Authorization: Bearer {トークンの値}
本文:
- 1 つの DICOM ファイルがバイナリバイトとして含まれます。

curl --location --request POST "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

multipart/related を使用してインスタンスをアップサートする

注意

これは、multipart/related を使用して DICOM ファイルのアップサートを可能にする非標準 API です。

詳細:

パス: ../studies
メソッド: PUT
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {トークンの値}
本文:
- Content-Type: アップロードする各ファイルの application/dicom (境界値で区切る)

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/red-triangle.dcm;type=application/dicom"
--trace-ascii "trace.txt"

特定の検査のインスタンスをアップサートする

注意

これは、指定した検査に対して multipart/related を使用して DICOM ファイルのアップサートを可能にする非標準 API です。

詳細:

パス: ../studies/{study}
メソッド: PUT
Headers:
- Accept: application/dicom+json
- Content-Type: multipart/related; type="application/dicom"
- Authorization: Bearer {トークンの値}
本文:
- Content-Type: アップロードする各ファイルの application/dicom (境界値で区切る)

Content-Type: multipart/related; type="application/dicom"; boundary=ABCD1234
Content-Type: multipart/related; boundary=ABCD1234
Content-Type: multipart/related

curl --request PUT "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: application/dicom+json"
--header "Content-Type: multipart/related; type=\"application/dicom\""
--header "Authorization: Bearer {token value}"
--form "file1=@{path-to-dicoms}/blue-circle.dcm;type=application/dicom"

1 つのインスタンスをアップサートする

注意

これは、1 つの DICOM ファイルのアップサートを可能にする非標準 API です。

1 つの DICOM ファイルをアップロードするには、次のメソッドを使います。

詳細:

パス: ../studies
メソッド: PUT
Headers:
- Accept: application/dicom+json
- Content-Type: application/dicom
- Authorization: Bearer {トークンの値}
本文:
- 1 つの DICOM ファイルをバイナリバイトとして含めます。

curl --location --request PUT "{Service URL}/v{version}/studies"
--header "Accept: application/dicom+json"
--header "Content-Type: application/dicom"
--header "Authorization: Bearer {token value}"
--data-binary "@{path-to-dicoms}/green-square.dcm"

DICOM を取得する (WADO)

検査内のすべてのインスタンスを取得する

この要求では、1 つの検査内にあるすべてのインスタンスを取得し、multipart/related バイトのコレクションとして返します。

詳細:

パス: ../studies/{study}
メソッド: GET
Headers:
- Accept: multipart/related; type="application/dicom"; transfer-syntax=*
- Authorization: Bearer {トークンの値}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

この cURL コマンドは、出力ファイル (suppressWarnings.txt) にダウンロードしたバイトを表示しますが、直接の DICOM ファイルではなく、multipart/related ダウンロードのテキスト表現にすぎません。

検査に含まれるすべてのインスタンスのメタデータを取得する

この要求は、1 つの検査内のすべてのインスタンスのメタデータを取得します。

詳細:

パス: ../studies/{study}/metadata
メソッド: GET
Headers:
- Accept: application/dicom+json
- Authorization: Bearer {トークンの値}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

シリーズ内のすべてのインスタンスを取得する

この要求では、1 つのシリーズ内にあるすべてのインスタンスを取得し、multipart/related バイトのコレクションとして返します。

詳細:

パス: ../studies/{study}/series/{series}
メソッド: GET
Headers:
- Accept: multipart/related; type="application/dicom"; transfer-syntax=*
- Authorization: Bearer {トークンの値}

この cURL コマンドは、出力ファイル (suppressWarnings.txt) にダウンロードしたバイトを表示しますが、それは DICOM ファイルではなく、multipart/related ダウンロードのテキスト表現にすぎません。

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652"
--header "Accept: multipart/related; type=\"application/dicom\"; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

シリーズに含まれるすべてのインスタンスのメタデータを取得する

この要求では、1 つの検査に含まれるすべてのインスタンスのメタデータを取得します。

詳細:

パス: ../studies/{study}/series/{series}/metadata
メソッド: GET
Headers:
- Accept: application/dicom+json
- Authorization: Bearer {トークンの値}

curl --request GET "{Service URL}/v{version}/studies1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

検査のシリーズに含まれる 1 つのインスタンスを取得する

この要求では、1 つのインスタンスを取得し、DICOM 形式のバイトストリームとして返します。

詳細:

パス: ../studies/{study}/series{series}/instances/{instance}
メソッド: GET
Headers:
- Accept: application/dicom; transfer-syntax=*
- Authorization: Bearer {トークンの値}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395"
--header "Accept: application/dicom; transfer-syntax=*"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"

検査のシリーズに含まれる 1 つのインスタンスのメタデータを取得する

この要求は、1 つの検査とシリーズに含まれる 1 つのインスタンスのメタデータを取得します。

詳細:

パス: ../studies/{study}/series/{series}/instances/{instance}/metadata
メソッド: GET
Headers:
- Accept: application/dicom+json
- Authorization: Bearer {トークンの値}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/metadata"
--header "Accept: application/dicom+json"
--header "Authorization: Bearer {token value}"

1 つのインスタンスから 1 つまたは複数のフレームを取得する

この要求では、1 つのインスタンスから 1 つ以上のフレームを取得し、multipart/related バイトのコレクションとして返します。各フレーム番号をコンマで区切ったリストを渡すことで、複数のフレームを取得できます。画像を含むすべての DICOM インスタンスには少なくとも 1 つのフレームがあり、多くの場合、それは単にインスタンス自体に関連付けられている画像です。

詳細:

パス: ../studies/{study}/series{series}/instances/{instance}/frames/1,2,3
メソッド: GET
Headers:
- Accept: multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (既定値) または
- Accept: multipart/related; type="application/octet-stream"; transfer-syntax=* または
- Accept: multipart/related; type="application/octet-stream";
- Authorization: Bearer {トークンの値}

curl --request GET "{Service URL}/v{version}/studies/1.2.826.0.1.3680043.8.498.13230779778012324449356534479549187420/series/1.2.826.0.1.3680043.8.498.45787841905473114233124723359129632652/instances/1.2.826.0.1.3680043.8.498.47359123102728459884412887463296905395/frames/1"
--header "Accept: multipart/related; type=\"application/octet-stream\"; transfer-syntax=1.2.840.10008.1.2.1"
--header "Authorization: Bearer {token value}"
--output "suppressWarnings.txt"