Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Risolvere i problemi relativi agli errori dell'API BigQuery Storage

Questo documento spiega come risolvere i problemi durante la lettura o lo streaming di dati in BigQuery utilizzando l'API BigQuery Storage Read, l'API BigQuery Storage Write (gRPC) o gli inserimenti in streaming con l'API BigQuery Storage Write (REST) (metodo tabledata.insertAll).

Analizza la telemetria di streaming con le viste INFORMATION_SCHEMA

Puoi eseguire query sulle viste INFORMATION_SCHEMA per monitorare l'integrità dell'acquisizione di importazione di flussi di dati, identificare i colli di bottiglia del throughput e ispezionare i codici di errore a intervalli di un minuto:

API Storage Write (gRPC): esegui query sulle viste INFORMATION_SCHEMA.WRITE_API_TIMELINE per esaminare le richieste di importazione di flussi di dati di dati gRPC, i byte e le righe totali aggiunti e i conteggi degli errori per error_code.
API Storage Write (REST): esegui query sulle INFORMATION_SCHEMA.STREAMING_TIMELINE viste per esaminare le richieste di streaming REST tabledata.insertAll precedenti e gli errori di quota o limite di frequenza.

Il seguente esempio esegue query su INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT per recuperare i conteggi degli errori e i byte inseriti per l'API Storage Write (gRPC) nelle ultime 24 ore:

SELECT
  start_timestamp,
  error_code,
  SUM(total_requests) AS request_count,
  SUM(total_input_bytes) AS input_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  AND error_code IS NOT NULL
GROUP BY
  start_timestamp,
  error_code
ORDER BY
  start_timestamp DESC;

Sostituisci REGION con il nome della regione del set di dati, ad esempio us o europe-west1.

Risolvere i problemi relativi agli errori dell'API Storage di lettura

Di seguito sono riportati gli errori comuni riscontrati quando utilizzi l'API Storage di lettura:

Errore: Stream removed: Soluzione:riprova a inviare la richiesta dell'API Storage di lettura. Probabilmente si tratta di un errore temporaneo che puoi risolvere riprovando a inviare la richiesta. Se il problema persiste, contatta l'assistenza clienti Google Cloud.
Errore: Stream expired: Causa: questo errore si verifica quando la sessione dell'API Storage Read raggiunge il timeout di 6 ore.; Risoluzione:

Aumenta il parallelismo del job.
Se l'utilizzo della CPU dei nodi worker è relativamente coerente e non supera l'85%, valuta la possibilità di eseguire il job su un tipo di macchina più grande.
Suddividi il job in più job o query più piccole.

Per saperne di più sulla gestione delle sessioni e sulla lettura dei dati, consulta la panoramica dell'API Storage Read.

Risolvere i problemi relativi agli inserti di streaming

Le sezioni seguenti descrivono come risolvere gli errori che si verificano quando trasmetti dati in streaming in BigQuery utilizzando l'API Storage Write (REST). Per saperne di più su come risolvere gli errori di quota per gli inserimenti di flussi di dati, consulta Errori di quota degli inserimenti di flussi di dati.

Codici di risposta HTTP di errore

Se ricevi un codice di risposta HTTP di errore, ad esempio un errore di rete, non è possibile determinare se l'inserimento di flussi di dati è riuscito. Se provi a inviare di nuovo la richiesta, potresti ottenere righe duplicate nella tabella. Per proteggere la tabella dalla duplicazione, imposta la proprietà insertId quando invii la richiesta. BigQuery utilizza la proprietà insertId per la deduplicazione.

Se ricevi un errore di autorizzazione, un errore di nome tabella non valido o un errore di quota superata, non vengono inserite righe e l'intera richiesta non va a buon fine.

Codici di risposta HTTP riusciti

Anche se ricevi un codice di risposta HTTP riuscita, devi controllare la proprietà insertErrors della risposta per determinare se gli inserimenti di righe sono riusciti, perché BigQuery potrebbe riuscire solo parzialmente a inserire le righe. Potresti riscontrare uno dei seguenti scenari:

