このページでは、HL7v2 標準に準拠していない HL7v2 メッセージを解析するカスタム スキーマを構成する方法について説明します。
HL7v2 メッセージを FHIR や OMOP などの別の形式に変換する場合は、まず HL7v2 メッセージを解析して HL7v2 ストアに取り込むことができる必要があります。このガイドを使用して、HL7v2 メッセージを正常に解析して取り込むことができることを確認してください。
概要
HL7v2 メッセージが HL7v2 標準に準拠していない場合があります。たとえば、HL7v2 メッセージに HL7v2 標準にないセグメントが含まれていたり、セグメントの順序がずれていたりすることがあります。準拠していないメッセージを取り込もうとすると、エラーが発生することがあります。
準拠していない HL7v2 メッセージを取り込むには、HL7v2 ストアの作成時または編集時に ParserConfig オブジェクトを変更する必要があります。ParserConfig 内では、カスタムタイプとセグメントに基づいてスキーマ化された解析を構成し、拒否された HL7v2 メッセージの処理方法を決定できます。
ParserConfig を構成する前に、次のセクションを確認して、HL7v2 メッセージ、型の定義、グループの定義を理解してください。
HL7v2 メッセージ
このセクションでは、HL7v2 メッセージの構造の概要について説明します。これは、カスタム スキーマ パーサーを構成する際に役立ちます。
HL7v2 メッセージは、イベントベースで、状態遷移と臨床レコードへの部分的な更新が記述されます。各 HL7v2 メッセージには、メッセージの目的を定義するメッセージ タイプがあります。メッセージ タイプは 3 文字コードを使用し、メッセージの必須メイン セグメント ヘッダー（MSH）で指定されます。以下のように多くのメッセージ タイプがあります。
ADT: 患者の Patient Administration データの一部を送信するために使用されますORU: 観察結果を送信するために使用されますORM: 順序に関する情報を送信するために使用します
セグメント、フィールド、コンポーネント、サブコンポーネントで構成される HL7v2 メッセージの構造を確認します。
図 1 では、HL7v2 メッセージのセグメント、セグメント ヘッダー、フィールド、コンポーネントの各部分にラベルが付けられています。
デフォルトでは、HL7v2 メッセージでは次の文字を使用して情報が区切られます。MSH セグメント内で、メッセージごとに HL7v2 メッセージのデリミター、区切り文字、ターミネータをオーバーライドできます。
セグメント ターミネータ:
\rHL7v2 メッセージで別のセグメント ターミネータを使用する場合は、カスタム セグメント ターミネータとカスタム フィールドの例をご覧ください。
フィールド区切り文字:
|コンポーネントの区切り文字:
^サブコンポーネントの区切り文字:
&繰り返し区切り文字:
~エスケープ文字:
\
種類とグループの定義
スキーマ パーサーを理解するには、型定義とグループ定義を使用します。
種類の定義
「型」という用語には、次の内容が含まれます。
HL7v2 セグメント タイプ（
MSH（メッセージ セグメント ヘッダー）、DG1（診断）、PID（患者 ID）など）すべての HL7v2 セグメント タイプの一覧については、セグメントの定義をご覧ください。
HL7v2 データ型（
ST（文字列データ）、TS（タイムスタンプ）、SI（シーケンス ID）など）すべての HL7v2 デフォルト データ型の一覧については、データ型をご覧ください。
型は、Type オブジェクト内の name フィールドで指定します。
型は、セグメントとセグメントのフィールド、コンポーネント、サブコンポーネントで構成されるモジュール形式を使用します。Type オブジェクトの情報は、セグメントの解析や解釈の方法を示し、次のような質問に答えます。
- セグメントに含まれる項目
- フィールドのデータ型は何か。
次の例は、カスタム ZCD セグメントの型定義を示しています。
{
"type": {
"name": "ZCD", // Segment type
"fields": [
{
"name": "1",
"type": "ST", // Primitive string data type
"minOccurs": 1, // Must occur at least once
"maxOccurs": 1 // Not repeated, because it can only occur once
},
{
"name": "2",
"type": "A", // Custom data type
"minOccurs": 1 // Repeated, because maxOccurs is not defined
}
]
}
}
この例では、ZCD セグメントに 1 と 2 という 2 つのフィールドが含まれています。1 のデータ型は ST です。これは、プリミティブ文字列データ型です。2 のデータ型は A です。これはカスタムデータ型です。
A カスタムデータ型の次の型定義には、B という別のカスタムデータ型も含まれています。
{
"type": {
"name": "A", // Custom data type
"fields": [
{
"name": "1",
"type": "ST", // Primitive string data type
"minOccurs": 1, // Must occur at least once
"maxOccurs": 1 // Not repeated, because it can only occur once
},
{
"name": "2",
"type": "B", // Custom data type
"minOccurs": 1,
"maxOccurs": 1
}
]
}
}
次の例は、B カスタムデータ型の型定義を示しています。これには、データ型が ST の1 という名前のフィールドと、データ型が ST の 2 という名前のフィールドなどが含まれます。
{
"type": {
"name": "B", // Custom data type
"fields": [
{
"name": "1",
"type": "ST", // Primitive string data type
"minOccurs": 1, // Must occur at least once
"maxOccurs": 1 // Not repeated, because it can only occur once
},
{
"name": "2",
"type": "ST"
"minOccurs": 1,
"maxOccurs": 1
}
]
}
}
セグメントとデータ型に関する情報がわかると、元の HL7v2 メッセージの ZCD セグメントがどのような形になるか推測できます。次の例は、A フィールドが 1 回繰り返される HL7v2 メッセージを示しています。A フィールドで maxOccurs が設定されていないため、この操作が許可されます。
ZCD|ZCD_field_1|A_field_1^B_component_1&B_component_2_repetition_1~A_field_1^B_component_1&B_component_2_repetition_2
図 2 では、型定義のセグメント、セグメント ヘッダー、フィールド、コンポーネント、サブコンポーネント、繰り返しの各部分にラベルが付けられています。
グループの定義
グループはセグメント レベルで定義され、各 HL7v2 メッセージにどのようなタイプのセグメントが含まれるかという情報を示します。
グループは、GroupOrSegment オブジェクト内の groups 配列で指定します。
ADT_A01 HL7v2 メッセージのグループ構造のスニペットを次に示します。
members配列の最初のsegmentはMSH（メッセージ セグメント ヘッダー）です。MSHはすべての HL7v2 メッセージで必要となるためです。Group 1という名前のgroup。このグループは
2回までしか存在できず、カスタムZCDセグメントが含まれます。通常、
groupには論理的にグループ化され、ネストされた複数のセグメントとその他のグループが含まれますが、この例ではGroup 1に単一のセグメントZCDのみが含まれます。
{
"ADT_A01": {
"members": [
{
"segment": {
"type": "MSH"
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"maxOccurs": "2",
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
グループに関する情報を把握できれば、HL7v2 メッセージで ZCD が 2 回発生した場合に、元の HL7v2 メッセージがどのようなものになるかを予測できます。これは Group 1 の maxOccurs が 2 に設定されているために許可されます。
ZCD セグメントの残りの部分は、型定義を知らなければ不明です。
MSH|^~\&|||||20100308000000||ADT^A01|23701|1|2.3|| ZCD|ZCD_CONTENT ZCD|ZCD_CONTENT
図 3 では、グループ定義のセグメントとセグメント ヘッダーの各部分にラベルが付けられています。
HL7v2 ストアにカスタム スキーマを構成する
以降のセクションでは、カスタム スキーマのコンポーネントと、HL7v2 ストアにスキーマを構成する方法について説明します。
HL7v2 ストアの型構成
HL7v2 メッセージの型定義を理解したら、HL7v2 ストアで型の構成を指定できます。構成を指定するには、types の配列と version 配列を追加します。
次の例は、HL7v2 ストアの型定義に示されている型の構成を指定する方法を示しています。
この構成では、version 配列を使用して mshField フィールドと value フィールドを指定しています。これらのフィールドは、MSH セグメントのフィールドとコンポーネントに対応しています。
指定した types 配列は、version 配列の mshField と value の値に対応する MSH セグメントがあるメッセージにのみ適用されます。これにより、異なるバージョンの HL7v2 メッセージを同じ HL7v2 ストアに取り込むことができます。
{
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD", // Segment type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A", // Data type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B", // Data type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST"
}
]
}
]
}
]
}
HL7v2 ストアグループの構成
グループを使用すると、「メンバーシップ」レベルでネストされた構造を構成できます。グループは、セグメント レベルの members 配列で指定されます。セグメントの構造は予測可能であり、通常はフィールド、コンポーネント、サブコンポーネントが含まれますが、セグメント自体は HL7v2 メッセージのどのレベルでも可能です。
型構成と同様に、グループ構成では version フィルタを使用して、異なるバージョンの HL7v2 メッセージを同じ HL7v2 ストアに取り込むことができます。
次の例は、HL7v2 ストアのグループ定義に示されているグループの構成を指定する方法を示しています。
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"members": [
{
"segment": {
"type": "MSH"
}
},
{
"group": {
"name": "Group 1",
"maxOccurs": "2",
"members": [
"segment": {
"type": "ZCD"
}
]
}
}
]
}
}
}
HL7v2 ストアの構成を完了する
型構成とグループ構成を組み合わせると、HL7v2 ストアでの完全なカスタム スキーマ構成がどのようなものかを決定できます。また、カスタム スキーマが次のような HL7v2 メッセージと一致するかどうかを特定することもできます。
MSH|^~\&|||||20100101000000||ADT^A01^A01|23701|1|2.3||
ZCD|ZCD_field_1|A_field_1^B_component_1&B_component_2_repetition_1~A_field_1^B_component_1&B_component_2_repetition_2
次のセクションを開いて、HL7v2 ストアの完全なカスタム スキーマを確認してから、カスタム スキーマを使用する HL7v2 ストアの作成に進みます。
開く
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1,
"maxOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"maxOccurs": "2",
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD", // Segment type
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A"
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "A", // Data type
"fields": [
{
"name": "1",
"type": "ST"
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B"
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B", // Data type
"fields": [
{
"name": "1",
"type": "ST"
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST"
"minOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
カスタム スキーマを使用して HL7v2 ストアを作成する
完全なカスタム スキーマを使用する HL7v2 ストアを作成するには、このセクションを完了してください。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: Google Cloud プロジェクトの ID
- LOCATION: データセットの場所
- DATASET_ID: HL7v2 ストアの親データセット
- HL7V2_STORE_ID: HL7v2 ストア ID
リクエストの本文（JSON）:
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。
cat > request.json << 'EOF'
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
EOFその後、次のコマンドを実行して REST リクエストを送信します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores?hl7V2StoreId=HL7V2_STORE_ID"
PowerShell
リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。
@'
{
"parserConfig": {
"schema": {
"schemas": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"messageSchemaConfigs": {
"ADT_A01": {
"name": "ADT_A01",
"members": [
{
"segment": {
"type": "MSH",
"minOccurs": 1
}
},
{
"group": {
"name": "Group 1",
"minOccurs": 1,
"members": [
{
"segment": {
"type": "ZCD"
}
}
]
}
}
]
}
}
}
],
"types": [
{
"version": [
{
"mshField": "12",
"value": "2.3"
}
],
"type": [
{
"name": "ZCD",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "A",
"minOccurs": 1
}
]
},
{
"name": "A",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "B",
"minOccurs": 1,
"maxOccurs": 1
}
]
},
{
"name": "B",
"fields": [
{
"name": "1",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
},
{
"name": "2",
"type": "ST",
"minOccurs": 1,
"maxOccurs": 1
}
]
}
]
}
]
},
"version": "V3"
}
}
'@ | Out-File -FilePath request.json -Encoding utf8その後、次のコマンドを実行して REST リクエストを送信します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores?hl7V2StoreId=HL7V2_STORE_ID" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
カスタム スキーマを使用して HL7v2 メッセージを取り込み、解析する
HL7v2 メッセージの base64 エンコード バージョンを取り込むには、このセクションを完了します。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID
- LOCATION: 親データセットの場所
- DATASET_ID: HL7v2 ストアの親データセット
- HL7V2_STORE_ID: HL7v2 ストア ID
リクエストの本文（JSON）:
{
"message": {
"data": "TVNIfF5+XCZ8fHx8fDIwMTAwMTAxMDAwMDAwfHxBRFReQTAxXkEwMXwyMzcwMXwxfDIuM3x8DVpDRHxaQ0RfZmllbGRfMXxBX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMX5BX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMQ=="
}
}
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。
cat > request.json << 'EOF'
{
"message": {
"data": "TVNIfF5+XCZ8fHx8fDIwMTAwMTAxMDAwMDAwfHxBRFReQTAxXkEwMXwyMzcwMXwxfDIuM3x8DVpDRHxaQ0RfZmllbGRfMXxBX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMX5BX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMQ=="
}
}
EOFその後、次のコマンドを実行して REST リクエストを送信します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages:ingest"
PowerShell
リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。
@'
{
"message": {
"data": "TVNIfF5+XCZ8fHx8fDIwMTAwMTAxMDAwMDAwfHxBRFReQTAxXkEwMXwyMzcwMXwxfDIuM3x8DVpDRHxaQ0RfZmllbGRfMXxBX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMX5BX2ZpZWxkXzJeQl9jb21wb25lbnRfMSZCX2NvbXBvbmVudF8yX3JlcGV0aXRpb25fMQ=="
}
}
'@ | Out-File -FilePath request.json -Encoding utf8その後、次のコマンドを実行して REST リクエストを送信します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages:ingest" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
フィールド カーディナリティを特定する
HL7v2 ストア内の次のフィールドを設定することにより、HL7v2 メッセージのフィールドのカーディナリティを特定できます。
minOccurs: HL7v2 の受信メッセージで、グループ、セグメント、フィールド、コンポーネント、サブコンポーネントが最低限必要な回数または繰り返される回数を決定します。maxOccurs: HL7v2 受信メッセージでグループ、セグメント、フィールド、コンポーネント、サブコンポーネントが最低限必要な回数または繰り返される回数を決定します。
不足している要素を無視する
不足している要素にかかわらず、HL7v2 API がすべての受信 HL7v2 メッセージを受け入れるようにするには、ignoreMinOccurs を true に設定します。つまり、必要なグループ、セグメント、フィールド、コンポーネント、サブコンポーネントが不足していても、メッセージは拒否されません。
メッセージに必須項目がないため、HL7v2 メッセージを取り込むことができない場合は、ignoreMinOccurs を true に設定することをおすすめします。
ワイルドカード フィールド型
ワイルドカード文字 * は、フィールドに使用される特殊な型です。* を使用して、HL7v2 パーサーに、HL7v2 メッセージの構造に基づいてフィールドを解析する必要があることを示します。厳格なフィールド データ型を適用する必要がない場合は、フィールドの値の代わりに * を使用すると便利です。フィールド内のコンテンツが HL7v2 標準に従っている限り、Cloud Healthcare API は HL7v2 メッセージを解析できます。
たとえば、次の型定義について考えてみます。フィールド 2 は、フィールド データ型ではなくワイルドカード文字を使用します。この定義は、型定義の最初の定義に相当するもので、A 型と B 型を指定する必要はありません。
"type": {
"name": "ZCD"
"fields": [
{
"name": "1",
"type": "ST"
},
{
"name": "2",
"type": "*"
}
]
}
次のステップ
カスタム スキーマ パーサーの構成の詳細については、カスタム スキーマ パーサーの例をご覧ください。