« Google Cloud Storage 输入 HTTP JSON 输入 »

› › ›

HTTP 端点输入

HTTP 端点输入初始化一个监听 HTTP 服务器，该服务器收集包含 JSON 主体的传入 HTTP POST 请求。主体必须是对象或对象数组，否则可以提供一个通用表达式语言表达式，将 JSON 主体转换为这些类型。任何其他数据类型将导致 HTTP 400（错误请求）响应。对于数组，将为数组中的每个对象创建一个文档。

如果请求发送时带有 Content-Encoding: gzip 标头，则支持 gzip 编码的请求主体。

此输入例如可用于接收来自第三方应用程序或服务的传入 Webhook。

可以将多个端点分配给单个地址和端口，并且 HTTP 端点输入将根据 URL 模式配置解析请求。如果在单个地址上配置了多个端点，则它们必须都具有相同的 TLS 配置，要么全部禁用，要么全部启用并具有相同的配置。

以下是来自服务器的可能响应代码。

HTTP 响应代码	名称	原因
200	OK	成功返回。
400	错误请求	如果 JSON 主体解码失败或 `wait_for_completion_timeout` 查询验证失败，则返回此响应。
401	未授权	当基本身份验证、秘密标头或 HMAC 验证失败时返回。
405	不允许的方法	如果使用 POST 以外的方法，则返回此响应。
406	不可接受	如果 POST 请求不包含主体，则返回此响应。
415	不支持的媒体类型	如果 Content-Type 不是 application/json。或者如果存在 Content-Encoding 并且不是 gzip，则返回此响应。
500	内部服务器错误	如果在读取请求时发生 I/O 错误，则返回此响应。
503	服务不可用	如果请求主体的长度将使飞行中的总字节数超出配置的 `max_in_flight_bytes` 值，则返回此响应。
504	网关超时	如果在所需的超时时间内无法确认请求发布，则返回此响应。

当提供带有持续时间的 URL 查询参数 wait_for_completion_timeout 时，端点将强制执行端到端 ACK。例如，https://127.0.0.1:8080/?wait_for_completion_timeout=1m 将等待最多 1 分钟，以将事件发布到集群，然后返回用户定义的消息。如果发布未在超时持续时间内完成，则 HTTP 响应将具有 504 网关超时状态代码。持续时间的语法是一个数字，后跟单位，单位可以是 h、m 和 s。不接受其他 HTTP 查询。如果提供了另一个查询参数或持续时间语法不正确，则请求将失败并返回 HTTP 400“错误请求”状态。

配置示例

基本示例

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080

自定义响应示例

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  response_code: 200
  response_body: '{"message": "success"}'
  url: "/"
  prefix: "json"

将请求映射到文档根示例

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  prefix: "."

多个端点示例

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  url: "/open/"
  tags: [open]
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  url: "/admin/"
  basic_auth: true
  username: adminuser
  password: somepassword
  tags: [admin]

禁用 Content-Type 检查

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  content_type: ""
  prefix: "json"

基本身份验证和 SSL 示例

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  ssl.enabled: true
  ssl.certificate: "/home/user/server.pem"
  ssl.key: "/home/user/server.key"
  ssl.verification_mode: "none"
  ssl.certificate_authority: "/home/user/ca.pem"
  basic_auth: true
  username: someuser
  password: somepassword

身份验证或检查特定标头是否包含特定值

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  secret.header: someheadername
  secret.value: secretheadertoken

使用 CRC 验证特定提供商的 Webhook 端点

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  secret.header: someheadername
  secret.value: secretheadertoken
  crc.provider: webhookProvider
  crc.secret: secretToken

验证来自特定标头的 HMAC 签名

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  hmac.header: "X-Hub-Signature-256"
  hmac.key: "password123"
  hmac.type: "sha256"
  hmac.prefix: "sha256="

保留原始事件并在文档中包含标头

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  preserve_original_event: true
  include_headers: ["TestHeader"]

通用表达式语言示例

filebeat.inputs:
- type: http_endpoint
  enabled: true
  listen_address: 192.168.1.1
  listen_port: 8080
  program: |
    obj.records.map(r, {
     "requestId": obj.requestId,
     "timestamp": string(obj.timestamp),
     "event": r,
    })

此示例将允许处理 JSON 主体，该主体是一个包含多个事件的对象，每个事件都应作为单独的文档摄取，并具有公共时间戳和请求 ID

{
  "requestId": "ed4acda5-034f-9f42-bba1-f29aea6d7d8f",
  "timestamp": 1578090901599,
  "records": [
    {
      "data": "event record 1"
    },
    {
      "data": "event record 2"
    }
  ]
}

配置选项

编辑

http_endpoint 输入支持以下配置选项以及稍后描述的通用选项。

