为去标识化的数据添加注释

本页面介绍了如何在对敏感 FHIRDICOM 数据进行去标识化时配置注释存储区和注释记录。

为去标识化的数据添加注释概览

每次对敏感 FHIR 或 DICOM 数据进行去标识化时,您都可以输出从注释存储区中移除的敏感数据相关信息。此信息作为一个或多个注释记录存储在注释存储区中。

您可以在现有数据集中创建注释存储区,也可以在去标识化操作期间创建的新数据集中创建注释存储区。如果您在现有数据集中创建注释存储区,则该数据集中不得存在同名的注释存储区。

创建的注释存储区必须与去标识化的源数据位于同一项目中。例如,您不能同时对一个项目中的数据进行去标识化,并将注释记录输出到其他项目中的注释存储区。

如果要指定注释存储区及其在去标识化期间的行为,请在 DeidentifyConfig 对象中的 annotation 对象内设置 annotation_store_name 字段。

您可以选择性地设置 store_quote 字段,具体取决于您的使用场景。有关设置 store_quote 字段的信息,请参阅下一部分

使用 store_quote 字段

以下信息同时适用于 FHIR 和 DICOM 数据。

如果请求中 annotation 内的 store_quote 字段设置为 true,则去标识化的数据的原始值会显示在 quote 字段的注释记录中部分。例如:

  • 如果对 DATE 进行去标识化,并且 store_quote 设置为 true,则注释记录中会显示以下信息:

    • quote 字段中显示的日期值(例如 1980-12-05
    • DATE infoType
    • 数据所在的起始位置和结束位置。起始位置和结束位置都使用从零开始(包含零)的索引。
  • 如果 store_quote 设置为 false,则日期 (1980-12-05) 不会显示在注释记录中,只会显示以下信息:

    • DATE infoType
    • 数据所在的起始位置和结束位置。起始位置和结束位置都使用从零开始(包含零)的索引。

去标识化的 FHIR 数据的注释

本部分以使用 Cloud Healthcare API 对 FHIR 数据进行去标识化中介绍的概念为基础。

注释记录结构

去标识化操作会为每个去标识化的 FHIR 资源创建一个注释记录。每个注释记录包含一个 textAnnotation 对象,用于存储经过检查和转换后的去标识化数据的相关信息。要使去标识化的字段显示在注释记录中,必须应用 INSPECT_AND_TRANSFORM Action

为去标识化的 FHIR 数据配置注释

以下示例使用默认 FHIR 数据去标识化作为其起点。这些示例展示了如何使用 FHIR 默认方法对患者资源进行去标识化,以及将去标识化数据的信息存储在新注释存储区的注释记录中。在本示例中,store_quote 字段设置为 true,这意味着输出注释记录包含去标识化数据的原始值。

新注释存储区位于去标识化操作创建的数据集中,但您也可以在现有数据集中创建注释存储区。

curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'destinationDataset': 'projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID',
      'config': {
        'fhir': {},
        'annotation': {
          'annotation_store_name': 'projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID',
          'store_quote': 'true'
        }
      }
    }" "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID:deidentify"

如果请求成功,服务器将以 JSON 格式返回响应:

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID"
}

响应包含操作名称。您可以使用 Operation get 方法来跟踪操作的状态:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID"

如果请求成功,服务器将以 JSON 格式返回响应。去标识化过程完成后,响应会包含 "done": true

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.dataset.DatasetService.DeidentifyDataset",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.deidentify.DeidentifySummary",
    "successStoreCount": "1",
    "successResourceCount": "1"
  }
}

确认去标识化操作成功后,您可以列出数据集中的注释存储区,并看到该操作创建了注释存储区:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores"

如果请求成功,服务器将以 JSON 格式返回响应:

{
  "annotationStores": [
    {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID"
    },
    {
      ...
    }
  ]
}

使用 ANNOTATION_STORE_ID 值列出注释存储区中的注释记录:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations"

如果请求成功,服务器将以 JSON 格式返回响应:

