次の方法で共有

拡張クエリ タグ

  • [アーティクル]

概要

既定では、DICOM サービスは 、準拠ステートメントで指定された DICOM タグに対するクエリをサポートします。 拡張クエリ タグを有効にすると、アプリケーションのニーズに基づいてタグの一覧を簡単に拡張できます。

以下に示す API を使用すると、ユーザーは DICOM スタディ、シリーズ、およびインスタンスのインデックスを、QIDO-RS クエリで指定できるように、標準とプライベートの両方の DICOM タグでインデックスを作成できます。

API

バージョン: v1

特定の DICOM サービス インスタンスでサポートされているタグを管理するために、次の API エンドポイントが追加されています。

API 説明
POST .../extendedquerytags 拡張クエリ タグの追加
GET .../extendedquerytags 拡張クエリ タグの一覧表示
GET .../extendedquerytags/{tagPath} 拡張クエリ タグの取得
DELETE .../extendedquerytags/{tagPath} 拡張クエリ タグの削除
PATCH .../extendedquerytags/{tagPath} 拡張クエリ タグの更新
GET .../extendedquerytags/{tagPath}/errors 拡張クエリ タグ エラーの一覧表示
GET .../operations/{operationId} Get 操作

拡張クエリ タグを追加する

1 つ以上の拡張クエリ タグを追加し、指定したタグを使用して現在の DICOM インスタンスのインデックスを再作成する実行時間の長い操作を開始します。

POST .../extendedquerytags

要求ヘッダー

名前 必須 Type 説明
Content-Type True string application/json がサポートされています

要求本文

名前 必須 Type 説明
body 追加するための拡張クエリ タグ[]

制限事項

次の VR の種類がサポートされています。

Vr 説明 単一値の一致 範囲の一致 あいまい一致
AE アプリケーション エンティティ X
AS Age String X
CS コード文字列 X
DA Date X X
DS 10 進文字列 X
DT Date Time X X
FD 浮動小数点倍精度浮動小数点型 (Double) X
FL 浮動小数点単精度浮動小数点 X
IS 整数文字列 X
Lo 長い文字列 X
PN 個人名 X X
SH 短い文字列 X
SL Signed Long X
SS Signed Short X
TM Time X X
UI 一意識別子 X
UL Unsigned Long X
US Unsigned Short X

注意

Sequence of Items (SQ) 型のタグのタグであるシーケンシャル タグは、現在サポートされていません。 最大 128 個の拡張クエリ タグを追加できます。

Responses

名前 Type 説明
202 (承認済み) 操作リファレンス 拡張クエリ タグが追加され、実行時間の長い操作が開始され、既存の DICOM インスタンスのインデックスが再作成されました
400 (Bad Request) 要求本文に無効なデータがある
409 (Conflict) 1 つ以上の要求されたクエリ タグが既にサポートされています

拡張クエリ タグを一覧表示する

すべての拡張クエリ タグの一覧。

GET .../extendedquerytags

Responses

名前 Type 説明
200 (OK) 拡張クエリ タグ[] 拡張クエリ タグを返します

拡張クエリ タグを取得する

拡張クエリ タグを取得します。

GET .../extendedquerytags/{tagPath}

URI パラメーター

名前 / 必須 Type 説明
tagPath path True string tagPath はタグのパスであり、タグまたはキーワード (keyword)にすることができます。 たとえば、患者 ID は または で 00100020 表されます。 PatientId

Responses

名前 Type 説明
200 (OK) 拡張クエリ タグ 指定した を持つ拡張クエリ タグ tagPath
400 (Bad Request) 要求されたタグ パスが無効です
404 (Not Found) 要求された tagPath を持つ拡張クエリ タグが見つかりません

拡張クエリ タグを削除する

拡張クエリ タグを削除します。

DELETE .../extendedquerytags/{tagPath}

URI パラメーター

名前 / 必須 Type 説明
tagPath path True string tagPath はタグのパスであり、タグまたはキーワード (keyword)にすることができます。 たとえば、患者 ID は または で 00100020 表されます。 PatientId

Responses

名前 Type 説明
204 (コンテンツなし) 要求された tagPath を含む拡張クエリ タグが正常に削除されました。
400 (Bad Request) 要求されたタグ パスが無効です。
404 (Not Found) 要求された tagPath を持つ拡張クエリ タグが見つかりません

拡張クエリ タグを更新する

拡張クエリ タグを更新します。

PATCH .../extendedquerytags/{tagPath}

URI パラメーター

名前 / 必須 Type 説明
tagPath path True string tagPath はタグのパスであり、タグまたはキーワード (keyword)にすることができます。 たとえば、患者 ID は または で 00100020 表されます。 PatientId

要求ヘッダー

名前 必須 Type 説明
Content-Type True string `SUSER_ID` はサポートされています。

要求本文

名前 必須 Type 説明
body 更新用の拡張クエリ タグ

Responses

名前 Type 説明
20 (OK) 拡張クエリ タグ 更新された拡張クエリ タグ
400 (Bad Request) 要求されたタグ パスまたは本文が無効です
404 (Not Found) 要求された tagPath を持つ拡張クエリ タグが見つかりません

