跳至主要内容

搜索脚本API

该脚本API旨在通过API调用简化搜索和聚合功能的访问。脚本API仅提供一个数据集、一条消息列表或一次聚合结果。大多数请求参数为可选，以进一步简化流程。

响应内容类型根据提供的 accept 请求头而异。支持的取值包括：

  • text/plain

  • text/csv

  • application/json

虽然纯文本和CSV响应格式不同，但包含的数据量相同。相比之下，JSON响应包含更多信息，包括模式属性中的列详情和元数据属性中的有效时间范围。

搜索消息

该端点允许直接从搜索页面访问消息。默认情况下，消息按时间戳排序，最新消息优先。典型用法是获取最新的X条消息（默认为10条），并可自定义响应中需要返回的字段。 

GET https://example.org/api/search/messages?fields=source,
http_method,http_response_code,took_ms
POST https://example.org/api/search/messages
{
    "query": "http_method:POST",
    "streams": ["620f890b70fb980467aca611"],
    "fields": [
        "timestamp",
        "source",
        "http_method",
        "http_response_code",
        "took_ms"
    ],
    "from": 2,
    "size": 15,
    "timerange": {
        "type": "keyword",
        "keyword": "最近五分钟"
    },
    "sort": "took_ms",
    "sort_order": "降序"
}

GET请求接受的参数与POST请求相同，唯一例外是POST请求可接受时间范围参数。时间范围参数支持：相对时间、绝对时间和关键字。关于时间范围选择器的更多信息，请参阅 这篇知识库文章。

注意

流、源和输入端点的默认返回字段是标题。若要显示ID，请在项目名称后追加 .id .

请求与响应示例

以下是一些请求和响应示例。请求头中 accept 字段的text/csv、text/plain和application/json值决定了返回响应的格式。 

➜  curl  -H 'Accept: text/csv' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/messages?fields=source,http_method,http_response_code,took_ms'
"字段: source","字段: http_method","字段: http_response_code","字段: took_ms"
"example.org","GET","200","36"
"example.org","GET","200","36"
"example.org","GET","200","48"
"example.org","PUT","200","129"
"example.org","POST","201","134"
"example.org","POST","201","134"
"example.org","GET","200","52"
"example.org","GET","200","48"
"example.org","GET","200","48"
"example.org","GET","200","63"
➜  curl  -H 'Accept: text/plain' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/messages?fields=source,http_method,http_response_code,took_ms'
┌────────────────────────┬────────────────────────┬────────────────────────┬───────────────────────┐
│字段: source           │字段: http_method      │字段:                  │字段: took_ms         │
│                        │                        │http_response_code      │                       │
├────────────────────────┼────────────────────────┼────────────────────────┼───────────────────────┤
│example.org             │GET                     │200                     │56                     │
│example.org             │GET                     │200                     │45                     │
│example.org             │GET                     │200                     │44                     │
│example.org             │GET                     │200                     │56                     │
│example.org             │GET                     │200                     │42                     │
│example.org             │DELETE                  │204                     │89                     │
│example.org             │DELETE                  │204                     │89                     │
│example.org             │GET                     │200                     │38                     │
│example.org             │GET                     │200                     │38                     │
│example.org             │DELETE                  │204                     │95                     │
└────────────────────────┴────────────────────────┴────────────────────────┴───────────────────────┘%
➜  curl  -H 'Accept: application/json' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/messages?fields=source,http_method,http_response_code,took_ms'
{
  "schema": [
    {
      "column_type": "字段",
      "type": "未知",
      "field": "来源",
      "name": "字段: 来源"
    },
    {
      "column_type": "字段",
      "type": "字符串",
      "field": "http方法",
      "name": "字段: http方法"
    },
    {
      "column_type": "字段",
      "type": "未知",
      "field": "http响应码",
      "name": "字段: http响应码"
    },
    {
      "column_type": "字段",
      "type": "数值",
      "field": "耗时(毫秒)",
      "name": "字段: 耗时(毫秒)"
    }
  ],
  "datarows": [
    [
      "example.org",
      "GET",
      200,
      50
    ],
    [
      "example.org",
      "GET",
      200,
      50
    ],
    [
      "example.org",
      "GET",
      200,
      55
    ],
    [
      "example.org",
      "GET",
      200,
      63
    ],
    [
      "example.org",
      "GET",
      200,
      63
    ],
    [
      "example.org",
      "GET",
      200,
      63
    ],
    [
      "example.org",
      "GET",
      200,
      37
    ],
    [
      "example.org",
      "GET",
      200,
      46
    ],
    [
      "example.org",
      "GET",
      200,
      59
    ],
    [
      "example.org",
      "GET",
      200,
      52
    ]
  ],
  "metadata": {
    "effective_timerange": {
      "from": "2023-04-05T09:08:23.193Z",
      "to": "2023-04-06T09:08:23.193Z",
      "type": "绝对时间"
    }
  }
}

聚合

