> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Connectez simplement votre stockage objet à ClickHouse Cloud.
# Intégrer Google Cloud Storage à ClickHouse Cloud
export const Image = ({img, alt, size}) => {
return
;
};
Le ClickPipe GCS offre une solution entièrement gérée et résiliente pour ingérer des données depuis Google Cloud Storage (GCS). Il prend en charge l’**ingestion ponctuelle** et l’**ingestion continue**, avec une sémantique d’exactly-once.
Les GCS ClickPipes peuvent être déployés et gérés manuellement via l’interface utilisateur de ClickPipes, ainsi que de façon programmatique à l’aide d’[OpenAPI](/fr/integrations/clickpipes/programmatic-access/openapi) et de [Terraform](/fr/integrations/clickpipes/programmatic-access/terraform).
## Formats pris en charge
* [JSON](/fr/reference/formats/JSON/JSON)
* [CSV](/fr/reference/formats/CSV/CSV)
* [TSV](/fr/reference/formats/TabSeparated/TabSeparated)
* [Parquet](/fr/reference/formats/Parquet/Parquet)
* [Avro](/fr/reference/formats/Avro/Avro)
## Fonctionnalités
### Ingestion ponctuelle
Par défaut, le ClickPipe GCS charge en un seul lot tous les fichiers du bucket spécifié qui correspondent à un motif dans la table de destination ClickHouse. Une fois la tâche d’ingestion terminée, le ClickPipe s’arrête automatiquement. Ce mode d’ingestion ponctuelle offre une sémantique d’exactly-once, assurant que chaque fichier est traité de manière fiable, sans doublons.
### Ingestion continue
Lorsque l’ingestion continue est activée, ClickPipes ingère en continu les données depuis le chemin spécifié. Pour déterminer l’ordre d’ingestion, le ClickPipe GCS s’appuie par défaut sur l’[ordre lexicographique](#continuous-ingestion-lexicographical-order) implicite des fichiers. Il peut également être configuré pour ingérer les fichiers dans [n’importe quel ordre](#continuous-ingestion-any-order) à l’aide d’un abonnement [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) [configuré pour envoyer des notifications pour le bucket](https://docs.cloud.google.com/storage/docs/reporting-changes#command-line).
#### Ordre lexicographique
Le ClickPipe GCS suppose que les fichiers sont ajoutés à un bucket dans l’ordre lexicographique et s’appuie sur cet ordre implicite pour ingérer les fichiers séquentiellement. Cela signifie que tout nouveau fichier **doit** être lexicographiquement supérieur au dernier fichier ingéré. Par exemple, des fichiers nommés `file1`, `file2` et `file3` seront ingérés séquentiellement, mais si un nouveau `file 0` est ajouté au bucket, il sera **ignoré**, car son nom n’est pas lexicographiquement supérieur à celui du dernier fichier ingéré.
Dans ce mode, le ClickPipe GCS effectue un chargement initial de **tous les fichiers** dans le chemin spécifié, puis recherche de nouveaux fichiers à intervalles configurables (30 secondes par défaut). Il est **impossible** de démarrer l’ingestion à partir d’un fichier spécifique ou d’un moment précis — ClickPipes chargera toujours tous les fichiers du chemin spécifié.
#### Dans n’importe quel ordre
Consultez [Configurer le mode non ordonné pour l’ingestion continue](/fr/integrations/clickpipes/object-storage/google-cloud-storage/unordered-mode) pour obtenir des instructions étape par étape.
Il est possible de configurer un ClickPipe GCS pour ingérer des fichiers qui n’ont pas d’ordre implicite en configurant un abonnement [Google Cloud Pub/Sub](https://docs.cloud.google.com/storage/docs/pubsub-notifications) qui reçoit les notifications du bucket. Cela permet à ClickPipes d’écouter les événements de création d’objets et d’ingérer tout nouveau fichier, quelle que soit la convention de nommage utilisée.
Le mode non ordonné n’est **pas** pris en charge pour les buckets publics. Il nécessite une authentification par **compte de service** ainsi qu’un abonnement [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) connecté au bucket.
Dans ce mode, le ClickPipe GCS effectue un chargement initial de **tous les fichiers** du chemin sélectionné, puis écoute les notifications `OBJECT_FINALIZE` via l’abonnement Pub/Sub correspondant au chemin spécifié. Tout message concernant un fichier déjà traité, un fichier ne correspondant pas au chemin ou un événement d’un autre type sera **ignoré**. Il est **impossible** de démarrer l’ingestion à partir d’un fichier précis ou d’un moment donné : ClickPipes chargera toujours tous les fichiers du chemin sélectionné.
### Correspondance des motifs de fichiers
Les Object Storage ClickPipes suivent la norme POSIX pour la correspondance des motifs de fichiers. Tous les motifs sont **sensibles à la casse** et s’appliquent au **chemin complet** après le nom du bucket. Pour de meilleures performances, utilisez le motif le plus spécifique possible (par exemple, `data-2024-*.csv` plutôt que `*.csv`).
#### Motifs pris en charge
| Motif | Description | Exemple | Correspondances |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------- |
| `?` | Correspond à exactement **un** caractère (hors `/`) | `data-?.csv` | `data-1.csv`, `data-a.csv`, `data-x.csv` |
| `*` | Correspond à **zéro, un ou plusieurs** caractères (hors `/`) | `data-*.csv` | `data-1.csv`, `data-001.csv`, `data-report.csv`, `data-.csv` |
| `**`
Récursif | Correspond à **zéro, un ou plusieurs** caractères (y compris `/`). Permet de parcourir les répertoires de manière récursive. | `logs/**/error.log` | `logs/error.log`, `logs/2024/error.log`, `logs/2024/01/error.log` |
**Exemples :**
* `https://bucket.s3.amazonaws.com/folder/*.csv`
* `https://bucket.s3.amazonaws.com/logs/**/data.json`
* `https://bucket.s3.amazonaws.com/file-?.parquet`
* `https://bucket.s3.amazonaws.com/data-2024-*.csv.gz`
#### Motifs non pris en charge
| Motif | Description | Exemple | Alternatives |
| ----------- | ------------------------------------ | ---------------------- | -------------------------------------------------- |
| `{abc,def}` | Expansion d'accolades (alternatives) | `{logs,data}/file.csv` | Créez des ClickPipes distincts pour chaque chemin. |
| `{N..M}` | Expansion de plage numérique | `file-{1..100}.csv` | Utilisez `file-*.csv` ou `file-?.csv`. |
**Exemples :**
* `https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json`
* `https://bucket.s3.amazonaws.com/file-{1..100}.csv`
* `https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet`
### Sémantique d’« exactly-once »
Différents types de défaillances peuvent se produire lors de l’ingestion de grands jeux de données, ce qui peut entraîner des insertions partielles ou des doublons. Les Object Storage ClickPipes sont robustes face aux échecs d’insertion et offrent une sémantique d’« exactly-once ». Cela est rendu possible grâce à l’utilisation de tables de « staging » temporaires. Les données sont d’abord insérées dans les tables de staging. Si un problème survient pendant cette insertion, la table de staging peut être tronquée et l’insertion peut être relancée depuis un état propre. Ce n’est que lorsqu’une insertion est terminée avec succès que les partitions de la table de staging sont déplacées vers la table cible. Pour en savoir plus sur cette stratégie, consultez [cet article de blog](https://clickhouse.com/blog/supercharge-your-clickhouse-data-loads-part3).
### Colonnes virtuelles
Pour suivre les fichiers qui ont été ingérés, incluez la colonne virtuelle `_file` dans la liste de mappage des colonnes. La colonne virtuelle `_file` contient le nom de fichier de l’objet source, ce qui permet de savoir quels fichiers ont été traités.
## Contrôle d’accès
### Autorisations
Le ClickPipe GCS prend en charge les buckets publics et privés. Les buckets [Requester Pays](https://docs.cloud.google.com/storage/docs/requester-pays) ne sont **pas** pris en charge.
#### GCS bucket
Le compte de service utilisé par ClickPipes doit disposer des autorisations suivantes au niveau du bucket :
* [`roles/storage.objectViewer`](https://docs.cloud.google.com/storage/docs/access-control/iam-roles#storage.objectViewer)
Ce rôle inclut les autorisations IAM [`storage.objects.list`](https://docs.cloud.google.com/storage/docs/json_api/v1/objects/list) et [\`storage.objects.get](https://docs.cloud.google.com/storage/docs/json_api/v1/objects/get#required-permissions), qui permettent à ClickPipes de répertorier et de récupérer les objets dans le bucket spécifié.
#### Abonnement Pub/Sub
Lors de l’utilisation du [mode non ordonné](#continuous-ingestion-any-order), le compte de service doit disposer des rôles suivants pour l’abonnement Pub/Sub :
* [`roles/pubsub.subscriber`](https://cloud.google.com/pubsub/docs/access-control#roles) — pour recevoir les messages et en accuser réception.
* [`roles/pubsub.viewer`](https://cloud.google.com/pubsub/docs/access-control#roles) — pour obtenir les métadonnées de l’abonnement.
### Authentification
#### Compte de service
L’authentification via un compte de service est requise lors de l’utilisation du [mode non ordonné](#continuous-ingestion-any-order) avec les notifications Pub/Sub. Sélectionnez **Service Account** comme méthode d’authentification, puis téléversez le fichier JSON de la clé du compte de service.
#### Identifiants HMAC
Pour utiliser des [clés HMAC](https://docs.cloud.google.com/storage/docs/authentication/hmackeys) pour vous authentifier, sélectionnez `Credentials` sous **Méthode d’authentification** lors de la configuration de votre connexion ClickPipe. Renseignez ensuite la clé d’accès (par exemple, `GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA`) et la clé secrète (par exemple, `bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ`) dans `Access key` et `Secret key`, respectivement.
Suivez [ce guide](/fr/integrations/connectors/data-sources/gcs#create-a-service-account-hmac-key-and-secret) pour créer un compte de service avec une clé HMAC.
### Accès réseau
Les ClickPipes GCS utilisent deux chemins réseau distincts pour la découverte des métadonnées et l’ingestion des données : le service ClickPipes et le service ClickHouse Cloud, respectivement. Si vous souhaitez ajouter une couche supplémentaire de sécurité réseau (par exemple, pour des raisons de conformité), l’accès réseau **doit être configuré pour ces deux chemins**.
* Pour le **contrôle d’accès par adresse IP**, les [règles de filtrage IP](https://docs.cloud.google.com/storage/docs/ip-filtering-overview) de votre bucket GCS doivent autoriser les IP statiques de la région du service ClickPipes indiquées [ici](/fr/integrations/clickpipes/home#list-of-static-ips), ainsi que les [IP statiques](/fr/products/cloud/guides/data-sources/cloud-endpoints-api) du service ClickHouse Cloud. Pour obtenir les IP statiques de votre région ClickHouse Cloud, ouvrez un terminal et exécutez :
```bash theme={null}
# Remplacez par votre région ClickHouse Cloud
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.gcp[] | select(.region == "") | .egress_ips[]'
```
## Paramètres avancés
ClickPipes propose des valeurs par défaut adaptées à la plupart des cas d’utilisation. Si votre cas d’utilisation nécessite un réglage plus fin, vous pouvez ajuster les paramètres suivants :
| Paramètre | Valeur par défaut | Description |
| ------------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Max insert bytes` | 10GB | Nombre d’octets à traiter dans un seul lot d’insertion. |
| `Max file count` | 100 | Nombre maximal de fichiers à traiter dans un seul lot d’insertion. |
| `Max threads` | auto(3) | [Nombre maximal de threads concurrents](/fr/reference/settings/session-settings#max_threads) pour le traitement des fichiers. |
| `Max insert threads` | 1 | [Nombre maximal de threads d’insertion concurrents](/fr/reference/settings/session-settings#max_insert_threads) pour le traitement des fichiers. |
| `Min insert block size bytes` | 1GB | [Taille minimale en octets du bloc](/fr/reference/settings/session-settings#min_insert_block_size_bytes) pouvant être inséré dans une table. |
| `Max download threads` | 4 | [Nombre maximal de threads de téléchargement concurrents](/fr/reference/settings/session-settings#max_download_threads). |
| `Object storage polling interval` | 30s | Configure le délai d’attente maximal avant l’insertion des données dans le cluster ClickHouse. |
| `Parallel distributed insert select` | 2 | [Paramètre parallel distributed insert select](/fr/reference/settings/session-settings#parallel_distributed_insert_select). |
| `Parallel view processing` | false | Indique s’il faut activer l’envoi vers les vues attachées [de manière concurrente plutôt que séquentielle](/fr/reference/settings/session-settings#parallel_view_processing). |
| `Use cluster function` | true | Indique s’il faut traiter les fichiers en parallèle sur plusieurs nœuds. |
### Mise à l'échelle
La mise à l'échelle des Object Storage ClickPipes repose sur la taille minimale du service ClickHouse, déterminée par les [paramètres d'autoscaling vertical configurés](/fr/products/cloud/features/autoscaling/vertical#configuring-vertical-auto-scaling). La taille du ClickPipe est définie au moment de la création du pipe. Les modifications ultérieures des paramètres du service ClickHouse n'affecteront pas la taille du ClickPipe.
Pour augmenter le débit des jobs d'ingestion volumineux, nous recommandons de mettre à l'échelle le service ClickHouse avant de créer le ClickPipe.
## Limitations connues
### Taille du fichier
ClickPipes n’essaiera d’ingérer que des objets d’une taille **inférieure ou égale à 10 Go**. Si un fichier dépasse 10 Go, une erreur sera ajoutée à la table d’erreurs dédiée de ClickPipes.
### Compatibilité
Le ClickPipe GCS s’appuie sur l’[API XML](https://docs.cloud.google.com/storage/docs/interoperability) de Cloud Storage pour l’interopérabilité, ce qui impose d’utiliser le préfixe de bucket `https://storage.googleapis.com/` (au lieu de `gs://`) ainsi que des [clés HMAC](https://docs.cloud.google.com/storage/docs/authentication/hmackeys) pour l’authentification.
### Prise en charge des vues
Les vues matérialisées sur la table cible sont également prises en charge. ClickPipes créera des tables de staging non seulement pour la table cible, mais aussi pour toute vue matérialisée dont elle dépend.
Nous ne créons pas de tables de staging pour les vues non matérialisées. Cela signifie que si vous avez une table cible avec une ou plusieurs vues matérialisées en aval, ces vues matérialisées doivent éviter de sélectionner des données via une vue à partir de la table cible. Sinon, il peut manquer des données dans la vue matérialisée.