拡張クエリ タグのエラーを一覧表示する

拡張クエリ タグのエラーを一覧表示します。

GET .../extendedquerytags/{tagPath}/errors

URI パラメーター

名前 / 必須 Type 説明
tagPath path True string tagPath はタグのパスであり、タグまたはキーワード (keyword)にすることができます。 たとえば、患者 ID は または で 00100020 表されます。 PatientId

Responses

名前 Type 説明
200 (OK) 拡張クエリ タグ エラー[] タグに関連付けられている拡張クエリ タグ エラーの一覧
400 (Bad Request) 要求されたタグ パスが無効です
404 (Not Found) 要求された tagPath を持つ拡張クエリ タグが見つかりません

Get 操作

実行時間の長い操作を取得します。

GET .../operations/{operationId}

URI パラメーター

名前 / 必須 Type 説明
operationId path True string 操作 ID

Responses

名前 Type 説明
200 (OK) 操作 指定した ID に対する完了した操作
202 (承認済み) 操作 指定した ID の実行中の操作
404 (Not Found) 操作が見つかりません

拡張クエリ タグを含む QIDO

タグの状態

拡張クエリ タグの 状態 は、現在の状態を示します。 拡張クエリ タグが最初に追加されると、その状態は に Adding設定され、実行時間の長い操作が開始され、既存の DICOM インスタンスのインデックスが再作成されます。 操作が完了すると、タグの状態が に Ready更新されます。 拡張クエリ タグを QIDO で使用できるようになりました。

たとえば、製造元のモデル名 (0008,1090) タグが追加され、状態が Ready の場合、次のクエリを使用して、製造元モデル名で格納されているインスタンスをフィルター処理できます。

../instances?ManufacturerModelName=Microsoft

既存のタグと共に使用することもできます。 次に例を示します。

../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true

タグ クエリの状態

QueryStatus は、QIDO がタグに対して許可されているかどうかを示します。 インデックス再作成操作がタグの 1 つ以上の DICOM インスタンスを処理できない場合、そのタグの QueryStatus は自動的に に Disabled 設定されます。 Update Extended Query Tag API を使用して を に設定することで、インデックス作成エラーを無視し、クエリでこのタグをQueryStatusEnabled使用できるようにすることができます。 少なくとも 1 つの手動で有効なタグを参照する QIDO 要求には、応答ヘッダー にインデックス作成エラーを含むタグのセットが含まれます erroneous-dicom-attributes。

たとえば、インデックス再作成中に拡張クエリ タグ PatientAge にエラーがあったが、手動で有効になっていたとします。 次のクエリでは、 ヘッダーにerroneous-dicom-attributesが表示PatientAgeされます。

../instances?PatientAge=035Y

定義

拡張クエリ タグ

QIDO-RS でサポートされる DICOM タグ。

名前 Type 説明
パス string タグのパス。通常はグループ ID と要素 ID で構成されます。たとえば、 PatientId (0010,0020) にはパス 00100020
Vr string このタグの値表現
PrivateCreator string このプライベート タグの実装者の識別コード
Level 拡張クエリ タグ レベル 拡張クエリ タグのレベル
Status 拡張クエリ タグの状態 拡張クエリ タグの状態
QueryStatus 拡張クエリ タグクエリの状態 拡張クエリ タグのクエリの状態
エラー 拡張クエリ タグ エラー リファレンス 拡張クエリ タグ エラーへの参照
Operation 操作リファレンス 実行時間の長い操作への参照

コード 例 1 は、状態の標準タグ (0008,0070) Ready です。

{
    "status": "Ready",
    "level": "Instance",
    "queryStatus": "Enabled",
    "path": "00080070",
    "vr": "LO"
}

コード 例 2 は、状態の標準タグ (0010,1010) Adding です。 ID 1a5d0306d9624f699929ee1a59ed57a0 を持つ操作が実行されており、これまでに 21 件のエラーが発生しました。

{
    "status": "Adding",
    "level": "Study",
    "errors": {
        "count": 21,
        "href": "https://localhost:63838/extendedquerytags/00101010/errors"
    },
    "operation": {
        "id": "1a5d0306d9624f699929ee1a59ed57a0",
        "href": "https://localhost:63838/operations/1a5d0306d9624f699929ee1a59ed57a0"
    },
    "queryStatus": "Disabled",
    "path": "00101010",
    "vr": "AS"
}

操作リファレンス

実行時間の長い操作への参照。

名前 Type 説明
id string 操作 ID
Href string 操作の URI

操作

実行時間の長い操作を表します。

名前 Type 説明
OperationId string 操作 ID
OperationType 操作の種類 実行時間の長い操作の種類
CreatedTime string 操作が作成された時刻
LastUpdatedTime string 操作が最後に更新された時刻
Status 操作の状態 操作の実行時の状態を表します
PercentComplete Integer 操作によって完了した作業の割合
リソース string[] 操作が作成または操作しているリソースの場所のコレクション

次のコード 例 は、実行中のインデックス再作成操作です。

