Gestione dei criteri di controllo delle versioni e della cronologia

I criteri di controllo delle versioni nel servizio FHIR® Servizi per i dati sanitari di Azure determinano la modalità di archiviazione della cronologia per ogni tipo di risorsa, con l'opzione per la configurazione specifica della risorsa. Questo criterio è direttamente correlato alla gestione della cronologia per le risorse FHIR.

Cronologia in FHIR

La cronologia in FHIR consente di visualizzare tutte le versioni precedenti di una risorsa. È possibile eseguire query sulla cronologia in FHIR a livello di risorsa, a livello di tipo o a livello di sistema. La documentazione di HL7 FHIR contiene ulteriori dettagli sull'interazione su cronologia. La cronologia è utile quando si vuole visualizzare l'evoluzione di una risorsa in FHIR o se si desidera visualizzare le informazioni di una risorsa in un momento specifico.

Tutte le versioni precedenti di una risorsa sono considerate obsolete e la versione corrente di una risorsa deve essere usata per le normali operazioni del flusso di lavoro aziendale. Tuttavia, può essere utile vedere lo stato di una risorsa come punto nel tempo in cui è stata presa una decisione precedente.

Criteri di controllo delle versioni

I criteri di controllo delle versioni nel servizio FHIR consentono di decidere la modalità di archiviazione della cronologia, a livello di servizio FHIR o a un livello di risorsa specifico.

Esistono tre livelli diversi per i criteri di controllo delle versioni:

versioned: la cronologia viene archiviata per l'operazione sulle risorse. La versione della risorsa viene incrementata. Questa è l'opzione predefinita.
version-update: la cronologia viene archiviata per l'operazione sulle risorse. La versione della risorsa viene incrementata. Gli aggiornamenti richiedono un'intestazione valida If-Match . Per altre informazioni, vedere VersionedUpdateExample.http.
no-version: la cronologia non viene creata per le risorse. La versione della risorsa viene incrementata.

È possibile configurare i criteri di controllo delle versioni come impostazione a livello di sistema ed eseguirne anche l'override a livello di risorsa. L'impostazione a livello di sistema si applica a tutte le risorse nel servizio FHIR, a meno che non si aggiunga un criterio di controllo delle versioni a livello di risorsa specifico.

Confronto dei criteri di controllo delle versioni

Valore dei criteri	Comportamento della cronologia	`meta.versionId` Comportamento di aggiornamento	Impostazione predefinita
`versioned`	La cronologia viene archiviata	If-Match non obbligatorio	Yes
`version-update`	La cronologia viene archiviata	If-Match obbligatorio	NO
`no-version`	La cronologia non viene archiviata	If-Match non obbligatorio	NO

Annotazioni

La modifica dei criteri di controllo delle versioni in no-version non influisce sulla cronologia delle risorse esistente. Per rimuovere la cronologia per le risorse, usare l'operazione $purge cronologia .

Configurare i criteri di controllo delle versioni

Per configurare i criteri di controllo delle versioni, selezionare Configurazione dei criteri di controllo delle versioni nel servizio FHIR.

Dopo essere passati a Configurazione dei criteri di controllo delle versioni, è possibile configurare l'impostazione sia a livello di sistema sia a livello di risorsa (come eccezione rispetto al livello di sistema). La configurazione a livello di sistema (annotata come 1) si applica a ogni risorsa nel servizio FHIR, a meno che non si configuri un override specifico della risorsa (annotato come 2).

Quando si configura la configurazione a livello di risorsa, si seleziona il tipo di risorsa FHIR (annotato come 1) e i criteri di controllo delle versioni specifici per questa risorsa specifica (annotata come 2). Selezionare il pulsante Aggiungi (contrassegnato con il numero 3) per aggiungere questa impostazione alla coda di salvataggio.

Assicurarsi di selezionare Salva dopo aver completato la configurazione dei criteri di controllo delle versioni.

Gestione della cronologia

