View a markdown version of this page

Começando com o SDK e AWS CLI - AWS HealthLake
Instalar e configurarEtapa 1: criar um perfil de transformaçãoEtapa 2: personalizar o perfil com o agente de IA (opcional)Etapa 3: teste com conversão de sincronização (opcional)Etapa 4: publicar o perfilEtapa 5: converter dados em FHIR

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Começando com o SDK e AWS CLI

Instalar e configurar

Para obter instruções de instalação e configuração, consulte Instalar AWS CLI o.

Etapa 1: criar um perfil de transformação

Começar a partir de AWS Perfil inicial (somente 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"}}'

Comece com dados de amostra (somente CSV)

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

Execute o agente de IA para criar o mapeamento YAML inicial.

Inicie uma nova conversa com o agente para obter um novo ID de conversa. Chame a API novamente, desta vez ConversationId passando a resposta anterior e sua solicitação real. Para um perfil CSV, é aqui que o agente analisa os arquivos de amostra que você forneceu na criação e gera o mapeamento 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"}'

Continue a conversa com o mesmo ConversationId para refinar o mapeamento em vários turnos (por exemplo, “Mapear a coluna RACE_CD para uma extensão FHIR”). Se o agente solicitar que você confirme uma alteração, responda com “Tipo”: “confirmation_response”.

Comece com o mapeamento 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 do 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}}'

Resposta:

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

O perfil é criado no estado de rascunho (versão 0).

Etapa 2: personalizar o perfil com o agente de IA (opcional)

Inicie uma nova conversa com o agente para obter um novo ID de conversa. Chame a API novamente, desta vez passando pelo 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"}'

Resposta:

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

Continue a conversa com o conversationID retornado:

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"

Etapa 3: teste com conversão de sincronização (opcional)

O endpoint de conversão de sincronização é REST-only. Teste um perfil em um documento de amostra antes de publicá-lo:

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

Resposta:

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

  • TransformedData: os recursos FHIR convertidos como uma string do pacote JSON-encoded FHIR.

  • DriftReport: presente somente quando DriftDetectionEnabled é verdadeiro. Um relatório de JSON-encoded desvio mostrando a taxa de cobertura e elementos de origem não mapeados.

nota

ProvenanceEnabled o padrão é true. Os recursos de proveniência são gerados, a menos que você defina explicitamente "ProvenanceEnabled“: false na solicitação.

Para um perfil CSV, transmita sua entrada como um mapa de nomes de tabelas para o conteúdo CSV. Cada chave CsvInput deve corresponder a um TableName na configuração de mapeamento do seu 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 mais de uma tabela em uma única solicitação, adicione 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,..."
    }
  }
}

Resposta:

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

Lembre-se do seguinte ao converter a entrada CSV:

  • Cada entrada de chave CsvInput deve corresponder exatamente a um TableName na configuração de mapeamento do seu perfil. A correspondência diferencia maiúsculas de minúsculas.

  • Passe o conteúdo CSV de cada tabela como uma única string. Separe as linhas com\n.

  • DriftDetectionEnabled não é compatível com entrada CSV. Omita-o ou defina-o como falso. Se você definir como verdadeiro, a solicitação falhará com ValidationException a.

Etapa 4: publicar o 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"

A publicação cria uma versão imutável (v1). Seu rascunho permanece editável e os trabalhos em massa usam a versão mais recente publicada automaticamente.

Etapa 5: converter dados em FHIR

O Data Transformation Agent oferece três maneiras de converter seus dados de origem em FHIR R4.

1. Conversão de sincronização

Para um 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 um 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. Execute um trabalho de transformação em massa para o 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

Monitore o trabalho:

# 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. Execute um trabalho de transformação em massa e faça a ingestão em um datastore HealthLake

Para converter arquivos de origem e carregar os recursos FHIR resultantes diretamente em um HealthLake armazenamento de dados em uma única etapa, use a StartFHIRImportJob API existente com os campos do perfil de transformação:

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

Isso inicia um trabalho em duas fases: primeiro, o serviço converte seus arquivos de origem usando o perfil publicado e depois ingere os recursos FHIR resultantes no armazenamento de dados. Os dados podem ser consultados imediatamente por meio da API REST do FHIR após a conclusão da ingestão.

Monitore o trabalho:

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

O armazenamento de dados deve estar no estado ATIVO. A proveniência é ativada por padrão. A função de acesso aos dados precisa do mesmo Amazon S3 e das mesmas AWS KMS permissões dos trabalhos autônomos.