27. 通知

一个通知模板是一个通知类型（电子邮件、Slack、Webhook 等）的实例，它具有名称、描述和定义的配置。

例如

电子邮件通知模板需要用户名、密码、服务器和收件人
Slack 通知模板需要令牌和频道列表
Webhook 通知模板需要 URL 和标头

通知是通知模板的体现；例如，当作业失败时，将使用通知模板定义的配置发送通知。

在较高层面上，通知系统的典型流程如下

用户在 /api/v2/notification_templates 端点（通过 API 或 UI）创建通知模板到 REST API。
用户将通知模板分配给支持它的各种对象（所有作业模板变体以及组织和项目），并在他们想要通知的适当触发级别（已启动、成功或错误）。例如，用户可能希望分配特定通知模板以在作业模板 1 失败时触发。在这种情况下，他们将在 /api/v2/job_templates/n/notification_templates_error API 端点将通知模板与作业模板关联。
您可以设置作业开始时的通知，而不仅仅是作业结束时的通知。用户和团队也可以定义自己的通知，这些通知可以附加到任意作业。

27.1. 通知层次结构

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

作业模板将使用在其上定义的通知模板，以及继承自作业模板使用的项目和它列出的组织（通过项目）的通知模板。
项目更新将使用在项目上定义的通知模板，并继承与其关联的组织的通知模板
清单更新将使用在它列出的组织上定义的通知模板
临时命令将使用在清单关联的组织上定义的通知模板

27.2. 工作流

当作业成功或失败时，错误或成功处理程序将使用上面定义的过程拉取相关通知模板列表。然后，它将为每个模板创建一个通知对象，其中包含有关作业的相关详细信息，然后将其发送到目标（电子邮件地址、slack 频道、短信号码等）。这些通知对象作为作业类型（作业、清单更新、项目更新）上的相关资源可用，也可以在 /api/v2/notifications 上使用。您还可以通过检查其相关资源来查看已从通知模板发送的通知。

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

27.3. 创建通知模板

要创建通知模板

从左侧导航栏中点击**通知**。
点击**添加**按钮。

在各自的字段中输入通知的名称和描述，并指定它所属的组织（必填）。
从**类型**下拉菜单中选择一种通知类型。有关更多信息，请参阅后续部分。
完成所有必要信息后，点击**保存**添加通知。

27.4. 通知类型

AWX 支持的通知类型

这些都有自己的配置和行为语义，测试它们可能需要采用不同的方式。此外，您可以自定义每种通知类型，直到特定细节，或一组触发通知的条件。有关配置自定义通知的更多详细信息，请参阅创建自定义通知。以下各节将尽可能详细地介绍每种通知类型。

27.4.1. AWS SNS 

