このページでは、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 プロジェクトの IDLOCATION: データセットの場所DATASET_ID: DICOM ストアの親データセットDICOM_STORE_ID: DICOM ストアの IDDICOM_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 レスポンスです。
複数のインスタンスを一度に更新する
次の例は、マルチパート メッセージを使用して、複数のインスタンスで構成される DICOM スタディまたはシリーズを更新する方法を示しています。
curl
リクエストのデータを使用する前に、次のように置き換えます。
PROJECT_ID: Google Cloud プロジェクトの IDLOCATION: データセットの場所DATASET_ID: DICOM ストアの親データセットDICOM_STORE_ID: DICOM ストアの IDMULTIPART_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 レスポンスです。
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 プロジェクトの IDLOCATION: データセットの場所DATASET_ID: DICOM ストアの親データセットDICOM_STORE_ID: DICOM ストアの IDSTUDY_UID: DICOM インスタンスのスタディ UIDSERIES_UID: DICOM インスタンスのシリーズ UIDINSTANCE_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 プロジェクトの IDLOCATION: データセットの場所DATASET_ID: DICOM ストアの親データセットDICOM_STORE_ID: DICOM ストアの IDSTUDY_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オペレーションは失敗します。
- つまり、元のシーケンスに含まれるタグのいずれかが bulkdata と見なされる場合、シーケンス タグに対する
- 存在しないタグを
replaceまたはremoveしようとすると、Cloud Healthcare API でエラーが返され、編集は失敗します。 - 既存のタグを
addしようとすると、編集操作は、置換操作を呼び出した場合と同じように動作します。置換オペレーションでは、タグの既存の値を、オペレーションで指定された新しい値に置き換えます。 - シーケンスの追加、置換、削除は可能ですが（シーケンス内のアイテムのタグも編集可能）、シーケンス内の個々のアイテムの追加、置換、削除はできません。
- 実際には、タグパスがインデックスで終わる編集はすべて拒否されます（例:
/ReferencedSeriesSequence/0）。 - シーケンス内の個々のアイテムに変更を加える必要がある場合は、変更が適用されたコピーで親シーケンス全体を置き換えます。
- 実際には、タグパスがインデックスで終わる編集はすべて拒否されます（例:
DICOM Studio を使用した更新
DICOM Studio を使用して、スタディ、シリーズ、インスタンスの DICOM メタデータを更新できます。
DICOM Studio を使用して DICOM メタデータを更新するには:
- 更新するスタディ、シリーズ、インスタンスを検索します。
- 検索結果でアイテムをクリックして、詳細ページに移動します。
- [メタデータ] タブをクリックします。
- 編集するタグのチェックボックスをオンにして、[編集] をクリックします。
- 編集パネルで、変更するタグを開きます。
- タグのキーワード、VR、値を編集します。
- [保存] をクリックします。
ユーザー インターフェースには引き続きすべての制限事項が適用されます。また、ユーザー インターフェースには次の制限があります。
- タグ編集インターフェースでは、値の多重度（VM）が 1 より大きいタグの編集はサポートされていません。
- タグ編集インターフェースでは、想定される VR または値の型に関するガイダンスや検証は提供されません。