Questo documento descrive come creare e gestire i canali di notifica utilizzando le librerie client o Google Cloud CLI, che richiamano l'API Cloud Monitoring. Cloud Monitoring utilizza i canali di notifica per inviare notifiche a te o al team di pronto intervento quando viene attivato un criterio di avviso. Sono disponibili vari tipi di canali, ognuno descritto in un descrittore del canale di notifica. Un canale di notifica di un certo tipo è un'istanza del descrittore di quel tipo. I criteri di avviso includono riferimenti ai canali di notifica da utilizzare come percorsi di notifica.
Un canale di notifica deve esistere prima di poter essere utilizzato in un criterio di avviso. I descrittori dei canali di notifica ti vengono forniti, ma devi creare i canali prima che possano essere utilizzati.
Per configurare i canali di notifica utilizzando la console Google Cloud, consulta Creazione e gestione dei canali di notifica.
Gli esempi di codice utilizzati in questo documento vengono estratti dall'esempio dell'API dei criteri di avviso, descritto in Esempio: backup e ripristino.
Informazioni sull'API
La risorsa NotificationChannel
supporta operazioni che ti consentono di
gestire i canali di notifica. Supporta anche le operazioni relative alla gestione del campo verificationStatus
di un canale:
- Invio di un codice di verifica
- Generazione di un codice per copiare lo stato di verifica di un canale verificato su altri canali identici nello stesso progetto o in uno nuovo
- Verifica del canale utilizzando il codice creato dalle due operazioni precedenti
Per ulteriori informazioni, consulta i documenti di riferimento di notificationChannels
.
Prima di iniziare
Per ottenere le autorizzazioni necessarie per visualizzare e configurare i canali di notifica utilizzando l'API Cloud Monitoring,
chiedi all'amministratore di concederti il ruolo IAM
Editor NotificationChannel Monitoring (roles/monitoring.notificationChannelEditor
) per il tuo progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Per ulteriori informazioni sui ruoli di Cloud Monitoring, consulta Controllare l'accesso con Identity and Access Management.
Elenca i tipi di canali di notifica
Monitoring offre numerosi tipi di canali
di notifica integrati. Ciascuno di questi tipi è descritto in un NotificationChannelDescriptor
.
Questi descrittori hanno un campo type
e il valore di questo campo funge da identificatore quando vengono create istanze di quel tipo di canale. Puoi recuperare i tipi di canale disponibili, descritti più in generale in Creare e gestire canali di notifica, con il seguente comando:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
Se il tuo canale di notifica preferito non è supportato, valuta la possibilità di creare una pipeline basata sull'invio delle notifiche a Pub/Sub. Per un esempio Python che utilizza Flask, consulta Creazione di notifiche personalizzate con Cloud Monitoring e Cloud Run. Per altri esempi, consulta il repository Git cloud-alerting-notification-forwarding.
Per recuperare tutti i descrittori di canale in un progetto Google Cloud, utilizza il metodo notificationChannelDescriptors.list
.
I descrittori recuperati sono di sola lettura.
Se cerchi un descrittore specifico di cui conosci il nome, puoi utilizzare il metodo notificationChannelDescriptors.get
per recuperare solo quel descrittore di canale. Il nome di un descrittore di canale ha il formato projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
[CHANNEL_TYPE]
deve essere uno dei tipi sopra elencati, ad esempio:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
Per elencare tutti i descrittori del canale di notifica in un progetto Google Cloud, utilizza il comando gcloud beta monitoring channel-descriptors list
:
gcloud beta monitoring channel-descriptors list
Se l'esito è positivo, il comando list
fornisce un elenco di tutti i descrittori di canale nel progetto specificato. Ad esempio, il descrittore del canale email
viene visualizzato nell'elenco in questo modo:
--- 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 ---
Tutti i descrittori di canale includono i seguenti campi:
name
: il nome completo della risorsa del descrittore del canaletype
: la parte del nome che indica il tipo di canaledisplayName
: una descrizione del campotype
a fini di visualizzazione.description
: una breve descrizione del canalelabels
: un insieme di campi specifici di un tipo di canale. Ogni tipo di canale ha il proprio set di etichette.
Quando viene creato un canale, riceve anche un campo enabled
, con valore
true
per impostazione predefinita.
Per elencare un singolo descrittore di canale, utilizza invece gcloud beta monitoring
channel-descriptors describe
e specifica il nome del descrittore di canale. Non è necessario specificare il nome completo. Ad esempio, entrambi questi comandi restituiscono l'elenco precedente:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
Per saperne di più, consulta i riferimenti a gcloud beta monitoring channel-descriptors
list
e describe
. Il comando describe
corrisponde al metodo
notificationChannelDescriptors.get
nell'API.
Creazione di un canale di notifica
Puoi creare canali di notifica per i tuoi progetti Google Cloud da file JSON o YAML utilizzando Google Cloud CLI e crearli in modo programmatico.
Per creare un canale di notifica, devi fornire valori per i campi nel relativo descrittore. La maggior parte di questi, come type
, è comune
in tutti i descrittori dei canali di notifica; consulta
notificationChannelDescriptors
.
Ogni descrittore ha anche un insieme di etichette, che varia in base al descrittore. Per visualizzare il set di etichette per un determinato descrittore, recupera il descrittore utilizzando il comando gcloud beta monitoring channel-descriptors describe
descritto in Elenco dei tipi di canali di notifica.
Ad esempio, se si recupera il descrittore di canale email
viene visualizzata una singola etichetta:
labels: - description: An address to send email. key: email_address
Il descrittore del canale pubsub
contiene anche una singola etichetta, che identifica l'argomento Pub/Sub. Tuttavia, i canali possono contenere
più etichette. Ad esempio, il descrittore di canale slack
ha due etichette:
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
Il recupero del descrittore di canale webhook_basicauth
mostra diverse etichette:
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
A prescindere dal fatto che tu crei un nuovo canale in modo programmatico o dalla riga di comando, il valore di type
nella specifica deve corrispondere al campo type
nel descrittore del canale di notifica corrispondente. Tutte le chiavi di etichetta obbligatorie
devono corrispondere anche a quelle nel descrittore del canale.
Alcune etichette corrispondono alle credenziali utilizzate per l'autenticazione con il provider. Quando si crea un canale, i valori per queste etichette devono essere ottenuti dal provider. L'ottenimento di una credenziale potrebbe comportare l'utilizzo di una pagina di generazione di chiavi API sul sito web del provider o il completamento di un flusso di accesso OAuth con il provider. Le specifiche su come ottenere questa credenziale dipendono dal particolare provider.
Ad esempio, quanto segue mostra la specifica di un nuovo canale di notifica pubsub
in formato JSON:
{ "type": "pubsub", "displayName": "Alert notifications", "description": "Pub/Sub channel for alert notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
Il valore type
(pubsub
) e la singola chiave di etichetta (topic
)
corrispondono ai campi type
e labels.key
nel descrittore
di canale corrispondente.
I canali sono attivi per impostazione predefinita. Se vuoi creare un canale non attivo,
puoi includere il campo enabled
con il valore false
.
I seguenti esempi illustrano la creazione di canali di notifica.
gcloud
Per creare un canale di notifica in un progetto Google Cloud, utilizza il comando gcloud beta monitoring
channels create
. Per caricare il canale da un file, usa il flag --channel-content-from-file
per specificare il file.
Nell'esempio seguente viene creato un nuovo canale Pub/Sub dal file pubsub-channel.json
:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
Se l'esito è positivo, questo comando restituisce il nome del nuovo canale, ad esempio:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
Per ulteriori informazioni, consulta il riferimento gcloud beta monitoring channels create
.
C#
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Elenco canali di notifica in un progetto
Per recuperare tutti i canali di notifica in un progetto Google Cloud, utilizza il metodo notificationChannels.list
. Questo metodo supporta anche le opzioni filter
e orderBy
per limitare e ordinare i risultati; consulta Ordinamento e filtri.
Se stai cercando un canale specifico di cui conosci il nome,
puoi utilizzare il metodo notificationChannels.get
per recuperarlo solo. Il nome di un canale ha il formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, ad esempio:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Quando recuperi un canale, i valori sensibili come i token di autenticazione e le chiavi API potrebbero essere offuscati per motivi di sicurezza. Se crei un nuovo canale copiandone uno esistente, tutti i valori offuscati devono essere corretti.
gcloud
Per elencare tutti i canali di notifica in un progetto Google Cloud, utilizza il comando gcloud beta monitoring channels list
:
gcloud beta monitoring channels list
Se l'esito è positivo, il comando list
fornisce un elenco di tutti i canali
nel progetto specificato. Ad esempio, il comando precedente potrebbe restituire un elenco
che include le voci seguenti:
--- 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 alert notifications displayName: Alert notifications enabled: true labels: topic: projects/[PROJECT_ID]/topics/notificationTopic name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: pubsub
Per elencare un singolo canale, usa invece gcloud beta monitoring
channels describe
e specifica il nome del canale.
Ad esempio, questo comando restituisce il canale Pub/Sub mostrato nell'elenco precedente:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Per saperne di più, consulta i riferimenti a gcloud beta monitoring channels list
e describe
. Il comando describe
corrisponde al metodo
notificationChannels.get
nell'API.
C#
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Eliminare un canale di notifica da un progetto
Per eliminare un canale di notifica da un progetto Google Cloud, utilizza il metodo notificationChannels.delete
e indica il nome del canale di notifica da eliminare. Il nome di un canale è il valore del campo name
, non displayName
, nell'istanza NotificationChannel
.
Il nome di un canale ha il formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, ad esempio:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Per impostazione predefinita, se tenti di eliminare un canale a cui fa riferimento un criterio di avviso, il canale non verrà eliminato. Per forzare la rimozione dei riferimenti dai criteri di avviso ed eliminare il canale, imposta l'opzione force
su true
. In questo modo, il canale verrà rimosso automaticamente
da tutte le norme di riferimento.
gcloud
Per eliminare un canale di notifica, usa gcloud beta monitoring channels
delete
e specifica il nome del canale da eliminare. Ad esempio, il seguente comando elimina il canale email
creato in un altro esempio:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Per ulteriori informazioni, consulta il riferimento gcloud beta monitoring channels delete
.
C#
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Modificare un canale di notifica
Per modificare un canale di notifica, utilizza il metodo notificationChannels.patch
(nell'API REST).
Altre implementazioni API e Google Cloud CLI chiamano update
anziché patch
.
Un'operazione di aggiornamento può sostituire completamente il canale esistente o modificare un sottoinsieme di campi. Ad esempio, puoi attivare e disattivare il canale. La disattivazione di un canale impedisce la ricezione delle notifiche. La disattivazione di un canale è in genere più comoda rispetto alla rimozione del canale dai criteri di avviso che vi fanno riferimento, se la modifica è destinata a essere temporanea.
gcloud
Per abilitare un canale di notifica disabilitato, utilizza il comando gcloud beta monitoring channels update
e fornisci il flag --enabled
. Il comando seguente consente di attivare il canale di notifica email
creato, in stato disabilitato, in un esempio precedente:
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
Per disabilitare un criterio, utilizza lo stesso comando e fornisci il flag --no-enabled
.
Per ulteriori informazioni, consulta il riferimento gcloud beta monitoring channels update
. Il comando update
corrisponde al metodo
notificationChannels.patch
nell'API REST.
C#
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Visualizza i log dei canali di notifica
Puoi utilizzare Esplora log per visualizzare gli errori del canale di notifica:
-
Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:
Inserisci ed esegui la query. Per query specifiche sugli errori dei canali di notifica, consulta Query di Cloud Monitoring.