Convalidare le risorse FHIR rispetto ai profili in Servizi dati di integrità di Azure
Nell'articolo sui profili di archiviazione nel servizio FHIR sono state illustrati i concetti di base dei profili FHIR e li si archivia. Il servizio FHIR in Servizi dati di integrità di Azure (denominato servizio FHIR) consente di convalidare le risorse rispetto ai profili per verificare se le risorse sono conformi ai profili. Questo articolo illustra come usare $validate per convalidare le risorse rispetto ai profili.
$validate è un'operazione in Fast Healthcare Interoperability Resources (FHIR®) che consente di garantire che una risorsa FHIR sia conforme ai requisiti delle risorse di base o a un profilo specificato. Questa operazione garantisce che i dati nel servizio FHIR dispongano degli attributi e dei valori previsti. Per informazioni sull'operazione di convalida, vedere Specifica HL7 FHIR.
Per specifica, è possibile specificare mode con $validate, ad esempio creare e aggiornare:
create: l'API di Azure per FHIR verifica che il contenuto del profilo sia univoco dalle risorse esistenti e che sia accettabile creare come nuova risorsa.update: verifica che il profilo sia un aggiornamento rispetto alla risorsa esistente designata, ovvero non vengono apportate modifiche ai campi non modificabili.
Esistono diversi modi per convalidare la risorsa:
- Opzione 1: convalidare una risorsa esistente con l'operazione di convalida.
- Opzione 2: Convalidare una nuova risorsa con l'operazione di convalida.
- Opzione 3: Convalidare nella risorsa CREATE/UPDATE usando l'intestazione.
Al termine della convalida di una risorsa esistente/nuova con l'operazione di convalida, la risorsa non viene mantenuta nel servizio FHIR. Usare l'opzione 3: Convalidare nella risorsa CREATE/UPDATE usando l'intestazione per rendere persistente la risorsa convalidata correttamente nel servizio FHIR.
Il servizio FHIR restituirà sempre un oggetto OperationOutcome come risultati di convalida per $validate'operazione. Il servizio FHIR esegue la convalida in due passaggi, una volta passata una risorsa in $validate endpoint. Il primo passaggio è una convalida di base per garantire che la risorsa possa essere analizzata. Durante l'analisi delle risorse, è necessario correggere singoli errori prima di procedere al passaggio successivo. Dopo l'analisi della risorsa, la convalida completa viene eseguita come secondo passaggio.
Nota
Tutti i set di valori da usare per la convalida devono essere caricati nel server FHIR. Sono inclusi tutti i set di valori che fanno parte della specifica FHIR, nonché qualsiasi ValueSet definito in Guide all'implementazione. Sono supportati solo i set di valori completamente espansi che contengono un elenco completo di tutti i codici. Le definizioni valueset che fanno riferimento a origini esterne non sono supportate.
Opzione 1: Convalida di una risorsa esistente
Per convalidare una risorsa esistente, usare $validate in una GET richiesta:
GET http://<your FHIR service base URL>/{resource}/{resource ID}/$validate
Ad esempio:
GET https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/a6e11662-def8-4dde-9ebc-4429e68d130e/$validate
In questo esempio si convalida la risorsa Paziente esistente rispetto alla risorsa a6e11662-def8-4dde-9ebc-4429e68d130e Paziente di base. Se è valido, si otterrà un OperationOutcome esempio di codice simile all'esempio di codice seguente:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "All OK"
}
]
}
Se la risorsa non è valida, verrà visualizzato un codice di errore e un messaggio di errore con i dettagli sul motivo per cui la risorsa non è valida. Viene restituito un esempio OperationOutcome con messaggi di errore e può essere simile all'esempio di codice seguente:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"details": {
"coding": [
{
"system": "http://hl7.org/fhir/dotnet-api-operation-outcome",
"code": "1028"
}
],
"text": "Instance count for 'Patient.identifier.value' is 0, which is not within the specified cardinality of 1..1"
},
"location": [
"Patient.identifier[1]"
]
},
{
"severity": "error",
"code": "invalid",
"details": {
"coding": [
{
"system": "http://hl7.org/fhir/dotnet-api-operation-outcome",
"code": "1028"
}
],
"text": "Instance count for 'Patient.gender' is 0, which is not within the specified cardinality of 1..1"
},
"location": [
"Patient"
]
}
]
}
In questo esempio la risorsa non è conforme al profilo Patient fornito, che richiedeva un valore di identificatore del paziente e un sesso.
Se si vuole specificare un profilo come parametro, è possibile specificare l'URL canonico per il profilo da convalidare, ad esempio nell'esempio seguente per il profilo di base HL7 per heartrate:
GET https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Observation/12345678/$validate?profile=http://hl7.org/fhir/StructureDefinition/heartrate
Opzione 2: Convalida di una nuova risorsa
Se si vuole convalidare una nuova risorsa che si sta caricando nel server, è possibile eseguire una POST richiesta:
POST http://<your FHIR service base URL>/{Resource}/$validate
Ad esempio:
POST https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/$validate
Questa richiesta convaliderà prima la risorsa. La nuova risorsa specificata nella richiesta verrà creata dopo la convalida.
Il server restituirà sempre un oggetto OperationOutcome come risultato.
Opzione 3: Convalidare nella risorsa CREATE/UPDATE usando l'intestazione
È possibile scegliere quando si vuole convalidare la risorsa, ad esempio nella risorsa CREATE o UPDATE. Per impostazione predefinita, il servizio FHIR è configurato per rifiutare esplicitamente la convalida sulla risorsa Create/Update. Questa funzionalità consente di convalidare in Create/Update, usando l'intestazione x-ms-profile-validation . Impostare "x-ms-profile-validation" su true per la convalida.
Nota
Nel servizio FHIR open source è possibile modificare l'impostazione di configurazione del server, in CoreFeatures.
{
"FhirServer": {
"CoreFeatures": {
"ProfileValidationOnCreate": true,
"ProfileValidationOnUpdate": false
}
}
Per abilitare la convalida rigorosa, usare l'intestazione 'Prefer: handling' con valore strict. Impostando questa intestazione, l'avviso di convalida verrà segnalato come errore.
Passaggi successivi
In questo articolo si è appreso come convalidare le risorse rispetto ai profili usando $validate. Per informazioni sulle altre funzionalità supportate dal servizio FHIR, vedere
FHIR® è un marchio registrato di HL7 e viene usato con l'autorizzazione di HL7.