Best practice per le operazioni a lunga esecuzione

Questa pagina descrive le best practice per l'esecuzione e la gestione delle operazioni a lungo termine (LRO) nell'API Cloud Healthcare. Per una panoramica delle operazioni a lunga esecuzione nell'API Cloud Healthcare, consulta Gestione delle operazioni a lunga esecuzione.

Proprietà LRO

Le sezioni seguenti si applicano ai metodi elencati in Metodi che restituiscono un LRO.

Impatto sulle quote

Le richieste LRO non condividono la quota con i metodi CRUD (Create, Read, Update e Delete) dell'API Cloud Healthcare che consumano i seguenti tipi di quota:

La quota LRO viene calcolata utilizzando le metriche fhir_store_lro_ops e dicom_store_lro_ops.

L'API Cloud Healthcare limita il numero di LRO che possono essere eseguiti contemporaneamente in un progetto Google Cloud. Per ulteriori informazioni, consulta Limiti sul numero di LRO.

Velocità in Mbps

I metodi LRO in genere raggiungono una maggiore velocità in termini di dati rispetto ai metodi CRUD equivalenti. Ad esempio, l'importazione di istanze DICOM con dicomStores.import in genere supera l'archiviazione delle istanze singolarmente con dicomStores.storeInstances.

L'esecuzione di più LRO contemporaneamente potrebbe non aumentare il throughput dei dati a causa degli seguenti vincoli, in particolare durante l'elaborazione di grandi volumi di dati:

  • Limitazioni delle quote
  • Concorrenza delle risorse
  • Altro traffico inviato dal progetto Google Cloud all'API Cloud Healthcare durante l'esecuzione di un LRO

Per una velocità in uscita massima dei dati durante l'esecuzione di LRO, tieni conto di quanto segue:

  • I piccoli batch di importazione ed esportazione hanno in genere un throughput ridotto a causa del sovradimensionamento.
  • Le LRO vengono eseguite e consumano quota separatamente dalle altre operazioni dell'API Cloud Healthcare.
  • Ogni LRO ha una velocità effettiva massima.
  • LRO simultanee sulla stessa risorsa possono causare contese per i blocchi.
  • L'API Cloud Healthcare limita il numero di LRO che possono essere eseguiti contemporaneamente in un progetto Google Cloud. Per ulteriori informazioni, consulta Limiti sul numero di LRO.

Pianifica il numero di LRO richiesti dal tuo caso d'uso. Se devi suddividere gruppi di dati di grandi dimensioni in più LRO, cerca di mantenere basso il numero di partizioni.

Integrità referenziale FHIR

Il metodo fhirStores.import non prende in considerazione l'impostazione disableReferentialIntegrity. In questo modo puoi importare dati con interdipendenze arbitrarie che non richiedono ordinamento o raggruppamento, il che aumenta il throughput dei dati. Se i dati di input contengono riferimenti non validi o se non è possibile importare alcune risorse FHIR, lo stato del repository FHIR potrebbe violare l'integrità referenziale.

Per utilizzare fhirStores.import, l'applicazione client deve verificare che i riferimenti alle risorse FHIR siano validi verificando quanto segue:

  • I dati e la formattazione delle risorse FHIR sono corretti
  • Eventuali errori che si verificano durante l'importazione vengono gestiti

Per applicare l'integrità referenziale, utilizza fhir.create o fhir.executeBundle anziché fhirStores.import. Per ulteriori informazioni, consulta Importazione dei dati FHIR rispetto all'esecuzione dei bundle.

Notifiche Pub/Sub

Alcuni metodi dell'API Cloud Healthcare inviano notifiche Pub/Sub per eventi clinici, come la creazione o l'eliminazione di una risorsa sanitaria. Per un elenco dei metodi che inviano notifiche Pub/Sub, consulta Configurazione delle notifiche Pub/Sub.

I seguenti metodi di importazione non inviano notifiche Pub/Sub:

Se parti della tua applicazione richiedono una notifica al termine di un'importazione, utilizza un altro metodo di notifica che possa elencare i dati nell'importazione.

Limiti di gestione degli errori

L'API Cloud Healthcare potrebbe non registrare tutti gli errori in un LRO, soprattutto se l'LRO elabora grandi volumi di dati e genera molti errori. Implementa un modo per monitorare separatamente l'elaborazione e gli errori LRO. Per ulteriori informazioni, consulta Gestione degli errori delle risorse.

Indicizzazione dei dati e della ricerca

I ritardi nei risultati di ricerca possono verificarsi a causa dell'indicizzazione asincrona della ricerca. Se un LRO crea o aggiorna una risorsa FHIR, potrebbe essere necessario del tempo aggiuntivo prima che le modifiche siano disponibili nei risultati di ricerca.

