26. 通知¶

26.1. 通知层次结构¶

在某些级别分配的通知模板将继承在父对象上定义的模板，如下所述：

• 作业模板将使用在其上定义的通知模板，以及从作业模板使用的项目中和列出了该作业模板的机构中继承通知模板（通过项目）。

• 项目更新将使用项目上定义的通知模板，并将继承与其关联的机构中的通知模板

• 清单更新将使用列出了该清单的机构上定义的通知模板

• 临时命令将使用与清单关联的机构上定义的通知模板

26.2. 工作流¶

当作业成功或失败时，错误或成功处理程序将按照以上定义的流程拉取相关的通知模板列表。然后，它会为每个包含作业相关详情的通知模板创建一个通知对象，然后将其发送到目的地（电子邮件地址、slack 频道、sms 号码等）。这些通知对象可作为作业类型（作业、库存更新、项目更新）的相关资源提供，也位于 /api/v2/notifications。您还可以通过检查通知模板的相关资源来查看由其发送的通知。

如果通知失败，它将不影响与其关联的作业，或导致作业失败。通知的状态可以在详情端点 (/api/v2/notifications/<n>) 中查看。

26.3. 创建通知模板¶

要创建通知模板，请执行以下操作：

1. 从左侧导航栏中点击 Notifications。

2. 点 Add 按钮。

3. 在相应字段中输入通知名称和描述，并指定其所属机构（必需）。

4. 从 Type 下拉菜单中选择一种通知类型。如需了解更多信息，请参阅后续部分。

5. 完成所有所需信息后，点击 Save 添加通知。

26.4. 通知类型¶

automation controller 支持的通知类型：

以上每一种通知都有自己的配置和行为性语义，并需要以不同的方式对其进行测试。此外，您可以自定义每种通知类型的具体细节，或一组触发通知的条件。如需了解更多有关配置自定义通知的详情，请参阅 创建自定义通知。以下几个部分将尽量详细介绍每种通知类型。

26.4.1. 电子邮件¶

电子邮件通知类型支持各种 SMTP 服务器，并支持 TLS/SSL 连接。

您必须提供以下详情来设置电子邮件通知：

• 主机

• 接收者列表

• 发件人电子邮件

• 端口

• Timeout（以秒为单位）：允许您指定 automation controller 在放弃前可以尝试连接电子邮件服务器的时间限度，最多 120 秒。

26.4.2. Grafana¶

Grafana 是一个简单直接的集成。首先，在 Grafana system 中创建一个 API 密钥（这是提供给 automation controller 的令牌）。

您必须提供以下详情来设置 Grafana 通知：

• Grafana URL：Grafana API 服务的 URL，通常为 http://yourcompany.grafana.com。

• Grafana API Key：用户必须首先在 Grafana 系统中创建一个 API 密钥（这是提供给 automation controller 的令牌）。

其他值得注意的选项有：

• ID of the Dashboard：当您为 Grafana 帐户创建 API 密钥时，您可以设置具有其自身唯一 ID 的仪表板。

• ID of the Panel：如果您在 Grafana 界面中添加了面板和图形，您可以在这里指定其 ID。

• Annotation：输入关键字，以帮助识别您要配置的事件的类型。

• Disable SSL Verification：默认情况下 SSL 验证是开启的，但您可以选择关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

26.4.3. IRC¶

IRC 通知采用 IRC bot 的形式，它将进行连接，将消息传送到频道或单独的用户，然后断开连接。通知 bot 还支持 SSL 身份验证。bot 目前不支持 Nickserv 身份识别。如果某个频道或用户不存在或者没有在线，则通知不会失败。通知失败仅用于代表连接失败。

连接信息很简单：

• IRC Server Password（可选）：IRC 服务器可以要求提供密码才能连接。如果服务器不需要密码，请保留空白

• IRC Server Port：IRC 服务器端口

• IRC Server Address：IRC 服务器的主机名或地址

• IRC Nick：bot 连接到服务器显示的昵称

• Destination Channels or Users：要将通知发送到的用户和/或频道列表。

• SSL Connection（可选）：bot 是否应使用 SSL 进行连接

26.4.4. Mattermost¶

Mattermost 通知类型为 Mattermost 的消息和协作工作区提供了一个简单的接口。可以指定的参数有：

• Target URL（必需）：将 POST 到的完整 URL

