Scroll Alerts


查询当前和历史告警，第一次查询跟随机查询的方式类似，得到一个 pageToken，后续每一页都是根据 pageToken 来查询下一页。

请求格式

POST https://{apigw-address}/alert-service/v2.1/alerts?action=scroll

请求参数（URI）

名称

位置（Path/Query）

必需/可选

数据类型

描述

orgId

Query

必需

String

资产所属的组织 ID。如何获取 orgId 信息>>

请求参数（Body）

名称

必需/可选

数据类型

描述

instanceId

可选

String

告警的实体，现阶段只有 asset，取值为 assetId。

metricId

可选

String

指标，比如测点。

startOccurTime

必需

String

查询起始时间，与 endOccurTime 配合使用，表示查询该时段内（不超过 3 个月）被触发的告警。API 在使用的时间参数>>

endOccurTime

必需

String

查询结束时间，与 startOccurTime 配合使用，表示查询该时段内（不超过 3 个月）被触发的告警。API 在使用的时间参数>>

startRecoverTime

可选

String

查询起始时间，与 endRecoverTime 配合使用，表示查询在该时段内异常状态恢复正常的告警，若不指定，默认为最近一周的数据。若为空，只返回当前告警。API在使用的时间参数>>

endRecoverTime

可选

String

查询起始时间，与 startRecoverTime 配合使用，表示查询在该时段内异常状态恢复正常的告警，若不指定，默认为最近一周的数据。若为空，只返回当前告警。API在使用的时间参数>>

active

可选

Boolean

  • true：只搜索当前的告警

  • false：只搜索历史告警

  • null（默认）：搜索全部告警，包括历史告警和当前的告警。

expression

可选

String

查询表达式，支持类 SQL 的查询。目前支持的逻辑运算是 and 和 or，查询的字段和对应的运算符清单如下。

  • instanceId、metricId、severityId、typeId、parentTypeId、contentId、ruleId、eventType 和 alertId：=、in 和 !=

  • metricTags.*、ruleTags.* 和 tags.*：=、in、!=、like 和 exists

  • inhibited：= 和 !=

  • maskedBy：=

字段描述参见 AlertVo 结构体。

如何使用查询表达式>>

scroll

必填

Scroll 结构体

翻页。只能按照 occurTime 倒序排列，不能指定排序字段。Scroll 结构体>>

Scroll 结构体

名称

必需/可选

数据类型

描述

pageSize

  • 第一次查询：必需

  • 第二次以上查询：不必填，会按照第一次的 pageSize 进行返回

Integer

每页记录数，必须大于 0。

pageToken

  • 第一次查询：不允许填

  • 第二次以上查询：必需

String

下一页的 token。

响应参数

名称

数据类型

描述

data

EnosScrollData 结构体

返回结果。EnosScrollData 结构体>>

EnosScrollData 结构体

名称

数据类型

描述

pageToken

String

下一页的 token。

pageSize

int

每页记录数。

sortedBy

Sorters 结构体数组

排序方式。有关 Sorters 结构体的定义，参见 Sorters 结构体。

items

AlertVo 结构体数组

具体的告警记录列表。有关 Alert 结构体的定义，参见 AlertVo 结构体。

AlertVo 结构体

名称

数据类型

描述

alertId

String

告警 ID。

eventType

Integer

  • 0：告警解除，通过规则触发（历史告警）

  • 1：告警开始，通过规则触发（当前告警）

  • 2：告警解除，通过接口创建（历史告警）

  • 3：告警开始，通过接口创建（当前告警）

  • 4：离散告警（历史告警）

  • 5: 乱序告警（历史告警）

其中，在 Create Alert 接口中，只允许填 2、3、4。

orgId

String

资产所属的组织 ID。

instanceId

String

告警的实体，现阶段只有 asset，取值为 assetId。

metricId

String

原始度量数据的 ID。

occurTime

Long

告警发生的时间，以 UTC 时间表示，格式见 UTC 采用的 ISO8601 标准时间格式>>

localOccurTime

String

告警发生的时间，以本地时间表示，格式见 localtime 采用的日期时间格式>>

recoverTime

Long

触发告警的异常状况恢复正常的时间，以 UTC 时间表示，格式见 UTC 采用的 ISO8601 标准时间格式>>

localRecoverTime

String

触发告警的异常状况恢复正常的时间，以本地时间表示，格式见 localtime 采用的日期时间格式>>

recoverReason

String

异常状况恢复的原因。

value

String

告警产生时的 metric value，对于高级的告警功能比如多测点告警或者时序告警，使用产生告警对应的那个 metric 的 value。

metricTags

Map

原始度量数据的标签。Key 和 Value 为 String。标签的作用与表示方法>>

不同业务/系统会有不同的原始度量，定义的标签也会不同。EnOS 有以下可能出现在 metricTags 标准标签。 其中带有 __ 前缀和后缀的标签是通用的 key，没带 __ 的是与业务相关的 key。

