Importare i dati FHIR

È possibile usare l'operazione import per inserire i dati FHIR nel server FHIR® con velocità effettiva elevata.

Modalità dell'operazione di importazione

L'operazione import supporta due modalità: iniziale e incrementale. Ogni modalità ha caratteristiche e casi d'uso diversi.

Modalità iniziale

• Destinato al caricamento di risorse FHIR in un server FHIR vuoto.

• Blocca le operazioni di scrittura dell'API nel server FHIR.

Modalità incrementale

• Ottimizzato per il caricamento periodico dei dati nel server FHIR e non blocca le scritture tramite l'API.

• Consente di caricare i valori lastUpdated e versionId dai metadati delle risorse, se presenti nel JSON della risorsa.

• Consente di caricare le risorse in un ordine non sequenziale delle versioni. Nota per l'inserimento non sequenziale delle risorse

  • Se i file di importazione non hanno i valori di version campo e lastUpdated specificati, non esiste alcuna garanzia di importare tutte le risorse nel servizio FHIR.
  • Se i file di importazione hanno risorse con valori duplicati version e lastUpdated di campo, nel servizio FHIR viene inserita in modo casuale una sola risorsa.
  • Durante l'esecuzione parallela, se più risorse condividono lo stesso ID risorsa, solo una di queste risorse viene importata in modo casuale.

Nella tabella seguente viene illustrata la differenza tra le modalità di importazione.

Considerazioni sulle prestazioni

Per ottenere prestazioni ottimali con l'operazione import , considerare i fattori seguenti.

• Usare file di grandi dimensioni per l'importazione. Le dimensioni ottimali del file NDJSON per l'importazione sono >=50 MB (o >=20 K risorse, nessun limite massimo). Valutare la possibilità di combinare file più piccoli.

• Importare i file di risorse FHIR come singolo batch. Per ottenere prestazioni ottimali, importare tutti i file di risorse FHIR da inserire nel server FHIR in un'unica import operazione. L'importazione di tutti i file in un'unica operazione riduce il sovraccarico di creazione e gestione di più processi di importazione. In modo ottimale, le dimensioni totali dei file in una singola importazione devono essere di grandi dimensioni (>=100 GB o >=100M di risorse, senza limite massimo).

• Limitare il numero di processi di importazione paralleli. È possibile eseguire più import processi contemporaneamente, ma potrebbe influire sulla velocità effettiva complessiva dell'operazione import .

Eseguire l'operazione di importazione

Prerequisiti

• Per usare l'operazione import , è necessario il ruolo di importazione dati FHIR nel server FHIR.

• Configurare il server FHIR. I dati FHIR devono essere archiviati in file specifici delle risorse in formato FHIR NDJSON nell'archivio BLOB di Azure. Per altre informazioni, vedere Configurare le impostazioni di importazione.

• I dati devono trovarsi nello stesso tenant del servizio FHIR.

• Per ottenere un token di accesso, vedere Token di accesso

Effettua una chiamata

Effettuare una POST chiamata a <<FHIR service base URL>>/$import con l'intestazione e il corpo della richiesta seguenti.

Header di richiesta

Prefer:respond-async
Content-Type:application/fhir+json

Corpo

Le tabelle seguenti descrivono i parametri e gli input del corpo.

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "<Use "InitialLoad" for initial mode import / Use "IncrementalLoad" for incremental mode import>"
        }, 
        {
            "name": "allowNegativeVersions",
            "valueBoolean": true
        },
        {
            "name": "errorContainerName",
            "valueString": "import-error-logs"
        },
        {
            "name": "input",
            "part": [
                { 
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/filename.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "\"0x8D92A7342657F4F\""
                }
            ]
        }
    ]
}

Controllare lo stato dell'importazione

Dopo aver avviato un'operazione import, viene restituito un corpo della risposta vuoto con un link callback nell'intestazione Content-location della risposta, insieme a un codice di stato 202 Accepted. Archiviare il callback collegamento per controllare lo stato di importazione.

La registrazione dell'operazione import viene implementata come chiamata idempotente. Lo stesso payload di registrazione produce la stessa registrazione, che influisce sulla possibilità di rielaborare i file con lo stesso nome. Evitare di aggiornare i file direttamente. È invece consigliabile usare un nome di file diverso per i dati aggiornati. In alternativa, se un aggiornamento sul posto con lo stesso nome file è inevitabile, aggiungere ETag nel payload di registrazione.

Per controllare lo stato di importazione, fai la chiamata REST con il metodo GET al collegamento callback restituito nel passaggio precedente.

Interpretare la risposta usando questa tabella.

La tabella seguente descrive i campi importanti nel corpo della risposta:

{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": <null in case type parameter in not populated in request. If provided, resource name will be added>,
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/filename.ndjson"
        }
    ],
    "error": [
        { 
        "type": "OperationOutcome",
        "count": 51,
        "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson",
        "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson"
        }
    ]
}

Importare risorse eliminate temporaneamente

