本文档介绍了如何通过 Google Cloud 控制台创建和管理通知渠道, 使用客户端库或使用 Google Cloud CLI 调用 Cloud Monitoring API。Cloud Monitoring 使用通知渠道 在提醒政策的条件发生时,通知您或随时待命的团队 。我们提供以下几种渠道类型:每种类型 (在通知渠道描述符中描述)。某种类型的通知渠道是该类型描述符的实例。 您的提醒政策包括对通知渠道的引用,这些通知渠道要用作通知路径。
通知渠道必须事先存在,才能用于提醒政策。 系统已经提供了通知渠道描述符,但您必须先创建渠道然后才能使用这些渠道。
如需使用 Google Cloud 控制台配置通知渠道,请参阅 创建和管理通知渠道。
本文档中使用的代码示例摘自 提醒政策 API 示例, 示例:备份和恢复中所述。
关于此 API
NotificationChannel
资源支持的操作可让您
管理通知渠道它还支持
管理频道的 verificationStatus
字段:
- 发送验证码
- 生成代码,用于将已验证渠道的验证状态复制到同一项目或新项目的其他相同渠道
- 使用前两个操作创建的代码验证渠道
如需了解详情,请参阅 notificationChannels
参考文档
文档。
准备工作
如需获取查看和配置通知渠道所需的权限,请使用 Cloud Monitoring API。
请让管理员授予您
项目的 Monitoring NotificationChannel Editor (roles/monitoring.notificationChannelEditor
) IAM 角色。
如需详细了解如何授予角色,请参阅管理访问权限。
如需详细了解 Cloud Monitoring 角色, 请参阅使用 Identity and Access Management 控制访问权限。
列出通知渠道的类型
Monitoring 提供了许多内置的通知渠道类型。每种类型都在 NotificationChannelDescriptor
中进行了介绍。这些描述符具有 type
字段,在创建该渠道类型的实例时,此字段的值将作为其标识符。要检索您可以使用
Cloud Monitoring API 或 Google Cloud CLI,请输入以下命令:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
如需详细了解通知渠道,请参阅 创建和管理通知渠道。
如果您的首选通知渠道不受支持,请考虑创建 一个依赖于向 Pub/Sub 发送通知的流水线。 如需查看使用 Flask 的 Python 示例,请参阅 使用 Cloud Monitoring 和 Cloud Run 创建自定义通知。 如需查看其他示例,请参阅 cloud-alerting-notification-forwarding Git 代码库。
如需检索 Google Cloud 项目中的所有渠道描述符,请使用
notificationChannelDescriptors.list
方法。
检索到的描述符均为只读。
如果您要查找特定描述符,并且知道其名称,则可以使用 notificationChannelDescriptors.get
方法仅检索该渠道描述符。渠道描述符名称的格式为 projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
[CHANNEL_TYPE]
必须是上面列出的类型之一,例如:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
如需列出 Google Cloud 项目中的所有通知渠道描述符,请执行以下操作:
使用 gcloud beta monitoring channel-descriptors list
命令:
gcloud beta monitoring channel-descriptors list
如果成功,该 list
命令将以列表显示指定项目中所有的渠道描述符。例如,email
渠道描述符在列表中显示为:
--- 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 ---
所有渠道描述符都包含以下字段:
name
:渠道描述符的完全限定资源名称type
:名称的一部分,用于表示渠道类型displayName
:type
字段的说明,用于显示目的description
:对渠道的简要说明labels
:一组专用于渠道类型的字段。每种渠道类型都有自己的一组标签。
创建渠道后,它还会获得一个 enabled
字段,默认值为 true
。
要列出单个渠道描述符,请使用 gcloud beta monitoring
channel-descriptors describe
,并指定渠道描述符的名称。您无需指定完全限定名称。例如,这两个命令都返回上面的列表:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
如需了解详情,请参阅 gcloud beta monitoring channel-descriptors
list
和 describe
参考。describe
命令对应于 API 中的 notificationChannelDescriptors.get
方法。
创建通知渠道
您可以为您的 Google Cloud 项目创建通知渠道 从 JSON 或 YAML 文件中提取 Google Cloud CLI,您可以通过编程方式创建它们。
要创建通知渠道,必须为其描述符中的字段提供值。其中大多数字段在所有通知渠道描述符中都很常见,如 type
;请参阅 notificationChannelDescriptors
。
每个描述符均有一组标签,且各不相同。要查看特定描述符的标签集,请检索
使用 gcloud beta monitoring channel-descriptors describe
指定描述符
列出通知渠道的类型中描述的命令。
例如,检索 email
渠道描述符会显示单个标签:
labels: - description: An address to send email. key: email_address
pubsub
渠道描述符还包含单个标签;这个标签
标识 Pub/Sub 主题。不过,渠道可以包含多个
标签。例如,slack
渠道描述符有两个标签:
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
检索 webhook_basicauth
渠道描述符会显示多个标签:
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
无论您以编程方式还是通过命令行创建新渠道,规范中 type
的值都必须与相应通知渠道描述符中的 type
字段匹配。任何必需的标签键也必须与渠道描述符中的字段相匹配。
一些标签对应着用来对提供商进行身份验证的凭据。 创建渠道时,系统必须从提供商获取这些标签的值。 获取凭据可能涉及使用 API 密钥生成页面 或完成与提供方的 OAuth 登录流程。 获得这种凭据的方式的具体情况取决于特定的提供商。
例如,下面显示了新 pubsub
的规范
采用 JSON 格式的通知渠道:
{ "type": "pubsub", "displayName": "Notifications", "description": "Pub/Sub channel for notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
type
值(pubsub
)和单个标签键(topic
)匹配相应渠道描述符中的 type
和 labels.key
字段。
默认情况下,渠道处于启动状态。如果您要创建无效渠道,可以在字段 enabled
中添加值 false
。
下面举例说明了创建通知渠道的过程。
gcloud
如需在 Google Cloud 项目中创建通知渠道,请使用 gcloud beta monitoring
channels create
命令。要从文件加载通道,请使用 --channel-content-from-file
标志指定文件。
以下示例从 pubsub-channel.json
文件创建新的 Pub/Sub 渠道:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
如果成功,此命令将返回新渠道的名称,例如:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
如需了解详情,请参阅 gcloud beta monitoring channels create
参考文档。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
示例:创建 Slack 通知渠道
如需为 Slack 应用配置通知渠道,请执行以下操作:
配置您的 Slack 应用:
- 如果您还没有 Slack 应用,请按照 Slack 参考文档:用于创建和安装 Slack 复制到您的工作区。
- 为 Slack 应用配置 OAuth 范围
chat:write
和chat:write.public
。 - 复制应用的聊天机器人用户 OAuth 令牌。
创建一个文件,用于定义通知渠道的配置。 添加一个标签,其中
auth_token
键包含 Slack 应用的聊天机器人用户 OAuth 令牌的值。例如:{ "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }
运行以下命令以创建通知渠道:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
列出项目中的通知渠道
如需检索 Google Cloud 项目中的所有通知渠道,请使用
notificationChannels.list
方法。此方法还支持使用 filter
和 orderBy
选项对结果进行限制和排序;具体请参阅排序和过滤。
如果您要查找特定渠道且知道该渠道名称,可使用 notificationChannels.get
方法仅检索该渠道。渠道名称的格式为 projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
,例如:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
检索渠道时,出于安全原因,系统可能会对身份验证令牌和 API 密钥等敏感值进行模糊处理。如果通过复制现有渠道来创建新渠道,则需要更正任何模糊处理的值。
gcloud
如需列出 Google Cloud 项目中的所有通知渠道,请使用
gcloud beta monitoring channels list
命令:
gcloud beta monitoring channels list
如果成功,list
命令将以列表形式显示指定项目中的所有渠道。例如,以上命令可能会返回包含以下条目的列表:
--- 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
要列出单个渠道,请使用 gcloud beta monitoring
channels describe
,然后指定渠道名称。
例如,此命令会返回上述列表中显示的 Pub/Sub 通道:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
如需了解详情,请参阅 gcloud beta monitoring channels list
和 describe
参考。describe
命令对应于 API 中的 notificationChannels.get
方法。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
从项目中删除通知渠道
如需从 Google Cloud 项目中删除通知渠道,请使用
notificationChannels.delete
方法,并提供名称
要删除的通知渠道。渠道的名称是
在 NotificationChannel
实例中,是 name
字段,而不是 displayName
。
渠道名称的格式为 projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
,例如:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
默认情况下,如果您尝试删除某个被
提醒政策,那么通道不会被删除。要强制移除提醒政策的引用,并删除渠道,请将 force
选项设置为 true
。 此选项会自动将该频道从所有
引用政策。
gcloud
要删除通知渠道,请使用 gcloud beta monitoring channels
delete
,然后指定要删除的渠道的名称。例如,以下命令会删除在另一示例中创建的 email
渠道:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
请参阅
gcloud beta monitoring channels delete
参考资料。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
修改通知渠道
要修改通知渠道,请使用 REST API 中的 notificationChannels.patch
方法。其他 API 实现和 Google Cloud CLI 称之为 update
,而不是 patch
。
更新操作可以完全替换现有的渠道,也可以修改其中一部分字段。例如,您可以启用或停用渠道。 停用渠道会阻止通知发送到该渠道。 通常情况下,如果只是想暂时不使用某渠道,则将被提醒政策引用的渠道停用比将其删除更简便一些。
gcloud
要启用已停用的通知渠道,请使用 gcloud beta monitoring channels update
命令并提供 --enabled
标志。以下命令可启用在上一示例中创建的 email
通知渠道(处于停用状态):
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
要停用政策,请使用同一命令并提供 --no-enabled
标志。
如需了解详情,请查看 gcloud beta monitoring channels update
参考。 update
命令与 REST API 中的 notificationChannels.patch
方法相对应。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
查看通知渠道日志
您可以使用日志浏览器查看通知渠道错误:
-
在 Google Cloud 控制台中,转到 Logs Explorer 页面。
如果您使用搜索栏查找此页面,请选择子标题为 Logging 的结果。
输入并运行您的查询。对于 通知渠道错误,请参阅 Cloud Monitoring 查询。