Por lo general, las políticas de alertas tienen alguna forma de informarte que se activaron. Estas formas de informar se llaman canales de notificación. Hay varios tipos de canales disponibles; cada tipo se explica en un descriptor de canal de notificación. Un canal de notificación de un cierto tipo es una instancia del descriptor de ese tipo. Tus políticas de alertas incluyen referencias a los canales de notificación que se usan como vías de notificación.
Para que un canal de notificación pueda ser utilizado en una política de alertas, primero debe existir. Ya se te proporcionan los descriptores de canal de notificación, pero debes crear los canales para poder usarlos.
Los ejemplos de código que se usan aquí se toman del ejemplo de la API de política de alertas, descrito en Ejemplo: Copia de seguridad y restablecimiento.
Descriptores de canal
Monitoring proporciona varios tipos de canales de notificaciones integrados. Cada uno de estos tipos se describe en un NotificationChannelDescriptor
.
Estos descriptores tienen un campo type
, y el valor de este campo actúa como su identificador cuando se crean instancias de ese tipo de canal. Puedes recuperar los tipos de canales disponibles, que se describen de forma más general en Opciones de notificación, con el siguiente comando:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
Para recuperar todos los descriptores de canales de un proyecto, usa el método notificationChannelDescriptors.list
.
Los descriptores recuperados son de solo lectura.
Si buscas un descriptor específico y sabes su nombre, puedes usar el método notificationChannelDescriptors.get
para recuperar solo ese descriptor. El nombre de un descriptor de canal debe tener el formato projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
[CHANNEL_TYPE]
, como uno de los tipos que se mencionan antes, por ejemplo:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
Para mostrar la lista de todos los descriptores de canales de notificaciones en un proyecto, usa el comando gcloud beta monitoring channel-descriptors list
:
gcloud beta monitoring channel-descriptors list
Si se ejecuta de forma correcta, el comando list
proporciona una lista de todos los descriptores de canales en el 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
: El nombre de recurso completamente calificado del descriptor de canalestype
: La parte del nombre que indica el tipo de canaldisplayName
: Una descripción del campotype
. Se usa para fines de visualización.description
: Una descripción breve 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.
Para mostrar un descriptor de un solo canal, usa gcloud beta monitoring
channel-descriptors describe
y especifica el nombre del descriptor. No es necesario que especifique el nombre completo. Por ejemplo, ambos comandos muestran la lista anterior:
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.
Canales de notificación
Un canal de notificación es una instancia de uno de los descriptores de canal de notificación analizados en Descriptores de canal.
El recurso NotificationChannel
admite las siguientes operaciones:
- Crear canales nuevos
- Borrar canales existentes
- Recuperar canales específicos
- Recuperar todos los canales
- Modificar los canales existentes
Hay otras tres 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
Consulta la referencia de notificationChannels
para obtener más información al respecto.
Crea canales
Puedes crear canales de notificaciones desde archivos JSON o YAML con la herramienta de línea de comandos de gcloud
y puedes hacerlo de manera 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 Descriptores de canales. 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
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 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. Obtener una credencial puede implicar el uso de una página para generar claves de API en el sitio web del proveedor o completar un flujo de acceso de OAuth con el proveedor. Los detalles específicos para obtener esa credencial dependen de cada proveedor.
Por ejemplo, a continuación se muestra la especificación de un nuevo canal de notificaciones pubsub
en JSON:
{ "type": "pubsub", "displayName": "Alert notifications", "description": "Pub/Sub channel for alert notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
El valor type
(pubsub
) y la clave de una sola etiqueta (topic
) coinciden con los campos type
y labels.key
en el descriptor de canal correspondiente.
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.
gcloud
Para crear un canal de notificaciones en un proyecto, usa el comando gcloud beta monitoring
channels create
. Si deseas cargar el canal desde un archivo, usa la marca --channel-content-from-file
para especificarlo.
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 funciona, este comando muestra el nombre del canal nuevo, por ejemplo:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
Consulta la referencia de gcloud beta monitoring channels create
para obtener más información.
C#
Node.js
Go
Java
PHP
Python
Recuperación de canales
Para recuperar todos los canales de notificaciones de un proyecto, usa el método notificationChannels.list
. Este método también admite opciones filter
y orderBy
para restringir y ordenar los resultados; consulta Ordena y filtra.
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 notificaciones en un proyecto, usa el comando gcloud 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, puede que el comando anterior muestre una lista que incluye 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 alert notifications displayName: Alert notifications enabled: true labels: topic: projects/[PROJECT_ID}/topics/notificationTopic name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: pubsub
Para mostrar un solo canal, usa gcloud beta monitoring
channels describe
y especifica el nombre del canal.
Por ejemplo, este comando muestra 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#
Node.js
Go
Java
PHP
Python
Borrar canales
Para borrar un canal de notificaciones de un proyecto, usa el método notificationChannels.delete
y proporciona el nombre del canal de notificaciones que deseas borrar. El nombre de un canal es el valor del campo name
, no de displayName
, en la instancia 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, este no se borrará. 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
.
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#
Go
Java
PHP
Node.js
Python
Modificación de canales
Para modificar un canal de notificaciones, usa el método notificationChannels.patch
(en la API de REST).
Otras implementaciones de la API y la herramienta de línea de comandos de gcloud
llaman a esto 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 que esté 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 una política, 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#
Go
Node.js
Java
PHP
Python