View a markdown version of this page

開發套件和 入門 AWS CLI - AWS HealthLake
安裝及設定步驟 1：建立轉換設定檔步驟 2：使用 AI 代理器自訂設定檔 （選用）步驟 3：使用同步轉換進行測試 （選用）步驟 4：發佈設定檔步驟 5：將資料轉換為 FHIR

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

開發套件和 入門 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 延伸模組」)。如果客服人員要求您確認變更，請回應 "Type"： "confirmation_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。在發佈之前，針對範例文件測試設定檔：

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 資源做為 JSON 編碼的 FHIR 套件字串。

  • DriftReport：只有在 DriftDetectionEnabled 為 true 時才會顯示。顯示涵蓋率和未映射來源元素的 JSON 編碼偏離報告。

注意

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

Data Transformation Agent 提供 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"
注意

資料存放區必須處於 ACTIVE 狀態。Provenance 預設為啟用。資料存取角色需要與獨立任務相同的 Amazon S3 和 AWS KMS 許可。