• 用户名

• 频道

• Icon URL：指定要为此通知显示的图标

• Disable SSL Verification：关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

26.4.5. PagerDuty¶

PagerDuty 是一个简单直接的集成。首先，在 PagerDuty system 中创建一个 API 密钥（这是提供给 automation controller 的令牌），然后创建一个“Service”，它提供的“Integration Key”也会提供给 automation controller。其他必需的选项为：

• API Token：用户必须首先在 PagerDuty 系统中创建一个 API 密钥（这是提供给 automation controller 的令牌）。

• PagerDuty Subdomain：当您注册 PagerDuty 帐户时，您会收到一个用来进行通信的唯一子域。例如，如果您以“testuser”身份注册，Web 仪表板将位于 testuser.pagerduty.com，并且您将提供 API testuser 作为子域（而非完整的域）。

• API 服务/集成密钥

• Client Identifier：这将与警报内容一同发送到 pagerduty 服务，以帮助识别使用 api 密钥/服务的服务。这在多个集成使用相同的 API 密钥和服务时很有用。

26.4.6. Rocket.Chat¶

Rocket.Chat 通知类型为 Rocket.Chat 的协作和通信平台提供了一个接口。可以指定的参数有：

• Target URL（必需）：将 POST 到的完整 URL

• 用户名

• Icon URL：指定要为此通知显示的图标

• Disable SSL Verification：关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

26.4.7. Slack¶

Slack 是一个协作团队通讯和消息传输工具，可以轻松进行配置。

您必须提供以下内容来设置 Slack 通知：

• Slack app（请参考 Slack `Basic App Setup <https://api.slack.com/authentication/basics>`文档的_ 页来获得如何创建）

• 令牌（请参考 Enabling Interactions with Bots <https://api.slack.com/bot-users> Token Types 文档页面中的 bot 令牌的详情）

在设置了 bot/app 后，导航到"Your Apps"，点新创建的应用，进入 Add features and functionality 来配置传入的 webhook、bot 和权限，并 在工作空间中按照应用。

您还必须邀请通知 bot 加入与 Slack 相关的频道。请注意，不支持私人消息。

26.4.8. Twilio¶

Twilio 服务是一个语音和 SMS 自动化服务。在您登录后，必须创建一个用来发送消息的电话号码。然后您以在 Programmable SMS 下定义一个“Messaging Service”并将您之前创建的号码与之关联。

请注意，在被允许使用此号码发送到任意号码前，您可能需要先验证它或一些其他信息。消息服务不需要状态回调 URL，它也不需要具备处理入站消息的功能。

在您的单独（或子）帐户设置中，您将有 API 凭证。Twilio 使用两个凭证来确定 API 请求来自哪个帐户：用作用户名的“Account SID”，以及用作密码的“Auth Token”。

要设置 Twilio，请提供以下详情：

• 帐户令牌

• Source Phone Number（这是与上述消息服务关联的号码，必须采用“+15556667777”的格式）

• Destination SMS number（这是接收 SMS 的号码列表，应该是 10 位电话号码）

• 帐户 SID

26.4.9. Webhook¶

webhook 通知类型提供了一个用于将 POST 发送到预定义的 Web 服务的简单接口。automation controller 将使用应用程序/json 内容类型向这个地址 POST 数据有效负载，其中包含 json 格式的所有相关详情。一些 Web 服务 API 预期 HTTP 请求采用特定格式并包含特定字段。您可以使用以下方法配置更多 webhook 通知设置：

• 配置 HTTP 方法（使用 POST 或 PUT）

• 传出请求的正文

• 配置身份验证（使用基本身份验证）

用于配置 Webhook 的参数有：

• 用户名

• 基本验证密码

• Target URL（必需）：Webhook 通知将 PUT 或 POST 到的完整 URL。

• Disable SSL Verification：默认情况下 SSL 验证是开启的，但您可以选择关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