La cronologia FHIR consente agli utenti finali di vedere come una risorsa cambia nel tempo. È utile anche quando si usano i log di controllo per visualizzare lo stato di una risorsa prima e dopo che un utente lo modifica. In generale, conserva la cronologia di una risorsa, a meno che non si sappia che non è necessaria. Gli aggiornamenti frequenti delle risorse possono comportare una grande quantità di archiviazione dei dati, che può essere indesiderata nei servizi FHIR con una grande quantità di dati.

Quando si modificano i criteri di controllo delle versioni, a livello di sistema o a livello di risorsa, la cronologia esistente per le risorse nel servizio FHIR non viene rimossa. Per ridurre le dimensioni dei dati della cronologia nel servizio FHIR, usa l'operazione $purge-history.

Annotazioni

Aggiungere i parametri di query _summary=count e _count=0 all'endpoint _history per ottenere un conteggio di tutte le risorse con versioni. Questo conteggio include risorse eliminate temporaneamente.

Aggiornamenti e versionamento di soli metadati

Se si impostano i criteri di controllo delle versioni su versioned o version-update, gli aggiornamenti solo metadati (modifiche alle risorse FHIR che influiscono solo sui metadati) incrementano la versione della risorsa, creano una nuova versione e salvano la versione precedente come record cronologico. Se si apportano modifiche solo ai metadati tramite PUT, PATCH o $bulk-update, usare il parametro _meta-history di query per configurare se la versione precedente viene salvata come record cronologico.

_meta-history=true è impostato per impostazione predefinita. Per impostazione predefinita, la versione della risorsa viene incrementata, viene creata una nuova versione e la versione precedente viene salvata come record cronologico. Il lastUpdated timestamp viene aggiornato in modo da riflettere la modifica.
_meta-history=false può essere impostato su false. Questa impostazione incrementa la versione della risorsa e crea una nuova versione, ma non salva la versione precedente come record cronologico. Il lastUpdated timestamp viene aggiornato anche per riflettere la modifica. Questa configurazione consente di ridurre l'archiviazione dei dati quando si apportano aggiornamenti solo metadati.

Per eseguire gli esempi seguenti, è necessario:

un servizio FHIR con criteri di controllo delle versioni impostati su versioned o version-update
Autorizzazioni di lettura e scrittura dati FHIR

Esempio di `_meta-history=false` con PUT

Per illustrare l'uso del _meta-history parametro di query con PUT, seguire questo esempio:

Creare una risorsa:

PUT <fhir server>/Patient/test-patient
Authorization: Bearer <token>
Content-type: application/fhir+json

{
    "id": "test-patient",
    "resourceType": "Patient",
    "name": [
        {
            "family": "Doe",
            "given": [ "John" ]
        }
    ]
}

Creare una nuova versione della risorsa. Questa versione è 2.

PUT <fhir server>/Patient/test-patient
Authorization: Bearer <token>
Content-type: application/fhir+json

{
    "id": "test-patient",
    "resourceType": "Patient",
    "name": [
        {
            "family": "Doe",
            "given": [ "Jane" ]
        }
    ]
}

Eseguire: GET <fhir server>/Patient/test-patient/_history. Vengono restituite due versioni, versioni 1 e 2.
Usare PUT per eseguire un aggiornamento di metadati solo con il parametro di query _meta-history=false.
```
PUT <fhir server>/Patient/test-patient?_meta-history=false
Authorization: Bearer <token>
Content-type: application/fhir+json

{
    "id": "test-patient",
    "resourceType": "Patient",
    "meta": {
        "tag": [
            {
                "system": "test",
                "code": "test"
            }
        ]
    },
    "name": [
        {
            "family": "Doe",
            "given": [ "Jane" ]
        }
    ]
}
```
Questa operazione incrementa la versione della risorsa e crea la versione 3, ma non salva la versione precedente 2 come record cronologico. Per visualizzare il risultato, eseguire:

GET <fhir server>/Patient/test-patient/_history

La risposta include due versioni, 1 e 3. Il _meta-history=false parametro di query influisce solo sulle modifiche apportate solo ai metadati tramite PUT o PATCH. L'uso del parametro di query per apportare aggiornamenti dei metadati insieme ad altre modifiche al valore del campo non metadati incrementa la versione della risorsa e salva la versione precedente come record cronologico.

