View a markdown version of this page

SDK 入门和 AWS CLI - AWS HealthLake
安装和配置步骤 1：创建转换配置文件步骤 2：使用 AI 代理自定义配置文件（可选）第 3 步：使用同步转换进行测试（可选）第 4 步：发布个人资料步骤 5：将数据转换为 FHIR

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

SDK 入门和 AWS CLI

安装和配置

有关安装和配置说明，请参阅安装 AWS CLI。

步骤 1：创建转换配置文件

从 AWS 初学者个人资料（仅限 CCDA）

aws healthlake create-data-transformation-profile \
  --region us-west-2 \
  --source-format CCDA \
  --profile-name "My CCDA Profile" \
  --source '{"StarterProfile": {"StarterProfileName": "ccda-starter-kit-v1"}}'

从示例数据开始（仅限 CSV）

创建个人资料：

aws healthlake create-data-transformation-profile \
  --region us-west-2 \
  --source-format CSV \
  --profile-name "Patient CSV Mapping" \
  --source '{"SampleData": {"S3Uri": "s3://my-bucket/samples/patient-data.csv"}}'

运行 AI 代理以创建初始 YAML 映射。

与代理发起新的对话以获取新的对话 ID。再次调用 API，这次是传递之前 ConversationId 的响应和您的实际请求。对于 CSV 配置文件，代理可以在此处分析您在创建时提供的示例文件并生成 YAML 映射：

aws healthlake update-profile-with-agent \
  --region us-west-2 \
  --profile-id "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  --source-format CSV \
  --conversation-id "00154593-c867-4e4c-b870-25fb5237e54f" \
  --input-message '{"Body": "Generate a profile to convert my CSVs into FHIR.", "Type": "normal"}'

继续使用相同的对话 ConversationId 来优化多个回合的映射（例如，“将 RACE_CD 列映射到 FHIR 扩展名”）。如果代理要求您确认更改，请回复 “类型”：“确认_response”。

从本地映射开始

aws healthlake create-data-transformation-profile \
  --region us-west-2 \
  --source-format CCDA \
  --profile-name "CI/CD Profile" \
  --source '{"ProfileMapping": {"ProfileMapping": {"Resources/Patient.vm": "#set($patient = $input)..."}}}'

从现有配置文件中克隆

aws healthlake create-data-transformation-profile \
  --region us-east-1 \
  --source-format CCDA \
  --profile-name test-profile-clone \
  --source '{"ExistingVersionedProfileId": {"ProfileId": "e41af4b891d6f9211b42b90435cf0cea", "Version": 0}}'

响应：

{
    "ProfileId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "Version": 0,
    "SourceFormat": "CCDA",
    "TargetFormat": "FHIR_R4",
    "ProfileName": "My CCDA Profile",
    "LastUpdatedAt": "2026-07-01T12:00:00Z"
}

配置文件在草稿状态（版本 0）下创建。

步骤 2：使用 AI 代理自定义配置文件（可选）

与代理发起新的对话以获取新的对话 ID。再次调用 API，这次是通过 ConversationId

aws healthlake update-profile-with-agent \
  --region us-west-2 \
  --profile-id "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  --source-format CCDA \
  --conversation-id "conv-a1b2c3d4-e5f6-7890" \
  --input-message '{"Body": "Add a mapping for Medication resources", "Type": "normal"}'

响应：

{
    "chatOutput": {
        "body": "I can help you add a Medication resource mapping. Which CCDA section should I map from?",
        "type": "options",
        "optionsList": ["Medications Section", "Discharge Medications", "Immunizations"]
    },
    "conversationId": "conv-a1b2c3d4-e5f6-7890"
}

使用返回的 conversationID 继续对话：

aws healthlake update-profile-with-agent \
  --region us-west-2 \
  --profile-id "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  --source-format CCDA \
  --input-message '{"body": "Medications Section", "type": "confirmation_response"}' \
  --conversation-id "conv-a1b2c3d4-e5f6-7890"

第 3 步：使用同步转换进行测试（可选）

同步转换端点是 REST-only。发布前，根据示例文档测试配置文件：