• HTTP Headers（必需）：JSON 格式的标头，其中键和值是字符串。例如：{"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}

• HTTP Method（必需）。选择 Webhook 的方法：

  • POST：创建新资源。也用作不适合于其他类别的操作的总括。除非您知道 Webhook 服务需要 PUT，否则很可能需要 POST。

  • PUT：更新特定资源（按标识符）或资源集合。如果事先知道资源标识符，PUT 也可以用于创建特定资源。

26.4.9.1. Webhook 有效负载¶

Automation controller 默认情况下，在 Webhook 端点发送以下数据：

job id
name
url
created_by
started
finished
status
traceback
inventory
project
playbook
credential
limit
extra_vars
hosts
http method

automation controller 返回的通过 Webhook 消息的 started 通知示例：

{"id": 38, "name": "Demo Job Template", "url": "https://host/#/jobs/playbook/38", "created_by": "bianca", "started":
"2020-07-28T19:57:07.888193+00:00", "finished": null, "status": "running", "traceback": "", "inventory": "Demo Inventory",
"project": "Demo Project", "playbook": "hello_world.yml", "credential": "Demo Credential", "limit": "", "extra_vars": "{}",
"hosts": {}}POST / HTTP/1.1

默认情况下，对于 success/fail 状态的 Webhook 端点，Automation controller 返回以下数据：

job id
name
url
created_by
started
finished
status
traceback
inventory
project
playbook
credential
limit
extra_vars
hosts

由 automation controller 返回的、通过 webhook 消息的 success/fail 通知示例：

{"id": 46, "name": "AWX-Collection-tests-awx_job_wait-long_running-XVFBGRSAvUUIrYKn", "url": "https://host/#/jobs/playbook/46",
"created_by": "bianca", "started": "2020-07-28T20:43:36.966686+00:00", "finished": "2020-07-28T20:43:44.936072+00:00", "status": "failed",
"traceback": "", "inventory": "Demo Inventory", "project": "AWX-Collection-tests-awx_job_wait-long_running-JJSlglnwtsRJyQmw", "playbook":
"fail.yml", "credential": null, "limit": "", "extra_vars": "{\"sleep_interval\": 300}", "hosts": {"localhost": {"failed": true, "changed": 0,
"dark": 0, "failures": 1, "ok": 1, "processed": 1, "skipped": 0, "rescued": 0, "ignored": 0}}}

26.5. 创建自定义通知¶

您可以通过使用切换按钮在通知表单的底部启用 Customize Messages 部分来为每个 通知类型 customize the text content。

您可以为各种作业事件提供自定义消息：

• 开始

• 成功

• 错误

• 工作流已批准

• 工作流已拒绝

• 工作流正在运行

• 工作流超时

消息表单会根据您所配置的通知类型而有所不同。例如，电子邮件和 PagerDuty 通知的消息会显示一个带有主题和正文的典型电子邮件表单，在这种情况下，automation controller 会将这些字段显示为 Message 和 Message Body。其他通知类型对每种事件类型只预期 Message：

Message 字段已预先填充一个模板，其中包含顶层变量 job 以及一个属性，如 id 或 name。模板用大括号括起，且可以从 automation controller 提供的固定字段集合中提取，如预填充的 Messages 字段所示。

这个预先填充的字段会建议通常向事件通知的接收者显示的消息。但是，您可以根据需要为作业添加您自己的属性，以使用不同的条件自定义这些消息。自定义通知消息使用 Jinja 呈现，这是 Ansible playbook 使用的同一模板引擎。

消息和消息正文具有不同的内容类型：

• 信息总是字符串（只能是一行；不允许使用新行）

• 消息正文可以是字典或者是文本块：

  • Webhooks 和 PagerDuty 的消息正文使用字典定义。它们的默认消息正文为 {{ job_metadata }}，您可以保留原样或者提供自己的字典

  • 电子邮件的消息正文使用文本块或多行字符串。默认的消息正文为：

  {{ job_friendly_name }} #{{ job.id }} had status {{ job.status }}, view details at {{ url }} {{ job_metadata }}
  

  您可以调整此文本（保留 {{ job_metadata }} 或将 {{ job_metadata }} 全盘丢弃）。由于正文是一个文本块，它实际上可以是您需要的任何字符串。

  {{ job_metadata }} 呈现为一个字典，其中包含描述待执行作业的字段。在所有情况下，{{ job_metadata }} 都将包括以下字段：

  • id

  • name

  • url

  • created_by

  • started

  • finished

  • status

  • traceback

  注解

  目前，您无法查询 {{ job_metadata }} 中的各个字段。在通知模板中使用 {{ job_metadata }} 时，所有数据都会被返回。

  生成的字典将类似如下：

  {"id": 18,
   "name": "Project - Space Procedures",
   "url": "https://host/#/jobs/project/18",
   "created_by": "admin",
   "started": "2019-10-26T00:20:45.139356+00:00",
   "finished": "2019-10-26T00:20:55.769713+00:00",
   "status": "successful",
   "traceback": ""
  }
  

  如果 {{ job_metadata }} 在作业中呈现，它将包括以下附加字段：

  • inventory

  • project

  • playbook

  • credential

  • limit

  • extra_vars

  • hosts

  
  

  生成的字典将类似如下：

  {"id": 12,
   "name": "JobTemplate - Launch Rockets",
   "url": "https://host/#/jobs/playbook/12",
   "created_by": "admin",
   "started": "2019-10-26T00:02:07.943774+00:00",
   "finished": null,
   "status": "running",
   "traceback": "",
   "inventory": "Inventory - Fleet",
   "project": "Project - Space Procedures",
   "playbook": "launch.yml",
   "credential": "Credential - Mission Control",
   "limit": "",
   "extra_vars": "{}",
   "hosts": {}
  }
  

  如果 {{ job_metadata }} 在工作流作业中呈现，它将包括以下附加字段：

  • ``body``（这将枚举工作流作业中的所有节点，并包含与每个节点关联的作业描述）

  
  

  生成的字典将类似如下：

  {"id": 14,
   "name": "Workflow Job Template - Launch Mars Mission",
   "url": "https://host/#/workflows/14",
   "created_by": "admin",
   "started": "2019-10-26T00:11:04.554468+00:00",
   "finished": "2019-10-26T00:11:24.249899+00:00",
   "status": "successful",
   "traceback": "",
   "body": "Workflow job summary:
  
           node #1 spawns job #15, \"Assemble Fleet JT\", which finished with status successful.
           node #2 spawns job #16, \"Mission Start approval node\", which finished with status successful.\n
           node #3 spawns job #17, \"Deploy Fleet\", which finished with status successful."
  }
  

如需更多详情，请参阅 Using variables with Jinja2。

Automation controller 需要有效的语法来检索用于显示消息的正确数据。对于支持的属性列表和正确的语法构建，请参阅本指南的 支持的自定义通知属性 部分。

如果您创建的通知模板使用无效语法或者引用不可使用的字段，则会显示一条错误消息，指出错误的性质。如果删除通知的自定义消息，则会在相应位置显示默认消息。

注解

如果您在没有编辑自定义消息（或编辑过且从没有恢复到默认值）的情况下保存通知模板，Details 屏幕会假定默认值，且不会显示自定义消息表。如果您编辑并保存任何值，则整个表会显示在 Details 屏幕中。

26.6. 启用和禁用通知¶

除了在作业运行结束时通知您成功或失败以外，您可以选择在某个特定作业启动时要通知的通知。需要记住以下一些行为：

• 如果工作流模板 (WFJT) 启用了启动时通知，且该工作流中的作业模板 (JT) 也启用了启动时通知，您将收到这两者的通知

• 您可以启用在 WFJT 中的很多 JT 上运行通知

• 您可以启用在分片作业模板 (SJT) 启动时运行通知，并且每个分片都会生成通知

• 如果您启用在作业启动时运行通知，且该通知被删除，则 JT 会继续运行，但会生成错误消息

您可以从以下资源中的 Notifications 标签页中启用作业启动、作业成功和作业失败时通知，或者它们中的任何组合：

• 任务模板

• 工作流模板

• 项目（如下例所示）

• 清单源

• 机构

对于具有批准节点的工作流模板，除了 Start、Success 和 Failure 以外，您还可启用或禁用某些与批准相关的事件：

有关使用这些节点类型的详情，请参阅 批准节点。

26.7. 为通知配置 host 主机名¶

In the System Settings, you can replace the default value in the Base URL of the service field with your preferred hostname to change the notification hostname.

刷新您的许可证也会更改通知主机名。automation controller 的新安装不必设置通知主机名。

26.8. 通知 API¶

使用 started、success 或 error 端点：

/api/v2/organizations/N/notification_templates_started/
/api/v2/organizations/N/notification_templates_success/
/api/v2/organizations/N/notification_templates_error/

此外，../../../N/notification_templates_started 端点具有适用于以下各项的 GET 和 POST 操作：

• 机构

• 项目

• 清单源

• 作业模板

• 系统作业模板

• 工作流任务模板