Créer des abonnements Cloud Storage

Ce document explique comment créer un abonnement Cloud Storage. Vous pouvez utiliser la console Google Cloud , Google Cloud CLI, la bibliothèque cliente ou l'API Pub/Sub pour créer un abonnement Cloud Storage.

Avant de commencer

Avant de lire ce document, assurez-vous de connaître les éléments suivants :

• Fonctionnement d'un abonnement Cloud Storage
• Comment fonctionne Cloud Storage et comment créer et gérer des buckets Cloud Storage.
• Comment configurer un sujet de lettres mortes pour gérer les échecs de messages.

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour créer un abonnement Cloud Storage, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Pub/Sub (roles/pubsub.editor) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour créer un abonnement Cloud Storage. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer un abonnement Cloud Storage :

• pubsub.subscriptions.create sur le projet
• pubsub.topics.attachSubscription sur le sujet

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Abonnements multiprojets

Si vous créez un abonnement dans un projet pour un sujet dans un autre projet, vous devez disposer de l'autorisation pubsub.subscriptions.create sur le projet dans lequel vous créez l'abonnement et de l'autorisation pubsub.topics.attachSubscription sur le sujet.

Attribuer des rôles IAM au compte de service

Pub/Sub utilise un compte de service Identity and Access Management (IAM) pour accéder aux ressources Google Cloud . Par défaut, il utilise l'agent de service Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com).

Pour permettre à Pub/Sub d'écrire dans Cloud Storage, le compte de service a besoin des rôles suivants :

• Créateur d'objets Storage (roles/storage.objectCreator)
• Lecteur des anciens buckets de l'espace de stockage (roles/storage.legacyBucketReader)

Vous pouvez accorder des autorisations au compte de service pour le projet ou le bucket Cloud Storage, comme suit :

Utiliser un compte de service personnalisé

En attribuant les rôles Créateur d'objets Storage et Lecteur de buckets Storage anciens au compte de service Cloud Pub/Sub, tout utilisateur autorisé à créer un abonnement dans votre projet peut écrire dans le bucket Cloud Storage. Si vous souhaitez accorder des autorisations plus précises, configurez plutôt un compte de service géré par l'utilisateur.

Les autorisations suivantes sont requises pour configurer un compte de service géré par l'utilisateur afin d'écrire dans Cloud Storage :

• Le compte de service géré par l'utilisateur doit disposer des rôles Créateur d'objets Storage et Lecteur de buckets Storage Legacy.

• Le compte de service Cloud Pub/Sub doit disposer de l'autorisation iam.serviceAccounts.getAccessToken sur le compte de service géré par l'utilisateur.

• L'utilisateur qui crée l'abonnement doit disposer de l'autorisation iam.serviceAccounts.actAs sur le compte de service géré par l'utilisateur.

Lorsque vous créez l'abonnement, spécifiez le compte de service géré par l'utilisateur comme compte de service de l'abonnement.

Propriétés des abonnements Cloud Storage

Les abonnements Cloud Storage sont compatibles avec toutes les propriétés d'abonnement courantes. Les sections suivantes décrivent les propriétés spécifiques aux abonnements Cloud Storage.

Nom du bucket

Un bucket Cloud Storage doit déjà exister avant de créer un abonnement Cloud Storage.

Les messages sont envoyés par lots et stockés dans le bucket Cloud Storage. Un seul lot ou fichier est stocké en tant qu'objet dans le bucket.

Le bucket Cloud Storage doit avoir l'option Paiements du demandeur désactivée.

Pour créer un bucket Cloud Storage, consultez Créer des buckets.

Préfixe, suffixe et date/heure du nom de fichier

Les fichiers Cloud Storage générés par l'abonnement Cloud Storage sont stockés en tant qu'objets dans le bucket Cloud Storage. Le nom de l'objet stocké dans le bucket Cloud Storage est au format suivant : <file-prefix><UTC-date-time>_<uuid><file-suffix>.

La liste suivante inclut des informations sur le format de fichier et les champs que vous pouvez personnaliser :

• <file-prefix> est le préfixe de nom de fichier personnalisé. Ce champ est facultatif.

• <UTC-date-time> est une chaîne générée automatiquement et personnalisable en fonction de l'heure de création de l'objet.

• <uuid> est une chaîne aléatoire générée automatiquement pour l'objet.

• <file-suffix> est le suffixe personnalisé du nom de fichier. Ce champ est facultatif. Le suffixe du nom de fichier ne peut pas se terminer par "/".

• Vous pouvez modifier le préfixe et le suffixe du nom de fichier :

  • Par exemple, si la valeur du préfixe du nom de fichier est prod_ et que la valeur du suffixe du nom de fichier est _archive, un exemple de nom d'objet est prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • Si vous ne spécifiez pas le préfixe et le suffixe du nom de fichier, le nom de l'objet stocké dans le bucket Cloud Storage est au format suivant : <UTC-date-time>_<uuid>.

  • Les exigences de dénomination des objets Cloud Storage s'appliquent également au préfixe et au suffixe du nom de fichier. Pour en savoir plus, consultez À propos des objets Cloud Storage.

