Operazione di importazione
L'operazione di importazione consente di caricare i dati FHIR® (Fast Healthcare Interoperability Resources) nel server FHIR con velocità effettiva elevata usando l'operazione di $import. L'importazione supporta sia il caricamento iniziale che incrementale dei dati nel server FHIR.
Uso dell'operazione di $import
Nota
Per usare $import, è necessario avere il ruolo di utilità di importazione dati FHIR nel server FHIR .
Per usare $import, è necessario configurare il server FHIR seguendo le istruzioni riportate nell'articolo Configurare le impostazioni di importazione . I dati FHIR da importare devono essere archiviati in file specifici delle risorse in formato FHIR NDJSON nell'archivio BLOB di Azure.
Per l'operazione di importazione, assicurarsi
- Tutte le risorse in un file devono essere dello stesso tipo. Potrebbero essere presenti più file per tipo di risorsa.
- I dati da importare devono trovarsi nello stesso tenant del servizio FHIR.
- Il numero massimo di file da importare per operazione è 10.000.
Nota:
- L'operazione di importazione non supporta i riferimenti condizionali nelle risorse.
- Durante l'operazione di importazione, se più risorse condividono lo stesso ID risorsa, solo una di queste risorse viene importata in modo casuale. Si è verificato un errore per le risorse che condividono lo stesso ID risorsa.
Chiamata a $import
Effettuare una POST chiamata a <<FHIR service base URL>>/$import con l'intestazione della richiesta e il corpo visualizzati:
Intestazione della richiesta
Prefer:respond-async
Content-Type:application/fhir+json
Corpo
| Nome parametro | Descrizione | Scheda. | Valori accettati |
|---|---|---|---|
| inputFormat | Stringa che rappresenta il nome del formato dell'origine dati. Attualmente sono supportati solo i file FHIR NDJSON. | 1..1 | application/fhir+ndjson |
| mode | Valore della modalità di importazione | 1..1 | Per il valore della modalità di utilizzo dell'importazione InitialLoad iniziale. Per il valore della modalità di importazione incrementale, usare IncrementalLoad il valore della modalità. Se non viene specificato alcun valore di modalità, il valore della modalità IncrementalLoad viene considerato per impostazione predefinita. |
| input | Dettagli dei file di input. | 1..* | Matrice JSON con tre parti descritte nella tabella seguente. |
| Nome parte di input | Descrizione | Scheda. | Valori accettati |
|---|---|---|---|
| tipo | Tipo di risorsa del file di input | 1..1 | Tipo di risorsa FHIR valido che corrisponde al file di input. |
| URL | URL di archiviazione di Azure del file di input | 1..1 | Valore URL del file di input che non può essere modificato. |
| etag | Etag del file di input nell'archiviazione di Azure usato per verificare che il contenuto del file non sia stato modificato. | 0..1 | Valore Etag del file di input che non può essere modificato. |
Corpo di esempio per l'importazione del carico iniziale:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "inputFormat",
"valueString": "application/fhir+ndjson"
},
{
"name": "mode",
"valueString": "InitialLoad"
},
{
"name": "input",
"part": [
{
"name": "type",
"valueString": "Patient"
},
{
"name": "url",
"valueUri": "https://example.blob.core.windows.net/resources/Patient.ndjson"
},
{
"name": "etag",
"valueUri": "0x8D92A7342657F4F"
}
]
},
{
"name": "input",
"part": [
{
"name": "type",
"valueString": "CarePlan"
},
{
"name": "url",
"valueUri": "https://example.blob.core.windows.net/resources/CarePlan.ndjson"
}
]
}
]
}
Controllo dello stato dell'importazione
Una volta avviata $import, viene restituito un corpo di risposta vuoto con un collegamento di callback nell'intestazione Content-location della risposta insieme 202-Accepted al codice di stato. Archiviare questo collegamento di callback per controllare lo stato di importazione.
Per controllare lo stato di importazione, effettuare la chiamata REST con il GET metodo al collegamento di callback restituito nel passaggio precedente.
È possibile interpretare la risposta usando la tabella seguente:
| Codice della risposta | Corpo della risposta | Descrizione |
|---|---|---|
| 202 - Accettato | L'operazione è ancora in esecuzione. | |
| 200 - OK | Il corpo della risposta non contiene alcuna voce error.url | Tutte le risorse sono state importate correttamente. |
| 200 - OK | Il corpo della risposta contiene una voce error.url | Errore durante l'importazione di alcune risorse. Per informazioni dettagliate, vedere i file che si trovano in error.url. Le altre risorse sono state importate correttamente. |
| Altro | Si è verificato un errore irreversibile e l'operazione è stata arrestata. Non è stato eseguito il rollback delle risorse importate correttamente. |
La tabella seguente fornisce alcuni dei campi importanti nel corpo della risposta:
| Campo | Descrizione |
|---|---|
| transactionTime | Ora di inizio dell'operazione di importazione bulk. |
| output.count | Numero di risorse importate correttamente |
| error.count | Numero di risorse che non sono state importate a causa di un errore |
| error.url | URL del file contenente i dettagli dell'errore. Ogni error.url è univoco per un URL di input. |
Risposta di esempio:
{
"transactionTime": "2021-07-16T06:46:52.3873388+00:00",
"request": "https://importperf.azurewebsites.net/$Import",
"output": [
{
"type": "Patient",
"count": 10000,
"inputUrl": "https://example.blob.core.windows.net/resources/Patient.ndjson"
},
{
"type": "CarePlan",
"count": 199949,
"inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.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"
}
]
}
Risoluzione dei problemi
Consente di eseguire la procedura dettagliata per alcuni codici di errore che possono verificarsi durante l'operazione di importazione.
200 OK, ma si è verificato un errore con l'URL nella risposta
Comportamento: L'operazione di importazione ha esito positivo e restituisce 200 OK. Tuttavia, error.url sono presenti 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}' does'nt 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, attualmente non supportati da $import.
Soluzione: Sostituire i riferimenti condizionali ai riferimenti normali nei file NDJSON.
400 - Richiesta non valida
Comportamento: L'operazione di importazione non è riuscita e 400 Bad Request viene restituita. Il corpo della risposta ha il contenuto seguente:
{
"resourceType": "OperationOutcome",
"id": "13876ec9-3170-4525-87ec-9e165052d70d",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: No such host is known. (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 sia in grado di 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.
403 - Accesso negato
Comportamento: L'operazione di importazione non è riuscita e 403 Forbidden viene restituita. Il corpo della risposta ha il contenuto seguente:
{
"resourceType": "OperationOutcome",
"id": "bd545acc-af5d-42d5-82c3-280459125033",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."
}
]
}
Causa: Viene usata l'identità gestita per l'autenticazione dell'archiviazione di origine. Questo errore può essere causato da un'assegnazione di ruolo mancante o errata.
Soluzione: Assegnare il ruolo Collaboratore ai dati dei BLOB di archiviazione al server FHIR seguendo la guida al controllo degli accessi in base al ruolo.
500 - Errore interno del server
Comportamento: L'operazione di importazione non è riuscita e 500 Internal Server Error viene restituita. Il corpo della risposta ha il contenuto seguente:
{
"resourceType": "OperationOutcome",
"id": "0d0f007d-9e8e-444e-89ed-7458377d7889",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: The database '****' has reached its size quota. Partition or delete data, drop indexes, or consult the documentation for possible resolutions."
}
]
}
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.
Passaggi successivi
In questo articolo si è appreso come l'operazione di importazione consente l'importazione di dati FHIR nel server FHIR con velocità effettiva elevata. Per altre informazioni sulla conversione dei dati in FHIR, sull'esportazione delle impostazioni per configurare un account di archiviazione e sullo spostamento dei dati in Azure Synapse, vedere
FHIR® è un marchio registrato di HL7 e viene usato con l'autorizzazione di HL7.