使用自定义架构解析 HL7v2 消息

本页面介绍如何配置自定义架构以解析不符合 HL7v2 标准的 HL7v2 消息。

如果要将 HL7v2 消息转换为其他格式（例如 FHIR 或 OMOP），您必须先能够解析 HL7v2 消息并将其注入到 HL7v2 存储区中。使用本指南确保您可以成功解析和注入 HL7v2 消息。

概览

有时，您的 HL7v2 消息可能不符合 HL7v2 标准。例如，HL7v2 消息可能包含 HL7v2 标准中没有的片段，或者片段可能顺序错乱。尝试注入不符合标准的消息时，您可能会遇到错误。

如需注入不符合标准的 HL7v2 消息，您必须在创建或修改 HL7v2 存储区时修改 ParserConfig 对象。在 ParserConfig 中，您可以根据自定义类型和片段配置架构化解析，确定被拒绝的 HL7v2 消息的处理方式，等等。

在配置 ParserConfig 之前，请参阅以下部分以了解 HL7v2 消息、类型定义和组定义。

HL7v2 消息

本部分简要介绍了 HL7v2 消息的结构，这在配置自定义架构解析器时非常有用。

HL7v2 消息基于事件，描述了临床记录的状态转换和部分更新。每条 HL7v2 消息都有一个消息类型，用于定义消息的用途。消息类型使用三个字符的代码，并在消息的必需主片段标头 (MSH) 中指定。有数十种消息类型，包括：

  • ADT：用于传输患者的部分患者管理数据
  • ORU：用于传输观察结果
  • ORM：用于传输有关订单的信息

请查看 HL7v2 消息的结构，其中包含片段、字段、组成部分和子组成部分：

图 1.HL7v2 消息结构的示意图。

在图 1 中，HL7v2 消息的以下部分添加了标签：片段、片段标头、字段和组成部分。

默认情况下，HL7v2 消息使用以下字符来分隔信息。您可以在 MSH 片段中替换每条 HL7v2 消息的分隔符和终止符。

  • 片段终止符：\r

    如果您的 HL7v2 消息使用不同的片段分隔符，请参阅自定义片段终止符和自定义字段示例。

  • 字段分隔符：|

  • 组成部分分隔符：^

  • 子组成部分分隔符：&

  • 重复分隔符：~

  • 转义字符：\

类型定义和组定义

了解架构解析器涉及使用类型定义和组定义。

类型定义

术语“类型”包括以下内容：

  • HL7v2 片段类型，例如 MSH（消息片段标头）、DG1（诊断）和 PID（患者标识）

    如需查看所有 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。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 自定义数据类型的类型定义，它具有名为 1 且数据类型为 ST 的字段以及名为 2 且数据类型为 ST 重复的字段：

{
  "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 字段重复一次的 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. 类型定义的示意图。

在图 2 中，类型定义的以下部分添加了标签：片段、片段标头、字段、组成部分、子组成部分和重复。

组定义

组在片段级别进行定义，它告诉您每条 HL7v2 消息中可以出现的片段类型。

您可以在 GroupOrSegment 对象内的 groups 数组中指定组。

来看看 ADT_A01 HL7v2 消息的组结构的以下代码段：

  • members 数组中的第一个 segment 是 MSH（消息片段标头），因为每个 HL7v2 消息中都需要 MSH。

  • 名为 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 时原始 HL7v2 消息的内容。由于 Group 1 上的 maxOccurs 设置为 2，这是允许的。ZCD 片段的其余部分未知，并且也不知道类型定义。

MSH|^~\&|||||20100308000000||ADT^A01|23701|1|2.3||
ZCD|ZCD_CONTENT
ZCD|ZCD_CONTENT
图 3. 组定义的示意图。

在图 3 中，组定义的以下部分添加了标签：片段和片段标头。

在 HL7v2 存储区上配置自定义架构

以下部分介绍了自定义架构的组件以及如何在 HL7v2 存储区上配置架构。

HL7v2 存储区类型配置

了解 HL7v2 消息的类型定义后，您可以在 HL7v2 存储区上指定类型配置。如需指定配置，请添加 types 数组和 version 数组。

以下示例展示了如何在 HL7v2 存储区上指定类型定义中显示的类型的配置。

请注意，该配置使用 version 数组指定 mshField 和 value 字段。这些字段对应于 MSH 片段中的字段和组成部分。

您指定的 types 数组仅适用于 MSH 片段与 version 数组中 mshField 和 value 值相对应的消息。这样，您便可以将不同版本的 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 消息

如需注入 Base64 编码版本的 HL7v2 消息，请完成本部分。

在使用任何请求数据之前，请先进行以下替换：

  • 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": "*"
    }
  ]
}

后续步骤

详细了解如何使用自定义架构解析器示例配置自定义架构解析器。