View a markdown version of this page

Cómo empezar a usar el SDK y AWS CLI - AWS HealthLake
Instalar y configurarPaso 1: Crear un perfil de transformaciónPaso 2: Personalizar 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 a usar 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 inicial (solo en 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 en 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 un mapeo YAML inicial.

Inicia una nueva conversación con el agente para obtener un nuevo identificador de conversación. Vuelva a llamar a la API, esta vez ConversationId transfiriendo la respuesta anterior a la solicitud actual. En el caso de un perfil CSV, aquí es donde el agente analiza los archivos de muestra que proporcionaste al crearlos y genera la asignación 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úe la conversación con el mismo ConversationId para refinar el mapeo en varios turnos (por ejemplo, «Asigne la columna RACE_CD a una extensión FHIR»). Si el agente te pide que confirmes un cambio, responde con la palabra «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 de borrador (versión 0).

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

Inicie una nueva conversación con el agente para obtener un nuevo ID 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úe la conversación con el identificador 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 la conversión sincronizada 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 verdadero. Un informe sobre JSON-encoded la evolución que muestra la tasa de cobertura y los elementos fuente no mapeados.

nota

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

En el caso de un perfil CSV, pasa los datos introducidos como un mapa de nombres de tablas al contenido CSV. Cada clave CsvInput debe coincidir con un nombre de tabla en la configuración de mapeo de tu perfil:

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": {
      "CsvInput": {
        "patients": "PAT_ID,MRN,LAST_NM,FIRST_NM,SEX,DOB,ZIP\nP001,MRN-001,Smith,John,M,1985-03-15,98101\nP002,MRN-002,Garcia,Maria,F,1990-07-22,90210"
      }
    }
  }'

Para enviar más de una tabla en una sola solicitud, agrega entradas a: CsvInput

{
  "ProfileId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "InputData": {
    "CsvInput": {
      "patients": "PAT_ID,MRN,LAST_NM,...\nP001,MRN-001,Smith,...",
      "encounters": "ENC_ID,PAT_ID,ENC_DATE,...\nE001,P001,2024-01-15,..."
    }
  }
}

Respuesta:

{
    "TransformedData": "{\"resourceType\":\"Bundle\",\"type\":\"transaction\",\"entry\":[...]}"
}

Cuando conviertas entradas en CSV, ten en cuenta lo siguiente:

  • Cada clave CsvInput debe coincidir exactamente con un nombre de tabla en la configuración de mapas de tu perfil. La coincidencia distingue entre mayúsculas y minúsculas.

  • Pase el contenido CSV de cada tabla como una sola cadena. Separe las filas con\n.

  • DriftDetectionEnabled no es compatible con la entrada en formato CSV. Omítelo o configúralo en falso. Si lo estableces como verdadero, la solicitud fallará con un ValidationException.

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 los datos de origen a FHIR R4.

1. Sincronizar la conversión

Para un C-CDA perfil:

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

Para un perfil CSV:

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": {
      "CsvInput": {
        "patients": "PAT_ID,MRN,LAST_NM,FIRST_NM,SEX,DOB,ZIP\nP001,MRN-001,Smith,John,M,1985-03-15,98101"
      }
    }
  }'

2. Ejecute un trabajo de transformación masiva en 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 de origen 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: en primer lugar, el servicio convierte los archivos fuente mediante el perfil publicado y, a continuación, introduce 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 ingesta.

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 permisos de Amazon S3 que los trabajos independientes.