Ad esempio, la ricerca di risorse Patient in un archivio FHIR potrebbe non restituire tutti i risultati immediatamente dopo un'operazione di importazione FHIR.

Ordine di esecuzione

Le LRO vengono pianificate in base alla disponibilità delle risorse Google Cloud. L'ordine in cui vengono eseguite e completate le richieste di operazioni locali potrebbe non corrispondere all'ordine in cui sono state richieste.

Evita piccole richieste di importazione ed esportazione

Questa sezione descrive le limitazioni dell'LRO durante l'elaborazione di piccoli volumi di dati.

Le LRO restituite dalle operazioni di importazione ed esportazione contribuiscono a scalare la velocità in bit dei dati elaborando rapidamente grandi quantità di dati ed evitando picchi di carico. Per archiviare piccole quantità di dati, utilizza un'altra tecnica descritta nelle Best practice per l'archiviazione dei dati.

Limiti al numero di OLR

L'API Cloud Healthcare limita il numero di LRO che possono essere eseguiti contemporaneamente in un progetto Google Cloud. Il limite si basa su quanto segue:

  • Il tipo di LRO.
  • La quantità di risorse Google Cloud allocate all'LRO. Il costo si basa sulle dimensioni dei dati di input.

Se esegui troppi LRO, la frequenza dell'API Cloud Healthcare viene limitata, vengono generati errori e il throughput degli LRO potrebbe diminuire. L'API Cloud Healthcare conserva automaticamente le risorse Google Cloud in modo che il numero di LRO rimanga nei limiti delle risorse.

Le LRO sono processi in background, quindi se il carico delle LRO interfere con processi di priorità più elevata, come le operazioni CRUD, l'API Cloud Healthcare può ridurre il throughput delle LRO. In questo modo, le procedure con priorità più elevata sono disponibili.

Overhead di allocazione e pulizia delle risorse

Quando viene avviato un LRO, l'API Cloud Healthcare alloca le risorse. L'operazione può richiedere diversi minuti perché l'API Cloud Healthcare deve eseguire le seguenti operazioni:

  1. Avvia un processo del controller.
  2. Alloca i worker da un pool di worker.
  3. Determina la dimensione dei dati di input.
  4. Inizia ad allocare il lavoro su larga scala.

Anche l'interruzione e la pulizia di un LRO possono richiedere diversi minuti.

A causa dell'overhead, un LRO che elabora una piccola quantità di dati potrebbe impiegare la maggior parte del tempo per allocare pool di worker e ripulire le risorse.

Se hai molti di questi LRO, potresti riscontrare una minore velocità in termini di dati perché è più probabile che tu raggiunga i limiti di quota del tuo progetto Google Cloud.

Limiti per la richiesta di quota LRO

Prima di richiedere una quota LRO più elevata, implementa le best practice per la gestione delle quote. Se hai ancora bisogno di più quota, contatta l'assistenza clienti Google Cloud. Per effettuare una richiesta, consulta la sezione Best practice per la richiesta di quota aggiuntiva.

Potresti aver bisogno di una quota aggiuntiva se i dati di input sono di grandi dimensioni, ad esempio:

  • Stai importando istanze DICOM di dimensioni pari a più petabyte (PB).
  • Stai importando decine di miliardi di risorse FHIR.

Stato LRO e stati di errore

Quando avvii un'operazione LRO, la risposta contiene un ID univoco. Puoi visualizzare lo stato di un LRO eseguendo il polling del relativo ID. Al termine dell'operazione, l'LRO assume uno dei seguenti stati:

  • Completata correttamente senza errori
  • Completata correttamente con alcuni errori
  • Non è stato possibile completare l'operazione, ma è stato eventualmente prodotto un output parziale prima dell'errore

Il seguente esempio JSON descrive la risposta restituita al termine di un LRO:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": 
    
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

Per ottenere lo stato di un'operazione a lunga esecuzione, elencarle e annullarle, consulta Gestione di operazioni a lunga esecuzione.

Gestire lo stato LRO e gli stati di errore

