Questo documento descrive come creare e gestire i canali di notifica utilizzando librerie client o Google Cloud CLI, entrambi per richiamare l'API Cloud Monitoring. Cloud Monitoring utilizza i canali di notifica di informare te o il tuo team disponibile quando la condizione di un criterio di avviso viene rispettata. Sono disponibili diversi tipi di canali. ogni tipo è 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.
Prima di poter essere utilizzato in un criterio di avviso, è necessario che esista un canale di notifica. I descrittori del canale di notifica ti vengono forniti, ma devi creano i canali prima che possano essere utilizzati.
Per configurare i canali di notifica utilizzando la console Google Cloud, consulta Creare e gestire i canali di notifica.
Gli esempi di codice utilizzati in questo documento vengono estratti dalla dell'API alerting-policy, descritto in Esempio: backup e ripristino.
Informazioni sull'API
La risorsa NotificationChannel
supporta operazioni che ti consentono
gestire i canali di notifica. Supporta inoltre le operazioni relative
gestire il campo verificationStatus
di un canale:
- Invio di un codice di verifica
- Generare un codice per copiare lo stato di verifica di un canale verificato ad altri canali identici nello stesso progetto o in uno nuovo
- Verificare il canale utilizzando il codice creato dalle due operazioni precedenti
Per ulteriori informazioni, consulta la documentazione di riferimento di notificationChannels
documenti.
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
Ruolo IAM Monitoring NotificationChannel (roles/monitoring.notificationChannelEditor
) per il progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite la ruoli o altri ruoli predefiniti ruoli.
Per ulteriori informazioni sui ruoli di Cloud Monitoring, consulta Controllare l'accesso con Identity and Access Management.
Elenca i tipi di canali di notifica
Il monitoraggio offre una serie di canali di notifica integrati
di testo. Ciascuno di
descritti in NotificationChannelDescriptor
.
Questi descrittori hanno un campo type
e il valore di questo campo
funge da identificatore durante la creazione delle istanze
tipo di canale. Puoi recuperare i tipi di canali disponibili, descritti più in dettaglio
in generale nella sezione 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 di 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 Repository Git cloud-alerting-notification-forwarding
Per recuperare tutti i descrittori di canale in un progetto Google Cloud, utilizza
notificationChannelDescriptors.list
.
I descrittori recuperati sono di sola lettura.
Se stai cercando un descrittore specifico e ne conosci il nome,
puoi usare il metodo notificationChannelDescriptors.get
per recuperare solo quel descrittore di canale. Il nome di un canale
descrittore ha il formato
projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
[CHANNEL_TYPE]
deve essere uno dei tipi elencati sopra, ad esempio:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
Per elencare tutti i descrittori del canale di notifica in un progetto Google Cloud,
usa il comando gcloud beta monitoring channel-descriptors list
:
gcloud beta monitoring channel-descriptors list
In caso di esito positivo, il comando list
fornisce un elenco di tutti i canali
nel progetto specificato. Ad esempio, il canale email
descrittore appare 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 del 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
ai fini della visualizzazione.description
: una breve descrizione del canalelabels
: un insieme di campi specifici di un tipo di canale. Ogni tipo di canale ha un proprio insieme di etichette.
Quando un canale viene creato, riceve anche un campo enabled
, con il valore
true
per impostazione predefinita.
Per elencare un singolo descrittore di canale, usa invece gcloud beta monitoring
channel-descriptors describe
e specifica il nome del canale
descrittore. Non è necessario specificare il nome completo. Ad esempio:
entrambi i comandi restituiscono l'elenco riportato sopra:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
Consulta la gcloud beta monitoring channel-descriptors
list
e describe
per ulteriori informazioni. Il comando describe
corrisponde
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 puoi crearle in modo programmatico.
Per creare un canale di notifica, devi fornire i valori per il parametro
nel suo descrittore. La maggior parte di queste, ad esempio type
, è comune
in tutti i descrittori del canale di notifica; vedi
notificationChannelDescriptors
.
Ogni descrittore ha anche un insieme di etichette, che varia a seconda del
descrittori. Per vedere l'insieme di etichette per un particolare descrittore, recupera
il descrittore utilizzando gcloud beta monitoring channel-descriptors describe
descritto in Elenca i tipi di canali di notifica.
Ad esempio, il recupero
email
descrittore del canale mostra una singola etichetta:
labels: - description: An address to send email. key: email_address
Il descrittore del canale pubsub
contiene anche una singola etichetta; quell'etichetta
identifica l'argomento Pub/Sub. Tuttavia, i canali possono contenere
etichette. Ad esempio, il descrittore del 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 del 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
Sia che crei un nuovo canale in modo programmatico
o dalla riga di comando,
il valore del parametro type
nella specifica deve corrispondere al campo type
in
il descrittore del canale di notifica corrispondente. Qualsiasi etichetta obbligatoria
devono corrispondere a quelle nel descrittore del canale.
Alcune etichette corrispondono alle credenziali utilizzate per l'autenticazione con il provider. Quando crei un canale, i valori di queste etichette devono essere ottenuti dalla o il provider di servizi di terze parti. L'ottenimento di una credenziale potrebbe comportare l'utilizzo di una pagina di generazione di chiavi API sul sito web del provider o completare un flusso di accesso OAuth con il provider. Le specifiche di come ottenere una credenziale di questo tipo dipendono dalle caratteristiche o il provider di servizi di terze parti.
Ad esempio, quanto segue mostra la specifica di un nuovo pubsub
canale di notifica in JSON:
{ "type": "pubsub", "displayName": "Notifications", "description": "Pub/Sub channel for notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
Il valore type
(pubsub
) e la chiave di etichetta singola (topic
)
corrisponde ai campi type
e labels.key
nel canale corrispondente
descrittore.
I canali sono attivati per impostazione predefinita. Se vuoi creare un canale inattivo,
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, utilizza il metodo
--channel-content-from-file
per specificare il file.
L'esempio seguente crea un nuovo canale Pub/Sub
dal file pubsub-channel.json
:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
In caso di esito positivo, questo comando restituisce il nome del nuovo canale, ad esempio:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
Consulta la gcloud beta monitoring channels create
di riferimento per ulteriori informazioni.
C#
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Esempio: creare un canale di notifica Slack
Per configurare un canale di notifica per un'app Slack, segui questi passaggi:
Configura l'app Slack:
- Se non hai ancora un'app Slack, segui le Slack documentazione di riferimento per crearne uno e installarlo a un ambiente nella tua area di lavoro.
- Configura la tua app Slack con ambiti OAuth per
chat:write
echat:write.public
. - Copia il token OAuth dell'utente del bot dell'app.
Crea un file che definisce la configurazione del tuo canale di notifica. Includi un'etichetta in cui la chiave
auth_token
ha del token OAuth dell'utente del bot della tua app Slack. Ad esempio:{ "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }
Esegui questo comando per creare il canale di notifica:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
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
opzioni filter
e orderBy
per limitare e ordinare i risultati.
consulta la sezione Ordinamento e filtri.
Se stai cercando un canale specifico e ne conosci il nome,
puoi usare il metodo notificationChannels.get
per recuperare solo quel canale. 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 offuscate per motivi di sicurezza. Se crei un nuovo canale copiandone uno esistente, i valori offuscati devono essere corretti.
gcloud
Per elencare tutti i canali di notifica in un progetto Google Cloud, utilizza
Comando gcloud beta monitoring channels list
:
gcloud beta monitoring channels list
In caso di esito positivo, il comando list
fornisce un elenco di tutti i canali
nel progetto specificato. Ad esempio, il comando riportato sopra potrebbe restituire un elenco
che include le seguenti voci:
--- 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
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 in
elenco sopra:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Consulta la gcloud beta monitoring channels list
e describe
per ulteriori informazioni. Il comando describe
corrisponde
notificationChannels.get
nell'API.
C#
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Elimina un canale di notifica da un progetto
Per eliminare un canale di notifica da un progetto Google Cloud, utilizza il metodo
notificationChannels.delete
e fornisci il nome
del canale di notifica da eliminare. Il nome di un canale è il valore di
il 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 sarà eliminato. Per forzare la rimozione di
riferimenti dai criteri di avviso ed elimina il canale, imposta force
per true
. Questa opzione rimuove automaticamente il canale da tutti
fare riferimento alle policy.
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
Consulta le
gcloud beta monitoring channels delete
di riferimento per ulteriori informazioni.
C#
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Modificare un canale di notifica
Per modificare un canale di notifica, utilizza il
notificationChannels.patch
(nell'API REST).
Altre implementazioni API e Google Cloud CLI chiamano questa funzionalità update
anziché patch
.
Un'operazione di aggiornamento può sostituire completamente il canale esistente oppure può modificare un sottoinsieme di campi. Ad esempio, puoi attivare e disattivare il canale. La disattivazione di un canale impedisce l'invio di notifiche al canale. In genere, la disattivazione di un canale è più comoda della sua rimozione dai criteri di avviso che vi fanno riferimento, se la modifica deve temporaneo.
gcloud
Per attivare un canale di notifica disattivato, utilizza il
gcloud beta monitoring channels update
e fornisci il comando --enabled
flag. Il seguente comando abilita il canale di notifica email
creato, con lo 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
.
Consulta la gcloud beta monitoring channels update
di riferimento per ulteriori informazioni. Il comando update
corrisponde
notificationChannels.patch
nell'API REST.
C#
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Visualizza i log del canale di notifica
Puoi utilizzare Esplora log per visualizzare gli errori del canale di notifica:
-
Nella console Google Cloud, vai alla pagina Esplora log:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.
Inserisci ed esegui la query. Per query specifiche sugli errori del canale di notifica, consulta Query di Cloud Monitoring.