将 FHIR 资源导出到 BigQuery

本页面介绍了如何将 FHIR 资源导出到 BigQuery 进行探索和分析。

设置 BigQuery 权限

在将 FHIR 资源导出到 BigQuery 之前，您必须向 Cloud Healthcare Service Agent 服务帐号授予其他权限。如需了解详情，请参阅FHIR 存储区 BigQuery 权限。

导出 FHIR 资源

以下示例展示了如何将 FHIR 资源导出到 BigQuery 表。

设置 BigQuery 目标时，请使用完全限定的 URI，如下所示：

bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID

导出操作的行为可能会因以下方面而有所不同：

  • 目标表是否已存在
  • 您是否已设置 force 字段
  • 您是否已设置 writeDisposition 枚举的值。如果使用 writeDisposition 枚举，请勿设置 force 字段。

上述每种情况下的行为如下：

  • 如果目标表已存在，并且 force 设置为 true，则导出操作会覆盖现有表。
  • 如果目标表已存在，并且 force 设置为 false，则会发生错误。
  • 如果目标表尚不存在，则无论您是否指定 force 字段，导出操作都会创建一个新表。
  • 使用 writeDisposition 时，如果目标表已存在且为空，则导出操作会成功完成，而不是返回错误。

控制台

如需将 FHIR 资源导出到 BigQuery，请完成以下步骤：

  1. 在 Cloud Console 中，转到数据集页面。
    转到“数据集”页面
  2. 点击要从中导出 FHIR 资源的 FHIR 存储区的数据集。
  3. 在数据存储区列表中，从 FHIR 存储区的操作列表中选择导出。
  4. 在显示的导出 FHIR 资源页面上，选择 BigQuery 表。
  5. 在 BigQuery 输出选项中，选择数据导出到 BigQuery 的方式。
  6. 在 BigQuery 输出选项中，点击浏览以选择 BigQuery 项目和数据集。
  7. 在选择数据集中，搜索要将 FHIR 资源导出到的 BigQuery 项目和数据集。
  8. 如需在输出架构中设置所有递归结构的深度，请点击递归结构深度滑块中的相关深度级别。默认情况下，递归值为 2。

    如需了解详情，请参阅 projects.locations.datasets.fhirStores.SchemaConfig。
  9. 点击导出，将 FHIR 资源导出到 BigQuery。
  10. 要跟踪操作的状态，请点击操作标签页。操作完成后，系统会显示以下指示：
    • 长时间运行的操作状态部分下方的确定标题下会显示一个绿色的对勾标记。
    • 概览部分在操作 ID 的同一行中显示一个绿色对勾标记和一个确定指示符。
    如果您遇到任何错误，请点击操作，然后点击在 Cloud Logging 中查看详细信息。

gcloud

如需将 FHIR 资源导出到 BigQuery，请使用 gcloud healthcare fhir-stores export bq 命令。请指定以下信息：

  • 父数据集的名称
  • FHIR 存储区的名称
  • 现有 BigQuery 数据集的名称
  • 拥有 BigQuery 数据集的项目的名称
  • 将 schema-type 设置为 analytics
  • --writeDisposition 标志可使用以下值之一：
    • write-empty：仅在目标表为空时才导出数据。这是默认的。
    • write-truncate：在写入实例之前清空表中的所有现有数据。
    • write-append：将数据附加到现有表。

以下示例展示了 gcloud healthcare fhir-stores export bq 命令。

gcloud healthcare fhir-stores export bq FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --bq-dataset=bq://PROJECT_ID.BIGQUERY_DATASET_ID \
  --schema-type=analytics \
  --write-disposition={write-empty|write-truncate|write-append}

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

Request issued for: [FHIR_STORE_ID]
Waiting for operation [projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/OPERATION_ID] to complete...done.
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

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

gcloud healthcare operations describe OPERATION_ID \
  --dataset=DATASET_ID

响应包括 done: true。

done: true
metadata:
'@type': type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata
apiMethodName: google.cloud.healthcare.v1.fhir.FhirService.ExportResources
createTime: 'CREATE_TIME'
endTime: 'END_TIME'
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID
response:
'@type': type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ExportResourcesResponse
fhirStore: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