• Vous pouvez modifier la façon dont la date et l'heure s'affichent dans le nom du fichier :

  • Les comparateurs de date et heure obligatoires que vous ne pouvez utiliser qu'une seule fois : année (YYYY ou YY), mois (MM), jour (DD), heure (hh), minute (mm), seconde (ss). Par exemple, YY-YYYY ou MMM ne sont pas valides.

  • Les comparateurs facultatifs que vous ne pouvez utiliser qu'une seule fois : séparateur de date et heure (T) et décalage horaire (Z ou +00:00).

  • Éléments facultatifs que vous pouvez utiliser plusieurs fois : trait d'union (-), trait de soulignement (_), deux-points (:) et barre oblique (/).

  • Par exemple, si la valeur du format de date et heure du nom de fichier est YYYY-MM-DD/hh_mm_ssZ, un exemple de nom d'objet est prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Si le format de date et d'heure du nom de fichier se termine par un caractère qui n'est pas un élément de correspondance, ce caractère remplacera le séparateur entre <UTC-date-time> et <uuid>. Par exemple, si la valeur du format de date et heure du nom de fichier est YYYY-MM-DDThh_mm_ss-, un exemple de nom d'objet est prod_2023-09-25T04_10_00-uNiQuE_archive.

Traitement des fichiers par lot

Les abonnements Cloud Storage vous permettent de décider quand vous souhaitez créer un fichier de sortie stocké en tant qu'objet dans le bucket Cloud Storage. Pub/Sub écrit un fichier de sortie lorsque l'une des conditions de traitement par lot spécifiées est remplie. Voici les conditions de traitement par lot de Cloud Storage :

• Durée maximale des lots de stockage. Ce paramètre est obligatoire. Pub/Sub écrit un nouveau fichier de sortie si la valeur spécifiée pour la durée maximale est dépassée. La durée est mesurée à partir du moment où Pub/Sub commence à écrire dans un nouveau fichier jusqu'à ce que le fichier soit finalisé. Par exemple, si vous définissez la durée maximale sur cinq minutes, Pub/Sub finalise le fichier au plus cinq minutes après avoir commencé à y écrire. Un nouveau fichier peut être créé avant l'expiration de la durée maximale. Si vous ne spécifiez pas de valeur, la valeur par défaut de cinq minutes est appliquée. Voici les valeurs applicables pour la durée maximale :

  • Valeur minimale : 1 minute
  • Valeur par défaut : 5 minutes
  • Valeur maximale : 10 minutes

• Nombre maximal d'octets par lot pour le stockage. Il s'agit d'un paramètre facultatif. L'abonnement Cloud Storage écrit un nouveau fichier de sortie si la valeur maximale d'octets spécifiée est dépassée. Voici les valeurs applicables pour le nombre maximal d'octets :

  • Valeur minimale : 1 Ko
  • Valeur maximale : 10 Gio

• Nombre maximal de messages par lot de stockage Il s'agit d'un paramètre facultatif. L'abonnement Cloud Storage écrit un nouveau fichier de sortie si le nombre maximal de messages spécifié est dépassé. Voici les valeurs applicables pour le nombre maximal de messages :

  • Valeur minimale = 1 000

Par exemple, vous pouvez configurer une durée maximale de 6 minutes et une taille maximale de 2 Go. Si, à la quatrième minute, le fichier de sortie atteint une taille de 2 Go, Pub/Sub finalise le fichier précédent et commence à écrire dans un nouveau fichier.

Un abonnement Cloud Storage peut écrire simultanément dans plusieurs fichiers d'un bucket Cloud Storage. Si vous avez configuré votre abonnement pour créer un fichier toutes les six minutes, vous pouvez observer la création de plusieurs fichiers Cloud Storage toutes les six minutes.

Dans certains cas, Pub/Sub peut commencer à écrire dans un nouveau fichier avant l'heure configurée par les conditions de regroupement des fichiers. Un fichier peut également dépasser la valeur "Nombre maximal d'octets" si l'abonnement reçoit des messages dont la taille est supérieure à cette valeur.

Format de fichier

Lorsque vous créez un abonnement Cloud Storage, vous pouvez spécifier le format des fichiers de sortie à stocker dans un bucket Cloud Storage (Texte ou Avro).

• Texte : les messages sont stockés en texte brut. Un caractère de nouvelle ligne sépare un message du message précédent dans le fichier. Seules les charges utiles des messages sont stockées, et non les attributs ni les autres métadonnées.

• Avro : les messages sont stockés au format binaire Apache Avro. Lorsque vous sélectionnez Avro, vous pouvez activer les propriétés supplémentaires suivantes :

  • Écrire les métadonnées : cette option vous permet de stocker les métadonnées du message avec le message. Les métadonnées telles que les champs subscription_name, message_id, publish_time et attributes sont écrites dans les champs de premier niveau de l'objet Avro de sortie, tandis que toutes les autres propriétés du message autres que les données (par exemple, une clé ordering_key, le cas échéant) sont ajoutées en tant qu'entrées dans la carte attributes.

    Si l'option Écrire les métadonnées est désactivée, seule la charge utile du message est écrite dans l'objet Avro de sortie. Voici le schéma Avro pour les messages de sortie avec l'option Écrire des métadonnées désactivée :