View a markdown version of this page

Cómo empezar con el SDK y AWS CLI - AWS HealthLake
Instalar y configurarPaso 1: Crear un perfil de transformaciónPaso 2: Personaliza el perfil con el agente de IA (opcional)Paso 3: Prueba con la conversión sincronizada (opcional)Paso 4: Publica el perfilPaso 5: Convierte los datos a FHIR

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Cómo empezar con el SDK y AWS CLI

Instalar y configurar

Para obtener instrucciones de instalación y configuración, consulte Instalar el AWS CLI.

Paso 1: Crear un perfil de transformación

Comience desde AWS Perfil de inicio (solo 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"}}'

Comience con datos de muestra (solo CSV)

Crear perfil:

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"}}'

Ejecute el agente de IA para crear el mapeo YAML inicial.

Inicie una nueva conversación con el agente para obtener un nuevo identificador de conversación. Vuelve a llamar a la API, esta vez pasando el ConversationId de la respuesta anterior y el de tu solicitud real. En el caso de un perfil CSV, aquí es donde el agente analiza los archivos de muestra que proporcionaste al crearlos y genera el mapeo de 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"}'

Continúa con la misma conversación ConversationId para afinar el mapeo en varios turnos (por ejemplo, «Asigne la columna RACE_CD a una extensión FHIR»). Si el agente le pide que confirme un cambio, responda con «Escriba»: «confirmation_response».

Comience desde el mapeo local

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)..."}}}'

Clonar a partir de un perfil existente

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

Respuesta:

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

El perfil se crea en estado borrador (versión 0).

Paso 2: Personaliza el perfil con el agente de IA (opcional)

Inicie una nueva conversación con el agente para obtener un nuevo identificador de conversación. Vuelva a llamar a la API, esta vez pasando el 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"}'

Respuesta:

{
    "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"
}

Continúa la conversación con el ID de conversación devuelto:

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"

Paso 3: Prueba con la conversión sincronizada (opcional)

El punto final de conversión de sincronización es REST-only. Pruebe un perfil con un documento de muestra antes de publicarlo:

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
  }'

Respuesta:

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

  • TransformedData: los recursos del FHIR convertidos como una cadena de paquete JSON-encoded del FHIR.

  • DriftReport: está presente solo cuando DriftDetectionEnabled es verdadera. Un informe de JSON-encoded desviación que muestra la tasa de cobertura y los elementos fuente no mapeados.

nota

ProvenanceEnabled el valor predeterminado es true. Los recursos de procedencia se generan a menos que se establezca explícitamente "ProvenanceEnabled«: false en la solicitud.

Paso 4: Publica el perfil

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

La publicación crea una versión inmutable (v1). El borrador sigue siendo editable y los trabajos masivos utilizan automáticamente la última versión publicada.

Paso 5: Convierte los datos a FHIR

El agente de transformación de datos ofrece tres formas de convertir sus datos de origen a FHIR R4.

1. Conversión sincronizada

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. Ejecute un trabajo de transformación masiva a 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

Supervise el trabajo:

# 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. Ejecute un trabajo de transformación masiva e introdúzcalo en un HealthLake almacén de datos

Para convertir los archivos fuente y cargar los recursos del FHIR resultantes directamente en un HealthLake almacén de datos en un solo paso, utilice la StartFHIRImportJob API existente con los campos del perfil de transformación:

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)"

Esto inicia un trabajo de dos fases: primero, el servicio convierte los archivos fuente utilizando el perfil publicado y, a continuación, ingiere los recursos del FHIR resultantes en el almacén de datos. Los datos se pueden consultar inmediatamente a través de la API REST del FHIR una vez finalizada la ingestión.

Supervise el trabajo:

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

El almacén de datos debe estar en estado ACTIVO. La procedencia está habilitada de forma predeterminada. La función de acceso a los datos necesita los mismos AWS KMS permisos y Amazon S3 que los trabajos independientes.