{

__timezone__: 时区

__instance__： instanceId

__metric__： metricId

__alias__： metricId 的别名

modelIdPath： 模型路径

modelId： modelId

assetTreePath： 资产树路径

assetTreePath_${treeId}: 指定 treeId 的资产树路径

}

severityId

String

告警级别编号。

severityDesc

StringI18n

告警级别描述。结构参见 国际化名称结构体。

typeId

String

告警类型编号。

typeDesc

StringI18n

告警类型描述。结构参见 国际化名称结构体。

parentTypeId

String

告警父类型编号。

parentTypeDesc

StringI18n

告警父类型描述。结构参见 国际化名称结构体。

content

StringI18n

告警内容。结构参见 国际化名称结构体。

ruleId

String

告警规则编号。

ruleDesc

StringI18n

告警规则描述。结构参见 国际化名称结构体。

ruleTags

Map

规则上的标签。

tags

Map

标签，只支持全量更新。标签的作用与表示方法>>

inhibited

Boolean

  • true：屏蔽

  • false：没被屏蔽

示例

第一次请求示例

url: https://{apigw-address}/alert-service/v2.1/alerts?action=scroll&orgId=yourOrgId
method: POST
requestBody:
{
    "endOccurTime":"2020-11-15T00:00:00Z",
    "startOccurTime":"2020-10-10T00:00:00Z",
    "scroll":{
        "pageSize":1
    }
}

返回示例

{
    "code":0,
    "msg":"OK",
    "requestId":"64a0ac08-eba9-4fc9-ab67-20092ec8a7c8",
    "data":{
        "items":[
            {
                "alertId":"202011146df8f354ebbebe233eee5a3bba2e3a00",
                "eventType":3,
                "orgId":"yourOrgId",
                "instanceId":"231",
                "metricId":"int1",
                "occurTime":1605372245417,
                "localOccurTime":"2020-11-02 00:00:00",
                "recoverTime":null,
                "localRecoverTime":null,
                "recoverReason":null,
                "value":"int1",
                "metricTags":{
                    "modelId":"moni01",
                    "modelIdPath":"/moni01"
                },
                "severityId":"setSeverityId",
                "severityDesc":{
                    "defaultValue":"defaultDeviceName12:44:05AM",
                    "i18nValue":{
                        "en_US":"EnglishName",
                        "zh_CN":"中文名"
                    }
                },
                "typeId":"setSubTypeId",
                "typeDesc":{
                    "defaultValue":null,
                    "i18nValue":{

                    }
                },
                "parentTypeId":"setTypeId",
                "parentTypeDesc":{
                    "defaultValue":null,
                    "i18nValue":{

                    }
                },
                "content":{
                    "defaultValue":null,
                    "i18nValue":{

                    }
                },
                "ruleId":null,
                "ruleDesc":null,
                "ruleTags":{
                    "color": "orange"
                },
                "tags":{
                    "223":"new",
                    "224":"new1"
                },
                "inhibited":null
            }
        ],
        "sortedBy":[
            {
                "field":"occurTime",
                "order":"DESC"
            },
            {
                "field":"alertId",
                "order":"DESC"
            }
        ],
        "pageToken":"pageTokenExample",
        "pageSize":1
    }
}

第二次请求示例

url: https://{apigw-address}/alert-service/v2.1/alerts?action=scroll&orgId=yourOrgId
method: POST
requestBody:
{
    "scroll":{
        "pageSize":0,
        "pageToken":"pageTokenExample"
    }
}

返回示例

{
    "code":0,
    "msg":"OK",
    "requestId":"44addba6-22d6-4290-9ef9-d064d3adced6",
    "data":{
        "items":[
            {
                "alertId":"202011145d4b63f0241a9dfb16f705d67cadadc3",
                "eventType":3,
                "orgId":"o15475450989191",
                "instanceId":"testBatch",
                "metricId":"int1",
                "occurTime":1605372245417,
                "localOccurTime":"2021-01-02 00:00:00",
                "recoverTime":null,
                "localRecoverTime":null,
                "recoverReason":null,
                "value":"int1",
                "metricTags":{
                    "modelId":"CCmodel",
                    "modelIdPath":"/CCmodel"
                },
                "severityId":"setSeverityId1",
                "severityDesc":null,
                "typeId":"setSubTypeId",
                "typeDesc":null,
                "parentTypeId":"setTypeId1",
                "parentTypeDesc":null,
                "content":null,
                "ruleId":null,
                "ruleDesc":null,
                "ruleTags":{
                    "color": "orange"
                },
                "tags":{

                },
                "inhibited":null
            }
        ],
        "sortedBy":[
            {
                "field":"occurTime",
                "order":"DESC"
            },
            {
                "field":"alertId",
                "order":"DESC"
            }
        ],
        "pageToken":"pageToken2",
        "pageSize":0
    }
}

SDK 示例


你可以在 Github 上获取告警引擎的 SDK 示例：