Skip to main content
Data Infrastructure Insights
简体中文版经机器翻译而成，仅供参考。如与英语版出现任何冲突，应以英语版为准。

Data Infrastructure InsightsAPI

贡献者 netapp-alavoie dgracenetapp
PDF

Data Infrastructure InsightsAPI 使NetApp客户和独立软件供应商 (ISV) 能够将Data Infrastructure Insights与其他应用程序（例如 CMDB 或其他票务系统）集成。

您的Data Infrastructure Insights"功能集角色"将决定您可以访问哪些 API。用户和来宾角色的权限比管理员角色的权限少。例如，如果您在监控和优化中具有管理员角色，但在报告中具有用户角色，则您可以管理除数据仓库之外的所有 API 类型。

API 访问要求

  • API 访问令牌模型用于授予访问权限。

  • API 令牌管理由具有管理员角色的Data Infrastructure Insights用户执行。

API 文档（Swagger）

通过登录Data Infrastructure Insights并导航至 Admin > API Acccess 可以找到最新的 API 信息。单击*API 文档*链接。

API 类型

API 文档基于 Swagger，提供 API 的简要描述和使用信息，并允许您在租户中尝试它。根据您的用户角色和/或Data Infrastructure Insights版本，您可用的 API 类型可能会有所不同。

API Swagger 示例

API 访问令牌

在使用Data Infrastructure InsightsAPI 之前，您必须创建一个或多个 API 访问令牌。访问令牌用于指定的 API 类型，并且可以授予读取和/或写入权限。您还可以设置每个访问令牌的有效期。指定类型下的所有 API 对于访问令牌均有效。每个令牌都没有用户名或密码。

要创建访问令牌：

  • 点击“管理”>“API 访问”

  • 点击*+API 访问令牌*

    • 输入代币名称

    • 选择 API 类型

    • 指定授予此 API 访问的权限

    • 指定令牌到期时间

备注 您的令牌仅可在创建过程中复制到剪贴板并保存。令牌一旦创建就无法检索，因此强烈建议复制令牌并将其保存在安全的位置。系统将提示您单击“复制 API 访问令牌”按钮，然后才能关闭令牌创建屏幕。

您可以禁用、启用和撤销令牌。已禁用的令牌可以启用。

令牌从客户角度授予对 API 的通用访问权限；管理其自身租户范围内对 API 的访问。客户管理员可以授予和撤销这些令牌，而无需Data Infrastructure Insights后端人员的直接参与。

用户成功验证并授权访问后，应用程序将收到访问令牌，然后在调用目标 API 时将访问令牌作为凭证传递。传递的令牌通知 API，令牌持有者已被授权访问 API 并执行授权期间授予的范围指定的特定操作。

传递访问令牌的 HTTP 标头是 X-CloudInsights-ApiKey:。

例如，使用以下命令检索存储资产：

 curl https://<tenant_host_name>/rest/v1/assets/storages -H 'X-CloudInsights-ApiKey:<API_Access_Token>'
其中 _<API_Access_Token>_ 是您在创建 API 访问期间保存的令牌。

请参阅 swagger 页面以获取特定于您希望使用的 API 的示例。

API 类型

Data Infrastructure InsightsAPI 是基于类别的，目前包含以下类型：

  • ASSETS 类型包含资产、查询和搜索 API。

    • 资产：枚举顶级对象并检索特定对象或对象层次结构。

    • 查询：检索和管理Data Infrastructure Insights查询。

    • 导入：导入注释或应用程序并将其分配给对象

    • 搜索：无需知道对象的唯一 ID 或全名即可定位特定对象。

  • 数据收集类型用于检索和管理数据收集器。

  • 数据摄取类型用于检索和管理摄取数据和自定义指标，例如来自 Telegraf 代理的数据

  • LOG INGESTION 用于检索和管理日志数据

随着时间的推移，可能会有更多类型和/或 API 可用。您可以在"API Swagger 文档"。

请注意，用户可以访问的 API 类型还取决于"用户角色"它们在每个Data Infrastructure Insights功能集（监控、工作负载安全、报告）中都有。

库存遍历