`basic_auth`

编辑

启用或禁用每个传入请求的 HTTP 基本身份验证。如果启用，则还需要配置 username 和 password。

`username`

编辑

如果启用了 basic_auth，则此为用于针对 HTTP 侦听器进行身份验证的用户名。还需要设置 password。

`password`

编辑

如果启用了 basic_auth，则此为用于针对 HTTP 侦听器进行身份验证的密码。还需要设置 username。

`secret.header`

编辑

要检查由 secret.value 指定的特定值的标头。某些 Webhook 提供了包含特殊标头和密钥以识别来源的可能性。

`secret.value`

编辑

存储在 secret.header 指定的标头名称中的密钥。某些 Webhook 提供了包含特殊标头和密钥以识别来源的可能性。

`hmac.header`

编辑

包含 HMAC 签名的标头的名称：X-Dropbox-Signature、X-Hub-Signature-256 等。HMAC 签名可以编码为十六进制或 base64。

`hmac.key`

编辑

用于计算 HMAC 签名的密钥。通常，Webhook 发送者会提供此值。

`hmac.type`

编辑

用于 HMAC 比较的哈希算法。目前，唯一有效的值是 sha256 或 sha1。

`hmac.prefix`

编辑

签名的前缀。某些 Webhook 会使用一个值作为 HMAC 签名的前缀，例如 sha256=。

`content_type`

编辑

默认情况下，输入希望传入的 POST 请求包含 application/json 的 Content-Type，以尝试强制传入的数据为有效的 JSON。在某些情况下，当请求的来源无法执行此操作时，可以使用另一个值覆盖它或将其设置为 null。

`max_in_flight_bytes`

编辑

在任何给定时间允许的请求主体长度的总和。如果为非零值，则输入会将此值与包含 wait_for_completion_timeout 请求查询的请求的飞行中请求主体长度之和进行比较，并将返回 503 HTTP 状态代码，以及使用 retry_after 选项配置的 Retry-After 标头。此选项的默认值为零，表示没有限制。

`retry_after`

编辑

如果请求超出 max_in_flight_bytes 限制，则对客户端的响应将包含一个 Retry-After 标头，指定客户端应等待多少秒才能再次重试。此选项的默认值为 10 秒。

`program`

编辑

当主体是一个对象时，输入的正常操作会将主体视为单个事件，当主体是一个数组时，则会将主体视为一组事件。如果主体应以不同的方式处理，例如，应将对象数组字段中的一组事件作为一组事件处理，则可以通过此配置字段提供一个通用表达式语言 (CEL)程序。CEL 程序中的对象名称为 obj。除了 CEL 标准库中的函数之外，不提供任何 CEL 扩展。支持 CEL 可选类型。

请注意，在评估期间，无法在双精度浮点值中精确表示的数字将转换为字符串以避免数据损坏。

`response_code`

编辑

成功后返回的 HTTP 响应代码。应在 2XX 范围内。

`response_body`

编辑

成功后返回的响应主体。

`listen_address`

编辑

如果存在多个接口，则可以设置 listen_address 来控制侦听器绑定到的 IP 地址。默认为 127.0.0.1。

`listen_port`

编辑

侦听器绑定到的端口。默认为 8000。

`url`

编辑

此选项指定接受请求的 URL 路径。默认为 /

`prefix`

编辑

此选项指定传入的请求将映射到的前缀。如果 prefix 为 "."，则请求将映射到结果文档的根。

`include_headers`

编辑

此选项指定应从传入请求复制并包含在文档中的 HTTP 标头列表。所有配置的标头将始终规范化以匹配传入请求的标头。例如，["content-type"] 在 Filebeat 运行时将变为 ["Content-Type"]。

`preserve_original_event`

编辑

此选项将传入请求的原始未修改主体作为字符串复制到 event.original 字段中，然后再将事件发送到 Elasticsearch。

`crc.provider`

编辑

此选项定义使用 CRC（质询-响应检查）来验证端点的 Webhook 提供商。HTTP 端点输入负责通过生成和验证唯一令牌来确保传入 Webhook 请求的真实性。通过指定 crc.provider，您可以确保系统正确处理所选提供商所需的特定 CRC 验证过程。

`crc.secret`

编辑

Webhook 所有者为 CRC 验证提供的密钥令牌。设置 crc.provider 时，此项为必需项。

`method`

编辑

端点处理的 HTTP 方法。如果指定，method 必须是 POST、PUT 或 PATCH。默认方法为 POST。如果指定 PUT 或 PATCH，则接受使用这些方法类型的请求，但它们被视为 POST 请求，并且应具有包含请求数据的请求主体。

`tracer.enabled`

编辑

