このページは Cloud Translation API によって翻訳されました。

DICOM のスタディ、シリーズ、インスタンスを更新してパッチを適用する

このページでは、Cloud Healthcare API の DICOM スタディ、シリーズ、インスタンスをインプレースで更新およびパッチ適用する方法について説明します。Cloud Healthcare API のストアに DICOM データを入力する方法については、DICOMweb 標準の使用をご覧ください。

DICOM インスタンスの更新

DICOM インスタンスは、.dcm ファイルの新しいバージョンをアップロードすることで置き換えることができます。storeInstances と同様に、マルチパートファイルを使用して複数のインスタンスを一度に更新することもできます（多くの場合、複数のインスタンスを含むスタディまたはシリーズを更新する場合に使用します）。更新後、元のインスタンスは完全に置き換えられます。

storeInstances とは異なり、完全なインスタンスの更新は JSON メタデータでは実行できません。JSON を使用した部分更新については、DICOM メタデータのパッチ適用をご覧ください。

インスタンスの更新は「upsert」として扱われます。インスタンスが存在する場合は、更新されます。インスタンスが存在しない場合は、インスタンスが作成され、ストアに挿入されます。

新しいインスタンスを挿入すると、指定されたメタデータから SOP_CLASS_UID、SOP_INSTANCE_UID、STUDY_INSTANCE_UID、SERIES_INSTANCE_UID の値が収集されます。UID は次の要件を満たす必要があります。

ピリオドで区切られた数値のみを含みます。
保護医療情報（PHI）が含まれていません。

次の例は、DICOM ストア内のインスタンスを更新する方法を示しています。詳細については、projects.locations.datasets.dicomStores.updateInstances をご覧ください。

curl

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID
LOCATION: データセットの場所
DATASET_ID: DICOM ストアの親データセット
DICOM_STORE_ID: DICOM ストアの ID
DICOM_INSTANCE_FILE: ローカルマシン上の DICOM インスタンスファイルへのパス。.dcm 接尾辞で終わります。

次のサンプルは、curl を使用した PUT リクエストを示しています。

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/dicom" \
    --data-binary @DICOM_INSTANCE_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

出力は次の XML レスポンスです。

レスポンス

<NativeDicomModel>
  <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
    <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID</Value>
  </DicomAttribute>
  <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence">
    <Item number="1">
      <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
        <Value number="1">SOP_CLASS_UID</Value>
      </DicomAttribute>
      <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID">
        <Value number="1">SOP_INSTANCE_UID</Value>
      </DicomAttribute>
      <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
        <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID</Value>
      </DicomAttribute>
    </Item>
  </DicomAttribute>
</NativeDicomModel>

複数のインスタンスを一度に更新する

次の例は、マルチパートメッセージを使用して、複数のインスタンスで構成される DICOM スタディまたはシリーズを更新する方法を示しています。

curl

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID
LOCATION: データセットの場所
DATASET_ID: DICOM ストアの親データセット
DICOM_STORE_ID: DICOM ストアの ID
MULTIPART_FILE: ローカルマシン上のマルチパートファイルのパス。このファイルには複数の DICOM インスタンスが含まれており、それぞれが境界で区切られています。
BOUNDARY: マルチパートファイル内の DICOM インスタンスを分離するために使用される境界

次のサンプルは、curl を使用した PUT リクエストを示しています。

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: multipart/related; type=application/dicom; boundary=BOUNDARY" \
    --data-binary @MULTIPART_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

出力は次の XML レスポンスです。

レスポンス

<NativeDicomModel>
  <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
    <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID</Value>
  </DicomAttribute>
  <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence">
    <Item number="1">
      <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
        <Value number="1">SOP_CLASS_UID</Value>
      </DicomAttribute>
      <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID">
        <Value number="1">SOP_INSTANCE_UID</Value>
      </DicomAttribute>
      <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
        <Value number="1">https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID</Value>
      </DicomAttribute>
    </Item>
  </DicomAttribute>
</NativeDicomModel>

DICOM メタデータのパッチ適用

DICOM タグは、スタディー、シリーズ、またはインスタンスレベルで、追加、削除、編集できます。各レベルの動作は、次のとおりです。

projects.locations.datasets.dicomStores.studies.updateMetadata を使用してスタディレベルのタグを編集すると、そのスタディのすべてのインスタンスに適用されます。長時間実行オペレーションが返されます
projects.locations.datasets.dicomStores.studies.series.updateMetadata を使用してシリーズレベルのタグを編集する場合、編集内容はそのシリーズのすべてのインスタンスに適用されます。長時間実行オペレーションが返されます。
projects.locations.datasets.dicomStores.studies.series.instances.updateMetadata を使用してインスタンスレベルのタグを編集すると、指定したインスタンスのみに適用されます。編集は同期的に行われ、編集されたインスタンスに関する JSON メタデータが返されます。

長時間実行オペレーションを返すパッチの場合、インスタンスへのパッチの適用に失敗すると、Cloud Logging に記録されます。失敗したインスタンスの数は、関連するログへのリンクとともに、オペレーションメタデータで返されます。

JSON Patch

タグ編集の構文は、JSON Patch 標準に準拠しています。add、replace、remove のオペレーションのみがサポートされています。タグは、公開キーワード（タグが公開されている場合）または 8 桁の 16 進数 ID を使用して指定できます。すべてのタグパスには / という接頭辞を付ける必要があります。タグを add または replace する場合は、タグ識別子とともに VR とタグの値を指定する必要があります。タグを remove する場合は、タグ ID のみ指定する必要があります。