本节介绍如何遍历Data Infrastructure Insights对象的层次结构。

顶级对象

请求中的各个对象通过唯一的 URL（在 JSON 中称为“self”）进行标识，并且需要了解对象类型和内部 ID。对于某些顶级对象（主机、存储等），REST API 提供对完整集合的访问。

API URL 的一般格式为：

 https://<tenant>/rest/v1/<type>/<object>
例如，要从名为 _mysite.c01.cloudinsights.netapp.com_ 的租户检索所有存储，请求 URL 为：
https://mysite.c01.cloudinsights.netapp.com/rest/v1/assets/storages

子对象和相关对象

顶级对象（例如存储）可用于遍历其他子对象和相关对象。例如，要检索特定存储的所有磁盘，请将存储“self”URL 与“/disks”连接起来，例如：

https://<tenant>/rest/v1/assets/storages/4537/disks

扩展

许多 API 命令支持 expand 参数，该参数提供有关对象或相关对象的 URL 的更多详细信息。

一个常见的扩展参数是_expands_。响应包含该对象所有可用的特定扩展的列表。

例如，当您请求以下内容时：

 https://<tenant>/rest/v1/assets/storages/2782?expand=_expands
API 返回对象的所有可用扩展，如下所示：

扩展示例

每个扩展都包含数据、URL 或两者。 expand 参数支持多个和嵌套属性，例如：

 https://<tenant>/rest/v1/assets/storages/2782?expand=performance,storageResources.storage
扩展允许您在一次响应中引入大量相关数据。  NetApp建议您不要一次请求太多信息；这可能会导致性能下降。

为了防止这种情况发生，顶级收藏的请求不能扩大。例如，您不能一次请求扩展所有存储对象的数据。客户端需要检索对象列表，然后选择特定对象进行扩展。

性能数据

性能数据作为单独的样本从许多设备上收集。每小时（默认），Data Infrastructure Insights都会汇总并总结性能样本。

API 允许访问样本和汇总数据。对于具有性能数据的对象，性能摘要可用 expand=performance 表示。性能历史时间序列可通过嵌套的_expand=performance.history_获得。

性能数据对象的示例包括：

  • 存储性能

  • 存储池性能

  • 港口绩效

  • 磁盘性能

绩效指标具有描述和类型，并包含一系列绩效摘要。例如，延迟、流量和速率。

性能摘要包含描述、单位、采样开始时间、采样结束时间以及在一定时间范围内（1 小时、24 小时、3 天等）从单个性能计数器计算得出的汇总值集合（当前值、最小值、最大值、平均值等）。

API 性能示例

生成的性能数据字典具有以下键：

  • “self” 是对象的唯一 URL

  • “history” 是时间戳和计数器值映射的列表

  • 每个其他字典键（“diskThroughput”等等）都是性能指标的名称。

每个性能数据对象类型都有一组独特的性能指标。例如，虚拟机性能对象支持“diskThroughput”作为性能指标。每个支持的性能指标都属于指标词典中呈现的某个“性能类别”。Data Infrastructure Insights支持本文​​档后面列出的几种性能指标类型。每个性能指标字典还将具有“描述”字段，该字段是该性能指标的人类可读的描述和一组性能摘要计数器条目。

性能摘要计数器是性能计数器的汇总。它呈现计数器的典型聚合值，如最小值、最大值和平均值，以及最新观察值、汇总数据的时间范围、计数器的单位类型和数据的阈值。只有阈值是可选的；其余属性都是必需的。

有以下类型的计数器的性能摘要：

  • 读取——读取操作摘要

  • 写入 – 写入操作摘要

  • 总计 – 所有操作的摘要。它可能高于读取和写入的简单总和；它可能包括其他操作。

  • Total Max – 所有操作的摘要。这是指定时间范围内的最大总值。

对象性能指标

API 可以返回租户上对象的详细指标，例如：

  • 存储性能指标，例如 IOPS（每秒输入/输出请求数）、延迟或吞吐量。

  • 交换机性能指标，例如流量利用率、BB 信用零数据或端口错误。

查看"API Swagger 文档"有关每个对象类型的指标的信息。

性能历史数据

