本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開發套件和入門 AWS CLI ## 安裝及設定如需安裝和組態指示，請參閱[安裝 AWS CLI](https://docs.aws.amazon.com/healthlake/latest/devguide/getting-started-setting-up.html#setting-up-install-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": "..."}, "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": "..."}, "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 許可。