シーケンス内のタグの編集とシーケンスの置換がサポートされています。パッチでサポートされていないものについては、パッチの制限事項をご覧ください。シーケンス内のタグを指定するには、シーケンスと子タグを項目インデックスとバックスラッシュで区切ります。以下に、タグ InstanceCreationDate を ReferencedInstanceSequence の 2 番目のアイテムに add する例を示します（シーケンスアイテムは 0 から始まるインデックスであることに注意してください）。

[
  {
    "op": "add",
    "path": "/ReferencedInstanceSequence/1/InstanceCreationDate",
    "value": {
      "vr": "DA",
      "Value": [ "20240501" ]
    }
  }
]

完全なシーケンスを追加する（または完全なシーケンスを置き換える）場合、JSON Patch エントリの value フィールドはシーケンスの DICOM JSON 表現である必要があります。次に、2 つの要素を含む OtherPatientIDs シーケンスをインスタンスに追加する例を示します。

[
  {
    "op": "add",
    "path": "/OtherPatientIDs",
    "value": {
      "vr": "SQ",
      "Value": [
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "54321" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital B" ]
          }
        },
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "24680" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital C" ]
          }
        }
      ]
    }
  }
]

単一インスタンスのパッチ適用

curl

単一のインスタンスの DICOM タグを編集するには、PATCH リクエストを送信して次の情報を指定します。

PROJECT_ID: Google Cloud プロジェクトの ID
LOCATION: データセットの場所
DATASET_ID: DICOM ストアの親データセット
DICOM_STORE_ID: DICOM ストアの ID
STUDY_UID: DICOM インスタンスのスタディ UID
SERIES_UID: DICOM インスタンスのシリーズ UID
INSTANCE_UID: DICOM インスタンスのインスタンス UID

次のサンプルは、curl を使用した PATCH リクエストを示しています。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID/metadata"

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "studyUID": "STUDY_UID",
  "seriesUID": "SERIES_UID",
  "instanceUID": "INSTANCE_UID",
  "createTimestamp": "CREATE_TIMESTAMP",
  "metadata": {
    // Full DICOM JSON metadata for the instance after edits applied
  }
}

スタディまたはシリーズのパッチ適用

curl

特定のスタディ内で全インスタンスの DICOM タグを編集するには、PATCH リクエストで、次の情報を指定します。

PROJECT_ID: Google Cloud プロジェクトの ID
LOCATION: データセットの場所
DATASET_ID: DICOM ストアの親データセット
DICOM_STORE_ID: DICOM ストアの ID
STUDY_UID: DICOM スタディのスタディ UID

次のサンプルは、curl を使用した PATCH リクエストを示しています。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/metadata"

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

レスポンスにはオペレーション ID が含まれています。オペレーションのステータスを追跡し、詳細を表示するには、オペレーションの get メソッドを使用します。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

リクエストが成功すると、サーバーはオペレーションのステータスを含む JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.dicom.DicomWebService.UpdateStudyMetadata",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "CLOUD_LOGGING_URL",
    "counter": {
      "success": "1" // Number of instances updated in the study
    }
  },
  "done": true,
  "response": {
    "@type": "..."
  }
}

制限事項

DICOM タグの編集時に、次の制限事項と追加の動作が適用されます。

次のタグは編集できません。
- SOPInstanceUID (0008,0018)
- SeriesInstanceUID (0020,000E)
- StudyInstanceUID (0020,000D)
- Modality (0008,0060)
- ModalitiesInStudy (0008,0061)
- SpecificCharacterSet (0008,0005)
- グループ番号が「0008」未満のタグ
- バルクデータと見なされるタグ（バルクデータの定義を参照）
- 上記の定義に加えて、VR が OD、OF、OL、OV、SV、UV のいずれかのタグは、長さに関係なく、patch（add または replace オペレーション）を使用して追加できません。
bulkdata と見なされるタグを含むシーケンスは編集できません
- つまり、元のシーケンスに含まれるタグのいずれかが bulkdata と見なされる場合、シーケンスタグに対する replace または remove オペレーションは失敗します。
- また、新しいシーケンスに含まれるタグのいずれかが bulkdata と見なされる場合、シーケンスタグに対する replace オペレーションまたは add オペレーションは失敗します。
存在しないタグを replace または remove しようとすると、Cloud Healthcare API でエラーが返され、編集は失敗します。
既存のタグを add しようとすると、編集操作は、置換操作を呼び出した場合と同じように動作します。置換オペレーションでは、タグの既存の値を、オペレーションで指定された新しい値に置き換えます。
シーケンスの追加、置換、削除は可能ですが（シーケンス内のアイテムのタグも編集可能）、シーケンス内の個々のアイテムの追加、置換、削除はできません。
- 実際には、タグパスの末尾がインデックスである編集はすべて拒否されます（例: /ReferencedSeriesSequence/0）。
- シーケンス内の個々のアイテムに変更を加える必要がある場合は、変更が適用されたコピーで親シーケンス全体を置き換えます。

DICOM のスタディ、シリーズ、インスタンスを更新してパッチを適用する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

DICOM インスタンスの更新

curl

レスポンス

複数のインスタンスを一度に更新する

curl

レスポンス

DICOM メタデータのパッチ適用

JSON Patch

単一インスタンスのパッチ適用

curl

スタディまたはシリーズのパッチ適用

curl

制限事項

DICOM のスタディ、シリーズ、インスタンスを更新してパッチを適用する