Este documento descreve como criar e gerenciar canais de notificação usando bibliotecas de cliente ou a Google Cloud CLI, ambos invocar a API Cloud Monitoring. O Cloud Monitoring usa canais de notificação notificar você ou sua equipe de plantão quando a condição de uma política de alertas é cumprida. Há vários tipos de canal disponíveis: cada tipo é em um descritor do canal de notificação. Um canal de um determinado tipo é uma instância do descritor desse tipo. Entre as políticas de alertas estão referências para os canais de notificação a serem usadas como caminhos de notificação.
Um canal de notificação precisa existir para ser usado em uma política de alertas. Os descritores do canal de notificação são fornecidos, mas você precisa criar os canais para que possam ser usados.
Para configurar canais de notificação usando o console do Google Cloud, consulte Criar e gerenciar canais de notificação.
Os exemplos de código usados neste documento foram extraídos do exemplo da API de política de alertas, descritos em Exemplo: backup e restauração.
Sobre a API
O recurso NotificationChannel
oferece suporte a operações que permitem
gerenciar seus canais de notificação. Ele também oferece suporte a operações relacionadas
gerenciar o campo verificationStatus
de um canal:
- Envio de um código de verificação
- Geração de um código para copiar o status da verificação de um canal verificado para outros canais idênticos no mesmo projeto ou em um novo
- Verificação do canal usando o código criado pelas duas operações anteriores
Para mais informações, consulte a referência notificationChannels
.
documentos.
Antes de começar
Para receber as permissões necessárias para visualizar e configurar canais de notificação usando a API Cloud Monitoring:
peça ao administrador para conceder a você
Papel do IAM Editor do canal de notificação do Monitoring (roles/monitoring.notificationChannelEditor
) no projeto.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.
Para mais informações sobre os papéis do Cloud Monitoring, consulte Controlar o acesso com o Identity and Access Management.
Listar os tipos de canais de notificação
O Monitoring fornece vários tipos de canais de notificação integrados. Cada um desses tipos é descrito em NotificationChannelDescriptor
.
Esses descritores têm um campo type
, e o valor desse campo funciona como um identificador para ele durante a criação de instâncias desse tipo de canal. Você pode recuperar os tipos de canal disponíveis, consulte as
geralmente em Criar e gerenciar canais de notificação,
pelo seguinte comando:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
Caso o canal de notificação de sua preferência não seja aceito, considere criar um pipeline que depende do envio das notificações para o Pub/Sub. Para um exemplo de Python que usa Flask, consulte Como criar notificações personalizadas com o Cloud Monitoring e o Cloud Run Para outros exemplos, consulte a repositório Git cloud-alerting-notification-forwarding.
Para recuperar todos os descritores de canal em um projeto do Google Cloud, use o
método notificationChannelDescriptors.list
.
Os descritores recuperados são somente leitura.
Se você estiver procurando por um descritor específico e souber o nome dele, poderá usar o método notificationChannelDescriptors.get
para recuperar apenas esse descritor de canal. O nome de um descritor de canal tem o formato projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
[CHANNEL_TYPE]
deve ser um dos tipos listados acima, por exemplo:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
Para listar todos os descritores do canal de notificação em um projeto do Google Cloud,
Use o comando gcloud beta monitoring channel-descriptors list
:
gcloud beta monitoring channel-descriptors list
Se bem-sucedido, o comando list
fornecerá uma listagem de todos os descritores de canal no projeto especificado. Por exemplo, o descritor de canal email
aparece na lista da seguinte forma:
--- 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 os descritores de canais incluem estes campos:
name
: o nome de recurso totalmente qualificado do descritor de canaltype
: a parte do nome que indica o tipo de canaldisplayName
: uma descrição do campotype
, para fins de exibiçãodescription
: uma breve descrição do canallabels
: um conjunto de campos específicos para um tipo de canal. Cada tipo de canal tem seu próprio conjunto de rótulos.
Quando um canal é criado, ele também recebe um campo enabled
, com o valor true
por padrão.
Para listar um descritor de único canal, use gcloud beta monitoring
channel-descriptors describe
, em vez disso, e especifique o nome do descritor de canal. Você não precisa especificar o nome totalmente qualificado. Por exemplo, ambos os comandos retornam a listagem acima:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
Consulte as referências gcloud beta monitoring channel-descriptors
list
e describe
para mais informações. O comando describe
corresponde ao método notificationChannelDescriptors.get
na API.
Criar um canal de notificação
É possível criar canais de notificação para seus projetos do Google Cloud de arquivos JSON ou YAML Google Cloud CLI, e você pode criá-las de maneira programática.
Para criar um canal de notificação, você precisa fornecer valores para os campos no descritor. A maioria deles, como type
, são comuns a todos os descritores de canal de notificação; veja notificationChannelDescriptors
.
Cada descritor também tem um conjunto de rótulos, e esse conjunto varia entre os descritores. Para ver o conjunto de rótulos de um descritor específico, recupere
o descritor usando gcloud beta monitoring channel-descriptors describe
.
descrito em Listar os tipos de canais de notificação.
Por exemplo, a recuperação do descritor de canal email
mostra um único rótulo:
labels: - description: An address to send email. key: email_address
O descritor de canal pubsub
também contém um único rótulo. esse marcador
identifica o tópico do Pub/Sub. No entanto, os canais podem conter várias
rótulos. Por exemplo, o descritor de canal slack
tem dois rótulos:
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
A recuperação do descritor de canal webhook_basicauth
mostra diversos rótulos:
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
Se você criar um novo canal de forma programática ou a partir da linha de comando, o valor de type
em sua especificação deve corresponder ao campo type
no descritor de canal de notificação correspondente. Todas as chaves de rótulo obrigatórias também precisam corresponder àquelas no descritor de canais.
Alguns rótulos correspondem às credenciais usadas na autenticação com o provedor. Durante a criação de um canal, os valores desses rótulos precisam ser recebidos do provedor. Conseguir uma credencial pode envolver o uso de uma página de geração de chaves de API no site do provedor ou concluindo um fluxo de login OAuth com o provedor. As especificidades de como receber essa credencial dependem do provedor específico.
Por exemplo, o exemplo abaixo mostra a especificação de um novo pubsub
canal de notificação em JSON:
{ "type": "pubsub", "displayName": "Notifications", "description": "Pub/Sub channel for notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
O valor type
(pubsub
) e a chave de rótulo única (topic
) correspondem aos campos type
e labels.key
no descritor de canais correspondente.
Os canais são ativados por padrão. Se você quiser criar um canal inativo, inclua o campo enabled
com o valor false
.
Nos exemplos a seguir, veja a criação de canais de notificação.
gcloud
Para criar um canal de notificação em um projeto do Google Cloud, use o comando gcloud beta monitoring
channels create
. Para carregar o canal a partir de um arquivo, use a sinalização --channel-content-from-file
para especificar o arquivo.
O exemplo a seguir cria um novo canal do Pub/Sub a partir do arquivo pubsub-channel.json
:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
Se bem-sucedido, este comando retornará o nome do novo canal. Por exemplo:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
Consulte a referência gcloud beta monitoring channels create
para mais informações.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Exemplo: criar um canal de notificação do Slack
Para configurar um canal de notificação para um aplicativo Slack, faça o seguinte:
Configure o aplicativo Slack:
- Se você ainda não tem um aplicativo Slack, siga as Documentação de referência do Slack para criar e instalar ao seu espaço de trabalho.
- Configurar o aplicativo Slack com escopos OAuth para
chat:write
echat:write.public
- Copie o token de OAuth do usuário de bot do app.
Crie um arquivo que defina a configuração do seu canal de notificação. Inclua um rótulo em que a chave
auth_token
tenha o do token de OAuth do usuário de bot do aplicativo do Slack. Exemplo:{ "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }
Execute o seguinte comando para criar o canal de notificação:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
Listar canais de notificação em um projeto
Para recuperar todos os canais de notificação em um projeto do Google Cloud, use o
método notificationChannels.list
. Esse método também suporta as opções filter
e orderBy
para restringir e classificar os resultados. Consulte Classificação e filtragem.
Se você estiver procurando um canal específico e souber o nome dele, use o método notificationChannels.get
para recuperar apenas esse canal. O nome de um canal tem o formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, por exemplo:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Quando você recupera um canal, valores confidenciais, como tokens de autenticação e chaves de API, podem ficar ocultos por motivos de segurança. Se você estiver criando um novo canal copiando um atual, todos os valores ocultos precisarão ser corrigidos.
gcloud
Para listar todos os canais de notificação em um projeto do Google Cloud, use o
Comando gcloud beta monitoring channels list
:
gcloud beta monitoring channels list
Se bem-sucedido, o comando list
fornece uma listagem de todos os canais no projeto especificado. Por exemplo, o comando acima pode retornar uma lista que inclui as seguintes 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 listar um único canal, use gcloud beta monitoring
channels describe
, e especifique o nome do canal.
Por exemplo, este comando retorna o canal do Pub/Sub mostrado na listagem acima:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Consulte as referências gcloud beta monitoring channels list
e describe
para mais informações. O comando describe
corresponde ao método notificationChannels.get
na API.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Excluir um canal de notificação de um projeto
Para excluir um canal de notificação de um projeto do Google Cloud, use o
notificationChannels.delete
e forneça o nome
do canal de notificação a ser excluído. O nome de um canal é o valor do campo name
, não o displayName
, na instância NotificationChannel
.
O nome de um canal tem o formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, por exemplo:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Por padrão, se você tentar excluir um canal que é referenciado por um
política de alertas, o canal não será excluído. Para forçar a remoção de referências das políticas de alertas e excluir o canal, defina a opção force
como true
. Essa opção remove automaticamente o canal de todos os
políticas de referência.
gcloud
Para excluir um canal de notificação, use gcloud beta monitoring channels
delete
e especifique o nome do canal a ser excluído. Por exemplo, o comando a seguir exclui o canal email
criado em outro exemplo:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Consulte a referência gcloud beta monitoring channels delete
para mais informações.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Modificar um canal de notificação
Para modificar um canal de notificação, use o método notificationChannels.patch
(na API REST).
Outras implementações de API e a Google Cloud CLI chamam este update
em vez de patch
.
Uma operação de atualização pode substituir todo o canal existente ou modificar um subconjunto de campos. Por exemplo, ative e desative o canal. Desativar um canal evita a entrega de notificações para o canal. Desativar um canal costuma ser mais prático do que removê-lo das políticas de alertas que se referem a ele, caso a alteração seja temporária.
gcloud
Para ativar um canal de notificação desativado, use o comando gcloud beta monitoring channels update
e forneça a sinalização --enabled
. O comando a seguir ativa o canal de notificação email
criado, no estado desativado, em um exemplo anterior:
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
Para desativar uma política, use o mesmo comando e forneça a sinalização --no-enabled
.
Consulte a referência gcloud beta monitoring channels update
para mais informações. O comando update
corresponde ao método notificationChannels.patch
na API REST.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ver registros do canal de notificação
Use a Análise de registros para conferir os erros do canal de notificação:
-
No console do Google Cloud, acesse a página Análise de registros:
Acessar a Análise de registros
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.
Insira e execute sua consulta. Para consultas específicas de erros do canal de notificação, consulte Consultas do Cloud Monitoring.