La API de Cloud Monitoring y Google Cloud CLI te permiten crear y administrar de forma programática los canales de notificación que Cloud Monitoring usa para alertarte a ti o a tu equipo de guardia cuando se activa una política de alertas. Con las bibliotecas cliente o Google Cloud CLI, creas canales de notificaciones a partir de descriptores de canales de notificaciones integrados y, luego, haces referencia a esos canales en tus políticas de alertas.
Para configurar canales de notificaciones en la consola de Google Cloud , consulta Cómo crear y administrar canales de notificaciones. Los ejemplos de código de este documento provienen del ejemplo de la API de alerting-policy en Ejemplo: copia de seguridad y restablecimiento.
Acerca de la API
El recurso NotificationChannel admite operaciones que te permiten administrar tus canales de notificaciones. También admite operaciones relacionadas con la administración del campo verificationStatus de un canal:
- Enviar un código de verificación
- Generar un código para copiar el estado de verificación de un canal verificado en otros canales idénticos en el mismo proyecto o en uno nuevo
- Verificar el canal mediante el código creado en las dos operaciones anteriores
Para obtener más información, consulta los documentos de referencia de notificationChannels.
Limitaciones
- Tipos de canales obsoletos: Los tipos de canales
campfireyhipchatquedaron obsoletos. No crees canales nuevos de estos tipos. - Políticas de almacenamiento de mensajes de Pub/Sub: Si configuras una política de almacenamiento de mensajes o restricciones de residencia de datos para un tema de Pub/Sub, es posible que Monitoring no pueda publicar en el tema. Para obtener más información, consulta el error
FAILED_PRECONDITION. - Llamadas a la API simultáneas: Diseña tu aplicación para que llame a la API de Cloud Monitoring desde un solo subproceso cuando crees, modifiques o borres un canal de notificación en un proyecto de Google Cloud .
Antes de comenzar
-
Para obtener los permisos que necesitas para ver y configurar canales de notificaciones con la API de Cloud Monitoring, pídele a tu administrador que te otorgue el rol de IAM de editor de Monitoring NotificationChannel (
roles/monitoring.notificationChannelEditor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.
Para obtener más información sobre los roles de Cloud Monitoring, consulta Controla el acceso con Identity and Access Management.
-
Selecciona la pestaña que corresponda a la forma en que planeas usar las muestras de esta página:
gcloud
En la consola de Google Cloud , activa Cloud Shell.
En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.
C#
Para usar las muestras de .NET de esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad (IdP) externo, primero debes acceder a gcloud CLI con tu identidad federada.
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.
Para obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .
Go
Para usar las muestras de Go de esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad (IdP) externo, primero debes acceder a gcloud CLI con tu identidad federada.
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.
Para obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .
Java
Para usar las muestras de Java de esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad (IdP) externo, primero debes acceder a gcloud CLI con tu identidad federada.
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.
Para obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .
Node.js
Para usar las muestras de Node.js de esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad (IdP) externo, primero debes acceder a gcloud CLI con tu identidad federada.
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.
Para obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .
PHP
Para usar las muestras de PHP de esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad (IdP) externo, primero debes acceder a gcloud CLI con tu identidad federada.
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.
Para obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .
Python
Para usar las muestras de Python de esta página en un entorno de desarrollo local, instala e inicializa la gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad (IdP) externo, primero debes acceder a gcloud CLI con tu identidad federada.
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.
Para obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud .
-
Si planeas usar Google Cloud CLI, configura el proyecto predeterminado:
gcloud config set project PROJECT_IDAntes de ejecutar el comando anterior, reemplaza lo siguiente:
- PROJECT_ID: Es el identificador del proyecto. Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.
Enumera los tipos de canales de notificaciones
Monitoring proporciona varios tipos de canales de notificaciones integrados. Cada uno de estos tipos se describe en un NotificationChannelDescriptor.
Cada descriptor tiene un campo type cuyo valor identifica el tipo de canal cuando creas una instancia del canal. Para recuperar una lista de los tipos de canales que puedes crear con la API de Cloud Monitoring o Google Cloud CLI, ingresa el siguiente comando:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
Si no se admite tu canal de notificaciones preferido, considera crear una canalización que dependa del envío de tus notificaciones a Pub/Sub. Para ver un ejemplo en Python que usa Flask, consulta Crea notificaciones personalizadas con Cloud Monitoring y Cloud Run. Para ver otros ejemplos, consulta el repositorio de Git cloud-alerting-notification-forwarding.
Enumera todos los tipos de canales
Para recuperar todos los descriptores de canales en un proyecto de Google Cloud , usa el comandogcloud beta monitoring channel-descriptors list o el método de la API denotificationChannelDescriptors.list.
Los descriptores recuperados son de solo lectura.
gcloud beta monitoring channel-descriptors list
Si se ejecuta correctamente, el comando list proporciona una lista de todos los descriptores de canales del proyecto especificado. Por ejemplo, el descriptor de canal email aparece en la lista de la siguiente manera:
---
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
---
Todos los descriptores de canales incluyen estos campos:
name: Es el nombre del recurso completamente calificado del descriptor del canal.type: Es la parte del nombre que indica el tipo de canal.displayName: Es una descripción del campotypeque se muestra.description: Es una breve descripción del canal.labels: Un conjunto de campos específicos para un tipo de canal. Cada tipo de canal tiene su propio conjunto de etiquetas.
Cuando se crea un canal, también obtiene un campo enabled, con el valor true de forma predeterminada.
Cómo enumerar un tipo de canal específico
Si buscas un descriptor específico y conoces su nombre, usa gcloud beta monitoring channel-descriptors describe o el método de la API de notificationChannelDescriptors.get. El nombre de un descriptor de canal tiene el formato projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE].
[CHANNEL_TYPE] debe ser uno de los tipos enumerados anteriormente. Por ejemplo:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
Consulta las referencias gcloud beta monitoring channel-descriptors list y describe para obtener más información. El comando describe corresponde al método notificationChannelDescriptors.get en la API.
Crea un canal de notificaciones
Puedes crear canales de notificación para tus proyectos de Google Cloud desde archivos JSON o YAML con Google Cloud CLI, y también puedes crearlos de forma programática.
Para crear un canal de notificación, debes completar los valores de los campos de su descriptor. La mayoría, como type, son comunes en todos los descriptores de canales de notificaciones; consulta notificationChannelDescriptors.
Cada descriptor posee, además, un conjunto de etiquetas que varía de un descriptor a otro. Para ver el conjunto de etiquetas de un descriptor en particular, recupera el descriptor con el comando gcloud beta monitoring channel-descriptors describe que se describe en Cómo enumerar los tipos de canales de notificación.
Por ejemplo, cuando se recupera el descriptor de canal email, se muestra una sola etiqueta:
labels:
- description: An address to send email.
key: email_address
El descriptor del canal pubsub también contiene una sola etiqueta, que identifica el tema de Pub/Sub. Sin embargo, los canales pueden contener varios sellos. Por ejemplo, el descriptor de canal slack tiene dos etiquetas:
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
Cuando se recupera el descriptor de canal webhook_basicauth, se muestran varias etiquetas:
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
Ya sea que crees un canal nuevo de manera programática o desde la línea de comandos, el valor de type en tu especificación debe coincidir con el campo type en el descriptor de canal de notificaciones correspondiente. Las claves de etiquetas necesarias también deben coincidir con las del descriptor de canal.
Algunas etiquetas corresponden a las credenciales que se usan para autenticarse con el proveedor. Cuando se crea un canal, los valores para estas etiquetas deben obtenerse del proveedor. Para obtener una credencial, es posible que debas usar una página de generación de claves de API en el sitio web del proveedor o completar un flujo de acceso con OAuth con el proveedor. Los detalles específicos para obtener esa credencial dependen de cada proveedor.
Los canales están habilitados de manera predeterminada. Si deseas crear un canal inactivo, puedes incluir el campo enabled con el valor false.
Los siguientes ejemplos ilustran la creación de los canales de notificación.
Ejemplo: Crea un canal de notificaciones de Pub/Sub con gcloud CLI
Para crear un canal de notificaciones en un proyecto Google Cloud , usa el comando gcloud beta monitoring channels create. Para cargar el canal desde un archivo, usa la marca --channel-content-from-file para especificar el archivo.
Por ejemplo, a continuación, se muestra la especificación de un nuevo canal de notificación pubsub en JSON:
{
"type": "pubsub",
"displayName": "Notifications",
"description": "Pub/Sub channel for notifications",
"labels": {
"topic": "projects/[PROJECT_ID]/topics/notificationTopic"
},
}
El valor de type (pubsub) y la clave de etiqueta única (topic) coinciden con los campos type y labels.key del descriptor de canal correspondiente.
Con el siguiente ejemplo, se crea un nuevo canal de Pub/Sub desde el archivo pubsub-channel.json:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
Si se ejecuta correctamente, este comando devuelve el nombre del canal nuevo. Por ejemplo:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
Cuando crees un canal de notificación de pubsub, asegúrate de autorizar la cuenta de servicio de notificaciones para publicar en el tema. También ten en cuenta que, si el tema tiene una política de almacenamiento de mensajes o restricciones de residencia de datos, es posible que Monitoring no pueda publicar en él. Consulta el error FAILED_PRECONDITION.
Ejemplo: Crea un canal de notificaciones con bibliotecas cliente
En los siguientes ejemplos, se muestra cómo crear un canal de notificación con una biblioteca cliente:
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ejemplo: Crea un canal de notificaciones de Slack
Para configurar un canal de notificaciones para una app de Slack, haz lo siguiente:
Configura tu app de Slack:
- Si aún no tienes una app de Slack, sigue la documentación de referencia de Slack para crear una y, luego, instálala en tu espacio de trabajo.
- Configura tu app de Slack con permisos de OAuth para
chat:writeychat:write.public. - Copia el token de OAuth del usuario bot de la app.
Crea un archivo que defina la configuración de tu canal de notificaciones. Incluye una etiqueta en la que la clave
auth_tokentenga el valor del token de OAuth del usuario bot de tu app de Slack. Por ejemplo:{ "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }Ejecuta el siguiente comando para crear el canal de notificación:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
Enumera los canales de notificaciones de un proyecto
Para recuperar todos los canales de notificaciones en un proyecto Google Cloud , usa el método notificationChannels.list. Este método también admite las opciones filter y orderBy para restringir y ordenar los resultados. Consulta Ordenamiento y filtrado.
Si buscas un canal específico y sabes su nombre, puedes usar el método notificationChannels.get para recuperar solo ese canal. El nombre de un canal tiene el formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]. Por ejemplo:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Cuando recuperas un canal, los valores sensibles, como los tokens de autenticación y las claves de API, pueden ofuscarse por motivos de seguridad. Si copias un canal existente para crear uno nuevo, debes corregir los valores ofuscados.
gcloud
Para enumerar todos los canales de notificación en un proyecto de Google Cloud , usa el comandogcloud beta monitoring channels list:
gcloud beta monitoring channels list
Si se ejecuta de forma correcta, el comando list proporciona una lista de todos los canales del proyecto especificado. Por ejemplo, el comando anterior podría devolver una lista que incluya las siguientes entradas:
---
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
Para enumerar un solo canal, usa gcloud beta monitoring channels describe y especifica el nombre del canal.
Por ejemplo, este comando devuelve el canal de Pub/Sub que se muestra en la lista anterior:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Consulta las referencias gcloud beta monitoring channels list y describe para obtener más información. El comando describe corresponde al método notificationChannels.get en la API.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Borra un canal de notificación de un proyecto
Para borrar un canal de notificaciones de un proyecto Google Cloud , usa el método notificationChannels.delete y proporciona el nombre del canal de notificaciones que se borrará. El nombre de un canal es el valor del campo name, no el displayName, en la instancia de NotificationChannel.
El nombre de un canal tiene el formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]. Por ejemplo:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
De forma predeterminada, si intentas borrar un canal al que hace referencia una política de alertas, no se borrará el canal. Para forzar la eliminación de las referencias de las políticas de alertas y borrar el canal, establece la opción force en true. Esta opción quita automáticamente el canal de todas las políticas de referencia.
gcloud
Para borrar un canal de notificaciones, usa gcloud beta monitoring channels
delete y especifica el nombre del canal que deseas borrar. Por ejemplo, con el siguiente comando, se borra el canal email, que se creó en otro ejemplo:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Consulta la referencia de gcloud beta monitoring channels delete para obtener más información.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Cómo modificar un canal de notificaciones
Para modificar un canal de notificaciones, usa el método notificationChannels.patch (en la API de REST).
Otras implementaciones de la API y Google Cloud CLI llaman a este update en lugar de patch.
Una operación de actualización puede reemplazar el canal existente por completo o puede modificar un subconjunto de campos. Por ejemplo, puedes habilitar o inhabilitar el canal. La inhabilitación de un canal impide la entrega de notificaciones al canal. Si se pretende que el cambio sea temporal, por lo general, es más conveniente inhabilitar un canal que eliminarlo de las políticas de alertas que hacen referencia a él.
gcloud
Para habilitar un canal de notificaciones inhabilitado, usa el comando gcloud beta monitoring channels update y proporciona la marca --enabled. Con el siguiente comando, se habilita el canal de notificaciones email que se creó, en el estado inhabilitado, en un ejemplo anterior:
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
Para inhabilitar un canal de notificaciones, usa el mismo comando y proporciona la marca --no-enabled.
Consulta la referencia de gcloud beta monitoring channels update para obtener más información. El comando update corresponde al método notificationChannels.patch en la API de REST.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Cómo ver los registros del canal de notificaciones
Puedes usar el Explorador de registros para ver los errores del canal de notificaciones:
-
En la consola de Google Cloud , ve a la página Explorador de registros del :
Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.
Ingresa y ejecuta tu consulta. Para consultas específicas sobre errores del canal de notificaciones, consulta Consultas de Cloud Monitoring.