Per gestire lo stato e gli stati di errore dell'LRO, segui queste best practice:

  • Effettua il polling delle richieste di accesso in lettura per ottenere il relativo stato e verificare quando sono state completate. Per eseguire il polling di un'operazione LRO, chiama ripetutamente il metodo projects.locations.datasets.operations.get fino al termine dell'operazione. Utilizza un backoff tra ogni richiesta di polling, ad esempio 10 secondi. Quando la risposta contiene "done": true, la LRO è terminata.

  • Al termine di un LRO, controlla se la risposta contiene un campo error. In questo caso, decidi se riprovare a eseguire l'operazione in base a quanto segue:

    • Il codice di errore. Consulta la sezione Risoluzione dei problemi relativi alle richieste di accesso a livello di organizzazione per i codici di errore e le azioni consigliate.
    • Il numero di tentativi già avvenuti.
    • Il tempo che intercorre tra l'inizio dell'operazione LRO e il momento in cui si è verificato l'errore. Ad esempio, se un'operazione LRO che normalmente richiede diverse ore richiede diversi giorni e non ha fornito uno stato di errore, potrebbe essere necessario l'intervento di un operatore. Per maggiori informazioni su quando potrebbe essere necessario l'intervento umano, consulta Pianificare gli stati di errore finali.

    Per informazioni su come riprovare un LRO, consulta Mettere in coda un LRO.

  • Se non stai riprovando l'operazione LRO, visualizza il campo metadata.counter.failure per verificare se si sono verificati errori su risorse specifiche. Potresti essere in grado di elaborare le risorse singolarmente. Per ulteriori informazioni, vedi Gestire gli errori delle risorse.

Gestire gli errori delle risorse

Un'operazione LRO può terminare con errori. Gli errori nella risposta LRO rispettano il modello di errore di Google Cloud. La risposta LRO include un link a Cloud Logging per ulteriori informazioni.

Dettagli errore LRO

Gli errori LRO in Cloud Logging hanno le seguenti proprietà:

  • Il log degli errori di Cloud Logging non contiene l'ID LRO. Utilizza i campi operation.id e operation.producer per trovare lo stato e gli errori dell'LRO. Ad esempio, le richieste di operazioni locali richiamate dal metodo projects.locations.datasets.fhirStores.import contengono import_fhir nel campo operation.producer.

    Se più LRO hanno gli stessi operation.id e operation.producer, utilizza i timestamp createTime e endTime per identificare l'LRO corretto.

  • Non tutti gli errori LRO sono disponibili in Cloud Logging. Il campo metadata.counter.failure potrebbe superare il numero di errori effettivi registrati a causa di quanto segue:

    • Limitazioni delle quote di Cloud Logging
    • Disponibilità del servizio Cloud Logging
    • Limiti dei log LRO

    Ad esempio, se un LRO importa 10 milioni di risorse FHIR e il 50% di queste presenta errori di formattazione, potrebbero essere registrati solo alcuni centinaia o alcuni migliaia di errori a causa del limitazione di frequenza e delle quote di Cloud Logging.

    Il numero di errori registrati varia anche in base al tempo di esecuzione dell'LRO quando si verificano tassi di errore elevati. Se l'LRO funziona lentamente, potrebbe mostrare più errori in Cloud Logging perché sono stati distribuiti su un lungo periodo di tempo e non sono stati soggetti a limitazione della frequenza.

Effetti del nuovo tentativo di un LRO

Se un LRO rileva un errore e un'applicazione client riprova automaticamente l'operazione utilizzando gli stessi dati, il nuovo tentativo potrebbe causare ulteriori errori.

Considera uno scenario in cui un LRO di fhirStores.import termina con errori perché alcune delle risorse FHIR che ha provato a importare non erano valide. La ripetizione automatica dell'importazione con gli stessi dati potrebbe generare molti errori 409 ALREADY_EXISTS perché alcune risorse FHIR sono state importate nell'operazione originale. Se esegui una query su un LRO e trovi un'operazione di creazione non riuscita, non riprovare automaticamente. Gli errori 409 ALREADY_EXISTS devono essere esaminati da una persona.

Se un nuovo tentativo va a buon fine, il campo metadata.counter.failure non include gli errori delle operazioni precedenti. Ciò potrebbe causare un conteggio errato degli errori perché la risposta del nuovo tentativo riuscito non include gli errori dei tentativi precedenti.

Riprovare un LRO

Se hai una pipeline di elaborazione lato client che rileva errori LRO, non utilizzare Cloud Logging. Come mostrato in Dettagli sugli errori LRO, i log degli errori di Cloud Logging per le richieste LRO non sono affidabili e sono incompleti. Utilizza invece le tecniche descritte nelle sezioni seguenti.

Riprovare le operazioni di importazione

Per rilevare i dati di cui non è andata a buon fine l'importazione, confronta i dati importati nell'API Cloud Healthcare con i dati di origine in Cloud Storage. Puoi importare i dati utilizzando i seguenti metodi:

Utilizza un identificatore univoco, ad esempio un numero di record sanitario (MRN) per una risorsa FHIR Patient, per confrontare i dati.

Consulta Effetti del nuovo tentativo di un'operazione LRO per conoscere la procedura da seguire quando si ritenta un'operazione di importazione.