Tutte le righe inserite correttamente:se la proprietà insertErrors è un elenco vuoto, tutte le righe sono state inserite correttamente.
Alcune righe inserite correttamente: tranne nei casi in cui si verifica una mancata corrispondenza dello schema in una delle righe, le righe indicate nella proprietà insertErrors non vengono inserite e tutte le altre righe vengono inserite correttamente. La proprietà errors contiene informazioni dettagliate sul motivo per cui ogni riga non riuscita non è andata a buon fine. La proprietà index indica l'indice di riga in base zero della richiesta a cui si applica l'errore.
Nessuna riga inserita correttamente: se BigQuery rileva una mancata corrispondenza dello schema nelle singole righe della richiesta, nessuna riga viene inserita e viene restituita una voce insertErrors per ogni riga, anche per quelle che non presentano una mancata corrispondenza dello schema. Le righe che non presentavano una mancata corrispondenza dello schema hanno un errore con la proprietà reason impostata su stopped e puoi inviarle così come sono. Le righe non riuscite includono informazioni dettagliate sulla mancata corrispondenza dello schema. Per scoprire di più sui tipi di buffer di protocollo supportati per ogni tipo di dati BigQuery, consulta Tipi di dati Arrow e buffer di protocollo supportati.

Errori dei metadati per gli inserimenti in streaming

Poiché l'API BigQuery Streaming è progettata per tassi di inserimento elevati, le modifiche ai metadati della tabella sottostante sono coerenti nel tempo quando interagisci con il sistema di streaming. La maggior parte delle volte, le modifiche ai metadati si propagano in pochi minuti, ma durante questo periodo le risposte dell'API potrebbero riflettere lo stato incoerente della tabella.

Alcuni scenari includono:

Modifiche allo schema:la modifica dello schema di una tabella che ha ricevuto di recente inserimenti in streaming può causare risposte con errori di mancata corrispondenza dello schema perché il sistema di streaming potrebbe non rilevare immediatamente la modifica dello schema.
Creazione o eliminazione di tabelle:lo streaming in una tabella inesistente restituisce una variante di una risposta notFound. Una tabella creata in risposta potrebbe non essere riconosciuta immediatamente dagli inserimenti di streaming successivi. Analogamente, l'eliminazione o la ricreazione di una tabella può creare un periodo di tempo in cui gli inserimenti in streaming vengono inviati alla vecchia tabella. Gli inserimenti in streaming potrebbero non essere presenti nella nuova tabella.
Troncamento della tabella:il troncamento dei dati di una tabella (utilizzando un job di query che utilizza un valore writeDisposition di WRITE_TRUNCATE) può causare in modo simile l'eliminazione degli inserimenti successivi durante il periodo di coerenza.

Dati mancanti o non disponibili

Gli inserimenti in streaming risiedono temporaneamente nello spazio di archiviazione ottimizzato per la scrittura, che ha caratteristiche di disponibilità diverse rispetto allo spazio di archiviazione gestito. Alcune operazioni in BigQuery non interagiscono con l'archiviazione ottimizzata per la scrittura, ad esempio i job di copia delle tabelle e i metodi API come tabledata.list. I dati di streaming recenti non sono presenti nella tabella di destinazione o nell'output.

Errori di quota relativi agli inserimenti di flussi di dati

Questa sezione fornisce suggerimenti per la risoluzione dei problemi relativi agli errori di quota correlati alla trasmissione dei dati in BigQuery.

In alcune aree geografiche, gli inserimenti di flussi di dati hanno una quota maggiore se non immetti dati nel campo insertId per ogni riga. Per ulteriori informazioni sulle quote per gli inserimenti di flussi di dati, consulta la pagina relativa agli Inserimento di flussi di dati. Gli errori relativi alle quote per i flussi di dati di BigQuery dipendono dalla presenza o dall'assenza di un valore nel campo insertId.

Messaggio di errore

Se il campo insertId è vuoto, si può verificare il seguente errore di quota:

Limite quota	Messaggio di errore
Byte al secondo per progetto	La tua entità con gaia_id: `GAIA_ID`, progetto: `PROJECT_ID` nella regione: `REGION` ha superato la quota per i byte di inserimento al secondo.

