ServiceNow数据源为Grafana | Grafana企业插件文档

文档

插件

ServiceNow 数据源插件

ServiceNow 数据源插件允许您在Grafana中查询和可视化来自ServiceNow的数据。

要求

此插件有以下要求

一个可以访问必要表格的ServiceNow用户
以下账户类型之一
- Grafana Cloud：专业客户、高级客户或启用企业插件附加组件的专业试用用户
- Grafana企业版：拥有已激活的许可证和具有Grafana服务器或组织管理权限的用户
已启用企业插件附加组件

安装ServiceNow数据源插件

要安装数据源，请参阅安装说明

配置ServiceNow

我们建议为Grafana创建新用户或使用服务用户。

注意如果使用“使用系统表格”选项，所提供的ServiceNow用户需要访问以下表格

表格	原因
`sys_db_object`	用于检索要查询的可用表格列表。
`sys_dictionary`	用于检索查询表格时字段列表。
`sys_choice`	用于检索使用“选择”字段过滤表格结果时选择的列表。
`sys_glide_object`	用于收集有关数据类型的信息，包括名称、基本类型等。
`incident`	在健康检查中用于验证表API和聚合API是否正常工作

建议使用的用户仅具有对必要表格的访问权限。如果用户访问太多表格，则查询编辑器可能会遇到性能问题。另外，请注意，禁用“使用系统表格”选项将导致插件不查询系统表格，在禁用此选项时请考虑这一点，以防您确实需要使用插件查询这些表格。

可以通过以下步骤配置ServiceNow用户账户

以下内容仅在使用“系统表格”选项获取架构和元数据时（在数据源设置中）是必要的

将管理员用户提升为安全管理员以执行以下操作。
创建一个名为grafana_reader_role的Role。 这可以是任何内容。
创建一个名为grafana_user_1的用户。 这也可以是任何内容。
将以下角色分配给上述用户grafana_user_1或您在第3步中创建的任何内容。
- grafana_reader_role或您在第2步中创建的任何内容。
创建提供以下权限的ACL规则。要执行以下操作，管理员用户需要提升为安全管理员。
- 对sys_db_object表格的读取访问权限
- 对sys_db_object.name字段的读取访问权限
- 对sys_db_object.label字段的读取访问权限
- 对sys_db_object.sys_name的读取访问权限（在ACL编辑器中，它将显示为Table[sys_db_object] => 显示名称）
- 对sys_db_object.super_class的读取访问权限（在ACL编辑器中，它将显示为Table[sys_db_object] => 扩展表格）
- 对sys_dictionary表格的读取访问权限
- 对sys_dictionary.*字段的读取访问权限
- 对sys_choice表格的读取访问权限
- 对sys_choice.*字段的读取访问权限
- 对sys_glide_object表格的读取访问权限
- 对sys_glide_object.*字段的读取访问权限
提供对incident表的读取访问权限。要执行此操作，管理员用户需要提升到安全管理员权限。
重复步骤6，为用户需要读取数据的其他表执行此操作。

开发者实例

要创建和设置ServiceNow的开发者实例，请访问ServiceNow开发者页面创建账户。

在Grafana中配置数据源

通过填写以下字段添加数据源：

认证字段

名称	描述
URL	ServiceNow实例的URL。
用户名	ServiceNow账户的用户名
密码	ServiceNow账户的密码
客户端ID	ServiceNow账户的OAuth客户端ID
客户端密钥	ServiceNow账户的OAuth客户端密钥

使用配置来配置数据源

可以使用Grafana的配置系统通过配置文件来配置数据源。您可以在配置页面上阅读有关其工作方式和可以为数据源设置的设置。

apiVersion: 1
datasources:
  - name: ServiceNow
    type: servicenow-datasource
    enabled: true
    access: proxy
    url: https://dev59952.service-now.com
    basicAuth: true
    basicAuthUser: ADD_YOUR_USER_HERE
    jsonData:
      oauthEnabled: true
      oauthClientID: ADD_YOUR_CLIENT_ID_HERE
    secureJsonData:
      basicAuthPassword: ADD_YOUR_PASSWORD_HERE
      oauthClientSecret: ADD_YOUR_CLIENT_SECRET_HERE
    version: 1
    editable: true
    isDefault: true

查询数据源

有两种查询方法：Table和Stats。

表格查询

返回适合在表格面板中显示的数据。它允许有序选择要显示的字段以及筛选选项。查询编辑器还提供了一个字段来限制查询返回的行数。

