DICOM 適合性宣言

Cloud Healthcare API 内の DICOM ストアは、DICOM PS3.18 - ウェブサービス標準（一般に DICOMweb）で指定された RESTful ウェブサービスのサブセットをサポートします。具体的には、スタディのサービスとリソース（以前は WADO-RS、STOW-RS、QIDO-RS サービスと呼ばれていました）をサポートしています。

また、Cloud Healthcare API では、DICOM インスタンスを削除するための独自のウェブサービスがサポートされます。

Cloud Healthcare API は、URI サービス、ワークリスト サービス、Non-Patient Instance Service、または Capabilities トランザクションのいずれも対象外です。

Retrieve トランザクション

Retrieve トランザクションは、DICOM 画像データを取得するための RESTful ウェブサービスです。

Retrieve トランザクションでは、次のリソースを取得できます。

  • DICOM リソース:
    • 調査結果
    • シリーズ
    • インスタンス
    • フレーム
    • Bulkdata
  • メタデータ リソース
    • 調査結果
    • シリーズ
    • インスタンス
  • レンダリングされたリソース
    • インスタンス
    • フレーム

サムネイル リソースはサポートされていません。

これらのメソッドの割り当てと上限の詳細については、割り当てと上限をご覧ください。

DICOM のスタディ / シリーズ / インスタンス

次の Accept ヘッダーがサポートされています。

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1（デフォルト）
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*

DICOM インスタンス

上記の Accept ヘッダーに加えて、RetrieveInstance では利便性を高めるためにシングルパートのコンテンツ タイプをサポートしています。

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

これは公式の DICOMweb 標準では使用されません。

DICOM フレーム

次の Accept ヘッダーがサポートされています。

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1（デフォルト）
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

* の転送構文を使用すると、ユーザーはコード変換を行わないようにリクエストできるため、アップロードされたファイルの転送構文が使用されます。application/octet-stream の場合、アップロードされた DICOM ファイルに表示される形式でバルクデータが返されます。

レンダリングされたリソース

次の Accept ヘッダーがサポートされています。

  • image/jpeg（デフォルト）
  • image/png

インスタンス リソースまたはフレーム リソースの取得のみがサポートされています。

サポートされている URL パラメータはありません。

メタデータ リソース

次の Accept ヘッダーがサポートされています。

  • application/dicom+json（デフォルト）
  • multipart/related; type=application/dicom+xml

転送構文パラメータは、メタデータ リソースをリクエストするエンドポイントではサポートされていないため、InlineBinary 要素としてエンコードされたタグは、リトル エンディアンのバイト順序を使用してエンコードされます。

デフォルトでは、RetrieveMetadata は、OB、OW、UN といった DICOM 規格の値表現を持つ属性を返しません。プレビューの Bulkdata の定義に一致するタグの BulkDataURI を返すには、Preview version を使用します。

メタデータ リソースでは、約 1 MiB を超えるデータが含まれる DICOM シーケンス タグは返されません。この制限はメタデータ リソースにのみ適用されます。DICOM リソースには、これらのタグが引き続き含まれます。

Bulkdata リソース（プレビュー）

次の Accept ヘッダーがサポートされています。

  • multipart/related; type="application/octet-stream"; transfer-syntax=*（デフォルト）
  • application/octet-stream; transfer-syntax=*

コード変換でサポートされている転送構文

上記の Accept ヘッダーには、API からリクエスト可能なメディアタイプと転送構文が記述されていますが、アップロードされた元のファイルの転送構文によっては記述できない場合があります。特に、コード変換は次の転送構文からのみ可能です。

  • 1.2.840.10008.1.2（リトル エンディアン暗黙指定）
  • 1.2.840.10008.1.2.1（リトル エンディアン明示指定）
  • 1.2.840.10008.1.2.2（明示的 VR ビッグ エンディアン）
  • 1.2.840.10008.1.2.4.50（JPEG ベースライン プロセス 1）
  • 1.2.840.10008.1.2.4.57（JPEG ロスレス）
  • 1.2.840.10008.1.2.4.70（JPEG ロスレス選択値 1）
  • 1.2.840.10008.1.2.4.90（JPEG 2000 ロスレスのみ）
  • 1.2.840.10008.1.2.4.91（JPEG 2000）
  • 1.2.840.10008.1.2.5（RLE ロスレス）

元のファイルの転送構文が上記のリストにない場合、別の形式へのコード変換をリクエストすると、エラーが返されます。

Cloud Healthcare API では、ビット深度が 8 より大きい非モノクロ画像を JPEG にコード変換できません。 また、Bits Allocated（0028、0100）の値が 1 の画像、または Float Pixel Data（7FE0,0008）、Double Float Pixel Data（7FE0,0009）タグで保存されている画像は、ネイティブ形式間でのみコード変換できます。