API

如需了解详情，请参阅 projects.locations.datasets.fhirStores.export。

curl

要导出 FHIR 资源，请发出 POST 请求并提供以下信息：

  • 父数据集的名称
  • FHIR 存储区的名称
  • 现有 BigQuery 数据集的名称
  • 拥有 BigQuery 数据集的项目的名称

  • 将 schemaType 字段设置为以下其中一项：

    • ANALYTICS：FHIR 分析架构
    • ANALYTICS_V2：支持重复扩展列和包含资源（JSON 字符串形式）的 FHIR 分析架构

  • 访问令牌

  • writeDisposition 枚举的以下某个值：

    • write-empty：仅在目标表为空时才导出数据。这是默认的。
    • write-truncate：在写入实例之前清空表中的所有现有数据。
    • write-append：将数据附加到现有表。

  • （仅适用于 v1beta1）：可选字段 _type，仅导出一种或多种 FHIR 资源类型

  • （仅适用于 v1beta1）：可选字段 _since，仅导出在特定时间之后更新的资源（定义为 YYYY-MM-DDThh:mm:ss.sss+zz:zz）

该操作会为 FHIR 存储区中的每种资源类型输出一个 BigQuery 表。

以下示例展示了使用 curl 的 POST 请求。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'bigqueryDestination': {
        'datasetUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID',
        'schemaConfig': {
          'schemaType': '{ANALYTICS|ANALYTICS_V2}'
        },
        'writeDisposition': '{write-empty|write-truncate|write-append}'
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:export"

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

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

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

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/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.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.ExportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ExportResourcesResponse",
  }
}

PowerShell

要导出 FHIR 资源，请发出 POST 请求并提供以下信息：

  • 父数据集的名称
  • FHIR 存储区的名称
  • 现有 BigQuery 数据集的名称
  • 拥有 BigQuery 数据集的项目的名称

  • 将 schemaType 字段设置为以下其中一项：

    • ANALYTICS：FHIR 分析架构
    • ANALYTICS_V2：支持重复扩展列和包含资源（JSON 字符串形式）的 FHIR 分析架构

  • 访问令牌

  • writeDisposition 枚举的以下某个值：

    • write-empty：仅在目标表为空时才导出数据。这是默认的。
    • write-truncate：在写入实例之前清空表中的所有现有数据。
    • write-append：将数据附加到现有表。

  • （仅适用于 v1beta1）：可选字段 _type，仅导出一种或多种 FHIR 资源类型

  • （仅适用于 v1beta1）：可选字段 _since，仅导出在特定时间之后更新的资源（定义为 YYYY-MM-DDThh:mm:ss.sss+zz:zz）

该操作会为 FHIR 存储区中的每种资源类型输出一个 BigQuery 表。

以下示例展示了使用 Windows PowerShell 的 POST 请求。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
    'bigqueryDestination': {
      'datasetUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID',
      'schemaConfig': {
        'schemaType': '{ANALYTICS|ANALYTICS_V2}'
      },
      'writeDisposition': '{write-empty|write-truncate|write-append}'
    }
  }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:export" | Select-Object -Expand Content

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

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

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

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

如果请求成功，服务器将以 JSON 格式返回包含操作状态的响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.ExportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ExportResourcesResponse",
  }
}

在 BigQuery 中查询和分析 FHIR 数据

将 FHIR 资源导出到 BigQuery 后，请参阅在 BigQuery 中分析 FHIR 数据解决方案，了解如何查询和分析导出的数据。该解决方案使用 FHIR 中由 Synthea™ 生成的合成数据 公共数据集，该数据集托管了在 Synthea™ 中使用 FHIR 格式生成的超过 100 万条合成患者记录。

对 FHIR 导出请求进行问题排查

如果在执行 FHIR 导出请求期间发生错误，则错误会记录到 Cloud Logging。如需了解详情，请参阅在 Cloud Logging 中查看错误日志。

如果整个操作返回错误，请参阅排查长时间运行的操作问题。

后续步骤