Se il campo insertId è compilato, si possono verificare i seguenti errori di quota:

Limite quota	Messaggio di errore
Righe al secondo per progetto	Il tuo progetto `PROJECT_ID` in `REGION` ha superato la quota per l'inserimento di righe di flussi di dati al secondo.
Righe al secondo per tabella	La tua tabella: `TABLE_ID` ha superato la quota per l'inserimento di flussi di dati di righe al secondo.
Byte al secondo per tabella	La tua tabella: `TABLE_ID` ha superato la quota per byte di inserimento di flussi di dati al secondo.

Lo scopo del campo insertId è deduplicare le righe inserite. Se arrivano più inserimenti con lo stesso insertId nel giro di pochi minuti, BigQuery scrive un'unica versione del record. Tuttavia, questa deduplicazione automatica non è garantita. Per la massima velocità effettiva di trasmissione dei flussi di dati, ti consigliamo di non includere insertId e di usare invece la deduplicazione manuale. Per ulteriori informazioni, consulta la pagina relativa a come garantire la coerenza dei dati.

Quando si verifica questo errore, diagnostica il problema e poi segui i passaggi consigliati per risolverlo.

Diagnosi

Usa le viste STREAMING_TIMELINE_BY_* per analizzare il traffico dei flussi di dati. Queste visualizzazioni aggregano le statistiche di streaming a intervalli di un minuto, raggruppate per error_code. Gli errori relativi alla quota vengono visualizzati nei risultati con error_code uguale a RATE_LIMIT_EXCEEDED o QUOTA_EXCEEDED.

A seconda del limite di quota specifico raggiunto, fai riferimento a total_rows o total_input_bytes. Se l'errore riguarda una quota a livello di tabella, filtra per table_id.

Ad esempio, la seguente query mostra i byte totali importati al minuto e il numero totale di errori di quota:

SELECT
 start_timestamp,
 error_code,
 SUM(total_input_bytes) as sum_input_bytes,
 SUM(IF(error_code IN ('QUOTA_EXCEEDED', 'RATE_LIMIT_EXCEEDED'),
     total_requests, 0)) AS quota_error
FROM
 `region-REGION_NAME`.INFORMATION_SCHEMA.STREAMING_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 1 DAY)
GROUP BY
 start_timestamp,
 error_code
ORDER BY 1 DESC

Risoluzione

Per risolvere questo errore relativo alla quota, segui questi passaggi:

Se utilizzi il campo insertId per la deduplicazione e il tuo progetto si trova in una regione che supporta la quota di streaming più elevata, ti consigliamo di rimuovere il campo insertId. Questa soluzione potrebbe richiedere alcuni passaggi aggiuntivi per deduplicare manualmente i dati. Per ulteriori informazioni, vedi Rimozione manuale dei duplicati.
Se non usi insertId, oppure non è possibile rimuoverlo, monitora il traffico dei flussi di dati per un periodo di 24 ore e analizza gli errori di quota:
- Se visualizzi principalmente errori RATE_LIMIT_EXCEEDED anziché errori QUOTA_EXCEEDED e il traffico complessivo è inferiore all'80% della quota, è probabile che gli errori indichino picchi temporanei. Puoi risolvere questi errori riprovando l'operazione utilizzando il backoff esponenziale tra i tentativi.
- Se utilizzi un job Dataflow per inserire dati, valuta la possibilità di utilizzare job di caricamento anziché inserimenti in streaming. Per saperne di più, vedi Impostazione del metodo di inserimento. Se utilizzi Dataflow con un connettore I/O personalizzato, valuta la possibilità di utilizzare un connettore I/O integrato. Per saperne di più, consulta Pattern I/O personalizzati.
- Se visualizzi errori QUOTA_EXCEEDED o il traffico complessivo supera costantemente l'80% della quota, invia una richiesta di aumento della quota. Per saperne di più, consulta Richiedi un aggiustamento delle quote.
- Potresti anche prendere in considerazione la sostituzione degli inserimenti in streaming con la più recente API Storage Write, che offre una velocità effettiva più elevata, un prezzo inferiore e molte funzionalità utili.