Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Résoudre les erreurs de l'API BigQuery Storage

Ce document explique comment résoudre les problèmes liés à la lecture ou au streaming de données dans BigQuery à l'aide de l'API BigQuery Storage Read, de l'API BigQuery Storage Write (gRPC) ou des insertions en flux continu avec l'API BigQuery Storage Write (REST) (méthode tabledata.insertAll).

Analyser la télémétrie de streaming avec les vues INFORMATION_SCHEMA

Vous pouvez interroger les vues INFORMATION_SCHEMA pour surveiller l'état de l'ingestion en flux continu, identifier les goulots d'étranglement du débit et inspecter les codes d'erreur sur des intervalles d'une minute :

API Storage Write (gRPC) : interrogez les vues INFORMATION_SCHEMA.WRITE_API_TIMELINE pour inspecter les requêtes d'ingestion en flux continu gRPC, le nombre total d'octets et de lignes ajoutés, ainsi que le nombre d'erreurs par error_code.
API Storage Write (REST) : interrogez les vues INFORMATION_SCHEMA.STREAMING_TIMELINE pour inspecter les anciennes requêtes de streaming tabledata.insertAll REST et les erreurs de quota ou de limite de fréquence.

L'exemple suivant interroge INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT pour récupérer le nombre d'erreurs et les octets ingérés pour l'API Storage Write (gRPC) au cours des dernières 24 heures :

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;

Remplacez REGION par le nom de la région de l'ensemble de données, par exemple us ou europe-west1.

Résoudre les erreurs de l'API Storage Read

Voici les erreurs courantes rencontrées lorsque vous utilisez l'API Storage Read :

Erreur : Stream removed: Résolution : réessayez la requête API Storage Read. Il s'agit probablement d'une erreur temporaire que vous pouvez résoudre en réessayant d'envoyer la requête. Si le problème persiste, contactez l'assistance Cloud Customer Care.
Erreur : Stream expired: Cause : Cette erreur se produit lorsque la session de l'API Storage Read atteint le délai d'expiration de six heures.; Solution :

Augmentez le parallélisme du job.
Si l'utilisation du processeur des nœuds de calcul est relativement constante et ne dépasse pas 85%, envisagez d'exécuter le job sur un type de machine plus grand.
Divisez le job en plusieurs jobs ou requêtes plus petites.

Pour en savoir plus sur la gestion des sessions et la lecture des données, consultez la présentation de l'API Storage Read.

Résoudre les problèmes liés aux insertions en flux continu

Les sections suivantes expliquent comment résoudre les erreurs qui se produisent lorsque vous diffusez des données en flux continu dans BigQuery à l'aide de l'API Storage Write (REST). Pour en savoir plus sur la résolution des erreurs de quota pour les insertions en flux continu, consultez la section Erreurs de quotas d'insertion en flux continu.

Codes de réponse HTTP d'échec

Si vous recevez un code de réponse HTTP d'échec, par exemple une erreur de réseau, il est impossible de savoir si l'insertion en flux continu a réussi. Si vous essayez simplement de renvoyer la requête, des lignes risquent d'apparaître en double dans votre table. Pour éviter les doublons dans la table, définissez la propriété insertId lorsque vous envoyez votre requête. BigQuery utilise la propriété insertId pour la déduplication.

Si vous recevez une erreur d'autorisation, une erreur de nom de table incorrect ou une erreur de quota dépassé, aucune ligne n'est insérée et l'ensemble de la requête échoue.

Codes de réponse HTTP de réussite

Même si vous recevez un code de réponse HTTP de réussite, vous devez examiner la propriété insertErrors de la réponse pour déterminer si les lignes ont bien été insérées, car il se peut que BigQuery n'ait réussi à insérer les lignes que partiellement. Vous pouvez rencontrer l'un des cas suivants :

Toutes les lignes ont bien été insérées : si la propriété insertErrors est une liste vide, toutes les lignes ont été insérées correctement.
Certaines lignes ont bien été insérées : sauf en cas d'incompatibilité de schémas dans l'une des lignes, les lignes ont été insérées correctement, sauf celles indiquées dans la propriété insertErrors. La propriété errors contient des informations détaillées sur la raison de l'échec de chaque ligne n'ayant pas été insérée. La propriété index indique l'index de ligne de base 0 de la requête à laquelle renvoie l'erreur.
Aucune ligne insérée : si BigQuery rencontre une incompatibilité de schéma sur certaines des lignes de la requête, aucune des lignes n'est insérée et une entrée insertErrors est renvoyée pour chaque ligne, même celles qui ne présentent pas une incompatibilité de schéma. Les lignes sans incompatibilité de schéma présentent une erreur lorsque la propriété reason est définie sur stopped, et vous pouvez les renvoyer telles quelles. Les lignes qui ont échoué incluent des informations détaillées sur l'incompatibilité du schéma. Pour en savoir plus sur les types de tampons de protocole compatibles avec chaque type de données BigQuery, consultez Types de données Arrow et de tampons de protocole compatibles.

Erreurs de métadonnées pour les insertions en flux continu

Étant donné que l'API BigQuery Streaming est conçue pour des taux d'insertion élevés, les modifications apportées aux métadonnées de la table sous-jacente sont cohérentes à terme lors de l'interaction avec le système de streaming. La plupart du temps, les modifications apportées aux métadonnées sont propagées en quelques minutes, mais pendant cette période, les réponses de l'API peuvent refléter l'état incohérent de la table.

Voici quelques exemples de scénarios :

