Grafana 的 ServiceNow 数据源

文档

插件

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

要求

此插件有以下要求

拥有必要表访问权限的 ServiceNow 用户
以下账户类型之一
- Grafana Cloud：启用 Enterprise 插件附加组件的 Pro 客户、Advanced 客户或 Pro 试用用户
- Grafana Enterprise：拥有已激活许可且具有 Grafana 服务器或组织管理权限的用户
启用 Enterprise 插件附加组件

安装 ServiceNow 数据源插件

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

配置 ServiceNow

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

注意如果使用 Use Sys Tables 选项，提供的 ServiceNow 用户需要访问以下表

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

建议使用的用户仅具有必要表的访问权限。如果用户访问的表过多，查询编辑器中可能会遇到性能问题。另外请注意，禁用 Use Sys Tables 选项将导致插件不查询 sys 表，禁用此选项时请考虑到您可能需要使用插件查询这些表的情况。

ServiceNow 用户账户可以按照以下步骤进行配置

以下内容仅在使用“Sys Tables”选项获取 Schema 和元数据时（在数据源设置中）是必需的

将管理员用户提升为安全管理员以执行以下操作。
创建名为 grafana_reader_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] => Display Name）
- sys_db_object.super_class 的读取权限（在 ACL 编辑器中，将显示为 Table[sys_db_object] => Extends Table）
- sys_dictionary 表的读取权限
- sys_dictionary.* 字段的读取权限
- sys_choice 表的读取权限
- sys_choice.* 字段的读取权限
- sys_glide_object 表的读取权限
- sys_glide_object.* 字段的读取权限
提供 incident 表的读取权限。执行此操作需要将管理员用户提升为安全管理员。
对其余用户需要读取数据的表重复步骤 6。

开发者实例

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

在 Grafana 中配置数据源

填写以下字段来添加数据源

认证字段

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

通过 Provisioning 配置数据源

可以使用 Grafana 的 Provisioning 系统通过配置文件配置数据源。您可以在Provisioning 文档页面阅读更多关于其工作原理以及可以为数据源设置的所有设置的信息。

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

请注意在 jsonData 部分使用了 authMethod: serviceNowOAuth。使用 OAuth 认证时，这是必需的。

向后兼容性

在插件的旧版本中，不存在 authMethod 字段。相反，您需要在 jsonData 部分设置 oauthEnabled: true，如下所示

apiVersion: 1
datasources:
  - name: ServiceNow
    ...
    jsonData:
      oauthEnabled: true
      ...
    ...

此配置仍受支持，但已弃用。建议改用 authMethod: serviceNowOAuth，因为插件的未来版本可能会移除对 oauthEnabled 的支持。

查询数据源

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

Table 查询

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

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

显示

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

显示值

显示值 标志将使查询返回易于理解的值或“显示值”，而不是数值。有三种不同的选项可用

选项	描述
全部	首选方式。此模式用于显示易于理解的显示值。此外，整数字段将以数字形式渲染，而 Choice 字段将以易于理解的标签形式显示。
True	这类似于 all 模式。但整数字段将以格式化字符串形式渲染。
False	在此模式下，所有字段都将显示实际值而非标签。这可能比其他模式具有更好的性能。（注意：severity/state 等 Choice 字段将显示为整数 ID，而非易于理解的标签）

例如，严重性为 1 且 false 标志开启时将仅显示 1。如果标志设置为 true/all，显示的值将是 1 - High。

根据 ServiceNow API 文档，all 和 true 模式可能比 false 模式慢。在 ServiceNow 文档中阅读更多关于 Display value / sysparm_display_value 的信息。

过滤器（通用）

过滤器 行提供基于多个字段和值条件缩小显示行范围的能力。

所有过滤器都通过 AND 或 OR 操作组合。

选择自定义表时，字段会自动从 ServiceNow API 填充。

值

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

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

排序方式

排序方式 行提供基于多个字段和值条件缩小显示行范围的能力。

所有过滤器都通过 AND 操作组合。将添加对更多运算符的支持。

限制

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

时间字段

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

如果未开启此值，将提供一个特殊值“忽略时间”，以允许显示“截止目前”的结果，并允许使用过滤器控制显示哪些数据。

时间字段 默认为 Opened At，但可以更改为任何包含时间值的可用字段。

Stats 查询