{
    "resources": [
        "https://localhost:63838/extendedquerytags/00101010"
    ],
    "operationId": "a99a8b51-78d4-4fd9-b004-b6c0bcaccf1d",
    "type": "Reindex",
    "createdTime": "2021-10-06T16:40:02.5247083Z",
    "lastUpdatedTime": "2021-10-06T16:40:04.5152934Z",
    "status": "Running",
    "percentComplete": 10
}

操作の状態

実行時間の長い操作の実行時の状態を表します。

名前 Type 説明
NotStarted string 操作が開始されていません
実行中 string 操作が実行中で、まだ完了していません
完了 string 操作が正常に完了しました
失敗 string 1 つ以上のエラーが発生した後、操作が途中で停止しました

拡張クエリ タグ エラー

拡張クエリ タグのインデックス作成操作中に発生したエラー。

名前 Type 説明
StudyInstanceUid string インデックス作成エラーが発生したスタディ インスタンス UID
SeriesInstanceUid string インデックス作成エラーが発生したシリーズ インスタンス UID
SopInstanceUid string インデックス作成エラーが発生した Sop インスタンス UID
CreatedTime string エラーが発生した時刻 (UTC)
ErrorMessage string エラー メッセージ

次のコード 例 には、DICOM インスタンスで予期しない値の長さのエラーが含まれています。 2021-10-06T16:41:44.4783136 で発生しました。

{
    "studyInstanceUid": "2.25.253658084841524753870559471415339023884",
    "seriesInstanceUid": "2.25.309809095970466602239093351963447277833",
    "sopInstanceUid": "2.25.225286918605419873651833906117051809629",
    "createdTime": "2021-10-06T16:41:44.4783136",
    "errorMessage": "Value length is not expected."
}

拡張クエリ タグ エラー リファレンス

拡張クエリ タグ エラーへの参照。

名前 Type 説明
Count Integer 拡張クエリ タグのエラーの合計数
Href string 拡張クエリ タグエラーへの URI

演算の種類

実行時間の長い操作の種類。

名前 Type 説明
インデックスの再作成 string 新しいタグに基づいて以前に追加されたデータのインデックスを更新するインデックス再作成操作

拡張クエリ タグの状態

拡張クエリ タグの状態。

名前 Type 説明
追加中 string 拡張クエリ タグが追加され、実行時間の長い操作で既存の DICOM インスタンスのインデックスが再作成されています
Ready string 拡張クエリ タグは QIDO-RS に対応しています
削除中 string 拡張クエリ タグが削除されています

拡張クエリ タグ レベル

このタグが適用される DICOM 情報階層のレベル。

名前 Type 説明
インスタンス string 拡張クエリ タグは、インスタンス レベルで関連しています
系列 string 拡張クエリ タグは、系列レベルで関連しています
検査 string 拡張クエリ タグは、学習レベルで関連しています

拡張クエリ タグクエリの状態

拡張クエリ タグのクエリ状態。

名前 Type 説明
無効 string 拡張クエリ タグのクエリは許可されません
Enabled string 拡張クエリ タグのクエリが許可されている

Note

インデックスの再作成操作中にエラーが発生すると、拡張クエリ タグの QIDO が無効になります。 拡張クエリ タグの更新 API を呼び出して有効にすることができます。

更新用の拡張クエリ タグ

更新用の拡張クエリ タグを表します。

名前 Type 説明
QueryStatus 拡張クエリ タグクエリの状態 拡張クエリ タグのクエリ状態

追加するための拡張クエリ タグ

追加する拡張クエリ タグを表します。

名前 必須 Type 説明
パス True string タグのパス。通常、(0010,0020) のグループ ID と要素 ID で構成され PatientId 、パス00100020
Vr string このタグの値表現。 標準タグの場合は省略可能で、プライベート タグには必須です
PrivateCreator string このプライベート タグの実装者の識別コード。 タグがプライベート タグの場合にのみ設定されます
Level True 拡張クエリ タグ レベル このタグが関連する階層を表します。 スタディ、シリーズ、またはインスタンスのいずれかである必要があります

コード 例 1MicrosoftPC では、インスタンス レベルで値表現を使用 SS してプライベート タグ (0401,1001) を定義しています。

{
    "Path": "04011001",
    "VR": "SS",
    "PrivateCreator": "MicrosoftPC",
    "Level": "Instance"
}

コード例 2 では、標準タグとキーワード (keyword)ManufacturerModelNameを使用しLO、系列レベルで定義されている値表現を使用します。

{
    "Path": "ManufacturerModelName",
    "VR": "LO",
    "Level": "Series"
}

コード 例 3 では、標準タグ (0010,0040) が使用され、研究で定義されています。 値表現は、DICOM 標準によって既に定義されています。

{
    "Path": "00100040",
    "Level": "Study"
}

まとめ

この概念記事では、DICOM サービス内の拡張クエリ タグ機能の概要について説明しました。

次の手順

DICOM サービスの展開の詳細については、次を参照してください。

DICOM サービスを Azure にデプロイする

DICOM サービスでの DICOMweb™Standard API の使用