コード変換を無効にして API からファイルを取得するには、Accept ヘッダーで transfer-syntax=* を設定します。

ステータス コード

コード 意味
200（OK） レスポンス ペイロードには、すべてのターゲット リソースの表現が含まれます。
400（不正なリクエスト） 指定されたターゲット リソースのリクエスト（例: ピクセルデータが欠落）が無効である（例: 不正なクエリ パラメータやヘッダー）。
401（未承認） リクエストに認証情報が指定されていません。
403（アクセスの拒否） 認証されたユーザーがこのリソースにアクセスできません（またはリソースが存在しません）。
406（受理できません） サーバーは、受け入れ可能なメディアタイプをサポートしていません。
429（リクエスト数が多すぎる） クライアントが割り当てを超えています。
503（サービス利用不可） サーバーを現在利用できないか、リクエストの期限を過ぎています。

Store トランザクション

Store トランザクションは、DICOM 画像データを格納するための RESTful ウェブサービスです。

Store トランザクションでは、パート 10 の DICOM バイナリ ファイルを直接受け入れるか、DICOM ファイルをメタデータ（JSON 形式）とバルクデータに分割して受け入れます。 この 2 つのバージョンのセマンティクスは異なります。これについては次のセクションで説明します。

このメソッドの割り当てと上限について詳しくは、割り当てと上限をご覧ください。

DICOM パート 10 バイナリ ファイル

次のコンテンツ タイプがサポートされています。

  • multipart/related; type=application/dicom
  • application/dicom

属性の強制変換や置換がサーバーで行われることはありません。

このバージョンは、すべての転送構文と SOP クラスに対応しています。いくつかの重要なメタデータ属性を抽出するために、DICOM ファイルの最小限の検証のみが行われます。

利便性のため、Store トランザクションでは、コンテンツタイプが application/dicom の単一の DICOM インスタンスを含むシングルパートの HTTP リクエストも受け入れます。これは公式の DICOMweb 標準では使用されません。

関連する入門ガイドについては、DICOM インスタンスの格納をご覧ください。

JSON メタデータとバルクデータ リクエスト

JSON メタデータとバルクデータを使用してインスタンスを格納する場合、最初のマルチパート部分は DICOM インスタンスの JSON 配列で構成する必要があります。

最初の部分のコンテンツ タイプは application/dicom+json; transfer-syntax=TransferSyntaxUID である必要があります。TransferSyntaxUID は、InlineBinary オブジェクトのバイナリデータのエンコードに使用された転送構文です。 メタデータに InlineBinary オブジェクトが存在しない場合は、transfer-syntax パラメータを省略できます。

以下の DICOM 要素は、JSON メタデータのすべてのインスタンスに存在している必要があります。

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

特定の文字セットを ISO_IR 192 に設定し、JSON メタデータを Unicode UTF-8 でエンコードする必要があります。TransferSyntaxUID は、次のサポートされていない転送構文を除いて、任意の有効な転送構文に設定できます。

  • 1.2.840.10008.1.2.2（明示的 VR ビッグ エンディアン）
  • 1.2.840.10008.1.2.1.99（デフレートされた明示的 VR リトル エンディアン）

JSON メタデータ内で、ユーザーは OB、OW、UN の VR を使用する DICOM タグに複数の BulkDataURIs を指定できます。 これらの BulkDataURIs は、URI を含むタグのバイナリデータが、Content-Location ヘッダーが BulkDataURIs に設定された次の部分で送信されることを示します。

JSON メタデータの各インスタンスは、最大 1 つの BulkDataURI を持つことが可能です。JSON メタデータに重複する BulkDataURI を存在させることはできません。圧縮されたイメージのバルクデータは、PixelData タグに対してのみ送信する必要があります。送信時に、バルクデータ部分で指定した転送構文がインスタンスの TransferSyntaxUID 要素の値と一致している必要があります。

バルクデータ部分では次のコンテンツ タイプがサポートされています。

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

バイナリデータを指定するもう 1 つの方法は、InlineBinary base64 エンコード文字列としてエンコードすることです。 この方法は、バルクデータ部分として送信する必要がある PixelData を除いて、すべてのタグに対してサポートされています。InlineBinary オブジェクトが JSON メタデータで使用される場合、エンコードに使用された転送構文は JSON メタデータ部分のコンテンツ タイプで指定する必要があります。

サーバーは画像ピクセル記述マクロ属性を取得しません。

関連する入門ガイドについては、JSON メタデータと JPEG ファイルから DICOM インスタンスを作成するをご覧ください。

レスポンス

エラーが発生すると、FailureDetail（0009、0097）タグ（XML レスポンスの場合）、または FailureDetailJSON（0009、1097）タグ（JSON レスポンスの場合）が追加で返されます。FailureDetail タグには、人が読める形式でエラーの説明が記述されています。

