机器数据分析平台

  • 机器数据分析平台 > API Reference > 数据查询

    数据查询

    最近更新时间:2020-02-15 17:36:54

    1. 接口清单

    SPL 查询接口是 Pandora 2.0 非常重要的接口,通过输入SPL的方式获取搜索或者分析结果。以下是搜索接口的清单:

    1. 创建搜索任务接口:/api/v1/jobs
    2. 获得搜索任务元信息接口:/api/v1/jobs/<JobId>
    3. 搜索事件接口events:/api/v1/jobs/<JobId>/events
    4. 搜索时间柱接口timeline:/api/v1/jobs/<JobId>/timeline
    5. 字段汇总统计接口summary:/api/v1/jobs/<JobId>/summary
    6. SPL 计算接口:/api/v1/jobs/<JobId>/results

    搜索的逻辑一般如下:

    1. 创建搜索任务,获取任务id
    2. 根据任务id 查询搜索任务信息,获得任务的执行状态、执行时间,得知任务类型是搜索(isResult=false)还是SPL计算(isResult=true)
    3. 持续轮询相应的计算任务结果接口,获得计算结果
      2.1. 如果是搜索类型任务,轮询获得eventstimelinesummary 的接口结果
      2.2. 如果是SPL计算类型任务,轮询获得results 的接口结果

    注意:搜索接口的请求格式是json格式,所以请求Header中必须添加 'Content-Type: application/json'

    2. 接口描述

    2.1 创建搜索任务

    请求路径:/api/v1/jobs

    请求方法:POST

    请求体示例:

    {
        "query": "* | stats count() by sourcetype",
        "startTime": 1578918430156,
        "endTime": 1578919155378,
        "actions": [
            "events",
            "timeline",
            "simple_summary", 
            "result"
        ]
    }
    

    请求体字段解释:

    字段名 是否必填 字段解释 默认值
    query 查询SPL语句,请参考 SPL参考手册
    startTime 查询起始时间,格式为毫秒精度时间戳,startTime为闭区间 最早的数据时间
    endTime 查询截止时间,格式为毫秒精度时间戳,endTime为开区间 当前时间
    actions 字符串数组,限制搜索任务执行操作,包含 eventstimelinesimple_summarysummaryresult eventstimelinesummaryresult

    actions 选项释义:

    选项 解释
    events 搜索任务需要收集命中搜索结果
    timeline 搜索任务需要收集数据时间轴计数统计结果
    summary 搜索任务需要收集字段统计信息,详细模式中会使用summary模式
    simple_summary 搜索任务需要收集字段缩略信息,极速模式中会使用simple_summary模式
    result 搜索任务收集统计结果

    响应体示例:

    {"id":"otjtnm8B2y-I4NYNAYOq"}
    

    响应体字段释义:

    字段名 是否必填 字段解释
    id 搜索任务id

    2.2 获得搜索任务元信息

    请求路径:/api/v1/jobs/<JobId>

    注意<JobId> 为创建搜索任务返回结果中的id字段值

    请求方法:GET

    响应体示例:

    {
        "process": 1,
        "duration": 17771,
        "scanCount": 0,
        "eventCount": 703919,
        "isResult": false,
        "isExport": false
    }
    

    响应体字段示例:

    字段名 是否必填 字段解释
    process 搜索状态,0代表搜索进行中,1代表搜索结束
    duration 搜索持续时间,毫秒单位
    scanCount 【废弃字段】结果为0
    eventCount 返回命中结果总数
    isResult 是否SPL transform命令,一般为统计命令结果,如果为true,则应该轮询获得 results 接口结果
    isExport 是否SPL export命令,一般为导出结果,如果为true,则应该轮询等待导出结果

    注意:当process 不为1的时候,持续去轮询相应的结果接口,获得最终搜索结果。

    2.3 搜索事件 events

    请求路径:/api/v1/jobs/<JobId>/events?rawLenLimit=<true|false>

    注意

    1. <JobId> 为创建搜索任务返回结果中的id字段值
    2. rawLenLimit 限制返回原始数据长度,避免返回过长数据,导致无法正常页面展示,默认不限制返回原始数据长度

    请求方法:GET

    响应体示例:

    {
        "rows": [
            {
                "collectTime": {
                    "value": null,
                    "highlight": false
                },
                "uid": {
                    "value": 1,
                    "highlight": false
                },
                "_raw": {
                    "value": "1,\u5bf9\u6bd4",
                    "tokens": [
                        {
                            "startOffset": 0,
                            "endOffset": 1,
                            "highlight": false
                        },
                        {
                            "startOffset": 2,
                            "endOffset": 3,
                            "highlight": false
                        },
                        {
                            "startOffset": 3,
                            "endOffset": 4,
                            "highlight": false
                        }
                    ]
                },
                "origin": {
                    "value": "a.txt",
                    "highlight": false
                },
                "repo": {
                    "value": "atxt",
                    "highlight": false
                },
                "host": {
                    "value": "upload",
                    "highlight": false
                },
                "action": {
                    "value": "\u5bf9\u6bd4",
                    "highlight": false
                },
                "sourcetype": {
                    "value": "aa",
                    "highlight": false
                },
                "_time": {
                    "value": 1574816466030,
                    "highlight": false
                }
            }
        ]
    }
    

    响应体释义:

    字段名 是否必填 字段解释
    rows 对象数组,每个对象代表一个事件
    rows.字段.value 事件的字段值
    rows.字段.highlight 字段返回结果是否高亮显示
    rows._raw.tokens 原始数据的分词结果
    rows._raw.tokens.startOffset 原始数据关键词开始位置
    rows._raw.tokens.endOffset 原始数据关键词结束位置
    rows._raw.tokens.highlight 原始数据关键词是否高亮

    2.4 搜索时间柱 timeline

    请求路径:/api/v1/jobs/<JobId>/timeline

    注意<JobId> 为创建搜索任务返回结果中的id字段值

    请求方法:GET

    响应体示例:

    {
        "buckets": [
            {
                "key": 1578893348510,
                "value": 0
            }
        ]
    }
    

    响应体释义:

    字段名 是否必填 字段解释
    buckets 对象数组,每个对象代表一个时间柱数据
    buckets.key 时间柱的时间,毫秒精度时间戳
    buckets.value 该时间的统计计数数量

    2.5 字段汇总统计 summary

    请求路径:/api/v1/jobs/<JobId>/summary

    注意<JobId> 为创建搜索任务返回结果中的id字段值

    请求方法:GET

    响应体示例:

    {
        "uid": {
            "distinct": 1,
            "max": "1.0",
            "min": "1.0",
            "avg": 1.0,
            "count": 4,
            "buckets": {
                "1": 4
            }
        },
        "host": {
            "distinct": 1,
            "count": 4,
            "buckets": {
                "upload": 4
            }
        },
        "origin": {
            "distinct": 1,
            "count": 4,
            "buckets": {
                "a.txt": 4
            }
        },
        "repo": {
            "distinct": 1,
            "count": 4,
            "buckets": {
                "atxt": 4
            }
        },
        "sourcetype": {
            "distinct": 1,
            "count": 4,
            "buckets": {
                "aa": 4
            }
        }
    }
    

    响应体释义:

    注意:响应体是key-value对,key为数据字段名,value为字段的统计信息。

    字段名 是否必填 字段解释
    字段.distinct 字段的值去重计数
    字段.count 非null字段值的计数
    字段.max 数值字段返回结果,字段最大值
    字段.min 数值字段返回结果,字段最小值
    字段.avg 数值字段返回结果,字段平均值
    字段.buckets 该字段Top 10的字段值,以及其出现频次

    2.6 SPL 计算结果

    请求路径:/api/v1/jobs/<JobId>/results

    注意<JobId> 为创建搜索任务返回结果中的id字段值

    请求方法:GET

    响应体示例:

    {
        "fields": [
            {
                "flag": "bucket",
                "bucketIndex": 0,
                "name": "sourcetype"
            },
            {
                "flag": "metric",
                "name": "count"
            }
        ],
        "rows": [
            [
                "aa",
                4
            ]
        ]
    }
    

    响应体释义:

    字段名 是否必填 字段解释
    fields 返回数据中的字段列表
    rows 数组,返回所有计算结果
    fields.flag 字段的类型,bucket 代表是分组字段,metric 代表是统计值
    fields.bucketIndex 字段序号,在rows数组中对应的是哪个序号
    fields.name 字段值
    以上内容是否对您有帮助?
  • Icon free helper
    Close