AggregateAPI 将始终返回指标，带有以下聚合：avg、min、max、sum。也可使用过滤来缩小查询范围。

显示

显示字段 行提供一个字段选择器和要显示的指标。也可以指定多个字段。

过滤器（通用）

Aggregate 过滤器 提供基于字段和值条件缩小显示指标范围的能力，类似于表格选项。

所有过滤器都通过 AND 操作组合。将添加对更多运算符的支持。

Stats 过滤器选项与 TableAPI 相同。

聚合

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

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

分组依据

此选择器能够将指标拆分为更小的聚合。按“优先级”分组将返回带有 priority“标签”的指标以及按唯一值分隔的数据。

字段引用

从 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 查询中使用它。有关变量的更多信息，请参阅模板和变量。

模板化

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

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

查询变量

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

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

选择查询设置时，将显示一个 过滤器 部分，允许您选择类型和字段。目前，类型仅限于 Incidents 和 Changes。选择类型后，将提供适用于该类型的一系列字段。选择类型和字段后，底部将显示值的预览，显示该类型/字段的可用选项。这些值将显示在仪表盘的下拉列表中，您可以结合模板化功能使用这些值来过滤仪表盘面板中的数据。

例如，如果您添加一个名为类别的变量，然后选择 Type = Incidents 和 Field = Category，您将看到 Category 的选项列表。如果您随后向面板添加过滤器，并选择 Category 等于 ${category}，面板数据将只显示从仪表盘下拉列表中选择的 Category 的数据。

导入按类别统计的事件仪表盘以查看示例。

在查询中使用变量

有两种语法

$<varname> 示例：模板变量名为 hostname

[[varname]] 示例：模板变量名为 hostname

注解

注解使您能够在图表上叠加事件。

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

转换

当使用带有 group by 子句的聚合查询时，转换可能很有用。

标签转字段

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

导入 ServiceNow 仪表盘

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

导入的仪表盘可以在 Configuration > Data Sources > 选择您的 ServiceNow 数据源 > 选择 Dashboards 标签页中找到，以查看可用的预制仪表盘。

注意：预制仪表盘无法从 ServiceNow 插件导入的默认文件夹中移动。

版本兼容性

当前版本的插件已在 ServiceNow 的 Washington DC 和 Xanadu 版本上进行了测试。可能支持更旧的版本，但未对其进行测试。

重大变更

升级到 V2.0

现有仪表盘在 2.0 版本上应继续工作。如果现有仪表盘出现无法工作的问题，请知悉这不是预期行为，您的反馈非常有价值。提交支持问题时，请务必附带面板 JSON 或仪表盘 JSON 的副本。

备份您的仪表盘

在升级到 v2.0 之前，务必备份您的仪表盘。v2.0 中的查询 schema 已更改，并添加了迁移功能，以在旧查询更改时将其转换为新查询。

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

已知限制

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

了解更多

添加注解。
配置和使用模板和变量。
添加转换。
设置告警；请参阅告警概述。
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 Roles Plugin 并且“Use Sys Tables”已启用怎么办？

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

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

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

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

登录的管理员需要提升权限至 security_admin
1. 点击右上角导航面板上的个人资料图标。它是带有下拉箭头指示器的那个图标
2. 从下拉菜单中点击“提升角色”
3. 在显示的模态框中，勾选“security_admin”旁边的复选框
4. 点击确定
创建一个新角色，命名方式随您喜好
1. 导航到左侧导航栏中的角色部分 System Security => Users and Groups => Roles
2. 点击顶部的“新建”
3. 输入角色的名称和相关描述
4. 点击提交
创建一个新用户或修改现有用户，并赋予您在步骤 2 中创建的角色
为所需的表和字段创建 Table ACL
1. 为 sys_db_object 表创建 ACL
  1. 在第二个搜索表头列“名称”中，输入 sys_db_object 并按回车
  2. 过滤结果应显示“表格”。点击以导航到记录中
  3. 在标签页部分，选择“Controls”
  4. 在页面底部，确保选中了“Access Controls”标签页
  5. 点击新建创建新的 ACL
  6. 将“操作”选择更改为 read
  7. 在底部附近的“Requires Role”部分，双击“插入新行”并搜索您创建的角色
  8. 选择您创建的角色后，点击绿色对勾标记
  9. 点击底部的提交创建 ACL，然后在模态框出现时点击继续