DICOM インスタンスに、DICOM ストアにすでに存在する別のインスタンスと同じ <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> タプルがある場合、「すでに存在」FailureDetail タグとともに処理失敗エラーが返されます。

レスポンスは、JSON 形式または XML 形式のいずれかで指定できます。これは、次の Accept ヘッダー値で制御できます。

  • application/dicom+xml（デフォルト）
  • application/dicom+json

ステータス コード

コード 意味
200（OK） リソースが正常に保存されました。
400（不正なリクエスト） リクエストが無効です（例: サポートされていないメディアタイプや転送構文）。
401（未承認） リクエストに認証情報が指定されていません。
403（アクセスの拒否） 認証されたユーザーがこのリソースにアクセスできません（またはリソースが存在しません）。
406（受理できません） サーバーは、受け入れ可能なメディアタイプをサポートしていません。
409（競合） 少なくとも 1 つのリソースが正常に保存されませんでした（無効な DICOM ファイルなど）。詳細については、レスポンス本文の FailureDetail タグをご覧ください。
429（リクエスト数が多すぎる） クライアントが割り当てを超えています。
503（サービス利用不可） サーバーを現在利用できないか、リクエストの期限を過ぎています。

Search トランザクション

Search トランザクションは、DICOM 画像メタデータをクエリするための RESTful ウェブサービスです。

Cloud Healthcare API は、スタディ、シリーズ、インスタンスの検索をサポートしています。

検索パラメータ

次のタグによる検索がサポートされています。

  • スタディ:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • シリーズ: すべてのスタディレベルの検索キーワードと
    • SeriesInstanceUID
    • モダリティ
  • インスタンス: すべてのスタディ / シリーズレベルの検索キーワードと
    • SOPInstanceUID

範囲クエリをサポートする StudyDate とファジー マッチングをサポートする PatientName を除き、単一の値、完全一致のみがサポートされます。

次に挙げる URL パラメータもサポートされています。

  • fuzzymatching: true に設定すると、PatientName タグにファジー一致が適用されます。ファジー一致では、クエリ内の PatientName の値と格納された値の両方のトークン化と正規化が行われます。検索トークンと保存されたトークンのプレフィックスが等しい場合に一致します。たとえば、PatientName が "John‐Doe" の場合、「jo」、「Do」、「John Doe」はすべて一致します。ただし、「ohn」は一致しません。
  • includefield: DICOM タグ ID やキーワードなどの attributeID のカンマ区切りリストに設定することも、値 all に設定して使用可能なすべてのタグを返すようにすることもできます。利用可能なタグの一覧については、返される結果をご覧ください。

ページングは、limit クエリ パラメータと offset クエリ パラメータを使用してサポートされています。利用できる結果が他にない場合、警告レスポンス ヘッダーはありません。他に結果があるかどうかを判断するために、追加のクエリを実行する必要があります。

  • limit: 返される結果の最大数。スタディ / シリーズの場合は最大 5,000 件、インスタンスの場合は最大 50,000 件。デフォルトの結果の数は、スタディ / シリーズの場合は 100 件、インスタンスの場合は 1,000 件です。

  • offset: 最初にスキップする結果の数（最大 1,000,000 件）。

UTC からのタイムゾーン オフセットはサポートされていません。

返された結果

レスポンスは、JSON 形式または XML 形式のいずれかで指定できます。これは、次の Accept ヘッダー値を使用して制御できます。

  • application/dicom+json（デフォルト）
  • multipart/related; type=application/dicom+xml

デフォルトでは、次の属性が返されます。

  • スタディ:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • シリーズ:
    • SpecificCharacterSet
    • モダリティ
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • インスタンス:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • 行
    • 列
    • BitsAllocated
    • NumberOfFrames

includefield=all の場合、デフォルトの属性と次の属性が返されます。

  • スタディ:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • シリーズ:
    • SeriesNumber
    • Laterality
    • SeriesDate
    • SeriesTime
  • インスタンス: 次の例外を除く、DICOM インスタンスに存在するすべての属性。

デフォルトでは、searchForInstances は OB、OW、UN といった DICOM 規格の値表現を持つ属性を返しません。プレビューの Bulkdata の定義に一致するタグの BulkDataURI を返すには、プレビュー searchForInstances を使用します。

メタデータ レスポンスでは、約 1 MiB を超えるデータが含まれる DICOM シーケンス タグは返されません。

一貫性がない / 無効なメタデータ

SearchForStudies または SearchForSeries の場合、複数のインスタンス間でスタディレベルまたはシリーズレベルのメタデータが一致しない可能性があります。たとえば、2 つのインスタンスを同じ StudyInstanceUID を使用してアップロードし、異なる StudyDate を持たせることができます。この場合、検索動作は明確に定義されません。その値による検索が成功する場合と失敗する場合があり、返される値が呼び出しごとに異なる可能性があります。