该端点允许执行包含多个分组和指标的聚合操作。例如，您可以通过HTTP方法和响应代码对HTTP请求消息进行分组，并找出这些组的最小和最大响应时间。

GET和POST格式的请求获取相同的数据。POST请求允许额外的配置选项，这些在GET格式中不可用。例如，使用POST请求时，您可以在分组聚合时定义限制和排序。 

GET https://example.org/api/search/aggregate?groups=http_method&metrics=avg:took_ms&metrics=count
POST https://example.org/api/search/aggregate
{
    "query": "source:example.org",
    "streams": [
        "620f890b70fb980467aca611"
    ],
    "timerange": {
        "type": "关键字",
        "keyword": "最近五分钟"
    },
    "group_by": [
        {
            "field": "http_method"
        },
        {
            "field": "http_response_code",
            "limit": 2
        }
    ],
    "metrics": [
        {
            "function": "min",
            "field": "took_ms"
        },
        {
            "function": "max",
            "field": "took_ms",
            "sort": "desc"
        }
    ]
}

指标定义为 函数:字段名 对。使用POST请求时，您还可以定义带排序的指标。POST请求允许包含比GET请求更多的信息。

百分位数指标还可以进一步配置如下： 

{
        "function": "percentile",
        "field": "took_ms",
        "configuration": 
        {"percentile": 90}
}

其他可用的指标函数包括： 平均值 , 计数 , 最新值 , 最大值 , 最小值 , 百分位数 , 标准差 , 总和 , 平方和 、 方差 .

请求与响应示例

以下是聚合功能的一些请求与响应示例。Accept请求头中的text/plain、text/csv和application/json值决定了返回响应的格式。 