L'importazione in modalità incrementale supporta l'acquisizione di risorse eliminate temporaneamente. È necessario usare l'estensione per inserire risorse eliminate temporaneamente nel servizio FHIR.

Aggiungere l'estensione alla risorsa per informare il servizio FHIR che la risorsa è stata eliminata temporaneamente.

{"resourceType": "Patient", "id": "example10", "meta": { "lastUpdated": "2023-10-27T04:00:00.000Z", "versionId": 4, "extension": [ { "url": "http://azurehealthcareapis.com/data-extensions/deleted-state", "valueString": "soft-deleted" } ] } }

Al termine dell'operazione import, eseguire una ricerca dello storico sulla risorsa per convalidare le risorse eliminate in modo temporaneo. Se si conosce l'ID della risorsa eliminata, usare il modello di URL nell'esempio seguente.

<FHIR_URL>/<resource-type>/<resource-id>/_history

Se non si conosce l'ID della risorsa, eseguire una ricerca della cronologia sul tipo di risorsa.

<FHIR_URL>/<resource-type>/_history

Risolvere i problemi relativi all'operazione di importazione

Ecco i messaggi di errore che si verificano se l'operazione import non riesce, insieme alle azioni consigliate per risolvere i problemi.

200 OK, ma c'è un errore con l'URL nella risposta

L'operazione import ha esito positivo e restituisce 200 OK. Tuttavia, error.url è presente nel corpo della risposta. I file presenti nel error.url percorso contengono frammenti JSON simili all'esempio seguente.

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "details": {
                "text": "Given conditional reference '{0}' doesn't resolve to a resource."
            },
            "diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
        }
    ]
}

Causa: i file NDJSON contengono risorse con riferimenti condizionali che import non supportano.

Soluzione: Sostituire i riferimenti condizionali ai riferimenti normali nei file NDJSON.

400 Richiesta non valida

L'operazione import ha esito negativo e restituisce 400 Bad Request. Il corpo della risposta contiene contenuto di diagnostica

operazione di importazione non riuscita per motivi: nessun host di questo tipo è noto. (example.blob.core.windows.net:443) Soluzione: verificare che il collegamento all'archiviazione di Azure sia corretto. Controllare le impostazioni di rete e firewall per assicurarsi che il server FHIR possa accedere alla risorsa di archiviazione. Se il servizio si trova in una rete virtuale, assicurarsi che l'archiviazione si trova nella stessa rete virtuale o in una rete virtuale con peering con la rete virtuale del servizio FHIR.

Le risorse SearchParameter non possono essere elaborate dall'importazione Soluzione: l'operazione di importazione restituisce un errore HTTP 400 quando una risorsa del parametro di ricerca viene inserita tramite il processo di importazione. Questa modifica è progettata per impedire che i parametri di ricerca vengano inseriti in uno stato non valido durante l'inserimento con un'operazione di importazione.

403 Vietato

L'operazione import ha esito negativo e restituisce 403 Forbidden. Il corpo della risposta contiene contenuto di diagnostica.

operazione di importazione non riuscita per motivi: il server non è riuscito a autenticare la richiesta. Verificare che il formato dell'intestazione dell'autorizzazione, firma inclusa, sia corretto. Causa: il servizio FHIR usa un'identità gestita per l'autenticazione dell'archiviazione di origine. Questo errore indica un'assegnazione di ruolo mancante o errata. Soluzione: Assegnare al server FHIR il ruolo di Collaboratore ai dati dei BLOB di archiviazione. Per altre informazioni, vedere Assegnare ruoli di Azure.

500 Errore interno del server

L'operazione import ha esito negativo e restituisce 500 Internal Server Error. Il corpo della risposta contiene contenuto di diagnostica

Operazione di importazione non riuscita per motivi: il database '_____' ha raggiunto la quota di dimensioni. Partizionare o eliminare dati, eliminare indici o consultare la documentazione per le possibili soluzioni.

Causa: è stato raggiunto il limite di archiviazione del servizio FHIR.

Soluzione: ridurre le dimensioni dei dati o prendere in considerazione l'API di Azure per FHIR, con un limite di archiviazione superiore.

423 - Bloccato

Comportamento: L'operazione import ha esito negativo e restituisce 423 Locked. Il corpo della risposta include questo contenuto:

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Service is locked for initial import mode."
        }
    ]
}

Causa: Il servizio FHIR è configurato con la modalità di importazione iniziale che ha bloccato altre operazioni.

Soluzione: Disattivare la modalità di importazione iniziale del servizio FHIR oppure selezionare Modalità incrementale.

Limitazioni

• Il numero massimo di file consentiti per ogni import operazione è 10.000.
• Il numero di file inseriti nel server FHIR con lo stesso valore del campo lastUpdated fino a millisecondi non può superare i 10.000.
• L'operazione di importazione non è supportata per il tipo di risorsa SearchParameter.
• L'operazione di importazione non supporta riferimenti condizionali nelle risorse.

Passaggi successivi

Converti i tuoi dati in FHIR

Configurare le impostazioni di esportazione e configurare un account di archiviazione

Copiare dati in Azure Synapse Analytics