Cloud Insights API
NetApp 客户和独立软件供应商( ISV )可以通过 Cloud Insights API 将 Cloud Insights 与其他应用程序集成,例如 CMDB 或其他票证系统。
请注意, Cloud Insights API 基于您当前的版本提供:
API 类别 | 基本 | 标准 | 高级版 |
---|---|---|---|
采集单元 |
|||
数据收集 |
|||
用户管理 |
|||
警报 |
|||
资产 |
|||
数据载入 |
|||
日志载入 |
此外,您还可以使用 Cloud Insights "功能集角色" 将确定您可以访问的 API 。用户和来宾角色的权限比管理员角色更少。例如,如果您在 " 监控和优化 " 中具有管理员角色,而在 " 报告 " 中具有用户角色,则您可以管理除数据仓库之外的所有 API 类型。
API 访问的要求
-
API 访问令牌模型用于授予访问权限。
-
API 令牌管理由具有管理员角色的 Cloud Insights 用户执行。
API 文档( Swagger )
登录到 Cloud Insights 并导航到 * 管理 > API 访问 * 可查看最新的 API 信息。单击 * API Documentation" 链接。
API 文档基于 Swagger ,其中提供了 API 的简短问题描述和使用情况信息,您可以在环境中试用这些文档。
API 访问令牌
在使用 Cloud Insights API 之前,必须创建一个或多个 * API 访问令牌 * 。访问令牌用于指定的 API 类别,并且可以授予读取和 / 或写入权限。您还可以为每个访问令牌设置到期时间。指定类别下的所有 API 对访问令牌有效。每个令牌都不包含用户名或密码。
创建访问令牌:
-
单击 * 管理 > API 访问 *
-
单击 * + API 访问令牌 *
-
输入令牌名称
-
选择 API 类别
-
指定为此 API 访问授予的权限
-
指定令牌到期日期
-
|
您的令牌只能在创建过程中复制到剪贴板并进行保存。令牌创建后无法检索,因此强烈建议复制令牌并将其保存在安全位置。系统将提示您单击 * 复制 API 访问令牌 * 按钮,然后才能关闭令牌创建屏幕。 |
您可以禁用,启用和撤消令牌。可以启用已禁用的令牌。
令牌从客户角度授予对 API 的通用访问权限;在其自己的租户范围内管理对 API 的访问权限。客户管理员可以在 Cloud 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 访问密钥期间保存的令牌。
API 类别
Cloud Insights API 基于类别,目前包含以下类别:
-
资产类别包含资产,查询和搜索 API 。
-
资产:枚举顶级对象并检索特定对象或对象层次结构。
-
查询:检索和管理 Cloud Insights 查询。
-
导入:导入标注或应用程序并将其分配给对象
-
搜索:在不知道对象的唯一 ID 或全名的情况下找到特定对象。
-
-
数据收集类别用于检索和管理数据收集器。
-
数据载入类别用于检索和管理载入数据和自定义指标,例如从 Telegraf 代理检索和管理
其他类别和 / 或 API 可能会随着时间的推移而变为可用。您可以在中找到最新的 API 信息 "API Swagger 文档"。
请注意,用户有权访问的 API 类别也取决于 "用户角色" 它们在每个 Cloud Insights 功能集(监控, Cloud Secure ,报告)中都有。
清单遍历
本节介绍如何遍历 Cloud Insights 对象的层次结构。
顶级对象
各个对象在请求中通过唯一 URL (在 JSON 中称为 "self-" )进行标识,并需要了解对象类型和内部 ID 。对于某些顶级对象(主机,存储等), REST API 可提供对完整收集的访问权限。
API URL 的常规格式为:
https://<tenant>/rest/v1/<category>/<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 命令都支持 * 扩展 * 参数,该参数可提供有关相关对象的一个或多个 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 通过 Expand ,您可以在一个响应中引入大量相关数据。NetApp 建议您一次不要请求太多信息;这可能会导致发生原因性能下降。
要阻止这种情况,无法扩展对顶级收集的请求。例如,您不能同时请求所有存储对象的扩展数据。客户端需要检索对象列表,然后选择要扩展的特定对象。
性能数据
性能数据会作为单独的示例收集到多个设备中。Cloud Insights 会每小时(默认值)聚合和汇总性能示例。
通过 API ,可以访问样本和汇总数据。对于包含性能数据的对象,性能摘要可通过 expand=performal 的形式提供。性能历史记录时间序列可通过嵌套的 expand=performer.history 来查看。
性能数据对象示例包括:
-
存储性能
-
StoragePoolPerformance
-
端口性能
-
磁盘性能
性能指标具有问题描述和类别,并包含一组性能摘要。例如,延迟,流量和速率。
性能摘要包含一个问题描述,单元,样本开始时间,样本结束时间以及一组汇总值(当前值,最小值,最大值,平均值等),这些值是从一个时间范围( 1 小时, 24 小时, 3 天等)内的单个性能计数器计算得出的。
生成的性能数据词典具有以下关键字:
-
"self-" 是对象的唯一 URL
-
" 历史记录 " 是时间戳对和计数器值映射的列表
-
其他每个词典密钥( "diskThroughput " 等)都是性能指标的名称。
每个性能数据对象类型都有一组唯一的性能指标。例如,虚拟机性能对象支持使用 "diskThroughput " 作为性能指标。每个受支持的性能指标都属于指标词典中提供的特定 " 性能类别 " 。Cloud Insights 支持本文档后面列出的几个性能指标类别。每个性能指标词典还将包含一个可供用户读取的此性能指标问题描述字段问题描述以及一组性能摘要计数器条目。
性能摘要计数器是性能计数器的汇总。它会显示计数器的典型聚合值,例如最小值,最大值和平均值,以及最新观察到的值,汇总数据的时间范围,计数器的单位类型以及数据的阈值。只有阈值是可选的;其余属性是必需的。
以下类型的计数器可提供性能摘要:
-
Read —读取操作摘要
-
写入—写入操作摘要
-
总计—所有操作的摘要。它可能高于简单的读写总和;它可能包括其他操作。
-
Total Max —所有操作的摘要。这是指定时间范围内的最大总值。
对象性能指标
API 可以返回环境中对象的详细指标,例如:
-
存储性能指标,例如 IOPS (每秒输入 / 输出请求数),延迟或吞吐量。
-
交换机性能指标,例如流量利用率, BB 信用零数据或端口错误。
请参见 "API Swagger 文档" 有关每种对象类型的指标的信息。
性能历史记录数据
历史数据以时间戳和计数器映射对列表的形式显示在性能数据中。
历史计数器根据性能指标对象名称命名。例如,虚拟机性能对象支持 "diskThroughput " ,因此历史记录映射将包含名为 "diskThroughput : read" , "diskThroughput : write" 和 "diskThroughput : total" 的键。
|
时间戳采用 UNIX 时间格式。 |
以下是磁盘的性能数据 JSON 示例:
具有容量属性的对象
具有容量属性的对象使用基本数据类型和 CapacityItem 来表示。
CapacityItem
CapacityItem 是一个逻辑容量单位。它的父对象定义了单位,并具有 " 值 " 和 " 高阈值 " 。此外,它还支持一个可选的细分图,用于说明容量值的构建方式。例如,一个 100 TB StoragePool 的总容量将是一个值为 100 的 CapacityItem 。细分情况可能会显示为 " 数据 " 分配了 60 TB ,为 " 快照 " 分配了 40 TB 。
- 注意
-
" 高阈值 " 表示系统为相应指标定义的阈值,客户端可以使用这些阈值针对超出可接受配置范围的值生成警报或直观提示。
下面显示了具有多个容量计数器的 StoragePools 的容量:
使用搜索查找对象
搜索 API 是系统的一个简单入口点。API 的唯一输入参数是自由格式的字符串,生成的 JSON 包含分类结果列表。类别是指与清单不同的资产类型,例如存储,主机,数据存储库等。每个类别都将包含一个与搜索条件匹配的类别类型对象列表。
Cloud Insights 是一种可扩展(广泛开放)的解决方案,可与第三方流程编排,业务管理,变更控制和服务单系统以及自定义 CMDB 集成进行集成。
Cloud Insight 的 RESTful API 是一个主要的集成点,支持简单有效地移动数据,并允许用户无缝访问其数据。