ステータス コード

コード 意味
200（OK） レスポンス ペイロードには、すべてのターゲット リソースの表現が含まれます。
400（不正なリクエスト） リクエストが無効です（無効なクエリ パラメータなど）。
401（未承認） リクエストに認証情報が指定されていません。
403（アクセスの拒否） 認証されたユーザーがこのリソースにアクセスできません（またはリソースが存在しません）。
406（受理できません） サーバーは、受け入れ可能なメディアタイプをサポートしていません。
429（リクエスト数が多すぎる） クライアントが割り当てを超えています。
503（サービス利用不可） サーバーを現在利用できないか、リクエストの期限を過ぎています。

削除

Cloud Healthcare API は、次の独自のアクション タイプをサポートしています。

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

これらは、それぞれ対応する WDO-RS のリクエストパス（RetrieveStudy、RetriatSeries、RetrieveInstance）を使用します。HTTP GET リクエストの代わりに、DELETE リクエストが使用されます。その結果、指定したスタディ、シリーズ、またはインスタンスが、そこに含まれるすべての DICOM リソースとともに削除されます。

DeleteStudy メソッドと DeleteSeries メソッドは、スタディまたはシリーズ内のすべてのインスタンスを削除する長時間実行オペレーションを返します。オペレーションで削除されるスタディーまたはシリーズには、オペレーションが完了するまでインスタンスを挿入できないことに注意してください。

オペレーションの入門ガイドについては、長時間実行オペレーションの管理をご覧ください。

DeleteInstance リクエストが成功すると、空のレスポンスが返されます。

ステータス コード

コード 意味
200（OK） リクエスト リソースが削除されました。
400（不正なリクエスト） リクエストは無効です。
401（未承認） リクエストに認証情報が指定されていません。
403（アクセスの拒否） 認証されたユーザーがこのリソースにアクセスできません（またはリソースが存在しません）。
429（リクエスト数が多すぎる） クライアントが割り当てを超えています。
503（サービス利用不可） サーバーを現在利用できないか、リクエストの期限を過ぎています。

Accept ヘッダー

上記のメソッドの一部では、HTTP の Accept ヘッダーを使用してレスポンス形式を制御できます。ワイルドカード マッチングは、トップレベル（*/* など）とサブタイプ（image/* など）の両方でサポートされています。相対的な優先度を示すために q 値を指定することもできます。q 値が Accept ヘッダーで指定されていない場合、デフォルト値の 1.0 に設定されます。

イベントで複数の Accept ヘッダーが指定されていて、優先度の最も高い Accept ヘッダーが同数である場合、サーバーが Accept ヘッダーを選択します。このシナリオでは、クライアントがサーバーの Accept ヘッダーの選択に依存しないようにする必要があります。

サポートされている SOP クラス

Cloud Healthcare API では、すべての DICOM SOP クラスの取り込みと基本的な取得を行うことができます。イメージ形式間のコード変換が必要な取得については、サポートされている転送構文一覧のコード変換でサポートされている転送構文をご覧ください。

DICOM 辞書のバージョン

Cloud Healthcare API は、取り込まれたインスタンスのタグを解析するために DICOM 2022d ディクショナリを使用します。

BigQuery へのエクスポートでは、Cloud Healthcare API は DICOM 2024c 辞書を使用して列名を生成します。

Bulkdata タグの定義（プレビュー）

プレビュー メソッドでメタデータを取得する場合、Cloud Healthcare API はバルクデータとして定義されている特定のタグを除外します。代わりに、これらのタグは BulkDataURI とともにメタデータとともに返されるため、ユーザーはこれらのタグの内容を取得できます（RetrieveBulkdata をご覧ください）。Cloud Healthcare API で使用される定義は次のとおりです。

  • すべてのピクセルデータタグ: （7FE0,0008）、（7FE0,0009）、（7FE0,0010）。
  • VR が OB、OW、UN の任意のタグ。
  • OD、OF、OL の VR が 2 KiB を超えるタグ。
    • 従来の理由により、すでに Cloud Healthcare API に取り込まれているインスタンスのタグは、256 B（OF および OL）または 512 B（OD）より大きい場合、バルクデータと見なされる可能性があります。
  • VR が AT、FD、FL、UL、US のタグで、値の多重度（VM）が 512 より大きいタグ。
    • 従来の理由により、Cloud Healthcare API にすでに取り込まれているインスタンスのタグは、VM が 64 を超える場合にバルクデータと見なされる場合があります。

また、次のタグはバルクデータと見なされますが、メタデータ メソッドから返されたときに BulkDataURI を持たず、RetrieveBulkdata を使用してコンテンツを取得できません。

  • VR が SQ で、サイズが約 1 MiB を超えるタグ。