示例表格面板，显示上述查询的结果

显示

显示行提供了用于显示字段的选择器。也可以指定多个字段。字段将按照指定的顺序返回。

显示值

显示值标志将导致查询返回人类友好的值，即“显示值”，而不是数值。有三个不同的选项可供选择

选项	描述
全部	首选方式。此模式用于显示人类友好的显示值。此外，整数字段将以数字形式呈现，而选择字段将以人类友好的标签显示。
真	这与全部模式类似。但整数字段将以格式化的字符串呈现。
假	使用此模式，所有字段将显示实际值而不是标签。这可能比其他模式具有更好的性能。（注意：选择字段如严重性/状态将显示为整数ID而不是人类友好的标签）

例如，带有1的严重性，并且false标志将只显示1。如果标志设置为true/全部，则显示的值将是1 - 高。

根据ServiceNow API 文档，全部和是模式可能比否模式慢。更多关于显示值 / sysparm_display_value的信息，请参阅ServiceNow 文档

过滤器（通用）

过滤器行可以根据多个字段和值标准缩小显示的行。

所有过滤器都是通过一个AND或一个OR操作组合的。

当选择自定义表时，字段将自动从Service Now API中填充。

值

值选择取决于所选的过滤器类型。

布尔过滤器有True/False选项
文本过滤器允许输入任何值
日期过滤器在需要选择日期时会显示日期选择器日历
某些操作符，如是任何内容或今天，不会显示额外的输入字段。

排序方式

排序方式行可以根据多个字段和值标准缩小显示的行。

所有过滤器都是通过一个AND操作组合的。将添加对其他操作符的支持。

限制

可以指定行限制以防止返回过多的数据。默认值为25。

时间字段

时间字段是将查询数据转换为时间序列的方式。将数据作为时间序列处理意味着所选的“时间字段”中的值如果不在仪表板/面板的时间范围内，则不会显示。

如果未启用此选项，将提供一个特殊的值“忽略时间”，以允许结果“直到现在”，并使过滤器能够控制显示哪些数据。

时间字段的默认值是打开时间，但可以将其更改为任何包含时间值的可用字段。

统计查询

AggregateAPI将始终返回指标，以下聚合：avg，min，max，sum。过滤也可以用于缩小查询。

显示

显示字段行提供了一个选择字段和要显示的指标（s）的选项。也可以指定多个字段。

过滤器（通用）

聚合过滤器提供了基于字段和值标准缩小显示的指标的能力，类似于表格选项。

所有过滤器都是通过一个AND操作组合的。将添加对其他操作符的支持。

统计过滤器选项与TableAPI相同。

聚合

有四种类型的指标聚合，还有一个“计数”

平均值
最小值
最大值
总和
计数 - 这返回查询返回的指标的“数量”

按组别

此选择器提供了将指标拆分为更小的聚合的能力。按“优先级”分组将返回带有“标签”的优先级的指标和唯一值。

字段引用

从v2.0.0开始，支持字段引用。

引用其他表的字段默认折叠

点击后，将展开以显示字段

字段引用将仅展开到一级深度，例如，考虑以下结构

Field (Reference) ->
--- Field 1
--- Field 2 (Reference)
    --- Field 4
    --- Field 5
    --- Field 6 (Reference)
        --- Field 7
        --- Field 8 (Reference)
            ...
--- Field 3

目前，只能展开第一个引用，导致以下情况

Field (Reference) ->
--- Field 1
--- Field 3

模板和变量

要添加新的ServiceNow查询变量，请参阅添加查询变量。使用您的ServiceNow数据源作为以下可用查询的数据源

创建变量后，您可以使用变量语法在ServiceNow查询中使用它。有关变量的更多信息，请参阅模板和变量。

模板化

您可以在查询中使用变量代替硬编码的名称。变量在仪表板的顶部显示为下拉选择框。这些下拉框使得更改仪表板上显示的数据变得很容易。

请参阅以下示例，了解如何在查询变量部分添加查询变量，并使用模板值引用它。

查询变量

如果您添加了类型为查询的模板变量，您可以编写可以返回类似类别名称、键名称或键值的查询，这些值将显示为下拉选择框。

例如，您可以通过在模板变量的查询设置中指定如下查询来创建一个包含所有categories值的变量。

