Esecuzione di un processo di reindicizzazione nell'API di Azure per FHIR

Articolo
10/04/2024

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.

Esistono scenari in cui potrebbero essere presenti parametri di ricerca o ordinamento nell'API di Azure per FHIR® che non sono ancora stati indicizzati. Questo scenario è rilevante quando si definiscono i propri parametri di ricerca. Finché il parametro di ricerca non viene indicizzato, non può essere usato nella ricerca. Questo articolo illustra come eseguire un processo di reindicizzazione per indicizzare i parametri di ricerca nel database del servizio FHIR.

Avviso

È importante leggere l'intero articolo prima di iniziare. Un processo reindicizzazione può richiedere prestazioni molto elevate. Questo articolo include opzioni per la limitazione e il controllo del processo di reindicizzazione.

Come eseguire un processo di reindicizzazione

Un processo di reindicizzazione può essere eseguito su un intero database del servizio FHIR e su parametri di ricerca personalizzati specifici.

Eseguire il processo di reindicizzazione nell'intero database del servizio FHIR

Per eseguire un processo di reindicizzazione, usare la chiamata seguente POST con la risorsa in Parameters formato JSON nel corpo della richiesta.

POST {{FHIR URL}}/$reindex 

{ 

“resourceType”: “Parameters”,  

“parameter”: [] 

}

Lasciare vuoto il "parameter": [] campo (come illustrato) se non è necessario modificare le risorse allocate al processo di reindicizzazione.

Se la richiesta ha esito positivo, viene visualizzato un codice di stato creato 201 oltre a una Parameters risorsa nella risposta, come nell'esempio seguente.

HTTP/1.1 201 Created 
Content-Location: https://{{FHIR URL}}/_operations/reindex/560c7c61-2c70-4c54-b86d-c53a9d29495e 

{
  "resourceType": "Parameters",
  "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
  "meta": {
    "versionId": "\"4c0049cd-0000-0100-0000-607dc5a90000\""
  },
  "parameter": [
    {
      "name": "id",
      "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
    },
    {
       "name": "lastModified",
       "valueDateTime": "2023-06-08T04:52:44.0974408+00:00"
    },
    {
       "name": "queuedTime",
       "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
    },
    {
       "name": "totalResourcesToReindex",
       "valueDecimal": 0.0
    },
    {
       "name": "resourcesSuccessfullyReindexed",
       "valueDecimal": 0.0
    },
    {
       "name": "progress",
       "valueDecimal": 0.0
    },
    {
       "name": "status",
       "valueString": "Queued"
    },
    {
       "name": "maximumConcurrency",
       "valueDecimal": 3.0
    },
    {
        "name": "queryDelayIntervalInMilliseconds",
        "valueDecimal": 500.0
    },
    {
        "name": "maximumNumberOfResourcesPerQuery",
        "valueDecimal": 100.0
    }
  ]
}

Eseguire il processo di reindicizzazione su un parametro di ricerca personalizzato specifico

Per eseguire un processo di reindicizzazione su un parametro di ricerca personalizzato specifico, usare la chiamata seguente POST con la risorsa in Parameters formato JSON nel corpo della richiesta.

POST {{FHIR_URL}}/$reindex 
content-type: application/fhir+json
{ 

"resourceType": "Parameters",  

"parameter": [
    {
      "name": "targetSearchParameterTypes",
      "valueString": "{url of custom search parameter. In case of multiple custom search parameters, url list can be comma seperated.}"
    }
] 

}

Nota

Per controllare lo stato di un processo di reindicizzazione o per annullare il processo, è necessario l'ID reindicizzazione. Si tratta dell'oggetto "id" "parameter" riportato nel valore restituito nella risposta. Nell'esempio precedente, l'ID per il processo reindicizzazione sarà 560c7c61-2c70-4c54-b86d-c53a9d29495e.

Come controllare lo stato di un processo di reindicizzazione

Dopo aver avviato un processo di reindicizzazione, è possibile controllare lo stato del processo usando la chiamata seguente.

