View a markdown version of this page

Guida introduttiva all'SDK e AWS CLI - AWS HealthLake
Installa e configuraFase 1: Creare un profilo di trasformazionePassaggio 2: Personalizza il profilo con l'agente AI (opzionale)Passaggio 3: Test con conversione sincronizzata (opzionale)Fase 4: Pubblicare il profiloFase 5: Convertire i dati in FHIR

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.

Fase 1: Creare un profilo di trasformazione

Inizia da AWS Starter Profile (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. Chiama nuovamente l'API, questa volta ConversationId passando la 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 ConversationId per rifinire 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 «Type»: «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. Richiama 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 conversione sincronizzata (opzionale)

L'endpoint di conversione della sincronizzazione è REST-only. Prova 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": "<?xml version=\"1.0\"?><ClinicalDocument>...</ClinicalDocument>"},
    "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 sulla 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.

Fase 4: Pubblicare 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

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. 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 datastore HealthLake

Per convertire i file sorgente e caricare le risorse FHIR risultanti direttamente in un HealthLake datastore in un unico passaggio, utilizza l'API esistente StartFHIRImportJob 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 di origine 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'ingestione.

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 lavori autonomi.