RESTful API 快速入门指南

关于

RESTful API 是 SevOne 解决方案集成框架的关键组件。表征状态传输（REST）从根本上说是一种架构风格，其特点是为 RESTful API 的后端实施制定了一系列原则。一个关键原则是无状态，这意味着系统不依赖临时状态来确保缓存和将请求路由到负载较少的设备。

虽然从用户的角度来看，RESTful API 的设计原则并没有那么严格的定义，但还是有很多方法、指南和最佳实践来设计此类 API。这些对于为不同团队和部门提供强大且用户友好的 RESTful 应用程序接口至关重要。遵循既定标准和统一设计可促进开发团队、专家实验室、支持部门和客户之间的协作。

SevOne's RESTful API 遵循 Swagger API 文档规范。这样，用户就可以访问 SevOne API 文档，并通过 Swagger 用户界面执行与 SevOne NMS 数据相关的操作。本文档旨在指导用户如何有效地将 Swagger 用户界面与 SevOne API 结合使用。

管理
警报
AuthService
ClusterManager
ClusterOrchestrator
数据
DeviceGroups
设备
DeviceTypes
发现
文档
流程
运行状况
热补丁
图标
指标
MaintenanceWindows
元数据
MetadataAdmin
ObjectGroups
对象
对等点
许可权
插件
策略
正在轮询
代理数
角色
SDB配置
解决解方案
统计信息
支持
TopNViews
拓扑
陷阱
用户
Utils
Webhook
工作时间

先决条件

在线编辑

需要 SevOne NMS 中的有效帐户。

注：有关 RESTful API 和 SevOne NMS 端口要求的信息，请参阅 SevOne Best Practices Guide - Cluster, Peer, and HSA guide 了解详情。

要从 SevOne NMS 访问 API 文档，请在浏览器中输入 URL ，启动用户界面。

示例：启动 SevOne NMS


http://<PAS hostname or IP address>

单击管理菜单并选择 API 文档 > 版本 3。

示例：第3版的 URL


http://<PAS hostname or IP address>/api/v3/docs

如果您已登录，则已进入 Swagger 用户界面。不需要验证令牌，因为 X-AUTH-TOKEN 字段会自动填入令牌。

HTTP

在线编辑

包含以下主题

方法
页眉

HTTP 方法，包括 GET、POST、PUT、PATCH 和 DELETE，其功能是向服务器传达有关特定资源的预期操作。与此相反， HTTP 标头提供了与请求或响应有关的补充信息，包括内容类型或验证细节等元素。

方法

在线编辑

HTTP 可用的方法有

GET - 从服务器检索数据。
POST - 在服务器上获取/创建新资源。
PUT - 用提供的数据替换现有资源。
DELETE - 从服务器上删除资源。
PATCH - 部分修改现有资源。

头

在线编辑

HTTP 提供了一系列不同的标头，每个标头都有规范中列出的特定用途。 HTTP 这些标头用于传递有关请求本身的元数据，并明确 API 消费者和提供者之间的通信。它们不是用来传递有关传播内容的信息。

HTTP 标头的常见用途包括授权令牌或角色、指定请求或响应的格式等。例如， Content-Type 标头可以设置为 application/json ，以表示请求体是 JSON 格式，而 Accept 标头也可以设置为相同的值，以表示客户端希望得到 JSON 响应。

在 RESTful API 中，所有日期都是以毫秒为单位的 UNIX 时间戳，也称为纪元时间乘以 1000。例如，时间戳 1743119894000 与 2025 年 3 月 27 日星期四 19:58:14 GMT-0400 （东部夏令时间）相对应。

无论日期是作为查询参数、数据传输协议 (DTP) 属性，还是在 HTTP 方法或请求/响应体中提供，该约定都普遍适用于所有 RESTful API 调用。这一标准没有例外。

端点

在线编辑

端点是 RESTful 应用程序接口中单一实例或同一类别实例集合的唯一 URL 标识符。实例类型通常用 ID 等标识符表示，应简单明了。从本质上讲，任何可以在你的领域范围内概念化的抽象实体都可以被视为资源。端点是通过应用程序接口提供者和消费者之间对领域的相互理解而建立的。

这些实例包括但不限于警报、设备、对象、用户等。每个资源都代表一个不同的资源，可以通过 RESTful API 中定义的端点进行访问、操作或交互。这种相互理解确保了应用程序接口提供商和消费者之间的无缝通信和互动，促进了高效的数据交换和系统集成。

示例: 单个资源的端点

/api/v3/alerts/{id } 列出具有给定 id 的警报。
/api/v3/devicegroups/{id } 列出具有给定 id 的设备组。
/api/v3/devices/{deviceId }/object/ {objectId} 列出带有给定 deviceId 对象的设备列表。 objectId.

示例资源集合的端点

/api/v3/alerts 列出所有警报。
/api/v3/devicegroups 列出所有设备组。
/api /dev ices/ {deviceId} /objects 列出具有给定 deviceId 的设备的所有对象的集合。
/api/v3/devicegroups/{id }/members/ {deviceId} 列出具有给定 id 的设备组中具有给定 deviceId id 的设备组中的所有成员。

数据传输对象（DTO）

在线编辑

数据传输对象（Data Transfer Objects，简称 DTO）可帮助在 RESTful API 的提供者和消费者之间传输结构化数据。目前，应用程序接口只能处理 JSON 格式的数据。这意味着 API 提供商和消费者之间交换的所有数据都必须以 JSON 格式化，以确保数据传输方法的标准化和一致性。这种方法简化了数据处理和解释，促进了不同系统之间的无缝集成和通信。

示例 # 1 - POST /api/v3/users/signin

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
  \"password\": \"<SevOne NMS appliance password>\",
  \"username\": \"<SevOne NMS username>\"
}" "http://10.12.206.104/api/v3/users/signin"

URL

http://10.12.206.104/api/v3/users/signin

响应机构


{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJubXMiLCJzdWIiOiIxIiwiYXVkIjpbInNvYSJdLCJleHAiOjE3Njk0NTk4MzUsIm5iZiI6MTc2OTQ1ODAzNSwiaWF0IjoxNzY5NDU4MDM1LCJqdGkiOiIwYjhjMjdjYS0xZjU5LTRiY2QtYjUwNi03NmNiZjY2ODRjNDIiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.oxlzt1e0flIdXri_YeNz2U25jU-e8h6VSBtNt3Trc64",
  "user": {
    "active": true,
    "dateFormat": "%e %b '%y %H:%M:%S",
    "email": "",
    "firstName": "Sev",
    "id": "1",
    "lastName": "One",
    "roles": [
      "2",
      "3"
    ],
    "timezone": "America/New_York",
    "username": "admin"
  }
}

响应代码2 00表示成功。

示例 # 2 - POST /api/v3/alerts

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJubXMiLCJzdWIiOiIxIiwiYXVkIjpbInNvYSJdLCJleHAiOjE3Njk0NTk4MzUsIm5iZiI6MTc2OTQ1ODAzNSwiaWF0IjoxNzY5NDU4MDM1LCJqdGkiOiIwYjhjMjdjYS0xZjU5LTRiY2QtYjUwNi03NmNiZjY2ODRjNDIiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.oxlzt1e0flIdXri_YeNz2U25jU-e8h6VSBtNt3Trc64" -d "{}" "http://10.12.206.104/api/v3/alerts"

URL


http://10.12.206.104/api/v3/alerts

响应机构


{
  "alerts": [
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "1",
      "messageText": "Trap received from 127.0.0.1: SNMPv2-MIB::coldStart -- Bindings: SNMPv2-MIB::snmpTrapEnterprise = 0 -- The device was powered up.",
      "occurrences": "3",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "2",
      "messageText": "Trap received from 127.0.0.1: IF-MIB::linkUp -- Bindings: RFC1213-MIB::ifIndex.2 = 2, RFC1213-MIB::ifAdminStatus.2 = 1, RFC1213-MIB::ifOperStatus.2 = 1, SNMPv2-MIB::snmpTrapEnterprise.0 = .1.3.6.1.4.1.8072.3.2.10, SNMPv2-MIB::snmpTrapEnterprise = 0 -- An interface has come back up.",
      "occurrences": "6",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    ...
    ...
    ...
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": {
        "altName": "",
        "description": "DEFERRED Device",
        "displayName": "DEFERREDDevice 2",
        "id": "37",
        "ip": "127.0.0.1",
        "name": "DEFERREDDevice 2",
        "object": null
      },
      "endTime": "1743107009",
      "infoDevice": {
        "allowDelete": true,
        "altName": "",
        "dateAdded": "1712562042",
        "deleted": false,
        "description": "DEFERRED Device",
        "displayName": "DEFERREDDevice 2",
        "elements": "1",
        "id": "37",
        "ip": "127.0.0.1",
        "name": "DEFERREDDevice 2",
        "new": false,
        "lastDiscovery": "1712562169",
        "peerId": "1",
        "pollFrequency": "300",
        "timeZone": "America/New_York",
        "workHoursGroupId": "1"
      },
      "id": "54",
      "messageText": "Trap received from DEFERREDDevice 2: SNMPv2-MIB::authenticationFailure -- Bindings: SNMPv2-MIB::snmpTrapEnterprise = 0 -- An authentication failure has occurred.",
      "occurrences": "19948",
      "startTime": "1743044847",
      "severity": "WARNING",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    }
  ],
  "endTime": "1743107009",
  "startTime": "1691618263",
  "partialResults": null
}

响应代码2 00表示成功。

示例# 3 - GET /api/v3/devicegroups

Curl


curl -X GET --header "Accept: application/json" --header "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJubXMiLCJzdWIiOiIxIiwiYXVkIjpbInNvYSJdLCJleHAiOjE3Njk0NTk4MzUsIm5iZiI6MTc2OTQ1ODAzNSwiaWF0IjoxNzY5NDU4MDM1LCJqdGkiOiIwYjhjMjdjYS0xZjU5LTRiY2QtYjUwNi03NmNiZjY2ODRjNDIiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.oxlzt1e0flIdXri_YeNz2U25jU-e8h6VSBtNt3Trc64" "http://10.12.206.104/api/v3/devicegroups"

URL


http://10.12.206.104/api/v3/devicegroups

响应机构


{
  "content": [
    {
      "name": "All Device Groups",
      "parentId": "1",
      "id": "2",
      "devices": []
    },
    {
      "name": "Location",
      "parentId": "2",
      "id": "3",
      "devices": []
    },
    {
      "name": "Type",
      "parentId": "2",
      "id": "4",
      "devices": []
    },
    {
      "name": "Router",
      "parentId": "4",
      "id": "6",
      "devices": []
    },
    {
      "name": "Switch",
      "parentId": "4",
      "id": "7",
      "devices": []
    },
    {
      "name": "Server",
      "parentId": "4",
      "id": "8",
      "devices": []
    },
    {
      "name": "SevOneNMS Appliance",
      "parentId": "4",
      "id": "9",
      "devices": []
    },
    {
      "name": "Unclassified",
      "parentId": "2",
      "id": "10",
      "devices": []
    },
    {
      "name": "Manufacturer",
      "parentId": "2",
      "id": "11",
      "devices": []
    },
    {
      "name": "SevOne",
      "parentId": "11",
      "id": "12",
      "devices": []
    },
    {
      "name": "Cisco",
      "parentId": "11",
      "id": "13",
      "devices": []
    },
    {
      "name": "Juniper",
      "parentId": "11",
      "id": "14",
      "devices": []
    },
    {
      "name": "Huawei",
      "parentId": "11",
      "id": "16",
      "devices": []
    },
    {
      "name": "Extreme",
      "parentId": "11",
      "id": "17",
      "devices": []
    },
    {
      "name": "F5",
      "parentId": "11",
      "id": "18",
      "devices": []
    },
    {
      "name": "HP",
      "parentId": "11",
      "id": "19",
      "devices": []
    },
    {
      "name": "Dell",
      "parentId": "11",
      "id": "20",
      "devices": []
    },
    {
      "name": "EMC",
      "parentId": "11",
      "id": "21",
      "devices": []
    },
    {
      "name": "NetApp",
      "parentId": "11",
      "id": "22",
      "devices": []
    },
    {
      "name": "Brocade",
      "parentId": "11",
      "id": "23",
      "devices": []
    }
  ],
  "pageNumber": 0,
  "pageSize": 20,
  "totalPages": "4",
  "totalElements": "61"
}

其中，

totalElements 是在没有分页的情况下返回的资源计数。

pageSize 是请求返回的资源数量。这与查询参数的大小相对应。

pageNumber 为当前页码。这与页面查询参数相对应。返回的元素从索引为 ( pageNumber * pageSize ) 的元素开始。

响应代码2 00表示成功。

注：在 RESTful API 的上下文中，常见的惯例是为每种独特的资源类型关联一个 DTO，可通过 URL 进行识别。然而，我们必须认识到，这种被广泛采用的模式并不是一条僵硬、不屈不挠的规则。

RESTful API 服务的设计以可组合性为核心原则，允许以多种方式组合服务，以实现复杂的工作流程和场景。这种设计理念要求在设计 DTO 时注重通用性和可重用性。至关重要的是，要确保 DTO 具有多功能性和适应性，并能在各种用例中重复使用。这种方法不仅提高了数据处理效率，还促进了系统的无缝集成，从而增强了整体功能和灵活性。

过滤、排序和速率限制

在线编辑

包含以下主题

过滤
分类
费率限制

过滤

在线编辑

要检索过滤后的数据，终端会在请求结束时加入关键字 " 过滤 "。这些过滤端点专门用于读取资源，不具备修改服务器上任何数据的功能。鉴于必须传输数据传输对象（DTO），这些操作通过 POST 方法执行。值得注意的是，这些请求不会引起系统状态的任何变化，从而确保数据的完整性和一致性。

示例＃1 ： POST /api/v3/devicegroups/filter

在本例中，让我们用 deviceId.

restApiFilter

在参数下，在正文中添加 {"deviceId": "1"} 在正文中。这将返回包含 deviceId = 1 的所有设备组。有关输出结果，请参阅下面的 " 答复正文 "。

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJubXMiLCJzdWIiOiIxIiwiYXVkIjpbInNvYSJdLCJleHAiOjE3Njk0NTk4MzUsIm5iZiI6MTc2OTQ1ODAzNSwiaWF0IjoxNzY5NDU4MDM1LCJqdGkiOiIwYjhjMjdjYS0xZjU5LTRiY2QtYjUwNi03NmNiZjY2ODRjNDIiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.oxlzt1e0flIdXri_YeNz2U25jU-e8h6VSBtNt3Trc64" -d "{\"deviceId\": \"1\"}" "http://10.12.206.104/api/v3/devicegroups/filter"

URL


http://10.12.206.104/api/v3/devicegroups/filter

响应机构


{
  "content": [
    {
      "name": "All Device Groups",
      "parentId": "1",
      "id": "2"
    },
    {
      "name": "IP",
      "parentId": "2",
      "id": "24"
    },
    {
      "name": "IPv4",
      "parentId": "24",
      "id": "25"
    },
    {
      "name": "Class A",
      "parentId": "24",
      "id": "27"
    },
    {
      "name": "Special",
      "parentId": "2",
      "id": "40"
    },
    {
      "name": "All Devices",
      "parentId": "40",
      "id": "41"
    }
  ],
  "pageNumber": 0,
  "pageSize": 20,
  "totalPages": "0",
  "totalElements": "6"
}

这表明 deviceId = 1 的元素共有 6 个。

响应代码

200 表示成功。

示例＃2 ： POST /api/v3/plugins/filter

从下拉菜单中选择 queryType 从下拉菜单中选择 " FULL "，就会返回可用插件列表，如下表所示。


插件 ID	插件名称
1	SNMP 波勒
2	ICMP 轮询器
3	进程轮询器
4	HTTP
5	代理 Ping 轮询器
6	NBAR 轮询器
7	波尔舍克-波勒
8	DNS 轮询器
9	IP SLA 轮询器
10	延迟数据
11	WMI 波勒
15 日	VMware 轮询器
16	Web 状态轮询器
17	xStats
18	MySQL 数据库轮询器
20	计算轮询器
24	AWS
25 台	SDWAN
26	Azure
27 日	SDN
29 日	无线网络
30	GCP

Curl


curl -X GET --header "Accept: application/json" --header "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJubXMiLCJzdWIiOiIxIiwiYXVkIjpbInNvYSJdLCJleHAiOjE3Njk0NTk4MzUsIm5iZiI6MTc2OTQ1ODAzNSwiaWF0IjoxNzY5NDU4MDM1LCJqdGkiOiIwYjhjMjdjYS0xZjU5LTRiY2QtYjUwNi03NmNiZjY2ODRjNDIiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.oxlzt1e0flIdXri_YeNz2U25jU-e8h6VSBtNt3Trc64" "http://10.12.206.104/api/v3/plugins/filter?queryType=FULL"

URL


http://10.12.206.104/api/v3/plugins/filter?queryType=FULL

响应机构


{
  "workingPlugins": {
    "plugins": [
      {
        "pluginId": "1",
        "pluginName": "SNMP Poller",
        "deviceCount": "14"
      },
      {
        "pluginId": "2",
        "pluginName": "ICMP Poller",
        "deviceCount": "7"
      },
      {
        "pluginId": "3",
        "pluginName": "Process Poller",
        "deviceCount": "6"
      },
      {
        "pluginId": "4",
        "pluginName": "HTTP Poller",
        "deviceCount": "2"
      },
      {
        "pluginId": "5",
        "pluginName": "Proxy Ping Poller",
        "deviceCount": "2"
      },
      ...
      ...
      ...
      {
        "pluginId": "29",
        "pluginName": "Wi-Fi",
        "deviceCount": "0"
      },
      {
        "pluginId": "30",
        "pluginName": "GCP",
        "deviceCount": "0"
      }
    ],
    "pluginCount": "22"
  }

这表明有 22 个插件可用。

响应代码

200 表示成功。

排序

在线编辑

例如 邮寄 /api/v3/metadata/devices

本例演示了对输出进行排序的过程。排序基于两个标准：方向（升序或降序）和字段。字段选项涵盖各种属性，如备用名称、添加的数据、描述、显示名称、ID、IP 地址、最后发现、名称、对象数量、对等 ID、轮询频率和时区。这种排序机制可以根据用户的具体要求和偏好，定制个性化的数据展示方式。

restApiSort

在参数下，在主体中添加 “sorts” 变量，如上图所示。这将根据设备的显示名称按升序返回所有设备。有关输出结果，请参阅下面的 " 答复正文 "。

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJubXMiLCJzdWIiOiIxIiwiYXVkIjpbInNvYSJdLCJleHAiOjE3Njk0NTk4MzUsIm5iZiI6MTc2OTQ1ODAzNSwiaWF0IjoxNzY5NDU4MDM1LCJqdGkiOiIwYjhjMjdjYS0xZjU5LTRiY2QtYjUwNi03NmNiZjY2ODRjNDIiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.oxlzt1e0flIdXri_YeNz2U25jU-e8h6VSBtNt3Trc64" -d "{
  \"sorts\": [
    {
      \"direction\": \"DIRECTION_ASCENDING\",
      \"field\": \"FIELD_DISPLAY_NAME\"
    }
  ]
}" "http://10.12.206.104/api/v3/metadata/devices"

URL


http://10.12.206.104/api/v3/metadata/devices

响应机构


{
  "devices": [
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562041",
      "deleted": false,
      "description": "BULKDATA Device",
      "displayName": "BULKDATADevice 1",
      "elements": "0",
      "id": "15",
      "ip": "127.0.0.1",
      "name": "BULKDATADevice 1",
      "new": false,
      "lastDiscovery": "1712562145",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562042",
      "deleted": false,
      "description": "BULKDATA Device",
      "displayName": "BULKDATADevice 2",
      "elements": "0",
      "id": "45",
      "ip": "::1",
      "name": "BULKDATADevice 2",
      "new": false,
      "lastDiscovery": "1712562155",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562041",
      "deleted": false,
      "description": "COC Device",
      "displayName": "COCDevice 1",
      "elements": "1",
      "id": "17",
      "ip": "127.0.0.1",
      "name": "COCDevice 1",
      "new": false,
      "lastDiscovery": "1712562163",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562042",
      "deleted": false,
      "description": "COC Device",
      "displayName": "COCDevice 2",
      "elements": "1",
      "id": "49",
      "ip": "::1",
      "name": "COCDevice 2",
      "new": false,
      "lastDiscovery": "1712562171",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562041",
      "deleted": false,
      "description": "DEFERRED Device",
      "displayName": "DEFERREDDevice 1",
      "elements": "1",
      "id": "11",
      "ip": "127.0.0.1",
      "name": "DEFERREDDevice 1",
      "new": false,
      "lastDiscovery": "1712562161",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    },
    ...
    ...
    ...
    {
      "allowDelete": true,
      "altName": "",
      "dateAdded": "1712562042",
      "deleted": false,
      "description": "WMI Device",
      "displayName": "WMIDevice 2",
      "elements": "11",
      "id": "39",
      "ip": "10.129.20.1",
      "name": "WMIDevice 2",
      "new": false,
      "lastDiscovery": "1712562152",
      "peerId": "1",
      "pollFrequency": "300",
      "timeZone": "America/New_York",
      "workHoursGroupId": "1"
    }
  ]
}

响应主体生成一个设备列表，按其显示名称进行组织和呈现。输出结果按升序排列，便于对数据进行系统化和结构化审查。

费率限制

在线编辑

在处理大量数据输出时，应用程序接口提供了一种机制，可根据用户指定的限制来限制数据量。这一功能使用户能够更有效地处理和解释大型数据集，确保他们只访问和审查与其要求相关的数据。

例如 邮寄 /api/v3/alerts

restApiRateLimits

在参数下，在主体中添加 “pagination” 变量，其中包含您想要限制的数据量，如上面的屏幕截图所示。由于限制设置为 3，因此将返回 3 个警报。有关输出结果，请参阅下面的 " 答复正文 "。

Curl


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJubXMiLCJzdWIiOiIxIiwiYXVkIjpbInNvYSJdLCJleHAiOjE3Njk0NTk4MzUsIm5iZiI6MTc2OTQ1ODAzNSwiaWF0IjoxNzY5NDU4MDM1LCJqdGkiOiIwYjhjMjdjYS0xZjU5LTRiY2QtYjUwNi03NmNiZjY2ODRjNDIiLCJVc2VyIjp7ImFjdGl2ZSI6dHJ1ZSwiZGF0ZV9mb3JtYXQiOiIlZSAlYiAnJXkgJUg6JU06JVMiLCJmaXJzdF9uYW1lIjoiU2V2IiwiaWQiOjEsImxhc3RfbmFtZSI6Ik9uZSIsInJvbGVzIjpbMiwzXSwidGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJEZXB0aCI6MH0.oxlzt1e0flIdXri_YeNz2U25jU-e8h6VSBtNt3Trc64" -d "{
  \"pagination\": {
    \"limit\": \"3\"
  }
}" "http://10.12.206.104/api/v3/alerts"

URL


http://10.12.206.104/api/v3/alerts

响应机构


{
  "alerts": [
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "1",
      "messageText": "Trap received from 127.0.0.1: SNMPv2-MIB::coldStart -- Bindings: SNMPv2-MIB::snmpTrapEnterprise = 0 -- The device was powered up.",
      "occurrences": "3",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "2",
      "messageText": "Trap received from 127.0.0.1: IF-MIB::linkUp -- Bindings: RFC1213-MIB::ifIndex.2 = 2, RFC1213-MIB::ifAdminStatus.2 = 1, RFC1213-MIB::ifOperStatus.2 = 1, SNMPv2-MIB::snmpTrapEnterprise.0 = .1.3.6.1.4.1.8072.3.2.10, SNMPv2-MIB::snmpTrapEnterprise = 0 -- An interface has come back up.",
      "occurrences": "6",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    },
    {
      "alertType": "TRAP",
      "clearedMessageText": "",
      "closed": false,
      "device": null,
      "endTime": "1708097859",
      "id": "3",
      "messageText": "Trap received from 127.0.0.1: IF-MIB::linkDown -- Bindings: RFC1213-MIB::ifIndex.3 = 3, RFC1213-MIB::ifAdminStatus.3 = 1, RFC1213-MIB::ifOperStatus.3 = 2, SNMPv2-MIB::snmpTrapEnterprise.0 = .1.3.6.1.4.1.8072.3.2.10, SNMPv2-MIB::snmpTrapEnterprise = 0 -- An interface has gone down.",
      "occurrences": "3",
      "startTime": "1691618263",
      "severity": "NOTICE",
      "thresholdId": "-1",
      "threshold": null,
      "assignedTo": "0",
      "assignedUser": null,
      "ignoreUntil": "0",
      "ignoreUid": "0",
      "ignoreComment": "",
      "acknowledgedBy": "",
      "comments": "",
      "pluginName": "127.0.0.1"
    }
  ],
  "endTime": "1708097859",
  "startTime": "1691618263",
  "partialResults": null
}

检查 " 响应体 "后发现，它包含三个不同的警报。其中一个关键指标是变量 messageText 的存在，它表示在输出中存在该变量的三个实例。即

SNMPv2-MIB::coldStart
IF-MIB::linkUp
IF-MIB::linkDown

响应代码

200 表示成功。

故障诊断

在线编辑

包含以下主题

HTTP 状态代码

执行操作后，"响应代码 "部分将显示 HTTP 状态代码，作为操作状态的指示符。例如，状态代码为 200 表示操作成功。在操作失败的情况下，"响应正文 "字段可提供所遇到问题的详细信息。

下面的截图举例说明了在未进行身份验证的情况下尝试执行操作时出现的错误。在这种情况下，相关的 HTTP 状态代码为 401，并附有 "未经授权 "的描述。在这种情况下，"详细信息 "后面会提供有关错误的补充信息：。

HTTP 状态代码

在线编辑

下表列出了执行 RESTful API 请求时返回的 HTTP 状态代码。

注：有关 HTTP 状态代码的完整列表，请参阅 HTTP 状态代码。


HTTP 状态码	描述
200 (OK)	已成功执行请求。
201 (已创建)	成功执行请求并在系统中创建新资源。
204（无内容）	已成功执行请求，但未返回任何内容。它用于 RESTful API 中的所有 DELETE 请求。
400 (Bad Request)	由于认为是客户机错误，服务器无法处理请求。例如，格式不正确的请求语法，无效的请求消息框架或欺骗性请求路由。
401 (未经授权)	未执行请求，因为它缺少目标资源的有效认证凭证。
403 (已禁止)	使用对于获取对资源的访问权并不重要的有效凭证来执行请求。
404 (未找到)	找不到请求的资源。例如，请求了错误的 URI 请求在设备组中添加设备，但找不到设备组
409 (Conflict)	由于与目标资源的当前状态冲突，无法创建/更新该资源。例如，请求创建新设备，但系统中已存在具有该名称的设备
422（无法处理的实体）	请求中缺少必需元素。
424（失败的依赖关系）	未成功执行外部系统。例如， RESTful API 执行失败的 NMS 脚本。
500 (内部服务器错误)	服务器迂到阻止其实现请求的意外情况。
503（服务不可用）	由于临时超负荷或调度的维护，服务器无法处理请求，这可能会在某些延迟后得到缓解。