curl -X POST "https://datatransformation.healthlake.us-west-2.amazonaws.com/transform-data" \
  --aws-sigv4 "aws:amz:us-west-2:healthlake" \
  --user "${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}" \
  -H "x-amz-security-token: ${AWS_SESSION_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ProfileId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "InputData": {"CcdaInput": "<?xml version=\"1.0\"?><ClinicalDocument>...</ClinicalDocument>"},
    "DriftDetectionEnabled": true
  }'

响应：

{
    "TransformedData": "{\"resourceType\":\"Bundle\",\"type\":\"collection\",\"entry\":[...]}",
    "DriftReport": "{\"coverageRate\":0.95,\"unmappedElements\":[...]}"
}

  • TransformedData：转换后的 FHIR 资源为 FH JSON-encoded IR 捆绑包字符串。

  • DriftReport: 仅在 DriftDetectionEnabled 为真时出现。显示覆盖率和未映射源元素的 JSON-encoded 漂移报告。

注意

ProvenanceEnabled 默认为 true。除非您在请求中明确设置 ProvenanceEnabled “”: false，否则将生成来源资源。

第 4 步：发布个人资料

aws healthlake publish-data-transformation-profile \
  --region us-west-2 \
  --profile-id "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  --source-format CCDA \
  --change-description "Initial release - Patient, Observation, Medication mappings"

发布会创建不可变版本 (v1)。您的草稿仍可编辑，批量作业会自动使用最新发布的版本。

步骤 5：将数据转换为 FHIR

数据转换代理提供了 3 种将源数据转换为 FHIR R4 的方法。

1. 同步转换

curl -X POST "https://datatransformation.healthlake.us-west-2.amazonaws.com/transform-data" \
  --aws-sigv4 "aws:amz:us-west-2:healthlake" \
  --user "${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}" \
  -H "x-amz-security-token: ${AWS_SESSION_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ProfileId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "InputData": {"CcdaInput": "<?xml version=\"1.0\"?><ClinicalDocument>...</ClinicalDocument>"},
    "DriftDetectionEnabled": true
  }'

2. 运行到 Amazon S3 的批量转换任务

aws healthlake start-data-transformation-job \
  --region us-west-2 \
  --profile-id "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  --input-data-config '{"S3Uri": "s3://my-source-bucket/ccda-files/", "SourceFormat": "CCDA"}' \
  --output-data-config '{"S3Configuration": {"S3Uri": "s3://my-output-bucket/fhir-output/", "KmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/abcd1234"}}' \
  --data-access-role-arn "arn:aws:iam::123456789012:role/DTA-DataAccessRole" \
  --client-token "unique-token-$(date +%s)" \
  --job-name "cardiology-batch-july" \
  --drift-detection-enabled

监控作业：

# Check status
aws healthlake describe-data-transformation-job \
  --region us-west-2 \
  --job-id "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

# List recent completed jobs
aws healthlake list-data-transformation-jobs \
  --region us-west-2 \
  --job-status COMPLETED \
  --submitted-after "2026-07-01T00:00:00Z"

3. 运行批量转换作业并提取到数据存储中 HealthLake

要在单个步骤中转换源文件并将生成的 FHIR 资源直接加载到 HealthLake 数据存储中，请使用带有转换配置文件字段的现有 StartFHIRImportJob API：

aws healthlake start-fhir-import-job \
  --region us-west-2 \
  --datastore-id "your-datastore-id" \
  --input-data-config '{"S3Uri": "s3://my-source-bucket/ccda-files/"}' \
  --job-output-data-config '{"S3Configuration": {"S3Uri": "s3://my-output-bucket/import-output/", "KmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/abcd1234"}}' \
  --data-access-role-arn "arn:aws:iam::123456789012:role/DTA-DataAccessRole" \
  --profile-id "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  --input-format "CCDA" \
  --drift-detection-enabled \
  --job-name "cardiology-import-july" \
  --client-token "import-$(date +%s)"

这将启动一个分为两个阶段的工作：首先，该服务使用已发布的配置文件转换您的源文件，然后将生成的 FHIR 资源摄取到数据存储中。提取完成后，可以立即通过 FHIR REST API 查询数据。

监控作业：

aws healthlake describe-fhir-import-job \
  --region us-west-2 \
  --datastore-id "your-datastore-id" \
  --job-id "returned-job-id"
注意

数据存储必须处于活动状态。默认情况下，来源处于启用状态。数据访问角色需要与独立任务相同的 Amazon S3 和 AWS KMS 权限。