选择查询设置时，将显示一个过滤器部分，允许您选择一个类型和字段。目前，类型仅限于事件和变更。选择类型时，您将获得适用于该类型的字段列表。选择一个类型和字段后，底部将显示值的预览，显示该类型/字段的选项。这些值将在仪表板上显示为下拉菜单，您可以使用模板与它们一起过滤仪表板面板上的数据。

例如，如果您添加了一个名为category的变量，然后选择类型=事件和字段=类别，您将看到类别选项列表。如果您然后在面板中添加一个过滤器，并选择类别等于${category}，则面板数据将仅显示从仪表板下拉菜单中选择的该类别的数据。

导入按类别分的事件仪表板以查看示例。

在查询中使用变量

有两种语法

$<varname> 带有名为hostname的模板变量的示例

[[varname]] 带有名为hostname的模板变量的示例

注释

注释使您能够在图形上叠加事件。

注释查询支持与标准查询编辑器相同的选项。

转换

转换在与其他聚合查询一起使用具有分组子句时非常有用。

标签到字段

使用标签到字段转换的示例

导入ServiceNow仪表板

按照这些说明导入仪表板。

导入的仪表板可以在配置 > 数据源 > 选择您的ServiceNow数据源 > 选择仪表板选项卡中找到，以查看可用的预制仪表板。

注意：预制仪表板不能从ServiceNow插件导入的默认文件夹中移动。

版本兼容性

当前插件版本已针对 华盛顿特区 和海洋版本的 ServiceNow 进行了测试。旧版本可能受到支持，但插件并未针对它们进行测试。

重大变更

升级到 V2.0

现有的仪表板应在 2.0 版本上继续工作。如果现有的仪表板不再工作，请知悉这不是预期行为，您的反馈非常重要。提交支持问题时，请务必包括您的面板 JSON 或仪表板 JSON 的副本。

备份您的仪表板

在升级到 v2.0 之前备份您的仪表板至关重要。v2.0 中的查询架构已更改，并添加了迁移以将旧查询转换为新的。

如果您遇到任何问题并需要降级，您的仪表板在降级后很可能无法继续工作。

已知限制

查询编辑器中的过滤器不包含引用类型的字段。

了解更多信息

添加注释。
配置和使用模板和变量。
添加转换。
设置警报；请参阅警报概述。
ServiceNow REST API 参考文档.
ServiceNow 版本发布

使用 HTTP 代理

当使用 HTTP 代理时，Grafana 需要设置以下环境变量之一

HTTP_PROXY（或 http_proxy）
- 完整路径 - http://host:port
- 或者只需： host:port
HTTPS_PROXY（或 https_proxy）
- 完整路径 - https://host:port
- 或者只需： host:port

如果我们没有 ITSM 角色插件且“使用系统表”已启用怎么办？

执行以下操作需要管理员权限

选项 1：授予 Grafana 用户管理员权限以允许访问所有表。

选项 2：创建一个角色并将 ACL 应用到所有需要由 Grafana 访问的表。

执行以下操作需要管理员权限

登录管理员需要提升访问权限到 security_admin
1. 点击右上角导航面板上的个人资料图标。它是带有下拉箭头指示器的那个
2. 从下拉菜单中点击“提升角色”
3. 从显示的模态窗口中，勾选“security_admin”旁边的框
4. 点击确定
创建一个新角色，使用您想要的任何命名约定
1. 导航到左侧导航中的角色部分系统安全 => 用户和组 => 角色
2. 点击顶部“新建”
3. 输入角色的名称和相关的描述
4. 点击提交
创建一个新用户并将步骤 2 中创建的角色附加到它
为所需的表和字段创建表 ACL
1. 为 sys_db_object 表创建 ACL
  1. 在第二个搜索标题列“名称”中输入 sys_db_object 并按回车键
  2. 过滤后的结果应显示“表”。点击进入记录
  3. 在选项卡部分，选择“控制”
  4. 在页面底部的底部部分，确保“访问控制”是选中的选项卡
  5. 点击新建以创建新的 ACL
  6. 将“操作”选择更改为读取
  7. 在页面底部的“需要角色”部分，双击“插入新行”并搜索您创建的角色
  8. 选择您创建的角色后，点击绿色勾选标记
  9. 在底部点击提交以创建 ACL，然后当模态窗口出现时点击继续
