Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Guida introduttiva all'SDK e AWS CLI ## Installa e configura Per le istruzioni di installazione e configurazione, consulta [ Installare il AWS CLI](https://docs.aws.amazon.com/healthlake/latest/devguide/getting-started-setting-up.html#setting-up-install-cli). ## Fase 1: Creare un profilo di trasformazione ### Inizia da AWS Profilo iniziale (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"}}' ``` ### Inizia da dati di esempio (solo CSV) Crea profilo: ``` 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"}}' ``` Esegui l'agente AI per creare la mappatura YAML iniziale. Avvia una nuova conversazione con l'agente per ottenere un nuovo ID di conversazione. Richiama nuovamente l'API, questa volta ConversationId passando il valore della risposta precedente e la tua richiesta effettiva. Per un profilo CSV, è qui che l'agente analizza i file di esempio forniti al momento della creazione e genera la mappatura 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"}' ``` Continua la conversazione con lo stesso metodo ConversationId per perfezionare la mappatura su più turni (ad esempio, «Associa la colonna RACE\_CD a un'estensione FHIR»). Se l'agente ti chiede di confermare una modifica, rispondi con «Tipo»: «confirmation\_response». ### Inizia dalla mappatura locale ``` 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)..."}}}' ``` ### Clona da un profilo esistente ``` aws healthlake create-data-transformation-profile \ --region us-east-1 \ --source-format CCDA \ --profile-name test-profile-clone \ --source '{"ExistingVersionedProfileId": {"ProfileId": "e41af4b891d6f9211b42b90435cf0cea", "Version": 0}}' ``` Risposta: ``` { "ProfileId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "Version": 0, "SourceFormat": "CCDA", "TargetFormat": "FHIR_R4", "ProfileName": "My CCDA Profile", "LastUpdatedAt": "2026-07-01T12:00:00Z" } ``` Il profilo viene creato in stato di bozza (versione 0). ## Passaggio 2: Personalizza il profilo con l'agente AI (opzionale) Avvia una nuova conversazione con l'agente per ottenere un nuovo ID di conversazione. Chiama nuovamente l'API, questa volta passando il 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"}' ``` Risposta: ``` { "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" } ``` Continua la conversazione con il conversationID restituito: ``` 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" ``` ## Passaggio 3: test con la conversione di sincronizzazione (opzionale) L'endpoint di conversione di sincronizzazione è REST-only. Verifica un profilo rispetto a un documento di esempio prima della pubblicazione: ``` 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 }' ``` Risposta: ``` { "TransformedData": "{\"resourceType\":\"Bundle\",\"type\":\"collection\",\"entry\":[...]}", "DriftReport": "{\"coverageRate\":0.95,\"unmappedElements\":[...]}" } ``` + TransformedData: le risorse FHIR convertite come stringa JSON-encoded FHIR Bundle. + DriftReport: presente solo quando DriftDetectionEnabled è vero. Un rapporto di JSON-encoded deriva che mostra il tasso di copertura e gli elementi sorgente non mappati. **Nota** ProvenanceEnabled il valore predefinito è true. Le risorse di provenienza vengono generate a meno che non si imposti esplicitamente "ProvenanceEnabled«: false nella richiesta. Per un profilo CSV, trasmetti il tuo input come mappa dei nomi delle tabelle al contenuto CSV. Ogni chiave CsvInput deve corrispondere a un TableName nella configurazione di mappatura del tuo profilo: ``` 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" } } }' ``` Per inviare più di una tabella in una singola richiesta, aggiungi le voci 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,..." } } } ``` Risposta: ``` { "TransformedData": "{\"resourceType\":\"Bundle\",\"type\":\"transaction\",\"entry\":[...]}" } ``` Tieni presente quanto segue quando converti un input CSV: + Ogni chiave CsvInput deve corrispondere esattamente a un TableName nella configurazione di mappatura del tuo profilo. La corrispondenza distingue tra maiuscole e minuscole. + Passa il contenuto CSV per ogni tabella come una singola stringa. Separa le righe con`\n`. + DriftDetectionEnabled non è supportato per l'input CSV. Omettilo o impostalo su false. Se lo imposti su true, la richiesta ha esito negativo con un ValidationException. ## Fase 4: Pubblica il profilo ``` 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 pubblicazione crea una versione immutabile (v1). La bozza rimane modificabile e i lavori in blocco utilizzano automaticamente l'ultima versione pubblicata. ## Fase 5: Convertire i dati in FHIR Data Transformation Agent offre 3 modi per convertire i dati di origine in FHIR R4. ### 1. Conversione di sincronizzazione Per un C-CDA profilo: ``` 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 }' ``` Per un profilo 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. Esegui un processo di trasformazione in blocco su 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 ``` Monitora il lavoro: ``` # 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. Esegui un processo di trasformazione in blocco e inseriscilo in un HealthLake datastore Per convertire i file sorgente e caricare le risorse FHIR risultanti direttamente in un HealthLake datastore in un solo passaggio, utilizza l' StartFHIRImportJob API esistente con i campi del profilo di trasformazione: ``` 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)" ``` Questo avvia un processo in due fasi: prima il servizio converte i file sorgente utilizzando il profilo pubblicato, quindi inserisce le risorse FHIR risultanti nel datastore. I dati sono immediatamente interrogabili tramite l'API REST FHIR una volta completata l'immissione. Monitora il lavoro: ``` aws healthlake describe-fhir-import-job \ --region us-west-2 \ --datastore-id "your-datastore-id" \ --job-id "returned-job-id" ``` **Nota** Il datastore deve essere in stato ATTIVO. La provenienza è abilitata per impostazione predefinita. Il ruolo di accesso ai dati richiede lo stesso Amazon S3 e le stesse AWS KMS autorizzazioni dei processi autonomi.