AWS SNS(https://aws.amazon.com/sns/) 通知类型支持将消息发送到 SNS 主题。

您必须提供以下详细信息以设置 SNS 通知

AWS 区域
AWS 访问密钥 ID
AWS 密钥访问密钥
AWS SNS 主题 ARN

27.4.2. 邮件 

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

您必须提供以下详细信息以设置电子邮件通知

主机
收件人列表
发件人电子邮件
端口
超时（以秒为单位）：允许您指定最多 120 秒，AWX 在放弃之前尝试连接到电子邮件服务器的时间长度。

27.4.3. Grafana 

Grafana 是一个相当直接的集成。首先，在 Grafana 系统中创建一个 API 密钥（这是提供给 AWX 的令牌）。

您必须提供以下详细信息以设置 Grafana 通知

Grafana URL：Grafana API 服务的 URL，通常为 http://yourcompany.grafana.com。
Grafana API 密钥：用户必须首先在 Grafana 系统中创建一个 API 密钥（这是提供给 AWX 的令牌）。

其他需要注意的选项是

仪表板 ID：当您为 Grafana 帐户创建 API 密钥时，您可以设置一个具有自己唯一 ID 的仪表板。
面板 ID：如果您在 Grafana 界面中添加了面板和图表，您可以在此处指定其 ID。
注释的标签：输入帮助识别您正在配置的通知的事件类型(s) 的关键字。
禁用 SSL 验证：SSL 验证默认情况下处于开启状态，但您可以选择关闭对目标证书真实性的验证。使用内部或私有 CA 的环境应选择此选项以禁用验证。

27.4.4. IRC 

IRC 通知采用 IRC 机器人的形式，它将连接、将消息传递到频道(s) 或单个用户(s)，然后断开连接。通知机器人还支持 SSL 身份验证。该机器人目前不支持 Nickserv 身份验证。如果频道或用户不存在或不在线，则通知不会失败；失败场景专门保留给连接问题。

连接信息很简单

IRC 服务器密码（可选）：IRC 服务器可能要求密码才能连接。如果服务器不需要密码，请留空
IRC 服务器端口：IRC 服务器端口
IRC 服务器地址：IRC 服务器的主机名或地址
IRC 昵称：机器人连接到服务器后的昵称
目标频道或用户：要向其发送通知的用户和/或频道列表。
SSL 连接（可选）：机器人连接时是否使用 SSL

27.4.5. Mattermost 

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

目标 URL（必填）：将 POST 到该 URL 的完整 URL
用户名
频道
图标 URL：指定此通知显示的图标
禁用 SSL 验证：关闭对目标证书真实性的验证。使用内部或私有 CA 的环境应选择此选项来禁用验证。

27.4.6. PagerDuty 

PagerDuty 是一个相当直接的集成。首先，在 PagerDuty 系统中创建一个 API 密钥（这是提供给 AWX 的令牌），然后创建一个提供“集成密钥”的“服务”，该密钥也将提供给 AWX。其他必需的选项是

API 令牌：用户必须首先在 PagerDuty 系统中创建一个 API 密钥（这是提供给 AWX 的令牌）。
PagerDuty 子域：注册 PagerDuty 帐户时，您会收到一个唯一的子域来进行通信。例如，如果您注册为“testuser”，则 Web 仪表板将位于 testuser.pagerduty.com，您将向 API 提供 testuser 作为子域（而不是完整域）。
API 服务/集成密钥
客户端标识符：这将与警报内容一起发送到 pagerduty 服务，以帮助识别使用 API 密钥/服务的服务。如果多个集成使用相同的 API 密钥和服务，这将很有用。

27.4.7. Rocket.Chat 

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

目标 URL（必填）：将 POST 到该 URL 的完整 URL
用户名
图标 URL：指定此通知显示的图标
禁用 SSL 验证：关闭对目标证书真实性的验证。使用内部或私有 CA 的环境应选择此选项来禁用验证。

27.4.8. Slack 

Slack 是一款协作团队通信和消息工具，配置非常简单。

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

一个 Slack 应用程序（有关如何创建应用程序的信息，请参阅 Slack 文档的基本应用程序设置页面）
一个令牌（请参阅启用与机器人的交互以及令牌类型文档页面上的有关机器人令牌的具体详细信息）

设置完机器人/应用程序后，您必须导航到“您的应用程序”，单击新创建的应用程序，然后转到 **添加功能和功能**，这使您可以配置传入的 Webhook、机器人和权限；以及 **将您的应用程序安装到您的工作区**。

您还必须邀请通知机器人加入 Slack 中的相关频道。请注意，不支持私信。

27.4.9. Twilio 

Twilio 服务是一种语音和短信自动化服务。登录后，您必须创建一个将发送消息的电话号码。然后，您可以在可编程短信下定义一个“消息服务”，并将之前创建的号码与它关联。

请注意，您可能需要验证此号码或其他一些信息，然后才能使用它向任何号码发送消息。消息服务不需要状态回调 URL，也不需要处理传入消息的能力。

在您的个人（或子）帐户设置下，您将拥有 API 凭据。Twilio 使用两个凭据来确定 API 请求来自哪个帐户。“帐户 SID”充当用户名，“Auth 令牌”充当密码。

要设置 Twilio，请提供以下详细信息

帐户令牌
源电话号码（这是与上面消息服务关联的号码，必须以“+15556667777”的形式给出）
目标短信号码（这将是接收短信的号码列表，应该是 10 位电话号码）
帐户 SID

27.4.10. Webhook 

Webhook 通知类型提供了一个简单的界面来发送 POST 到预定义的 Web 服务。AWX 将使用 application/json 内容类型将 POST 到此地址，数据有效负载包含所有相关详细信息，以 json 格式。一些 Web 服务 API 希望 HTTP 请求以特定格式和特定字段的形式呈现。您可以通过以下方式配置更多 Webhook 通知

配置 HTTP 方法（使用 **POST** 或 **PUT**）
传出请求的主体
配置身份验证（使用基本身份验证）

配置 Webhook 的参数是

用户名
基本身份验证密码
目标 URL（必填）：Webhook 通知将 PUT 或 POST 到该 URL 的完整 URL。
禁用 SSL 验证：SSL 验证默认情况下处于打开状态，但您可以选择关闭对目标证书真实性的验证。使用内部或私有 CA 的环境应选择此选项来禁用验证。
HTTP 标头（必填）：以 JSON 格式呈现的标头，其中键和值都是字符串。例如，{"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}
HTTP 方法（必填）。选择您的 Webhook 的方法
- POST：创建新资源。也充当不适合其他类别的操作的万能方法。除非您知道您的 Webhook 服务期望 PUT，否则您可能需要 POST。
- PUT：更新特定资源（通过标识符）或一组资源。如果事先知道资源标识符，PUT 也可用于创建特定资源。

27.4.10.1. Webhook 有效负载 

默认情况下，AWX 会在 Webhook 端点发送以下数据

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

通过 Webhook 消息发送的 started 通知示例，如 AWX 返回的那样

{"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

默认情况下，AWX 会在 Webhook 端点返回以下数据，以获得 success/fail 状态

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

通过 Webhook 消息发送的 success/fail 通知示例，如 AWX 返回的那样

{"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}}}

27.5. 创建自定义通知

您可以自定义每种通知类型的文本内容，方法是在通知表单底部使用切换按钮启用 **自定义消息** 部分。

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

开始
成功
错误
工作流已批准
工作流被拒绝
工作流正在运行
工作流超时

消息表单因您配置的通知类型而异。例如，电子邮件和 PagerDuty 通知的消息将显示为典型的电子邮件表单，具有主题和正文，在这种情况下，AWX 将字段显示为 **消息** 和 **消息正文**。其他通知类型仅针对每种类型的事件期望一个 **消息**

**消息** 字段预先填充了一个包含顶级变量 job 以及属性（例如 id 或 name）的模板，例如。模板包含在花括号中，并且可以从 AWX 提供的固定字段集中提取，如预先填充的 **消息** 字段中所示。

Custom notification template example syntax

此预先填充的字段建议向收到事件通知的接收者显示常用的消息。但是，您也可以通过根据需要添加自己的属性来自定义这些消息。自定义通知消息使用 Jinja 渲染 - 这与 Ansible 剧本使用的相同模板引擎。

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

消息始终只是字符串（仅限单行；不允许换行）

消息正文将是字典或文本块

Webhook 和 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."
}

有关更多详细信息，请参阅使用 Jinja2 的变量。

AWX 需要有效的语法才能检索正确的数据以显示消息。有关支持的属性列表和正确的语法构造，请参阅本指南的自定义通知的支持属性部分。

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

注意

如果您保存通知模板而不编辑自定义消息（或编辑并恢复为默认值），则**详细信息**屏幕将采用默认值，并且不会显示自定义消息表。如果您编辑并保存任何值，则整个表将在**详细信息**屏幕中显示。

Notification template with and without a custom message

27.6. 启用和禁用通知

除了在作业运行结束时通知您成功或失败之外，您还可以选择在特定作业开始时通知您哪些通知。一些需要注意的行为

如果工作流模板 (WFJT) 启用了开始时的通知，并且该工作流中的作业模板 (JT) 也启用了开始时的通知，您将收到这两个通知
您可以在 WFJT 中的多个 JT 上启用通知
您可以在切片作业模板 (SJT) 开始时启用通知，每个切片将生成一个通知
当您启用在作业开始时运行的通知，并且该通知被删除时，JT 会继续运行，但会导致错误消息

您可以在以下资源的**通知**选项卡中启用作业开始、作业成功和作业失败的通知，或任何组合。

作业模板
工作流模板
项目（在下例中显示）
库存源
组织

对于具有审批节点的工作流模板，除了开始、成功和失败之外，您还可以启用或禁用某些与审批相关的事件

List of project notifications with approval nodes option

有关使用这些类型节点的更多详细信息，请参阅审批节点。

27.7. 配置通知的`host`主机名

在系统设置中，您可以使用首选主机名替换**服务的基本 URL**字段中的默认值，以更改通知主机名。

Configuring base URL with preferred hostname

刷新许可证也会更改通知主机名。AWX 的新安装无需设置通知的主机名。

27.7.1. 重置`AWX_URL_BASE`

AWX 确定基本 URL (AWX_URL_BASE) 定义方式的主要方法是查看传入请求，并根据该传入请求设置服务器地址。

AWX 首先从数据库获取设置值。如果未找到设置值，它将回退到使用设置文件中的值。如果用户通过导航到 AWX 主机的 IP 地址发布许可证，则发布的许可证将写入数据库中的设置条目。

如果拾取了错误的地址，要更改AWX_URL_BASE，请使用您希望在通知中显示的 DNS 条目，从设置菜单中导航到**系统杂项设置**，然后重新添加您的许可证。

27.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**操作

组织
项目
库存源
作业模板
系统作业模板
工作流作业模板