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

Gli LRO non condividono la quota con l'API Cloud Healthcare per le attività di creazione, lettura, aggiornamento i metodi delete (CRUD) che consumano i seguenti tipi della quota:

La quota LRO viene calcolata utilizzando fhir_store_lro_ops e dicom_store_lro_ops metriche di valutazione.

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

Velocità in Mbps

I metodi LRO di solito ottengono una velocità effettiva dei dati più elevata rispetto a metodi CRUD equivalenti. Ad esempio, l'importazione di istanze DICOM con dicomStores.import in genere ottiene risultati migliori quando si archiviano le 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
  • Conflitto delle risorse
  • Altro traffico che il progetto Google Cloud invia all'API Cloud Healthcare mentre un LRO esegue

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

  • I batch di importazione ed esportazione di piccole dimensioni hanno in genere una velocità effettiva bassa overhead.
  • Gli LRO vengono eseguiti e consumano la quota separatamente dalle altre operazioni dell'API Cloud Healthcare.
  • Ogni LRO ha una velocità effettiva massima.
  • LRO concorrenti 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 al 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

La fhirStores.import non considera disableReferentialIntegrity dell'ambientazione. Ciò ti consente di importare dati con interdipendenze arbitrarie che non non richiedono l'ordinamento o il raggruppamento, il che aumenta la velocità effettiva dei dati. Se i dati di input contiene riferimenti non validi o, se l'importazione di alcune risorse FHIR non riesce, il valore lo stato del negozio potrebbe violare integrità referenziale.

Per utilizzare fhirStores.import, la tua applicazione client deve avere per assicurarti che i riferimenti alle risorse FHIR siano validi, verificando quanto segue:

  • I dati e la formattazione delle risorse FHIR sono corretti
  • Tutti gli 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 scopi 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 quando l'importazione, utilizza un altro metodo di notifica in grado di elencare i dati l'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: una ricerca di risorse Patient in un datastore FHIR potrebbe non restituire tutti i risultati immediatamente dopo un'operazione di importazione FHIR.

Ordine di esecuzione

Gli LRO sono pianificati in base alla disponibilità delle risorse di 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 richieste di importazione ed esportazione di piccole dimensioni

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. Si basa su sulla dimensione 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. Ciò garantisce la disponibilità dei processi con priorità più elevata.

Overhead di allocazione e pulizia delle risorse

All'avvio di un LRO, l'API Cloud Healthcare alloca le risorse. Questo può richiedere diversi minuti, perché l'API Cloud Healthcare deve:

  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 a distribuire 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 disponi di molti di questi LRO, potresti riscontrare di riduzione della velocità effettiva dei dati perché è più probabile che soddisfi le tue Google Cloud limiti di quota per i progetti.

Limiti alla richiesta di una quota LRO

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

Potrebbe essere necessaria 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 Stato dell'LRO tramite polling del relativo ID. Al termine dell'operazione, l'LRO assume uno dei seguenti stati:

  • Completata correttamente senza errori
  • Completato correttamente con alcuni errori
  • Impossibile completare, ma potrebbe essere stato generato un output parziale prima di non riuscire

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.

Gestisci lo stato LRO e gli stati di errore

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

  • Fai sondaggi agli LRO per conoscerne lo stato e verificare una volta terminati. 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, LRO è terminato.

  • Al termine di un'operazione 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 agli LRO per visualizzare i codici di errore e le azioni consigliate.
    • Il numero di nuovi tentativi già eseguiti.
    • Il tempo che intercorre tra l'inizio dell'LRO e il momento in cui si è verificato l'errore. Ad esempio, se un LRO che normalmente richiede diverse ore richiede diversi giorni e non ha restituito uno stato di errore, potresti richiedere l'intervento di un essere umano. Per maggiori informazioni su quando potrebbe essere necessario l'intervento umano, consulta Pianificare gli stati di errore finali.

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

  • Se non stai ritentando l'LRO, visualizza il campo metadata.counter.failure per verificare se si sono verificati errori il risorse specifiche. Potresti essere in grado di elaborare le risorse singolarmente. Per saperne di più, consulta Gestione degli errori delle risorse.

Gestire gli errori delle risorse

Un'operazione LRO può terminare con errori. Gli errori nella risposta LRO seguono 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 LRO 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 di 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 limite di velocità e delle quote di Cloud Logging.

    Anche il numero di errori registrati varia in base al tempo l'LRO viene eseguito e rileva alti tassi di errore. Se l'LRO funziona lentamente, potrebbe mostrare più errori in Cloud Logging perché sono stati distribuiti per un lungo periodo di tempo e non erano soggetti a limitazioni di frequenza.

Effetti di un nuovo tentativo di LRO

Se un LRO rileva un errore e un'applicazione client proverà automaticamente a eseguire un nuovo tentativo utilizzando gli stessi dati, il nuovo tentativo potrebbe causare altri errori.

Considera uno scenario in cui un LRO fhirStores.import termina con errori perché alcune delle risorse FHIR che ha tentato di importare non erano valide. È possibile che un nuovo tentativo automatico di importazione con gli stessi dati generano molti errori di tipo 409 ALREADY_EXISTS perché alcune risorse FHIR erano importati 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 ha esito positivo, il campo metadata.counter.failure non include da operazioni precedenti. Ciò potrebbe causare un conteggio errato degli errori perché la risposta relativa al nuovo tentativo riuscito non include errori dei tentativi precedenti.

Riprova un LRO

Se hai una pipeline di elaborazione lato client che rileva l'LRO gli errori, non usare Cloud Logging. Come mostrato nei dettagli dell'errore LRO, i log degli errori di Cloud Logging per gli LRO non sono affidabili e sono incompleti. Utilizza invece le tecniche descritte nelle sezioni seguenti.

Riprova 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 il numero di una cartella clinica (MRN) di una risorsa FHIR Patient, per confrontare i dati.

Consulta la sezione Effetti di un nuovo tentativo di LRO per conoscere la procedura da seguire quando un nuovo tentativo di importazione.

Eseguire nuovamente un'importazione potrebbe ricreare le risorse eliminate in precedenza. Prendi in considerazione il seguente scenario:

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

Riprovare le operazioni di esportazione

Per rilevare i dati la cui esportazione in BigQuery non è riuscita, 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 a seconda delle dimensioni e dei tipi di Gli LRO che gestisci.
  • 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 delle importazioni FHIR per determinare se ignora 409 ALREADY_EXISTS errori o esegui CRUD separati operazioni per risolvere gli errori. Come mostrato nei dettagli dell'errore LRO, alcuni errori 409 ALREADY_EXISTS potrebbero non essere registrati in Cloud Logging. Se l'applicazione si basa su log degli errori, utilizza una delle tecniche in Riprova un LRO.

    • Per risolvere alcuni errori, metti in coda una coda LRO per i dati che hanno riscontrato gli errori o che hanno eseguito Operazioni CRUD.

    • Per risolvere molti errori, eseguire nuovamente l'LRO potrebbe essere l'opzione più semplice garantire 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. Dovresti avere strumenti e playbook operativi per amministratori di sistema. Le attività per correggere gli errori possono includere quanto segue:

    • Riprogrammare un LRO.
    • Ripianifica un sottoinsieme di dati di un LRO precedente.
    • Esaminare gli errori e gestire i singoli elementi di dati in cui si sono verificati errori. Questa operazione è possibile solo se puoi stabilire che tutti gli errori nell'LRO sono stati registrati.

  • Determina le pianificazioni delle operazioni di recupero dei dati. Potresti programmare LRO per evitare l'esecuzione nelle ore di punta, quando sono in esecuzione molte operazioni CRUD. Per Per saperne di più, consulta Gestire la quota per massimizzare la velocità effettiva dei dati.

Monitorare e ricevere avvisi

Creare e mantenere procedure per il monitoraggio degli LRO e la risoluzione degli avvisi. Google Alert sono causati principalmente dagli stati LRO e dall'accodamento che le applicazioni presentino problemi di prestazioni. 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. Consulta Mettere in coda e gestire gli LRO per ulteriori informazioni su come risolvere i problemi che richiedono l'intervento umano.
  • 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 più operazione di eliminazione dell'identità LRO 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.