Ce document explique comment créer et gérer des canaux de notification à l'aide de bibliothèques clientes ou de la Google Cloud CLI, qui appellent tous deux l'API Cloud Monitoring. Cloud Monitoring utilise des canaux de notification pour vous avertir, vous ou votre équipe d'astreinte, lorsque la condition d'une règle d'alerte est remplie. Il existe plusieurs types de canaux disponibles. Chaque type est décrit dans un descripteur de canal de notification. Un canal de notification d'un certain type correspond à une instance du descripteur de ce type. Les règles d'alerte incluent des références aux canaux de notification à utiliser comme chemins de notification.
Un canal de notification doit exister avant de pouvoir être utilisé dans une règle d'alerte. Les descripteurs de canaux de notification vous sont fournis, mais vous devez vous-même créer les canaux avant de pouvoir les utiliser.
Pour configurer des canaux de notification à l'aide de la console Google Cloud, consultez la page Créer et gérer des canaux de notification.
Les exemples de code utilisés dans ce document sont extraits de l'exemple d'API de règle d'alerte décrit dans la section Exemples: sauvegarde et restauration.
À propos de l'API
La ressource NotificationChannel
prend en charge les opérations qui vous permettent de gérer vos canaux de notification. Il prend également en charge les opérations liées à la gestion du champ verificationStatus
d'un canal:
- Envoyer un code de vérification
- Générer un code pour copier l'état de vérification d'un canal vérifié sur d'autres canaux identiques d'un même projet ou d'un nouveau projet
- Vérifier le canal à l'aide du code créé lors des deux opérations précédentes
Pour en savoir plus, consultez les documents de référence notificationChannels
.
Avant de commencer
Pour obtenir les autorisations nécessaires pour afficher et configurer des canaux de notification à l'aide de l'API Cloud Monitoring, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Monitoring NotificationChannel (roles/monitoring.notificationChannelEditor
) sur votre 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.
Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
Pour en savoir plus sur les rôles Cloud Monitoring, consultez Contrôler les accès avec Identity and Access Management.
Lister les types de canaux de notification
Monitoring intègre un certain nombre de types de canaux de notification. Chacun de ces types est décrit dans une ressource NotificationChannelDescriptor
.
Ces descripteurs possèdent un champ type
dont la valeur sert d'identifiant lors de la création d'instances pour ce type de canal. Pour récupérer la liste des types de canaux que vous pouvez créer avec l'API Cloud Monitoring ou la Google Cloud CLI, saisissez la commande suivante:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
Pour en savoir plus sur les canaux de notification, consultez la page Créer et gérer des canaux de notification.
Si le canal de notification de votre choix n'est pas pris en charge, envisagez de créer un pipeline qui repose sur l'envoi de vos notifications à Pub/Sub. Pour obtenir un exemple Python utilisant Flask, consultez la section Créer des notifications personnalisées avec Cloud Monitoring et Cloud Run. Pour d'autres exemples, consultez le dépôt Git cloud-alerting-notification-forwarding.
Pour récupérer tous les descripteurs de canaux d'un projet Google Cloud, utilisez la méthode notificationChannelDescriptors.list
.
Les descripteurs récupérés sont en lecture seule.
Si vous recherchez un descripteur spécifique dont vous connaissez le nom, récupérez-le à l'aide de la méthode notificationChannelDescriptors.get
. Le nom d'un descripteur de canal est au format projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
, où [CHANNEL_TYPE]
doit correspondre à l'un des types répertoriés ci-dessus, par exemple :
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
Pour répertorier tous les descripteurs de canaux de notification d'un projet Google Cloud, exécutez la commande gcloud beta monitoring channel-descriptors list
:
gcloud beta monitoring channel-descriptors list
Si l'opération réussit, la commande list
fournit la liste de tous les descripteurs de canaux du projet spécifié. Par exemple, le descripteur de canal email
apparaît dans la liste comme suit :
--- description: A channel that sends notifications via email. displayName: Email labels: - description: An address to send email. key: email_address name: projects/[PROJECT_ID]/notificationChannelDescriptors/email type: email ---
Tous les descripteurs de canaux incluent les champs suivants :
name
: nom de ressource complet du descripteur de canaltype
: partie du nom qui indique le type de canal.displayName
: description du champtype
, à des fins d'affichagedescription
: brève description du canallabels
: ensemble de champs propres à un type de canal. Chaque type de canal possède son propre ensemble de libellés.
Lorsqu'un canal est créé, il reçoit également un champ enabled
, avec la valeur true
par défaut.
Pour répertorier un seul descripteur de canal, utilisez plutôt gcloud beta monitoring
channel-descriptors describe
et spécifiez le nom de ce descripteur de canal. Vous n'avez pas besoin de spécifier le nom complet. Par exemple, ces deux commandes renvoient la liste ci-dessus :
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
Pour plus d'informations, consultez la documentation de référence sur gcloud beta monitoring channel-descriptors
list
et describe
. La commande describe
correspond à la méthode notificationChannelDescriptors.get
dans l'API.
Créer un canal de notification
Vous pouvez créer des canaux de notification pour vos projets Google Cloud à partir de fichiers JSON ou YAML à l'aide de la Google Cloud CLI. Vous pouvez également les créer de manière automatisée.
Pour créer un canal de notification, vous devez fournir des valeurs associées aux champs de son descripteur. La plupart d'entre eux, par exemple type
, sont communs à tous les descripteurs de canaux de notification (consultez la page sur notificationChannelDescriptors
).
Chaque descripteur comporte également un ensemble de libellés, qui varie selon les descripteurs. Pour afficher l'ensemble des libellés d'un descripteur spécifique, récupérez le descripteur à l'aide de la commande gcloud beta monitoring channel-descriptors describe
décrite dans la section Lister les types de canaux de notification.
Par exemple, si vous récupérez le descripteur de canal email
, un seul libellé s'affiche :
labels: - description: An address to send email. key: email_address
Le descripteur de canal pubsub
contient également un seul libellé, qui identifie le sujet Pub/Sub. Cependant, les canaux peuvent contenir plusieurs libellés. Par exemple, le descripteur de canal slack
comporte deux libellés:
labels: - description: A permanent authentication token provided by Slack. This field is obfuscated by returning only a few characters of the key when fetched. key: auth_token - description: The Slack channel to which to post notifications. key: channel_name
La récupération du descripteur de canal webhook_basicauth
affiche plusieurs libellés :
labels: - description: The password. The field is obfuscated when the channel is fetched. key: password - description: The public URL to which to publish the webhook. key: url - description: The username. key: username
Que vous créiez un canal de manière automatisée ou à partir de la ligne de commande, la valeur de type
dans votre spécification doit correspondre au champ type
du descripteur de canal de notification correspondant. Toute clé de libellé requise doit également correspondre à celle du descripteur de canal.
Certaines étiquettes correspondent aux identifiants utilisés pour s'authentifier auprès du fournisseur. Lors de la création d'un canal, les valeurs de ces étiquettes doivent être obtenues auprès du fournisseur. Pour obtenir des identifiants, il se peut que vous deviez utiliser une page de génération de clé API sur le site Web du fournisseur ou exécuter un processus de connexion OAuth auprès du fournisseur. Les modalités d'obtention des identifiants dépendent du fournisseur concerné.
L'exemple suivant montre la spécification d'un nouveau canal de notification pubsub
au format JSON:
{ "type": "pubsub", "displayName": "Notifications", "description": "Pub/Sub channel for notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
La valeur de type
(pubsub
) et la clé de libellé unique (topic
) correspondent aux champs type
et labels.key
du descripteur de canal correspondant.
Les canaux sont activés par défaut. Si vous souhaitez créer un canal inactif, vous pouvez inclure le champ enabled
avec la valeur false
.
Les exemples suivants illustrent la création de canaux de notification.
gcloud
Pour créer un canal de notification dans un projet Google Cloud, exécutez la commande gcloud beta monitoring
channels create
. Pour charger le canal à partir d'un fichier, utilisez l'option --channel-content-from-file
pour spécifier le fichier.
L'exemple suivant crée un canal Pub/Sub à partir du fichier pubsub-channel.json
:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
Si l'opération réussit, la commande renvoie le nom du nouveau canal, par exemple :
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
Pour plus d'informations, consultez la documentation de référence sur gcloud beta monitoring channels create
.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Exemple: Créer un canal de notification Slack
Pour configurer un canal de notification pour une application Slack, procédez comme suit:
Configurez votre application Slack:
- Si vous ne possédez pas encore d'application Slack, suivez la documentation de référence Slack pour en créer une et l'installer dans votre espace de travail.
- Configurez votre application Slack avec des niveaux d'accès OAuth pour
chat:write
etchat:write.public
. - Copiez le jeton OAuth de l'utilisateur bot de l'application.
Créez un fichier qui définit la configuration de votre canal de notification. Incluez un libellé où la clé
auth_token
a la valeur du jeton OAuth de l'utilisateur bot de votre application Slack. Exemple :{ "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }
Exécutez la commande suivante pour créer le canal de notification:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
Lister les canaux de notification d'un projet
Pour récupérer tous les canaux de notification d'un projet Google Cloud, utilisez la méthode notificationChannels.list
. Cette méthode est également compatible avec les options filter
et orderBy
, qui permettent de restreindre et de trier les résultats. Pour en savoir plus, consultez la page Trier et filtrer.
Si vous recherchez un canal spécifique dont vous connaissez le nom, récupérez-le à l'aide de la méthode notificationChannels.get
. Le nom d'un canal est au format projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, par exemple :
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Lorsque vous récupérez un canal, des valeurs sensibles telles que les jetons d'authentification et les clés API peuvent être masquées pour des raisons de sécurité. Si vous créez un canal en copiant un canal existant, toutes les valeurs masquées doivent être corrigées.
gcloud
Pour répertorier tous les canaux de notification d'un projet Google Cloud, exécutez la commande gcloud beta monitoring channels list
:
gcloud beta monitoring channels list
Si l'opération réussit, la commande list
fournit la liste de tous les canaux du projet spécifié. Par exemple, la commande ci-dessus peut renvoyer une liste incluant les entrées suivantes :
--- description: E-mail channel created by gcloud as a test displayName: test e-mail channel enabled: false labels: email_address: user@example.com name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: email --- description: Pub/Sub channel for notifications displayName: Notifications enabled: true labels: topic: projects/[PROJECT_ID]/topics/notificationTopic name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: pubsub
Pour ne répertorier qu'un seul canal, utilisez plutôt gcloud beta monitoring
channels describe
et spécifiez son nom.
Par exemple, cette commande renvoie le canal Pub/Sub affiché dans la liste ci-dessus :
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Pour plus d'informations, consultez la documentation de référence sur gcloud beta monitoring channels list
et describe
. La commande describe
correspond à la méthode notificationChannels.get
dans l'API.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Supprimer un canal de notification d'un projet
Pour supprimer un canal de notification d'un projet Google Cloud, utilisez la méthode notificationChannels.delete
et indiquez le nom du canal de notification à supprimer. Le nom d'un canal correspond à la valeur du champ name
, et non pas du champ displayName
, dans l'instance NotificationChannel
.
Le nom d'un canal est au format projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, par exemple :
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Par défaut, vous ne pourrez pas supprimer un canal référencé par une règle d'alerte. Pour forcer la suppression des références des règles d'alerte et supprimer le canal, définissez l'option force
sur true
. Le canal sera automatiquement supprimé de toutes les règles de référence.
gcloud
Pour supprimer un canal de notification, utilisez gcloud beta monitoring channels
delete
et spécifiez le nom du canal à supprimer. Par exemple, la commande suivante supprime le canal email
créé dans un autre exemple :
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Pour plus d'informations, consultez la documentation de référence sur gcloud beta monitoring channels delete
.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Modifier un canal de notification
Pour modifier un canal de notification, utilisez la méthode notificationChannels.patch
(dans l'API REST).
D'autres implémentations d'API et la Google Cloud CLI appellent update
au lieu de patch
.
Une opération de mise à jour peut remplacer entièrement le canal existant ou modifier un sous-ensemble de champs. Par exemple, vous pouvez activer et désactiver le canal. La désactivation d'un canal empêche l'envoi de notifications au canal. En règle générale, il est plus pratique de désactiver un canal plutôt que de le supprimer des règles d'alerte qui y font référence, si la modification est censée être temporaire.
gcloud
Pour activer un canal de notification désactivé, exécutez la commande gcloud beta monitoring channels update
et spécifiez l'option --enabled
. La commande suivante active le canal de notification email
créé à l'état désactivé dans un exemple précédent :
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
Pour désactiver une règle, exécutez la même commande et spécifiez l'option --no-enabled
.
Pour plus d'informations, consultez la documentation de référence sur gcloud beta monitoring channels update
. La commande update
correspond à la méthode notificationChannels.patch
dans l'API REST.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Afficher les journaux des canaux de notification
Vous pouvez utiliser l'explorateur de journaux pour afficher les erreurs liées aux canaux de notification:
-
Dans la console Google Cloud, accédez à la page Explorateur de journaux.
Accéder à l'explorateur de journaux
Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
Saisissez et exécutez votre requête. Pour les requêtes spécifiques aux erreurs de canal de notification, consultez la section Requêtes Cloud Monitoring.