➜  curl  -H 'Accept: text/plain' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/aggregate?groups=http_method&metrics=avg:took_ms&metrics=count'
┌────────────────────────┬────────────────────────┬───────────────────────┐
│分组: http_method       │指标: avg(took_ms)      │指标: count()          │
├────────────────────────┼────────────────────────┼───────────────────────┤
│GET                     │84.59519448510214       │3326553                │
│DELETE                  │96.02973055642204       │330199                 │
│POST                    │170.11398232130765      │329323                 │
│PUT                     │132.19959919839678      │154690                 │
└────────────────────────┴────────────────────────┴───────────────────────┘
➜  curl  -H 'Accept: text/csv' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/aggregate?groups=http_method&metrics=avg:took_ms&metrics=count'
"分组: http_method","指标: avg(took_ms)","指标: count()"
"GET","84.58997204888469","3326522"
"DELETE","96.02450487553752","330220"
"POST","170.08947537817832","329342"
"PUT","132.2030966157029","154685"
➜ curl  -H 'Accept: application/json' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/aggregate?groups=http_method&metrics=avg:took_ms&metrics=count'
{
  "数据结构": [
    {
      "列类型": "分组",
      "类型": "字符串",
      "字段": "http_method",
      "名称": "分组: http_method"
    },
    {
      "列类型": "指标",
      "类型": "数值",
      "函数": "avg",
      "字段": "took_ms",
      "名称": "指标: avg(took_ms)"
    },
    {
      "列类型": "指标",
      "类型": "数值",
      "函数": "count",
      "名称": "指标: count()"
    }
  ],
  "数据行": [
    [
      "GET",
      84.6043288978779,
      3326528
    ],
    [
      "DELETE",
      96.02355285311111,
      330236
    ],
    [
      "POST",
      170.09012904205252,
      329350
    ],
    [
      "PUT",
      132.20231038249952,
      154693
    ]
  ],
  "元数据": {
    "有效时间范围": {
      "起始": "2023-04-05T09:14:39.731Z",
      "截止": "2023-04-06T09:14:39.731Z",
      "类型": "绝对时间"
    }
  }
}
{
    "查询": "http_method:POST",
    "数据流": ["620f890b70fb980467aca611"],
    "字段": [
        "时间戳",
        "来源",
        "http方法",
        "http响应码",
        "耗时(毫秒)"
    ],
    "起始位置": 2,
    "返回数量": 15,
    "时间范围": {
        "类型": "关键词",
        "关键词": "最近五分钟"
    },
    "排序": "耗时(毫秒)",
    "排序顺序": "降序"
}
➜  curl  -H 'Accept: text/csv' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/messages?fields=source,http_method,http_response_code,took_ms'
"字段: 来源","字段: HTTP方法","字段: HTTP响应码","字段: 耗时(毫秒)"
"example.org","GET","200","36"
"example.org","GET","200","36"
"example.org","GET","200","48"
"example.org","PUT","200","129"
"example.org","POST","201","134"
"example.org","POST","201","134"
"example.org","GET","200","52"
"example.org","GET","200","48"
"example.org","GET","200","48"
"example.org","GET","200","63"
➜  curl  -H 'Accept: text/plain' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/messages?fields=source,http_method,http_response_code,took_ms'
┌────────────────────────┬────────────────────────┬────────────────────────┬───────────────────────┐
│字段: 来源              │字段: HTTP方法          │字段:                   │字段: 耗时(毫秒)       │
│                        │                        │HTTP响应码              │                       │
├────────────────────────┼────────────────────────┼────────────────────────┼───────────────────────┤
│example.org             │GET                     │200                     │56                     │
│example.org             │GET                     │200                     │45                     │
│example.org             │GET                     │200                     │44                     │
│example.org             │GET                     │200                     │56                     │
│example.org             │GET                     │200                     │42                     │
│example.org             │DELETE                  │204                     │89                     │
│example.org             │DELETE                  │204                     │89                     │
│example.org             │GET                     │200                     │38                     │
│example.org             │GET                     │200                     │38                     │
│example.org             │DELETE                  │204                     │95                     │
└────────────────────────┴────────────────────────┴────────────────────────┴───────────────────────┘%
➜  curl  -H 'Accept: application/json' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/messages?fields=source,http_method,http_response_code,took_ms'
{
  "数据结构": [
    {
      "列类型": "字段",
      "类型": "未知",
      "字段": "来源",
      "名称": "字段: 来源"
    },
    {
      "列类型": "字段",
      "类型": "字符串",
      "字段": "HTTP方法",
      "名称": "字段: HTTP方法"
    },
    {
      "列类型": "字段",
      "类型": "未知",
      "字段": "HTTP响应码",
      "名称": "字段: HTTP响应码"
    },
    {
      "列类型": "字段",
      "类型": "数值",
      "字段": "耗时(毫秒)",
      "名称": "字段: 耗时(毫秒)"
    }
  ],
  "数据行": [
    [
      "example.org",
      "GET",
      200,
      50
    ],
    [
      "example.org",
      "GET",
      200,
      50
    ],
    [
      "example.org",
      "GET",
      200,
      55
    ],
    [
      "example.org",
      "GET",
      200,
      63
    ],
    [
      "example.org",
      "GET",
      200,
      63
    ],
    [
      "example.org",
      "GET",
      200,
      63
    ],
    [
      "example.org",
      "GET",
      200,
      37
    ],
    [
      "example.org",
      "GET",
      200,
      46
    ],
    [
      "example.org",
      "GET",
      200,
      59
    ],
    [
      "example.org",
      "GET",
      200,
      52
    ]
  ],
  "元数据": {
    "有效时间范围": {
      "起始": "2023-04-05T09:08:23.193Z",
      "结束": "2023-04-06T09:08:23.193Z",
      "类型": "绝对"
    }
  }
}
{
        "函数": "百分位数",
        "字段": "took_ms",
        "配置": 
        {"百分位": 90}
}
➜  curl  -H 'Accept: text/plain' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/aggregate?groups=http_method&metrics=avg:took_ms&metrics=count'
┌────────────────────────┬────────────────────────┬───────────────────────┐
│分组: http_method      │指标: avg(took_ms)      │指标: count()          │
├────────────────────────┼────────────────────────┼───────────────────────┤
│GET                     │84.59519448510214       │3326553                │
│DELETE                  │96.02973055642204       │330199                 │
│POST                    │170.11398232130765      │329323                 │
│PUT                     │132.19959919839678      │154690                 │
└────────────────────────┴────────────────────────┴───────────────────────┘
➜  curl  -H 'Accept: text/csv' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/aggregate?groups=http_method&metrics=avg:took_ms&metrics=count'
"分组: http_method","指标: avg(took_ms)","指标: count()"
"GET","84.58997204888469","3326522"
"DELETE","96.02450487553752","330220"
"POST","170.08947537817832","329342"
"PUT","132.2030966157029","154685"
➜ curl  -H 'Accept: application/json' -H 'X-Requested-By: cli'  -u username:password 'https://example.org/api/search/aggregate?groups=http_method&metrics=avg:took_ms&metrics=count'
{
  "模式": [
    {
      "列类型": "分组",
      "类型": "字符串",
      "字段": "http_method",
      "名称": "分组: http_method"
    },
    {
      "列类型": "指标",
      "类型": "数值",
      "函数": "avg",
      "字段": "took_ms",
      "名称": "指标: avg(took_ms)"
    },
    {
      "列类型": "指标",
      "类型": "数值",
      "函数": "count",
      "名称": "指标: count()"
    }
  ],
  "数据行": [
    [
      "GET",
      84.6043288978779,
      3326528
    ],
    [
      "DELETE",
      96.02355285311111,
      330236
    ],
    [
      "POST",
      170.09012904205252,
      329350
    ],
    [
      "PUT",
      132.20231038249952,
      154693
    ]
  ],
  "元数据": {
    "有效时间范围": {
      "起始": "2023-04-05T09:14:39.731Z",
      "结束": "2023-04-06T09:14:39.731Z",
      "类型": "绝对"
    }
  }
}
本节内容 :