Ce document explique comment créer un abonnement Cloud Storage. Vous pouvez utiliser la console Google Cloud, la 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 maîtriser les points 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 à l'échelle du projet.
Vous avez également besoin d'autorisations au niveau des ressources si vos abonnements et sujets se trouvent dans des projets différents, comme expliqué 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 plus sur la façon d'accorder ces autorisations, reportez-vous aux de ce document.
Pour obtenir les autorisations nécessaires pour créer des abonnements Cloud Storage,
demandez à votre administrateur de vous accorder le
Éditeur Pub/Sub (roles/pubsub.editor
) sur le projet.
Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.
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
-
Associer un abonnement à un sujet:
pubsub.topics.attachSubscription
-
Extraire d'un abonnement:
pubsub.subscriptions.consume
-
Obtenir un abonnement:
pubsub.subscriptions.get
-
Pour lister un abonnement:
pubsub.subscriptions.list
-
Pour mettre à jour 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 Cloud Storage
abonnements d'un projet qui sont associés à un sujet dans un autre
demandez à l'administrateur du sujet de vous accorder également le rôle d'éditeur Pub/Sub
(roles/pubsub.editor)
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
permet aux services d'accéder à vos ressources. Ces comptes de service sont appelés
les agents de service. Pub/Sub crée et gère un service
pour chaque projet dans un format
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
Pour créer un abonnement Cloud Storage, compte de service doit être autorisé à écrire dans un 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 l'instance Cloud Storage spécifique bucket, attribuez le rôle Créateur d'objets Storage (
roles/storage.objectCreator
) et le rôle de 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
) sur le projet contenant le bucket Cloud Storage. Attribuez ce rôle au Compte de service Pub/Sub.
Autorisations relatives aux buckets
Procédez comme suit pour attribuer le rôle de créateur d'objets Storage
(roles/storage.objectCreator
) et lecteur des anciens buckets Storage
(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 Autorisations > Dans l'onglet Afficher par compte principal, cliquez sur Accorder l'accès.
La page Accorder l'accès s'ouvre.
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
Creator
et sélectionnez le rôle Storage Object Creator.Cliquez sur Ajouter un autre rôle.
Dans la liste déroulante Sélectionner un rôle, saisissez
Bucket Reader
. et sélectionnez le rôle Lecteur des anciens buckets 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'ouvre.
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 IAM dans Cloud Storage, consultez la page Gestion de l'authentification et des accès dans Cloud Storage.
Propriétés d'abonnement 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.
Le bucket Cloud Storage doit contenir L'option Paiements du demandeur est désactivée.
Pour créer un bucket Cloud Storage, consultez Créez 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
format: <file-prefix><UTC-date-time>_<uuid><file-suffix>
.
La liste suivante contient des informations sur le format de fichier et les champs que vous 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 personnalisable générée automatiquement en fonction de l'heure l'objet est créé.<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. La 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 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 ni le suffixe du nom de fichier, le nom d'objet est stocké dans le bucket Cloud Storage est au format suivant:
<UTC-date-time>_<uuid>
Les règles de dénomination des objets Cloud Storage s'appliquent également au nom de fichier un préfixe et un suffixe. Pour en savoir plus, consultez À propos des objets Cloud Storage
Vous pouvez modifier l'affichage de la date et de l'heure dans le nom du fichier:
Mise en correspondance de date et d'heure obligatoires, que vous ne pouvez utiliser qu'une seule fois: l'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 (
-
), un trait de soulignement (_
), un deux-points (:
) et une barre oblique (/
).Par exemple, si la valeur du format date/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 date/heure du nom de fichier se termine par un caractère qui n'est pas une correspondance, ce caractère remplacera le séparateur entre
<UTC-date-time>
et<uuid>
Par exemple, si la valeur du format date/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 Cloud Storage bucket. Pub/Sub écrit un fichier de sortie lorsque l'un des les conditions de traitement par lot spécifiées sont remplies. 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 pour le 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. Vous trouverez ci-dessous les pour le nombre maximal d'octets:
- Valeur minimale = 1 Ko
- Valeur maximale = 10 Gio
Par exemple, vous pouvez configurer la durée maximale sur 6 minutes et 2 Go au maximum. Si à la 4e minute, le fichier de sortie atteint une de 2 Go, Pub/Sub finalise le fichier précédent et démarre écrire dans un nouveau fichier.
Un abonnement Cloud Storage peut écrire dans plusieurs fichiers d'un bucket Cloud Storage simultanément. Si vous avez configuré votre pour créer un fichier toutes les six minutes, vous pourriez constater 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 bytes" (Nombre maximal d'octets) si l'abonnement reçoit des messages dont la taille dépasse la valeur "Max bytes".
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. Message uniquement les charges utiles sont stockées, pas des attributs ou d’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 les métadonnées: cette option vous permet de stocker les métadonnées du message avec celui-ci. 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, order_key, le cas échéant) sont ajoutées en tant qu'entrées dans le mappageattributes
.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 conditions 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 plus d'informations sur le nom d'un abonnement, consultez la section Consignes pour nommer un sujet ou 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 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.
Après avoir créé le bucket, sélectionnez-le pour 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
. -
-
Si vous rencontrez des problèmes 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 le message de métadonnées pour le format Avro, consultez la section Fichier de sortie.
-
Facultatif: vous pouvez spécifier le paramètre File name prefix, suffix, and date/heure de tous les fichiers à écrire dans le bucket Cloud Storage. Un fichier est stocké en tant qu'objet dans le bucket.
Pour savoir comment définir le préfixe, le suffixe et date et heure, consultez la section Préfixe, suffixe et date/heure.
-
Pour Traitement des fichiers par lot, spécifiez un délai maximal. avant de créer un fichier.
Vous pouvez également définir la taille maximale des fichiers si vous le souhaitez.
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
-
Dans la console Google Cloud, activez Cloud Shell.
En bas de la fenêtre de la console Google Cloud, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
- Pour créer un
Sur 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-bytes=CLOUD_STORAGE_MAX_BYTES \ --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \ --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \ --cloud-storage-write-metadata
Dans la commande,
SUBSCRIPTION_ID
uniquement, l'option--topic
et--cloud-storage-bucket
; sont requises. Les autres options 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 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 pour le nom de fichier Cloud Storage. Par exemple,log_events_
.CLOUD_STORAGE_FILE_SUFFIX
: spécifie le pour le 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_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_DURATION
: valeur maximale qui peut s'écouler avant qu'un nouveau fichier Cloud Storage ne soit créé. La valeur doit être comprise entre 1 et 10 m. Par exemple,5m
.CLOUD_STORAGE_OUTPUT_FORMAT
: sortie pour les données écrites dans Cloud Storage. Les valeurs sont les suivantes : suivant: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
n'a d'effet que pour abonnements au format de sortieavro
.
C++
Avant d'essayer cet exemple, suivez les instructions de configuration de C++ dans le Guide de démarrage rapide de Pub/Sub 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 les 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 de Go dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Go Pub/Sub documentation de référence.
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 les API Java Pub/Sub documentation de référence.
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.
Surveiller les abonnements
Cloud Monitoring fournit un certain nombre de métriques pour surveiller les abonnements.
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 les tarifs des abonnements Cloud Storage.