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 Starter Profile에서 시작(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를 가져옵니다. 이번에는 ConversationId를 전달하여 API를 다시 호출합니다.

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: JSON 인코딩 FHIR 번들 문자열로 변환된 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로 변환

데이터 변환 에이전트는 소스 데이터를 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)"

이렇게 하면 2단계 작업이 시작됩니다. 먼저 서비스가 게시된 프로파일을 사용하여 소스 파일을 변환한 다음 결과 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 상태여야 합니다. 증명은 기본적으로 활성화되어 있습니다. 데이터 액세스 역할에는 독립 실행형 작업과 동일한 Amazon S3 및 AWS KMS 권한이 필요합니다.