La nuova esecuzione di un'importazione potrebbe ricreare le risorse che hai eliminato in precedenza. Considera lo scenario seguente:

  1. Provi a importare 1.000.000 risorse FHIR. 50.000 risorse non vanno a buon fine a causa di errori di formattazione.
  2. Trascorri diversi giorni a correggere gli errori di formattazione. Durante questo periodo, un paziente ti chiede di rimuovere i suoi dati.
  3. Se esegui nuovamente l'importazione, rischi di ricreare i dati del paziente che hai eliminato.

Riprovare le operazioni di esportazione

Per rilevare i dati di cui non è riuscita l'esportazione in BigQuery, scrivi uno script per confrontare gli ID univoci nei dati di origine con i dati esportati.

Puoi esportare i dati in BigQuery utilizzando i seguenti metodi:

Mettere in coda e gestire le richieste LRO

Se esegui LRO che elaborano grandi volumi di dati per l'onboarding o secondo una programmazione regolare, implementa le seguenti tecniche di coda LRO:

  • Limita il numero di richieste LRO simultanee a un numero ridotto, ad esempio 5. Puoi modificare questo limite in base alle dimensioni e ai tipi di annunci dinamici della rete di ricerca che pubblichi.
  • Monitora il completamento dell'LRO. Se si verificano errori, riprogramma l'LRO o risolvi gli errori singolarmente nella pipeline di elaborazione.

  • Risolvi automaticamente gli errori descritti in Gestione degli errori delle risorse, se possibile.

    • Comprendi il caso d'uso per le importazioni FHIR per determinare se ignorare gli errori 409 ALREADY_EXISTS o eseguire operazioni CRUD separate per risolverli. Come mostrato in Dettagli errori LRO, alcuni errori 409 ALREADY_EXISTS potrebbero non essere registrati in Cloud Logging. Se la tua applicazione si basa su log degli errori, utilizza una delle tecniche descritte in Riprovare un LRO.

    • Per risolvere alcuni errori, metti in coda un LRO più piccolo per i dati in cui si sono verificati gli errori o esegui operazioni CRUD separate.

    • Per risolvere molti errori, la riesecuzione dell'LRO potrebbe essere l'opzione più semplice per garantire la coerenza. Consulta Ripetere le operazioni di importazione per conoscere i rischi di esecuzione di un'importazione sui dati eliminati.

  • Rileva automaticamente se è necessario l'intervento umano per risolvere gli errori. Devi disporre di strumenti e playbook operativi per gli amministratori di sistema. Le attività per risolvere gli errori potrebbero includere:

    • Riprogrammare un LRO.
    • Riprogrammare un sottoinsieme di dati di un LRO precedente.
    • Esamina gli errori e risolvi i singoli elementi di dati che hanno riscontrato errori. Questa operazione è possibile solo se puoi stabilire che tutti gli errori nell'LRO sono stati registrati.

  • Determina le pianificazioni delle operazioni di recupero locali. Potresti pianificare le LRO per evitare che vengano eseguite nelle ore di punta quando sono in esecuzione molte operazioni CRUD. Per ulteriori informazioni, consulta Gestire la quota per massimizzare il throughput dei dati.

Monitorare e ricevere avvisi

Crea e gestisci procedure per il monitoraggio delle richieste di accesso a livello di organizzazione e la risoluzione degli avvisi. Gli avvisi sono causati principalmente dagli stati LRO e da problemi di coda. Le procedure devono affrontare le seguenti situazioni:

  • LRO che tentano più volte senza successo rispetto a quanto configurato.
  • Problemi che richiedono l'intervento umano per risolvere un sottoinsieme di errori. Ad esempio, se un LRO non va a buon fine e il cliente non riesce a risolvere gli errori, è probabile che sia necessario l'intervento di una persona. Per ulteriori informazioni su come risolvere i problemi che richiedono l'intervento umano, consulta la sezione Coda e gestione delle richieste di ottimizzazione lato client.
  • Code che superano una determinata lunghezza o che crescono troppo rapidamente.
  • Mancata conformità ai requisiti delle norme, ad esempio un problema di autorizzazioni o una configurazione errata.
  • Controlli di coerenza che mostrano problemi sistemici in più LRO. Potresti avere diversi annunci LRO di anonimizzazione che si aspettano che il set di dati di origine e il set di dati di destinazione abbiano lo stesso numero di risorse FHIR. Se esiste una discrepanza in aumento nel tempo, potrebbe indicare dati non elaborati.
  • Problemi relativi alla quota LRO. Per ulteriori informazioni, consulta Gestire la quota per massimizzare il throughput dei dati e Best practice per la gestione delle quote.