{
  "annotations": [
    "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_RECORD_ID",
    ...
  ]
}

使用 ANNOTATION_RECORD_ID 值查看注释记录:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_RECORD_ID"

如果请求成功,服务器将以 JSON 格式返回响应。

textAnnotation 对象包含去标识化操作移除的敏感文本的相关信息。在 details 字段中,您可以看到该操作搜索了 patient.text.div 对象并找到了四个 infoType、infoType 的值以及这些值所在的位置。

使用默认 FHIR 进行去标识化时,只有经过检查和转换后的数据是 patient.text.div 对象中的数据;所有其他去标识化数据均已经过转换,但未进行检查,因为它已在原始 FHIR 资源中声明其 infoType。

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_RECORD_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID"
    }
  },
  "textAnnotation": {
    "details": {
      "patient.text.div": {
        "findings": [
          {
            "infoType": "PERSON_NAME",
            "start": "42",
            "end": "54",
            "quote": "Smith, Darcy"
          },
          {
            "infoType": "PERSON_NAME",
            "start": "42",
            "end": "47",
            "quote": "Smith"
          },
          {
            "infoType": "PERSON_NAME",
            "start": "49",
            "end": "54",
            "quote": "Darcy"
          },
          {
            "infoType": "DATE",
            "start": "81",
            "end": "91",
            "quote": "1980-12-05"
          }
        ]
      }
    }
  }
}

去标识化的 DICOM 数据的注释

本部分以使用 Cloud Healthcare API 对 DICOM 数据进行去标识化中介绍的概念为基础。

注释记录结构

去标识化操作会为去标识化的 DICOM 数据创建两种类型的注释记录。这两种类型的注释记录如下:

  • 文本注释记录:包含去标识化数据中的元数据,例如 DICOM 标记。每个文本注释记录包含一个 textAnnotation 对象,用于存储经过检查和转换后的去标识化数据的相关信息。要使去标识化的标记显示在注释记录中,必须根据 TagFilterProfile 字段中提供的配置检查其中的受保护健康信息 (PHI)。例如,为去标识化的 DICOM 数据配置注释中的示例使用 DEIDENTIFY_TAG_CONTENTS 配置。
  • 图片注释记录:包含各个 DICOM 帧中的敏感信息所在的位置。每条图片注释记录都包含一个 ImageAnnotation 对象,用于保存找到的敏感信息的坐标。

去标识化操作会为 DICOM 实例中的每个帧创建注释记录。例如,如果一个 DICOM 实例有三个帧,则去标识化操作会创建以下注释记录:

  • 一条文本注释记录(包含 textAnnotation),用于 DICOM 实例中的 DICOM 标记。
  • 三条图片注释记录(三个帧各含一条),每条记录包含一个 imageAnnotation。每条图片注释记录都包含一个 frame_index 字段,用于指明记录所对应的帧。

所有这些注释记录都具有相同的 cloudHealthcareSource.name 值,即采用格式 projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID 的 DICOM 实例路径。

为去标识化的 DICOM 数据配置注释

以下示例使用合并标记去标识化和烧屏文字遮盖功能作为起点。这些示例展示了如何对 DICOM 实例进行去标识化,以遮盖图片中的所有烧屏文字并检查和转换敏感文本。这些示例还展示了如何在新注释存储区的注释记录中存储去标识化的数据相关信息。在本示例中,store_quote 字段设置为 true,这意味着输出注释记录包含去标识化数据的原始值。

新注释存储区位于去标识化操作创建的数据集中,但您也可以在现有数据集中创建注释存储区。

curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'destinationDataset': 'projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID',
      'config': {
        'dicom': {
          'filterProfile': 'DEIDENTIFY_TAG_CONTENTS'
        },
        'image': {
          'textRedactionMode': 'REDACT_ALL_TEXT'
        },
        'annotation': {
          'annotation_store_name': 'projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID',
          'store_quote': 'true'
        }
      }
    }" "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID:deidentify"

