Ce document explique comment créer un abonnement Cloud Storage. Vous pouvez créer un abonnement Cloud Storage à l'aide de la console Google Cloud, de la Google Cloud CLI, de la bibliothèque cliente ou de l'API Pub/Sub.
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 les buckets Cloud Storage.
- Comment configurer une lettre morte pour gérer les échecs de messages.
Rôles et autorisations requis
Voici une liste de consignes concernant les rôles et les autorisations:
Pour créer un abonnement, vous devez configurer le contrôle des accès au niveau du projet.
Vous avez également besoin d'autorisations au niveau des ressources si vos abonnements et vos sujets se trouvent dans différents projets, comme indiqué plus loin dans cette section.
Pour créer un abonnement Cloud Storage, Le compte de service Pub/Sub doit être autorisé à écrire dans le un bucket Cloud Storage spécifique et lire ses métadonnées. Pour en savoir plus sur l'attribution de ces autorisations, consultez la section suivante de ce document.
Pour obtenir les autorisations nécessaires pour créer des abonnements 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 la page 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 des abonnements 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 des abonnements Cloud Storage:
-
Créez un abonnement:
pubsub.subscriptions.create
-
Joindre un abonnement à un sujet :
pubsub.topics.attachSubscription
-
Extraire à partir d'un abonnement :
pubsub.subscriptions.consume
-
Obtenir un abonnement :
pubsub.subscriptions.get
-
Lister un abonnement :
pubsub.subscriptions.list
-
Modifier un abonnement :
pubsub.subscriptions.update
-
Supprimer un abonnement :
pubsub.subscriptions.delete
-
Obtenez la stratégie IAM d'un abonnement:
pubsub.subscriptions.getIamPolicy
-
Configurez la stratégie IAM pour un abonnement :
pubsub.subscriptions.setIamPolicy
Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Si vous devez créer des abonnements Cloud Storage dans un projet associés à un sujet dans un autre projet, demandez à l'administrateur du sujet de vous accorder également le rôle IAM (roles/pubsub.editor)
Éditeur Pub/Sub sur le sujet.
Attribuer des rôles Cloud Storage au compte de service Pub/Sub
Certains services Google Cloud disposent de comptes de service gérés par Google Cloud qui leur permettent d'accéder à vos ressources. Ces comptes de service sont appelés
les agents de service. Pub/Sub crée et gère un compte de service pour chaque projet au format service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
.
Pour créer un abonnement Cloud Storage, le compte de service Pub/Sub doit être autorisé à écrire dans le bucket Cloud Storage spécifique et à lire ses métadonnées. Choisir l'une des procédures suivantes:
Accordez des autorisations au niveau du bucket. Sur le bucket Cloud Storage spécifique, attribuez le rôle Créateur d'objets Storage (
roles/storage.objectCreator
) et le rôle Lecteur des anciens buckets Storage (roles/storage.legacyBucketReader
) au compte de service Pub/Sub.Si vous devez attribuer des rôles au niveau du projet, vous pouvez attribuer le rôle "Administrateur de l'espace de stockage" (
roles/storage.admin
) au projet contenant le bucket Cloud Storage. Attribuez ce rôle au compte de service Pub/Sub.
Autorisations relatives aux buckets
Suivez les étapes ci-dessous pour accorder les rôles Créateur d'objets Storage (roles/storage.objectCreator
) et Lecteur des anciens ensembles de l'espace de stockage (roles/storage.legacyBucketReader
) au niveau du bucket :
Dans la console Google Cloud, accédez à la page Cloud Storage.
Cliquez sur le bucket Cloud Storage dans lequel vous souhaitez écrire des messages.
La page Informations sur le bucket s'ouvre.
Sur la page Informations sur le bucket, cliquez sur l'onglet Autorisations.
Dans l'onglet Autorisations > Afficher par compte principal, cliquez sur Accorder l'accès.
La page Accorder l'accès s'affiche.
Dans la section Ajouter des comptes principaux, saisissez le nom de votre compte de service Pub/Sub.
Le format du compte de service est
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
Par exemple, pour un projet avec PROJECT_NUMBER=112233445566
, le compte de service est au formatservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
Dans le menu déroulant Attribuer des rôles > Sélectionner un rôle, saisissez
Creator
, puis sélectionnez le rôle Créateur d'objets Storage.Cliquez sur Ajouter un autre rôle.
Dans la liste déroulante Sélectionner un rôle, saisissez
Bucket Reader
, puis sélectionnez le rôle Storage Legacy Bucket Reader (Lecteur de bucket ancien Storage).Cliquez sur Enregistrer.
Autorisations liées au projet
Procédez comme suit pour accorder à l'administrateur de l'espace de stockage
(roles/storage.admin
) au niveau du projet:
Dans la console Google Cloud, accédez à la page IAM.
Dans Autorisations > Dans l'onglet Afficher par compte principal, cliquez sur Accorder l'accès.
La page Accorder l'accès s'affiche.
Dans la section Ajouter des comptes principaux, saisissez le nom de votre de service géré.
Le format du compte de service est
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
. Par exemple, pour un projet avec PROJECT_NUMBER=112233445566
, le compte de service est au formatservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
Dans la section Attribuer des rôles > dans la liste déroulante Sélectionnez un rôle, Saisissez
Storage Admin
et sélectionnez le rôle Administrateur Storage.Cliquez sur Enregistrer.
Pour en savoir plus sur l'IAM Cloud Storage, consultez la page Gestion de l'authentification et des accès Cloud Storage.
Propriétés des abonnements Cloud Storage
Lorsque vous configurez un abonnement Cloud Storage, vous devez spécifier les propriétés communes à tous les types d'abonnements et certaines Propriétés spécifiques aux abonnements Cloud Storage.
Propriétés d'abonnement courantes
En savoir plus sur les propriétés d'abonnement courantes que vous pouvez définir pour tous les abonnements.
Nom du bucket
Pour que vous puissiez créer un bucket Cloud Storage, Abonnement Cloud Storage.
Les messages sont envoyés sous forme de lots et stockés dans le bucket Cloud Storage. Un seul lot ou fichier est stocké en tant qu'objet. dans le bucket.
L'option Pays du demandeur doit être désactivée pour le bucket Cloud Storage.
Pour créer un bucket Cloud Storage, consultez la page Créer des buckets.
Préfixe, suffixe et date/heure du nom de fichier
Les fichiers Cloud Storage de sortie générés par l'API 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 du nom de fichier personnalisé. Ce champ est facultatif.<UTC-date-time>
est une chaîne personnalisable générée automatiquement 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 doit 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 de le suffixe du nom de fichier est_archive
, un exemple de nom d'objet estprod_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 :
<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 la section À propos des objets Cloud Storage.
Vous pouvez modifier l'affichage de la date et de l'heure dans le nom du fichier:
Correspondances de date/heure obligatoires que vous ne pouvez utiliser qu'une seule fois : année (
YYYY
ouYY
), mois (MM
), jour (DD
), heure (hh
), minute (mm
), seconde (ss
). Par exemple,YY-YYYY
ouMMM
n'est pas valide.Outils de mise en correspondance facultatifs que vous ne pouvez utiliser qu'une seule fois: séparateur de la date et de l'heure (
T
) et et le décalage horaire (Z
ou+00:00
).Éléments facultatifs que vous pouvez utiliser plusieurs fois: tiret (
-
), Trait de soulignement (_
), deux-points (:
) et barre oblique (/
).Par exemple, si la valeur du format de date et d'heure du nom de fichier est
YYYY-MM-DD/hh_mm_ssZ
, un exemple de nom d'objet estprod_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 opérateur de correspondance, ce caractère remplace le séparateur entre
<UTC-date-time>
et<uuid>
. Par exemple, si la valeur du format de date et d'heure du nom de fichier estYYYY-MM-DDThh_mm_ss-
, un exemple de nom d'objet estprod_2023-09-25T04_10_00-uNiQuE_archive
.
Traitement des fichiers par lot
Les abonnements Cloud Storage vous permettent de décider quand créer un nouveau fichier de sortie stocké en tant qu'objet dans le bucket. Pub/Sub écrit un fichier de sortie lorsqu'une des conditions de traitement par lot spécifiées est remplie. Voici les conditions de traitement par lot Cloud Storage :
Durée maximale des lots de stockage Ce paramètre est obligatoire. La L'abonnement Cloud Storage écrit un nouveau fichier de sortie si la valeur spécifiée pour la durée maximale est dépassée. Si vous ne spécifiez la valeur, une valeur par défaut de 5 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 de stockage Ce paramètre est facultatif. La L'abonnement Cloud Storage écrit un nouveau fichier de sortie si le la valeur spécifiée pour le nombre maximal d'octets est dépassée. Voici les valeurs applicables pour les octets max :
- Valeur minimale = 1 Ko
- Valeur maximale = 10 Go
Nombre maximal de messages par lot pour le stockage. Ce paramètre est facultatif. La L'abonnement Cloud Storage écrit un nouveau fichier de sortie si le le nombre maximal de messages spécifié est dépassé. Vous trouverez ci-dessous les valeurs pour le nombre maximal de messages:
- Valeur minimale = 1 000
Par exemple, vous pouvez configurer la durée maximale sur 6 minutes et la taille maximale en octets sur 2 Go. Si, à la 4e 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 pour créer un fichier toutes les six minutes, vous pouvez constater de plusieurs fichiers Cloud Storage créés toutes les 6 minutes.
Dans certains cas, Pub/Sub peut commencer à écrire dans un nouveau plus tôt que l'heure configurée par les conditions de traitement par lot des fichiers. Un fichier peut également dépasser la valeur "Max. octets" si l'abonnement reçoit des messages plus volumineux que 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 en tant que Text 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 Format binaire Apache Avro. Lorsque vous sélectionnez Avro, vous pouvez activer les propriétés supplémentaires suivantes :
Écrire des 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
etattributes
sont écrites dans les champs de niveau supérieur de l'objet Avro de sortie, tandis que toutes les autres propriétés de message autres que les données (par exemple, une clé de tri, le cas échéant) sont ajoutées en tant qu'entrées dans la mappeattributes
.Si l'option write metadata (é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 lorsque l'option write metadata (écriture de métadonnées) est désactivée:
{ "type": "record", "namespace": "com.google.pubsub", "name": "PubsubMessage", "fields": [ { "name": "data", "type": "bytes" } ] }
Voici le schéma Avro pour les messages de sortie avec les métadonnées d'écriture activées:
{ "type": "record", "namespace": "com.google.pubsub", "name": "PubsubMessageWithMetadata", "fields": [ { "name": "subscription_name", "type": "string" }, { "name": "message_id", "type": "string" }, { "name": "publish_time", "type": { "type": "long", "logicalType": "timestamp-micros" } }, { "name": "attributes", "type": { "type": "map", "values": "string" } }, { "name": "data", "type": "bytes" } ] }
Utiliser un schéma avec sujet: cette option permet à Pub/Sub d'utiliser le schéma du sujet Pub/Sub auquel l'abonnement est associé lors de l'écriture de fichiers Avro.
Lorsque vous utilisez cette option, n'oubliez pas de vérifier les exigences supplémentaires suivantes :
Le schéma du sujet doit être au format Apache Avro.
Si l'option Utiliser le schéma du sujet et l'écriture des métadonnées sont activées, le schéma du sujet doit comporter un objet Record à sa racine. Pub/Sub développe la liste des champs de l'enregistrement pour inclure les champs de métadonnées. Par conséquent, l'enregistrement ne peut contenir aucun champ portant le même nom que les champs de métadonnées (
subscription_name
,message_id
,publish_time
ouattributes
).
Créer un abonnement Cloud Storage
Console
-
Dans la console Google Cloud, accédez à la page Abonnements.
-
Cliquez sur Créer un abonnement.
-
Dans le champ ID d'abonnement, saisissez un nom.
Pour savoir comment nommer un abonnement, consultez la section Consignes de dénomination d'un sujet ou d'un abonnement.
-
Choisissez ou créez un sujet dans le menu déroulant.
L'abonnement reçoit les messages du sujet.
Pour savoir comment créer un sujet, consultez la section Créer et gérer des sujets.
-
Dans le champ Type de diffusion, sélectionnez Écrire dans Cloud Storage.
-
Pour le bucket Cloud Storage, cliquez sur Parcourir.
-
Vous pouvez sélectionner un bucket existant dans n'importe quel projet approprié.
-
Vous pouvez également cliquer sur l'icône Créer et suivre les instructions à l'écran pour créer un bucket.
Une fois le bucket créé, sélectionnez-le pour l'abonnement Cloud Storage.
Pour en savoir plus sur la création d'un bucket, consultez la page Créer des buckets.
Lorsque vous spécifiez le bucket, Pub/Sub vérifie les autorisations appropriées sur le bucket de service géré. En cas de problèmes d'autorisation, un message semblable à ceci:
Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions
. -
-
En cas de problème d'autorisation, cliquez sur Définir l'autorisation et suivez les instructions à l'écran.
Vous pouvez également suivre les instructions de la section Attribuer des rôles Cloud Storage au compte de service Pub/Sub.
-
Dans le champ Format de fichier, sélectionnez Texte ou Avro
Si vous sélectionnez Avro, vous pouvez également spécifier vous souhaitez stocker les métadonnées du message dans la sortie.
Pour en savoir plus sur les deux options, y compris l'option de métadonnées de message pour le format Avro, consultez la section Format de fichier.
-
Facultatif : vous pouvez spécifier le préfixe, le suffixe et la date et l'heure du nom de fichier pour tous les fichiers à écrire dans le bucket Cloud Storage. Un fichier est stocké en tant qu'objet dans le bucket.
Pour en savoir plus sur la configuration du préfixe, du suffixe et de la date et heure du fichier, consultez la section Préfixe, suffixe et date et heure du nom de fichier.
-
Pour Traitement des fichiers par lot, spécifiez un délai maximal. avant de créer un fichier.
Vous pouvez également, si vous le souhaitez, définir la taille maximale du fichier ou le nombre maximal messages pour les fichiers.
Pour en savoir plus sur ces deux options de traitement par lot, consultez la section Traitement des fichiers par lot.
-
Nous vous recommandons vivement d'activer la gestion des lettres mortes pour gérer les échecs de messages.
Pour en savoir plus, consultez la section Lettres mortes sujet.
-
Vous pouvez conserver les autres paramètres par défaut et cliquer sur Créer.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
- Pour créer un abonnement Cloud Storage, exécutez la commande
gcloud pubsub subscriptions create
.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --cloud-storage-bucket=BUCKET_NAME \ --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \ --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \ --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \ --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \ --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \ --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \ --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \ --cloud-storage-write-metadata --cloud-storage-use-topic-schema
Dans la commande, seuls
SUBSCRIPTION_ID
, l'option--topic
et l'option--cloud-storage-bucket
sont obligatoires. Les options restantes sont facultatives et peuvent être omises.Remplacez les éléments suivants :
SUBSCRIPTION_ID
: nom ou ID de votre nouveau Abonnement Cloud Storage.TOPIC_ID
: nom ou ID de votre thème.BUCKET_NAME
: spécifie le nom d'un bucket existant. Exemple :prod_bucket
Le nom du bucket ne doit pas inclure l'ID du projet. Pour créer un bucket, consultez la page Créer des buckets.CLOUD_STORAGE_FILE_PREFIX
: spécifie le préfixe du nom de fichier Cloud Storage. Par exemple,log_events_
.CLOUD_STORAGE_FILE_SUFFIX
: spécifie le suffixe du nom de fichier Cloud Storage. Par exemple,.txt
.CLOUD_STORAGE_FILE_DATETIME_FORMAT
: Spécifie le format de date et d'heure du nom de fichier Cloud Storage. Exemple :YYYY-MM-DD/hh_mm_ssZ
CLOUD_STORAGE_MAX_DURATION
: valeur maximale qui peut s'écouler avant qu'un nouveau fichier Cloud Storage ne soit créé. La valeur doit être comprise entre 1 m et 10 m. Par exemple,5m
.CLOUD_STORAGE_MAX_BYTES
: nombre maximal d'octets pouvant être écrites dans un fichier Cloud Storage avant qu'un nouveau fichier est créé. La valeur doit être comprise entre 1 ko et 10 Go. Par exemple,20MB
.CLOUD_STORAGE_MAX_MESSAGES
: valeur maximale Nombre de messages pouvant être écrits dans un fichier Cloud Storage avant de créer un fichier. La valeur doit être supérieure ou égale à 1 000. Exemple :100000
CLOUD_STORAGE_OUTPUT_FORMAT
: format de sortie des données écrites dans Cloud Storage. Les valeurs sont les suivantes :text
: les messages sont écrits sous forme de texte brut, séparés par un retour à la ligne.avro
: les messages sont écrits sous la forme d'un binaire Avro.--cloud-storage-write-metadata
et--cloud-storage-use-topic-schema
ne concerne que abonnements au format de sortieavro
.
C++
Avant d'essayer cet exemple, suivez les instructions de configuration pour C++ du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez les API C++ Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub Go.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration de Java dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub Java.
Pour vous authentifier auprès de Pub/Sub, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
Surveiller un abonnement Cloud Storage
Cloud Monitoring fournit un certain nombre de métriques surveiller les abonnements.
Pour obtenir la liste de toutes les métriques disponibles liées à Pub/Sub, et leur description, consultez la Documentation Monitoring pour Pub/Sub
Vous pouvez également surveiller les abonnements depuis Pub/Sub.
Étape suivante
Résoudre un problème d'abonnement Cloud Storage
Découvrez Cloud Storage.
Consultez les tarifs de Pub/Sub, y compris l'abonnement Cloud Storage.