2. 为特定的 sys_db_object 字段创建 ACL。对于以下每个字段，都需要重复以下步骤：Name、Label、Display Name 和 Extends table
  1. 仍在 sys_db_object 表记录视图时，在屏幕顶部附近的标签页组中选择“Columns”标签页
  2. 找到字段名称并选中它
  3. 在底部标签页部分，在访问控制标签页中点击“新建”
  4. 将操作更改为 read
  5. 在底部“Requires role”表中双击插入行文本
  6. 搜索您创建的角色并点击绿色对勾标记
  7. 点击提交
  8. 确保您已为所有必需字段重复了这些步骤：Name、Label、Display Name 和 Extends table
3. 对 Change、Incident 和任何其他您希望从 Grafana 查询的非 CMDB 表重复步骤 4.1 中的步骤。不要重复步骤 4.2，该步骤仅适用于 sys_db_object。

当“Use Sys Tables”已启用时，如何为 grafana 用户提供所需的访问权限？

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

选项 1：执行以下步骤为 grafana 创建一个连接 servicenow 的用户

将管理员用户提升为安全管理员以执行以下操作。
创建名为 grafana_reader_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] => Display Name）
- sys_db_object.super_class 的读取权限（在 ACL 编辑器中，将显示为 Table[sys_db_object] => Extends Table）
- 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. 导航到左侧导航栏中的角色部分 System Security => Users and Groups => Roles
2. 点击顶部的“新建”
3. 输入角色的名称和相关描述
4. 点击提交
创建一个新用户或修改现有用户，并赋予您在步骤 2 中创建的角色
为所需的表和字段创建 Table ACL
1. 为 sys_db_object 表创建 ACL
  1. 在第二个搜索表头列“名称”中，输入 sys_db_object 并按回车
  2. 过滤结果应显示“表格”。点击以导航到记录中
  3. 在标签页部分，选择“Controls”
  4. 在页面底部，确保选中了“Access Controls”标签页
  5. 点击新建创建新的 ACL
  6. 将“操作”选择更改为 read
  7. 在底部附近的“Requires Role”部分，双击“插入新行”并搜索您创建的角色
  8. 选择您创建的角色后，点击绿色对勾标记
  9. 点击底部的提交创建 ACL，然后在模态框出现时点击继续
2. 为特定的 sys_db_object 字段创建 ACL。对于以下每个字段，都需要重复以下步骤：Name、Label、Display Name 和 Extends table
  1. 仍在 sys_db_object 表记录视图时，在屏幕顶部附近的标签页组中选择“Columns”标签页
  2. 找到字段名称并选中它
  3. 在底部标签页部分，在访问控制标签页中点击“新建”
  4. 将操作更改为 read
  5. 在底部“Requires role”表中双击插入行文本
  6. 搜索您创建的角色并点击绿色对勾标记
  7. 点击提交
  8. 确保您已为所有必需字段重复了这些步骤：Name、Label、Display Name 和 Extends table
3. 对 Change、Incident 和任何其他您希望从 Grafana 查询的非 CMDB 表重复步骤 4.1 中的步骤。不要重复步骤 4.2，该步骤仅适用于 sys_db_object。

选项 2：授予 Grafana 用户管理员权限以允许访问所有表。（强烈不推荐）

执行上述任何选项都需要管理员权限

此页面有帮助吗？

发送邮件至 docs@grafana.com

帮助与支持

社区

要求

安装 ServiceNow 数据源插件

配置 ServiceNow

开发者实例

在 Grafana 中配置数据源

认证字段

通过 Provisioning 配置数据源

向后兼容性

查询数据源

Table 查询

显示

显示值

过滤器（通用）

值

排序方式

限制

时间字段

Stats 查询

显示

过滤器（通用）

聚合

分组依据

字段引用

模板和变量

模板化

查询变量

在查询中使用变量

注解

转换

标签转字段

导入 ServiceNow 仪表盘

版本兼容性

重大变更

升级到 V2.0

备份您的仪表盘

已知限制

了解更多

使用 HTTP 代理

如果我们没有 ITSM Roles Plugin 并且“Use Sys Tables”已启用怎么办？

当“Use Sys Tables”已启用时，如何为 grafana 用户提供所需的访问权限？

此页面有帮助吗？

来自 Grafana Labs 的相关资源