2. 为特定的sys_db_object字段创建访问控制列表（ACL）。以下步骤需要为以下每个字段重复：名称、标签、显示名称和扩展表。
  1. 在sys_db_object的表记录视图中，选择屏幕顶部最接近的标签组中的“列”标签。
  2. 定位字段名称并选择它。
  3. 在底部的标签区域中，点击“访问控制”标签中的“新建”。
  4. 将操作更改为读取。
  5. 在底部的“需要角色”表中双击“插入行”文本。
  6. 搜索您创建的角色并单击绿色的勾选标记。
  7. 点击提交
  8. 请确保您已为所有必需的字段（名称、标签、显示名称和扩展表）重复了这些步骤。
3. 重复步骤4.1，对于您想要从Grafana查询的更改、事件和其他非CMDB表。不要重复步骤4.2，该步骤仅适用于sys_db_object。

当启用“使用系统表”时，如何为Grafana用户提供所需的访问权限？

执行以下操作需要管理员权限

选项1：执行以下步骤以创建Grafana连接ServiceNow的用户。

将管理员用户提升为安全管理员以执行以下操作。
创建一个名为grafana_reader_role的Role。 这可以是任何内容。
创建一个名为grafana_user_1的用户。 这也可以是任何内容。
将以下角色分配给上述用户grafana_user_1或您在第3步中创建的任何内容。
- grafana_reader_role或您在第2步中创建的任何内容。
创建提供以下权限的ACL规则。要执行以下操作，管理员用户需要提升为安全管理员。
- 对sys_db_object表格的读取访问权限
- 对sys_db_object.name字段的读取访问权限
- 对sys_db_object.label字段的读取访问权限
- 对sys_db_object.sys_name的读取访问权限（在ACL编辑器中，它将显示为Table[sys_db_object] => 显示名称）
- 对sys_db_object.super_class的读取访问权限（在ACL编辑器中，它将显示为Table[sys_db_object] => 扩展表格）
- 对sys_dictionary表格的读取访问权限
- 对sys_dictionary.*字段的读取访问权限
- 对sys_choice表格的读取访问权限
- 对sys_choice.*字段的读取访问权限
- 对sys_glide_object表格的读取访问权限
- 对sys_glide_object.*字段的读取访问权限
提供对incident表的读取访问权限。要执行此操作，管理员用户需要提升到安全管理员权限。
重复步骤6，为用户需要读取数据的其他表执行此操作。

以下步骤详细说明了如何执行上述操作。

登录管理员需要提升访问权限到 security_admin
1. 点击右上角导航面板上的个人资料图标。它是带有下拉箭头指示器的那个
2. 从下拉菜单中点击“提升角色”
3. 从显示的模态窗口中，勾选“security_admin”旁边的框
4. 点击确定
创建一个新角色，使用您想要的任何命名约定
1. 导航到左侧导航中的角色部分系统安全 => 用户和组 => 角色
2. 点击顶部“新建”
3. 输入角色的名称和相关的描述
4. 点击提交
创建新用户或修改现有用户，赋予您在步骤2中创建的角色。
为所需的表和字段创建表 ACL
1. 为 sys_db_object 表创建 ACL
  1. 在第二个搜索标题列“名称”中输入 sys_db_object 并按回车键
  2. 过滤后的结果应显示“表”。点击进入记录
  3. 在选项卡部分，选择“控制”
  4. 在页面底部的底部部分，确保“访问控制”是选中的选项卡
  5. 点击新建以创建新的 ACL
  6. 将“操作”选择更改为读取
  7. 在页面底部的“需要角色”部分，双击“插入新行”并搜索您创建的角色
  8. 选择您创建的角色后，点击绿色勾选标记
  9. 在底部点击提交以创建 ACL，然后当模态窗口出现时点击继续
2. 为特定的sys_db_object字段创建访问控制列表（ACL）。以下步骤需要为以下每个字段重复：名称、标签、显示名称和扩展表。
  1. 在sys_db_object的表记录视图中，选择屏幕顶部最接近的标签组中的“列”标签。
  2. 定位字段名称并选择它。
  3. 在底部的标签区域中，点击“访问控制”标签中的“新建”。
  4. 将操作更改为读取。
  5. 在底部的“需要角色”表中双击“插入行”文本。
  6. 搜索您创建的角色并单击绿色的勾选标记。
  7. 点击提交
  8. 请确保您已为所有必需的字段（名称、标签、显示名称和扩展表）重复了这些步骤。
3. 重复步骤4.1，对于您想要从Grafana查询的更改、事件和其他非CMDB表。不要重复步骤4.2，该步骤仅适用于sys_db_object。