Esempio di `_meta-history=false` con PATCH o `$bulk-update`

Per illustrare l'uso del _meta-history parametro di query con PATCH o $bulk-update, seguire questo esempio:

Creare una risorsa:

PUT <fhir server>/Patient/test-patient
Authorization: Bearer <token>
Content-type: application/fhir+json

{
    "id": "test-patient",
    "resourceType": "Patient",
    "name": [
        {
            "family": "Doe",
            "given": [ "John" ]
        }
    ]
}

Creare una nuova versione della risorsa. Questa versione è 2.

PUT <fhir server>/Patient/test-patient
Authorization: Bearer <token>
Content-type: application/fhir+json

{
    "id": "test-patient",
    "resourceType": "Patient",
    "meta": {
        "tag": [
            {
                "system": "test",
                "code": "test"
            }
        ]
    },
    "name": [
        {
            "family": "Doe",
            "given": [ "Jane" ]
        }
    ]
}

Eseguire: GET <fhir server>/Patient/test-patient/_history. Vengono restituite due versioni, versioni 1 e 2.
Usa PATCH o $bulk-update per eseguire un aggiornamento solo ai metadati con il parametro di query _meta-history=false. L'esempio illustra l'uso di PATCH o $bulk-update per aggiornare solo il valore Patient.meta.tag.system. Per altre informazioni su PATCH, vedere PATCH e PATCH condizionale. Per ulteriori informazioni su $bulk-update, vedi Aggiornamento in blocco FHIR.

Uso di PATCH con la patch FHIRPath:
```
PATCH <fhir server>/Patient/test-patient?_meta-history=false
Authorization: Bearer <token>
Content-type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        { "name": "type",  "valueCode": "replace" },
        { "name": "path",  "valueString": "Patient.meta.tag[0].system" },
        { "name": "value", "valueUri": "test2" }
      ]
    }
  ]
}
```
Se si desidera aggiornare in blocco più risorse, usare $bulk-update. L'esempio seguente illustra come usare $bulk-update per aggiornare lo stesso campo di metadati per tutte le risorse paziente con _meta-history=false:
```
PATCH <fhir server>/Patient/$bulk-update?_meta-history=false
Authorization: Bearer <token>
Accept: application/fhir+json  
Content-type: application/fhir+json
Prefer: respond-async

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        { "name": "type",  "valueCode": "upsert" },
        { "name": "path",  "valueString": "Patient.meta.tag[0].system" },
        { "name": "value", "valueUri": "test2" }
      ]
    }
  ]
}
```
Uso di PATCH con patch JSON:
```
PATCH <fhir server>/Patient/test-patient?_meta-history=false
Authorization: Bearer <token>
Content-type: application/json-patch+json

[
  {
    "op": "replace",
    "path": "/meta/tag/0/system",
    "value": "test2"
  }
]
```
Questa operazione incrementa la versione della risorsa e crea la versione 3, ma la versione 2 precedente non viene salvata come record cronologico. Per visualizzare il risultato, eseguire:

GET <fhir server>/Patient/test-patient/_history

La risposta include due versioni, 1 e 3. Il _meta-history=false parametro di query influisce solo sulle modifiche apportate solo ai metadati tramite PUT o PATCH. L'uso del parametro di query per apportare aggiornamenti dei metadati insieme ad altre modifiche al valore del campo non metadati incrementa la versione della risorsa e salva la versione precedente come record cronologico.

Passaggi successivi

Operazione di rimozione definitiva cronologia

Annotazioni

FHIR® è un marchio registrato di HL7 e viene usato con l'autorizzazione di HL7.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-05-26

Gestione dei criteri di controllo delle versioni e della cronologia

Cronologia in FHIR

Criteri di controllo delle versioni

Confronto dei criteri di controllo delle versioni

Configurare i criteri di controllo delle versioni

Gestione della cronologia

Aggiornamenti e versionamento di soli metadati

Esempio di _meta-history=false con PUT

Esempio di _meta-history=false con PATCH o $bulk-update

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Esempio di `_meta-history=false` con PUT

Esempio di `_meta-history=false` con PATCH o `$bulk-update`