GET {{FHIR URL}}/_operations/reindex/{{reindexJobId}

Di seguito è riportata una risposta di esempio.

{
    "resourceType": "Parameters",
    "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
    "meta": {
        "versionId": "138087"
    },
    "parameter": [
        {
            "name": "id",
            "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
        },
        {
            "name": "startTime",
            "valueDateTime": "2023-06-08T04:54:53.2943069+00:00"
        },
        {
            "name": "endTime",
            "valueDateTime": "2023-06-08T04:54:54.4052272+00:00"
        },
        {
            "name": "lastModified",
            "valueDateTime": "2023-06-08T04:54:54.4053002+00:00"
        },
        {
            "name": "queuedTime",
            "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
        },
        {
            "name": "totalResourcesToReindex",
            "valueDecimal": 2.0
        },
        {
            "name": "resourcesSuccessfullyReindexed",
            "valueDecimal": 2.0
        },
        {
            "name": "progress",
            "valueDecimal": 100.0
        },
        {
            "name": "status",
            "valueString": "Completed"
        },
        {
            "name": "maximumConcurrency",
            "valueDecimal": 3.0
        },
        {
            "name": "resources",
            "valueString": "{{LIST_OF_IMPACTED_RESOURCES}}"
        },
        {
            "name": "resourceReindexProgressByResource (CountReindexed of Count)",
            "valueString": "{{RESOURCE_TYPE:REINDEXED_COUNT OF TOTAL_COUNT}}"
        },
        {
            "name": "searchParams",
            "valueString": "{{LIST_OF_SEARCHPARAM_URLS}}h"
        },
        {
            "name": "queryDelayIntervalInMilliseconds",
            "valueDecimal": 500.0
        },
        {
            "name": "maximumNumberOfResourcesPerQuery",
            "valueDecimal": 100.0
        }
    ]
}

Nella risposta vengono visualizzate le informazioni seguenti.

totalResourcesToReindex: include il numero totale di risorse da reindicizzare in questo processo.
resourcesSuccessfullyReindexed: numero totale di risorse che sono già state reindicizzare in questo processo.
progress: percentuale di completamento del processo reindicizzazione. Calcolato come resourcesSuccessfullyReindexed/totalResourcesToReindex x 100.
status: indica se il processo di reindicizzazione viene accodato, in esecuzione, completato, non riuscito o annullato.
resources: elenca tutti i tipi di risorse interessati dal processo di reindicizzazione.
resourceReindexProgressByResource (CountReindexed of Count): fornisce un conteggio reindiczzato del conteggio totale, per tipo di risorsa. Nei casi in cui la reindicizzazione per un tipo di risorsa specifico viene accodata, viene fornito solo Count.
searchParams: elenca l'URL dei parametri di ricerca interessati dal processo di reindicizzazione.

Eliminare un processo reindicizzazione

Se è necessario annullare un processo di reindicizzazione, usare una chiamata di eliminazione e specificare l'ID processo reindicizzazione:

Delete {{FHIR URL}}/_operations/reindex/{{reindexJobId}

Considerazioni sulle prestazioni

Un processo reindicizzazione può richiedere prestazioni elevate. Sono stati implementati alcuni controlli di limitazione per gestire il modo in cui viene eseguito un processo di reindicizzazione nel database.

Nota

Non è raro che nei set di dati di grandi dimensioni venga eseguito un processo di reindicizzazione per giorni. Per un database con 30.000.000 risorse, si è notato che ci sono voluti 4-5 giorni a 100.000 unità richiesta (UR) per reindicizzare l'intero database.

Di seguito è riportata una tabella che delinea i parametri, le impostazioni predefinite e gli intervalli consigliati disponibili. È possibile usare questi parametri per velocizzare il processo (usare più calcolo) o rallentare il processo (usare meno calcolo). Ad esempio, è possibile eseguire il processo di reindicizzazione a un tempo di traffico ridotto e aumentare il calcolo per ottenere risultati più rapidi. È anche possibile usare le impostazioni per garantire un utilizzo ridotto delle risorse di calcolo e eseguirlo per giorni in background.

Parametro	Descrizione	Default	Intervallo disponibile
QueryDelayIntervalInMilliseconds	Ritardo tra ogni batch di risorse che viene avviata durante il processo di reindicizzazione. Un numero più piccolo accelera il processo mentre un numero più elevato lo rallenta.	500 MS (5 secondi)	50-500000
MaximumResourcesPerQuery	Numero massimo di risorse incluse nel batch di risorse da reindicizzare.	100	1-5000
MaximumConcurrency	Numero di batch eseguiti alla volta.	1	1-10
targetDataStoreUsagePercentage	Consente di specificare la percentuale di utilizzo dell'archivio dati per il processo di reindicizzazione. Ad esempio, è possibile specificare il 50% e garantire che al massimo il processo di reindicizzazione usi il 50% delle UR disponibili in Azure Cosmos DB.	Non presente, il che significa che è possibile usare fino al 100%.	0-100

Se si vuole usare uno dei parametri precedenti, è possibile passarli alla risorsa Parametri quando si avvia il processo di reindicizzazione.

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "maximumConcurrency",
      "valueInteger": "3"
    },
    {
      "name": "targetDataStoreUsagePercentage",
      "valueInteger": "20"
    },
    {
      "name": "queryDelayIntervalInMilliseconds",
      "valueInteger": "1000"
    },
    {
      "name": "maximumNumberOfResourcesPerQuery",
      "valueInteger": "1"
    }
  ]
}

Passaggi successivi

In questo articolo si è appreso come avviare un processo di reindicizzazione. Per informazioni su come definire nuovi parametri di ricerca che richiedono il processo di reindicizzazione, vedere

Definizione di parametri di ricerca personalizzati

Nota

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

Condividi tramite

Esecuzione di un processo di reindicizzazione nell'API di Azure per FHIR

Come eseguire un processo di reindicizzazione

Eseguire il processo di reindicizzazione nell'intero database del servizio FHIR

Eseguire il processo di reindicizzazione su un parametro di ricerca personalizzato specifico

Come controllare lo stato di un processo di reindicizzazione

Eliminare un processo reindicizzazione

Considerazioni sulle prestazioni

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive