Best practice per le operazioni a lunga esecuzione

In questa pagina vengono descritte le best practice per l'esecuzione e la gestione di modelli operazioni (LRO) nell'API Cloud Healthcare. Per una panoramica degli LRO Nell'API Cloud Healthcare, consulta Gestione delle operazioni a lunga esecuzione.

Proprietà LRO

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

Impatto sulla quota

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à effettiva dati

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 contemporanea di più LRO potrebbe non aumentare la velocità effettiva dei dati a causa ai seguenti vincoli, soprattutto durante l'elaborazione di grandi volumi di dati:

  • Limiti di quota
  • Conflitto delle risorse
  • Altro traffico che il tuo progetto Google Cloud invia all'API Cloud Healthcare mentre un LRO esegue

Per ottenere la velocità effettiva dei dati massima quando esegui LRO, valuta la possibilità di le seguenti:

  • 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.
  • Gli LRO simultanei sulla stessa risorsa possono causare conflitti tra 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 eseguire la partizione in batch di dati di grandi dimensioni su più LRO, cerca di mantenere un numero ridotto 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 della risorsa FHIR sono corretti
  • Tutti gli errori che si verificano durante l'importazione vengono gestiti

Per applicare l'integrità referenziale, utilizza fhir.create oppure fhir.executeBundle anziché fhirStores.import. Per ulteriori informazioni consulta l'articolo Importare dati FHIR rispetto all'esecuzione di 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, in particolare se l'LRO elabora grandi volumi di dati e produce molti errori. Implementa un modo per monitorare separatamente l'elaborazione e gli errori LRO. Per ulteriori informazioni, vedi Gestione degli errori delle risorse.

Indicizzazione dei dati e della ricerca

Potrebbero verificarsi ritardi nei risultati di ricerca a causa dell'indicizzazione della ricerca asincrona. Se un LRO crea o aggiorna una risorsa FHIR, potrebbe essere necessario più tempo 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 gli LRO vengono eseguiti e terminati potrebbero non corrispondere all'ordine richieste.

Evita richieste di importazione ed esportazione di piccole dimensioni

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

Gli LRO restituiti dalle operazioni di importazione ed esportazione aiutano a scalare la velocità effettiva dei dati elaborando rapidamente grandi quantità di dati ed evitando i picchi di carico. A Archiviare piccole quantità di dati, utilizza un'altra tecnica descritta nelle Best practice per l'archiviazione dei dati.

Limiti al numero di LRO

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, i limiti di frequenza dell'API Cloud Healthcare producono e potrebbe ridurre la velocità effettiva LRO. L'API Cloud Healthcare viene automaticamente conserva le risorse di Google Cloud in modo che il numero di LRO rimanga all'interno limiti delle risorse.

Gli LRO sono processi in background, quindi se il carico dagli LRO interferisce con i processi a priorità più elevata, come CRUD operazioni, l'API Cloud Healthcare può ridurre il LRO e la velocità effettiva effettiva. 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'arresto e la pulizia di un LRO possono richiedere diversi minuti.

A causa dell'overhead, un LRO che elabora una piccola quantità di dati potrebbe dedicare la maggior parte del suo tempo all'allocazione dei pool di worker e alla pulizia per l'ottimizzazione delle 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 superiore, implementa la classe Best practice per la gestione delle quote. 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 LRO, la risposta contiene un ID univoco. Puoi visualizzare Lo stato dell'LRO tramite polling del relativo ID. Dopo il giorno termina l'LRO, avrà 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 quando un LRO finiture:

{
  "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 conoscere lo stato di un LRO, elenca gli LRO e annulla Per gli LRO, consulta Gestione delle 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 LRO, richiama ripetutamente il metodo projects.locations.datasets.operations.get fino al termine dell'operazione. Utilizza un backoff tra ogni richiesta di sondaggio, ad esempio di 10 secondi. Quando la risposta contiene "done": true, LRO è terminato.

  • Al termine di un LRO, controlla se la risposta contiene un campo error. In caso affermativo, determina se riprovare 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 per ulteriori informazioni sui casi in cui potrebbe essere necessario l'intervento umano, vedi Pianifica 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 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 la Campi operation.id e operation.producer per trovare lo stato dell'LRO ed errori. Ad esempio, gli LRO richiamati 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. metadata.counter.failure potrebbe superare il numero di errori effettivi registrati per i seguenti motivi:

    • 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, il 50% di queste errori di formattazione, potrebbero essere registrati solo alcune centinaia o alcune migliaia di errori a causa della limitazione di frequenza 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 fare 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 poiché 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 rilevi un errore creazione, non riprovare automaticamente. La revisione deve essere eseguita da una persona 409 ALREADY_EXISTS errore.

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 la le tecniche nelle sezioni seguenti.

Riprova le operazioni di importazione

Per rilevare i dati la cui importazione non è riuscita, confronta i dati importati in l'API Cloud Healthcare ai 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 di risorse FHIR. 50.000 risorse non riuscita a causa di errori di formattazione.
  2. Devi dedicare diversi giorni a correggere gli errori di formattazione. Durante questo periodo, un paziente richiede la rimozione dei suoi dati.
  3. Se esegui di nuovo l'importazione, rischi di ricreare i dati del paziente che hai eliminato.

Riprova a eseguire 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 gli LRO

Se esegui LRO che elaborano grandi volumi di dati per l'onboarding o a intervalli regolari implementare le seguenti tecniche di accodamento LRO:

  • Limita gli LRO simultanei a un numero ridotto, ad esempio 5. Puoi modificare questo limite a seconda delle dimensioni e dei tipi di Gli LRO che gestisci.
  • Monitorare il completamento dell'LRO. Se si verificano errori, riprogramma l'LRO o risolvi separatamente gli errori nella pipeline di elaborazione.

  • Risolvi automaticamente gli errori in Gestione degli errori delle risorse laddove 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, rieseguire l'LRO potrebbe essere l'opzione più semplice garantire coerenza. Vedi Ripetere le operazioni di importazione per i rischi legati alla riesecuzione di un'importazione sui dati eliminati.

  • Rileva automaticamente se è necessario un 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:

    • Riprogramma 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 attività è possibile solo se puoi determinare che tutti gli errori nell'LRO sono stati registrati.

  • Determinare le pianificazioni LRO. 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 dovrebbero risolvere le seguenti situazioni:

  • LRO che non riprovano più volte rispetto a quanto è configurato.
  • Problemi che richiedono l'intervento umano per risolvere un sottoinsieme di errori. Ad esempio, se un LRO non riesce e il client non è in grado di risolvere gli errori, probabilmente è necessaria. 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 lunghezza o crescono troppo rapidamente.
  • I requisiti delle norme non sono soddisfatti, ad esempio problemi di autorizzazioni o una configurazione errata.
  • Controlli di coerenza che mostrano i problemi sistemici in più LRO. Potrebbero essere presenti diversi LRO di anonimizzazione che prevedono il set di dati di origine e quello di destinazione per avere lo stesso numero di risorse FHIR. In caso di discrepanza che cresce nel tempo, potrebbe indicare dati non elaborati.
  • Problemi relativi alla quota LRO. Per saperne di più, consulta Gestire la quota per massimizzare la velocità effettiva dei dati e Best practice per la gestione della quota.