如果请求成功,服务器将以 JSON 格式返回响应:

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID"
}

响应包含操作名称。您可以使用 Operation get 方法来跟踪操作的状态:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID"

如果请求成功,服务器将以 JSON 格式返回响应。去标识化过程完成后,响应会包含 "done": true

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.dataset.DatasetService.DeidentifyDataset",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.deidentify.DeidentifySummary",
    "successStoreCount": "1",
    "successResourceCount": "1"
  }
}

确认去标识化操作成功后,您可以列出数据集中的注释存储区,并看到该操作创建了新注释存储区:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores"

如果请求成功,服务器将以 JSON 格式返回响应:

{
  "annotationStores": [
    {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID"
    },
    {
      ...
    }
  ]
}

使用 ANNOTATION_STORE_ID 值列出注释存储区中的注释记录:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations"

如果请求成功,服务器将以 JSON 格式返回响应:

{
  "annotations": [
    "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/TEXT_ANNOTATION_RECORD_ID",
    "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/IMAGE_ANNOTATION_RECORD_ID",
    ...
  ]
}

您可以看到创建了两条注释记录:一条文本注释记录和一条图片注释记录。

首先,使用 TEXT_ANNOTATION_RECORD_ID 值查看文本注释记录:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/TEXT_ANNOTATION_RECORD_ID"

如果请求成功,服务器将以 JSON 格式返回响应。

textAnnotation 对象包含去标识化操作移除的敏感文本的相关信息。在 details 字段中,您可以看到该操作提供了 DICOM 标记列表。找到 DICOM 标记时,将在 findings 对象中提供其信息,该对象显示 infoType、infoType 的值以及这些值所在的位置。

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/TEXT_ANNOTATION_RECORD_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID"
    }
  },
  "textAnnotation": {
    "details": {
      "00080070": {},
      "00080090": {
        "findings": [
          {
            "infoType": "PERSON_NAME",
            "end": "8",
            "quote": "John Doe"
          }
        ]
      },
      "00081090": {},
      "00100010": {
        "findings": [
          {
            "infoType": "PERSON_NAME",
            "end": "11",
            "quote": "Ann Johnson"
          }
        ]
      },
      "00100020": {},
      "00100030": {
        "findings": [
          {
            "infoType": "DATE",
            "end": "8",
            "quote": "19880812"
          }
        ]
      },
      "00020013": {
        "findings": [
          {
            "infoType": "LOCATION",
            "end": "5",
            "quote": "OFFIS"
          }
        ]
      },
      "00080020": {
        "findings": [
          {
            "infoType": "DATE",
            "end": "8",
            "quote": "20110909"
          }
        ]
      }
    }
  }
}

接下来,使用 IMAGE_ANNOTATION_RECORD_ID 值查看图片注释记录:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/annotationStores/ANNOTATION_STORE_ID//annotations/IMAGE_ANNOTATION_RECORD_ID"

如果请求成功,服务器将以 JSON 格式返回响应。

imageAnnotation 对象中有多个 vertices,每一个都包含四个 X/Y 点,这些点绑定了去标识化操作检测到敏感图像数据和烧屏文字的位置。

{
  "name": "projects/PROJECT_ID/locations/REGION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/IMAGE_ANNOTATION_RECORD_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/REGION/datasets/SOURCE_DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID"
    }
  },
  "imageAnnotation": {
    "boundingPolys": [
      {
        "vertices": [
          {
            "x": 439,
            "y": 919
          },
          {
            "x": 495,
            "y": 919
          },
          {
            "x": 495,
            "y": 970
          },
          {
            "x": 439,
            "y": 970
          }
        ]
      },
      {
        "vertices": [
          {
            "x": 493,
            "y": 919
          },
          {
            "x": 610,
            "y": 919
          },
          {
            "x": 610,
            "y": 972
          },
          {
            "x": 493,
            "y": 972
          }
        ]
      },
      {
        "vertices": [
        ...
        ]
      },
      ...
    ]
  }
}