可以记录 HTTP 请求到本地文件系统以进行调试配置。通过将 tracer.enabled 设置为 true 并设置 tracer.filename 值来启用此选项。还可以使用其他选项来调整日志轮换行为。要删除现有日志，请在不取消设置文件名选项的情况下将 tracer.enabled 设置为 false。

启用此选项会损害安全性，应仅用于调试。

`tracer.filename`

编辑

为了区分不同输入实例生成的跟踪文件，可以在文件名中添加占位符 *，它将被替换为输入实例 ID。例如，http-request-trace-*.ndjson。

`tracer.maxsize`

编辑

此值设置日志文件在轮换之前的最大大小（以兆字节为单位）。默认情况下，日志在轮换之前允许达到 1MB。

`tracer.maxage`

编辑

这指定保留轮换日志文件的天数。如果未设置，则日志文件将无限期保留。

`tracer.maxbackups`

编辑

要保留的旧日志数量。如果未设置，则会保留所有旧日志，但受 tracer.maxage 设置的约束。

`tracer.localtime`

编辑

是否使用主机本地时间而不是 UTC 来为轮换的日志文件名添加时间戳。

`tracer.compress`

编辑

这确定是否应使用 gzip 压缩轮换的日志。

指标

编辑

此输入在 HTTP 监控端点下公开指标。这些指标在 /inputs 路径下公开。它们可用于观察输入的活动。

指标	描述
`bind_address`	输入的绑定地址。
`route`	输入的 HTTP 请求路由。
`is_tls_connection`	输入是否正在侦听 TLS 连接。
`api_errors_total`	API 错误总数。
`batches_received_total`	接收到的事件数组的数量。
`batches_published_total`	已发布的事件数组的数量。
`batches_acked_total`	已确认的事件数组的数量。
`events_published_total`	已发布的事件数量。
`size`	请求内容长度的直方图。
`batch_size`	接收到的事件数组长度的直方图。
`batch_processing_time`	以纳秒为单位的成功批处理所用时间的直方图（非空批次的接收时间到 ACK 时间）。
`batch_ack_time`	以纳秒为单位的成功批次 ACK 所用时间的直方图（非空批次的处理器启动时间到 ACK 时间）。

通用选项

编辑

所有输入都支持以下配置选项。

`enabled`

编辑

使用 enabled 选项启用和禁用输入。默认情况下，enabled 设置为 true。

`tags`

编辑

Filebeat 在每个已发布事件的 tags 字段中包含的标签列表。使用标签可以轻松地在 Kibana 中选择特定事件或在 Logstash 中应用条件筛选。这些标签将附加到通用配置中指定的标签列表。

示例

filebeat.inputs:
- type: http_endpoint
  . . .
  tags: ["json"]

`fields`

编辑

您可以指定的可选字段，用于向输出添加其他信息。例如，您可以添加可用于筛选日志数据的字段。字段可以是标量值、数组、字典或它们的任何嵌套组合。默认情况下，您在此处指定的字段将分组在输出文档中的 fields 子字典下。要将自定义字段存储为顶级字段，请将 fields_under_root 选项设置为 true。如果在通用配置中声明了重复字段，则其值将被此处声明的值覆盖。

filebeat.inputs:
- type: http_endpoint
  . . .
  fields:
    app_id: query_engine_12

`fields_under_root`

编辑

如果此选项设置为 true，则自定义字段将存储为输出文档中的顶级字段，而不是分组在 fields 子字典下。如果自定义字段名称与 Filebeat 添加的其他字段名称冲突，则自定义字段将覆盖其他字段。

`processors`

编辑

要应用于输入数据的处理器列表。

有关在配置中指定处理器的信息，请参阅 处理器。

`pipeline`

编辑

为此输入生成的事件设置的摄取管道 ID。

也可以在 Elasticsearch 输出中配置管道 ID，但此选项通常会产生更简单的配置文件。如果管道在输入和输出中都进行了配置，则使用输入中的选项。

`keep_null`

编辑

如果此选项设置为 true，则具有 null 值的字段将在输出文档中发布。默认情况下，keep_null 设置为 false。

`index`

编辑

如果存在，此格式化字符串将覆盖来自此输入的事件的索引（对于 elasticsearch 输出），或设置事件元数据的 raw_index 字段（对于其他输出）。此字符串只能引用代理名称和版本以及事件时间戳；要访问动态字段，请使用 output.elasticsearch.index 或处理器。

示例值："%{[agent.name]}-myindex-%{+yyyy.MM.dd}" 可能会展开为 "filebeat-myindex-2019.11.01"。

`publisher_pipeline.disable_host`

编辑

默认情况下，所有事件都包含 host.name。可以将此选项设置为 true 以禁用将此字段添加到所有事件。默认值为 false。

« Google Cloud Storage 输入 HTTP JSON 输入 »