历史数据在性能数据中以时间戳和计数器映射对的列表形式呈现。

历史计数器根据性能指标对象名称命名。例如，虚拟机性能对象支持“diskThroughput”，因此历史记录图将包含名为“diskThroughput.read”、“diskThroughput.write”和“diskThroughput.total”的键。

备注 时间戳采用 UNIX 时间格式。

以下是磁盘性能数据 JSON 的示例：

磁盘性能 JSON

具有容量属性的对象

具有容量属性的对象使用基本数据类型和CapacityItem来表示。

容量项目

CapacityItem 是容量的单个逻辑单位。它具有由其父对象定义的单位的“值”和“高阈值”。它还支持可选的细分图，解释容量值是如何构建的。例如，100 TB 存储池的总容量将是值为 100 的 CapacityItem。细分结果可能显示 60 TB 分配给“数据”，40 TB 分配给“快照”。

注意：“highThreshold”代表系统为相应指标定义的阈值，客户端可以使用它来对超出可接受配置范围的值生成警报或视觉提示。

下面显示了具有多个容量计数器的 StoragePools 的容量：

存储池容量示例

使用搜索查找对象

搜索 API 是系统的简单入口点。 API 的唯一输入参数是自由格式的字符串，生成的 JSON 包含分类的结果列表。类型是与库存不同的资产类型，例如存储、主机、数据存储等。每种类型都包含符合搜索条件的该类型的对象列表。

Data Infrastructure Insights是一种可扩展（广泛开放）的解决方案，允许与第三方编排、业务管理、变更控制和票务系统以及自定义 CMDB 集成。

Cloud Insight 的 RESTful API 是一个主要的集成点，它允许简单有效地移动数据，并允许用户无缝访问他们的数据。

禁用或撤销 API 令牌

要暂时禁用 API 令牌，请在 API 令牌列表页面上，单击 API 的“三个点”菜单，然后选择_禁用_。您可以随时使用相同的菜单并选择“启用”来重新启用令牌。

要永久删除 API 令牌，请从菜单中选择“撤销”。您无法重新启用已撤销的令牌；您必须创建一个新的令牌。

禁用或撤销 API 令牌

轮换过期的 API 访问令牌

API 访问令牌有一个有效期。当 API 访问令牌过期时，用户需要生成一个新令牌（类型为“数据提取”，具有读/写权限）并重新配置 Telegraf 以使用新生成的令牌而不是过期的令牌。以下步骤详细说明了如何执行此操作。

Kubernetes

请注意，这些命令使用默认命名空间“netapp-monitoring”。如果您设置了自己的命名空间，请在这些命令和所有后续命令和文件中替换该命名空间。

注意：如果您安装了最新的NetApp Kubernetes Monitoring Operator 并使用可续订的 API 访问令牌，则过期的令牌将自动被新的/刷新的 API 访问令牌替换。无需执行下面列出的手动步骤。

  • 创建一个新的 API 令牌。

  • 按照以下步骤操作"手动升级"，选择新的 API 令牌。

注意：使用配置管理工具（例如 Kustomize）管理其NetApp Kubernetes Monitoring Operator 的客户可以按照相同的步骤生成并下载一组更新的 YAML 以推送到他们的存储库。

RHEL/CentOS 和 Debian/Ubuntu

  • 编辑 Telegraf 配置文件，并用新的 API 令牌替换旧 API 令牌的所有实例。

     sudo sed -i.bkup ‘s/<OLD_API_TOKEN>/<NEW_API_TOKEN>/g’ /etc/telegraf/telegraf.d/*.conf
* 重新启动 Telegraf。
    sudo systemctl restart telegraf

Windows

  • 对于 C:\Program Files\telegraf\telegraf.d 中的每个 Telegraf 配置文件，用新的 API 令牌替换旧 API 令牌的所有实例。

    cp <plugin>.conf <plugin>.conf.bkup
(Get-Content <plugin>.conf).Replace(‘<OLD_API_TOKEN>’, ‘<NEW_API_TOKEN>’) | Set-Content <plugin>.conf

  • 重新启动 Telegraf。

    Stop-Service telegraf
Start-Service telegraf