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

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

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

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

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

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

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

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

使用 `storeQuote` 字段

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

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

如果对 DATE 进行去标识化，并且 storeQuote 设置为 true，则注解记录中会显示以下信息：
- quote 字段中显示的日期值（例如 1980-12-05）
- DATE infoType
- 数据所在的起始位置和结束位置。起始位置和结束位置都使用从零开始（包含零）的索引。
如果 storeQuote 设置为 false，则日期 (1980-12-05) 不会显示在注解记录中，只会显示以下信息：
- DATE infoType
- 数据所在的起始位置和结束位置。起始位置和结束位置都使用从零开始（包含零）的索引。

去标识化的 FHIR 数据的注释

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

注释记录结构

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

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

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

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

curl

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

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

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

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

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/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 application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores"

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

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

使用 ANNOTATION_STORE_ID 值列出注解存储区中的注解记录：

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

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

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

使用 ANNOTATION_RECORD_ID 值查看注解记录：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/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/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/ANNOTATION_RECORD_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/LOCATION/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"
          }
        ]
      }
    }
  }
}

gcloud

以下示例使用 gcloud beta healthcare datasets deidentify 命令。storeQuote 字段默认设置为 true，并且在使用 Google Cloud CLI 时无法更改。

gcloud beta healthcare datasets deidentify SOURCE_DATASET_ID \
    --destination-dataset=projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID \
    --default-fhir-config \
    --annotation-store=projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID

命令行会显示操作 ID，操作完成后，done：

Request issued for: [SOURCE_DATASET_ID]
Waiting for operation [projects/PROJECT_ID/locations/LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID] to complete...done.

要查看操作的更多详情，请运行 gcloud beta healthcare operations describe 命令，并提供响应中的 OPERATION_ID：

gcloud beta healthcare operations describe --dataset=SOURCE_DATASET_ID \
    OPERATION_ID

响应包括 done: true：

done: true
metadata:
  '@type': type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata
  apiMethodName: google.cloud.healthcare.v1beta1.dataset.DatasetService.DeidentifyDataset
  counter: {COUNTER}
  createTime: 'CREATE_TIME'
  endTime: 'END_TIME'
  logsUrl: CLOUD_LOGGING_URL
name: projects/PROJECT_ID/locations/LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID
response:
  '@type': type.googleapis.com/google.cloud.healthcare.v1beta1.deidentify.DeidentifySummary

运行以下命令以列出数据集中的注解存储区，并查看该操作创建了新的注解存储区：

gcloud beta healthcare annotation-stores list --dataset=DESTINATION_DATASET_ID

如果请求成功，则服务器将返回新的注解存储区：

ID                    LOCATION
ANNOTATION_STORE_ID                      LOCATION

无法使用 gcloud CLI 查看单条注解的详细信息。如需查看单条注解的详细信息，请按照 curl 示例中的说明操作。

去标识化的 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/LOCATION/datasets/SOURCE_DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID 的 DICOM 实例路径。

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

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

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

curl

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

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

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

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

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/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 application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores"

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

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

使用 ANNOTATION_STORE_ID 值列出注解存储区中的注解记录：

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

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

{
  "annotations": [
    "projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/TEXT_ANNOTATION_RECORD_ID",
    "projects/PROJECT_ID/locations/LOCATION/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 application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/TEXT_ANNOTATION_RECORD_ID"

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/TEXT_ANNOTATION_RECORD_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/LOCATION/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 application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID//annotations/IMAGE_ANNOTATION_RECORD_ID"

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID/annotations/IMAGE_ANNOTATION_RECORD_ID",
  "annotationSource": {
    "cloudHealthcareSource": {
      "name": "projects/PROJECT_ID/locations/LOCATION/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": [
        ...
        ]
      },
      ...
    ]
  }
}

gcloud

以下示例使用 gcloud beta healthcare datasets deidentify 命令。storeQuote 字段默认设置为 true，并且在使用 Google Cloud CLI 时无法更改。

gcloud beta healthcare datasets deidentify SOURCE_DATASET_ID \
    --destination-dataset=projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID \
    --text-redaction-mode=all \
    --annotation-store=projects/PROJECT_ID/locations/LOCATION/datasets/DESTINATION_DATASET_ID/annotationStores/ANNOTATION_STORE_ID

命令行会显示操作 ID，操作完成后，done：

Request issued for: [SOURCE_DATASET_ID]
Waiting for operation [projects/PROJECT_ID/locations/LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID] to complete...done.

要查看操作的更多详情，请运行 gcloud beta healthcare operations describe 命令，并提供响应中的 OPERATION_ID：

gcloud beta healthcare operations describe --dataset=SOURCE_DATASET_ID \
    OPERATION_ID

响应包括 done: true：

done: true
metadata:
  '@type': type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata
  apiMethodName: google.cloud.healthcare.v1beta1.dataset.DatasetService.DeidentifyDataset
  counter: {COUNTER}
  createTime: 'CREATE_TIME'
  endTime: 'END_TIME'
  logsUrl: CLOUD_LOGGING_URL
name: projects/PROJECT_ID/locations/LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID
response:
  '@type': type.googleapis.com/google.cloud.healthcare.v1beta1.deidentify.DeidentifySummary

运行以下命令以列出数据集中的注解存储区，并查看该操作创建了新的注解存储区：

gcloud beta healthcare annotation-stores list --dataset=DESTINATION_DATASET_ID

如果请求成功，则服务器将返回新的注解存储区：

ID                    LOCATION
ANNOTATION_STORE_ID                      LOCATION

无法使用 gcloud CLI 查看单条注解的详细信息。如需查看单条注解的详细信息，请按照 curl 示例中的说明操作。

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