Convalida operazione : Panoramica
Importante
L'API di Azure per FHIR verrà ritirata il 30 settembre 2026. Seguire le strategie di migrazione per passare al servizio FHIR® di Servizi per i dati sanitari di Azure entro tale data. A causa del ritiro dell'API di Azure per FHIR, le nuove distribuzioni non saranno consentite a partire dal 1° aprile 2025. Il servizio FHIR di Servizi per i dati sanitari di Azure è la versione evoluta dell'API di Azure per FHIR che consente ai clienti di gestire i servizi FHIR, DICOM e MedTech con integrazioni in altri servizi di Azure.
Nell'articolo Sui profili di archiviazione nell'API di Azure per FHIR sono stati descritti i concetti di base dei profili FHIR e li si archivia. Questo articolo illustra come usare $validate per convalidare le risorse rispetto ai profili. La convalida di una risorsa rispetto a un profilo significa verificare se la risorsa è conforme al profilo, incluse le specifiche elencate in Resource.meta.profile o in una Guida all'implementazione.
$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 nell'API di Azure per FHIR dispongano degli attributi e dei valori previsti. Per informazioni sull'operazione di convalida, vedere Specifica HL7 FHIR. Per specifica, la modalità può essere specificata con $validate, ad esempio creazione e aggiornamento:
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:
- Convalidare una risorsa esistente con l'operazione di convalida.
- Convalidare una nuova risorsa con l'operazione di convalida.
- Convalidare nella risorsa CREATE/UPDATE usando l'intestazione .
L'API di Azure per FHIR restituirà sempre come OperationOutcome risultati della convalida per $validate operazione. Il servizio API di Azure per FHIR esegue la convalida in due passaggi, una volta passata una risorsa all'endpoint $validate. Il primo passaggio è una convalida di base per assicurarsi che la risorsa possa essere analizzata. Durante l'analisi delle risorse, è necessario correggere singoli errori prima di procedere con il passaggio successivo. Una volta analizzata correttamente la 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 nelle 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.
Convalida di una risorsa esistente
Per convalidare una risorsa esistente, usare $validate in una GET richiesta:
GET http://<your Azure API for FHIR 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 sta convalidando 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 al 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. Un esempio OperationOutcome viene restituito 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 Paziente fornito, che richiede 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 l'esempio seguente per il profilo di base HL7 per heartrate:
GET https://myAzureAPIforFHIR.azurehealthcareapis.com/Observation/12345678/$validate?profile=http://hl7.org/fhir/StructureDefinition/heartrate
Convalida di una nuova risorsa
Se si vuole convalidare una nuova risorsa che si sta caricando nell'API di Azure per FHIR, è possibile eseguire una POST richiesta: il server restituirà sempre OperationOutcome come risultato.
POST http://<your Azure API for FHIR base URL>/{Resource}/$validate
Ad esempio:
POST https://myAzureAPIforFHIR.azurehealthcareapis.com/Patient/$validate
Questa richiesta convaliderà la risorsa. Nelle risorse di convalida non vengono create nel servizio FHIR, è necessario inviare una richiesta POST senza $validate per creare una risorsa.
Convalidare nella risorsa CREATE/UPDATE usando l'intestazione .
Per impostazione predefinita, l'API di Azure per FHIR è configurata per rifiutare esplicitamente la convalida nella 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
}
}
Passaggi successivi
In questo articolo si è appreso come convalidare le risorse rispetto ai profili usando $validate. Per altre informazioni sulle altre funzionalità supportate dell'API di Azure per FHIR, vedere
FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.