Questo documento descrive come creare e gestire i canali di notifica utilizzando le librerie client o Google Cloud CLI, che richiamano entrambe l'API Cloud Monitoring. Cloud Monitoring utilizza i canali di notifica per informare te o il tuo team di assistenza quando viene soddisfatta la condizione di un criterio di avviso. Esistono diversi tipi di canali disponibili; ciascun tipo è descritto in un descrittore del canale di notifica. Un canale di notifica di un determinato tipo è un'istanza del relativo descrittore. 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 Creare e gestire i canali di notifica.
Gli esempi di codice utilizzati in questo documento sono estratti dall'esempio di API alert-policy, descritto in Esempio: backup e ripristino.
Informazioni sull'API
La risorsa NotificationChannel
supporta le operazioni che ti consentono di gestire i canali di notifica. Supporta inoltre 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 un nuovo progetto
- Verifica del canale utilizzando il codice creato dalle due operazioni precedenti
Per ulteriori informazioni, consulta la documentazione 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 di NotificationChannel di monitoraggio (roles/monitoring.notificationChannelEditor
) nel progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a 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
Il monitoraggio offre una serie di tipi di canali di notifica integrati. Ognuno di questi tipi è descritto in un NotificationChannelDescriptor
.
Questi descrittori hanno un campo type
e il valore di questo campo funge da identificatore per la creazione di istanze di quel tipo di canale. Per recuperare un elenco dei tipi di canali che puoi creare con l'API Cloud Monitoring o Google Cloud CLI, inserisci 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
Per saperne di più sui canali di notifica, consulta la pagina Creare e gestire i canali di notifica.
Se il tuo canale di notifica preferito non è supportato, ti consigliamo di creare una pipeline che si basi sull'invio delle notifiche a Pub/Sub. Per un esempio di Python che utilizza Flask, consulta Creare notifiche personalizzate con Cloud Monitoring e Cloud Run. Per altri esempi, consulta il repository Git cloud-alerting-notification-forwarding.
Per recuperare tutti i descrittori dei canali in un progetto Google Cloud, utilizza il metodo
notificationChannelDescriptors.list
.
I descrittori recuperati sono di sola lettura.
Se stai cercando un descrittore specifico e ne conosci il nome, puoi utilizzare il metodo notificationChannelDescriptors.get
per recuperare solo quel descrittore del canale. Il nome di un descriptor del canale ha il formatoprojects/[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 dei canali di notifica in un progetto Google Cloud,
utilizza 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 descrittori
del canale nel progetto specificato. Ad esempio, il descrittore del canale email
viene visualizzato nell'elenco come segue:
--- 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 dei canali 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 scopo di visualizzazionedescription
: una breve descrizione del canalelabels
: un insieme di campi specifici per un tipo di canale. Ogni tipo di canale ha un proprio insieme di etichette.
Quando viene creato un canale, viene aggiunto anche un campo enabled
con il valore
true
per impostazione predefinita.
Per elencare un singolo descrittore di canale, utilizza gcloud beta monitoring
channel-descriptors describe
e specifica il nome del descrittore. Non è necessario specificare il nome completo. Ad esempio, entrambi i comandi seguenti restituiscono la scheda sopra:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
Per ulteriori informazioni, consulta le referenze 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 puoi crearli in modo programmatico.
Per creare un canale di notifica, devi fornire i valori per i campi nel relativo descrittore. La maggior parte di questi, come type
, sono comuni a tutti i descrittori dei canali di notifica; consulta notificationChannelDescriptors
.
Ogni descrittore ha anche un insieme di etichette, che varia in base ai descrittori. Per visualizzare l'insieme di etichette per un determinato descrittore, recuperalo utilizzando il comando gcloud beta monitoring channel-descriptors describe
descritto in Elenca i tipi di canali di notifica.
Ad esempio, il recupero del descrittore del canale email
mostra 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 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
Indipendentemente dal fatto che tu crei un nuovo canale tramite programmazione o dalla riga di comando, il valore di type
nella specifica deve corrispondere al campo type
nel descrittore del canale di notifica corrispondente. Eventuali chiavi di etichetta obbligatorie devono corrispondere anche a quelle nel descrittore del canale.
Alcune etichette corrispondono alle credenziali utilizzate per l'autenticazione con il fornitore. Quando crei un canale, i valori per queste etichette devono essere ottenuti dal fornitore. L'ottenimento di una credenziale potrebbe comportare l'utilizzo di una pagina di generazione di chiavi API sul sito web del fornitore o il completamento di un flusso di accesso OAuth con il fornitore. Le specifiche su come ottenere una credenziale del genere dipendono dal fornitore specifico.
Ad esempio, di seguito è riportata la specifica di un nuovo canale di notifica pubsub
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 singola chiave di etichetta (topic
) devono corrispondere ai campi type
e labels.key
nel descrittore del canale corrispondente.
I canali sono abilitati per impostazione predefinita. Se vuoi creare un canale inattivo, puoi includere il campo enabled
con il valore false
.
Gli esempi riportati di seguito 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 flag --channel-content-from-file
per specificare il file.
Il seguente esempio 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].
Per ulteriori informazioni, consulta la documentazione di riferimento gcloud beta monitoring channels create
.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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 la documentazione di riferimento di Slack per crearne una e installarla nella tua area di lavoro.
- Configura l'app Slack con gli ambiti OAuth per
chat:write
echat:write.public
. - Copia il token OAuth dell'utente bot dell'app.
Crea un file che definisce la configurazione del canale di notifica. Includi un'etichetta in cui la chiave
auth_token
ha il valore 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 il comando seguente per creare il canale di notifica:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
Elenco dei 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 e ne conosci il nome, puoi utilizzare il metodo notificationChannels.get
per recuperare solo quel canale. Il nome di un canale ha il formatoprojects/[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
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, utilizza gcloud beta monitoring
channels describe
e specifica il nome del canale.
Ad esempio, questo comando restituisce il canale Pub/Sub mostrato nell'elenco riportato sopra:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Per ulteriori informazioni, consulta le referenze gcloud beta monitoring channels list
e describe
. Il comando describe
corrisponde al metodo notificationChannels.get
nell'API.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori 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 fornisci 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 formatoprojects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, ad esempio:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Per impostazione predefinita, se tenti di eliminare un canale a cui viene fatto riferimento da 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
. Questa opzione rimuove automaticamente il canale da tutte le norme di riferimento.
gcloud
Per eliminare un canale di notifica, utilizza gcloud beta monitoring channels
delete
e specifica il nome del canale da eliminare. Ad esempio, il
comando seguente elimina il canale email
creato in un altro esempio:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Per ulteriori informazioni, consulta la documentazione di riferimento gcloud beta monitoring channels delete
.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori 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 dell'API e Google Cloud CLI chiamano questo parametro update
instead of 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 l'invio di notifiche al canale. La disattivazione di un canale è in genere più comoda della rimozione del canale dai criteri di avviso che fanno riferimento al canale, se la modifica è prevista essere temporanea.
gcloud
Per attivare un canale di notifica disattivato, utilizza il comando gcloud beta monitoring channels update
e specifica il flag --enabled
. Il seguente comando attiva il canale di notifica email
creato (nello stato disattivato) in un esempio precedente:
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
Per disattivare un criterio, utilizza lo stesso comando e specifica il flag --no-enabled
.
Per ulteriori informazioni, consulta la documentazione di riferimento gcloud beta monitoring channels update
. Il comando update
corrisponde al metodo notificationChannels.patch
nell'API REST.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Visualizzare i log dei canali di notifica
Puoi utilizzare Esplora log per visualizzare gli errori dei canali 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 relative agli errori dei canali di notifica, consulta Query di Cloud Monitoring.