Modifications du schéma : la modification du schéma d'une table qui a récemment reçu des insertions en flux continu peut entraîner des réponses avec des erreurs d'incompatibilité de schéma, car le système de flux continu peut ne pas détecter immédiatement la modification du schéma.
Création ou suppression de tables : le streaming vers une table inexistante renvoie une variante de la réponse notFound. Il est possible qu'une table créée en réponse ne soit pas immédiatement reconnue par les insertions de flux suivantes. De même, la suppression ou la recréation d'une table peut entraîner une période pendant laquelle les insertions de flux sont envoyées à l'ancienne table. Il est possible que les insertions de flux ne soient pas présentes dans la nouvelle table.
Troncation de table : la troncation des données d'une table (à l'aide d'un job de requête qui utilise une valeur writeDisposition de WRITE_TRUNCATE) peut également entraîner la suppression des insertions ultérieures pendant la période de cohérence.

Données manquantes ou non disponibles

Les insertions en flux continu résident temporairement dans le stockage optimisé en écriture, qui présente des caractéristiques de disponibilité différentes de celles du stockage géré. Certaines opérations dans BigQuery n'interagissent pas avec le stockage optimisé en écriture, comme les tâches de copie de table et les méthodes d'API telles que tabledata.list. De ce fait, les données de streaming récentes ne sont pas présentes dans la table ou la sortie de destination.

Erreurs de quota d'insertion en flux continu

Cette section fournit des conseils pour résoudre les erreurs de quota liées à la diffusion de données en flux continu dans BigQuery.

Dans certaines régions, les insertions en flux continu ont un quota plus élevé si vous ne remplissez pas le champ insertId pour chaque ligne. Pour en savoir plus sur les quotas d'insertion en flux continu, consultez la section Insertions en flux continu. Les erreurs liées aux quotas d'insertion en flux continu dans BigQuery dépendent de la présence ou de l'absence de insertId.

Message d'erreur

Si le champ insertId est vide, l'erreur de quota suivante est possible :

Limite de quota	Message d'erreur
Octets par seconde et par projet	Votre entité avec gaia_id : `GAIA_ID`, projet : `PROJECT_ID` dans la région : `REGION` a dépassé le quota d'insertion d'octets par seconde.

Si le champ insertId est renseigné, les erreurs de quota suivantes sont possibles :

Limite de quota	Message d'erreur
Lignes par seconde et par projet	Votre projet `PROJECT_ID` dans `REGION` a dépassé le quota d'insertion en flux continu de lignes par seconde.
Lignes par seconde et par table	Votre table `TABLE_ID` a dépassé le quota d'insertion en flux continu de lignes par seconde.
Octets par seconde et par table	Votre table `TABLE_ID` a dépassé le quota d'insertion en flux continu d'octets par seconde.

Le champ insertId permet de dédupliquer les lignes insérées. Si plusieurs insertions avec le même insertId arrivent dans un intervalle de quelques minutes, BigQuery écrit une seule version de l'enregistrement. Cependant, cette déduplication automatique n'est pas garantie. Pour un débit en flux continu maximal, nous vous recommandons de ne pas inclure insertId et d'utiliser plutôt la déduplication manuelle. Pour en savoir plus, consultez la section Assurer la cohérence des données.

Lorsque vous rencontrez cette erreur, diagnostiquez le problème, puis suivez les étapes recommandées pour le résoudre.

Diagnostic

Utilisez les vues STREAMING_TIMELINE_BY_* pour analyser le trafic en flux continu. Ces vues cumulent des statistiques de flux continu sur des intervalles d'une minute, regroupés par error_code. Les erreurs de quota s'affichent dans les résultats avec error_code égal à RATE_LIMIT_EXCEEDED ou QUOTA_EXCEEDED.

En fonction de la limite de quota spécifique qui a été atteinte, consultez total_rows ou total_input_bytes. Si l'erreur est un quota au niveau de la table, filtrez par table_id.

Par exemple, la requête suivante affiche le nombre total d'octets ingérés par minute et le nombre total d'erreurs de 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

Solution

Pour résoudre cette erreur de quota, procédez comme suit :

Si vous utilisez le champ insertId pour la déduplication et que votre projet se trouve dans une région compatible avec le quota d'insertion en flux continu le plus élevé, nous vous recommandons de supprimer le champ insertId. Cette solution peut nécessiter des étapes supplémentaires pour dédupliquer manuellement les données. Pour en savoir plus, consultez la section Supprimer manuellement les doublons.
Si vous n'utilisez pas insertId ou si vous ne pouvez pas le supprimer, surveillez le trafic en flux continu sur une période de 24 heures et analysez les erreurs de quota :
- Si vous constatez principalement des erreurs RATE_LIMIT_EXCEEDED plutôt que des erreurs QUOTA_EXCEEDED et que votre trafic global est inférieur à 80% du quota, les erreurs indiquent probablement des pics temporaires. Vous pouvez retenter l'opération en utilisant un intervalle exponentiel entre les tentatives pour résoudre ces erreurs.
- Si vous utilisez une tâche Dataflow pour insérer des données, pensez à utiliser des tâches de chargement plutôt que des insertions en flux continu. Pour en savoir plus, consultez la section Définir la méthode d'insertion. Si vous utilisez Dataflow avec un connecteur d'E/S personnalisé, envisagez plutôt d'utiliser un connecteur d'E/S intégré. Pour en savoir plus, consultez la section Modèles d'E/S personnalisés.
- Si vous voyez des erreurs QUOTA_EXCEEDED ou si le trafic global dépasse systématiquement 80 % du quota, envoyez une requête d'augmentation du quota. Pour en savoir plus, consultez Demander un ajustement de quota.
- Vous pouvez également envisager de remplacer les insertions en flux continu par la nouvelle API Storage Write, qui bénéficie d'un débit plus élevé, d'un prix plus faible et de nombreuses fonctionnalités utiles.