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á. # Introdução ao SDK e AWS CLI ## Instalar e configurar Para obter instruções de instalação e configuração, consulte [Instalar AWS CLI](https://docs.aws.amazon.com/healthlake/latest/devguide/getting-started-setting-up.html#setting-up-install-cli) o. ## Etapa 1: criar um perfil de transformação ### Comece 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 uma nova ID de conversa. Chame a API novamente, desta vez ConversationId transmitindo 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 de um 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 uma nova ID de conversa. Chame a API novamente, desta vez passando o 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 ID de conversa 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 sincronizada (opcional) O endpoint de conversão de sincronização é REST-only. Teste um perfil em relação a um documento de amostra antes de publicar: ``` 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 }' ``` Resposta: ``` { "TransformedData": "{\"resourceType\":\"Bundle\",\"type\":\"collection\",\"entry\":[...]}", "DriftReport": "{\"coverageRate\":0.95,\"unmappedElements\":[...]}" } ``` + TransformedData: os recursos FHIR convertidos como uma string de pacote JSON-encoded FHIR. + DriftReport: presente somente quando DriftDetectionEnabled é verdadeiro. Um relatório de JSON-encoded desvio mostrando a taxa de cobertura e os elementos de origem não mapeados. **nota** ProvenanceEnabled o padrão é verdadeiro. Os recursos de proveniência são gerados, a menos que você defina explicitamente "ProvenanceEnabled“: false na solicitação. ## 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 automaticamente a versão mais recente publicada. ## 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 ``` 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. 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 consuma em um armazenamento de dados 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, em seguida, ingere os recursos FHIR resultantes no armazenamento de dados. Os dados podem ser consultados imediatamente por meio da API REST 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 a dados precisa do Amazon S3 e das mesmas AWS KMS permissões dos trabalhos autônomos.